Legacy API compatibility

ergoExo and ADEPTModule remain supported and are not deprecated in this release. The compatibility façade preserves their setup, return values, MLflow lifecycle, configuration artifacts, and solver-specific post-processing while solver internals move onto the explicit architecture.

Current routing

Supported TF1D, electrostatic PIC1D, VFP2D, and Vlasov1D forward runs are prepared through SimulationSpec and the solver registry, then executed by run_prepared. The façade converts the structured result back into the historical {"solver result": diffrax.Solution} shape before invoking the existing post-processor. This routing does not change the three-value return from ergoExo.__call__. VFP2D preserves its flat saved-state dictionary, physical save times (including between-step samples), diagnostics, and artifact export. Vlasov1D preserves its named save streams, field/species diagnostics, and existing plot and netCDF export.

The façade opts into prepared execution only when preparation reproduces the legacy initial state exactly. It uses the legacy path when any compatibility-sensitive input is present, including:

  • a custom ADEPTModule;

  • explicit args or non-empty trainable modules;

  • replacement of the module state or stored arguments after setup;

  • TF1D learned trapping closures or unsupported save layouts;

  • PIC1D transverse or stochastic drivers, off-grid saves, or an initialization that differs from the legacy seeded state;

  • a solver without an explicit façade adapter, including the specialized vlasov-1d-iaw module and LPSE2D today; or

  • ergoExo.val_and_grad, which continues to call ADEPTModule.vg.

No failed prepared solve is silently rerun. Fallback decisions happen before numerical execution. After setup or a run, exo.execution_backend is either "prepared" or "legacy"; exo.compatibility_fallback_reason explains a legacy selection.

New integrations

New code should use SimulationSpec, solver_registry.prepare, and run_prepared directly. Existing applications can keep using ergoExo while solvers migrate. The next compatibility slices will add builders for the remaining solver paths before removal or deprecation of the legacy API is considered.