run_psa

run.run_psa(
    model,
    draws,
    *,
    seed=None,
    collect=None,
    n_jobs=-1,
    sequential=False,
    batch_size=None,
    progress=None,
)

Evaluate a model over the parameter draw matrix, preserving its index.

This is the single execution point. It owns every execution concern: it builds the per-iteration random streams from seed and hands them to a stochastic engine, runs the batches in parallel, gathers any collect log, and returns a RunResult. Engines themselves hold no seed and no side channel, so the same model object reruns under a new seed without reconstruction.

The draw matrix’s index is the canonical iteration index: the outcomes carry exactly that index, keeping the parameter/outcome linkage intact for value-of-information analysis.

The run is parallel by default. Because each iteration draws a stream keyed by its index, the numbers, and any collected log, are identical whether the run is parallel or sequential, and whatever the batch size; splitting only changes how work is dispatched, not the result.

Parameters

Name	Type	Description	Default
model	ModelEngine | ModelFn	A ModelEngine or a callable draws -> Outcomes.	required
draws	pd.DataFrame	Parameter draw matrix (rows = iterations), e.g. from heormodel.params.ParameterSet.sample.	required
seed	int | None	Root seed for the per-iteration streams a stochastic engine uses. None (default) draws fresh entropy; pass an integer for a reproducible run. Ignored by deterministic engines.	None
collect	str | None	None (default) returns outcomes only. "events" also gathers the state-change or resource history, and "individuals" the per-individual accruals, into the RunResult. Only a stochastic engine produces these; asking a deterministic model for them raises.	None
n_jobs	int	joblib worker count; -1 (default) uses all cores.	-1
sequential	bool	Run in-process on one worker, the readable off switch for debugging and reproducibility checks. Forces sequential whatever n_jobs says. The run also falls back to sequential when there is one iteration or one available core.	False
batch_size	int | None	Rows per experiment (default: split evenly across workers, four batches per worker). One experiment is one unit of work the loop dispatches, and the progress readout counts these.	None
progress	bool | None	Show a completed-count and time-remaining readout on stderr as experiments finish. None (default) shows it when stderr is a terminal and stays quiet otherwise, so CI logs and docs builds are silent; True forces it on, False off. The remaining-time estimate uses only finished experiments, so early estimates are noisy and sharpen over the run.	None

Returns

Name	Type	Description
	RunResult	A RunResult whose outcomes iteration index equals draws.index.

Example

import pandas as pd from heormodel.params import Normal, ParameterSet from heormodel.models import Outcomes from heormodel.run import run_psa def model(d: pd.DataFrame) -> Outcomes: … costs = pd.DataFrame({“A”: d[“c”], “B”: d[“c”] + 10}) … effects = pd.DataFrame({“A”: d[“c”] * 0, “B”: d[“c”] * 0 + 0.1}) … return Outcomes.from_wide(costs, effects) draws = ParameterSet({“c”: Normal(100, 5)}).sample(50, seed=1) run_psa(model, draws, sequential=True).outcomes.n_iterations 50