BUG: keep stochastic nominal values stable across reseeds

[thc1006]

119 lines of this are production code. Most of it is stochastic_model.py; the other three files get a line or two each, hooking the same recording call. The other 600 are the tests that each of the problems below cost, and a note in the user documentation. Reading the four hunks in stochastic_model.py is enough to judge the change.

Problem

_set_stochastic(seed) re-validates every declared input, and validation reads the nominal off the wrapped object. create_object writes the sampled value back onto that same object on purpose, so re-reading it on a reseed takes one simulation's output as the next one's nominal.

Four reseeds of one model, all with seed 12345, wind_velocity_x_factor=(1.0, 0.1) on a nominal 10 m/s:

develop    8.576175   7.355078   6.307843   5.409717
this PR    8.576175   8.576175   8.576175   8.576175

Each value on develop is the one before it multiplied by the same factor again. A plain scalar spec drifts the same way, since _validate_scalar and the (std, "distribution") tuple both take their centre from the object.

Invariant established by this PR

A model samples around the value the wrapped object held when that input was configured, however many times it is reseeded and whatever ran before. For the types that get copied, nothing downstream can move it: not the generated object, not last_rnd_dict, and not the next draw. A Function or a callable is held by reference and its own mutators still reach the baseline, which docs/user/stochastic.rst says.

Configured, not built, because an add_* method installs its input after __init__ and is read then. docs/user/stochastic.rst states the rule and the four cases that sit outside it: a late add_* input, a component position, an ensemble wind factor under a selected member, and anything held by reference.

Changes

• read each nominal once and keep it, instead of re-reading the wrapped object on every reseed;
• keep that value private, and hand out a copy. It reaches the model attribute, last_rnd_dict and the object create_object returns, and a write through any of those used to land on the kept one;
• copy through the built-in containers rather than stopping at the outside, since an array inside an airfoil tuple would otherwise stay shared;
• read the nominal again when a late input is configured again, and replace a pair such as x and y together or not at all. An axis the caller left out keeps everything it had, since an omitted argument and a written None arrive the same way; removing one deliberately is BUG: setting a declared eccentricity back to None leaves the old distribution in place #1171;
• give every draw its own copy of a mutable value. A list-valued input handed back the candidate itself, so on develop a whole batch of simulations shares one outline, and that outline is the deterministic fin the caller passed in:

five create_object calls, no reset in between
develop   all five share one shape_points object
          writing through the first one reaches calisto_free_form_fins itself
          the next simulation reads (9.9, 9.9) where (0.08, 0.1) was drawn
this PR   each call gets its own, the deterministic fin is untouched

A serial MonteCarlo run never resets between simulations, so this holds for the whole study rather than for adjacent pairs;

• record a draw through _record_draw, after any subclass that adjusts a value. StochasticFreeFormFins corrects a perturbed outline in dict_generator and StochasticParachute derives its pressure noise seed in create_object, both once the base class has already recorded;
• drop _declare_stochastic_input and the _MISSING sentinel, which the grouped reconfiguration left without callers;
• leave a component position uncached: it arrives through an injected getter, reads an attribute nothing writes back to, and shares the one name position across every component;
• say in docs/user/stochastic.rst where a nominal comes from, since three places there said only that it is taken from the deterministic object.

Non-goals

• no MonteCarlo API changes;
• no worker lifecycle changes;
• no append or checkpoint changes;
• no StochasticRocket component-stream changes, which are BUG: give each StochasticRocket component its own random stream #1170;
• no change to how anything is drawn, only to what it is drawn around;
• nothing outside the nominal's own lifecycle. BUG: setting a declared eccentricity back to None leaves the old distribution in place #1171 is still open: removing an earlier declaration means telling None apart from an omitted argument, both axes default to None, and a private sentinel default is a signature change rather than a bug fix. There is a regression test here holding the omitted axis in place, so nothing gets worse in the meantime.

Breaking change

Yes, for a model whose nominal was drifting. Nothing is drawn differently and no draw is added or removed, so the stream position is untouched: stochastic_calisto under seed 42 reads mass=14.906007947 on develop and the same here.

Verification

Focused first, then the suites the CI jobs run:

pytest tests/unit/stochastic/test_stochastic_model.py       36 passed
pytest tests/unit                                         2188 passed
pytest rocketpy --doctest-modules                           48 passed
pytest tests/integration                                   154 passed
pytest tests/acceptance                                     18 passed
ruff check .  /  ruff format --check .                     clean
pylint rocketpy/ tests/ docs/                           10.00/10, exit 0

The four tests/unit/test_sensitivity.py failures on this machine are a missing statsmodels, and they fail the same way on an unmodified develop.

Each mechanism is pinned by a mutation, and each mutation leaves a control standing:

undone	goes red	still passes
the nominal is not kept	seven	_snapshot_of's own test
the kept value is handed out rather than copied	the two alias tests	the drift tests
_snapshot_of copies nothing	the two container tests	the drift tests
_snapshot_of stops at a tuple	the nested-array test	the rest
the cache is keyed by seed rather than by model	the three seed-history tests	the rest
a late input is not read again when configured again	the reconfiguration test	the rest
an omitted axis joins the replacement	the two axis tests, before the reset as well as after	the rest
each input is committed as it validates, one at a time	the pair test	the rest
a list draw hands back the candidate itself	the consecutive-create_object test	the rest
last_rnd_dict points at what was built from	the record test	the rest
the outline correction happens after the record	the two free-form record tests, and the source scan	the rest
the noise seed is derived after the record	the two parachute record tests, and the source scan	the rest
the previous nominal is not restored when validation raises	the rollback test	the rest
the injected getter is ignored	test_visualize_attributes[stochastic_calisto]	the rest
the getter's result is kept under position too	the component-position test	the rest

Two of those exist because a weaker fix passes everything else. Keying the cache by seed satisfies "the same seed four times agrees" and still re-reads a moved nominal whenever the seed changes. Collapsing _snapshot_of to a shallow copy satisfies every drift test, because those use scalars.

Together with #1170

Both touch the stochastic package, and green on separate bases says nothing about the merge, so they are merged into a throwaway tree on develop and run there: pylint exit 0, ruff clean, the unit suite, doctests, integration and acceptance. The mutations that undo either change still fail their own tests in the combined tree, so neither is masking the other. stochastic_calisto under seed 42 reads mass=14.906007947 there too.

Related to #1171, which stays open. The reasoning is recorded there.

Extracted from

#1054, as the first of the split you asked for in #1054 (comment).

The idea is that branch's. The code is not: copy-on-read, the recursive snapshot and the reconfiguration path are all new here, and its older one-argument _declare_stochastic_input is deliberately left behind, since #1167 replaced it on develop with a version that keeps the value.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.62%. Comparing base (4263fa9) to head (302fc8b).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1169      +/-   ##
===========================================
+ Coverage    84.57%   84.62%   +0.04%     
===========================================
  Files          131      131              
  Lines        17527    17557      +30     
===========================================
+ Hits         14824    14857      +33     
+ Misses        2703     2700       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[thc1006]

Since this went up I found three things wrong with it and fixed them. The description above is current, so this is only the record of what moved.

The kept nominal was reachable from outside. _nominal handed back the cached object itself, and on the empty-spec path that one object was also the model attribute, the entry in last_rnd_dict, and the outline on the FreeFormFins that create_object returns. A write through any of them moved what the next reseed sampled around:

after generated.shape_points[1] = (9.9, 9.9)
kept nominal = [(0, 0), (9.9, 9.9), (0.12, 0.1), (0.12, 0)]

It copies on the way out now, so what it hands over is disposable.

_snapshot_of stopped at a tuple, which left an array inside an airfoil pair shared with the object it came from. It walks lists, tuples, sets and dicts now, and rebuilds a namedtuple through its own type rather than flattening it.

Configuring a late input twice kept the first nominal. A second add_cp_eccentricity went on sampling around the value the rocket held at the first call, 0.5 where 0.8 had been asked for. Reproducible, and around the wrong centre, which is harder to notice than a value that moves. Late configuration drops the kept value before validation reads one, and puts it back if validation raises.

Two I left alone. #1171 is the other half of the same lifecycle, where setting a declared eccentricity back to None leaves the earlier distribution in place; that is develop's behaviour rather than this branch's. And a Function nominal is still held by reference: set_source on a drag curve does move the baseline, so the boundary has a test now instead of only a line in the docs.

Head is 1f0e516f. Nothing here changes what is drawn or how many draws are made.