sim_runtime_state.h

Go to the documentation of this file.

 
#ifndef OAKFIELD_SIM_RUNTIME_STATE_H
#define OAKFIELD_SIM_RUNTIME_STATE_H
 
#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"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef SIM_RUNTIME_DEFAULT_DT
#define SIM_RUNTIME_DEFAULT_DT 0.0166667f
#endif
 
#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
 
typedef struct SimRuntimeComplexSample {
    double re; 
    double im; 
} SimRuntimeComplexSample;
 
typedef struct SimRuntimePhasePortraitMetrics {
    double mean_re;    
    double mean_im;    
    double max_dev_x;  
    double max_dev_y;  
    double max_dev;    
    double min_radius; 
    double max_radius; 
    double min_r2;     
    double max_r2;     
    double rms_radius; 
    size_t count;      
} SimRuntimePhasePortraitMetrics;
 
typedef struct SimRuntimeWaveformSampleStats {
    double min_value;     
    double max_value;     
    double max_magnitude; 
    size_t count;         
} SimRuntimeWaveformSampleStats;
 
typedef enum SimTimeModel {
    SIM_TIME_MODEL_CONTINUOUS =
        0,                 
    SIM_TIME_MODEL_MAP = 1 
} SimTimeModel;
 
#define SIM_STEP_METRIC_HISTORY 128U
 
typedef struct SimStepMetrics {
    size_t step_index;           
    double requested_dt;         
    double accepted_dt;          
    double next_dt;              
    double rms_error;            
    uint64_t step_wall_ns;       
    uint64_t integrator_wall_ns; 
    uint64_t operator_wall_ns;   
    uint64_t dirty_write_count;  
    uint64_t stable_write_count; 
    uint64_t integrator_workspace_bytes;     
    uint64_t integrator_drift_scratch_bytes; 
    uint32_t integrator_attempt_count; 
    uint32_t integrator_rejection_count; 
    uint32_t active_warp_mask;           
} SimStepMetrics;
 
typedef 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         
} SimRuntimeLoopStopReason;
 
typedef 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          
} SimRuntimeLoopErrorSource;
 
typedef struct SimRuntimeLoopError {
    bool valid;                       
    SimResult code;                   
    SimRuntimeLoopErrorSource source; 
    size_t step_index;                
} SimRuntimeLoopError;
 
typedef enum SimRuntimeCallerStepMode {
    SIM_RUNTIME_CALLER_STEP_MODE_NONE = 0,       
    SIM_RUNTIME_CALLER_STEP_MODE_MANUAL_STEP,    
    SIM_RUNTIME_CALLER_STEP_MODE_INTEGRATOR_STEP 
} SimRuntimeCallerStepMode;
 
typedef 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 
} SimRuntimeLoopProgressKind;
 
typedef struct SimRuntimeLoopProgress {
    bool active;                     
    SimRuntimeLoopProgressKind kind; 
    uint64_t steps_completed;        
    uint64_t checks_completed;       
    uint64_t step_chunk;             
    uint64_t step_budget;            
    uint64_t check_budget;           
    double sim_time_advanced;        
    double wall_time_ms;             
    double sim_time_budget;          
    double wall_time_budget;         
    double requested_dt;             
    size_t trace_limit;              
    bool has_step_chunk;             
    bool has_step_budget;            
    bool has_check_budget;           
    bool has_sim_time_budget;        
    bool has_wall_time_budget;       
    bool has_requested_dt;           
    bool has_trace_limit;            
} SimRuntimeLoopProgress;
 
typedef struct SimRuntimeState {
    double dt;                  
    SimTimeModel time_model;    
    size_t step_index;          
    double time_accumulated;    
    uint32_t drift_mode_depth;  
    double drift_time_override; 
    bool drift_time_override_active;     
    uint64_t *field_dirty_counts;        
    uint64_t *field_stable_counts;       
    double *field_phase_ema;             
    double *field_phase_last_time;       
    uint8_t *field_phase_lock_state;     
    uint8_t *field_phase_initialized;    
    SimFieldStats *drift_field_stats;    
    size_t drift_field_stats_step_index; 
    bool *drift_field_stats_valid;       
    bool *drift_field_stats_requested;   
    SimComplexDouble **drift_field_snapshots; 
    size_t *drift_field_snapshot_capacity;    
    size_t *drift_field_snapshot_count;       
    size_t *drift_field_snapshot_step_index;  
    bool *drift_field_snapshot_valid;         
    bool *drift_field_snapshot_requested;     
    SimFieldStats *field_stats_cache;         
    size_t *field_stats_cache_step_index;     
    SimFieldStatsComputeConfig
        field_stats_config; 
    SimFieldStatsRuntimeProfile
        field_stats_profile; 
    SimFieldTopologyRuntimeState *field_topology_cache; 
    size_t *field_health_cache_step_index; 
    size_t *field_health_nan_counts;       
    size_t *field_health_inf_counts;       
    size_t measurement_cache_step_index; 
    bool measurement_cache_valid;        
    double measurement_energy;           
    double measurement_dissipation;      
    double measurement_remainder;        
    size_t measurement_remainder_sources;          
    bool measurement_energy_valid;                 
    bool measurement_dissipation_valid;            
    bool measurement_remainder_valid;              
    SimRuntimeComplexSample **visual_sample_cache; 
    size_t *visual_sample_cache_capacity;          
    size_t *visual_sample_cache_count;             
    size_t *visual_sample_cache_step_index;   
    size_t *visual_sample_cache_source_count; 
    size_t *visual_sample_cache_stride;       
    bool *visual_sample_cache_valid;          
    SimRuntimePhasePortraitMetrics
        *phase_portrait_metrics_cache;               
    size_t *phase_portrait_metrics_cache_step_index; 
    size_t *phase_portrait_metrics_cache_sample_count; 
    bool *phase_portrait_metrics_cache_valid;          
    SimRuntimeWaveformSampleStats
        *waveform_sample_stats_cache;               
    size_t *waveform_sample_stats_cache_step_index; 
    size_t *waveform_sample_stats_cache_sample_count; 
    bool *waveform_sample_stats_cache_valid; 
    size_t
        visual_sample_target_samples; 
    size_t visual_sample_max_samples; 
    size_t continuity_capacity;       
    uint32_t current_step_warp_mask;  
    FluxLensState flux_lens;          
    FluxLensWorkspace flux_workspace; 
    SimStepMetrics
        step_metrics[SIM_STEP_METRIC_HISTORY]; 
    size_t step_metrics_head;                  
    size_t step_metrics_count;                 
    bool step_metrics_valid; 
    SimStepMetrics step_metrics_latest;        
    bool pending_cancel;                       
    SimRuntimeLoopStopReason last_stop_reason; 
    SimRuntimeLoopError last_loop_error;       
    SimRuntimeCallerStepMode
        last_caller_step_mode; 
    size_t
        caller_step_streak; 
    uint32_t external_driver_depth; 
    SimRuntimeLoopProgress
        loop_progress; 
    SimRuntimeLoopProgress
        last_loop_progress;        
    bool last_loop_progress_valid; 
} SimRuntimeState;
 
SimResult sim_runtime_state_init(SimRuntimeState *state);
 
void sim_runtime_state_release_continuity_buffers(SimRuntimeState *state);
 
SimResult sim_runtime_state_ensure_continuity_capacity(SimRuntimeState *state, size_t required);
 
void sim_runtime_state_destroy(SimRuntimeState *state);
 
void sim_runtime_state_record_step_metrics(SimRuntimeState *state, const SimStepMetrics *metrics);
 
bool sim_runtime_state_latest_step_metrics(const SimRuntimeState *state,
                                           SimStepMetrics *out_metrics);
 
size_t sim_runtime_state_copy_step_metrics(const SimRuntimeState *state, SimStepMetrics *dest,
                                           size_t capacity);
 
void sim_runtime_state_set_pending_cancel(SimRuntimeState *state, bool pending);
 
bool sim_runtime_state_pending_cancel(const SimRuntimeState *state);
 
void sim_runtime_state_set_last_stop_reason(SimRuntimeState *state,
                                            SimRuntimeLoopStopReason reason);
 
SimRuntimeLoopStopReason sim_runtime_state_last_stop_reason(const SimRuntimeState *state);
 
void sim_runtime_state_clear_loop_error(SimRuntimeState *state);
 
void sim_runtime_state_record_loop_error(SimRuntimeState *state, SimResult code,
                                         SimRuntimeLoopErrorSource source, size_t step_index);
 
bool sim_runtime_state_last_loop_error(const SimRuntimeState *state,
                                       SimRuntimeLoopError *out_error);
 
void sim_runtime_state_note_caller_step(SimRuntimeState *state, SimRuntimeCallerStepMode mode);
 
void sim_runtime_state_clear_caller_step_history(SimRuntimeState *state);
 
SimRuntimeCallerStepMode sim_runtime_state_last_caller_step_mode(const SimRuntimeState *state);
 
size_t sim_runtime_state_caller_step_streak(const SimRuntimeState *state);
 
void sim_runtime_state_acquire_external_driver(SimRuntimeState *state);
 
void sim_runtime_state_release_external_driver(SimRuntimeState *state);
 
void sim_runtime_state_clear_external_driver(SimRuntimeState *state);
 
size_t sim_runtime_state_external_driver_depth(const SimRuntimeState *state);
 
void sim_runtime_state_set_loop_progress(SimRuntimeState *state,
                                         const SimRuntimeLoopProgress *progress);
 
void sim_runtime_state_clear_loop_progress(SimRuntimeState *state);
 
bool sim_runtime_state_loop_progress(const SimRuntimeState *state,
                                     SimRuntimeLoopProgress *out_progress);
 
bool sim_runtime_state_last_loop_progress(const SimRuntimeState *state,
                                          SimRuntimeLoopProgress *out_progress);
 
void sim_runtime_state_clear_last_loop_progress(SimRuntimeState *state);
 
const char *sim_runtime_loop_stop_reason_name(SimRuntimeLoopStopReason reason);
 
const char *sim_runtime_loop_error_source_name(SimRuntimeLoopErrorSource source);
 
const char *sim_runtime_caller_step_mode_name(SimRuntimeCallerStepMode mode);
 
const char *sim_runtime_loop_progress_kind_name(SimRuntimeLoopProgressKind kind);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OAKFIELD_SIM_RUNTIME_STATE_H */