Merge pull request #15 from epri-dev/develop_req_SQA

EPRI-SQA · web-flow · commit fe7877c664bc · 2025-04-15T12:33:02.000-05:00
Matching documentations to V2.2.0 model specification
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,10 @@
 
 Changelog
 =========
+2.2.0 (2025-04-11)
+------------------
+* Updated documentations to match version 2.2 model specification.
+
 2.1.6 (2025-01-13)
 ------------------
 * Updated volt-var curve point setting and nameplate information validity check
diff --git a/README.rst b/README.rst
@@ -20,8 +20,8 @@ OpenDER is under active development. Use the following resources to get involved
 
 * EPRI OpenDER homepage (`link <https://www.epri.com/OpenDER>`__)
 
-* Model specification: IEEE 1547-2018 OpenDER Model: Version 2.1, EPRI, Palo Alto, CA: 2023. 3002026631
-  (`link <https://www.epri.com/research/products/000000003002026631>`__)
+* Model specification: IEEE 1547-2018 OpenDER Model: Version 2.2, EPRI, Palo Alto, CA: 2024. 3002030962
+  (`link <https://www.epri.com/research/products/000000003002030962>`__)
 
 * OpenDER model interface to OpenDSS for circuit level analysis
   (`link <https://github.com/epri-dev/OpenDER_interface>`__)
diff --git a/setup.py b/setup.py
@@ -38,7 +38,7 @@ def read(*names, **kwargs):
 
 setup(
     name='opender',
-    version='2.1.6',
+    version='2.2.0',
     license='BSD',
     description='Open-source Distributed Energy Resources (DER) Model that represents IEEE Standard 1547-2018 '
                 'requirements for steady-state and dynamic analyses',
@@ -70,7 +70,7 @@ def read(*names, **kwargs):
         # 'Changelog': 'https://py_dss_interface.readthedocs.io/en/latest/changelog.html', #TODO change
         # 'Issue Tracker': 'https://github.com/PauloRadatz/py_dss_interface/issues', #TODO change
         'Homepage': 'https://www.epri.com/OpenDER',
-        'Model Specification': 'https://www.epri.com/research/products/000000003002021694'
+        'Model Specification': 'https://www.epri.com/research/products/000000003002030962'
         # 'Documentation': 'https://py_dss_interface.readthedocs.io/', #TODO change
     },
     keywords=[
diff --git a/src/opender/__init__.py b/src/opender/__init__.py
@@ -1,4 +1,4 @@
-__version__ = '2.1.6'
+__version__ = '2.2.0'
 
 from .common_file_format import DERCommonFileFormat
 from .common_file_format import DERCommonFileFormatBESS
diff --git a/src/opender/active_power_support_funcs/active_power_limit.py b/src/opender/active_power_support_funcs/active_power_limit.py
@@ -19,7 +19,7 @@ class ActivePowerLimit:
     """
     Active Power Limit Function
 
-    EPRI Report Reference: Section 3.7.1.2 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7.1.2 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_file, exec_delay):
diff --git a/src/opender/active_power_support_funcs/es_perf.py b/src/opender/active_power_support_funcs/es_perf.py
@@ -17,7 +17,7 @@
 class EnterServicePerformance:
     """
     Calculate desired active power output in Enter service ramp condition
-    EPRI Report Reference: Section 3.7.1.3 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7.1.3 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_obj):
diff --git a/src/opender/active_power_support_funcs/frequency_droop.py b/src/opender/active_power_support_funcs/frequency_droop.py
@@ -20,7 +20,7 @@
 class FreqDroop:
     """
     Frequency-droop Function
-    EPRI Report Reference: Section 3.7.1.4 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7.1.4 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     
     def __init__(self, der_obj):
diff --git a/src/opender/active_power_support_funcs/frequency_droop_bess.py b/src/opender/active_power_support_funcs/frequency_droop_bess.py
@@ -21,7 +21,7 @@
 class FreqDroopBESS(FreqDroop):
     """
     Frequency-droop Function for BESS DER
-    EPRI Report Reference: Section 3.7.3.2 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7.3.2 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     
     def __init__(self, der_obj):
diff --git a/src/opender/active_power_support_funcs/p_funcs.py b/src/opender/active_power_support_funcs/p_funcs.py
@@ -18,7 +18,7 @@
 class DesiredActivePower:
     """
     Desired active power calculation from active power support functions
-    EPRI Report Reference: Section 3.7 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_obj):
@@ -93,7 +93,7 @@ def calculate_p_desired_pu(self, p_out_w):
         """
         Based on the calculated values from volt-watt, frequency-droop, active power limit, and enter service ramp,
         their enabling signal, and DER operating status, generate the DER desired active power output
-        EPRI Report Reference: Section 3.7.1.5 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+        EPRI Report Reference: Section 3.7.1.5 in Report #3002030962: IEEE 1547-2018 OpenDER Model
 
         Variable used in this function:
         :param ap_limit_enable_exec:	Active power limit enable (AP_LIMIT_ENABLE) signal after execution delay
diff --git a/src/opender/active_power_support_funcs/p_funcs_bess.py b/src/opender/active_power_support_funcs/p_funcs_bess.py
@@ -21,7 +21,7 @@
 class DesiredActivePowerBESS(DesiredActivePower):
     """
     Desired active power calculation from active power support functions for BESS DER
-    EPRI Report Reference: Section 3.7.3 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7.3 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     def __init__(self, der_obj):
         super(DesiredActivePowerBESS, self).__init__(der_obj)
@@ -37,7 +37,7 @@ def calculate_p_desired_pu(self, p_out_w):
         Based on the calculated values from volt-watt, frequency-droop, active power limit, and enter service ramp,
         their enabling signal, and DER operating status, generate the DER desired active power output. Specifically
         for BESS DER, the State of Charge (SoC) and limitation of output active power due to SoC is considered.
-        EPRI Report Reference: Section 3.7.3.3 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+        EPRI Report Reference: Section 3.7.3.3 in Report #3002030962: IEEE 1547-2018 OpenDER Model
 
         Variable used in this function:
         :param ap_limit_enable_exec:	Active power limit enable (AP_LIMIT_ENABLE) signal after execution delay
diff --git a/src/opender/active_power_support_funcs/p_funcs_pv.py b/src/opender/active_power_support_funcs/p_funcs_pv.py
@@ -18,7 +18,7 @@
 class DesiredActivePowerPV(DesiredActivePower):
     """
     Desired active power calculation from active power support functions for PV DER
-    EPRI Report Reference: Section 3.7.2 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7.2 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_obj):
diff --git a/src/opender/active_power_support_funcs/volt_watt.py b/src/opender/active_power_support_funcs/volt_watt.py
@@ -23,7 +23,7 @@
 class VoltWatt:
     """
     Voltage – Active Power (Volt-watt) Function
-    EPRI Report Reference: Section 3.7.1.1 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.7.1.1 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_file, exec_delay, der_input):
diff --git a/src/opender/auxiliary_funcs/cond_delay.py b/src/opender/auxiliary_funcs/cond_delay.py
@@ -19,7 +19,7 @@ class ConditionalDelay:
     """
     Conditional Delayed Enable can also be referred as On Delay.
     Output is true only when input stays true for a time period
-    EPRI Report Reference: Section 3.12.4 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.12.4 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self):
diff --git a/src/opender/auxiliary_funcs/flipflop.py b/src/opender/auxiliary_funcs/flipflop.py
@@ -21,7 +21,7 @@
 class FlipFlop:
     """
     |  Flipflop logic
-    |  EPRI Report Reference: Section 3.12.5 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    |  EPRI Report Reference: Section 3.12.5 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     def __init__(self, ff_init):
         self.ff_out_prev = ff_init
diff --git a/src/opender/auxiliary_funcs/low_pass_filter.py b/src/opender/auxiliary_funcs/low_pass_filter.py
@@ -18,7 +18,7 @@
 class LowPassFilter:
     """
     |  Low pass filter for modeling DER open loop response behavior and other related responses
-    |  EPRI Report Reference: Section 3.12.1 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    |  EPRI Report Reference: Section 3.12.1 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     
     def __init__(self):
diff --git a/src/opender/auxiliary_funcs/ramping.py b/src/opender/auxiliary_funcs/ramping.py
@@ -20,7 +20,7 @@
 class Ramping:
     """
     |  Ramp rate limit function
-    |  EPRI Report Reference: Section 3.12.2 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    |  EPRI Report Reference: Section 3.12.2 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     
     def __init__(self):
diff --git a/src/opender/auxiliary_funcs/time_delay.py b/src/opender/auxiliary_funcs/time_delay.py
@@ -18,7 +18,7 @@
 class TimeDelay:
     """
     |  Time delay function
-    |  EPRI Report Reference: Section 3.12.3 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    |  EPRI Report Reference: Section 3.12.3 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     
     def __init__(self):
diff --git a/src/opender/bess_specifc/bess_specific.py b/src/opender/bess_specifc/bess_specific.py
@@ -18,7 +18,7 @@
 class BESSspecific:
     """
     State of Charge related Models for Battery Energy Storage System (BESS) DERs
-    EPRI Report Reference: Section 3.6 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.6 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     def __init__(self, der_obj):
 
diff --git a/src/opender/bess_specifc/soc.py b/src/opender/bess_specifc/soc.py
@@ -19,7 +19,7 @@
 class StateOfCharge:
     """
     State of Charge related Models for Battery Energy Storage System (BESS) DERs
-    EPRI Report Reference: Section 3.6 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.6 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_file):
diff --git a/src/opender/capability_and_priority.py b/src/opender/capability_and_priority.py
@@ -80,7 +80,7 @@ def intercep_piecewise_circle(mag, xp, yp, k = 0.9, err = 1.e-3, ):
 class CapabilityPriority:
     """
     | Calculate active and reactive power power output limited by DER ratings, according to the priority of responses.
-    | EPRI Report Reference: Section 3.9 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    | EPRI Report Reference: Section 3.9 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     def __init__(self, der_obj):
         self.der_file = der_obj.der_file
diff --git a/src/opender/common_file_format/common_file_format.py b/src/opender/common_file_format/common_file_format.py
@@ -565,7 +565,7 @@ def _get_parameter_list(self):
     def nameplate_value_validity_check(self):
         """
         Validity Check for Nameplate Parameters
-        Reference: Section 3.1, part of Table 3-1 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+        Reference: Section 3.1, part of Table 3-1 in Report #3002030962: IEEE 1547-2018 OpenDER Model
         Other validity checks are performed in variable setters
         """
 
diff --git a/src/opender/op_cond_proc.py b/src/opender/op_cond_proc.py
@@ -28,7 +28,7 @@ class DERInputs:
     """
     This module handles inputs to the DER model, and generate per unit value of applicable voltage,
     per unit available power for PV DER, per unit active power demand for BESS DER, etc.
-    EPRI Report Reference: Section 3.3 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.3 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_file: DERCommonFileFormat):
@@ -70,7 +70,7 @@ def __init__(self, der_file: DERCommonFileFormat):
 
     def operating_condition_input_processing(self):
         """
-        EPRI Report Reference: Section 3.3 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+        EPRI Report Reference: Section 3.3 in Report #3002030962: IEEE 1547-2018 OpenDER Model
 
         Used variables as inputs:
         :param v_a, v_b, v_c:	Three-phase line-to-ground RMS voltage at RPA
@@ -159,7 +159,7 @@ def operating_condition_input_processing(self):
     def operating_conditions_validity_check(self):
         """
         Validity Check for DER Model operating conditions
-        Reference: Table 3-5 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+        Reference: Table 3-5 in Report #3002030962: IEEE 1547-2018 OpenDER Model
         Should be executed every timestep
         """
 
diff --git a/src/opender/operation_status/enter_service_crit/es_crit.py b/src/opender/operation_status/enter_service_crit/es_crit.py
@@ -23,7 +23,7 @@
 class EnterServiceCrit:
     """
     Enter Service criteria
-    EPRI Report Reference: Section 3.5.1.1 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.5.1.1 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_obj):
diff --git a/src/opender/operation_status/enter_service_crit/es_crit_pv.py b/src/opender/operation_status/enter_service_crit/es_crit_pv.py
@@ -18,7 +18,7 @@
 class EnterServiceCritPV(EnterServiceCrit):
     """
     Enter Service criteria for PV DER
-    EPRI Report Reference: Section 3.5.2 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.5.2 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     def __init__(self, der_obj):
         super(EnterServiceCritPV, self).__init__(der_obj)
diff --git a/src/opender/operation_status/operating_status.py b/src/opender/operation_status/operating_status.py
@@ -20,7 +20,7 @@
 class OperatingStatus:
     """
     Determine Overall DER operating status in terms of Trip, Entering Service, Continuous Operation, etc.
-    EPRI Report Reference: Section 3.5.1.4 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.5.1.4 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
 
     def __init__(self, der_obj):
@@ -58,16 +58,16 @@ def determine_der_status(self):
         :param es_completed:	Enter service ramp completed in the previous time step
         """
 
-        # Enter service criteria (Section 3.5.1.1 in Report #3002026631: IEEE 1547-2018 OpenDER Model)
+        # Enter service criteria (Section 3.5.1.1 in Report #3002030962: IEEE 1547-2018 OpenDER Model)
         es_crit = self.enterservicecrit.es_decision()
 
-        # Trip criteria (Section 3.5.1.2 in Report #3002026631: IEEE 1547-2018 OpenDER Model)
+        # Trip criteria (Section 3.5.1.2 in Report #3002030962: IEEE 1547-2018 OpenDER Model)
         trip_crit = self.tripcrit.trip_decision()
 
-        # Ride-through criteria (Section 3.5.1.3 in Report #3002026631: IEEE 1547-2018 OpenDER Model)
+        # Ride-through criteria (Section 3.5.1.3 in Report #3002030962: IEEE 1547-2018 OpenDER Model)
         self.ridethroughcrit.determine_ride_through_mode()
 
-        # Eq 3.5.1-51,52, If DER is in Trip condition, and enter service criteria is met, depending on whether
+        # Eq 3.5.1-57,58, If DER is in Trip condition, and enter service criteria is met, depending on whether
         # simulation time step is greater than the ramp time, DER goes to "Entering Service" or "Continuous Operation"
         if self.der_status == 'Trip':
             if es_crit:
@@ -76,7 +76,7 @@ def determine_der_status(self):
                 else:
                     self.der_status = 'Continuous Operation'
 
-        # Eq 3.5.1-53~58, If DER is not Tripped (Entering Service, Continuous Operation, or all other Ride-through
+        # Eq 3.5.1-59~64, If DER is not Tripped (Entering Service, Continuous Operation, or all other Ride-through
         # modes), DER status depends on ride-through modes, in the priority of: Not Defined (frequency ride-through),
         # Other ride-through modes, and Continuous Operation.
         if self.der_status != 'Trip':
@@ -91,11 +91,10 @@ def determine_der_status(self):
                     self.der_status = 'Continuous Operation'
                 else:
                     self.der_status = 'Entering Service'
-                # Eq 3.5.1-57, If DER is in continuous operation, reset the flag that indicates required
-                # ride-through time has passed
+                # If DER is in continuous operation, reset the flag that indicates required ride-through time has passed
                 self.ridethroughcrit.reset_rt_pass_time_req()
 
-        # Eq. 3.5.1-59, if trip criteria is met, DER goes to Trip mode
+        # Eq. 3.5.1-65, if trip criteria is met, DER goes to Trip mode
         if trip_crit:
             self.der_status = 'Trip'
 
diff --git a/src/opender/operation_status/operating_status_pv.py b/src/opender/operation_status/operating_status_pv.py
@@ -23,7 +23,7 @@
 class OperatingStatusPV(OperatingStatus):
     """
     Determine Overall DER operating status for PV DER
-    EPRI Report Reference: Section 3.5.2 in Report #3002026631: IEEE 1547-2018 OpenDER Model
+    EPRI Report Reference: Section 3.5.2 in Report #3002030962: IEEE 1547-2018 OpenDER Model
     """
     def __init__(self, der_obj: opender.DER):
         super(OperatingStatusPV, self).__init__(der_obj)
diff --git a/src/opender/operation_status/rt_crit.py b/src/opender/operation_status/rt_crit.py
diff --git a/src/opender/operation_status/trip_crit/trip_crit.py b/src/opender/operation_status/trip_crit/trip_crit.py
diff --git a/src/opender/operation_status/trip_crit/trip_crit_pv.py b/src/opender/operation_status/trip_crit/trip_crit_pv.py
diff --git a/src/opender/output_options.py b/src/opender/output_options.py
diff --git a/src/opender/reactive_power_support_funcs/constant_pf.py b/src/opender/reactive_power_support_funcs/constant_pf.py
diff --git a/src/opender/reactive_power_support_funcs/constant_vars.py b/src/opender/reactive_power_support_funcs/constant_vars.py
diff --git a/src/opender/reactive_power_support_funcs/q_funcs.py b/src/opender/reactive_power_support_funcs/q_funcs.py
diff --git a/src/opender/reactive_power_support_funcs/volt_var.py b/src/opender/reactive_power_support_funcs/volt_var.py
diff --git a/src/opender/reactive_power_support_funcs/watt_var.py b/src/opender/reactive_power_support_funcs/watt_var.py
diff --git a/src/opender/rt_perf.py b/src/opender/rt_perf.py
diff --git a/src/opender/setting_execution_delay.py b/src/opender/setting_execution_delay.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-__version__ = '2.1.6'`
	`1`	`+__version__ = '2.2.0'`
`2`	`2`
`3`	`3`	`from .common_file_format import DERCommonFileFormat`
`4`	`4`	`from .common_file_format import DERCommonFileFormatBESS`