sim_context.h File Reference

Runtime container coordinating fields, operators, and execution. More...

#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"

Include dependency graph for sim_context.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SimContextMemoryLimits
	Memory limits enforced by the simulation context. More...
struct	SimContext
	Simulation runtime state. More...

Macros
#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)

Typedefs
typedef struct SimContextMemoryLimits	SimContextMemoryLimits
	Memory limits enforced by the simulation context.
typedef struct SimContext	SimContext
	Simulation runtime state.

Functions
void	sim_context_set_representation_mode (SimContext *context, SimRepresentationMode mode)
	Set the default representation mode for the context.
SimRepresentationMode	sim_context_representation_mode (const SimContext *context)
	Get the default representation mode for the context.
void	sim_context_set_logger (SimContext *context, void(*log_fn)(SimLogLevel level, const char *message, void *userdata), void *userdata)
	Attach a logger callback to the context (optional).
void	sim_context_log_warning (const SimContext *context, const char *fmt,...)
	Emit a warning through the context logger (or stderr fallback).
bool	sim_context_allows_determinism (const SimContext *context, SimDeterminismFlags flags)
	Return true when the current representation mode permits the given determinism flags.
bool	sim_context_kernel_allowed (const SimContext *context, uint64_t required_features, SimDeterminismFlags determinism_flags)
	Return true when a kernel-backed operator is allowed under the current policy.
bool	sim_context_kernel_allowed_mode (const SimContext *context, SimRepresentationMode mode, uint64_t required_features, SimDeterminismFlags determinism_flags)
	Return true when a kernel-backed operator is allowed under an explicit mode.
SimResult	sim_context_init (SimContext *context)
	Initialize a simulation context with default universe parameters.
SimResult	sim_context_init_with_universe (SimContext *context, const SimUniverseSpec *universe_spec)
	Initialize a simulation context with universe specification.
void	sim_context_set_seed (SimContext *context, uint64_t seed)
	Set the base seed used for deterministic RNG streams.
uint64_t	sim_context_seed (const SimContext *context)
	Get the base seed used for deterministic RNG streams.
void	sim_context_set_memory_limits (SimContext *context, const SimContextMemoryLimits *limits)
	Configure memory limits for fields and scratch allocations.
void	sim_context_get_memory_limits (const SimContext *context, SimContextMemoryLimits *out_limits)
	Fetch current memory limit settings.
void	sim_context_memory_usage (const SimContext *context, size_t *out_fields, size_t *out_scratch, size_t *out_total)
	Report current memory usage counters.
SimResult	sim_context_check_field_limits (const SimContext *context, size_t element_count, size_t field_bytes)
	Check if a field allocation would violate configured limits.
SimResult	sim_context_reserve_scratch (SimContext *context, size_t bytes)
	Reserve scratch bytes against the context counters.
void	sim_context_release_scratch (SimContext *context, size_t bytes)
	Release previously reserved scratch bytes.
void	sim_context_destroy (SimContext *context)
	Destroy a simulation context and free owned resources.
SimResult	sim_context_add_field (SimContext *context, SimField *field, size_t *out_index)
	Add a field to the context, transferring ownership.
SimField *	sim_context_field (SimContext *context, size_t index)
	Access a field by index.
size_t	sim_context_field_count (const SimContext *context)
	Returns the number of fields currently owned by the context.
SimResult	sim_context_register_operator (SimContext *context, const SimOperatorDescriptor *descriptor, size_t *out_index)
	Register a new operator within the context.
SimResult	sim_context_add_operator_dependency (SimContext *context, size_t operator_index, size_t dependency_index)
	Add an explicit dependency edge between two registered operators.
SimResult	sim_context_prepare_plan (SimContext *context)
	Ensure the execution plan is up to date.
SimResult	sim_context_execute (SimContext *context)
	Execute the operator plan sequentially.
SimResult	sim_context_execute_prepared (SimContext *context)
	Execute the current operator plan without re-running plan preparation.
SimIRBuilder *	sim_context_ir_builder (SimContext *context)
	Access the shared IR builder.
void	sim_context_set_integrator (SimContext *context, struct Integrator *integrator)
	Assigns the integrator responsible for advancing the context.
struct Integrator *	sim_context_integrator (SimContext *context)
	Retrieves the currently bound integrator.
SimResult	sim_context_set_integrator_sequence (SimContext *context, struct Integrator *const *integrators, size_t count)
	Assign an ordered sequence of integrators for opt-in multi-integrator stepping.
size_t	sim_context_integrator_sequence_count (const SimContext *context)
	Returns the number of integrators in the optional sequence.
struct Integrator *	sim_context_integrator_sequence_at (const SimContext *context, size_t index)
	Returns the integrator at index in the optional sequence.
void	sim_context_set_backend (SimContext *context, struct SimBackend *backend)
	Assigns the backend used for kernel execution.
struct SimBackend *	sim_context_backend (SimContext *context)
	Returns the active compute backend.
void	sim_context_set_timestep (SimContext *context, double dt)
	Overrides the integration timestep stored in the context.
double	sim_context_timestep (const SimContext *context)
	Queries the integration timestep currently used by the context.
void	sim_context_set_field_stats_features (SimContext *context, uint32_t feature_mask)
	Configure optional field-stat feature families.
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)
	Set the time evolution model for the simulation (continuous vs map).
void	sim_context_begin_drift (SimContext *context)
	Enter/exit drift mode to suppress side effects during derivative evaluation.
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)
	Returns the number of completed integration steps.
double	sim_context_time (const SimContext *context)
	Returns the simulation time accumulated so far (seconds).
void	sim_context_record_step_metrics (SimContext *context, double requested_dt, double accepted_dt, double rms_error)
	Capture per-step metrics (invoked by scheduler/integrators).
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)
	Capture per-step metrics with explicit wall-time attribution.
void	sim_context_accept_step (SimContext *context, double accepted_dt)
	Advance runtime counters after an accepted step.
bool	sim_context_latest_step_metrics (const SimContext *context, SimStepMetrics *out_metrics)
	Fetch the most recent step metrics sample, if available.
size_t	sim_context_step_metrics_history (const SimContext *context, SimStepMetrics *dest, size_t capacity)
	Copy a slice of the step-metrics history ordered oldest to newest.
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)
	Internal hook used by split operators to relay substep feedback.
size_t	sim_context_truncation_level (const SimContext *context)
	Get hyperexponential truncation level from universe.
double	sim_context_epsilon (const SimContext *context)
	Get epsilon parameter from universe.
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)
	Override the fallback invoked when special functions fail.
void	sim_context_set_preferred_visual_mode (SimContext *context, int mode)
int	sim_context_preferred_visual_mode (const SimContext *context)
void	sim_context_set_preferred_phase_mode (SimContext *context, int mode)
int	sim_context_preferred_phase_mode (const SimContext *context)
void	sim_context_set_preferred_visual_auto_scale (SimContext *context, int enabled)
int	sim_context_preferred_visual_auto_scale (const SimContext *context)
void	sim_context_set_preferred_visual_scale (SimContext *context, double scale)
double	sim_context_preferred_visual_scale (const SimContext *context)
void	sim_context_set_preferred_visual_field_enabled (SimContext *context, size_t field_index, bool enabled)
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)
	Retrieve the context-managed fallback hook for safe helpers.
uint64_t	sim_context_special_fault_count (const SimContext *context)
	Total number of special-function faults observed so far.
bool	sim_context_last_special_fault (const SimContext *context, SimSpecialEvalReport *out_report)
	Copy the most recent special-function fault report, if any.
void	sim_context_clear_special_faults (SimContext *context)
	Reset accumulated special-function fault statistics.
SimDiagnostics *	sim_context_diagnostics (SimContext *context)
	Access diagnostics container.
const SimDiagnostics *	sim_context_diagnostics_const (const SimContext *context)
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)
	Retrieve the dirty/stable continuity counters for a field.
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)

Detailed Description

Runtime container coordinating fields, operators, and execution.

A SimContext owns registered fields, operator descriptors, scheduler plan state, diagnostics, integrator bindings, and runtime counters. Fields added with sim_context_add_field() transfer ownership to the context; backend and integrator pointers remain caller-owned and must outlive any context step that uses them.

Macro Definition Documentation

SIM_CONTEXT_MAX_FIELD_BYTES_DEFAULT

#define SIM_CONTEXT_MAX_FIELD_BYTES_DEFAULT   (512U * 1024U * 1024U)

Default maximum bytes allowed in a single field (0 disables).

SIM_CONTEXT_MAX_FIELD_ELEMENTS_DEFAULT

#define SIM_CONTEXT_MAX_FIELD_ELEMENTS_DEFAULT   (64U * 1024U * 1024U)

Default maximum number of elements allowed in a single field (0 disables).

SIM_CONTEXT_MAX_FIELDS_DEFAULT

#define SIM_CONTEXT_MAX_FIELDS_DEFAULT   256U

Default maximum number of fields in a context (0 disables).

SIM_CONTEXT_MAX_SCRATCH_BYTES_PER_OPERATOR_DEFAULT

#define SIM_CONTEXT_MAX_SCRATCH_BYTES_PER_OPERATOR_DEFAULT   (256U * 1024U * 1024U)

Default maximum scratch bytes per operator (0 disables).

SIM_CONTEXT_MAX_TOTAL_FIELD_BYTES_DEFAULT

#define SIM_CONTEXT_MAX_TOTAL_FIELD_BYTES_DEFAULT   (2ULL * 1024ULL * 1024ULL * 1024ULL)

Default maximum total bytes across all fields in a context (0 disables).

SIM_CONTEXT_PREFERRED_VISUAL_FIELD_CAPACITY

#define SIM_CONTEXT_PREFERRED_VISUAL_FIELD_CAPACITY   256U

Number of preferred visual field selection bits retained in the context.

Typedef Documentation

SimContextMemoryLimits

typedef struct SimContextMemoryLimits SimContextMemoryLimits

Memory limits enforced by the simulation context.

Set values to 0 to disable a particular limit.

Function Documentation

sim_context_accept_step()

void sim_context_accept_step	(	SimContext *	context,
		double	accepted_dt
	)

Advance runtime counters after an accepted step.

Allows reuse across scheduler and scripting entry points.

Parameters

context	Context whose runtime counters are updated.
accepted_dt	Positive timestep accepted by the integrator.

sim_context_add_field()

SimResult sim_context_add_field	(	SimContext *	context,
		SimField *	field,
		size_t *	out_index
	)

Add a field to the context, transferring ownership.

Parameters

	context	Target context.
	field	Field instance; must be initialized. Ownership moves on success.
[out]	out_index	Optional pointer receiving the field index.

Returns

SIM_RESULT_OK on success.

sim_context_add_operator_dependency()

SimResult sim_context_add_operator_dependency	(	SimContext *	context,
		size_t	operator_index,
		size_t	dependency_index
	)

Add an explicit dependency edge between two registered operators.

Adds dependency_index to the dependency list of operator_index. Duplicate edges are ignored.

sim_context_destroy()

void sim_context_destroy

(

SimContext *

context

)

Destroy a simulation context and free owned resources.

Parameters

context

Context to destroy; may be NULL.

sim_context_execute()

SimResult sim_context_execute

(

SimContext *

context

)

Execute the operator plan sequentially.

Parameters

context

Context instance.

Returns

SIM_RESULT_OK on success; propagates operator errors.

sim_context_execute_prepared()

SimResult sim_context_execute_prepared

(

SimContext *

context

)

Execute the current operator plan without re-running plan preparation.

Callers must ensure the context plan is already valid via sim_context_prepare_plan.

sim_context_field()

SimField * sim_context_field	(	SimContext *	context,
		size_t	index
	)

Access a field by index.

Parameters

context	Context instance.
index	Field index.

Returns

Pointer to the field or NULL if out of range.

sim_context_field_count()

size_t sim_context_field_count

(

const SimContext *

context

)

Returns the number of fields currently owned by the context.

Safe to call with NULL; returns 0 in that case.

sim_context_init()

SimResult sim_context_init

(

SimContext *

context

)

Initialize a simulation context with default universe parameters.

Parameters

[out]

context

Context to initialize.

Returns

SIM_RESULT_OK on success.

sim_context_init_with_universe()

SimResult sim_context_init_with_universe	(	SimContext *	context,
		const SimUniverseSpec *	universe_spec
	)

Initialize a simulation context with universe specification.

Parameters

[out]	context	Context to initialize.
	universe_spec	Universe specification (copied into context); may be NULL for defaults.

Returns

SIM_RESULT_OK on success.

sim_context_ir_builder()

SimIRBuilder * sim_context_ir_builder

(

SimContext *

context

)

Access the shared IR builder.

Parameters

context

Context instance.

Returns

Pointer to the IR builder or NULL if context is NULL.

sim_context_latest_step_metrics()

bool sim_context_latest_step_metrics	(	const SimContext *	context,
		SimStepMetrics *	out_metrics
	)

Fetch the most recent step metrics sample, if available.

Parameters

	context	Context to inspect.
[out]	out_metrics	Receives the latest metrics sample.

Returns

true when a metrics sample was available.

sim_context_preferred_visual_mode()

int sim_context_preferred_visual_mode

(

const SimContext *

context

)

Get preferred GUI visual mode; returns negative when unset.

sim_context_prepare_plan()

SimResult sim_context_prepare_plan

(

SimContext *

context

)

Ensure the execution plan is up to date.

Parameters

context

Context instance.

Returns

SIM_RESULT_OK on success.

sim_context_profiler_counters()

bool sim_context_profiler_counters	(	SimContext *	context,
		SimProfilerCounter *	out_counters,
		size_t	capacity,
		size_t *	out_count
	)

Retrieve profiler counters for the direct-execution profiler (non-scheduler).

sim_context_profiler_snapshot()

bool sim_context_profiler_snapshot	(	SimContext *	context,
		SimProfilerSnapshot *	out_snapshot
	)

Snapshot the direct-execution profiler (non-scheduler).

sim_context_register_operator()

SimResult sim_context_register_operator	(	SimContext *	context,
		const SimOperatorDescriptor *	descriptor,
		size_t *	out_index
	)

Register a new operator within the context.

Parameters

	context	Context instance.
	descriptor	Operator descriptor.
[out]	out_index	Optional pointer receiving the assigned index.

Returns

SIM_RESULT_OK on success.

sim_context_set_integrator()

void sim_context_set_integrator	(	SimContext *	context,
		struct Integrator *	integrator
	)

Assigns the integrator responsible for advancing the context.

Ownership remains with the caller; the context only stores the pointer.

sim_context_set_integrator_sequence()

SimResult sim_context_set_integrator_sequence	(	SimContext *	context,
		struct Integrator *const *	integrators,
		size_t	count
	)

Assign an ordered sequence of integrators for opt-in multi-integrator stepping.

Passing count = 0 clears the sequence and detaches the active integrator.

sim_context_set_preferred_visual_mode()

void sim_context_set_preferred_visual_mode	(	SimContext *	context,
		int	mode
	)

Set preferred GUI visual mode on the context (negative = unset).

sim_context_set_time_model()

void sim_context_set_time_model	(	SimContext *	context,
		SimTimeModel	model
	)

Set the time evolution model for the simulation (continuous vs map).

Changing after steps have executed will emit a warning but still apply.

sim_context_step_metrics_history()

size_t sim_context_step_metrics_history	(	const SimContext *	context,
		SimStepMetrics *	dest,
		size_t	capacity
	)

Copy a slice of the step-metrics history ordered oldest to newest.

Parameters

	context	Context to inspect.
[out]	dest	Destination array for copied samples.
	capacity	Number of entries available in dest.

Returns

Number of samples written.

sim_context_truncation_level()

size_t sim_context_truncation_level

(

const SimContext *

context

)

Get hyperexponential truncation level from universe.

Parameters

context

Context instance.

Returns

K parameter; returns 0 if context is NULL.