sim_context.h

Go to the documentation of this file.

 
#ifndef OAKFIELD_SIM_CONTEXT_H
#define OAKFIELD_SIM_CONTEXT_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "async_logger.h"
#include "field.h"
#include "kernel_ir.h"
#include "math/special_functions.h"
#include "neural_models.h"
#include "operator.h"
#include "sim_diagnostics.h"
#include "sim_integrator_state.h"
#include "sim_profiler.h"
#include "sim_runtime_state.h"
#include "sim_scheduler_state.h"
#include "sim_seed.h"
#include "sim_world.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct Integrator;
struct SimBackend;
struct SimOperator;
 
#define SIM_CONTEXT_MAX_FIELD_ELEMENTS_DEFAULT (64U * 1024U * 1024U)
#define SIM_CONTEXT_MAX_FIELD_BYTES_DEFAULT (512U * 1024U * 1024U)
#define SIM_CONTEXT_MAX_FIELDS_DEFAULT 256U
#define SIM_CONTEXT_MAX_TOTAL_FIELD_BYTES_DEFAULT (2ULL * 1024ULL * 1024ULL * 1024ULL)
#define SIM_CONTEXT_PREFERRED_VISUAL_FIELD_CAPACITY 256U
#define SIM_CONTEXT_MAX_SCRATCH_BYTES_PER_OPERATOR_DEFAULT (256U * 1024U * 1024U)
 
typedef struct SimContextMemoryLimits {
    size_t max_field_elements;             
    size_t max_field_bytes;                
    size_t max_fields;                     
    size_t max_total_field_bytes;          
    size_t max_scratch_bytes_per_operator; 
} SimContextMemoryLimits;
 
typedef struct SimContext {
    SimWorld world;                 
    SimRuntimeState runtime;        
    SimSchedulerPlan scheduler;     
    SimIntegratorState integrators; 
    SimDiagnostics diag;            
    SimProfiler profiler;           
    bool profiler_ready;            
    uint64_t base_seed;             
    SimRepresentationMode representation_mode; 
    SimContextMemoryLimits memory_limits;      
    size_t bytes_fields_in_use;                
    size_t bytes_scratch_in_use;               
    size_t bytes_total_in_use;                 
    bool continuity_override_enabled;      
    SimOperatorConfig continuity_override; 
    /* Optional GUI preference: preferred visual and phase modes exposed to UI. -1 when unspecified.
     */
    int preferred_gui_visual_mode;        
    int preferred_gui_phase_mode;         
    int preferred_gui_visual_auto_scale;  
    double preferred_gui_visual_scale;    
    int preferred_gui_visual_field_index; 
    bool preferred_gui_visual_field_selected
        [SIM_CONTEXT_PREFERRED_VISUAL_FIELD_CAPACITY]; 
    void (*log_fn)(SimLogLevel level, const char *message,
                   void *userdata); 
    void *log_userdata;                   
    SimNeuralModelRegistry neural_models; 
} SimContext;
 
void sim_context_set_representation_mode(SimContext *context, SimRepresentationMode mode);
 
SimRepresentationMode sim_context_representation_mode(const SimContext *context);
 
void sim_context_set_logger(SimContext *context,
                            void (*log_fn)(SimLogLevel level, const char *message, void *userdata),
                            void *userdata);
 
void sim_context_log_warning(const SimContext *context, const char *fmt, ...);
 
bool sim_context_allows_determinism(const SimContext *context, SimDeterminismFlags flags);
 
bool sim_context_kernel_allowed(const SimContext *context, uint64_t required_features,
                                SimDeterminismFlags determinism_flags);
 
bool sim_context_kernel_allowed_mode(const SimContext *context, SimRepresentationMode mode,
                                     uint64_t required_features,
                                     SimDeterminismFlags determinism_flags);
 
SimResult sim_context_init(SimContext *context);
 
SimResult sim_context_init_with_universe(SimContext *context, const SimUniverseSpec *universe_spec);
 
void sim_context_set_seed(SimContext *context, uint64_t seed);
 
uint64_t sim_context_seed(const SimContext *context);
 
void sim_context_set_memory_limits(SimContext *context, const SimContextMemoryLimits *limits);
 
void sim_context_get_memory_limits(const SimContext *context, SimContextMemoryLimits *out_limits);
 
void sim_context_memory_usage(const SimContext *context, size_t *out_fields, size_t *out_scratch,
                              size_t *out_total);
 
SimResult sim_context_check_field_limits(const SimContext *context, size_t element_count,
                                         size_t field_bytes);
 
SimResult sim_context_reserve_scratch(SimContext *context, size_t bytes);
 
void sim_context_release_scratch(SimContext *context, size_t bytes);
 
void sim_context_destroy(SimContext *context);
 
SimResult sim_context_add_field(SimContext *context, SimField *field, size_t *out_index);
 
SimField *sim_context_field(SimContext *context, size_t index);
 
size_t sim_context_field_count(const SimContext *context);
 
SimResult sim_context_register_operator(SimContext *context,
                                        const SimOperatorDescriptor *descriptor, size_t *out_index);
 
SimResult sim_context_add_operator_dependency(SimContext *context, size_t operator_index,
                                              size_t dependency_index);
 
SimResult sim_context_prepare_plan(SimContext *context);
 
SimResult sim_context_execute(SimContext *context);
 
SimResult sim_context_execute_prepared(SimContext *context);
 
SimIRBuilder *sim_context_ir_builder(SimContext *context);
 
void sim_context_set_integrator(SimContext *context, struct Integrator *integrator);
 
struct Integrator *sim_context_integrator(SimContext *context);
 
SimResult sim_context_set_integrator_sequence(SimContext *context,
                                              struct Integrator *const *integrators, size_t count);
 
size_t sim_context_integrator_sequence_count(const SimContext *context);
 
struct Integrator *sim_context_integrator_sequence_at(const SimContext *context, size_t index);
 
void sim_context_set_backend(SimContext *context, struct SimBackend *backend);
 
struct SimBackend *sim_context_backend(SimContext *context);
 
void sim_context_set_timestep(SimContext *context, double dt);
 
double sim_context_timestep(const SimContext *context);
 
void sim_context_set_field_stats_features(SimContext *context, uint32_t feature_mask);
uint32_t sim_context_field_stats_features(const SimContext *context);
void sim_context_reset_field_stats_profile(SimContext *context);
bool sim_context_field_stats_profile(const SimContext *context,
                                     SimFieldStatsRuntimeProfile *out_profile);
 
void sim_context_set_time_model(SimContext *context, SimTimeModel model);
 
void sim_context_begin_drift(SimContext *context);
void sim_context_end_drift(SimContext *context);
bool sim_context_in_drift(const SimContext *context);
void sim_context_set_drift_time_override(SimContext *context, double time_value);
void sim_context_clear_drift_time_override(SimContext *context);
 
size_t sim_context_step_index(const SimContext *context);
 
double sim_context_time(const SimContext *context);
 
void sim_context_record_step_metrics(SimContext *context, double requested_dt, double accepted_dt,
                                     double rms_error);
 
void sim_context_record_step_metrics_with_timing(SimContext *context, double requested_dt,
                                                 double accepted_dt, double rms_error,
                                                 uint64_t step_wall_ns, uint64_t integrator_wall_ns,
                                                 uint64_t operator_wall_ns);
 
void sim_context_accept_step(SimContext *context, double accepted_dt);
 
bool sim_context_latest_step_metrics(const SimContext *context, SimStepMetrics *out_metrics);
 
size_t sim_context_step_metrics_history(const SimContext *context, SimStepMetrics *dest,
                                        size_t capacity);
 
bool sim_context_profiler_counters(SimContext *context, SimProfilerCounter *out_counters,
                                   size_t capacity, size_t *out_count);
 
bool sim_context_profiler_snapshot(SimContext *context, SimProfilerSnapshot *out_snapshot);
 
void sim_split_notify_integrator(struct SimContext *context, double dt_sub, double error_estimate);
size_t sim_context_truncation_level(const SimContext *context);
 
double sim_context_epsilon(const SimContext *context);
 
const SimPole *sim_context_poles(const SimContext *context, size_t *out_count);
SimPoleFieldOptions sim_pole_field_options_default(void);
SimResult sim_context_synthesize_pole_field(struct SimContext *context, size_t field_index,
                                            const SimPoleFieldOptions *options);
 
void sim_context_set_special_fallback(SimContext *context, SimSpecialFallbackFn fallback,
                                      void *userdata);
 
void sim_context_set_preferred_visual_mode(SimContext *context, int mode);
 
int sim_context_preferred_visual_mode(const SimContext *context);
 
/* Set preferred Phase Mode (negative = unset) */
void sim_context_set_preferred_phase_mode(SimContext *context, int mode);
 
/* Get preferred Phase Mode; returns negative when unset. */
int sim_context_preferred_phase_mode(const SimContext *context);
 
/* Set preferred visual auto-scale state (-1 unset, 0 disabled, 1 enabled). */
void sim_context_set_preferred_visual_auto_scale(SimContext *context, int enabled);
 
/* Get preferred visual auto-scale state; returns negative when unset. */
int sim_context_preferred_visual_auto_scale(const SimContext *context);
 
/* Set preferred visual scale (positive value, negative to unset). */
void sim_context_set_preferred_visual_scale(SimContext *context, double scale);
 
/* Get preferred visual scale; returns negative when unset. */
double sim_context_preferred_visual_scale(const SimContext *context);
 
/* Set preferred visual field selection state for a given field index. */
void sim_context_set_preferred_visual_field_enabled(SimContext *context, size_t field_index,
                                                    bool enabled);
 
/* Get preferred visual field selection state for a given field index. */
bool sim_context_preferred_visual_field_enabled(const SimContext *context, size_t field_index);
 
void sim_context_special_fallback_hook(const SimContext *context,
                                       SimSpecialFallbackFn *out_fallback, void **out_userdata);
 
uint64_t sim_context_special_fault_count(const SimContext *context);
 
bool sim_context_last_special_fault(const SimContext *context, SimSpecialEvalReport *out_report);
 
void sim_context_clear_special_faults(SimContext *context);
 
SimDiagnostics *sim_context_diagnostics(SimContext *context);
const SimDiagnostics *sim_context_diagnostics_const(const SimContext *context);
 
#if SIM_DIAGNOSTICS
void sim_context_flush_special_diagnostics(SimContext *context);
#endif
 
SimResult sim_context_apply_operator(SimContext *context, struct SimOperator *op);
void sim_context_reset_continuity_counters(SimContext *context);
void sim_context_set_continuity_override(SimContext *context, bool enabled,
                                         const SimOperatorConfig *config);
 
void sim_context_field_continuity_counts(const SimContext *context, size_t field_index,
                                         uint64_t *out_dirty, uint64_t *out_stable);
 
/* Optional accessors for counts to reduce internal coupling */
size_t sim_context_operator_count(const SimContext *context);
size_t sim_context_plan_operator_count(const SimContext *context);
bool sim_context_plan_is_valid(const SimContext *context);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OAKFIELD_SIM_CONTEXT_H */