Mici

<!-- Release notes generated using configuration in .github/release.yml at main -->

What's Changed
🚨 Breaking changes
* System classes now define a `backend` argument which defaults to `None` specifying automatic differentiation backend to use if derivative functions not directly provided (with `None` default raising an error if derivative functions are not specified). Previous behaviour which was to fallback to using Autograd can be restored by passing `backend="autograd"` to system class initialiser.
✨ New features
* Add support for alternative automatic differentiation backends by matt-graham in https://github.com/matt-graham/mici/pull/11
* Make progress bars display in pyodide based interactive shells by matt-graham in https://github.com/matt-graham/mici/pull/18
📦 Dependency updates
* Python 3.9 support dropped
* Bump actions/setup-python from 4 to 5 by dependabot in https://github.com/matt-graham/mici/pull/14
* Bump actions/checkout from 3 to 4 by dependabot in https://github.com/matt-graham/mici/pull/17
* Bump peaceiris/actions-gh-pages from 3 to 4 by dependabot in https://github.com/matt-graham/mici/pull/15
* Bump actions/cache from 3 to 4 by dependabot in https://github.com/matt-graham/mici/pull/16

**Full Changelog**: https://github.com/matt-graham/mici/compare/v0.2.1...v0.3.0

Minor release.

Bug fixes:
* Fixed bug in handling of `NaN` Hamiltonian values when computing Metropolis accept probability due to `min(0, float("nan"))` evaluating to 0.
* Fixed CSS styling of progress bar HTML representation to avoid overflow in container `div` element causing horizontal scrollbars to appear.
* Fixed bug causing sampling stage progress bar to still be displayed when calling `sample_chains` method with argument `display_progress=False`.

Packaging changes
* Excluded `docs` and `images` folders from `sdist` builds to minimize download size.

Major release.

Dependency changes

* Dropped support for Python 3.6, 3.7 and 3.8.
* Minimum NumPy version changed to 1.22 per NEP 29.

API changes

* Interface to sampler classes simplified to remove previous `sample_chain` and `sample_chains_with_adaptive_warm_up` methods in favour of combining all functions into a single `sample_chains` method, which now requires arguments to be passed specifying both number of warm-up iterations (`n_warm_up_iter`, can be zero) and number of main iterations (`n_main_iter`). All arguments to `sample_chain` other than `n_warm_up_iter`, `n_main_iter` and `init_states` are now keyword only.
* `metric` and optional arguments specifying derivatives (for example `grad_neg_log_dens` and `jacob_constr`) to system classes are now all keyword only.
* `sample_chains` methods now return named tuples with entries `final_states`, `traces` and `statistics`.
* `memmap_enabled` keyword argument to `sample_chains` removed and replaced with `force_memmap` argument, with adjusted semantics that memory mapping is now always enabled when sampling chain in parallel on multiple processes, with `force_memmap` allowing memory mapping to also be used when sampling a chain or chains on a single process.

Bug fixes

* Bug due to `mici.transitions.Transition.statistic_types` being shared across subclasses as a mutable set fixed.
* Accept probabilities now computed using `exp(min(.))` rather than `min(exp(.))` to improve numerical stability.
* `reverse_norm` argument to `ConstrainedLeapfrogIntegrator` initializer was previously ignored - this is now fixed.
* Usages of deprecated `numpy.bool` type removed.

New, changed and removed features

* Added implicit midpoint integrator (`mici.integrators.ImplicitMidpointIntegrator`) for non-separable Hamiltonian systems, with `dh2_dpos` method added to `EuclideanMetricSystem` to allow also using with implicit midpoint integrator for testing purposes.
* Added family of symmetric composition integrators described in [Blanes, Casas, Sanz-Serna (2014)](https://doi.org/10.1137/130932740).
* Added option to record traces during warm-up (`trace_warm_up` argument to `sample_chains` method).
* Added new `mici.interop` module with convenience functions for converting Mici `sample_chains` output to an `arviz.InferenceData` object, sampling a PyMC model with Mici and sampling a PyStan model with Mici.
* Added new projection solver for use with `ConstrainedLeapfrogIntegrator` which performs a Newton iteration with backtracking line search (`mici.solvers.solve_projection_onto_manifold_newton_with_line_search`).
* Default for `projection_solver` argument to `ConstrainedLeapfrogIntegrator` initializer changed to `mici.solvers.solve_projection_onto_manifold_newton`.
* Step size adapter now allows using custom reducer for combining per-chain adapted step sizes.
* Current step size now recorded in integration transition statistics (with key `step_size`) allowing live monitoring using `monitor_stats` argument to `sample_chains`.
* Handling of matrices initialised with non finite values improved with new `mici.errors.LinAlgError` exception being raised.
* Automatic chain truncation on keyboard interrupt removed.
* Norm functions now do not explicitly use NumPy API, instead using array methods / operator overloads, to allow using to array-like inputs such as `jax.Array` instances.

Documentation and packaging

* Documentation now built using Sphinx.
* Additional details and references added to docstrings and formatting improved.
* Project metadata now stored in `pyproject.toml` file with `setup.py` script removed.

Minor release.

Bug fixes:

* Fixed bug with metric adaptation due to momentum not being resampled. Previously after the metric was updated at the end of an adaptive sampling stage with a metric adapter active the chain state momentum component was left unchanged. As under the new metric this momentum may have a very high kinetic energy (low density) and the cached Hamiltonian and gradients depending on this momentum are no longer valid this could cause the initialisation of the step size in an immediately subsequent adaptive sampling stage to fail due to the Hamiltonian at the initial state being incorrect and thus a large chain in Hamiltonian always being computed irrespective of the step size.

Minor release.

New features

* Added option to limit threads used per process when sampling chain in parallel with `max_threads_per_process` option to `sample_chains*` methods if `threadpoolctl` is installed.

Bug fixes

* Fixing non pass through of call counter on state copy. Bug introduced in fdea526 when switching `state._call_counts` from dictionary to `collections.Counter` instance which meant call counter not shared by all copies of state which is intended behaviour to ensure that all calls are recorded.
* Changed to always reinitializing integrator step size at beginning of sampling stages with step size adaptation engaged. Changes from previous behaviour of not reinitializing step size of
integrator if previously set on beginning of adaptive sampling stage, which occured if for example step size was set manually when constructing integrator or had been set in a previous adaptive
chain stage. Instead when using step size adaptation the integrator step size is now always reinitialized to a reasonable value when initializing the adapter, which ensures the initial step size is appropriate if e.g. the metric has been changed or a previous chain (when running sequential chains) had adapted to a step size inappropriate for the position in state space of the current chain.
* Adjusted step size initialization logic to be robust to cases where Hamiltonian function may evaluate to NaN at some states
* Fixed bug with exception variable not being initialized in edge case of sample chains call with zero length collection of initial states.
* Removed faulty custom subclass / instance check behaviour for matrix classes.

Bug fixes

* Fixed bug when sampling chains in parallel without `multiprocess` installed introduced in v0.1.6 release due to use of non-pickleable local function in default value for `trace_funcs` argument.
* Corrected handling of zero and infinity edge cases by `LogRepFloat` class.
* Fixed bug in constructing diagonal of `*BlockDiagonalMatrix` classes.
* Fixed bug when using `sample_chain` method with `display_progress=False`.

Dependency changes and deprecations

* Minimum `numpy` version changed to 1.17 to ensure new-style `numpy.random.Generator` RNGs are available with use of `numpy.random.RandomState` instances deprecated.

API changes

* `tqdm` based progress bar implementation `mici.progressbars.TqdmProgressBar` removed as alternative to inbuilt progress bar class.
* `mici.utils.convert_to_arviz_inference_data` helper function removed as traces dictionary can be directly used in most ArviZ API functions and/or explicitly converted to an ArviZ `InferenceData` container using the inbuilt convert functions.
* Logic controlling staging of chain iterations in sampler `sample_chains_with_adaptive_warm_up` methods factored out to 'stager' classes in `mici.stagers` module. The `sample_chains_with_adaptive_warm_up` methods now accept a new keyword argument `stager` which replaces the previous windowed-adaptation specific `n_init_fast_stage_iter`, `n_init_slow_window_iter`, `n_final_fast_stage_iter` and `slow_window_multiplier` keywords, with these parameters now able to be instead set via the initializer for the `mici.stagers.WindowedWarmUpStager` class.
* Memoizing decorator `multi_cache_in_state`, used to cache outputs of system functions with additionally auxiliary outputs, renamed to `cache_in_state_with_aux`.