hycon 0.7.1__tar.gz

hycon-0.7.1/LICENSE.txt

@@ -0,0 +1,26 @@
+BSD 3-Clause License
+
+Copyright (c) 2025 Alliance for Energy Innovation, LLC and Colorado School of Mines.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted
+provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions
+and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of
+conditions and the following disclaimer in the documentation and/or other materials provided
+with the distribution.
+
+* Neither the name of the copyright holder nor the names of its contributors may be used to
+endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

hycon-0.7.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: hycon
+Version: 0.7.1
+Summary: Hybrid power plant controller.
+Author-email: "Michael (Misha) Sinner" <michael.sinner@nlr.gov>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2025 Alliance for Energy Innovation, LLC and Colorado School of Mines.
+        
+        Redistribution and use in source and binary forms, with or without modification, are permitted
+        provided that the following conditions are met:
+        
+        * Redistributions of source code must retain the above copyright notice, this list of conditions
+        and the following disclaimer.
+        
+        * Redistributions in binary form must reproduce the above copyright notice, this list of
+        conditions and the following disclaimer in the documentation and/or other materials provided
+        with the distribution.
+        
+        * Neither the name of the copyright holder nor the names of its contributors may be used to
+        endorse or promote products derived from this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+        IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+        AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+        OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+        OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+        POSSIBILITY OF SUCH DAMAGE.
+Project-URL: Homepage, https://github.com/NatLabRockies/hycon
+Project-URL: Documentation, https://natlabrockies.github.io/hycon/intro.html
+Keywords: hycon
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy~=2.0
+Requires-Dist: pandas~=2.0
+Requires-Dist: matplotlib~=3.0
+Requires-Dist: floris~=4.3
+Requires-Dist: zmq
+Provides-Extra: docs
+Requires-Dist: jupyter-book==1.0.4; extra == "docs"
+Requires-Dist: sphinx-book-theme; extra == "docs"
+Provides-Extra: develop
+Requires-Dist: pytest; extra == "develop"
+Requires-Dist: pre-commit; extra == "develop"
+Requires-Dist: ruff; extra == "develop"
+Requires-Dist: isort; extra == "develop"
+Dynamic: license-file
+
+# Hycon
+
+Hycon is a python-based tool for real-time hybrid power plant control.
+Hycon will primarily be run in simulation, although we intend that it could be 
+used for physical plants in future. 
+
+Hycon provides plant-level (and hybrid plant-level) controls such as
+wake steering control, spatial filtering/consensus, active power control, 
+and coordinated control of hybrid power plant assets;
+and creates an entry point for the development of more advanced controllers. 
+
+Hycon will interface with various simulation testbeds and lower level 
+controllers, including:
+- [Hercules](https://github.com/NatLabRockies/hercules)
+- [FAST.Farm](https://github.com/OpenFAST/openfast)
+- [ROSCO](https://github.com/NatLabRockies/rosco)
+
+Hycon controllers will also call on design tools such as
+[FLORIS](https://github.com/NatLabRockies/floris).
+
+## WETO software
+
+Hycon is primarily developed with the support from the U.S. Department of Energy and
+is part of the [WETO Software Stack](https://natlabrockies.github.io/WETOStack).
+For more information and other integrated modeling software, see:
+
+- [Portfolio Overview](https://natlabrockies.github.io/WETOStack/portfolio_analysis/overview.html)
+- [Entry Guide](https://natlabrockies.github.io/WETOStack/_static/entry_guide/index.html)
+- [Wind Farm Controls Workshop](https://www.youtube.com/watch?v=f-w6whxIBrA&list=PL6ksUtsZI1dwRXeWFCmJT6cEN1xijsHJz)
+
+NLR's software record for Hycon is SWR-25-54.
+
+## Documentation
+
+Documentation for Hycon, including installation instructions, can be found
+[here](https://natlabrockies.github.io/hycon/intro.html).

hycon-0.7.1/README.md

@@ -0,0 +1,36 @@
+# Hycon
+
+Hycon is a python-based tool for real-time hybrid power plant control.
+Hycon will primarily be run in simulation, although we intend that it could be 
+used for physical plants in future. 
+
+Hycon provides plant-level (and hybrid plant-level) controls such as
+wake steering control, spatial filtering/consensus, active power control, 
+and coordinated control of hybrid power plant assets;
+and creates an entry point for the development of more advanced controllers. 
+
+Hycon will interface with various simulation testbeds and lower level 
+controllers, including:
+- [Hercules](https://github.com/NatLabRockies/hercules)
+- [FAST.Farm](https://github.com/OpenFAST/openfast)
+- [ROSCO](https://github.com/NatLabRockies/rosco)
+
+Hycon controllers will also call on design tools such as
+[FLORIS](https://github.com/NatLabRockies/floris).
+
+## WETO software
+
+Hycon is primarily developed with the support from the U.S. Department of Energy and
+is part of the [WETO Software Stack](https://natlabrockies.github.io/WETOStack).
+For more information and other integrated modeling software, see:
+
+- [Portfolio Overview](https://natlabrockies.github.io/WETOStack/portfolio_analysis/overview.html)
+- [Entry Guide](https://natlabrockies.github.io/WETOStack/_static/entry_guide/index.html)
+- [Wind Farm Controls Workshop](https://www.youtube.com/watch?v=f-w6whxIBrA&list=PL6ksUtsZI1dwRXeWFCmJT6cEN1xijsHJz)
+
+NLR's software record for Hycon is SWR-25-54.
+
+## Documentation
+
+Documentation for Hycon, including installation instructions, can be found
+[here](https://natlabrockies.github.io/hycon/intro.html).

hycon-0.7.1/hycon/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("hycon")

hycon-0.7.1/hycon/controllers/__init__.py

@@ -0,0 +1,19 @@
+from hycon.controllers.battery_controller import (
+    BatteryController,
+    BatteryPassthroughController,
+    BatteryPriceSOCController,
+)
+from hycon.controllers.hybrid_supervisory_controller import (
+    HybridSupervisoryControllerBaseline,
+    HybridSupervisoryControllerMultiRef,
+)
+from hycon.controllers.hydrogen_plant_controller import HydrogenPlantController
+from hycon.controllers.lookup_based_wake_steering_controller import (
+    LookupBasedWakeSteeringController,
+)
+from hycon.controllers.solar_passthrough_controller import SolarPassthroughController
+from hycon.controllers.wake_steering_rosco_standin import WakeSteeringROSCOStandin
+from hycon.controllers.wind_farm_power_tracking_controller import (
+    WindFarmPowerDistributingController,
+    WindFarmPowerTrackingController,
+)

hycon-0.7.1/hycon/controllers/battery_controller.py

@@ -0,0 +1,268 @@
+import numpy as np
+
+from hycon.controllers.controller_base import ControllerBase
+
+
+class BatteryController(ControllerBase):
+    """
+    Modifies power reference to consider battery degradation for single battery.
+
+    In particular, ensures smoothness in battery reference signal to avoid rapid
+    changes in power reference, which can lead to degradation.
+    """
+
+    def __init__(self, interface, input_dict, controller_parameters={}, verbose=True):
+        """
+        Instantiate BatteryController.
+
+        Args:
+            interface (object): Interface object for communicating with simulator.
+            input_dict (dict): Dictionary of input parameters (e.g. from Hercules).
+            controller_parameters (dict): Dictionary of controller parameters k_batt and
+                clipping_thresholds. See set_controller_parameters for more details. If
+                controller parameters are provided both in input_dict and controller_parameters,
+                the latter will take precedence.
+            verbose (bool): If True, print debug information.
+        """
+        super().__init__(interface, verbose)
+
+        # Extract global parameters
+        self.dt = input_dict["dt"]
+
+        # Check that parameters are not specified both in input file
+        # and in controller_parameters
+        if "controller" in input_dict:
+            for cp in controller_parameters.keys():
+                if cp in input_dict["controller"]:
+                    raise KeyError(
+                        'Found key "' + cp + '" in both input_dict["controller"] and'
+                        " in controller_parameters."
+                    )
+            controller_parameters = {**controller_parameters, **input_dict["controller"]}
+        self.set_controller_parameters(**controller_parameters)
+
+        # Initialize controller internal state
+        self.x = 0
+
+    def set_controller_parameters(
+        self,
+        k_batt=0.1,
+        clipping_thresholds=[0, 0, 1, 1],
+        **_,  # <- Allows arbitrary additional parameters to be passed, which are ignored
+    ):
+        """
+        Set gains and threshold limits for BatteryController.
+
+        k_batt is the controller gain. The controller will be stable and slow to react for small
+        values of k_batt (e.g. k_batt=0.01), and will be fast to react (and eventually unstable)
+        for large values of k_batt (e.g. k_batt=1).
+
+        clipping_thresholds is a list of four values: [soc_min, soc_min_clip, soc_max_clip,
+        soc_max]. soc_min is the minimum allowable SOC value, below which the controller output
+        reference power will be zero. soc_min_clip is the SOC value below which the controller
+        applies clipping to the reference power (the reference power is clipped linearly between
+        soc_min and soc_min_clip). Similarly, soc_max_clip is the SOC value above which linear
+        clipping is applied, until soc_max, after which the output is zero. Between soc_min_clip
+        and soc_max_clip, the full reference power is used.
+
+        Args:
+            k_batt (float): Gain for controller.
+            clipping_thresholds (list): SOC thresholds for clipping reference power. Should be a
+                list of four values: [soc_min, soc_min_clip, soc_max_clip, soc_max].
+        """
+        zeta = 2
+        omega = 2 * np.pi * k_batt
+
+        # Discrete-time, first-order state-space model of controller
+        p = np.exp(-2 * zeta * omega * self.dt)
+        self.a = p
+        self.b = 1
+        self.c = omega / (2 * zeta) * (1 - p) / 2 * (p + 1)
+        self.d = omega / (2 * zeta) * (1 - p) / 2
+
+        self.clipping_thresholds = clipping_thresholds
+
+    def soc_clipping(self, soc, reference_power):
+        """
+        Clip the input reference based on the state of charge and clipping_thresholds.
+
+        Args:
+            soc (float): Current state of charge.
+            reference_power (float): Reference power to be clipped.
+
+        Returns:
+            float: Clipped reference power.
+        """
+        clip_fraction = np.interp(soc, self.clipping_thresholds, [0, 1, 1, 0], left=0, right=0)
+
+        r_charge = clip_fraction * self.plant_parameters["battery"]["charge_rate"]
+        r_discharge = clip_fraction * self.plant_parameters["battery"]["discharge_rate"]
+
+        return np.clip(reference_power, -r_discharge, r_charge)
+
+    def compute_controls(self, measurements_dict):
+        """
+        Main compute_controls method for BatteryController.
+        """
+        reference_power = measurements_dict["battery"]["power_reference"]
+        current_power = measurements_dict["battery"]["power"]
+        soc = measurements_dict["battery"]["state_of_charge"]
+
+        # Apply reference clipping
+        reference_power = self.soc_clipping(soc, reference_power)
+
+        e = reference_power - current_power
+
+        # Compute control
+        u = self.c * self.x + self.d * e
+
+        # Update controller internal state
+        self.x = self.a * self.x + self.b * e
+
+        controls_dict = {"power_setpoint": current_power + u}
+
+        return controls_dict
+
+
+class BatteryPassthroughController(ControllerBase):
+    """
+    Simply passes power reference down to (single) battery.
+    """
+
+    def __init__(self, interface, input_dict, verbose=True):
+        """
+        Instantiate BatteryPassthroughController."
+        """
+        super().__init__(interface, verbose)
+
+    def compute_controls(self, measurements_dict):
+        """
+        Main compute_controls method for BatteryPassthroughController.
+        """
+        return {"power_setpoint": measurements_dict["battery"]["power_reference"]}
+
+
+class BatteryPriceSOCController(ControllerBase):
+    """
+    Controller considers price and SOC to determine power setpoint.
+
+    This controller implements a price-arbitrage strategy that uses day-ahead (DA)
+    locational marginal prices (LMPs) and real-time (RT) LMPs to decide when to
+    charge or discharge the battery. The algorithm identifies the top and bottom
+    price hours of the day based on battery duration (e.g., for a 4-hour battery,
+    it targets the "top_d" = 4 highest and "bottom_d" = 4 lowest priced hours).
+
+    The decision logic is as follows:
+        1. If RT price exceeds the highest DA price: discharge at full rate
+           (unconditionally).
+        2. Else if RT price is in the top-d highest DA prices AND SOC > low_soc:
+           discharge at full rate.
+        3. Else if RT price is below the lowest DA price: charge at full rate
+           (unconditionally).
+        4. Else if RT price is in the bottom-d lowest DA prices AND SOC < high_soc:
+           charge at full rate.
+        5. Otherwise: hold (power setpoint = 0).
+
+    The SOC thresholds (high_soc, low_soc) prevent over-charging or over-discharging
+    during moderate price signals, while still allowing full charge/discharge when
+    prices move outside the expected DA range.
+
+    Note:
+        Charging power is represented as negative values, matching the convention
+        used at the Hercules/hybrid_plant level.
+    """
+
+    def __init__(self, interface, input_dict, controller_parameters={}, verbose=True):
+        super().__init__(interface, verbose)
+
+        # Check that parameters are not specified both in input file
+        # and in controller_parameters
+        if "controller" in input_dict:
+            for cp in controller_parameters.keys():
+                if cp in input_dict["controller"]:
+                    raise KeyError(
+                        'Found key "' + cp + '" in both input_dict["controller"] and'
+                        " in controller_parameters."
+                    )
+            controller_parameters = {**controller_parameters, **input_dict["controller"]}
+        self.set_controller_parameters(**controller_parameters)
+
+        self.rated_power_charging = input_dict["battery"]["charge_rate"]
+        self.rated_power_discharging = input_dict["battery"]["discharge_rate"]
+
+        # Save the duration rounded to nearest hour
+        self.duration = round(
+            interface.plant_parameters["battery"]["energy_capacity"]
+            / interface.plant_parameters["battery"]["power_capacity"]
+        )
+
+        # Raise if duration makes this controller implausible
+        if self.duration >= 12:
+            raise ValueError(
+                f"Battery duration is {self.duration} hours, which is not "
+                "supported by BatteryPriceSOCController."
+                " This controller is only intended for durations shorter than 12 hours."
+            )
+
+        if self.duration < 1:
+            raise ValueError(
+                f"Battery duration is {self.duration} hours, which is not "
+                "supported by BatteryPriceSOCController."
+                " This controller is only intended for durations of at least 1 hour."
+            )
+
+    def set_controller_parameters(
+        self,
+        high_soc=1.0,
+        low_soc=0.2,
+        **_,  # <- Allows arbitrary additional parameters to be passed, which are ignored
+    ):
+        """
+        Set parameters for BatteryPriceSOCController.
+
+        high_soc is the SOC threshold above which the battery will only charge if the price is below
+        the lowest (hourly) DA price of the day.  Defaults to 1.0.
+
+        low_soc is the SOC threshold below which the battery will only discharge if the price is
+        above the highest (hourly) DA price of the day.  Defaults to 0.2.
+
+        high_soc defaults to 1.0 (effectively disabled) as experience suggests waiting for
+        very low prices is not worthwhile. low_soc defaults to 0.2 as experience suggests waiting
+        for very high prices is worthwhile.
+
+        Args:
+            high_soc (float): High SOC threshold (0 to 1).  Defaults to 1.0.
+            low_soc (float): Low SOC threshold (0 to 1).  Defaults to 0.2.
+        """
+        self.high_soc = high_soc
+        self.low_soc = low_soc
+
+    def compute_controls(self, measurements_dict):
+        day_ahead_lmps = np.array(measurements_dict["DA_LMP_24hours"])
+        sorted_day_ahead_lmps = np.sort(day_ahead_lmps)
+        real_time_lmp = measurements_dict["RT_LMP"]
+
+        # Extract limits
+        bottom_d = sorted_day_ahead_lmps[self.duration - 1]
+        top_d = sorted_day_ahead_lmps[-self.duration]
+        bottom_1 = sorted_day_ahead_lmps[0]
+        top_1 = sorted_day_ahead_lmps[-1]
+
+        # Access the state of charge and LMP in real-time
+        soc = measurements_dict["battery"]["state_of_charge"]
+
+        # Note that the convention is followed where charging is negative power
+        # This matches what is in place in the hercules/hybrid_plant level and
+        # will be inverted before passing into the battery modules
+        if real_time_lmp > top_1:
+            power_setpoint = self.rated_power_discharging
+        elif (real_time_lmp > top_d) & (soc > self.low_soc):
+            power_setpoint = self.rated_power_discharging
+        elif real_time_lmp < bottom_1:
+            power_setpoint = -self.rated_power_charging
+        elif (real_time_lmp < bottom_d) & (soc < self.high_soc):
+            power_setpoint = -self.rated_power_charging
+        else:
+            power_setpoint = 0.0
+
+        return {"power_setpoint": power_setpoint}

hycon-0.7.1/hycon/controllers/controller_base.py

@@ -0,0 +1,68 @@
+from abc import ABCMeta, abstractmethod
+
+
+class ControllerBase(metaclass=ABCMeta):
+    def __init__(self, interface, verbose=True):
+        self._s = interface
+        self.verbose = verbose
+
+        # Initialize measurements and controls to send
+        self._measurements_dict = {}
+        self._controls_dict = {}
+
+    def _receive_measurements(self, input_dict=None):
+        # May need to eventually loop here, depending on server set up.
+        self._measurements_dict = self._s.get_measurements(input_dict)
+
+        return None
+
+    def _send_controls(self, input_dict=None):
+        self._s.check_controls(self._controls_dict)
+        output_dict = self._s.send_controls(input_dict, **self._controls_dict)
+
+        return output_dict
+
+    def step(self, input_dict=None):
+        # If not running with direct hercules integration, hercules_dict may simply be None
+        # throughout this method.
+        self._receive_measurements(input_dict)
+
+        self._controls_dict = self.compute_controls(self._measurements_dict)
+
+        output_dict = self._send_controls(input_dict)
+
+        return output_dict
+
+    @property
+    def controller_parameters(self):
+        return self._s.controller_parameters
+
+    @property
+    def plant_parameters(self):
+        return self._s.plant_parameters
+
+    @property
+    def dt(self):
+        return self._s.dt
+
+    @dt.setter
+    def dt(self, _):
+        print(
+            "Warning: Setting dt directly is deprecated. Use the interface's dt property instead."
+        )
+
+    @property
+    def cname(self):
+        if hasattr(self, "_cname"):
+            return self._cname
+        else:
+            return ValueError("cname has not been set for this controller.")
+
+    @cname.setter
+    def cname(self, value):
+        self._cname = value
+
+    @abstractmethod
+    def compute_controls(self, measurements_dict: dict) -> dict:
+        pass  # Control algorithms should be implemented in the compute_controls
+        # method of the child class.