Merge branch 'main' of https://github.com/Pyomo/pyomo into parmest-re…

…design
kaklise · Apr 30, 2024 · cedef5d · cedef5d
2 parents 539d62d + 6393961
commit cedef5d
Show file tree

Hide file tree

Showing 204 changed files with 3,891 additions and 2,560 deletions.
diff --git a/.github/workflows/test_branches.yml b/.github/workflows/test_branches.yml
@@ -40,7 +40,8 @@ jobs:
         python-version: '3.10'
     - name: Black Formatting Check
       run: |
-        pip install black
+        # Note v24.4.1 fails due to a bug in the parser
+        pip install 'black!=24.4.1'
         black . -S -C --check --diff --exclude examples/pyomobook/python-ch/BadIndent.py
     - name: Spell Check
       uses: crate-ci/typos@master
@@ -92,7 +93,7 @@ jobs:
           skip_doctest: 1
           TARGET: linux
           PYENV: conda
-          PACKAGES: mpi4py
+          PACKAGES: openmpi mpi4py
 
         - os: ubuntu-latest
           python: '3.10'

diff --git a/.github/workflows/test_pr_and_main.yml b/.github/workflows/test_pr_and_main.yml
@@ -7,6 +7,11 @@ on:
   pull_request:
     branches:
       - main
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
   workflow_dispatch:
     inputs:
       git-ref:
@@ -34,6 +39,8 @@ jobs:
   lint:
     name: lint/style-and-typos
     runs-on: ubuntu-latest
+    if: |
+      contains(github.event.pull_request.title, '[WIP]') != true && !github.event.pull_request.draft
     steps:
     - name: Checkout Pyomo source
       uses: actions/checkout@v4
@@ -43,7 +50,8 @@ jobs:
         python-version: '3.10'
     - name: Black Formatting Check
       run: |
-        pip install black
+        # Note v24.4.1 fails due to a bug in the parser
+        pip install 'black!=24.4.1'
         black . -S -C --check --diff --exclude examples/pyomobook/python-ch/BadIndent.py
     - name: Spell Check
       uses: crate-ci/typos@master
@@ -93,7 +101,7 @@ jobs:
           skip_doctest: 1
           TARGET: linux
           PYENV: conda
-          PACKAGES: mpi4py
+          PACKAGES: openmpi mpi4py
 
         - os: ubuntu-latest
           python: '3.11'
@@ -733,7 +741,7 @@ jobs:
   cover:
     name: process-coverage-${{ matrix.TARGET }}
     needs: build
-    if: always() # run even if a build job fails
+    if: success() || failure() # run even if a build job fails, but not if cancelled
     runs-on: ${{ matrix.os }}
     timeout-minutes: 10
     strategy:

diff --git a/.github/workflows/typos.toml b/.github/workflows/typos.toml
@@ -40,4 +40,28 @@ WRONLY = "WRONLY"
 Hax = "Hax"
 # Big Sur
 Sur = "Sur"
+# Ignore the shorthand ans for answer
+ans = "ans"
+# Ignore the keyword arange
+arange = "arange"
+# Ignore IIS
+IIS = "IIS"
+iis = "iis"
+# Ignore PN
+PN = "PN"
+# Ignore hd
+hd = "hd"
+# Ignore opf
+opf = "opf"
+# Ignore FRE
+FRE = "FRE"
+# Ignore MCH
+MCH = "MCH"
+# Ignore RO
+ro = "ro"
+RO = "RO"
+# Ignore EOF - end of file
+EOF = "EOF"
+# Ignore lst as shorthand for list
+lst = "lst"
 # AS NEEDED: Add More Words Below
diff --git a/README.md b/README.md
@@ -71,6 +71,7 @@ version, we will remove testing for that Python version.
 
 ### Tutorials and Examples
 
+* [Pyomo — Optimization Modeling in Python](https://link.springer.com/book/10.1007/978-3-030-68928-5)
 * [Pyomo Workshop Slides](https://github.com/Pyomo/pyomo-tutorials/blob/main/Pyomo-Workshop-December-2023.pdf)
 * [Prof. Jeffrey Kantor's Pyomo Cookbook](https://jckantor.github.io/ND-Pyomo-Cookbook/)
 * The [companion notebooks](https://mobook.github.io/MO-book/intro.html)

diff --git a/doc/OnlineDocs/bibliography.rst b/doc/OnlineDocs/bibliography.rst
@@ -39,6 +39,8 @@ Bibliography
                   John D. Siirola, Jean-Paul Watson, and David L. Woodruff.
                   Pyomo - Optimization Modeling in Python, 3rd Edition.
                   Vol. 67. Springer, 2021.
+                  doi: `10.1007/978-3-030-68928-5
+                  <https://doi.org/10.1007/978-3-030-68928-5>`_
 
 .. [PyomoJournal] William E. Hart, Jean-Paul Watson, David L. Woodruff.
                   "Pyomo: modeling and solving mathematical programs in

diff --git a/doc/OnlineDocs/contributed_packages/pynumero/backward_compatibility.rst b/doc/OnlineDocs/contributed_packages/pynumero/backward_compatibility.rst
@@ -0,0 +1,14 @@
+Backward Compatibility
+======================
+
+While PyNumero is a third-party contribution to Pyomo, we intend to maintain
+the stability of its core functionality. The core functionality of PyNumero
+consists of:
+
+1. The ``NLP`` API and ``PyomoNLP`` implementation of this API
+2. HSL and MUMPS linear solver interfaces
+3. ``BlockVector`` and ``BlockMatrix`` classes
+4. CyIpopt and SciPy solver interfaces
+
+Other parts of PyNumero, such as ``ExternalGreyBoxBlock`` and
+``ImplicitFunctionSolver``, are experimental and subject to change without notice.
diff --git a/doc/OnlineDocs/contributed_packages/pynumero/index.rst b/doc/OnlineDocs/contributed_packages/pynumero/index.rst
@@ -13,6 +13,7 @@ PyNumero. For more details, see the API documentation (:ref:`pynumero_api`).
    installation.rst
    tutorial.rst
    api.rst
+   backward_compatibility.rst
 
 
 Developers

diff --git a/doc/OnlineDocs/contributed_packages/pyros.rst b/doc/OnlineDocs/contributed_packages/pyros.rst
@@ -903,10 +903,10 @@ Observe that the log contains the following information:
    :linenos:
 
    ==============================================================================
-   PyROS: The Pyomo Robust Optimization Solver, v1.2.9.
-          Pyomo version: 6.7.0
+   PyROS: The Pyomo Robust Optimization Solver, v1.2.11.
+          Pyomo version: 6.7.2
           Commit hash: unknown
-          Invoked at UTC 2023-12-16T00:00:00.000000
+          Invoked at UTC 2024-03-28T00:00:00.000000
 
    Developed by: Natalie M. Isenberg (1), Jason A. F. Sherman (1),
                  John D. Siirola (2), Chrysanthos E. Gounaris (1)
@@ -926,6 +926,7 @@ Observe that the log contains the following information:
     keepfiles=False
     tee=False
     load_solution=True
+    symbolic_solver_labels=False
     objective_focus=<ObjectiveType.worst_case: 1>
     nominal_uncertain_param_vals=[0.13248000000000001, 4.97, 4.97, 1800]
     decision_rule_order=1

diff --git a/doc/OnlineDocs/contribution_guide.rst b/doc/OnlineDocs/contribution_guide.rst
@@ -71,6 +71,10 @@ at least 70% coverage of the lines modified in the PR and prefer coverage
 closer to 90%. We also require that all tests pass before a PR will be 
 merged.
 
+.. note::
+   If you are having issues getting tests to pass on your Pull Request,
+   please tag any of the core developers to ask for help.
+
 The Pyomo main branch provides a Github Actions workflow (configured
 in the ``.github/`` directory) that will test any changes pushed to
 a branch with a subset of the complete test harness that includes
@@ -82,13 +86,16 @@ This will enable the tests to run automatically with each push to your fork.
 
 At any point in the development cycle, a "work in progress" pull request
 may be opened by including '[WIP]' at the beginning of the PR
-title. This allows your code changes to be tested by the full suite of
-Pyomo's automatic
-testing infrastructure. Any pull requests marked '[WIP]' will not be
+title. Any pull requests marked '[WIP]' or draft will not be
 reviewed or merged by the core development team. However, any
 '[WIP]' pull request left open for an extended period of time without
 active development may be marked 'stale' and closed.
 
+.. note::
+   Draft and WIP Pull Requests will **NOT** trigger tests. This is an effort to
+   reduce our CI backlog. Please make use of the provided
+   branch test suite for evaluating / testing draft functionality.
+
 Python Version Support
 ++++++++++++++++++++++
 

diff --git a/doc/OnlineDocs/developer_reference/solvers.rst b/doc/OnlineDocs/developer_reference/solvers.rst
@@ -84,6 +84,37 @@ be used with other Pyomo tools / capabilities.
    ...
    3 Declarations: x y obj
 
+In keeping with our commitment to backwards compatibility, both the legacy and
+future methods of specifying solver options are supported:
+
+.. testcode::
+   :skipif: not ipopt_available
+
+   import pyomo.environ as pyo
+
+   model = pyo.ConcreteModel()
+   model.x = pyo.Var(initialize=1.5)
+   model.y = pyo.Var(initialize=1.5)
+
+   def rosenbrock(model):
+       return (1.0 - model.x) ** 2 + 100.0 * (model.y - model.x**2) ** 2
+
+   model.obj = pyo.Objective(rule=rosenbrock, sense=pyo.minimize)
+
+   # Backwards compatible
+   status = pyo.SolverFactory('ipopt_v2').solve(model, options={'max_iter' : 6})
+   # Forwards compatible
+   status = pyo.SolverFactory('ipopt_v2').solve(model, solver_options={'max_iter' : 6})
+   model.pprint()
+
+.. testoutput::
+   :skipif: not ipopt_available
+   :hide:
+
+   2 Var Declarations
+   ...
+   3 Declarations: x y obj
+
 Using the new interfaces directly
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/doc/OnlineDocs/installation.rst b/doc/OnlineDocs/installation.rst
@@ -12,7 +12,7 @@ version, Pyomo will remove testing for that Python version.
 Using CONDA
 ~~~~~~~~~~~
 
-We recommend installation with *conda*, which is included with the
+We recommend installation with ``conda``, which is included with the
 Anaconda distribution of Python. You can install Pyomo in your system
 Python installation by executing the following in a shell:
 
@@ -21,7 +21,7 @@ Python installation by executing the following in a shell:
    conda install -c conda-forge pyomo
 
 Optimization solvers are not installed with Pyomo, but some open source
-optimization solvers can be installed with conda as well:
+optimization solvers can be installed with ``conda`` as well:
 
 ::
 
@@ -31,7 +31,7 @@ optimization solvers can be installed with conda as well:
 Using PIP
 ~~~~~~~~~
 
-The standard utility for installing Python packages is *pip*.  You
+The standard utility for installing Python packages is ``pip``.  You
 can install Pyomo in your system Python installation by executing
 the following in a shell:
 
@@ -43,14 +43,14 @@ the following in a shell:
 Conditional Dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Extensions to Pyomo, and many of the contributions in `pyomo.contrib`,
+Extensions to Pyomo, and many of the contributions in ``pyomo.contrib``,
 often have conditional dependencies on a variety of third-party Python
 packages including but not limited to: matplotlib, networkx, numpy,
 openpyxl, pandas, pint, pymysql, pyodbc, pyro4, scipy, sympy, and
 xlrd. 
 
 A full list of conditional dependencies can be found in Pyomo's
-`setup.py` and displayed using:
+``setup.py`` and displayed using:
 
 ::
 
@@ -72,3 +72,28 @@ with the standard Anaconda installation.
 You can check which Python packages you have installed using the command
 ``conda list`` or ``pip list``. Additional Python packages may be
 installed as needed.
+
+
+Installation with Cython
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can opt to install Pyomo with
+`cython <https://cython.readthedocs.io/en/latest/src/tutorial/cython_tutorial.html>`_
+initialized.
+
+.. note::
+   This can only be done via ``pip`` or from source.
+
+Via ``pip``:
+
+::
+
+   pip install pyomo --global-option="--with-cython"
+
+From source (recommended for advanced users only):
+
+::
+
+   git clone https://github.com/Pyomo/pyomo.git
+   cd pyomo
+   python setup.py install --with-cython
diff --git a/doc/OnlineDocs/library_reference/common/enums.rst b/doc/OnlineDocs/library_reference/common/enums.rst
@@ -0,0 +1,7 @@
+
+pyomo.common.enums
+==================
+
+.. automodule:: pyomo.common.enums
+   :members:
+   :member-order: bysource
diff --git a/doc/OnlineDocs/library_reference/common/index.rst b/doc/OnlineDocs/library_reference/common/index.rst
@@ -11,6 +11,7 @@ or rely on any other parts of Pyomo.
    config.rst
    dependencies.rst
    deprecation.rst
+   enums.rst
    errors.rst
    fileutils.rst
    formatting.rst

diff --git a/doc/OnlineDocs/tutorial_examples.rst b/doc/OnlineDocs/tutorial_examples.rst
@@ -3,15 +3,18 @@ Pyomo Tutorial Examples
 
 Additional Pyomo tutorials and examples can be found at the following links:
 
-`Pyomo Workshop Slides and Exercises
-<https://github.com/Pyomo/pyomo-tutorials>`_
+* `Pyomo — Optimization Modeling in Python
+  <https://link.springer.com/book/10.1007/978-3-030-68928-5>`_ ([PyomoBookIII]_)
 
-`Prof. Jeffrey Kantor's Pyomo Cookbook
-<https://jckantor.github.io/ND-Pyomo-Cookbook/>`_
+* `Pyomo Workshop Slides and Exercises
+  <https://github.com/Pyomo/pyomo-tutorials>`_
 
-The `companion notebooks <https://mobook.github.io/MO-book/intro.html>`_
-for *Hands-On Mathematical Optimization with Python*
+* `Prof. Jeffrey Kantor's Pyomo Cookbook
+  <https://jckantor.github.io/ND-Pyomo-Cookbook/>`_
 
-`Pyomo Gallery <https://github.com/Pyomo/PyomoGallery>`_
+* The `companion notebooks <https://mobook.github.io/MO-book/intro.html>`_
+  for *Hands-On Mathematical Optimization with Python*
+
+* `Pyomo Gallery <https://github.com/Pyomo/PyomoGallery>`_
 
 
diff --git a/examples/pyomobook/pyomo-components-ch/obj_declaration.txt b/examples/pyomobook/pyomo-components-ch/obj_declaration.txt
@@ -55,7 +55,7 @@ Model unknown
     None
 value
 x[Q] + 2*x[R]
-1
+minimize
 6.5
 Model unknown