Merge pull request #29 from dynamicslab/cleanup-and-fixes

Cleanup and fixes

Author: kmanohar

.github/workflows/release.yml

@@ -10,11 +10,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
-        uses: actions/checkout@v1
+        uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.7
+          python-version: 3.11
       - name: Install dependencies
         run: pip install wheel
       - name: Build package

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
   rev: v5.0.0
   hooks:
     - id: check-added-large-files
-      args: ["--maxkb=775"]
+      args: ["--maxkb=900"]
     - id: check-merge-conflict
 - repo: https://github.com/PyCQA/isort
   rev: 5.12.0

README.rst

@@ -21,6 +21,12 @@ the PySensors approach to reconstruction problems and Brunton et al.
 literature review along with examples and additional tips for
 using PySensors effectively.
 
+The diagram below shows current Pysensors capabilities.
+
+.. figure:: docs/figures/pysensors-capabilities.jpeg
+  :align: center
+  :alt: A diagram showing current pysensors capabilities.
+  :figclass: align-center
 
 Reconstruction
 ^^^^^^^^^^^^^^
@@ -43,12 +49,18 @@ feed them to a ``SSPOR`` instance with 10 sensors, and
   model = pysensors.reconstruction.SSPOR(n_sensors=10)
   model.fit(data)
 
-Use the ``predict`` method to reconstruct a new function sampled at the chosen sensor locations:
+Use the ``predict`` method to reconstruct a new function sampled at the chosen sensor locations. There are two methods of reconstruction using ``predict``: ``Unregularized Reconstruction`` and ``Regularized Reconstruction``.
+
 
 .. code-block:: python
 
   f = numpy.abs(x[model.selected_sensors]**2 - 0.5)
-  f_pred = model.predict(f)
+  # Unregularized reconstruction can be used using the method ``unregularized``
+  f_pred_unregularized = model.predict(f, method='unregularized')
+  # Regularized reconstruction, on the other hand is the default method for predict. It also requires other parameters like prior and noise
+  f_pred_regularized = model.predict(f, prior, noise)
+
+See `reconstruction comparison example <https://python-sensors.readthedocs.io/en/latest/examples/reconstruction_comparison.html>`__ for more information on the methods of reconstruction.
 
 .. figure:: docs/figures/vandermonde.png
   :align: center
@@ -77,6 +89,8 @@ Three strategies to deal with constraints are currently developed:
 
 * ``predetermined`` - A number of sensor locations are predetermined and the aim is to optimize the rest.
 
+* ``distance constrained`` - Enforces a minimum distance 'r' between selected sensors.
+
 .. code-block:: python
 
   optimizer_exact = ps.optimizers.GQR()
@@ -89,24 +103,10 @@ Three strategies to deal with constraints are currently developed:
 We have further provided functions to compute the sensors in the constrained regions. For example if the user provides the center and radius of a circular
 constrained region, the constraints in utils compute the constrained sensor indices. Direct constraint plotting capabilities have also been developed.
 
-The constrained shapes currently implemented are:
-
-* ``Circle``
-
-* ``Cylinder``
-
-* ``Line``
-
-* ``Parabola``
+The constrained shapes currently implemented are: ``Circle``, ``Cylinder``, ``Line``, ``Parabola``, ``Ellipse``, ``Polygon``.
+A user can also define their own constraints using ``UserDefinedConstraints``, this type of constraint has the ability to take in either a function or a .py file which contains a functional definition of the constrained region.
 
-* ``Ellipse``
-
-* ``Polygon``
-
-* ``UserDefinedConstraints``
-
-  - This type of constraint has the ability to take in either a function from the user or a
-  .py file which contains a functional definition of the constrained region.
+See `this example <https://python-sensors.readthedocs.io/en/latest/examples/Olivetti_constrained_sensing.html>`__ for more information.
 
 Classification
 ^^^^^^^^^^^^^^
@@ -126,7 +126,7 @@ Bases
 ^^^^^
 The basis in which measurement data are represented can have a dramatic
 effect on performance. PySensors implements the three bases most commonly
-used for sparse sensor placement: raw measurements, SVD/POD/PCA modes, and random projections. Bases can be easily incorporated into ``SSPOR`` and ``SSPOC`` classes:
+used for sparse sensor placement: raw measurements, SVD/POD/PCA modes, and random projections. A user can also define their own custom basis. Bases can be easily incorporated into ``SSPOR`` and ``SSPOC`` classes:
 
 .. code-block:: python
 
@@ -141,7 +141,7 @@ Installation
 
 Dependencies
 ^^^^^^^^^^^^
-The high-level dependencies for PySensors are Linux or macOS and Python 3.6-3.8. ``pip`` is also recommended as is makes managing PySensors' other dependencies much easier. You can install it by following the instructions `here <https://packaging.python.org/tutorials/installing-packages/#ensure-you-can-run-pip-from-the-command-line>`__.
+The high-level dependencies for PySensors are Linux or macOS and Python 3.9-3.12. ``pip`` is also recommended as is makes managing PySensors' other dependencies much easier. You can install it by following the instructions `here <https://packaging.python.org/tutorials/installing-packages/#ensure-you-can-run-pip-from-the-command-line>`__.
 
 PySensors has not been tested on Windows.
 
@@ -191,10 +191,24 @@ The primary PySensors objects are the ``SSPOR`` and ``SSPOC`` classes, which are
 
   - ``Identity`` - use raw measurement data
   - ``SVD`` - efficiently compute first k left singular vectors
-  - ``RandomProjection`` - Gaussian random projections of measurements
+  - ``RandomProjection`` - gaussian random projections of measurements
+  - ``CustomBasis`` - user defined bases ranging from DMD modes to Chebyshev polynomials
 
+* ``optimizers`` - submodule implementing different optimizers to fit data
+
+  - ``QR`` - greedy QR optimizer
+  - ``CCQR`` - greedy cost constrained QR optimizer
+  - ``GQR`` - general QR optimizer
+  - ``TPGR`` - two point greedy optmizer
 * Convenience functions to aid in the analysis of error as number of sensors or basis modes are varied
 
+The diagram below outlines a flow chart of how a user can utilize pysensors.
+
+.. figure:: docs/figures/pysensors-methods.jpeg
+  :align: center
+  :alt: A flow chart of pysensors methods.
+  :figclass: align-center
+
 Documentation
 -------------
 PySensors has a `documentation site <https://python-sensors.readthedocs.io/en/latest/index.html>`__ hosted by readthedocs.
@@ -300,12 +314,15 @@ References
    (2018): 2642-2656.
    `[DOI] <https://doi.org/10.1109/JSEN.2018.2887044>`__
 
--  Karnik, Niharika, Mohammad G. Abdo, Carlos E. Estrada-Perez, Jun Soo Yoo,
-    Joshua J. Cogliati, Richard S. Skifton, Pattrick Calderoni, Steven L. Brunton, and Krithika Manohar.
-   "Constrained Optimization of Sensor Plcaement for Nuclear Digital Twins" IEEE Sensors Journal 24, no. 9
+-  Karnik, Niharika, Mohammad G. Abdo, Carlos E. Estrada-Perez, Jun Soo Yoo, Joshua J. Cogliati, Richard S. Skifton, Pattrick Calderoni, Steven L. Brunton, and Krithika Manohar.
+   "Constrained Optimization of Sensor Placement for Nuclear Digital Twins" IEEE Sensors Journal 24, no. 9
    (2024): 15501 - 15516.
    `[DOI] <https://doi.org/10.1109/JSEN.2024.3368875>`__
 
+- Klishin, Andrei A., J. Nathan Kutz, Krithika Manohar
+  "Data-Induced Interations of Sparse Sensors" (2023)
+  `[DOI] <https://doi.org/10.48550/arXiv.2307.11838>`__
+
 .. |Build| image:: https://github.com/dynamicslab/pysensors/actions/workflows/main.yml/badge.svg?branch=master
     :target: https://github.com/dynamicslab/pysensors/actions?query=workflow%3ACI
 

docs/figures/pysensors-capabilities.jpeg

@@ -1,19 +1,71 @@
 PySensors Examples
 ==================
 
+This directory provides examples of how to use `PySensors` objects to solve sensor placement problems.
+`PySensors` was designed to be completely compatible with `scikit-learn`.
+
+`PySensors Overview <./pysensors_overview.ipynb>`__
+---------------------------------------------------
+This notebook gives an overview of most of the different tools available in `PySensors`. It's a good place to start to get a quick idea of what the package is capable of.
+
+.. toctree::
+  :hidden:
+  :maxdepth: 1
+
+  pysensors_overview
+
+`Classification <./classification.ipynb>`__
+-------------------------------------------
+This notebook showcases the use of `SSPOC` class (Sparse Sensor Placement Optimization for Classification) to choose sparse sets of sensors for *classification* problems.
+
+.. toctree::
+  :hidden:
+  :maxdepth: 1
+
+  classification
+
+Reconstruction
+--------------
+These notebooks show how the `SSPOR` class (Sparse Sensor Placement Optimization for Reconstruction) can be used with different optimizers.
+The default optimizer for `SSPOR` is `QR`, which uses QR pivoting to select sensors in unconstrained problems.
+`GQR` (General QR) optimizer provides a more intrusive approach into the `QR` pivoting procedure to take into account spatial constraints. The `General QR Optimizer for Spatial Constraints <./spatial_constrained_qr.ipynb>`__ and `Functional Constraints for Olivetti Faces <./Olivetti_constrained_sensing.ipynb>`__ notebooks provide a detailed account of unconstrained and constrained sensor placement.
+`CCQR` (Cost Constrained QR) optimizer can be used to place sparse sensors when there are variable costs associated with different locations. The `Cost Constrained QR <./cost_constrained_qr.ipynb>`__ notebook showcases the `CCQR` optimizer.
+`TPGR` (Two Point GReedy) optimizer uses a thermodynamic approach to sensor placement that maps the complete landscape of sensor interactions induced by the training data and places sensors such that the marginal energy of each next placed sensor is minimized. The `TPGR <./two_point_greedy.ipynb>`__ notebook goes into detail about the optimizer and the one-point and two-point enery landscape computation. The `TPGR` optimizer requires prior and noise.
+
+There are two methods used for reconstruction: `Unregularized Reconstruction`, which uses the Moore-Penrose Pseudoinverse method, and `Regularized Reconstruction`, that uses a maximal likelihood reconstructor that requires a prior and noise.
+The `Reconstruction Comparison <./reconstruction_comparison.ipynb>`__ notebook compares these two methods using the `TPGR` optimizer. It also shows a comparison between `TPGR` and `QR` optimizers using both of the reconstruction methods.
+
+.. toctree::
+  :hidden:
+  :maxdepth: 1
+
+  spatial_constrained_qr
+  Olivetti_constrained_sensing
+  cost_constrained_qr
+  two_point_greedy
+  reconstruction_comparison
+
+Basis
+-----
+The `Basis Comparison <./basis_comparison.ipynb>`__ notebook compares the different basis options implemented in `PySensors` on a simple problem.
+`Cross Validation<./cross_validation.ipynb>`__ is also performed with `scikit-learn` objects to optimize the number of sensors and/or basis modes.
+
 .. toctree::
-   :maxdepth: 1
-   :caption: Example Notebooks
-
-   pysensors_overview
-   basis_comparison
-   classification
-   cost_constrained_qr
-   cross_validation
-   sea_surface_temperature
-   reconstruction_comparison
-   two_point_greedy
-   polynomial_curve_fitting
-   spatial_constrained_qr
-   Olivetti_constrained_sensing
-   OPTI-TWIST_constrained_sensing
+  :hidden:
+  :maxdepth: 1
+
+  basis_comparison
+  cross_validation
+
+Applications
+------------
+These notebooks showcase the sensor placement optimization methods on datasets ranging from `Sea Surface Temperature <./sea_surface_temperature.ipynb>`__ to predicting the temperature within a `Fuel Rod <./OPTI-TWIST_constrained_sensing.ipynb>`__ with spatially constrained sensors.
+The `Polynomial Curve Fitting <./polynomial_curve_fitting>`__ notebook demonstrates how to use PySensors to select sensor locations for polynomial interpolation using the monomial basis $1, x, x^2, x^3, \dots, x^k$.
+
+.. toctree::
+  :hidden:
+  :maxdepth: 1
+
+  sea_surface_temperature
+  polynomial_curve_fitting
+  OPTI-TWIST_constrained_sensing