[schaubh]

• Review: By commit
• Merge strategy: Merge (no squash)

Description

Adds support for standard CPython 3.15 while retaining Python 3.9–3.14, and ensures source builds enforce the supported Python range. Profiling with Python 3.15’s Tachyon sampling profiler also identified startup and Monte Carlo overhead addressed in this PR.

Changes are organized into nine commits:

1. Ignore local virtual-environment directories beginning with .venv.
2. Add shared Python-version validation based on project.requires-python. The build script rejects unsupported interpreters before cleanup or generation; CMake validates its selected interpreter.
3. Extend support to >=3.9, <3.16, with Python-specific NumPy and Numba requirements that preserve dependency choices for older interpreters. Update the associated regression tests.
4. Update cibuildwheel and existing CI version targets for Python 3.15. Retain the Python 3.9 build and older wheel selectors, without adding CI jobs or test matrices.
5. Update installation documentation and release notes.
6. Defer support-data GitHub tag checks until remote data is needed, avoiding unnecessary network requests during import and local-data use.
7. Lazily import Matplotlib in SimulationBaseClass on Python 3.15. Python 3.9–3.14 retain their existing eager-import behavior.
8. Remove the redundant one-second delay after each Monte Carlo run queues retained data. Completion still waits for the writer to finish.
9. Reuse Monte Carlo worker pools across batches, with configurable worker recycling and a bounded retention queue. Add writer-failure detection and cleanup, preserve failed-index reporting, and handle NumPy initial-condition indices.

Monte Carlo workers recycle after eight simulations by default. setMaxTasksPerChild() controls recycling, and setRetentionQueueSize() controls queue capacity, which defaults to twice the active worker count. Writer failures raise RuntimeError; simulation, preparation, and submission failures are reported through failed indices. The one-worker setting continues to execute in the calling process.

Python 3.9’s existing deprecation warning remains unchanged. Free-threaded Python support is outside this PR.

Verification

Local compatibility validation completed:

• Successful macOS build using Python 3.15.2, with opNav, MuJoCo, Rust modules, and strict compiler warnings enabled.
• 809 native CTest tests passed.
• 72 runtime tests passed, covering Numba modules, messaging, build information, the basic-orbit example, and the Rust module template.
• 86 build/configuration tests passed on Python 3.15, and 52 passed on Python 3.14.
• Python 3.9 and 3.14 successfully imported the Python 3.15-built native modules and completed messaging and spacecraft-construction smoke tests.
• Build and development dependency resolution succeeded for Python 3.9–3.15 across all four CI platform targets.
• Editable installation, dependency consistency, workflow YAML, documentation snippets, and commit hooks were validated.

Additional validation for the profiling-driven changes:

• The existing 87 SimulationBaseClass tests passed on Python 3.9–3.15. The final compact subprocess test also passed on all seven versions, checking import behavior and first-use plotting.
• All 68 Monte Carlo tests passed on Python 3.9, 3.14, and 3.15, including pool reuse, recycling, bounded queues, writer failures, interruption, task-preparation/submission failures, initial-condition reruns, and NumPy case arrays.
• Both reaction-wheel Monte Carlo example paths passed: normal execution and saved initial conditions.
• Benchmark validation covered 46 campaigns and 1,616 simulations. Retained arrays and dispersed parameters matched the references, and 299 combined dataframes were checked.
• Campaigns of up to 512 simulations with four workers verified the configured eight-run recycling limit and showed no accumulating simulation wrappers in the tested workloads.

Representative local performance measurements:

Workload	Before	After
Import SimulationBaseClass	266 ms	37 ms
Basic-orbit Monte Carlo: 32 runs, two workers	22.30 s	4.04 s
Reaction-wheel Monte Carlo: 32 runs, two workers	25.94 s	4.37 s

Measurements used macOS ARM64 and Python 3.15.2 with the JIT disabled. Import results are medians from 12 paired fresh-process trials. Monte Carlo results are medians of three trials, comparing pool reuse against per-batch pool creation after removal of the fixed sleep; timings include process startup, retention, and shutdown, but exclude parent imports and plotting. These short workloads benefit strongly from reduced startup overhead.

The CPython JIT was also evaluated with basic-orbit, native-controller, Python-controller, and Numba scenarios. It provided no useful improvement in these local measurements, so this PR does not enable it.

Full PI and cross-platform CI checks should validate the final revision, including the Monte Carlo enhancements.

Documentation

Updated:

• Linux, macOS, and Windows installation guides to list Python 3.9–3.15 support.
• Build instructions to explain Python-version validation and unsupported-version errors.
• Support-data documentation to explain deferred remote tag checks.
• Monte Carlo documentation covering worker recycling, queue capacity, failure handling, and incomplete archives.
• Release-note snippets for Python compatibility, deferred support-data checks, lazy Matplotlib imports, and Monte Carlo improvements.
• Known-issue snippets for unsupported-version builds, support-data tag checks, and Monte Carlo writer failures.

Future work

Continue profiling longer and more computationally intensive workloads to assess how these improvements scale. Scenario plotting and post-processing remain candidates for separate optimization.

Evaluate portable native-profiling build options, including explicit frame-pointer settings, before changing optimized-build defaults. Further JIT or free-threaded work should remain separate and be guided by measured benefits and compatibility requirements.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T01:46:59.359999Z	19d6e7b	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.