opender 2.2.0
Open-source Distributed Energy Resources (DER) Model that represents IEEE Standard 1547-2018 requirements for steady-state and dynamic analyses
License: BSD
Requires Python: >=3.7

.. figure:: https://raw.githubusercontent.com/epri-dev/OpenDER/develop_req_SQA/docs/logo.png
    :alt: Open-source Distributed Energy Resources (OpenDER) Model

EPRI’s OpenDER model aims to accurately represent steady-state and dynamic behaviors of inverter-based distributed
energy resources (DERs). The model follows interconnection standards or grid-codes and is informed by the observed
behaviors of commercial products. Currently, model version 2.1 includes photovoltaic (PV) and battery energy storage
system (BESS) DER behaviors according to the capabilities and functionalities required by the IEEE standard 1547-2018.
This first-of-its-kind model can be used to run snapshot, Quasi-Static Time Series (QSTS), and a variety of dynamic
analyses to study the impacts of DERs on distribution operations and planning.

This project is licensed under the terms of the BSD-3 clause license.


.. |GitHub license| image:: https://img.shields.io/badge/License-BSD_3--Clause-blue.svg
   :target: https://github.com/epri-dev/opender/blob/master/LICENSE.txt

Resources
---------
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.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>`__)

Development Objective
---------------------
* Harmonize accurate interpretations of the IEEE Std 1547-2018 DER interconnection standard among all the stakeholders,
  including utilities, distribution analysis tool developers, and original equipment manufacturers (OEMs).

* Build consensus through an open-to-all DER Model User’s Group (DERMUG), which will utilize EPRI developed model
  specifications and codes and provide feedback for continuous improvement of the OpenDER model.

* Help the industry properly model the DERs that are (or to be) grid interconnected and evaluate the associated impacts
  on distribution circuits accurately.

Overall Block Diagram
---------------------
.. figure:: https://raw.githubusercontent.com/epri-dev/OpenDER/develop_req_SQA/docs/blockdiagram.png
    :width: 900

Dependencies
------------
Python >= 3.7

numpy

pandas

matplotlib

Dependencies of the package are auto-installed by pip command below.

Installation
------------
pip install opender


Example of Using the DER Model
------------------------------
Example script: main.py

This example generate DER output power in a dynamic simulation to demonstrate DER trip and enter service behavior.
The grid voltage is set to be alternating between 1 and 1.11 per unit every ~10 minutes.
DER should be observed to enter service and trip periodically.

Other examples can be found in the `Examples <examples>`_ directory.
Click the .ipynb files to see example scripts and execution results.

Unit tests
----------
Dependency: pytest

Execution command: pytest path-to-package\\tests




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
* Added two parameters (QV_VREF_MIN and QV_VREF_MAX) to indicate the maximum value for volt-var automatic Vref
  adjustment mode
* Changed volt-var function internal variable name
* Fixed a minor bug for PV DER, watt-var function
* Fixed a bug/typo in frequency-droop function
* Updated time constant calculation for Volt-var Vref auto adjustment.
* Correct an minor error in ride-through state determination.

2.1.5 (2024-06-12)
------------------
* Fixed a FutureWarning for pandas version 2.2.
* Fixed bugs for single phase model.
* Fixed a bug for negative sequence performance for Momentary Cessation

2.1.4 (2024-03-29)
------------------
* Added a setting to enable and disable momentary cessation (MC_ENABLE)
* Added settings to configure the momentary cessation voltage threshold (MC_LVRT_V1, MC_HVRT_V1)
* Fixed a bug on momentary cessation not triggering on high voltage condition.
* If NP_PHASE is set to 1 or 3, it will be automatically converted to 'SINGLE' or 'THREE'

2.1.3 (2023-12-05)
------------------
* Added a property for SoC of BESS DER using .bess_soc
* Automatically update the reactive capability curve if nameplate parameter is modified
  (when user defined curve is not provided)

2.1.2 (2023-08-23)
------------------
* Fixed an issue for BESS parameter initialization

2.1.1 (2023-08-18)
------------------
* Fixed an issue on voltage source output when zero sequence voltage is present
* Corrected single phase DER voltage measurement

2.1.0 (2023-05-29)
------------------
* Updated interaction between enter service ramp and ride-through. Now DER returns to enter service ramp
  after ride-through
* Added an optional charge/discharge ramp rate limit for BESS DER
* Added resets for all grid-support functions when DER is tripped

2.0.3 (2023-04-14)
------------------
* Fixed the option to update BESS DER parameter when creating the object.
* Fixed a bug when initializing a BESS DER during abnormal frequency condition.

2.0.2 (2023-04-03)
------------------
* Fixed a bug abnormal operation category (NP_ABNORMAL_OP_CAT) only accepts uppercase values
* Updated ride-through performance to better represent actual inverter's behavior
* Added an option to update DER parameter when creating the object.

2.0.1 (2023-03-21)
------------------
* Fixed a bug where enter service randomized enter delay does not behave as expected
* Fixed a bug where momentary cessation does not behave as expected

2.0.0 (2023-03-20)
------------------
* Changed all units of nameplate rating to the base unit Watt/var/VA, from kW/kvar/kVA in Version 1.0.
* Added one time delay feature to represent the DER active and reactive grid support functions’ reaction time, and a first order lag for in applicable voltage measurement.
* Added Battery Energy Storage System (BESS) DER specific functions including State-of-Charge (SOC) calculation, and their corresponding model input parameters.
* Updated applicable smart inverter functions to consider BESS DER behaviors, including volt-watt, active power limit, and watt-var functions.
* Changed the DER operation status from ON/OFF to “Continuous Operation”, “Mandatory Operation”, “Momentary Cessation”, “Trip”, etc., to better capture the DER ride-through status, and its performance in different ride-through modes.
* Added DER ride-through performance module, which includes the DER performance under different ride-through modes, including Momentary Cessation, etc.
* Added DER model output options as current source and voltage source behind impedance.


1.0.2 (2022-07-18)
------------------
* Improve model input validity check process

1.0.1 (2022-06-17)
------------------
* Include parameter csv files into the PyPI release

1.0.0 (2022-05-17)
------------------
* First release
* Model for photovoltaic (PV) DERs, including all smart inverter functions defined in IEEE Standard 1547-2018, as well as trip and enter service behaviors
* Output active and reactive power (P, Q) for power flow analysis
* Suitable for both steady-state, quasi-static time series (QSTS) and dynamic simulations