Loading...
Searching...
No Matches
scratchpads.h File Reference

Unified header for the scratchpad memory management system. More...

`#include "gridfire/engine/scratchpads/scratchpad_abstract.h"`
`#include "gridfire/engine/scratchpads/engine_graph_scratchpad.h"`
`#include "gridfire/engine/scratchpads/engine_adaptive_scratchpad.h"`
`#include "gridfire/engine/scratchpads/engine_multiscale_scratchpad.h"`
`#include "gridfire/engine/scratchpads/engine_defined_scratchpad.h"`
`#include "gridfire/engine/scratchpads/types.h"`
`#include "gridfire/engine/scratchpads/blob.h"`
`#include "gridfire/engine/scratchpads/utils.h"`
`#include "gridfire/engine/scratchpads/formatters.h"`
Include dependency graph for scratchpads.h:
This graph shows which files directly or indirectly include this file:

## Namespaces

namespace | gridfire::engine::scratch
| Scratchpad memory management for computational engines.

## Detailed Description

Unified header for the scratchpad memory management system.

This is the main include file for the scratchpad subsystem. It provides a single include point for all scratchpad-related functionality, including the abstract base class, concrete implementations, type definitions, the StateBlob container, utility functions, and formatters for debugging.

What are Scratchpads?
  Scratchpads are temporary working memory containers used by computational engines during ODE integration and reaction network calculations. They serve several critical purposes:

- Performance: Pre-allocate memory once and reuse across iterations, avoiding repeated heap allocations during time-critical computations.
- Caching: Store intermediate results (Jacobians, derivatives, etc.) that can be reused across solver steps.
- Thread Safety: Provide thread-local storage for parallel execution, where each thread operates on its own independent scratchpad instance.
- State Management: Encapsulate engine-specific working state separate from the engine's persistent configuration.

Architecture Overview
  The scratchpad system consists of:

- AbstractScratchPad: Base interface defining `is_initialized()` and `clone()`
- Concrete Scratchpads: Engine-specific implementations
  - `GraphEngineScratchPad`: CppAD ADFun and Jacobian caches
  - `AdaptiveEngineViewScratchPad`: Active species/reactions for adaptive networks
  - `DefinedEngineViewScratchPad`: Species/reactions for static networks
  - `MultiscalePartitioningEngineViewScratchPad`: QSE groups and SUNDIALS context
- StateBlob: Container managing multiple scratchpads with type-safe access
- Utilities: Helper functions for exception-based retrieval
- Formatters: std::format specializations for debugging output

Why Use Scratchpads?
  During numerical integration of stiff reaction networks, engines must:
  1. Evaluate right-hand side functions (species derivatives)
  2. Compute sparse Jacobian matrices
  3. Solve linear systems within Newton iterations

These operations require substantial temporary memory. Without scratchpads, each evaluation would allocate and deallocate working buffers, causing:

- Memory fragmentation
- Cache thrashing
- Unnecessary allocation overhead

Scratchpads solve this by providing persistent, reusable working memory that lives for the duration of an integration step (or longer).

Thread Safety Model
  The scratchpad system is designed for thread-local usage:

- Scratchpads are not thread-safe by design
- Each thread must have its own scratchpad instances
- Use `StateBlob::clone_structure()` to create independent copies for workers
- The original scratchpad/blob remains usable by the main thread

Examples
  #include "gridfire/engine/scratchpads/scratchpads.h"
  using namespace gridfire::engine::scratch;
  // === Basic Usage ===
  // Create a StateBlob and enroll scratchpads
  StateBlob blob;
  blob.enroll<GraphEngineScratchPad>();
  blob.enroll<AdaptiveEngineViewScratchPad>();
  // Initialize scratchpads
  auto* graph_scratch = get_state<GraphEngineScratchPad>(blob);
  graph_scratch->initialize(engine);
  // Use initialized scratchpad
  auto* scratch = get_state<GraphEngineScratchPad, true>(blob); // Throws if not initialized
  auto& adfun = scratch->rhsADFun.value();
  // === Parallel Execution ===
  // Clone for worker threads
  std::vector<std::unique_ptr<StateBlob>> worker_blobs;
  for (int i = 0; i < num_threads; ++i) {
  worker_blobs.push_back(blob.clone_structure());
  }
  // Each worker uses its own blob
  #pragma omp parallel for
  for (int i = 0; i < work_items; ++i) {
  int tid = omp_get_thread_num();
  StateBlob& my_blob = *worker_blobs[tid];
  auto* my_scratch = get_state<GraphEngineScratchPad>(my_blob);
  // Thread-safe: each thread has its own scratchpad
  compute_with_scratchpad(*my_scratch);
  }
  // === Debugging ===
  // Use formatters for logging
  std::cout << std::format("Blob state: {}\n", blob);
  // Output: StateBlob(Enrolled: GraphEngineScratchPad(...), AdaptiveEngineViewScratchPad(...))
  // Check status
  auto status = blob.get_status<GraphEngineScratchPad>();
  if (status == StateBlob::ScratchPadStatus::ENROLLED_NOT_INITIALIZED) {
  // Need to initialize before use
  }
  gridfire::engine::scratch::StateBlob
  Container for managing a collection of typed scratchpad instances.
  Definition blob.h:114
  gridfire::engine::scratch::StateBlob::get_status
  ScratchPadStatus get_status() const
  Get the status of a specific scratchpad type.
  Definition blob.h:445
  gridfire::engine::scratch::StateBlob::ScratchPadStatus::ENROLLED_NOT_INITIALIZED
  @ ENROLLED_NOT_INITIALIZED
  Scratchpad enrolled but not yet initialized.
  Definition blob.h:164
  gridfire::engine::scratch::StateBlob::enroll
  void enroll()
  Enroll a new scratchpad type into the blob.
  Definition blob.h:196
  gridfire::engine::scratch::StateBlob::clone_structure
  std::unique_ptr< StateBlob > clone_structure() const
  Create a deep copy of this blob with all enrolled scratchpads.
  Definition blob.h:361
  gridfire::engine::scratch
  Scratchpad memory management for computational engines.
  Definition blob.h:69
  gridfire::engine::scratch::get_state
  CTX * get_state(StateBlob &ctx)
  Retrieve a scratchpad from a StateBlob, throwing on error.
  Definition utils.h:84
  gridfire::engine
  Definition dynamic_engine_diagnostics.h:39
  scratchpads.h
  Unified header for the scratchpad memory management system.
  gridfire::engine::scratch::AdaptiveEngineViewScratchPad
  Scratchpad for storing working memory used by AdaptiveEngineView computations.
  Definition engine_adaptive_scratchpad.h:66
  gridfire::engine::scratch::AdaptiveEngineViewScratchPad::initialize
  void initialize(const AdaptiveEngineView &engine)
  Initialize the scratchpad from an AdaptiveEngineView.
  Definition engine_adaptive_scratchpad.h:102
  gridfire::engine::scratch::GraphEngineScratchPad
  Scratchpad for storing CppAD automatic differentiation state for GraphEngine.
  Definition engine_graph_scratchpad.h:83

Included Headers
  This header includes:
  - scratchpad_abstract.h - AbstractScratchPad base class
  - engine_graph_scratchpad.h - GraphEngineScratchPad
  - engine_adaptive_scratchpad.h - AdaptiveEngineViewScratchPad
  - engine_multiscale_scratchpad.h - MultiscalePartitioningEngineViewScratchPad
  - engine_defined_scratchpad.h - DefinedEngineViewScratchPad
  - types.h - ScratchPadType enumeration
  - blob.h - StateBlob container
  - utils.h - get_state() helper functions
  - formatters.h - std::format specializations

See also
  AbstractScratchPad
  StateBlob
  ScratchPadType