Merging main

IDAES · Jan 25, 2024 · 1e92d90 · 1e92d90
2 parents c4c9f5d + f07552d
commit 1e92d90
Show file tree

Hide file tree

Showing 40 changed files with 3,374 additions and 719 deletions.
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,45 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - name: "IDAES contributors"
+title: "Institute for Design of Advanced Energy Systems (IDAES): advanced computational algorithms to enable the design and optimization of complex, interacting energy and process systems from individual plant components to the entire electrical grid"
+url: "https://github.com/IDAES/idaes-pse"
+license-url: "https://github.com/IDAES/idaes-pse/blob/main/LICENSE.md"
+preferred-citation:
+  type: article
+  authors:
+    - family-names: "Lee"
+      given-names: "Andrew"
+    - family-names: "Ghouse"
+      given-names: "Jaffer H"
+    - family-names: "Eslick"
+      given-names: "John C"
+    - family-names: "Laird"
+      given-names: "Carl D"
+    - family-names: "Siirola"
+      given-names: "John D"
+    - family-names: "Zamarripa"
+      given-names: "Miguel A"
+    - family-names: "Gunter"
+      given-names: "Dan"
+    - family-names: "Shinn"
+      given-names: "John H"
+    - family-names: "Dowling"
+      given-names: "Alexander W"
+    - family-names: "Bhattacharyya"
+      given-names: "Debangsu"
+    - family-names: "Biegler"
+      given-names: "Lorenz T"
+    - family-names: "Burgard"
+      given-names: "Anthony P"
+    - family-names: "Miller"
+      given-names: "David C"
+  title: "The IDAES process modeling framework and model library—Flexibility for process simulation and optimization"
+  journal: "Journal of Advanced Manufacturing and Processing"
+  publisher: "Wiley Online Library"
+  volume: 3
+  number: 3
+  pages: e10095
+  year: 2021
+  doi: "doi/10.1002/amp2.10095"
+
diff --git a/data/config.yaml → dmf_data/config.yaml b/data/config.yaml → dmf_data/config.yaml
diff --git a/...3b0763c5424b8a056f5b0821dc32/pitzer_4.csv → ...3b0763c5424b8a056f5b0821dc32/pitzer_4.csv b/...3b0763c5424b8a056f5b0821dc32/pitzer_4.csv → ...3b0763c5424b8a056f5b0821dc32/pitzer_4.csv
diff --git a/...7ea39cd04decae3a13cb89397255/pitzer_5.csv → ...7ea39cd04decae3a13cb89397255/pitzer_5.csv b/...7ea39cd04decae3a13cb89397255/pitzer_5.csv → ...7ea39cd04decae3a13cb89397255/pitzer_5.csv
diff --git a/...76e4eb33410fa40cbdd155e57d60/pitzer_3.csv → ...76e4eb33410fa40cbdd155e57d60/pitzer_3.csv b/...76e4eb33410fa40cbdd155e57d60/pitzer_3.csv → ...76e4eb33410fa40cbdd155e57d60/pitzer_3.csv
diff --git a/...7bd211c4a5683f6f389f9a762df/pitzer_13.csv → ...7bd211c4a5683f6f389f9a762df/pitzer_13.csv b/...7bd211c4a5683f6f389f9a762df/pitzer_13.csv → ...7bd211c4a5683f6f389f9a762df/pitzer_13.csv
diff --git a/...4089045464db1afad7f5cd384c7/pitzer_14.csv → ...4089045464db1afad7f5cd384c7/pitzer_14.csv b/...4089045464db1afad7f5cd384c7/pitzer_14.csv → ...4089045464db1afad7f5cd384c7/pitzer_14.csv
diff --git a/...319d0fd4b328b4cf53af35301f7/pitzer_16.csv → ...319d0fd4b328b4cf53af35301f7/pitzer_16.csv b/...319d0fd4b328b4cf53af35301f7/pitzer_16.csv → ...319d0fd4b328b4cf53af35301f7/pitzer_16.csv
diff --git a/...2419c7c243059dea2fbac2a991a7/pitzer_2.csv → ...2419c7c243059dea2fbac2a991a7/pitzer_2.csv b/...2419c7c243059dea2fbac2a991a7/pitzer_2.csv → ...2419c7c243059dea2fbac2a991a7/pitzer_2.csv
diff --git a/...4b2994646c1bb5c188aa8f318af/pitzer_10.csv → ...4b2994646c1bb5c188aa8f318af/pitzer_10.csv b/...4b2994646c1bb5c188aa8f318af/pitzer_10.csv → ...4b2994646c1bb5c188aa8f318af/pitzer_10.csv
diff --git a/...1700e67446887efccafd43015da/pitzer_12.csv → ...1700e67446887efccafd43015da/pitzer_12.csv b/...1700e67446887efccafd43015da/pitzer_12.csv → ...1700e67446887efccafd43015da/pitzer_12.csv
diff --git a/...3a7a54fcf99d3a8bfe925ab19/Pitzer_1984.pdf → ...3a7a54fcf99d3a8bfe925ab19/Pitzer_1984.pdf b/...3a7a54fcf99d3a8bfe925ab19/Pitzer_1984.pdf → ...3a7a54fcf99d3a8bfe925ab19/Pitzer_1984.pdf
diff --git a/...8a43c8134ba2b11235b0fb475a68/pitzer_1.csv → ...8a43c8134ba2b11235b0fb475a68/pitzer_1.csv b/...8a43c8134ba2b11235b0fb475a68/pitzer_1.csv → ...8a43c8134ba2b11235b0fb475a68/pitzer_1.csv
diff --git a/...f86d2cf3439a9dfbe71f5ca468c4/pitzer_8.csv → ...f86d2cf3439a9dfbe71f5ca468c4/pitzer_8.csv b/...f86d2cf3439a9dfbe71f5ca468c4/pitzer_8.csv → ...f86d2cf3439a9dfbe71f5ca468c4/pitzer_8.csv
diff --git a/...9646005e45af98e94990648eef5f/pitzer_9.csv → ...9646005e45af98e94990648eef5f/pitzer_9.csv b/...9646005e45af98e94990648eef5f/pitzer_9.csv → ...9646005e45af98e94990648eef5f/pitzer_9.csv
diff --git a/...a0a466a24a4a9f5f7c9ef6809355/pitzer_6.csv → ...a0a466a24a4a9f5f7c9ef6809355/pitzer_6.csv b/...a0a466a24a4a9f5f7c9ef6809355/pitzer_6.csv → ...a0a466a24a4a9f5f7c9ef6809355/pitzer_6.csv
diff --git a/...e45d9e54011ad7f45506cd943d9/pitzer_17.csv → ...e45d9e54011ad7f45506cd943d9/pitzer_17.csv b/...e45d9e54011ad7f45506cd943d9/pitzer_17.csv → ...e45d9e54011ad7f45506cd943d9/pitzer_17.csv
diff --git a/...996b34d24048891713a8d3a1be71/pitzer_7.csv → ...996b34d24048891713a8d3a1be71/pitzer_7.csv b/...996b34d24048891713a8d3a1be71/pitzer_7.csv → ...996b34d24048891713a8d3a1be71/pitzer_7.csv
diff --git a/...39e4707443a9768f81a84c3ba85/pitzer_11.csv → ...39e4707443a9768f81a84c3ba85/pitzer_11.csv b/...39e4707443a9768f81a84c3ba85/pitzer_11.csv → ...39e4707443a9768f81a84c3ba85/pitzer_11.csv
diff --git a/...c9ba1f54e3a85f0f3e383951fc3/pitzer_15.csv → ...c9ba1f54e3a85f0f3e383951fc3/pitzer_15.csv b/...c9ba1f54e3a85f0f3e383951fc3/pitzer_15.csv → ...c9ba1f54e3a85f0f3e383951fc3/pitzer_15.csv
diff --git a/data/resourcedb.json → dmf_data/resourcedb.json b/data/resourcedb.json → dmf_data/resourcedb.json
diff --git a/docs/explanations/modeling_extensions/surrogate/sampling/index.rst b/docs/explanations/modeling_extensions/surrogate/sampling/index.rst
@@ -15,6 +15,7 @@ The PySMO package offers five common sampling methods for one-shot design:
    pysmo_halton
    pysmo_hammersley
    pysmo_cvt
+   pysmo_custom
    pysmo_sampling_properties
 
 

diff --git a/docs/explanations/modeling_extensions/surrogate/sampling/pysmo_custom.rst b/docs/explanations/modeling_extensions/surrogate/sampling/pysmo_custom.rst
@@ -0,0 +1,40 @@
+Custom Sampling
+===========================================
+With this method, users can explicitly define the distribution for the sampling of each input variable explicitly.
+
+The ``pysmo.sampling.CustomSampling`` method carries out the user-defined sampling strategy. This can be done in two modes:
+
+* The samples can be selected from a user-provided dataset, or
+* The samples can be generated from a set of provided bounds.
+
+We currently support three distributions options for sampling:
+
+* "random", for sampling from a random distribution.
+* "uniform", for sampling from a uniform distribution.
+* "normal", for sampling from a normal (i.e. Gaussian) distribution.
+
+.. warning::
+    **A note on Gaussian-based sampling**
+
+    To remain consistent with the other sampling methods and distributions, bounds are required for specifying normal distributions, rather than the mean (:math:`\bar{x}`) and standard deviation (:math:`\sigma`). For a normal distribution, 99.7% of the points/sample fall within three standard deviations of the mean. Thus, the bounds of the distribution ay be computed as:
+
+    .. math::
+        \begin{equation}
+        LB = \bar{x} - 3\sigma
+        \end{equation}
+
+    .. math::
+        \begin{equation}
+        UB = \bar{x} + 3\sigma
+        \end{equation}
+
+    While almost all of the points generated will typically fall between LB and UB, a few points may be generated outside the bounds (as should be expected from a normal distribution). However, users can choose to enforce the bounds as hard constraints by setting the boolean option  **strictly_enforce_gaussian_bounds**  to True during initialization. In that case, values exceeding the bounds are replaced by new values generated from the distributions. However, this may affect  the underlying distribution.
+
+
+Available Methods
+------------------
+
+.. autoclass:: idaes.core.surrogate.pysmo.sampling.CustomSampling
+    :members: __init__, sample_points
+
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -74,6 +74,12 @@ The IDAES team is comprised of collaborators from the following institutions:
 * University of Notre Dame
 * Georgia Tech
 
+Citing IDAES
+------------
+If you use IDAES software for your research, please cite us:
+
+Lee, Andrew, Jaffer H. Ghouse, John C. Eslick, Carl D. Laird, John D. Siirola, Miguel A. Zamarripa, Dan Gunter et al. "The IDAES process modeling framework and model library—Flexibility for process simulation and optimization." Journal of Advanced Manufacturing and Processing 3, no. 3 (2021): e10095. https://doi.org/10.1002/amp2.10095
+
 Contact us
 -----------
 General, background and overview information is available at the `IDAES website`_.

diff --git a/docs/reference_guides/model_libraries/generic/unit_models/mscontactor.rst b/docs/reference_guides/model_libraries/generic/unit_models/mscontactor.rst
@@ -75,14 +75,21 @@ Variable                      Name                                           Des
 :math:`X_{equil,t,x,s,r}`     stream + "_equilibrium_reaction_extent"        Extent of equilibrium reaction ``r`` in stream ``s`` at ``x`` and ``t``                                       Only if equilibrium reactions present for stream
 :math:`X_{inher,t,x,s,r}`     stream + "_inherent_reaction_extent"           Extent of inherent reaction ``r`` in stream ``s`` at ``x`` and ``t``                                          Only if inherent reactions present for stream
 :math:`X_{hetero,t,x,r}`      heterogeneous_reaction_extent                  Extent of heterogeneous reaction ``r`` at ``x`` and ``t``                                                     Only if heterogeneous reactions present
+:math:`V_x`                   volume                                         Total volume of element ``x``                                                                                 Only if ``has_holdup``
+:math:`f_{t,x,s}`             volume_frac_stream                             Volume fraction of stream ``s`` in element ``x`` at time ``t``                                                Only if ``has_holdup``
+:math:`\phi_{t,x,s,p}`        stream + "_phase_fraction"                     Volume fraction of phase ``p`` in stream ``s`` in element ``x`` at time ``t``                                 Only if ``has_holdup``
+:math:`N_{t,x,s,p,j}`         stream + "_material_holdup"                    Holdup of component ``j`` in phase ``p`` for stream ``s`` at ``x`` and ``t``                                  Only if ``has_holdup``
+:math:`dN/dt_{t,x,s,p,j}`     stream + "_material_accumulation"              Accumulation of component ``j`` in phase ``p`` for stream ``s`` at ``x`` and ``t``                            Only if ``dynamic``
+:math:`U_{t,x,s,p}`           stream + "_energy_holdup"                      Holdup of energy in phase ``p`` for stream ``s`` at ``x`` and ``t``                                           Only if ``has_holdup``
+:math:`dU/dt_{t,x,s,p}`       stream + "_energy_accumulation"                Accumulation of energy in phase ``p`` for stream ``s`` at ``x`` and ``t``                                     Only if ``dynamic``
 ============================= ============================================== ============================================================================================================= =========================================
 
 Constraints
 -----------
 
 In all cases, the multi-stage contactor model writes a set of material balances for each stream in the model. For component ``j`` in stream ``s`` the following constraint, named ``stream + "_material_balance"``, is written for all finite elements ``x``:
 
-.. math:: 0 = \sum_p{F_{t,x-,s,p,j}} - \sum_p{F_{t,x,s,p,j}} + \left[ \sum_p{F_{side,t,x,s,p,j}} \right] + \sum_o{M_{t,x,s,o,j}} + \left[ \sum_p{G_{rate,t,x,s,p,j}} + \sum_p{G_{equil,t,x,s,p,j}} + \sum_p{G_{inher,t,x,s,p,j}} + \sum_p{G_{hetero,t,x,s,p,j}} \right]
+.. math:: dN/dt_{t,x,s,p,j} = \sum_p{F_{t,x-,s,p,j}} - \sum_p{F_{t,x,s,p,j}} + \left[ \sum_p{F_{side,t,x,s,p,j}} \right] + \sum_o{M_{t,x,s,o,j}} + \left[ \sum_p{G_{rate,t,x,s,p,j}} + \sum_p{G_{equil,t,x,s,p,j}} + \sum_p{G_{inher,t,x,s,p,j}} + \sum_p{G_{hetero,t,x,s,p,j}} \right]
 
 where ``F`` is the material flow term, ``x-`` represents the previous finite element (``x-1`` in the case of co-current flow and ``x+1`` in the case of counter-current flow), ``F_side`` is the material flow term for a side stream (if present) and ``o`` represents all other streams in the model (for cases where ``s`` is the second index (i.e., M_{t,x,o,s,j}) the term is multiplied by -1). The reaction generation terms are only included if the appropriate reaction type is supported by the reaction or property package for the stream.
 
@@ -94,18 +101,38 @@ Equivalent constraints are written for equilibrium, inherent and heterogeneous r
 
 For streams including energy balances (``has_energy_balance = True``) the following constraint (named ``stream + "_energy_balance"``) is written at each finite element:
 
-.. math:: 0 = \sum_p{H_{t,x-,s,p}} - \sum_p{H_{t,x,s,p}} + \biggl[ \sum_p{H_{side,t,x,s,p}} \biggr] + \sum_o{E_{t,x,s,o}} + \biggl[ Q_{t,x,s} \biggr] + \biggl[ \sum_{rate}{\Delta H_{rxn,r} \times X_{rate,t,x,s,r}} + \sum_{equil}{\Delta H_{rxn,r} \times X_{equil,t,x,s,r}} + \sum_{inher}{\Delta H_{rxn,r} \times X_{inher,t,x,s,r}} \biggr]
+.. math:: \sum_p{dU/dt_{t,x,s,p}} = \sum_p{H_{t,x-,s,p}} - \sum_p{H_{t,x,s,p}} + \biggl[ \sum_p{H_{side,t,x,s,p}} \biggr] + \sum_o{E_{t,x,s,o}} + \biggl[ Q_{t,x,s} \biggr] + \biggl[ \sum_{rate}{\Delta H_{rxn,r} \times X_{rate,t,x,s,r}} + \sum_{equil}{\Delta H_{rxn,r} \times X_{equil,t,x,s,r}} + \sum_{inher}{\Delta H_{rxn,r} \times X_{inher,t,x,s,r}} \biggr]
 
 where ``H`` represent enthalpy flow terms and :math:`\Delta H_{rxn}` represents heat of reaction. The heat of reaction terms are only included if a reaction package is provided for the stream AND the configuration option ``has_heat_of_reaction = True`` is set for the stream. **Note** heterogeneous reactions **do not** support heat of reaction terms as it is uncertain which stream/phase the heat should be added too.
 
 For streams including pressure balances (``has_pressure_balance = True``) the following constraint (named ``stream + "_pressure_balance"``) is written at each finite element:
 
 .. math:: 0 = P_{t,x-,s} - P_{t,x,s} + \biggl[ \Delta P_{t,x,s} \biggr]
 
-where ``P`` represents pressure. For streams with side streams, the following pressure equality constraint (names ``stream + "_side_stream_pressure_balance"``) is also written:
+where ``P`` represents pressure. For streams with side streams, the following pressure equality constraint (named ``stream + "_side_stream_pressure_balance"``) is also written:
 
 .. math:: P_{t,x,s} = P_{side,t,x,s}
 
+If ``has_holdup`` is true, the following additional constraints are included to calculate holdup terms. First, ``sum_volume_frac`` constrains the sum of all volume fractions to be 1.
+
+.. math:: 1 = \sum_s{f_{t,x,s}}
+
+Additionally, constraints are written for the sum of phase fractions in each stream (named ``stream + "_sum_phase_fractions"``):
+
+.. math:: 1 = \sum_p{\phi_{t,x,s,p}}
+
+The material holdup is defined by the following constraint (named ``stream + "_material_holdup_constraint"``):
+
+.. math:: N_{t,x,s,p,j} = V \times f_{t,x,s} \phi_{t,x,s,p} \times \C_{t,x,s,p,j}
+
+where :math:`C_{t,x,s,p,j}` is the concentration of component ``j`` in phase ``p`` for stream ``s`` at ``x`` and ``t``.
+
+The energy holdup is defined by the following constraint (named ``stream + "_energy_holdup_constraint"``):
+
+.. math:: U_{t,x,s,p} = V*f_{t,x,s} \times \phi_{t,x,s,p} \times \u_{t,x,s,p}
+
+where :math:`u_{t,x,s,p}` is the internal energy density of phase ``p`` for stream ``s`` at ``x`` and ``t``.
+
 Initialization
 --------------