Merge pull request #3425 from mrmundt/doc-urls

Update Documentation URLs

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 <https://pyomo.readthedocs.io/en/stable/contributed_packages/parmest/index.html>`_ can perform parameter estimation using the available data to infer values for parameters,
+Parameter estimation packages such as :ref:`Parmest <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 <https://pyomo.readthedocs.io/en/stable/contributed_packages/parmest/index.html>`_. 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 <parmest>`. The four ``Suffix`` components are:
 
 * ``experiment_inputs`` - The experimental design decisions
 * ``experiment_outputs`` - The values measured during the experiment

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

doc/OnlineDocs/explanation/solvers/mcpp.rst

@@ -1,3 +1,5 @@
+.. _MC++:
+
 MC++ Interface
 ==============
 

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/contributed_packages/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 <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
 .. _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 <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`_.
 
 .. _BARON: https://minlp.com/baron-solver
 .. _SCIP: https://www.scipopt.org/

doc/OnlineDocs/explanation/solvers/persistent.rst

@@ -1,3 +1,5 @@
+.. _persistent_solvers:
+
 Persistent Solvers
 ==================
 

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 <pyomo_installation>`.
    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.

doc/OnlineDocs/getting_started/installation.rst

@@ -1,3 +1,5 @@
+.. _pyomo_installation:
+
 Installation
 ------------
 

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

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'

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

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

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:

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
         -------