Price taker model for DISPATCHES, Rehashed

.github/workflows/typos.toml

@@ -37,6 +37,9 @@ equil = "equil"
 astroid = "astroid"
 # delt == delta
 delt = "delt"
+# FOM for fixed operating and maintenance for DISPATCHES
+FOM = "FOM"
+fom = "fom"
 # Minimal Infeasible System
 mis = "mis"
 MIS = "MIS"

docs/reference_guides/apps/grid_integration/index.rst

@@ -20,6 +20,7 @@ wholesale electricity markets. For more information, please look at the introduc
    Bidder
    Tracker
    Coordinator
+   multiperiod/index
 
 Cite us
 ^^^^^^^

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

@@ -0,0 +1,55 @@
+Price Taker
+===========
+
+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
+depicted in figure below.
+
+.. |pricetaker| image:: images/pricetaker.png
+  :width: 1200
+  :alt: Alternative text
+  :align: middle
+
+|pricetaker|
+
+The following equations represent the multi-period price taker model, where :math:`d` are design decisions,
+:math:`u` are operating decisions, :math:`δ` are power decisions, :math:`s` are scenarios (timeseries/representative days),
+:math:`w` is weight/frequency, :math:`R` is revenue, :math:`π` is price data,
+:math:`C` is capital and operating costs, :math:`g` is the process model, and :math:`h` is the temporal constraint.
+
+    .. math::
+
+       max_{d,u, δ} = \sum_{s ∈ S} \sum_{t ∈ T} w_{s}[R(d,u_{s,t},δ_{s,t},π_{s,t}) - C(d,u_{s,t},δ_{s,t})]
+
+    .. math::
+
+       g(d,u_{s,t},δ_{s,t}) = 0; ∀_{s} ∈ S, t ∈ T
+
+    .. math::
+
+       h(d,u_{s,t},δ_{s,t},u_{s,t+1},δ_{s,t+1}) = 0; ∀_{s} ∈ S, t ∈ T
+
+
+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 (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).
+In part 2, PRESCIENT uses a variety of input parameters (design capacity, minimum power output, ramp rate, minimum up/down time, marginal cost, no load cost, and startup profile)
+to generate data for the market surrogates. Meanwhile, IDAES uses the double loop simulation to integrate detailed
+process models (b, ii) into the daily (a, c) and hourly (i, iii) grid operations workflow.
+
+.. |hybrid_energy_system| image:: images/hybrid_energy_system.png
+  :width: 1200
+  :alt: Alternative text
+  :align: middle
+
+|hybrid_energy_system|
+
+.. module:: idaes.apps.grid_integration.multiperiod.price_taker_model
+
+.. autoclass:: PriceTakerModel
+  :members:

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

@@ -0,0 +1,13 @@
+Multi-Period Modeling
+=====================
+
+Multi-period modeling can be used to simplify dynamic optimization problems
+by linking steady-state models over a time horizon with rate-limiting constraints.
+Therefore, sets of constraints at one temporal index will affect decisions taken
+at a different moment in time. These interactions can be used to model the relationship
+between the energy systems and wholesale electricity markets.
+
+.. toctree::
+    :maxdepth: 2
+
+    Price_Taker

idaes/apps/grid_integration/__init__.py

@@ -15,3 +15,8 @@
 from .coordinator import DoubleLoopCoordinator
 from .forecaster import PlaceHolderForecaster
 from .multiperiod.multiperiod import MultiPeriodModel
+from .multiperiod.price_taker_model import PriceTakerModel
+from .multiperiod.design_and_operation_models import (
+    DesignModel,
+    OperationModel,
+)

idaes/apps/grid_integration/multiperiod/design_and_operation_models.py

@@ -0,0 +1,226 @@
+#################################################################################
+# The Institute for the Design of Advanced Energy Systems Integrated Platform
+# Framework (IDAES IP) was produced under the DOE Institute for the
+# Design of Advanced Energy Systems (IDAES).
+#
+# Copyright (c) 2018-2023 by the software owners: The Regents of the
+# University of California, through Lawrence Berkeley National Laboratory,
+# National Technology & Engineering Solutions of Sandia, LLC, Carnegie Mellon
+# University, West Virginia University Research Corporation, et al.
+# All rights reserved.  Please see the files COPYRIGHT.md and LICENSE.md
+# for full copyright and license information.
+#################################################################################
+
+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):
+    """
+    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 = ConfigDict()
+    CONFIG.declare(
+        "model_func",
+        ConfigValue(
+            doc="Function that builds the design model",
+        ),
+    )
+    CONFIG.declare(
+        "model_args",
+        ConfigValue(
+            default={},
+            doc="Dictionary containing arguments needed for model_func",
+        ),
+    )
+
+    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
+            _logger.warning(
+                "The function that builds the design model is not specified."
+                "model_func must declare all the necessary design variables,"
+                "relations among design variables, capital cost correlations,"
+                "and fixed operating and maintenance cost correlations."
+            )
+            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(
+                "'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(
+                "'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):
+    """
+    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 = ConfigDict()
+    CONFIG.declare(
+        "model_func",
+        ConfigValue(
+            doc="Function that builds the design model",
+        ),
+    )
+    CONFIG.declare(
+        "model_args",
+        ConfigValue(
+            default={},
+            doc="Dictionary containing arguments needed for model_func",
+        ),
+    )
+    CONFIG.declare(
+        "declare_op_vars",
+        ConfigValue(
+            default=True,
+            domain=Bool,
+            doc="Should op_mode, startup, shutdown vars be defined?",
+        ),
+    )
+    CONFIG.declare(
+        "declare_lmp_param",
+        ConfigValue(
+            default=True,
+            domain=Bool,
+            doc="Should LMP data automatically be appended to the model?",
+        ),
+    )
+
+    # noinspection PyAttributeOutsideInit
+    def build(self):
+        super().build()
+
+        # Build the model
+        if self.config.declare_op_vars:
+            self.op_mode = Var(
+                within=Binary,
+                doc="Binary: 1 if the unit is operating, 0 otherwise",
+            )
+
+            self.startup = Var(
+                within=Binary,
+                doc="Binary: 1 if the startup is initiated, 0 otherwise",
+            )
+
+            self.shutdown = Var(
+                within=Binary,
+                doc="Binary: 1 if the shutdown is initiated, 0 otherwise",
+            )
+
+        if self.config.declare_lmp_param:
+            self.LMP = Param(
+                initialize=1,
+                mutable=True,
+                doc="Time-varying locational marginal prices (LMPs) [in $/MWh]",
+            )
+
+        if self.config.model_func is None:
+            _logger.warning(
+                "The function that builds the operation model is not specified."
+                "model_func must declare all the necessary operation variables,"
+                "relations among operation variables, and variable"
+                "operating and maintenance cost correlations."
+            )
+            return
+
+        # Call the function that builds the operation model
+        self.config.model_func(self, **self.config.model_args)