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");

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))
);

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...
    }
}

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);

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
}