Loading...
Searching...
No Matches
gridfire::engine::scratch Namespace Reference

Scratchpad memory management for computational engines. More...

## Classes

struct | AbstractScratchPad
| Abstract base struct for engine scratchpad memory. More...
struct | AdaptiveEngineViewScratchPad
| Scratchpad for storing working memory used by AdaptiveEngineView computations. More...
struct | DefinedEngineViewScratchPad
| Scratchpad for storing working memory used by defined reaction network engines. More...
struct | GraphEngineScratchPad
| Scratchpad for storing CppAD automatic differentiation state for GraphEngine. More...
struct | MultiscalePartitioningEngineViewScratchPad
| Scratchpad for multiscale partitioning engine computations with QSE groups. More...
class | StateBlob
| Container for managing a collection of typed scratchpad instances. More...

## Concepts

concept | IsScratchPad
| Concept that constrains types to valid scratchpad implementations.

## Enumerations

enum class | ScratchPadType : uint8_t { GRAPH_ENGINE_SCRATCHPAD , MULTISCALE_PARTITIONING_ENGINE_VIEW_SCRATCHPAD , ADAPTIVE_ENGINE_VIEW_SCRATCHPAD , DEFINED_ENGINE_VIEW_SCRATCHPAD , PRIMING_ENGINE_VIEW_SCRATCHPAD , _COUNT }
| Enumeration of all registered scratchpad types. More...

## Functions

consteval size_t | get_max_scratchpad_types ()
| Get the maximum number of scratchpad types at compile time.
constexpr std::string_view | get_scratchpad_type_name (const ScratchPadType scratchpad_type)
| Convert a ScratchPadType to a human-readable name.
template<IsScratchPad CTX>
CTX * | get_state (StateBlob &ctx)
| Retrieve a scratchpad from a StateBlob, throwing on error.
template<IsScratchPad CTX>
const CTX * | get_state (const StateBlob &ctx)
| Retrieve a const scratchpad from a const StateBlob, throwing on error.
template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>
CTX * | get_state (StateBlob &ctx)
| Retrieve a scratchpad with optional initialization check, throwing on error.
template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>
const CTX * | get_state (const StateBlob &ctx)
| Retrieve a const scratchpad with optional initialization check, throwing on error.

## Detailed Description

Scratchpad memory management for computational engines.

The scratch namespace contains all components related to temporary working memory management for GridFire's computational engines. This includes the abstract scratchpad interface, concrete implementations for each engine type, the StateBlob container for managing multiple scratchpads, and utilities for convenient access.

Key Components
  - AbstractScratchPad: Interface for all scratchpad types
  - GraphEngineScratchPad: Working memory for CppAD-based graph engines
  - AdaptiveEngineViewScratchPad: Storage for adaptive network computations
  - DefinedEngineViewScratchPad: Storage for static network computations
  - MultiscalePartitioningEngineViewScratchPad: QSE solver state management
  - StateBlob: Type-safe container for multiple scratchpads
  - ScratchPadType: Enumeration of registered scratchpad types
  - IsScratchPad: Concept constraining valid scratchpad types
  - get_state(): Utility functions for exception-based retrieval

Design Philosophy
  The scratchpad system follows these design principles:

1. Separation of Concerns: Working memory is separate from engine configuration
2. Type Safety: Compile-time verification of scratchpad types via concepts
3. Performance: O(1) access via enum-indexed arrays
4. Thread Locality: Each thread owns its scratchpad instances
5. Clonability: Deep copying enables parallel execution patterns

## Enumeration Type Documentation

## ScratchPadType

enum class gridfire::engine::scratch::ScratchPadType : uint8_t

strong

Enumeration of all registered scratchpad types.

Each scratchpad implementation must have a unique type identifier in this enumeration. The concrete scratchpad class should define a static `ID` member initialized to its corresponding ScratchPadType value.

Note
  The `_COUNT` enumerator is a sentinel value used to determine the total number of scratchpad types. It must always be the last entry. Do not use `_COUNT` as an actual scratchpad type.

Enumerator
GRAPH_ENGINE_SCRATCHPAD | GraphEngineScratchPad for CppAD-based engines.
MULTISCALE_PARTITIONING_ENGINE_VIEW_SCRATCHPAD | MultiscalePartitioningEngineViewScratchPad for QSE partitioning.
ADAPTIVE_ENGINE_VIEW_SCRATCHPAD | AdaptiveEngineViewScratchPad for adaptive networks.
DEFINED_ENGINE_VIEW_SCRATCHPAD | DefinedEngineViewScratchPad for static networks.
PRIMING_ENGINE_VIEW_SCRATCHPAD | PrimingEngineViewScratchPad for engine priming.
_COUNT | Sentinel value representing the total number of scratchpad types. Do not use as a type.

## Function Documentation

## get_max_scratchpad_types()

size_t gridfire::engine::scratch::get_max_scratchpad_types | ( |  | ) |

consteval

Get the maximum number of scratchpad types at compile time.

Returns the total count of registered scratchpad types, derived from the ScratchPadType::_COUNT sentinel value. This is useful for sizing fixed-size arrays that need a slot for each scratchpad type.

Returns
  The number of valid scratchpad types (excluding _COUNT).

Examples
  // Use at compile time for array sizing
  constexpr size_t NUM_TYPES = get_max_scratchpad_types();
  std::array<std::unique_ptr<AbstractScratchPad>, NUM_TYPES> scratchpads;
  // Use in static_assert
  static_assert(get_max_scratchpad_types() > 0, "No scratchpad types defined");
  gridfire::engine::scratch::get_max_scratchpad_types
  consteval size_t get_max_scratchpad_types()
  Get the maximum number of scratchpad types at compile time.
  Definition types.h:93

## get_scratchpad_type_name()

std::string_view gridfire::engine::scratch::get_scratchpad_type_name | ( | const ScratchPadType | scratchpad_type | ) |

constexpr

Convert a ScratchPadType to a human-readable name.

Returns a string view containing the class name associated with the given scratchpad type. Useful for logging, debugging, and error messages.

Parameters

  scratchpad_type | The scratchpad type to convert.

Returns
  A string view containing the scratchpad class name, or "UnknownScratchPadType" for unrecognized values.

Examples
  ScratchPadType type = ScratchPadType::GRAPH_ENGINE_SCRATCHPAD;
  std::cout << "Using: " << get_scratchpad_type_name(type) << "\n";
  // Output: "Using: GraphEngineScratchPad"
  // Use in error messages
  throw std::runtime_error(
  std::format("Failed to initialize {}", get_scratchpad_type_name(type))
  );
  gridfire::engine::scratch::ScratchPadType
  ScratchPadType
  Enumeration of all registered scratchpad types.
  Definition types.h:64
  gridfire::engine::scratch::ScratchPadType::GRAPH_ENGINE_SCRATCHPAD
  @ GRAPH_ENGINE_SCRATCHPAD
  GraphEngineScratchPad for CppAD-based engines.
  Definition types.h:65
  gridfire::engine::scratch::get_scratchpad_type_name
  constexpr std::string_view get_scratchpad_type_name(const ScratchPadType scratchpad_type)
  Convert a ScratchPadType to a human-readable name.
  Definition types.h:121

## get_state() [1/4]

template<IsScratchPad CTX>

const CTX * gridfire::engine::scratch::get_state | ( | const StateBlob & | ctx | ) |

Retrieve a const scratchpad from a const StateBlob, throwing on error.

Const-correct overload of get_state() for read-only access to scratchpads. Use this when you have a const reference to the StateBlob and only need to read from the scratchpad.

Template Parameters

  CTX | The scratchpad type to retrieve (must satisfy IsScratchPad).

Parameters

  ctx | The const StateBlob to retrieve the scratchpad from.

Returns
  Const pointer to the requested scratchpad.

Exceptions

  exceptions::ScratchPadError | if the scratchpad is not found, cannot be cast to the requested type, or any other error occurs.

Examples
  void inspect(const StateBlob& blob) {
  const GraphEngineScratchPad* scratch = get_state<GraphEngineScratchPad>(blob);
  if (scratch->is_initialized()) {
  // Read from scratch...
  }
  }
  gridfire::engine::scratch::StateBlob
  Container for managing a collection of typed scratchpad instances.
  Definition blob.h:114
  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::scratch::GraphEngineScratchPad
  Scratchpad for storing CppAD automatic differentiation state for GraphEngine.
  Definition engine_graph_scratchpad.h:83

## get_state() [2/4]

template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>

const CTX * gridfire::engine::scratch::get_state | ( | const StateBlob & | ctx | ) |

Retrieve a const scratchpad with optional initialization check, throwing on error.

Const-correct overload of the initialization-checking get_state(). Combines read-only access with optional initialization verification.

Template Parameters

  CTX | The scratchpad type to retrieve (must satisfy IsScratchPad).
  MUST_BE_INITIALIZED | If true, throws when the scratchpad is not initialized.

Parameters

  ctx | The const StateBlob to retrieve the scratchpad from.

Returns
  Const pointer to the requested scratchpad (guaranteed initialized if MUST_BE_INITIALIZED is true).

Exceptions

  exceptions::ScratchPadError | if the scratchpad is not found, cannot be cast, is not initialized (when required), or any other error.

Examples
  void validate(const StateBlob& blob) {
  // Get const access, ensuring initialization
  const auto* scratch = get_state<GraphEngineScratchPad, true>(blob);
  // Safe to read - guaranteed initialized
  const auto& adfun = scratch->rhsADFun.value();
  }

## get_state() [3/4]

template<IsScratchPad CTX>

CTX * gridfire::engine::scratch::get_state | ( | StateBlob & | ctx | ) |

Retrieve a scratchpad from a StateBlob, throwing on error.

Convenience wrapper around StateBlob::get() that converts error codes into exceptions. Use this when you expect the scratchpad to exist and want exception-based error handling.

Template Parameters

  CTX | The scratchpad type to retrieve (must satisfy IsScratchPad).

Parameters

  ctx | The StateBlob to retrieve the scratchpad from.

Returns
  Pointer to the requested scratchpad.

Exceptions

  exceptions::ScratchPadError | if the scratchpad is not found, cannot be cast to the requested type, or any other error occurs.

Examples
  StateBlob blob;
  blob.enroll<GraphEngineScratchPad>();
  // Retrieve the scratchpad - throws if not enrolled
  GraphEngineScratchPad* scratch = get_state<GraphEngineScratchPad>(blob);
  scratch->initialize(engine);
  gridfire::engine::scratch::StateBlob::enroll
  void enroll()
  Enroll a new scratchpad type into the blob.
  Definition blob.h:196
  gridfire::engine
  Definition dynamic_engine_diagnostics.h:39

## get_state() [4/4]

template<IsScratchPad CTX, bool MUST_BE_INITIALIZED>

CTX * gridfire::engine::scratch::get_state | ( | StateBlob & | ctx | ) |

Retrieve a scratchpad with optional initialization check, throwing on error.

Extended version of get_state() that can optionally verify the scratchpad is initialized before returning it. When MUST_BE_INITIALIZED is true, an exception is thrown if the scratchpad exists but hasn't been initialized.

Template Parameters

  CTX | The scratchpad type to retrieve (must satisfy IsScratchPad).
  MUST_BE_INITIALIZED | If true, throws when the scratchpad is not initialized.

Parameters

  ctx | The StateBlob to retrieve the scratchpad from.

Returns
  Pointer to the requested scratchpad (guaranteed initialized if MUST_BE_INITIALIZED is true).

Exceptions

  exceptions::ScratchPadError | if the scratchpad is not found, cannot be cast, is not initialized (when required), or any other error.

Examples
  // Ensure scratchpad is initialized before use
  try {
  auto* scratch = get_state<GraphEngineScratchPad, true>(blob);
  // Guaranteed to be initialized here
  use_scratchpad(*scratch);
  } catch (const exceptions::ScratchPadError& e) {
  // Handle missing or uninitialized scratchpad
  }
  gridfire::exceptions::ScratchPadError
  Definition error_scratchpad.h:9