|
Oakfield API Documentation 1.0.0
Numerical core APIs
|
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"

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. | |
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. | |
Dynamic runtime state for simulations.
| #define SIM_STEP_METRIC_HISTORY 128U |
Number of per-step samples preserved in the runtime ring buffer.
| typedef enum SimRuntimeCallerStepMode 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.
| 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.
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.
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. |
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. |
Last observed terminal/non-running reason for a managed loop.
| enum 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. |
| const char * sim_runtime_caller_step_mode_name | ( | SimRuntimeCallerStepMode | mode | ) |
Convert a caller-owned step mode to a stable machine-readable name.
| mode | Caller step mode enum value. |
| const char * sim_runtime_loop_error_source_name | ( | SimRuntimeLoopErrorSource | source | ) |
Convert a loop error source to a stable machine-readable name.
| source | Error source enum value. |
| const char * sim_runtime_loop_progress_kind_name | ( | SimRuntimeLoopProgressKind | kind | ) |
Convert a loop-progress kind to a stable machine-readable name.
| kind | Loop-progress kind enum value. |
| const char * sim_runtime_loop_stop_reason_name | ( | SimRuntimeLoopStopReason | reason | ) |
Convert a loop stop reason to a stable machine-readable name.
| reason | Stop reason enum value. |
| void sim_runtime_state_acquire_external_driver | ( | SimRuntimeState * | state | ) |
Acquire a caller-owned external-driver claim.
| state | Runtime state to update. |
| size_t sim_runtime_state_caller_step_streak | ( | const SimRuntimeState * | state | ) |
Fetch the consecutive caller-owned step streak.
| state | Runtime state to inspect. |
| void sim_runtime_state_clear_caller_step_history | ( | SimRuntimeState * | state | ) |
Clear descriptive caller-owned step history.
| state | Runtime state to update. |
| void sim_runtime_state_clear_external_driver | ( | SimRuntimeState * | state | ) |
Clear all caller-owned external-driver claims.
| state | Runtime state to update. |
| void sim_runtime_state_clear_last_loop_progress | ( | SimRuntimeState * | state | ) |
Clear any retained completed caller-owned loop progress snapshot.
| state | Runtime state to update. |
| void sim_runtime_state_clear_loop_error | ( | SimRuntimeState * | state | ) |
Clear the most recent loop/runtime error record.
| state | Runtime state to update. |
| void sim_runtime_state_clear_loop_progress | ( | SimRuntimeState * | state | ) |
Clear the current caller-owned loop progress snapshot.
| state | Runtime state to update. |
| 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.
| state | Runtime state to inspect. | |
| [out] | dest | Destination array for copied samples. |
| capacity | Number of entries available in dest. |
| void sim_runtime_state_destroy | ( | SimRuntimeState * | state | ) |
Destroy runtime state and release resources.
| state | Runtime state to destroy; NULL is ignored. |
| SimResult sim_runtime_state_ensure_continuity_capacity | ( | SimRuntimeState * | state, |
| size_t | required | ||
| ) |
Ensure continuity counters can index at least required fields.
| state | Runtime state to grow. |
| required | Required number of field entries. |
| size_t sim_runtime_state_external_driver_depth | ( | const SimRuntimeState * | state | ) |
Report the current nested external-driver claim depth.
| state | Runtime state to inspect. |
| SimResult sim_runtime_state_init | ( | SimRuntimeState * | state | ) |
Initialize runtime state with defaults.
| state | Runtime state to initialize. |
| SimRuntimeCallerStepMode sim_runtime_state_last_caller_step_mode | ( | const SimRuntimeState * | state | ) |
Fetch the last caller-owned step primitive observed.
| state | Runtime state to inspect. |
SIM_RUNTIME_CALLER_STEP_MODE_NONE for NULL state. | bool sim_runtime_state_last_loop_error | ( | const SimRuntimeState * | state, |
| SimRuntimeLoopError * | out_error | ||
| ) |
Fetch the most recent loop/runtime error.
| state | Runtime state to inspect. | |
| [out] | out_error | Receives the error record. |
| bool sim_runtime_state_last_loop_progress | ( | const SimRuntimeState * | state, |
| SimRuntimeLoopProgress * | out_progress | ||
| ) |
Fetch the most recent completed caller-owned loop progress snapshot.
| state | Runtime state to inspect. | |
| [out] | out_progress | Receives the retained final progress snapshot. |
| SimRuntimeLoopStopReason sim_runtime_state_last_stop_reason | ( | const SimRuntimeState * | state | ) |
Fetch the most recent loop stop reason.
| state | Runtime state to inspect. |
SIM_RUNTIME_LOOP_STOP_REASON_NONE for NULL state. | bool sim_runtime_state_latest_step_metrics | ( | const SimRuntimeState * | state, |
| SimStepMetrics * | out_metrics | ||
| ) |
Copy the most recent step metrics sample.
| state | Runtime state to inspect. | |
| [out] | out_metrics | Receives the latest sample. |
| bool sim_runtime_state_loop_progress | ( | const SimRuntimeState * | state, |
| SimRuntimeLoopProgress * | out_progress | ||
| ) |
Fetch the current caller-owned loop progress snapshot.
| state | Runtime state to inspect. | |
| [out] | out_progress | Receives the active progress snapshot. |
| void sim_runtime_state_note_caller_step | ( | SimRuntimeState * | state, |
| SimRuntimeCallerStepMode | mode | ||
| ) |
Record a successful caller-owned step primitive.
| state | Runtime state to update. |
| mode | Step primitive to record; NONE is ignored. |
| bool sim_runtime_state_pending_cancel | ( | const SimRuntimeState * | state | ) |
Read the current pending-cancel flag.
| state | Runtime state to inspect. |
| void sim_runtime_state_record_loop_error | ( | SimRuntimeState * | state, |
| SimResult | code, | ||
| SimRuntimeLoopErrorSource | source, | ||
| size_t | step_index | ||
| ) |
Record the most recent loop/runtime error.
| state | Runtime state to update. |
| code | Error result code. |
| source | Subsystem that produced the error. |
| step_index | Step index associated with the error. |
| void sim_runtime_state_record_step_metrics | ( | SimRuntimeState * | state, |
| const SimStepMetrics * | metrics | ||
| ) |
Append a step metrics sample to the runtime ring buffer.
| state | Runtime state to update. |
| metrics | Metrics sample to copy; NULL is ignored. |
| void sim_runtime_state_release_continuity_buffers | ( | SimRuntimeState * | state | ) |
Release continuity buffer allocations.
| state | Runtime state to update; NULL is ignored. |
| void sim_runtime_state_release_external_driver | ( | SimRuntimeState * | state | ) |
Release one caller-owned external-driver claim.
| state | Runtime state to update. |
| void sim_runtime_state_set_last_stop_reason | ( | SimRuntimeState * | state, |
| SimRuntimeLoopStopReason | reason | ||
| ) |
Record the most recent loop stop reason.
| state | Runtime state to update. |
| reason | Stop reason to store. |
| void sim_runtime_state_set_loop_progress | ( | SimRuntimeState * | state, |
| const SimRuntimeLoopProgress * | progress | ||
| ) |
Replace the current caller-owned loop progress snapshot.
| state | Runtime state to update. |
| progress | Progress snapshot to copy; NULL clears active progress. |
| void sim_runtime_state_set_pending_cancel | ( | SimRuntimeState * | state, |
| bool | pending | ||
| ) |
Mark whether a scheduler-owned cancel is in progress.
| state | Runtime state to update. |
| pending | Pending-cancel flag value. |