shell.parameter_study

shell.parameter_study(
    base,
    params,
    probe=None,
    *,
    mode='grid',
    warm_start=True,
    keep_solutions=True,
    on_fail='raise',
    progress=False,
    **solve_kw,
)

Solve the mean flow over a grid of parameter values, warm-started point to point.

Each point solves base.with_params({address: value, ...}) – a fresh copy, so the base stays pristine and no state accumulates across points. Because parameter writes never touch topology, the previous point’s converged state is a valid warm start and is chained through solve(x0=prev.x) (points march last-address-fastest, so neighbouring solves differ in one value).

Parameters

Name Type Description Default
base Network The pristine base network (never mutated). required
params dict {address: values} – each key a dotted parameter address (see :meth:Network.parameters), each value a 1-D sequence to sweep. required
probe callable probe(solution) -> {name: scalar} evaluated at every converged point; the outputs are collected into grid-shaped arrays (:attr:StudyResult.probes). None
mode (grid, zip) "grid" (default) sweeps the outer product of the value lists (N-D grid); "zip" aligns equal-length lists into a single 1-D path. "grid"
warm_start bool Chain each solve from the previous converged state (default True). True
keep_solutions bool Retain every point’s :class:~nefes.shell.network.Solution (default True); set False on large sweeps to save memory (probes are still collected). True
on_fail ('raise', 'continue') What to do when a point fails to converge: "raise" (default) stops with a pointed error; "continue" records converged=False (probes NaN) and marches on, warm-starting from the last converged state. "raise"
progress bool Print a one-line status per point as it solves (default False): the point index, its swept address values, and whether it converged, in how many iterations, and its residual norm. A lightweight progress readout for long sweeps; leaves the returned :class:StudyResult unchanged. False
**solve_kw Forwarded to :meth:Network.solve at every point (e.g. tol, verbose). {}

Returns

Name Type Description
StudyResult

Examples

A 1-D operating-line sweep with a scalar probe:

>>> res = parameter_study(base, {"inlet.mdot": np.linspace(0.3, 0.7, 20)},
...                       probe=lambda sol: {"p_drop": sol.field("p")[0] - sol.field("p")[-1]})

A 2-D grid over a composite knob and a boundary value:

>>> res = parameter_study(base, {"orifice.throat_area": areas, "outlet.p": pressures})
>>> res.probes["p_drop"].shape == (len(areas), len(pressures))

See Also

Network.with_params : the functional single-point idiom this driver chains. Network.builder : the build(p) closure for eigenvalue/Nyquist continuation. nefes.perturbation.stability.trajectory.eigenvalue_trajectory : modal continuation.

Back to top