parstudy

Parameter and variant studies for simulation models, independent of the simulation backend.

You describe each quantity to vary on its own as a ModelParameter - its name, the values to sweep, an optional default, and an optional list of model attributes it affects. Attributes a parameter affects are snapshotted at the start of the study, written for you before every serial run (verbatim, or combined with their baseline when mode="multiply" / "add"), and restored at the end - so evaluate only has to do what affects cannot. You give a Study one callable, evaluate(values), that does any remaining setup, runs the model and reduces one run to (scalars, raw). Study.run() sweeps the parameters, restores the model, and hands back a tidy MultiIndex table plus correlation / regression / Sobol / plotting helpers.

import parstudy as ps

# `affects` are written (and restored) for you; `mode="multiply"` sweeps a factor
speed = ps.ModelParameter("speed", ps.linspace(0.5, 2.0, 6), affects=[(model, "speed")])
drag = ps.ModelParameter("drag", [0.5, 1.0, 2.0], default=1.0, mode="multiply",
                         affects=[(model, "drag")])

def evaluate(values):
    raw = run(model)                       # model.speed / model.drag already set
    return {"range": raw.range, "peak": raw.peak}, raw

study = ps.Study([speed, drag], evaluate)

results = study.run(verbose=1)        # one-at-a-time: each parameter swept, others at default
results.evaluations                   # MultiIndex table: ("parameters", ...) and ("results", ...)
results.varied                        # Series: which parameter each run swept
results.correlation()                 # parameter x metric
results.regression(standardized=True) # comparable sensitivity coefficients
results.plot()                        # metric vs value, one panel per parameter
results.raw(3)                        # the full artefact of run 3

Switch the design with one argument: strategy="grid", ps.latin_hypercube(120), ps.sobol(256) (then results.sobol_indices()), or ps.from_design("design.csv"). run(raw_store="dir") streams raw results to disk and enables run(resume=True) and run(parallel=N).

Why not a for loop?

A hand-written sweep tangles parameter definitions, ranges, model mutation, running, collecting and restoring - and you rewrite it for every study. parstudy separates them: parameters are reusable objects, the pipeline is one callable, the affected model state is snapshotted and restored even on error, and the results arrive in one schema the analysis helpers understand. See the getting-started tutorial for the full argument and a worked example.

Install

pip install -e .                    # numpy + pandas only
pip install -e ".[viz]"             # + matplotlib (all plots)
pip install -e ".[sampling]"        # + scipy   (sobol strategy / indices)
pip install -e ".[parallel]"        # + joblib  (run(parallel=N))
pip install -e ".[all]"             # everything above

License

MIT, see LICENSE.