load_model: Assemble and validate a simulation model (v2 API)

In fluxCore: Probabilistic Simulation of Single-Entity Systems in Irregular Time

Assemble and validate a simulation model (v2 API)

Description

load_model() is the recommended entry point for the v2 architecture. It validates all supplied components against the schema and against each other, applies defaults, and returns a configured Engine in v2 mode.

Usage

load_model(
  schema,
  bundle,
  policy = NULL,
  environment = NULL,
  trajectory = NULL,
  runtime = NULL,
  param_source = NULL
)

Arguments

schema	A validated full schema list (from set_schema() or equivalent) containing at minimum ⁠$variables⁠ and a ⁠$time_spec⁠ of class "time_spec". For 2.1 compatibility, a variables-only named list is also accepted with a migration warning. A full schema may contain canonical leaf declarations in ⁠$decision_points⁠ and grouped references in ⁠$decision_groups⁠. See set_schema().
bundle	A ModelBundle list with at minimum propose_events, transition, and stop callbacks, plus a ⁠$time_spec⁠ semantically equal to the full schema declaration.
policy	Optional for ordinary decisions. A function or list with a propose_action method called at ordinary decision points. A schema with non-empty decision_groups requires a list with an exact propose_plan callback as documented below; there is no implicit ordinary-policy fallback.
environment	Optional. An EnvironmentContext for ABM/RL scenarios.
trajectory	Optional. A TrajectoryLogger configuration list; enables TrajectoryRecord emission. Requires schema$decision_points to be non-empty.
runtime	Optional. A RuntimeContext specifying reproducibility and backend settings. Defaults are applied when NULL.
param_source	Optional. A ParamSource that resolves ParamContexts once per run.

Details

Engines returned by load_model() enforce the following at runtime:

• Fail fast on ctx-style usage: passing a ⁠ctx=⁠ argument to Engine$run() raises an immediate error. Use typed context objects (SimContext, ParamContext, RuntimeContext) instead.

• Bundle callbacks that need typed context declare supported sim_ctx and param_ctx formals. The removed v1.x-style ctx formal is rejected.

Value

An Engine object with v2_mode = TRUE.

Model time contract

A full schema and its ModelBundle must declare semantically equal time_spec objects. Equality covers unit, origin instant, origin class, and zone; object identity is not required. Engine⁠$time_spec⁠ is the sole assembled runtime clock and is propagated through SimContext.

For 2.1 compatibility, a variables-only schema (a named list of variable definitions without the full ⁠$variables⁠ wrapper) is accepted with a migration warning and uses bundle$time_spec. A full schema, identified by the presence of a ⁠$variables⁠ field, must also contain ⁠$time_spec⁠.

Decision declaration contract

Leaf DecisionPoint() objects remain in schema$decision_points. Shared trigger declarations live separately in schema$decision_groups and reference leaf ids rather than embedding leaf definitions. load_model() defensively repeats the global id, membership, no-nesting, and group-only trigger checks performed by set_schema() so manually assembled schemas do not bypass the declaration contract. When at least one group is declared, policy must be a list exposing propose_plan(); grouped dispatch never falls back implicitly to propose_action().

For each fired group with at least one eligible member, Core makes exactly one call of the following shape:

policy$propose_plan(
  grouped_decision_point,
  eligible_decision_points,
  entity,
  sim_ctx = NULL,
  param_ctx = NULL
)

The first three named inputs are required. Core supplies sim_ctx and param_ctx only when the callback declares those formals. The eligible decision points are canonical schema objects in group member order, evaluated after the triggering transition; when none are eligible, Core skips the callback. The result must be a complete DecisionPlan() rather than NULL.

User experience tiers

Level	Entry point	What you supply
1	load_model(schema, bundle)	In-memory schema + bundle
2	load_model(schema, bundle, ...) + JSON schema export	JSON spec + language code
3	All optional components supplied	Full stack

Trajectory output contract

When trajectory is configured, the Engine returned by load_model() emits trajectory_records in run outputs.

• Engine$run(...) includes trajectory_records when trajectory logging is enabled.

• run_cohort(...) run entries include per-run trajectory_records when enabled.

• trajectory_records is a list of plain named lists (JSON-serializable).

• trajectory$detail controls state capture:

  • none: state_before and state_after are NULL.

  • summary: both are outputs of summary_fn (default state_summary_default()).

  • full: both are full snapshots of entity$current.

See Also

SimContext(), ParamContext(), RuntimeContext(), EnvironmentContext(), DecisionPoint(), GroupedDecisionPoint(), DecisionPlan(), TrajectoryRecord()

fluxCore documentation built on Sept. 22, 2026, 5:07 p.m.