Merge branch 'parmest-doc-update' of https://github.com/slilonfe5/pyomo into parmest-doc-update

Author: slilonfe5

.github/workflows/test_branches.yml

@@ -99,7 +99,7 @@ jobs:
           PYENV: pip
 
         - os: windows-latest
-          python: 3.12
+          python: 3.14
           test_docs: 1
           TARGET: win
           PYENV: conda
@@ -236,8 +236,11 @@ jobs:
       if: matrix.PYENV == 'conda'
       uses: conda-incubator/setup-miniconda@v3
       with:
+        conda-remove-defaults: true
         auto-update-conda: false
         python-version: ${{ matrix.python }}
+        channels: conda-forge, gurobi, ibmdecisionoptimization, fico-xpress
+        use-mamba: true
 
     # This is necessary for qt (UI) tests; the package utilized here does not
     # have support for OSX.
@@ -317,27 +320,7 @@ jobs:
       run: |
         # Set up environment
         conda config --set always_yes yes
-        conda config --set auto_update_conda false
         conda config --set channel_priority strict
-        conda config --remove channels defaults
-        conda config --append channels nodefaults
-        conda config --append channels conda-forge
-        # Try to install mamba
-        CONDA_VER=$(conda --version | cut -d\  -f2)
-        if test 23.10 = "`echo -e "23.10\n$CONDA_VER" | sort -V | tail -1`"; then
-            # Note: removed '--update-deps' on 2025-02-28 to work around
-            #       broken libffi(?)
-            conda install -q -y -n base conda-libmamba-solver \
-                || MAMBA_FAILED=1
-            if test -z "$MAMBA_FAILED"; then
-                echo "*** Activating the mamba environment solver ***"
-                conda config --set solver libmamba
-            fi
-        fi
-        # Add the rest of the channels
-        conda config --append channels gurobi
-        conda config --append channels ibmdecisionoptimization
-        conda config --append channels fico-xpress
         # Print environment info
         echo "*** CONDA environment: ***"
         conda info
@@ -375,10 +358,8 @@ jobs:
         echo ""
         echo "*** Install Pyomo dependencies ***"
         # For windows, cannot use newer setuptools because of APPSI compilation issues
-        # There seems to be some specific problem with platformdirs 4.5.0
-        # on win 3.13/3.14 as of 2025-10-23
         if test "${{matrix.TARGET}}" == 'win'; then
-            CONDA_DEPENDENCIES="$CONDA_DEPENDENCIES setuptools<74.0.0 platformdirs!=4.5.0"
+            CONDA_DEPENDENCIES="$CONDA_DEPENDENCIES setuptools<74.0.0"
         fi
         # Note: this will fail the build if any installation fails (or
         # possibly if it outputs messages to stderr)

.github/workflows/test_pr_and_main.yml

@@ -93,8 +93,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        # FIXME: pinning to 3.14.0 until 3.14.1 is removed from runner tool cache
-        python: [ '3.10', 3.11, 3.12, 3.13, 3.14.0 ]
+        python: [ '3.10', 3.11, 3.12, 3.13, 3.14 ]
         other: [""]
         category: [""]
 
@@ -289,8 +288,11 @@ jobs:
       if: matrix.PYENV == 'conda'
       uses: conda-incubator/setup-miniconda@v3
       with:
+        conda-remove-defaults: true
         auto-update-conda: false
         python-version: ${{ matrix.python }}
+        channels: conda-forge, gurobi, ibmdecisionoptimization, fico-xpress
+        use-mamba: true
 
     # This is necessary for qt (UI) tests; the package utilized here does not
     # have support for OSX.
@@ -370,27 +372,7 @@ jobs:
       run: |
         # Set up environment
         conda config --set always_yes yes
-        conda config --set auto_update_conda false
         conda config --set channel_priority strict
-        conda config --remove channels defaults
-        conda config --append channels nodefaults
-        conda config --append channels conda-forge
-        # Try to install mamba
-        CONDA_VER=$(conda --version | cut -d\  -f2)
-        if test 23.10 = "`echo -e "23.10\n$CONDA_VER" | sort -V | tail -1`"; then
-            # Note: removed '--update-deps' on 2025-02-28 to work around
-            #       broken libffi(?)
-            conda install -q -y -n base conda-libmamba-solver \
-                || MAMBA_FAILED=1
-            if test -z "$MAMBA_FAILED"; then
-                echo "*** Activating the mamba environment solver ***"
-                conda config --set solver libmamba
-            fi
-        fi
-        # Add the rest of the channels
-        conda config --append channels gurobi
-        conda config --append channels ibmdecisionoptimization
-        conda config --append channels fico-xpress
         # Print environment info
         echo "*** CONDA environment: ***"
         conda info
@@ -428,10 +410,8 @@ jobs:
         echo ""
         echo "*** Install Pyomo dependencies ***"
         # For windows, cannot use newer setuptools because of APPSI compilation issues
-        # There seems to be some specific problem with platformdirs 4.5.0
-        # on win 3.13/3.14 as of 2025-10-23
         if test "${{matrix.TARGET}}" == 'win'; then
-            CONDA_DEPENDENCIES="$CONDA_DEPENDENCIES setuptools<74.0.0 platformdirs!=4.5.0"
+            CONDA_DEPENDENCIES="$CONDA_DEPENDENCIES setuptools<74.0.0"
         fi
         # Note: this will fail the build if any installation fails (or
         # possibly if it outputs messages to stderr)

.github/workflows/typos.toml

@@ -75,4 +75,10 @@ gam = "gam"
 ond = "ond"
 # GAMS_writer
 PATHC = "PATHC"
+# Bimap - tries to correct to Bitmap
+Bimap = "Bimap"
+# cmo - tries to correct to com
+cmo = "cmo"
+# Substituters
+Substituters = "Substituters"
 # AS NEEDED: Add More Words Below

doc/OnlineDocs/explanation/analysis/parmest/covariance.rst

@@ -3,7 +3,7 @@
 Covariance Matrix Estimation
 ============================
 
-The goal is parameter estimation (see :ref:`driversection` Section) is to estimate unknown model parameters
+The goal of parameter estimation (see :ref:`driversection` Section) is to estimate unknown model parameters
 from experimental data. When the model parameters are estimated from the data, their accuracy is measured by
 computing the covariance matrix. The diagonal of this covariance matrix contains the variance of the
 estimated parameters which is used to calculate their uncertainty. Assuming Gaussian independent and identically

doc/OnlineDocs/explanation/analysis/parmest/datarec.rst

@@ -44,8 +44,8 @@ The following example returns model values from a Pyomo Expression.
 
    >>> # Define objective
    >>> def SSE(model):
-   ...     expr = (model.experiment_outputs[model.y[model.hour]]
-   ...             - model.y[model.hour]
+   ...     expr = (model.experiment_outputs[model.y]
+   ...             - model.y
    ...            ) ** 2
    ...     return expr
 

doc/OnlineDocs/explanation/analysis/parmest/driver.rst

@@ -82,15 +82,12 @@ required packages for parameter estimation in parmest:
 Step 1: Create the Experiment Class for the Model
 -------------------------------------------------
 
-parmest requires that the user creates an :class:`~pyomo.contrib.parmest.experiment.Experiment` class that
-contains the annotated Pyomo model with labeled experiment outputs, unknown parameters, and measurement errors.
+parmest requires that the user create an :class:`~pyomo.contrib.parmest.experiment.Experiment` class that
+builds an annotated Pyomo model denoting experiment outputs, unknown parameters, and measurement errors using Pyomo `Suffix` components.
 
-A labeled Pyomo model ``m`` has the following additional suffixes (Pyomo `Suffix`):
-
-* ``m.experiment_outputs`` which defines experiment output (Pyomo `Param`, `Var`, or `Expression`)
-  and their associated data values (float, int).
-* ``m.unknown_parameters`` which defines the mutable parameters or variables (Pyomo `Param` or `Var`)
-  to estimate along with their component unique identifier (Pyomo `ComponentUID`).
+* ``m.experiment_outputs`` maps the experiment output, or measurement, terms in the model (Pyomo `Param`, `Var`, or `Expression`) to their associated data values (float, int).
+* ``m.unknown_parameters`` maps the model parameters to estimate (Pyomo `Param` or `Var`)
+  to their component unique identifier (Pyomo `ComponentUID`) which is used to identify equivalent parameters across multiple experiments.
   Within parmest, any parameters that are to be estimated are converted to unfixed variables.
   Variables that are to be estimated are also unfixed.
 
@@ -165,12 +162,10 @@ mathematical model outlined in the introduction section of this Quick Start.
     ...         return self.model
 
 
-Step 2: Load the Data and Create a List of the Model's Experiment Class
+Step 2: Load the Data and Create a List Experiments
 -----------------------------------------------------------------------
 
-After creating an :class:`~pyomo.contrib.parmest.experiment.Experiment` class instance for the model, a list of the
-model's :class:`~pyomo.contrib.parmest.experiment.Experiment` class for all the experimental data points should be
-created.
+Load the experimental data into Python and create an instance of your :class:`~pyomo.contrib.parmest.experiment.Experiment` class for each set of experimental data. In this example, each measurement of `y` is treated as a separate experiment.
 
 .. doctest::
 
@@ -240,12 +235,9 @@ Optionally, solver options can be supplied, e.g.,
 Objective function
 ^^^^^^^^^^^^^^^^^^
 
-The second argument is an optional argument if the objective function has already been included in the
-Pyomo model, which defines the optimization objective function to use in parameter estimation. However, if the
-objective function has not been included in the Pyomo model, like the one in the :ref:`ExperimentClass` Section
-above, the user is required to supply the second argument.
+The second argument, ``obj_function``, is used to specify the objective function to use for parameter estimation if the user has not manually defined an objective function in their ``Experiment`` class.
 
-If no objective function is specified, the Pyomo model is used "as is" and
+If ``obj_function`` is not specified, the Pyomo model is used "as is" and
 should be defined with "FirstStageCost" and "SecondStageCost"
 expressions that are used to build an objective for the two-stage 
 stochastic programming problem.
@@ -254,14 +246,14 @@ If the Pyomo model is not written as a two-stage stochastic programming problem
 this format, the user can select the "SSE" or "SSE_weighted" built-in objective
 functions. If the user wants to use an objective that is different from the built-in
 options, a custom objective function can be defined for parameter estimation. However,
-covariance matrix estimation (see :ref:`covariancesection` Section) will not support this
-custom objective function.
+covariance matrix estimation (see :ref:`covariancesection` Section) is not supported
+for custom objective functions.
 
 Parmest includes two built-in objective functions ("SSE" and "SSE_weighted") to compute
 the sum of squared errors between the ``m.experiment_outputs`` model values and
 data values.
 
-Step 3: Estimate the Parameters
+Step 4: Estimate the Parameters
 -------------------------------
 
 After creating the :class:`~pyomo.contrib.parmest.parmest.Estimator` object with the desired objective function,

doc/OnlineDocs/ext/pyomo_autosummary_autoenum.py

@@ -85,18 +85,26 @@ def render(self, name, ns):
 
                 caller = inspect.currentframe().f_back
                 l = caller.f_locals
-                doc = l['doc']
+                if 'obj_type' in l:
+                    # Sphinx >= 9.1.0
+                    doc_field = 'obj_type'
+                else:
+                    doc_field = 'doc'
+                doc = l[doc_field]
                 obj = l['obj']
-                args = {'obj': obj}
+                args = {'obj': obj, doc_field: doc}
                 if '_get_members' in caller.f_globals:
                     _get_members = caller.f_globals['_get_members']
                     if 'config' in l:
                         # Sphinx >= 8.2.1
-                        for field in ('config', 'doc', 'events', 'registry'):
+                        for field in ('config', 'events'):
                             args[field] = l[field]
+                        if 'registry' in l:
+                            # Sphinx < 9.1
+                            args['registry'] = l['registry']
                     else:
                         # Sphinx >= 7.2
-                        args.update({'doc': doc, 'app': l['app']})
+                        args['app'] = l['app']
                 else:
                     # Sphinx < 7.2
                     _get_members = caller.f_locals['get_members']