Merge pull request #23 from Jimmy-INL/Jimmy-handling-functional-Constraints

Adding a constraints class for the GQR optimizer

Author: yb6599

README.rst

@@ -55,6 +55,59 @@ Use the ``predict`` method to reconstruct a new function sampled at the chosen s
   :alt: A plot showing the function to be reconstructed, the learned sensor locations, and the reconstruction.
   :figclass: align-center
 
+Reconstruction with constraints
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In most engineering applications, certain areas within the region of interest might allow a limited number of sensors or none at all.
+We develop a data-driven technique that incorporates constraints into an optimization framework for sensor placement, with the primary objective
+of minimizing reconstruction errors under noisy sensor measurements.
+
+This work has been implemented in the general QR optimizer for sensor selection.
+This is an extension that requires a more intrusive access to the QR optimizer to facilitate a more adaptive optimization. It is a generalized version of cost constraints
+in the sense that users can allow `n_const_sensors` in the constrained area. If n = 0 this converges to the CCQR results. If there is
+no constrained region it should converge to the results from QR optimizer.
+
+To implement constrained sensing we initialize the optimizer GQR and provide it additional kwargs such as the constrained region, number of allowable
+sensors in the constrained region and the type of constraint.
+
+Three strategies to deal with constraints are currently developed:
+
+* ``max_n`` - Number of sensors in the constrained region should be less than or equal to the allowable constrained sensors.
+
+* ``exact_n`` - Number of sensors in the constrained region should be exactly equal to the allowable constrained sensors.
+
+* ``predetermined`` - A number of sensor locations are predetermined and the aim is to optimize the rest.
+
+.. code-block:: python
+
+  optimizer_exact = ps.optimizers.GQR()
+  opt_exact_kws={'idx_constrained':sensors_constrained,
+          'n_sensors':n_sensors,
+          'n_const_sensors':n_const_sensors,
+          'all_sensors':all_sensors,
+          'constraint_option':"exact_n"}
+
+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``
+
+* ``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.
+
 Classification
 ^^^^^^^^^^^^^^
 Classification is the problem of predicting which category an example belongs to, given a set of training data (e.g. determining whether digital photos are of dogs or cats).
@@ -247,6 +300,12 @@ 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
+   (2024): 15501 - 15516.
+   `[DOI] <https://doi.org/10.1109/JSEN.2024.3368875>`__
+
 .. |Build| image:: https://github.com/dynamicslab/pysensors/workflows/Tests/badge.svg
     :target: https://github.com/dynamicslab/pysensors/actions?query=workflow%3ATests
 

examples/README.rst

@@ -37,6 +37,22 @@ ocean at any given point.
 Reproduces an example from `Manohar et al. (2018) <https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=8361090>`_
 where sensor locations are learned for a monomial basis for the task of reconstruction.
 
+`Spatial constraints example <https://python-sensors.readthedocs.io/en/latest/examples/spatially_constrained_qr.html>`_
+----------------------------------------------------------------------------------------------------
+Sensor locations are learned for a constrained sensing problem for the task of reconstruction. For further details of constrained sensing refer
+`Karnik et al. (2024) <https://ieeexplore.ieee.org/abstract/document/10453459>`_
+
+`Functional constraints example <https://python-sensors.readthedocs.io/en/latest/examples/functional_constraints.html>`_
+----------------------------------------------------------------------------------------------------
+Sensor locations are learned for various shapes of constrained regions. For further details refer to
+`Karnik et al. (2024) <https://www.mdpi.com/1996-1073/17/13/3355>`_
+
+`Spatially Constrained sensing for a nuclear application <https://python-sensors.readthedocs.io/en/latest/examples/nuclear_application.html>`_
+----------------------------------------------------------------------------------------------------
+See how `PySensors` can be used to pick near optimal locations for sensors that accurateely reconstruct temperature in a nuclear fuel rod prototype
+. For further details refer to `Karnik et al. (2024) <https://ieeexplore.ieee.org/abstract/document/10453459>`_
+
+
 
 Full table of contents
 ----------------------