ENH: Implement Adaptive Simulation based on Convergence Criteria

[Gui-FernandesBR]

Is your feature request related to a problem? Please describe.
Currently, the user must guess the number_of_simulations (e.g., 1000 or 5000) before running the analysis.

• If the number is too low, the results are statistically insignificant.
• If the number is too high, computational time is wasted.

Users need a way to define a target precision (e.g., "I want the estimate of the Apogee to be accurate within $\pm 10$ meters") and have the simulation run exactly as many times as necessary to achieve that.

Describe the solution you'd like
Implement an automated convergence loop. Instead of specifying a fixed number of simulations, the user specifies a target variable (e.g., Apogee), a confidence level, and a tolerance width.

The MonteCarlo class should:

1. Run a small batch of simulations.
2. Calculate the Confidence Interval (CI) width for the target variable (using the bootstrapping method).
3. Check if CI_width <= tolerance.
4. If yes, stop. If no, run another batch and repeat.

Implementation Details

• Dependency: This relies on the completion of the "Bootstrapping/CI" issue.
• New Method: Introduce a method like simulate_until_convergence or extend the existing simulate method with new arguments.
• Batching: To avoid the overhead of recalculating statistics after every single flight, simulations should run in chunks (e.g., checking convergence every 50 or 100 flights).

Proposed Usage

analysis = MonteCarlo(...)

# "Run simulations until the 95% Confidence Interval 
# for Apogee is narrower than 20 meters."
analysis.simulate_convergence(
    target_variable="apogee",
    target_confidence=0.95,
    tolerance=20.0,  # The desired width of the CI
    min_simulations=100,
    max_simulations=10000, # Safety stop to prevent infinite loops
    batch_size=50
)

Acceptance Criteria

• Implement the convergence loop logic.
• Ensure a safety cap (max_simulations) prevents infinite loops if convergence is never met.
• Allow the user to define the "check frequency" or batch size.
• Log the progress (e.g., "Iteration 500: CI width is 45m... Continuing").
• Add unit tests demonstrating that the simulation stops once the tolerance is reached.

Additional Context

• Performance Note: Calculating the bootstrap CI is computationally expensive. It is crucial that this check is not performed after every single flight, but rather in batches.

[Malmahrouqi3]

@Gui-FernandesBR Interested, Please Assign!

[Malmahrouqi3]

Just to follow up on this, I was able to build on top of estimate_confidence_interval function in PR #897.
I do not believe there is any need for the lower bound.

The image showcases how CI Width per batch progressively improves albeit fluctuates a little bit. Attribute: Apogee (±30 m) & Apogee Time (±0.5 s). Batch size: 50 & 200. Implemented by expanding dispersion test in docs/notebooks/monte_carlo_analysis/monte_carlo_class_usage.ipynb

test_dispersion.simulate_convergence(
        target_attribute="apogee",
        target_confidence=0.95,
        tolerance=30.0,
        max_simulations=5000,
        batch_size=50
    )

Will PR the changes soon.