From d19e46371790c71d49ad75b17c7be3deae79283f Mon Sep 17 00:00:00 2001 From: Miranda Mundt Date: Mon, 18 Nov 2024 07:04:57 -0700 Subject: [PATCH 1/4] Update Documentation URLs --- doc/OnlineDocs/explanation/analysis/doe/doe.rst | 2 +- doc/OnlineDocs/explanation/solvers/mindtpy.rst | 4 ++-- pyomo/contrib/incidence_analysis/README.md | 2 +- pyomo/contrib/mindtpy/algorithm_base_class.py | 2 +- pyomo/contrib/mindtpy/global_outer_approximation.py | 2 +- pyomo/contrib/mindtpy/outer_approximation.py | 2 +- pyomo/contrib/mpc/README.md | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/OnlineDocs/explanation/analysis/doe/doe.rst b/doc/OnlineDocs/explanation/analysis/doe/doe.rst index 66feaa38ad0..a48f4546ab0 100644 --- a/doc/OnlineDocs/explanation/analysis/doe/doe.rst +++ b/doc/OnlineDocs/explanation/analysis/doe/doe.rst @@ -26,7 +26,7 @@ Pyomo.DoE provides the exploratory analysis and MBDoE capabilities to the Pyomo the allowable design spaces for design variables, and the assumed observation error model. During exploratory analysis, Pyomo.DoE checks if the model parameters can be inferred from the postulated measurements or preliminary data. MBDoE then recommends optimized experimental conditions for collecting more data. -Parameter estimation packages such as `Parmest `_ can perform parameter estimation using the available data to infer values for parameters, +Parameter estimation packages such as `Parmest `_ can perform parameter estimation using the available data to infer values for parameters, and facilitate an uncertainty analysis to approximate the parameter covariance matrix. If the parameter uncertainties are sufficiently small, the workflow terminates and returns the final model with quantified parametric uncertainty. If not, MBDoE recommends optimized experimental conditions to generate new data. diff --git a/doc/OnlineDocs/explanation/solvers/mindtpy.rst b/doc/OnlineDocs/explanation/solvers/mindtpy.rst index ce7650b5a05..bb47315fc70 100644 --- a/doc/OnlineDocs/explanation/solvers/mindtpy.rst +++ b/doc/OnlineDocs/explanation/solvers/mindtpy.rst @@ -26,7 +26,7 @@ at Purdue University and Carnegie Mellon University. .. _Duran & Grossmann, 1986: https://dx.doi.org/10.1007/BF02592064 .. _Westerlund & Petterson, 1995: http://dx.doi.org/10.1016/0098-1354(95)87027-X .. _Kesavan & Allgor, 2004: https://link.springer.com/article/10.1007/s10107-004-0503-1 -.. _MC++: https://pyomo.readthedocs.io/en/stable/contributed_packages/mcpp.html +.. _MC++: https://pyomo.readthedocs.io/en/stable/explanation/solvers/mcpp.html .. _Bernal & Peng, 2021: http://www.optimization-online.org/DB_HTML/2021/06/8452.html .. _Kronqvist & Bernal, 2018: https://link.springer.com/article/10.1007%2Fs10107-018-1356-3 .. _Bonami & Cornuéjols, 2009: https://link.springer.com/article/10.1007/s10107-008-0212-2 @@ -132,7 +132,7 @@ The LP/NLP based branch-and-bound algorithm in MindtPy is implemented based on t In Pyomo, `persistent solvers`_ are necessary to set or register callback functions. The single tree implementation currently only works with CPLEX and GUROBI, more exactly ``cplex_persistent`` and ``gurobi_persistent``. To use the `LazyConstraintCallback`_ function of CPLEX from Pyomo, the `CPLEX Python API`_ is required. This means both IBM ILOG CPLEX Optimization Studio and the CPLEX-Python modules should be installed on your computer. To use the `cbLazy`_ function of GUROBI from pyomo, `gurobipy`_ is required. -.. _`persistent solvers`: https://pyomo.readthedocs.io/en/stable/advanced_topics/persistent_solvers.html?highlight=persistent +.. _`persistent solvers`: https://pyomo.readthedocs.io/en/stable/explanation/solvers/persistent.html .. _CPLEX Python API: https://www.ibm.com/docs/en/icos/20.1.0?topic=cplex-setting-up-python-api .. _gurobipy: https://www.gurobi.com/documentation/9.1/quickstart_mac/cs_grbpy_the_gurobi_python.html .. _LazyConstraintCallback: https://www.ibm.com/docs/en/icos/20.1.0?topic=classes-cplexcallbackslazyconstraintcallback diff --git a/pyomo/contrib/incidence_analysis/README.md b/pyomo/contrib/incidence_analysis/README.md index e998f417be3..6f2442869b5 100644 --- a/pyomo/contrib/incidence_analysis/README.md +++ b/pyomo/contrib/incidence_analysis/README.md @@ -7,7 +7,7 @@ These tools can be used to detect whether and (approximately) why the Jacobian of equality constraints is structurally or numerically singular, which commonly happens as the result of a modeling error. See the -[documentation](https://pyomo.readthedocs.io/en/stable/contributed_packages/incidence/index.html) +[documentation](https://pyomo.readthedocs.io/en/stable/explanation/analysis/incidence/index.html) for more information and examples. ## Dependencies diff --git a/pyomo/contrib/mindtpy/algorithm_base_class.py b/pyomo/contrib/mindtpy/algorithm_base_class.py index e015fc89e09..c91d78d91b7 100644 --- a/pyomo/contrib/mindtpy/algorithm_base_class.py +++ b/pyomo/contrib/mindtpy/algorithm_base_class.py @@ -185,7 +185,7 @@ def _log_solver_intro_message(self): ' Mixed-Integer Nonlinear Decomposition Toolbox in Pyomo (MindtPy) \n' '-----------------------------------------------------------------------------------------------\n' 'For more information, please visit \n' - 'https://pyomo.readthedocs.io/en/stable/contributed_packages/mindtpy.html' + 'https://pyomo.readthedocs.io/en/stable/explanation/solvers/mindtpy.html' ) self.config.logger.info( 'If you use this software, please cite the following:\n' diff --git a/pyomo/contrib/mindtpy/global_outer_approximation.py b/pyomo/contrib/mindtpy/global_outer_approximation.py index c43409a8493..3c162738be5 100644 --- a/pyomo/contrib/mindtpy/global_outer_approximation.py +++ b/pyomo/contrib/mindtpy/global_outer_approximation.py @@ -56,7 +56,7 @@ def check_config(self): if config.mip_solver not in {'cplex_persistent', 'gurobi_persistent'}: raise ValueError( "Only cplex_persistent and gurobi_persistent are supported for LP/NLP based Branch and Bound method." - "Please refer to https://pyomo.readthedocs.io/en/stable/contributed_packages/mindtpy.html#lp-nlp-based-branch-and-bound." + "Please refer to https://pyomo.readthedocs.io/en/stable/explanation/solvers/mindtpy.html#lp-nlp-based-branch-and-bound." ) if config.threads > 1: config.threads = 1 diff --git a/pyomo/contrib/mindtpy/outer_approximation.py b/pyomo/contrib/mindtpy/outer_approximation.py index ead5cadfeac..aee0893e2be 100644 --- a/pyomo/contrib/mindtpy/outer_approximation.py +++ b/pyomo/contrib/mindtpy/outer_approximation.py @@ -63,7 +63,7 @@ def check_config(self): if config.mip_solver not in {'cplex_persistent', 'gurobi_persistent'}: raise ValueError( "Only cplex_persistent and gurobi_persistent are supported for LP/NLP based Branch and Bound method." - "Please refer to https://pyomo.readthedocs.io/en/stable/contributed_packages/mindtpy.html#lp-nlp-based-branch-and-bound." + "Please refer to https://pyomo.readthedocs.io/en/stable/explanation/solvers/mindtpy.html#lp-nlp-based-branch-and-bound." ) if config.threads > 1: config.threads = 1 diff --git a/pyomo/contrib/mpc/README.md b/pyomo/contrib/mpc/README.md index 7e03163f703..27bfa00cfe6 100644 --- a/pyomo/contrib/mpc/README.md +++ b/pyomo/contrib/mpc/README.md @@ -2,7 +2,7 @@ Pyomo MPC is an extension for developing model predictive control simulations using Pyomo models. Please see the -[documentation](https://pyomo.readthedocs.io/en/stable/contributed_packages/mpc/index.html) +[documentation](https://pyomo.readthedocs.io/en/stable/explanation/analysis/mpc/index.html) for more detailed information. Pyomo MPC helps with, among other things, the following use cases: From 4e10fbcb9a5bd9683917717acb45a2047a1c7c95 Mon Sep 17 00:00:00 2001 From: Miranda Mundt Date: Mon, 18 Nov 2024 07:09:23 -0700 Subject: [PATCH 2/4] One more missed URL --- doc/OnlineDocs/explanation/analysis/doe/doe.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/OnlineDocs/explanation/analysis/doe/doe.rst b/doc/OnlineDocs/explanation/analysis/doe/doe.rst index a48f4546ab0..7bc2a2d1cac 100644 --- a/doc/OnlineDocs/explanation/analysis/doe/doe.rst +++ b/doc/OnlineDocs/explanation/analysis/doe/doe.rst @@ -116,7 +116,7 @@ In order to solve problems of the above, Pyomo.DoE implements the 2-stage stocha Pyomo.DoE Required Inputs -------------------------------- -The required input to the Pyomo.DoE solver is an ``Experiment`` object. The experiment object must have a ``get_labeled_model`` function which returns a Pyomo model with four ``Suffix`` components identifying the parts of the model used in MBDoE analysis. This is in line with the convention used in the parameter estimation tool, `Parmest `_. The four ``Suffix`` components are: +The required input to the Pyomo.DoE solver is an ``Experiment`` object. The experiment object must have a ``get_labeled_model`` function which returns a Pyomo model with four ``Suffix`` components identifying the parts of the model used in MBDoE analysis. This is in line with the convention used in the parameter estimation tool, `Parmest `_. The four ``Suffix`` components are: * ``experiment_inputs`` - The experimental design decisions * ``experiment_outputs`` - The values measured during the experiment From 0528cfc541237c7f26c68111666a8161a9fdeaaf Mon Sep 17 00:00:00 2001 From: John Siirola Date: Mon, 18 Nov 2024 10:35:38 -0700 Subject: [PATCH 3/4] Convert internal documentation references from URL to :ref: --- doc/OnlineDocs/explanation/analysis/doe/doe.rst | 4 ++-- doc/OnlineDocs/explanation/analysis/parmest/index.rst | 6 ++++-- doc/OnlineDocs/explanation/solvers/mcpp.rst | 2 ++ doc/OnlineDocs/explanation/solvers/mindtpy.rst | 8 +++----- doc/OnlineDocs/explanation/solvers/persistent.rst | 2 ++ doc/OnlineDocs/explanation/solvers/pyros.rst | 2 +- doc/OnlineDocs/getting_started/installation.rst | 2 ++ 7 files changed, 16 insertions(+), 10 deletions(-) diff --git a/doc/OnlineDocs/explanation/analysis/doe/doe.rst b/doc/OnlineDocs/explanation/analysis/doe/doe.rst index 7bc2a2d1cac..f80878b67eb 100644 --- a/doc/OnlineDocs/explanation/analysis/doe/doe.rst +++ b/doc/OnlineDocs/explanation/analysis/doe/doe.rst @@ -26,7 +26,7 @@ Pyomo.DoE provides the exploratory analysis and MBDoE capabilities to the Pyomo the allowable design spaces for design variables, and the assumed observation error model. During exploratory analysis, Pyomo.DoE checks if the model parameters can be inferred from the postulated measurements or preliminary data. MBDoE then recommends optimized experimental conditions for collecting more data. -Parameter estimation packages such as `Parmest `_ can perform parameter estimation using the available data to infer values for parameters, +Parameter estimation packages such as :ref:`Parmest ` can perform parameter estimation using the available data to infer values for parameters, and facilitate an uncertainty analysis to approximate the parameter covariance matrix. If the parameter uncertainties are sufficiently small, the workflow terminates and returns the final model with quantified parametric uncertainty. If not, MBDoE recommends optimized experimental conditions to generate new data. @@ -116,7 +116,7 @@ In order to solve problems of the above, Pyomo.DoE implements the 2-stage stocha Pyomo.DoE Required Inputs -------------------------------- -The required input to the Pyomo.DoE solver is an ``Experiment`` object. The experiment object must have a ``get_labeled_model`` function which returns a Pyomo model with four ``Suffix`` components identifying the parts of the model used in MBDoE analysis. This is in line with the convention used in the parameter estimation tool, `Parmest `_. The four ``Suffix`` components are: +The required input to the Pyomo.DoE solver is an ``Experiment`` object. The experiment object must have a ``get_labeled_model`` function which returns a Pyomo model with four ``Suffix`` components identifying the parts of the model used in MBDoE analysis. This is in line with the convention used in the parameter estimation tool, :ref:`Parmest `. The four ``Suffix`` components are: * ``experiment_inputs`` - The experimental design decisions * ``experiment_outputs`` - The values measured during the experiment diff --git a/doc/OnlineDocs/explanation/analysis/parmest/index.rst b/doc/OnlineDocs/explanation/analysis/parmest/index.rst index 71aad8a0131..4616a2134d4 100644 --- a/doc/OnlineDocs/explanation/analysis/parmest/index.rst +++ b/doc/OnlineDocs/explanation/analysis/parmest/index.rst @@ -1,5 +1,7 @@ -Parameter Estimation with ``parmest`` -===================================== +.. _parmest: + +Parameter Estimation +==================== ``parmest`` is a Python package built on the Pyomo optimization modeling language ([Pyomo-paper]_, [PyomoBookIII]_) to support parameter estimation using experimental data along with diff --git a/doc/OnlineDocs/explanation/solvers/mcpp.rst b/doc/OnlineDocs/explanation/solvers/mcpp.rst index 18cea7f9b20..b25868e37ad 100644 --- a/doc/OnlineDocs/explanation/solvers/mcpp.rst +++ b/doc/OnlineDocs/explanation/solvers/mcpp.rst @@ -1,3 +1,5 @@ +.. _MC++: + MC++ Interface ============== diff --git a/doc/OnlineDocs/explanation/solvers/mindtpy.rst b/doc/OnlineDocs/explanation/solvers/mindtpy.rst index bb47315fc70..38798a0183c 100644 --- a/doc/OnlineDocs/explanation/solvers/mindtpy.rst +++ b/doc/OnlineDocs/explanation/solvers/mindtpy.rst @@ -11,7 +11,7 @@ The following algorithms are currently available in MindtPy: - **Outer-Approximation (OA)** [`Duran & Grossmann, 1986`_] - **LP/NLP based Branch-and-Bound (LP/NLP BB)** [`Quesada & Grossmann, 1992`_] - **Extended Cutting Plane (ECP)** [`Westerlund & Petterson, 1995`_] -- **Global Outer-Approximation (GOA)** [`Kesavan & Allgor, 2004`_, `MC++`_] +- **Global Outer-Approximation (GOA)** [`Kesavan & Allgor, 2004`_] - **Regularized Outer-Approximation (ROA)** [`Bernal & Peng, 2021`_, `Kronqvist & Bernal, 2018`_] - **Feasibility Pump (FP)** [`Bernal & Vigerske, 2019`_, `Bonami & Cornuéjols, 2009`_] @@ -26,7 +26,6 @@ at Purdue University and Carnegie Mellon University. .. _Duran & Grossmann, 1986: https://dx.doi.org/10.1007/BF02592064 .. _Westerlund & Petterson, 1995: http://dx.doi.org/10.1016/0098-1354(95)87027-X .. _Kesavan & Allgor, 2004: https://link.springer.com/article/10.1007/s10107-004-0503-1 -.. _MC++: https://pyomo.readthedocs.io/en/stable/explanation/solvers/mcpp.html .. _Bernal & Peng, 2021: http://www.optimization-online.org/DB_HTML/2021/06/8452.html .. _Kronqvist & Bernal, 2018: https://link.springer.com/article/10.1007%2Fs10107-018-1356-3 .. _Bonami & Cornuéjols, 2009: https://link.springer.com/article/10.1007/s10107-008-0212-2 @@ -130,9 +129,8 @@ The LP/NLP based branch-and-bound algorithm in MindtPy is implemented based on t .. note:: - In Pyomo, `persistent solvers`_ are necessary to set or register callback functions. The single tree implementation currently only works with CPLEX and GUROBI, more exactly ``cplex_persistent`` and ``gurobi_persistent``. To use the `LazyConstraintCallback`_ function of CPLEX from Pyomo, the `CPLEX Python API`_ is required. This means both IBM ILOG CPLEX Optimization Studio and the CPLEX-Python modules should be installed on your computer. To use the `cbLazy`_ function of GUROBI from pyomo, `gurobipy`_ is required. + In Pyomo, :ref:`persistent solvers ` are necessary to set or register callback functions. The single tree implementation currently only works with CPLEX and GUROBI, more exactly ``cplex_persistent`` and ``gurobi_persistent``. To use the `LazyConstraintCallback`_ function of CPLEX from Pyomo, the `CPLEX Python API`_ is required. This means both IBM ILOG CPLEX Optimization Studio and the CPLEX-Python modules should be installed on your computer. To use the `cbLazy`_ function of GUROBI from pyomo, `gurobipy`_ is required. -.. _`persistent solvers`: https://pyomo.readthedocs.io/en/stable/explanation/solvers/persistent.html .. _CPLEX Python API: https://www.ibm.com/docs/en/icos/20.1.0?topic=cplex-setting-up-python-api .. _gurobipy: https://www.gurobi.com/documentation/9.1/quickstart_mac/cs_grbpy_the_gurobi_python.html .. _LazyConstraintCallback: https://www.ibm.com/docs/en/icos/20.1.0?topic=classes-cplexcallbackslazyconstraintcallback @@ -257,7 +255,7 @@ Augmented Penalty refers to the introduction of (non-negative) slack variables o Global Outer-Approximation ^^^^^^^^^^^^^^^^^^^^^^^^^^ -Apart from the decomposition methods for convex MINLP problems [`Kronqvist et al., 2019`_], MindtPy provides an implementation of Global Outer Approximation (GOA) as described in [`Kesavan & Allgor, 2004`_], to provide optimality guaranteed for nonconvex MINLP problems. Here, the validity of the Mixed-integer Linear Programming relaxation of the original problem is guaranteed via the usage of Generalized McCormick envelopes, computed using the package `MC++`_. The NLP subproblems, in this case, need to be solved to global optimality, which can be achieved through global NLP solvers such as `BARON`_ or `SCIP`_. +Apart from the decomposition methods for convex MINLP problems [`Kronqvist et al., 2019`_], MindtPy provides an implementation of Global Outer Approximation (GOA) as described in [`Kesavan & Allgor, 2004`_], to provide optimality guaranteed for nonconvex MINLP problems. Here, the validity of the Mixed-integer Linear Programming relaxation of the original problem is guaranteed via the usage of Generalized McCormick envelopes, computed using the :ref:`interface to the MC++ package `. The NLP subproblems, in this case, need to be solved to global optimality, which can be achieved through global NLP solvers such as `BARON`_ or `SCIP`_. .. _BARON: https://minlp.com/baron-solver .. _SCIP: https://www.scipopt.org/ diff --git a/doc/OnlineDocs/explanation/solvers/persistent.rst b/doc/OnlineDocs/explanation/solvers/persistent.rst index aebb0545dd0..e926dfd82c9 100644 --- a/doc/OnlineDocs/explanation/solvers/persistent.rst +++ b/doc/OnlineDocs/explanation/solvers/persistent.rst @@ -1,3 +1,5 @@ +.. _persistent_solvers: + Persistent Solvers ================== diff --git a/doc/OnlineDocs/explanation/solvers/pyros.rst b/doc/OnlineDocs/explanation/solvers/pyros.rst index 576b2e60f5b..ad3c99c1c11 100644 --- a/doc/OnlineDocs/explanation/solvers/pyros.rst +++ b/doc/OnlineDocs/explanation/solvers/pyros.rst @@ -118,7 +118,7 @@ PyROS Installation ----------------------------- PyROS can be installed as follows: -1. :doc:`Install Pyomo <../../installation>`. +1. :ref:`Install Pyomo `. PyROS is included in the Pyomo software package, at pyomo/contrib/pyros. 2. Install NumPy and SciPy with your preferred package manager; both NumPy and SciPy are required dependencies of PyROS. diff --git a/doc/OnlineDocs/getting_started/installation.rst b/doc/OnlineDocs/getting_started/installation.rst index e36d83d4f8a..2b9cb6aae07 100644 --- a/doc/OnlineDocs/getting_started/installation.rst +++ b/doc/OnlineDocs/getting_started/installation.rst @@ -1,3 +1,5 @@ +.. _pyomo_installation: + Installation ------------ From 825a7354a9f40d2814e7f4e17796fb20512c54c6 Mon Sep 17 00:00:00 2001 From: John Siirola Date: Mon, 18 Nov 2024 10:36:27 -0700 Subject: [PATCH 4/4] Update docstrings to remove Sphinx warnings --- .../plugins/parameterized_standard_form.py | 21 ++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/pyomo/repn/plugins/parameterized_standard_form.py b/pyomo/repn/plugins/parameterized_standard_form.py index 541b859caab..1d9c5a301b2 100644 --- a/pyomo/repn/plugins/parameterized_standard_form.py +++ b/pyomo/repn/plugins/parameterized_standard_form.py @@ -32,13 +32,28 @@ 'bilevel optimization problem).', ) class ParameterizedLinearStandardFormCompiler(LinearStandardFormCompiler): + r"""Compiler to convert a "Parameterized" LP to the matrix representation + of the standard form: + + .. math:: + + \min\ & c^Tx \\ + s.t.\ & Ax \le b + + by treating the variables specified in the ``wrt`` list as data + (constants). The resulting compiled representation is returned as + NumPy arrays and SciPy sparse matrices in a + :py:class:`LinearStandardFormInfo` . + + """ + CONFIG = LinearStandardFormCompiler.CONFIG() CONFIG.declare( 'wrt', ConfigValue( default=None, domain=ComponentDataSet(Var), - description="Vars to treat as data for the purposes of compiling" + description="Vars to treat as data for the purposes of compiling " "the standard form", doc=""" Optional list of Vars to be treated as data while compiling the @@ -54,8 +69,8 @@ class ParameterizedLinearStandardFormCompiler(LinearStandardFormCompiler): @document_kwargs_from_configdict(CONFIG) def write(self, model, ostream=None, **options): - """Convert a model to standard form (`min cTx s.t. Ax <= b`) treating the - Vars specified in 'wrt' as data + r"""Convert a model to standard form treating the Vars specified in + ``wrt`` as data. Returns -------