run_cohort: Run a cohort of entities (serial or parallel) with optional...

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

Run a cohort of entities (serial or parallel) with optional global parameter draws

Description

These helpers support batch simulation with: global parameter draws reused across entities (parameter uncertainty) multiple stochastic sims per entity per draw (stochastic uncertainty) parallelization across entities

Usage

run_cohort(
  engine,
  entities,
  n_param_draws = 1,
  n_sims = 1,
  param_draws = NULL,
  runtime = NULL,
  max_events = 1000,
  max_time = NULL,
  return_observations = TRUE,
  backend = NULL,
  n_workers = NULL,
  seed = NULL
)

Arguments

engine	An Engine object (with a materialized bundle).
entities	List of Entity objects.
n_param_draws	Integer; number of global parameter draws (D). Default 1.
n_sims	Integer; number of stochastic sims per entity per draw (S). Default 1.
param_draws	Optional list of exactly n_param_draws ParamContext objects. Draw ids are stable identities: they must be positive and unique, need not be contiguous, and determine canonical cohort order. Bare parameter payload lists are not accepted. If NULL, the function calls engine$bundle$sample_params(D) when available; otherwise it constructs contexts numbered 1:D from bundle$params or an empty parameter list.
runtime	Optional RuntimeContext; carries seed, backend, and n_workers for v2-mode engines. Takes precedence over the individual seed, backend, and n_workers arguments when non-NULL. Its replicate_id must be NULL; cohort replicates are represented by sim_id. An explicit runtime with seed = NULL requests an unseeded cohort even when the Engine stores a seed.
max_events	Max events per run.
max_time	Optional max time per run.
return_observations	Logical; whether to return observations (if bundle provides observe()).
backend	Backend used to parallelize across entities. One of "none", "cluster", "mclapply", or "future". When NULL, inherits the Engine's stored runtime backend when available, then defaults to "none". Ignored when runtime is supplied.
n_workers	Integer; workers for parallel; default parallel::detectCores() - 1. When NULL, inherits the Engine's stored runtime setting when available. Ignored when runtime is supplied.
seed	Optional base seed for reproducibility. Public contract: fixed seed + draw_id + sim_id + entity_id = reproducible output. A non-NULL value overrides the Engine's stored runtime seed. Ignored when runtime is supplied.

Value

A list with: runs: list of per-run outputs (entity/events/observations; plus trajectory_records when enabled) with labels index: data.frame mapping run_id -> entity_id/param_draw_id/sim_id param_draws: the validated contexts in ascending draw-id order

The index run_id is a batch-local join key shared by the corresponding run, its SimContext, and its trajectory records. For replay across cohort calls, use the stable entity/draw/simulation coordinates rather than assuming that a sequential run_id will remain unchanged when the cohort shape changes.

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