Skip to content

New API option, JAX backend, faster, more memory efficient

Choose a tag to compare

@florisvb florisvb released this 30 Sep 18:59
· 10 commits to main since this release
08923ea

Highlights

  • ObservabilityAnalysis: a new high-level API. Configure it, call run() once, then query the minimum error variance for any selection of states, sensors and time-steps without recomputing. Settings can be saved to and loaded from YAML, and save_results() writes CSV plus a YAML sidecar (and, optionally, the observability matrices as .npz).
  • JAX backend (pip install "pybounds[jax]"): JaxSimulator and JAX observability classes use exact autodiff Jacobians with vmap over windows. Supports aux, z_function, integration substeps, and an opt-in batch_size to cap memory.
  • compute_observability(): a one-call helper, with use_jax=True for the JAX backend.
  • Much lower memory and faster queries: about 5–8× lower peak memory, and min_error_variance queries up to ~90× faster. Optional Fisher-information storage (storage='fisher_per_sensor' / 'fisher') reduces memory further for long windows, and fisher_information() returns every window's F.
  • Process-based parallel sliding windows (parallel_sliding=True, simulator_factory=...).
  • Documentation on ReadTheDocs, CI, and a larger test suite.

Behavior changes

  • Python 3.10+ is required. pyyaml is a new dependency.
  • lam defaults to 1e-8 everywhere. SlidingFisherObservability previously used 1e6, which capped every error variance at 1e-6, and FisherObservability used 0. 1/λ is the ceiling on the minimum error variance.
  • Dict x0 and u are read in the simulator's name order, not key order.
  • A matrix R (DataFrame or array) is aligned with the rows of O.
  • Odd window sizes are time-stamped at the window center.
  • Threads over a shared pybounds Simulator now run sequentially with a warning, because CasADi isn't thread-safe.
  • transform_states Jacobians are relabeled. Use dxdz and dzdx_sym; the old dzdx and dxdz_sym are deprecated.
  • import pybounds no longer enables JAX float64 globally.
  • Clearer errors for unknown integrators, invalid window sizes, wrong-length x0, and a simulator passed to the wrong backend.

Fixes

  • Crashes fixed:
    • single-state systems;
    • mpc_horizon > 11;
    • FisherObservability with an array O or a single selected row;
    • from pybounds import * without JAX;
    • plain-list inputs and u={}.
  • Hang fixed: a notebook-defined simulator_factory now raises a clear error instead of hanging.
  • ObservabilityMatrixImage fixes:
    • sensor names containing _;
    • pandas 3;
    • tuple names;
    • rows sorted by sensor.
  • Compatibility with pandas 2.2+ / 3 and newer numpy; assorted docstring and label fixes.