DOC: Add objects.rst, slim down README.rst

Jacob-Stevens-Haas · Jacob-Stevens-Haas · commit 73ebd4117293 · 2025-09-22T09:31:55.000-07:00
diff --git a/README.rst b/README.rst
@@ -3,69 +3,53 @@ PySINDy
 
 |BuildCI| |RTD| |PyPI| |Codecov| |JOSS1| |JOSS2| |DOI|
 
-**PySINDy** is a sparse regression package with several implementations for the
+**PySINDy** is a package for system identification, primarily revolving around the method of
 Sparse Identification of Nonlinear Dynamical systems (SINDy) method introduced
 in Brunton et al. (2016a).
-It also includes a variety of other methods from related literature.
-A comprehensive literature review is given in de Silva et al. (2020) and Kaptanoglu, de Silva et al. (2021).
+It also includes other methods from related literature.
 
-System identification
----------------------
-System identification refers to the process of leveraging measurement data to infer governing equations, in the form of dynamical systems, describing the data.
+*System identification* refers to the process of using measurement data to infer the governing dynamics.
 Once discovered, these equations can make predictions about future states, can inform control inputs, or can enable the theoretical study using analytical techniques.
-Dynamical systems are a flexible, well-studied class of mathematical objects for modeling systems evolving in time.
-SINDy is a model discovery method which uses *sparse regression* to infer nonlinear dynamical systems from measurement data.
 The resulting models are inherently *interpretable* and *generalizable*.
 
-How it works
-^^^^^^^^^^^^
-Suppose, for some physical system of interest, we have measurements of state variables ``x(t)`` (a vector of length n) at different points in time. Examples of state variables include the position, velocity, or acceleration of objects; lift, drag, or angle of attack of aerodynamic objects; and concentrations of different chemical species. If we suspect that the system could be well-modeled by a dynamical system of the form
 
-.. code-block:: text
-
-    x'(t) = f(x(t)),
-
-then we can use SINDy to learn ``f(x)`` from the data (``x'(t)`` denotes the time derivative of ``x(t)``). Note that both ``f(x)`` and ``x(t)`` are typically vectors. The fundamental assumption SINDy employs is that each component of ``f(x)``, ``f_i(x)`` can be represented as a *sparse* linear combination of basis functions ``theta_j(x)``
-
-.. code-block:: text
-
-    f_i(x) = theta_1(x) * xi_{1,i} + theta_2(x) * xi_{2,i} + ... + theta_k * xi{k,i}
+First Steps
+------------------
 
-Concatenating all the objects into matrices (denoted with capitalized names) helps to simplify things.
-To this end we place all measurements of the state variables into a data matrix ``X`` (with a row per time measurement and a column per variable), the derivatives of the state variables into a matrix ``X'``, all basis functions evaluated at all points in time into a matrix ``Theta(X)`` (each basis function gets a column), and all coefficients into a third matrix ``Xi`` (one column per state variable).
-The approximation problem to be solved can then be compactly written as
-
-.. code-block:: text
-
-    X' = Theta(X) * Xi.
+Installation
+^^^^^^^^^^^^^^
 
-Each row of this matrix equation corresponds to one coordinate function of ``f(x)``.
-SINDy employs sparse regression techniques to find a solution ``Xi`` with sparse column vectors.
-For a more in-depth look at the mathematical foundations of SINDy, please see our `introduction to SINDy <https://pysindy.readthedocs.io/en/latest/examples/2_introduction_to_sindy/example.html>`__.
+The preferred way to install is with pip or conda e.g. ``pip install pysindy``.
+You may have to add the ``--user`` option.
+Pysindy also provides several extras, e.g. ``pip install pysindy[miosr]``:
 
-Relation to PySINDy
-^^^^^^^^^^^^^^^^^^^
-The PySINDy package revolves around the ``SINDy`` class which consists of three primary components; one for each term in the above matrix approximation problem.
+cvxpy
+  Convex optimizer ``SR3`` and subclasses
 
-* ``differentiation_method``: computes ``X'``, though if derivatives are known or measured directly, they can be used instead
-* ``feature_library``: specifies the candidate basis functions to be used to construct ``Theta(X)``
-* ``optimizer``: implements a sparse regression method for solving for ``Xi``
+miosr
+  Branch-and-bound optimizer for L0-constraint, ``MIOSR``
 
-Once a ``SINDy`` object has been created it must be fit to measurement data, similar to a ``scikit-learn`` model.
-It can then be used to predict derivatives given new measurements, evolve novel initial conditions forward in time, and more.
+sbr
+  Bayesian regression optimizer yielding posteriors, ``SBR``.
 
 Example
-^^^^^^^
+^^^^^^^^^^^
 Suppose we have measurements of the position of a particle obeying the following dynamical system at different points in time
 
-.. code-block:: text
+.. math::
 
-  x' = -2x
-  y' = y
+  x' &= -2 x \\
+  y' &= y
 
-Note that this system of differential equations decouples into two differential equations whose solutions are simply ``x(t) = x_0 * exp(-2 * t)`` and ``y(t) = y_0 * exp(t)``, where ``x_0 = x(0)`` and ``y_0 = y(0)`` are the initial conditions.
+Note that this system of differential equations decouples into two differential equations whose solutions are simply
 
-Using the initial conditions ``x_0 = 3`` and ``y_0 = 0.5``, we construct the data matrix ``X``.
+.. math::
+
+  x(t) &= x_0 * exp(-2 * t) \\
+  y(t) &= y_0 * exp(t)
+
+This example uses the initial conditions ``x_0 = 3`` and ``y_0 = 0.5``.
+It then fits and prints the discovered model
 
 .. code-block:: python
 
@@ -77,69 +61,31 @@ Using the initial conditions ``x_0 = 3`` and ``y_0 = 0.5``, we construct the dat
   y = 0.5 * np.exp(t)
   X = np.stack((x, y), axis=-1)  # First column is x, second is y
 
-To instantiate a ``SINDy`` object with the default differentiation method, feature library, and optimizer and then fit it to the data, we invoke
-
-.. code-block:: python
-
-  model = ps.SINDy(feature_names=["x", "y"])
-  model.fit(X, t=t)
-
-We use the ``feature_names`` argument so that the model prints out the correct labels for ``x`` and ``y``. We can inspect the governing equations discovered by the model and check whether they seem reasonable with the ``print`` function.
-
-.. code-block:: python
-
+  model = ps.SINDy()
+  model.fit(X, t=t, feature_names=["x", "y"])
   model.print()
 
-which prints the following
+which correctly results in
 
 .. code-block:: text
 
   x' = -2.000 x
   y' = 1.000 y
 
-PySINDy provides numerous other features not shown here. We recommend the `feature overview <https://pysindy.readthedocs.io/en/latest/examples/1_feature_overview/example.html>`__ section of the documentation for a more exhaustive summary of additional features.
-
-Installation
-------------
-
-The preferred way to install is with pip or conda e.g. ``pip install pysindy``.
-You may have to add ``--user`` option.
-Pysindy also provides several extras:
+PySINDy provides numerous other features not shown here. We have a variety of tutorials and examples, starting with
+`feature overview <https://pysindy.readthedocs.io/en/latest/examples/1_feature_overview/example.html>`_.
 
-cvxpy
-  Convex optimizer ``SR3`` and subclasses
 
-miosr
-  Branch-and-bound optimizer for L0-constraint, ``MIOSR``
-
-sbr
-  Bayesian regression optimizer yielding posteriors, ``SBR``.
-
-
-Documentation
+Getting Help
 -------------
-The documentation site for PySINDy can be found `here <https://pysindy.readthedocs.io/en/latest/>`__.
-There are numerous `examples <https://pysindy.readthedocs.io/en/latest/examples/index.html>`_ of PySINDy in action to help you get started.
-Examples are also available as `Jupyter notebooks <https://github.com/dynamicslab/pysindy/tree/master/examples>`__.
-A video overview of PySINDy can be found on `Youtube <https://www.youtube.com/watch?v=DvbbXX8Bd90>`__.
-We have also created a `video playlist <https://www.youtube.com/playlist?list=PLN90bHJU-JLoOfEk0KyBs2qLTV7OkMZ25>`__ with practical PySINDy tips.
-
-If something is unclear, please open an issue.  To discuss your particular dynamics problem, open a discussion.  Make sure to format your example as python code in github!
-
-PySINDy implements a lot of advanced functionality that may be overwhelming for new users or folks who are unfamiliar with these methods. Below (see here if image does not render https://github.com/dynamicslab/pysindy/blob/master/docs/JOSS2/Fig3.png), we provide a helpful flowchart for figuring out which methods to use, given the characteristics of your dataset:
-
-.. image:: https://github.com/dynamicslab/pysindy/blob/master/docs/JOSS2/Fig3.png
-
-This flow chart summarizes how ``PySINDy`` users can start with a dataset and systematically choose the proper candidate library and sparse regression optimizer that are tailored for a specific scientific task. The ``GeneralizedLibrary`` class allows for tensoring, concatenating, and otherwise combining many different candidate libraries.
-
-Contributions:
------------------------------
-See `Contributor guide <https://pysindy.readthedocs.io/en/latest/contributing.html>`_.
-
 
-Citing PySINDy
------------------
-See `Academic use <https://pysindy.readthedocs.io/en/latest/academic.html>`_.
+* If you have a **question** or find a **bug**, please open an `issue <https://github.com/dynamicslab/pysindy/issues>`_ on github.
+* The **documentation** site for PySINDy can be found `here <https://pysindy.readthedocs.io/en/latest/>`__.
+  A video overview of PySINDy can be found on `Youtube <https://www.youtube.com/watch?v=DvbbXX8Bd90>`__.
+  We have also created a `video playlist <https://www.youtube.com/playlist?list=PLN90bHJU-JLoOfEk0KyBs2qLTV7OkMZ25>`__ with practical PySINDy tips.
+* To understand more about the **types of objects** in pysindy, see the `object model <https://pysindy.readthedocs.io/en/latest/objects>`_.
+* If you want to fix a problem, add a feature, or share an example, check the `**Contributor** Guide <https://pysindy.readthedocs.io/en/latest/contributing.html>`_.
+* If you are using pysindy in **academic** work, please see `Academic Use <https://pysindy.readthedocs.io/en/latest/academic.html>`_ for recommendations, including **citations**.
 
 
 Related packages
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,18 +3,20 @@
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
    :caption: User Guide
 
    API Documentation <api/pysindy>
    Examples <examples/index>
    Practical tips <tips>
    Contributing <contributing>
    Using pysindy in academia <academic>
+   Object Model <objects>
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
    :caption: Useful links
 
-
    PySINDy @ PyPI <https://pypi.org/project/PySINDy/>
    Issue Tracker <https://github.com/dynamicslab/pysindy/issues>
diff --git a/docs/objects.rst b/docs/objects.rst
@@ -0,0 +1,115 @@
+PySINDy Object Model
+========================
+This document describes the main types of objects in pysindy
+and how users tend to interact with them.
+It then proceeds to summarize the problems and planned changes to the type system,
+as discussed in issues like
+`this one <https://github.com/dynamicslab/pysindy/issues/351>`_.
+It is most useful for people who want to implement their own variant of SINDy
+within the pysindy package.
+
+Current typing system
+----------------------------
+The PySINDy package revolves around the abstract base class ``_BaseSINDy`` which represents
+the problem of fitting a dynamical system :math:`X' = \Xi^T \Theta(X)`.
+It implements the basics of printing the discovered system of equations and
+fitting the shape of inputs and outputs.
+For example, it contains methods like ``equations()``, ``print()``, and  ``_fit_shape()``.
+Different subclasses handle how that fitting actually occurs:
+As the only current concrete subclass, ``SINDy`` objects follow the traditional approach, comprising a
+
+* ``differentiation_method: BaseDifferentiation``: computes :math:`X'`.
+  Subclasses often accept an ``axis`` and ``order`` argument, and are callable objects.
+  When creating new differentiation methods, add them to the |derivative|_.
+* ``feature_library: BaseFeatureLibrary``: specifies the candidate basis functions to be used to construct :math:`\Theta(X)`.
+  Most significantly for the end user, ``fit()`` determines the number and string format
+  of the feature library, as applied to the input variables.
+  You can see these with ``BaseFeatureLibrary.get_feature_names()`` or ``BaseFeatureLibrary.n_features_out_``.
+  One challenge with the straight-pipeline approach is that constraints must be manually constructed as arrays,
+  and require knowing the order of the features, which in turn requires the feature library to be fit.
+  There is no harm, however, in fitting the feature library on the data before fitting ``SINDy``,
+  even though the latter will refit the feature library.
+  ``transform()`` is used to actually calculate the feature values on input data.
+* ``optimizer: BaseOptimizer``: implements a sparse regression method for solving for :math:`\Xi`.
+  These share a common ``fit()`` method, with different implementations going in ``_reduce()``.
+  Most notably, they share a ``history_`` of coefficient values and a ``coef_`` array of the final coefficients.
+  When subclassing ``BaseOptimizer``, be sure to note whether your approach can be unbiased,
+  and if not, raise an error if set to ``True``.
+
+
+.. |derivative| replace:: ``derivative`` package
+.. _derivative: https://derivative.readthedocs.io/en/latest/
+
+Once a ``SINDy`` object has been created it must be fit to measurement data, similar to a ``scikit-learn`` model.
+It can then be used to predict derivatives given new measurements in ``predict()``
+as well as evolve novel initial conditions forward in time using ``simulate()``.
+It can also ``score()`` itself.  Take care, however, as there are different metrics
+for a SINDy model (`issue 1`_, `issue 2`_).
+
+.. _issue 1: https://github.com/dynamicslab/pysindy/issues/372
+
+.. _issue 2: https://github.com/scikit-learn/scikit-learn/issues/31360
+
+
+Problems
+---------------------
+.. admonition:: A good rule
+
+    Type compatibility should equate to mathematical compatibility
+
+While the single base class ``SINDy`` worked for a while, it ran into problems as different innovations
+were added as either differentiation methods, feature libraries, or optimizers,
+but not as new types.
+Oftentimes the innovations were only compatible with correct decisions on other objects in the SINDy model,
+e.g. trapping SINDy is implemented as a ``TrappingSR3`` optimizer, but is only mathematically sensible with a quadratic Polynomial library.
+At the same time, the Polynomial library type is not parameterized by polynomial order,
+which is just one of the changes that would need to exist in order for the type system to enforce mathematical compatibility.
+
+Similar problems exist in Weak SINDy and SINDy-PI, whose implementations are deeply coupled.
+
+Future type system changes
+-----------------------------
+Currently weak SINDy is implemented through the ``WeakPDELibrary`` in a basic SINDy model.
+However, as it eschews derivative calculation, ``WeakSINDy`` will soon exist as a subclass of ``_BaseSINDy``
+for fitting continuous dynamics using the integral form.
+
+Similarly, discrete SINDy, which does not use a differentiation method, will become a subclass of ``_BaseSINDy``
+rather than an argument to the ``SINDy`` initialization.
+
+SINDy-PI is a unique problem in that it represents the problem of fitting a dynamical system,
+as does ``_BaseSINDy``,
+but produces a set of possible coefficient matrices with no ability to choose from them.
+Moreover, the equations it attempts to discover are implicit and do not create predictions in a uniform way.
+This means that ``predict()``, ``simulate()``, and ``equations()`` do not work.
+SINDy-PI is currently implemented across the ``PDELibrary``, ``WeakPDELibrary`` and ``SINDyPIOptimizer``,
+but will eventually become its own class that interacts with ``SINDy``, ``WeakSINDy``, Discrete SINDy,
+and component objects in a unique way.
+
+``EnsembleOptimizer`` and ``SBR`` are two different optimizers that result in a distribution of coefficients.
+The former wraps another optimizer, however it should not wrap ``SBR`` or another ``EnsembleOptimizer``.
+This reflects a fundamental difference in types: ``RandomVariableOptimizers`` whose coefficients are understaood to be random variables
+and ``DeterministicOptimizers`` whose coefficients are deterministic.
+Moreover, post-analysis of random variable optimizers is ad-hoc;
+users must access the underlying numpy arrays (``EnsembleOptimizer``)
+or numpyro random variables (``SBR``) in order to visualize the distributions.
+While that is a smaller problem, it suggests a unified API would support better comparison of these approaches.
+
+
+Trapping SINDy, as mentioned, requires some spooky action at a distance.
+It may become a factory function which chooses the optimizer and feature library for the user,
+depending on whether the user wants weak or traditional SINDy.
+
+Differentiation began with ``FiniteDifference``, but quickly moved to methods that
+both smooth and differentiate.
+For a while pysindy did not use the smooth coordinates, only the smoothed derivatives.
+For backwards compatibility, the smoothed coordinates were attached
+to the ``BaseDifferentiation`` object, rather than returned.
+Using differentiation for PDEs adds additional complexity.
+Some differentation/smoothing methods assume a single order of smoothness,
+which makes them unsuitable for most PDEs.
+Smoothing that only smoothes in one axis as a time does not result in consistent
+trajectories when smoothed along different axes.
+Moreover, most existing implementations are defined in the ``derivative`` package.
+Ideally, ``pysindy`` gets out of the business of derivative implementations,
+merely specifying (and correctly using) an API that treats differentiation and smoothing
+as two aspects of applying assumptions to a random process.
diff --git a/examples/README.rst b/examples/README.rst
@@ -5,6 +5,7 @@ This directory showcases examples of PySINDy in action.
 Some are copied from another repository that contains dependency information and
 potentially a greater description.
 
+Tutorials in the pysindy repo are also available as `Jupyter notebooks <https://github.com/dynamicslab/pysindy/tree/master/examples>`_.
 Some notebooks require substantial computing resources.
 
 `Feature overview <./1_feature_overview/example.ipynb>`_
