Introduce opt-in scientific core (massive_core) with numerics, diagnostics, EnKF, steppers and engine integration

[Adlgr87]

Motivation

• Provide an opt-in scientific extension layer that adds stable numerical steppers, diagnostics, data-assimilation and physics-inspired helpers without changing legacy simulator behavior.
• Allow engines to optionally use tested numerical steppers (e.g. euler_maruyama, adaptive) while preserving the historical execution path by default.
• Make it easy to produce reproducible scientific reports and benchmarks and to prepare CfC training data from legacy histories.

Description

• Add a new massive_core package that exposes ScientificRuntimeConfig, scientific runners (run_scientific_simulation, run_energy_scientific_simulation, run_multilayer_scientific_simulation), diagnostics (build_scientific_report, ScientificReport), data-assimilation (EnsembleKalmanFilter, assimilation workflow), metalearning adapters (CfC dataset builders and MetaRegimeSelector) and canonical benchmarks.
• Implement a numerical subsystem under massive_core.numerics including solvers (adaptive solver), steppers (EulerMaruyamaStepper, AdaptiveStepper, create_stepper) and stability diagnostics, and wire them into energy_engine.py and multilayer_engine.py via an opt-in scientific_config that selects a stepper.
• Add physics and analysis modules under massive_core.physics, massive_core.dynamical_systems, massive_core.network_inference, and massive_core.multiscale to support entropy/free-energy, bifurcation detection, network reconstruction, multiscale engines and hydrodynamic/perturbation helpers.
• Provide massive_core.__getattr__ lazy-loading to preserve legacy exports (e.g. simular, resumen_historial) while promoting the new import surface.
• Update app.py to optionally inject a raw analytics snippet via the new MASSIVE_ANALYTICS_SNIPPET environment variable and add the variable to .env.example.
• Expand documentation and examples (README.md, new docs/*, math_physics_extension_plan_ES.md) and update mkdocs.yml and requirements.txt to include docs theme; add .gitignore entry for site/.
• Add a comprehensive test suite under tests/ covering data-assimilation workflows, diagnostics, numerics, engine integration and benchmarks.

Testing

• Ran the unit/integration test suite with python -m pytest tests/ and all tests in tests/ completed successfully.
• Exercised engine-level integration tests test_scientific_integration.py to verify create_stepper('euler_maruyama') reproduces legacy deterministic paths and that numeric diagnostics are produced.
• Executed diagnostics/assimilation tests (test_scientific_report.py, test_data_assimilation_workflow.py) and benchmark/metalearning tests (test_scientific_benchmarks_and_cfc_data.py) which all passed.

---

Codex Task

---

Summary by cubic

Introduces an opt-in scientific core massive_core with numerics, diagnostics, EnKF, steppers, benchmarks, and high-level scientific runners. Engines keep legacy behavior by default; enabling scientific_config activates stable steppers and scientific reports.

• New Features

  • massive_core: scientific runners (run_scientific_simulation, run_energy_scientific_simulation, run_multilayer_scientific_simulation) and ScientificRuntimeConfig.
  • Numerics: adaptive solver, EulerMaruyama/Adaptive steppers, stability diagnostics; create_stepper integrated into energy/multilayer engines.
  • Diagnostics: build_scientific_report, ScientificReport, canonical benchmarks.
  • Data assimilation: EnsembleKalmanFilter, assimilate_history_observations; CfC dataset builders and MetaRegimeSelector.
  • Physics/analysis modules: dynamical systems, network inference, multiscale, statistical mechanics, hydrodynamics, perturbation theory, and a PINN baseline.
  • Optional analytics via MASSIVE_ANALYTICS_SNIPPET; expanded docs and a full test suite.

• Migration

  • No changes needed to keep current behavior.
  • To enable: pass scientific_config={"solver": "euler_maruyama" | "adaptive", "enable_scientific_report": true} to engines or use the scientific runners.
  • To inject analytics, set MASSIVE_ANALYTICS_SNIPPET in the environment.
  • If building docs locally, ensure mkdocs-material is installed.

^{Written for commit e2aebaa. Summary will update on new commits.}