Engine: Engine

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

Engine

Description

Orchestrates simulation by repeatedly proposing the next event(s), applying a transition patch, recording the event on a Entity, and stopping when bundle$stop() returns TRUE (or a max_time / max_events limit is reached).

Run result

Engine$run() returns a list containing the updated entity, its events, optional observations, and stopped_by. The termination value is one of "stop", "max_time", "max_events", or "no_proposals". When trajectory logging is configured, the result also contains trajectory_records.

Direct Engine$run() calls construct one ParamContext from bundle$params, or an empty parameter list, unless a Core cohort harness supplies a prevalidated context. Engine$run_draw() remains a raw parameter payload entry point. Its caller owns RNG setup, so a RuntimeContext stored on the Engine does not reseed the internal draw run.

Grouped decision dispatch

For an Engine assembled with schema$decision_groups, raw direct/group overlap is rejected before transition. After the event transition is applied once, Core freezes ordinary eligibility followed by grouped-member eligibility. Conditions are evaluated in ordinary schema order, then group declaration and member order, before any policy call. Core dispatches ordinary policies first and then each fired group in declaration order. A non-empty eligible group receives exactly one policy$propose_plan() call; an empty eligible group skips policy.

A grouped DecisionPlan() must name every and only eligible member and is validated completely, including every pending-slot outcome, before one group-level commit. This atomic boundary coordinates action selection and staging only; constituent actions later arbitrate and realize independently. Ordinary decisions and separate groups are independent local boundaries, not one event-wide transaction.

Grouped trajectory records

With trajectory logging enabled, a grouped activation emits ordinary-style leaf rows, not a synthetic parent row. Every eligible member gets a row, including an explicit NULL selection; an ineligible member gets a veto row only when its leaf declares audit = TRUE. All rows from one firing share grouped_decision_point_id and a deterministic run-local group_activation_id. A zero-eligible firing still advances activation identity and emits its opted-in veto rows, but has no policy call or plan metadata. Plan metadata remains opaque and is retained only in raw records.

Failure and partial progress

Ambiguous raw activation is rejected before transition. Otherwise the triggering transition and atomic Entity update occur before decision conditions and policies. A condition, policy, or plan error therefore stops the run without rolling back that triggering event. A failing action handler stops before its action event or state effect is committed. Ordinary work and each accepted group are independent local boundaries, so a later group error does not roll back an earlier policy call, diagnostic, or pending-slot commit.

Methods

Public methods

• Engine$new()

• Engine$run()

• Engine$run_draw()

• Engine$clone()

---

Engine$new()

Usage

Engine$new(bundle = NULL, ...)

---

Engine$run()

Usage

Engine$run(
  entity,
  max_events = 1000,
  max_time = NULL,
  return_observations = TRUE,
  .internal_ctx = NULL
)

---

Engine$run_draw()

Usage

Engine$run_draw(
  entity,
  params = list(),
  draw_id = 1L,
  sim_id = 1L,
  max_events = 1000,
  max_time = NULL,
  return_observations = TRUE
)

---

Engine$clone()

The objects of this class are cloneable with this method.

Usage

Engine$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

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