pysindy.BINDy

class pysindy.BINDy(sigma_x: float, optimizer: EvidenceGreedy | None = None, feature_library: BaseFeatureLibrary | None = None, differentiation_method: FiniteDifference | None = None)[source]

Bayesian Identification of Nonlinear Dynamical Systems (BINDy)

Learns a dynamical model with corrections for measurement noise passing through differentiation and feature library. Maximizes a Gaussian (Laplace) approximation of the posterior with a weakly informed hyper prior on the feature coefficients, then greedily eliminates model features to maximize Bayesian evidence.

For more information, see this paper: https://doi.org/10.1098/rspa.2024.0200 .

See also

SBR

A Bayesian optimizer that uses a more sophisticated sparsifying prior and Monte Carlo sampling. Slower but more accurate.

EnsembleOptimizer

Model sparsification by b(r)agging. Empirically approximating Bayesian method.

Parameters:

(required) (sigma_x) –

Measurement noise standard deviation (std) for the state measurements x. If x_dot is provided, sigma_x is used to set the noise variance optimizer._sigma2 = sigma_x**2.

Otherwise, sigma_x is propagated through the differentiation_method to estimate the derivative noise variance:

_sigma2 = TemporalNoisePropagation(
    differentiation_method, t_grid, sigma_x
)

For multiple trajectories, _sigma2 is computed per trajectory and averaged.

optimizer

Optimization method used to fit the SINDy model. This must be a class extending pysindy.optimizers.BaseOptimizer. The default is pysindy.optimizers.EvidenceGreedy.

feature_library

Feature library object used to specify candidate right-hand side features. This must be a class extending pysindy.feature_library.base.BaseFeatureLibrary. The default option is pysindy.feature_library.PolynomialLibrary.

differentiation_method

Method for differentiating the data. This must be a class extending pysindy.differentiation.base.BaseDifferentiation class. It must also be a linear method. The default option is centered finite differences.

Attributes:

  • model (sklearn.pipeline.Pipeline) – The fitted SINDy model pipeline.

  • n_input_features_ (int) – The total number of input features.

  • n_output_features_ (int) – The total number of output features.

  • n_control_features_ (int) – The total number of control input features.

  • feature_names (list of str or None) – Names for the input features.

Notes

Noise propagation from measurement noise sigma_x to the derivative noise variance used by the regression (optimizer._sigma2) is only performed when:

  1. x_dot is not provided, and derivatives are estimated internally.

  2. differentiation_method is linear (e.g., FiniteDifference or SmoothedFiniteDifference).

Spectral differentiation is currently not supported for noise propagation.

  • FiniteDifference is strongly recommended for EvidenceGreedy because the noise propagation algorithm assumes a linear differential operator. If you use a different differentiator, set optimizer._sigma2 manually.

Examples

>>> import numpy as np
>>> from scipy.integrate import odeint
>>> import pysindy as ps
>>> from pysindy.differentiation import FiniteDifference
>>> from pysindy.optimizers import EvidenceGreedy
>>>
>>> def lorenz(z, t):
...     x, y, z_ = z
...     return [10.0 * (y - x), x * (28.0 - z_) - y, x * y - 8.0 / 3.0 * z_]
>>>
>>> t = np.arange(0, 10, 0.01)
>>> x0 = np.array([-8.0, 8.0, 27.0])
>>> sigma_x = 0.01
>>> x = odeint(lorenz, x0, t)
>>> x = x + sigma_x * np.random.normal(size=x.shape) # add noise
>>> dt = t[1] - t[0]
>>>
>>> model = ps.BINDy(sigma_x=sigma_x) # You MUST specify sigma_x
>>> model.fit(x, t=dt)
>>> model.print()

Methods

fit

Fit an BINDy model.

set_fit_request

Configure whether metadata should be requested to be passed to the fit method.

set_predict_request

Configure whether metadata should be requested to be passed to the predict method.

set_score_request

Configure whether metadata should be requested to be passed to the score method.

Attributes

feature_library

optimizer

feature_names

fit(x, t, x_dot=None, u=None, feature_names: list[str] | None = None)[source]

Fit an BINDy model.

See pysindy.SINDy.fit for full parameter documentation.

set_fit_request(*, feature_names: bool | None | str = '$UNCHANGED$', t: bool | None | str = '$UNCHANGED$', u: bool | None | str = '$UNCHANGED$', x: bool | None | str = '$UNCHANGED$', x_dot: bool | None | str = '$UNCHANGED$') → BINDy

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • feature_names (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for feature_names parameter in fit.

  • t (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for t parameter in fit.

  • u (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for u parameter in fit.

  • x (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x parameter in fit.

  • x_dot (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x_dot parameter in fit.

Returns:

self – The updated object.

Return type:

object

set_predict_request(*, u: bool | None | str = '$UNCHANGED$', x: bool | None | str = '$UNCHANGED$') → BINDy

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to predict.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • u (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for u parameter in predict.

  • x (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x parameter in predict.

Returns:

self – The updated object.

Return type:

object

set_score_request(*, metric: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$', t: bool | None | str = '$UNCHANGED$', u: bool | None | str = '$UNCHANGED$', x: bool | None | str = '$UNCHANGED$', x_dot: bool | None | str = '$UNCHANGED$') → BINDy

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to score.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • metric (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for metric parameter in score.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.

  • t (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for t parameter in score.

  • u (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for u parameter in score.

  • x (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x parameter in score.

  • x_dot (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x_dot parameter in score.

Returns:

self – The updated object.

Return type:

object