Oakfield API Documentation 1.0.0
Numerical core APIs
Loading...
Searching...
No Matches
sim_runtime_state.h File Reference

Dynamic runtime state for simulations. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "field.h"
#include "sim_field_stats_runtime.h"
#include "sim_field_topology_runtime.h"
#include "sim_flux_lens.h"
Include dependency graph for sim_runtime_state.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  SimRuntimeComplexSample
 Complex sample stored in runtime visualization and drift caches. More...
 
struct  SimRuntimePhasePortraitMetrics
 Bounds and aggregate radii for phase-portrait visualization samples. More...
 
struct  SimRuntimeWaveformSampleStats
 Min/max summary for downsampled waveform visualization data. More...
 
struct  SimStepMetrics
 Aggregated metrics captured once per completed integration step. More...
 
struct  SimRuntimeLoopError
 Structured record of the most recent loop/runtime failure. More...
 
struct  SimRuntimeLoopProgress
 Snapshot of caller-owned loop progress and declared budgets. More...
 
struct  SimRuntimeState
 Runtime parameters and integration state. More...
 

Macros

#define SIM_RUNTIME_DEFAULT_DT   0.0166667f
 
#define SIM_RUNTIME_VIS_DOWNSAMPLE_TARGET_DEFAULT   4096U
 
#define SIM_RUNTIME_VIS_DOWNSAMPLE_MAX_DEFAULT   16384U
 
#define SIM_RUNTIME_VIS_DOWNSAMPLE_TARGET_MIN   64U
 
#define SIM_RUNTIME_VIS_DOWNSAMPLE_TARGET_MAX   65536U
 
#define SIM_STEP_METRIC_HISTORY   128U
 

Typedefs

typedef struct SimRuntimeComplexSample SimRuntimeComplexSample
 Complex sample stored in runtime visualization and drift caches.
 
typedef struct SimRuntimePhasePortraitMetrics SimRuntimePhasePortraitMetrics
 Bounds and aggregate radii for phase-portrait visualization samples.
 
typedef struct SimRuntimeWaveformSampleStats SimRuntimeWaveformSampleStats
 Min/max summary for downsampled waveform visualization data.
 
typedef enum SimTimeModel SimTimeModel
 Time evolution model for the simulation.
 
typedef struct SimStepMetrics SimStepMetrics
 Aggregated metrics captured once per completed integration step.
 
typedef enum SimRuntimeLoopStopReason SimRuntimeLoopStopReason
 Last observed terminal/non-running reason for a managed loop.
 
typedef enum SimRuntimeLoopErrorSource SimRuntimeLoopErrorSource
 Origin of the most recent loop/runtime failure.
 
typedef struct SimRuntimeLoopError SimRuntimeLoopError
 Structured record of the most recent loop/runtime failure.
 
typedef enum SimRuntimeCallerStepMode SimRuntimeCallerStepMode
 Most recent caller-owned stepping primitive observed on the context.
 
typedef enum SimRuntimeLoopProgressKind SimRuntimeLoopProgressKind
 Kind of caller-owned bounded loop currently being observed.
 
typedef struct SimRuntimeLoopProgress SimRuntimeLoopProgress
 Snapshot of caller-owned loop progress and declared budgets.
 
typedef struct SimRuntimeState SimRuntimeState
 Runtime parameters and integration state.
 

Enumerations

enum  SimTimeModel { SIM_TIME_MODEL_CONTINUOUS , SIM_TIME_MODEL_MAP = 1 }
 Time evolution model for the simulation. More...
 
enum  SimRuntimeLoopStopReason {
  SIM_RUNTIME_LOOP_STOP_REASON_NONE = 0 , SIM_RUNTIME_LOOP_STOP_REASON_PAUSED , SIM_RUNTIME_LOOP_STOP_REASON_CANCELLED , SIM_RUNTIME_LOOP_STOP_REASON_STEPS_EXHAUSTED ,
  SIM_RUNTIME_LOOP_STOP_REASON_MAX_SIM_TIME_REACHED , SIM_RUNTIME_LOOP_STOP_REASON_MAX_WALL_MS_REACHED , SIM_RUNTIME_LOOP_STOP_REASON_RUNTIME_ERROR
}
 Last observed terminal/non-running reason for a managed loop. More...
 
enum  SimRuntimeLoopErrorSource {
  SIM_RUNTIME_LOOP_ERROR_SOURCE_NONE = 0 , SIM_RUNTIME_LOOP_ERROR_SOURCE_SCHEDULER_STEP , SIM_RUNTIME_LOOP_ERROR_SOURCE_EXECUTION_FRAME , SIM_RUNTIME_LOOP_ERROR_SOURCE_OPERATOR_EXECUTION ,
  SIM_RUNTIME_LOOP_ERROR_SOURCE_INTEGRATOR_BRIDGE , SIM_RUNTIME_LOOP_ERROR_SOURCE_INTEGRATOR_SEQUENCE , SIM_RUNTIME_LOOP_ERROR_SOURCE_LEGACY_STEP
}
 Origin of the most recent loop/runtime failure. More...
 
enum  SimRuntimeCallerStepMode { SIM_RUNTIME_CALLER_STEP_MODE_NONE = 0 , SIM_RUNTIME_CALLER_STEP_MODE_MANUAL_STEP , SIM_RUNTIME_CALLER_STEP_MODE_INTEGRATOR_STEP }
 Most recent caller-owned stepping primitive observed on the context. More...
 
enum  SimRuntimeLoopProgressKind {
  SIM_RUNTIME_LOOP_PROGRESS_NONE = 0 , SIM_RUNTIME_LOOP_PROGRESS_RUN_STEPS , SIM_RUNTIME_LOOP_PROGRESS_RUN_UNTIL , SIM_RUNTIME_LOOP_PROGRESS_RUN_INTEGRATOR_STEPS ,
  SIM_RUNTIME_LOOP_PROGRESS_RUN_UNTIL_INTEGRATOR , SIM_RUNTIME_LOOP_PROGRESS_RUN_PARAMETER_SWEEP , SIM_RUNTIME_LOOP_PROGRESS_RUN_PARAMETER_GRID , SIM_RUNTIME_LOOP_PROGRESS_RUN_PARAMETER_CONTINUATION
}
 Kind of caller-owned bounded loop currently being observed. More...
 

Functions

SimResult sim_runtime_state_init (SimRuntimeState *state)
 Initialize runtime state with defaults.
 
void sim_runtime_state_release_continuity_buffers (SimRuntimeState *state)
 Release continuity buffer allocations.
 
SimResult sim_runtime_state_ensure_continuity_capacity (SimRuntimeState *state, size_t required)
 Ensure continuity counters can index at least required fields.
 
void sim_runtime_state_destroy (SimRuntimeState *state)
 Destroy runtime state and release resources.
 
void sim_runtime_state_record_step_metrics (SimRuntimeState *state, const SimStepMetrics *metrics)
 Append a step metrics sample to the runtime ring buffer.
 
bool sim_runtime_state_latest_step_metrics (const SimRuntimeState *state, SimStepMetrics *out_metrics)
 Copy the most recent step metrics sample.
 
size_t sim_runtime_state_copy_step_metrics (const SimRuntimeState *state, SimStepMetrics *dest, size_t capacity)
 Copy up to capacity samples into dest ordered from oldest to newest.
 
void sim_runtime_state_set_pending_cancel (SimRuntimeState *state, bool pending)
 Mark whether a scheduler-owned cancel is in progress.
 
bool sim_runtime_state_pending_cancel (const SimRuntimeState *state)
 Read the current pending-cancel flag.
 
void sim_runtime_state_set_last_stop_reason (SimRuntimeState *state, SimRuntimeLoopStopReason reason)
 Record the most recent loop stop reason.
 
SimRuntimeLoopStopReason sim_runtime_state_last_stop_reason (const SimRuntimeState *state)
 Fetch the most recent loop stop reason.
 
void sim_runtime_state_clear_loop_error (SimRuntimeState *state)
 Clear the most recent loop/runtime error record.
 
void sim_runtime_state_record_loop_error (SimRuntimeState *state, SimResult code, SimRuntimeLoopErrorSource source, size_t step_index)
 Record the most recent loop/runtime error.
 
bool sim_runtime_state_last_loop_error (const SimRuntimeState *state, SimRuntimeLoopError *out_error)
 Fetch the most recent loop/runtime error.
 
void sim_runtime_state_note_caller_step (SimRuntimeState *state, SimRuntimeCallerStepMode mode)
 Record a successful caller-owned step primitive.
 
void sim_runtime_state_clear_caller_step_history (SimRuntimeState *state)
 Clear descriptive caller-owned step history.
 
SimRuntimeCallerStepMode sim_runtime_state_last_caller_step_mode (const SimRuntimeState *state)
 Fetch the last caller-owned step primitive observed.
 
size_t sim_runtime_state_caller_step_streak (const SimRuntimeState *state)
 Fetch the consecutive caller-owned step streak.
 
void sim_runtime_state_acquire_external_driver (SimRuntimeState *state)
 Acquire a caller-owned external-driver claim.
 
void sim_runtime_state_release_external_driver (SimRuntimeState *state)
 Release one caller-owned external-driver claim.
 
void sim_runtime_state_clear_external_driver (SimRuntimeState *state)
 Clear all caller-owned external-driver claims.
 
size_t sim_runtime_state_external_driver_depth (const SimRuntimeState *state)
 Report the current nested external-driver claim depth.
 
void sim_runtime_state_set_loop_progress (SimRuntimeState *state, const SimRuntimeLoopProgress *progress)
 Replace the current caller-owned loop progress snapshot.
 
void sim_runtime_state_clear_loop_progress (SimRuntimeState *state)
 Clear the current caller-owned loop progress snapshot.
 
bool sim_runtime_state_loop_progress (const SimRuntimeState *state, SimRuntimeLoopProgress *out_progress)
 Fetch the current caller-owned loop progress snapshot.
 
bool sim_runtime_state_last_loop_progress (const SimRuntimeState *state, SimRuntimeLoopProgress *out_progress)
 Fetch the most recent completed caller-owned loop progress snapshot.
 
void sim_runtime_state_clear_last_loop_progress (SimRuntimeState *state)
 Clear any retained completed caller-owned loop progress snapshot.
 
const char * sim_runtime_loop_stop_reason_name (SimRuntimeLoopStopReason reason)
 Convert a loop stop reason to a stable machine-readable name.
 
const char * sim_runtime_loop_error_source_name (SimRuntimeLoopErrorSource source)
 Convert a loop error source to a stable machine-readable name.
 
const char * sim_runtime_caller_step_mode_name (SimRuntimeCallerStepMode mode)
 Convert a caller-owned step mode to a stable machine-readable name.
 
const char * sim_runtime_loop_progress_kind_name (SimRuntimeLoopProgressKind kind)
 Convert a loop-progress kind to a stable machine-readable name.
 

Detailed Description

Dynamic runtime state for simulations.

Macro Definition Documentation

◆ SIM_STEP_METRIC_HISTORY

#define SIM_STEP_METRIC_HISTORY   128U

Number of per-step samples preserved in the runtime ring buffer.

Typedef Documentation

◆ SimRuntimeCallerStepMode

Most recent caller-owned stepping primitive observed on the context.

This stays intentionally local to the runtime/runner and does not imply a managed scheduler-owned loop. It is used only for descriptive driver-state reporting.

◆ SimTimeModel

typedef enum SimTimeModel SimTimeModel

Time evolution model for the simulation.

SIM_TIME_MODEL_CONTINUOUS: dt refinement should converge (ODE/PDE flows). SIM_TIME_MODEL_MAP: dt is part of the discrete map; refinement changes the model.

Enumeration Type Documentation

◆ SimRuntimeCallerStepMode

Most recent caller-owned stepping primitive observed on the context.

This stays intentionally local to the runtime/runner and does not imply a managed scheduler-owned loop. It is used only for descriptive driver-state reporting.

Enumerator
SIM_RUNTIME_CALLER_STEP_MODE_NONE 

No caller-owned step observed.

SIM_RUNTIME_CALLER_STEP_MODE_MANUAL_STEP 

Context manual-step path observed.

SIM_RUNTIME_CALLER_STEP_MODE_INTEGRATOR_STEP 

Integrator-owned step path observed.

◆ SimRuntimeLoopErrorSource

Origin of the most recent loop/runtime failure.

Enumerator
SIM_RUNTIME_LOOP_ERROR_SOURCE_NONE 

No error source has been recorded.

SIM_RUNTIME_LOOP_ERROR_SOURCE_SCHEDULER_STEP 

Scheduler step dispatch failed.

SIM_RUNTIME_LOOP_ERROR_SOURCE_EXECUTION_FRAME 

Execution-frame setup failed.

SIM_RUNTIME_LOOP_ERROR_SOURCE_OPERATOR_EXECUTION 

Operator execution failed.

SIM_RUNTIME_LOOP_ERROR_SOURCE_INTEGRATOR_BRIDGE 

Integrator bridge failed.

SIM_RUNTIME_LOOP_ERROR_SOURCE_INTEGRATOR_SEQUENCE 

Integrator sequence failed.

SIM_RUNTIME_LOOP_ERROR_SOURCE_LEGACY_STEP 

Legacy stepping path failed.

◆ SimRuntimeLoopProgressKind

Kind of caller-owned bounded loop currently being observed.

Enumerator
SIM_RUNTIME_LOOP_PROGRESS_NONE 

No bounded loop is active.

SIM_RUNTIME_LOOP_PROGRESS_RUN_STEPS 

sim_context_run_steps-style loop.

SIM_RUNTIME_LOOP_PROGRESS_RUN_UNTIL 

sim_context_run_until-style loop.

SIM_RUNTIME_LOOP_PROGRESS_RUN_INTEGRATOR_STEPS 

Integrator-step-count loop.

SIM_RUNTIME_LOOP_PROGRESS_RUN_UNTIL_INTEGRATOR 

Integrator run-until loop.

SIM_RUNTIME_LOOP_PROGRESS_RUN_PARAMETER_SWEEP 

Parameter sweep loop.

SIM_RUNTIME_LOOP_PROGRESS_RUN_PARAMETER_GRID 

Parameter grid loop.

SIM_RUNTIME_LOOP_PROGRESS_RUN_PARAMETER_CONTINUATION 

Parameter continuation loop.

◆ SimRuntimeLoopStopReason

Last observed terminal/non-running reason for a managed loop.

Enumerator
SIM_RUNTIME_LOOP_STOP_REASON_NONE 

No terminal reason has been recorded.

SIM_RUNTIME_LOOP_STOP_REASON_PAUSED 

Loop stopped because execution was paused.

SIM_RUNTIME_LOOP_STOP_REASON_CANCELLED 

Loop stopped because cancellation was requested.

SIM_RUNTIME_LOOP_STOP_REASON_STEPS_EXHAUSTED 

Loop consumed its step budget.

SIM_RUNTIME_LOOP_STOP_REASON_MAX_SIM_TIME_REACHED 

Simulation-time budget reached.

SIM_RUNTIME_LOOP_STOP_REASON_MAX_WALL_MS_REACHED 

Wall-clock budget reached.

SIM_RUNTIME_LOOP_STOP_REASON_RUNTIME_ERROR 

Loop stopped after a runtime error.

◆ SimTimeModel

Time evolution model for the simulation.

SIM_TIME_MODEL_CONTINUOUS: dt refinement should converge (ODE/PDE flows). SIM_TIME_MODEL_MAP: dt is part of the discrete map; refinement changes the model.

Enumerator
SIM_TIME_MODEL_CONTINUOUS 

Continuous-time model where dt refinement should converge.

SIM_TIME_MODEL_MAP 

Discrete map where dt is part of the model definition.

Function Documentation

◆ sim_runtime_caller_step_mode_name()

const char * sim_runtime_caller_step_mode_name ( SimRuntimeCallerStepMode  mode)

Convert a caller-owned step mode to a stable machine-readable name.

Parameters
modeCaller step mode enum value.
Returns
Static lowercase name.

◆ sim_runtime_loop_error_source_name()

const char * sim_runtime_loop_error_source_name ( SimRuntimeLoopErrorSource  source)

Convert a loop error source to a stable machine-readable name.

Parameters
sourceError source enum value.
Returns
Static lowercase name.

◆ sim_runtime_loop_progress_kind_name()

const char * sim_runtime_loop_progress_kind_name ( SimRuntimeLoopProgressKind  kind)

Convert a loop-progress kind to a stable machine-readable name.

Parameters
kindLoop-progress kind enum value.
Returns
Static lowercase name.

◆ sim_runtime_loop_stop_reason_name()

const char * sim_runtime_loop_stop_reason_name ( SimRuntimeLoopStopReason  reason)

Convert a loop stop reason to a stable machine-readable name.

Parameters
reasonStop reason enum value.
Returns
Static lowercase name.

◆ sim_runtime_state_acquire_external_driver()

void sim_runtime_state_acquire_external_driver ( SimRuntimeState state)

Acquire a caller-owned external-driver claim.

Parameters
stateRuntime state to update.

◆ sim_runtime_state_caller_step_streak()

size_t sim_runtime_state_caller_step_streak ( const SimRuntimeState state)

Fetch the consecutive caller-owned step streak.

Parameters
stateRuntime state to inspect.
Returns
Consecutive streak count, or 0 for NULL state.

◆ sim_runtime_state_clear_caller_step_history()

void sim_runtime_state_clear_caller_step_history ( SimRuntimeState state)

Clear descriptive caller-owned step history.

Parameters
stateRuntime state to update.

◆ sim_runtime_state_clear_external_driver()

void sim_runtime_state_clear_external_driver ( SimRuntimeState state)

Clear all caller-owned external-driver claims.

Parameters
stateRuntime state to update.

◆ sim_runtime_state_clear_last_loop_progress()

void sim_runtime_state_clear_last_loop_progress ( SimRuntimeState state)

Clear any retained completed caller-owned loop progress snapshot.

Parameters
stateRuntime state to update.

◆ sim_runtime_state_clear_loop_error()

void sim_runtime_state_clear_loop_error ( SimRuntimeState state)

Clear the most recent loop/runtime error record.

Parameters
stateRuntime state to update.

◆ sim_runtime_state_clear_loop_progress()

void sim_runtime_state_clear_loop_progress ( SimRuntimeState state)

Clear the current caller-owned loop progress snapshot.

Parameters
stateRuntime state to update.

◆ sim_runtime_state_copy_step_metrics()

size_t sim_runtime_state_copy_step_metrics ( const SimRuntimeState state,
SimStepMetrics dest,
size_t  capacity 
)

Copy up to capacity samples into dest ordered from oldest to newest.

Parameters
stateRuntime state to inspect.
[out]destDestination array for copied samples.
capacityNumber of entries available in dest.
Returns
Number of samples written.

◆ sim_runtime_state_destroy()

void sim_runtime_state_destroy ( SimRuntimeState state)

Destroy runtime state and release resources.

Parameters
stateRuntime state to destroy; NULL is ignored.

◆ sim_runtime_state_ensure_continuity_capacity()

SimResult sim_runtime_state_ensure_continuity_capacity ( SimRuntimeState state,
size_t  required 
)

Ensure continuity counters can index at least required fields.

Parameters
stateRuntime state to grow.
requiredRequired number of field entries.
Returns
SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, or SIM_RESULT_OUT_OF_MEMORY.

◆ sim_runtime_state_external_driver_depth()

size_t sim_runtime_state_external_driver_depth ( const SimRuntimeState state)

Report the current nested external-driver claim depth.

Parameters
stateRuntime state to inspect.
Returns
Current claim depth, or 0 for NULL state.

◆ sim_runtime_state_init()

SimResult sim_runtime_state_init ( SimRuntimeState state)

Initialize runtime state with defaults.

Parameters
stateRuntime state to initialize.
Returns
SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.

◆ sim_runtime_state_last_caller_step_mode()

SimRuntimeCallerStepMode sim_runtime_state_last_caller_step_mode ( const SimRuntimeState state)

Fetch the last caller-owned step primitive observed.

Parameters
stateRuntime state to inspect.
Returns
Last mode, or SIM_RUNTIME_CALLER_STEP_MODE_NONE for NULL state.

◆ sim_runtime_state_last_loop_error()

bool sim_runtime_state_last_loop_error ( const SimRuntimeState state,
SimRuntimeLoopError out_error 
)

Fetch the most recent loop/runtime error.

Parameters
stateRuntime state to inspect.
[out]out_errorReceives the error record.
Returns
true when a valid error record was available.

◆ sim_runtime_state_last_loop_progress()

bool sim_runtime_state_last_loop_progress ( const SimRuntimeState state,
SimRuntimeLoopProgress out_progress 
)

Fetch the most recent completed caller-owned loop progress snapshot.

Parameters
stateRuntime state to inspect.
[out]out_progressReceives the retained final progress snapshot.
Returns
true when a retained final progress snapshot is available.

◆ sim_runtime_state_last_stop_reason()

SimRuntimeLoopStopReason sim_runtime_state_last_stop_reason ( const SimRuntimeState state)

Fetch the most recent loop stop reason.

Parameters
stateRuntime state to inspect.
Returns
Stored reason, or SIM_RUNTIME_LOOP_STOP_REASON_NONE for NULL state.

◆ sim_runtime_state_latest_step_metrics()

bool sim_runtime_state_latest_step_metrics ( const SimRuntimeState state,
SimStepMetrics out_metrics 
)

Copy the most recent step metrics sample.

Parameters
stateRuntime state to inspect.
[out]out_metricsReceives the latest sample.
Returns
true when a sample was available.

◆ sim_runtime_state_loop_progress()

bool sim_runtime_state_loop_progress ( const SimRuntimeState state,
SimRuntimeLoopProgress out_progress 
)

Fetch the current caller-owned loop progress snapshot.

Parameters
stateRuntime state to inspect.
[out]out_progressReceives the active progress snapshot.
Returns
true when a progress snapshot is active.

◆ sim_runtime_state_note_caller_step()

void sim_runtime_state_note_caller_step ( SimRuntimeState state,
SimRuntimeCallerStepMode  mode 
)

Record a successful caller-owned step primitive.

Parameters
stateRuntime state to update.
modeStep primitive to record; NONE is ignored.

◆ sim_runtime_state_pending_cancel()

bool sim_runtime_state_pending_cancel ( const SimRuntimeState state)

Read the current pending-cancel flag.

Parameters
stateRuntime state to inspect.
Returns
true when a cancel request is pending.

◆ sim_runtime_state_record_loop_error()

void sim_runtime_state_record_loop_error ( SimRuntimeState state,
SimResult  code,
SimRuntimeLoopErrorSource  source,
size_t  step_index 
)

Record the most recent loop/runtime error.

Parameters
stateRuntime state to update.
codeError result code.
sourceSubsystem that produced the error.
step_indexStep index associated with the error.

◆ sim_runtime_state_record_step_metrics()

void sim_runtime_state_record_step_metrics ( SimRuntimeState state,
const SimStepMetrics metrics 
)

Append a step metrics sample to the runtime ring buffer.

Parameters
stateRuntime state to update.
metricsMetrics sample to copy; NULL is ignored.

◆ sim_runtime_state_release_continuity_buffers()

void sim_runtime_state_release_continuity_buffers ( SimRuntimeState state)

Release continuity buffer allocations.

Parameters
stateRuntime state to update; NULL is ignored.

◆ sim_runtime_state_release_external_driver()

void sim_runtime_state_release_external_driver ( SimRuntimeState state)

Release one caller-owned external-driver claim.

Parameters
stateRuntime state to update.

◆ sim_runtime_state_set_last_stop_reason()

void sim_runtime_state_set_last_stop_reason ( SimRuntimeState state,
SimRuntimeLoopStopReason  reason 
)

Record the most recent loop stop reason.

Parameters
stateRuntime state to update.
reasonStop reason to store.

◆ sim_runtime_state_set_loop_progress()

void sim_runtime_state_set_loop_progress ( SimRuntimeState state,
const SimRuntimeLoopProgress progress 
)

Replace the current caller-owned loop progress snapshot.

Parameters
stateRuntime state to update.
progressProgress snapshot to copy; NULL clears active progress.

◆ sim_runtime_state_set_pending_cancel()

void sim_runtime_state_set_pending_cancel ( SimRuntimeState state,
bool  pending 
)

Mark whether a scheduler-owned cancel is in progress.

Parameters
stateRuntime state to update.
pendingPending-cancel flag value.