ENH: continue a Monte Carlo study from the root its rows were drawn with

CHANGELOG.md

@@ -32,6 +32,7 @@ Attention: The newest changes should be on top -->
 
 ### Added
 
+- ENH: Reproducible Monte Carlo seeding, and an append that continues the same study [#1187](https://github.com/RocketPy-Team/RocketPy/pull/1187) [#1053](https://github.com/RocketPy-Team/RocketPy/issues/1053) [#1075](https://github.com/RocketPy-Team/RocketPy/issues/1075)
 - ENH: 3-DOF single rail button flight phase (tip-off analysis), enabled with the opt-in `Flight(use_udot_rail2=True)`. Between the upper rail button leaving the rail and the lower one following it, the rocket pivots about the lower button under a solved constraint wrench instead of jumping straight to free 6-DOF flight. The window is reported as `between_rails_time`, `between_rails_velocity` and `tip_off_duration`, printed by `Flight.info()` and shaded in the attitude plots. Requires `simulation_mode="6 DOF"` and `equations_of_motion="standard"`. [#920](https://github.com/RocketPy-Team/RocketPy/pull/920)
 - ENH: Support fixed-time parachute deployment triggers [#1133](https://github.com/RocketPy-Team/RocketPy/pull/1133) [#437](https://github.com/RocketPy-Team/RocketPy/issues/437)
 - DOC: Add SIL parachute ejection integration example [#1131](https://github.com/RocketPy-Team/RocketPy/pull/1131) [#524](https://github.com/RocketPy-Team/RocketPy/issues/524)
@@ -51,6 +52,7 @@ Attention: The newest changes should be on top -->
 
 ### Changed
 
+- ENH: Number the simulations of a serial Monte Carlo run from zero, as the parallel path already did — the two used to name the same simulation `1, 2, 3` and `0, 1, 2`. The `index` field written into the inputs and outputs rows shifts by one for serial runs, so code reading indices off those files has to expect a run of `n` simulations to be numbered `0` to `n - 1`. An append onto a study written before this release is refused rather than continued, since its rows do not record which root drew them. [#1187](https://github.com/RocketPy-Team/RocketPy/pull/1187)
 - MNT: Store the reference-area correction factor on each rocket aero surface component, so it is carried with the surface instead of being recomputed at every lift evaluation. `Rocket.aerodynamic_surfaces`, `rail_buttons` and `sensors` now yield `(component, position, ref_factor)`, so code that unpacks a pair from them (`for surface, position in rocket.aerodynamic_surfaces`) has to take the third field or absorb it. Simulation results are unchanged, and `.rpy` files written before this still load. [#1129](https://github.com/RocketPy-Team/RocketPy/pull/1129) [#561](https://github.com/RocketPy-Team/RocketPy/issues/561)
 - ENH: Compute the rocket static margin lazily [#1135](https://github.com/RocketPy-Team/RocketPy/pull/1135) [#780](https://github.com/RocketPy-Team/RocketPy/issues/780)
 - DOC: Tighten the comments that came with the sampler seed groups [#1154](https://github.com/RocketPy-Team/RocketPy/pull/1154)

docs/notebooks/monte_carlo_analysis/monte_carlo_class_usage.ipynb

@@ -772,7 +772,9 @@
     "Finally, let's simulate our flights. \n",
     "We can run the simulations using the method `MonteCarlo.simulate()`.\n",
     "\n",
-    "Set `append=False` to overwrite the previous results, or `append=True` to add the new results to the previous ones.\n"
+    "Set `append=False` to overwrite the previous results, or `append=True` to add the new results to the previous ones.\n",
+    "\n",
+    "The rows a run writes are numbered from zero, serially and in parallel alike. An append carries on the study already in the file. Every input row records the seed root it was drawn from, so the seed does not have to be given again, and one that disagrees with the rows is refused rather than mixed in. A log written before this behaviour existed carries no root, so an append onto one is refused too: run the study again to write a log that can be continued.\n"
    ]
   },
   {

docs/user/stochastic.rst

@@ -341,6 +341,25 @@ draws under a fixed seed. The rocket's own inputs, such as ``mass`` and
     one model. Sharing one between two components leaves each of them seeding it
     from their own child, and the last one to be reset decides what both draw.
 
+.. note::
+    A whole run is fixed by ``MonteCarlo.simulate(random_seed=...)`` rather than
+    by seeding these models yourself. Each simulation takes its seed from its own
+    index, so simulation 7 draws the same inputs whether the run was serial or
+    split over any number of workers, and whether it was reached first or last.
+    A run of ``n`` simulations numbers them 0 to ``n - 1`` either way, which is
+    what makes one index name one simulation.
+    Every input row records the root it came from, so appending carries that
+    study on whether or not the seed is given again, and a different one is
+    refused rather than mixed in. Without a seed a run draws fresh entropy and
+    reproduces nothing.
+
+    An index fixes the draw, not the object it is drawn around. Where the note
+    above says a value follows its deterministic object, moving that object
+    between runs still moves what is sampled, however the seed was set. A
+    ``CustomSampler`` that draws from the process-global ``numpy.random``
+    rather than from the generator it is handed sits outside all of this, as
+    :ref:`custom_sampler` warns.
+
 Conclusion
 ----------