Price taker model for DISPATCHES, Rehashed

docs/reference_guides/apps/grid_integration/multiperiod/Price_Taker.rst

@@ -1,7 +1,7 @@
 Price Taker
 ===========
 
-Price takers are companies or individuals who must accept market prices since they lack the market share
+Price takers are entities that must accept market prices since they lack the market share
 to directly influence the market price. Likewise, it is assumed that a price taker's resource or energy
 system is small enough such that it does not significantly impact the market. When coupled with multi-period modeling,
 the price-taker model is able to synthesize grid-centric modeling with steady-state process-centric modeling, as
@@ -34,7 +34,7 @@ The following equations represent the multi-period price taker model, where :mat
 
 The price taker multi-period modeling workflow involves the integration of multiple software platforms into the IDAES optimization model
 and can be broken down into two distinct functions, as shown in the figure below. In part 1, simulated or historical
-ISO (International Organization for Standardization) data is used to generate locational marginal price (LMP)
+ISO (Independent System Operator) data is used to generate locational marginal price (LMP)
 signals, and production cost models (PCMs) are used to compute and optimize the time-varying dispatch schedules for each
 resource based on their respective bid curves. Advanced data analytics (RAVEN) reinterpret the LMP signals and PCM
 as stochastic realizations of the LMPs in the form of representative days (or simply the full-year price signals).

idaes/apps/grid_integration/multiperiod/design_and_operation_models.py

@@ -10,27 +10,63 @@
 # All rights reserved.  Please see the files COPYRIGHT.md and LICENSE.md
 # for full copyright and license information.
 #################################################################################
-from functools import reduce
-from pyomo.environ import (
-    Var,
-    Param,
-    Binary,
-    Expression,
-    NonNegativeReals,
-    Constraint,
-)
-from pyomo.common.config import ConfigValue, In
+
+import logging
+from pyomo.environ import Binary, Param, Var
+from pyomo.common.config import Bool, ConfigDict, ConfigValue
 from idaes.core.base.process_base import declare_process_block_class
 from idaes.core.base.process_base import ProcessBlockData
 
+_logger = logging.getLogger(__name__)
+
 
+# pylint: disable = attribute-defined-outside-init, too-many-ancestors
+# pylint: disable = invalid-name, logging-fstring-interpolation
 @declare_process_block_class("DesignModel")
 class DesignModelData(ProcessBlockData):
     """
-    Class for containing design model ...
+    Builds the 'design model' for a unit/process.
+
+    Args:
+        model_func: Function that builds the design model
+        model_args: Dictionary containing the arguments needed for model_func
+
+    The class defines `install_unit` binary variable that takes the value 1
+    if the unit is built/installed, and 0 otherwise.
+
+    Function model_func must declare all the necessary design variables,
+    relations among design variables, capital cost correlations, and fixed O&M
+    cost correlations. The function must also define attributes `capex` for
+    capital cost, and `fom` for fixed O&M cost. If not defined, these attributes
+    will be set to zero.
+
+    Example Usage:
+
+    .. code-block:: python
+
+        def my_design_model(m, p_min, p_max, cost):
+            m.power = Var()
+            m.min_capacity = Constraint(
+                expr=p_min * m.install_unit <= m.power
+            )
+            m.max_capacity = Constraint(
+                expr=m.power <= p_max * m.install_unit
+            )
+
+            # capex and fom must either be a constant, or Var, or Expression
+            m.capex = Expression(expr=cost["capex"] * m.power)
+            m.fom = Expression(expr=cost["fom"] * m.power)
+
+        m = ConcreteModel()
+        m.unit_1 = DesignModel(
+            model_func=my_design_model,
+            model_args={
+                "p_min": 150, "p_max": 600, "cost": {"capex": 10, "fom": 1},
+            },
+        )
     """
 
-    CONFIG = ProcessBlockData.CONFIG()
+    CONFIG = ConfigDict()
     CONFIG.declare(
         "model_func",
         ConfigValue(
@@ -45,20 +81,74 @@ class DesignModelData(ProcessBlockData):
         ),
     )
 
-    # noinspection PyAttributeOutsideInit
     def build(self):
         super().build()
 
+        self.install_unit = Var(
+            within=Binary,
+            doc="Binary: 1, if the unit is installed, 0 otherwise",
+        )
+
+        if self.config.model_func is None:
+            # Function that builds the design model is not specified
+            return
+
+        # Call the function that builds the design model
         self.config.model_func(self, **self.config.model_args)
 
+        # Check if capital and fixed O&M costs are defined
+        if not hasattr(self, "capex"):
+            _logger.warning(
+                f"'capex' attribute is not set for the design model "
+                f"{self.name}. Setting the capital cost of the unit to zero."
+            )
+            self.capex = 0
+
+        if not hasattr(self, "fom"):
+            _logger.warning(
+                f"'fom' attribute is not set for the design model "
+                f"{self.name}. Setting the fixed O&M cost of the unit to zero."
+            )
+            self.fom = 0
+
 
 @declare_process_block_class("OperationModel")
 class OperationModelData(ProcessBlockData):
     """
-    Class for containing design model ...
+    Builds the 'operation model' for a unit/process.
+
+    Args:
+        model_func: Function that builds the operation model
+        model_args: Dictionary containing the arguments needed for model_func
+
+    The class defines `op_mode`, `startup`, and `shutdown` binary variables
+    to track the operation, startup, and shutdown of the unit/process.
+
+    Function model_func must declare all the necessary operation variables,
+    relations among operation variables, and variable O&M cost correlations.
+
+    Example Usage:
+
+    .. code-block:: python
+
+        def my_operation_model(m, design_blk):
+            m.power = Var()
+            m.fuel_flow = Var()
+            ...
+
+        m = ConcreteModel()
+        m.unit_1 = DesignModel(
+            model_func=my_design_model,
+            model_args={
+                "p_min": 150, "p_max": 600, "cost": {"capex": 10, "fom": 1},
+            },
+        )
+        m.op_unit_1 = OperationModel(
+            model_func=my_operation_model, model_args={"design_blk": m.unit_1},
+        )
     """
 
-    CONFIG = ProcessBlockData.CONFIG()
+    CONFIG = ConfigDict()
     CONFIG.declare(
         "model_func",
         ConfigValue(
@@ -72,20 +162,19 @@ class OperationModelData(ProcessBlockData):
             doc="Dictionary containing arguments needed for model_func",
         ),
     )
-
     CONFIG.declare(
         "declare_op_vars",
         ConfigValue(
             default=True,
-            domain=In([True, False]),
+            domain=Bool,
             doc="Should op_mode, startup, shutdown vars be defined?",
         ),
     )
     CONFIG.declare(
-        "append_lmp_data",
+        "declare_lmp_param",
         ConfigValue(
             default=True,
-            domain=In([True, False]),
+            domain=Bool,
             doc="Should LMP data automatically be appended to the model?",
         ),
     )
@@ -98,24 +187,29 @@ def build(self):
         if self.config.declare_op_vars:
             self.op_mode = Var(
                 within=Binary,
-                doc="Binary var: 1 if the unit is operating, 0 otherwise",
+                doc="Binary: 1 if the unit is operating, 0 otherwise",
             )
 
             self.startup = Var(
                 within=Binary,
-                doc="Binary var: 1 if the startup is initiated, 0 otherwise",
+                doc="Binary: 1 if the startup is initiated, 0 otherwise",
             )
 
             self.shutdown = Var(
                 within=Binary,
-                doc="Binary var: 1 if the shutdown is initiated, 0 otherwise",
+                doc="Binary: 1 if the shutdown is initiated, 0 otherwise",
             )
 
-        if self.config.append_lmp_data:
+        if self.config.declare_lmp_param:
             self.LMP = Param(
                 initialize=1,
                 mutable=True,
-                doc="Parameter: Will be updated to LMP value at given time",
+                doc="Time-varying locational marginal prices (LMPs) [in $/MWh]",
             )
 
+        if self.config.model_func is None:
+            # Function that builds the operation model is not specified
+            return
+
+        # Call the function that builds the operation model
         self.config.model_func(self, **self.config.model_args)