> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/library-blocks-reference/control-smart-inverters/gfl-secondary-control-three-phase.md).

# GFL Secondary Control Three Phase

## Description

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-ef3bf8000ce73092d9ff2cf62156110f51c61e85%2FCSI_GFL_2nde_control_3P_block.png?alt=media" alt="" width="325"><figcaption></figcaption></figure>

The **GFL Secondary Control Three Phase** block, located in the **Control Smart Inverters library**, implements grid support functions (GSF) per IEEE Std 1547-2018 \[1]. It generates the active and reactive power references used by the primary control loops. You can select which GSFs are active and set their parameters.

The functions are grouped into three categories: Voltage Support with Reactive Power Control, Voltage Support with Active Power Control, and Frequency Support with Active Power Control.

Multiple functions can operate simultaneously while preserving mutual exclusivity where required.

{% hint style="danger" %}
This block requires a valid license on both the simulator and the workstation with the feature SMART INVERTER enabled.
{% endhint %}

### Voltage Support with Reactive Power Control

#### Constant Power Factor (CPF)

Computes the reactive power reference to maintain a constant power factor at the point of coupling (PoC), based on the power factor setpoint and measured active power. You define the excitation (VAR absorption or injection), limits, and the function open-loop response time. The response time is the duration from a step change at the input until the output reaches 90% of its final value; it is implemented using a first-order low-pass filter and limited to a maximum of 10 s.

#### Voltage–Reactive Power (Volt-VAR)

Outputs the reactive power reference as a function of the measured PoC voltage using a user-defined piecewise linear curve. The default curve uses values specified in \[1].

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-de44c3d22dcec00b1da76baef9c416ae7849050d%2FCSI_GFL_2nde_control_3P_VA_curves.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The function supports autonomous voltage reference (Vref) adjustment, which continuously recenters the curve around Vref. Vref is the moving average of the measured positive sequence voltage at the PoC over a user-defined time window. The response time is configurable as described above.

#### Active Power–Reactive Power (Watt-VAR or PQ)

Outputs the reactive power reference as a function of the measured active power using a user-defined piecewise linear curve.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7b2464765cc54967f1afde9eaac62dbe7dcb351f%2FDR-hyp-dnp3sl-add.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The first active power point of the curve is limited to the greater of 0.2 x Prated or Pmin, per \[1]. The response time is configurable as described above and limited to a maximum of 10 s.

#### Constant Reactive Power (Cons. Q)

Outputs a constant reactive power reference. You define the reactive power setpoint, excitation (VAR absorption or injection), limits, and the function open-loop response time. The response time is implemented as described above and limited to a maximum of 10 s.

### Voltage Support with Active Power Control

#### Voltage–Active Power (Volt-Watt)

Outputs the active power reference as a function of the measured PoC voltage using a user-defined piecewise linear curve.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-66dc5b920593c78097ceb3ef997cbb6cd03a1d87%2FCSI_GFL_2nde_control_3P_watt_curve.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The first active power point is set to Prated (1 p.u.), and the second point is limited to the lesser of 0.2\*Prated or Pmin, per \[1]. The response time is configurable as described above and limited to a maximum of 60 s.

{% hint style="info" %}
The power reference Pr is a limiting value. The actual active power output depends on the available power in the DC link.
{% endhint %}

### Frequency Support with Active Power Control

#### Frequency–Watt (Droop)

Outputs the active power reference as a function of the measured PoC frequency, considering available active power, pre-disturbance active power, and a deadband around the nominal frequency as defined in \[1]. When the frequency is inside the deadband, the Pr output is the active power limit defined by the Plim input and the power priority configuration. When the frequency is outside the deadband, Pr is a limiting value defined by the droop curve. Per \[1]:

$$
P\_r =
\begin{cases}
\min \left( P\_{\text{pre}} + \dfrac{(60 - db\_{UF}) - f}{60 \cdot k\_{UF}}, ; P\_{\text{rated}} \right), & \text{for } f < 60 - db\_{UF}, \\\[10pt]
\max \left( P\_{\text{pre}} - \dfrac{f - (60 + db\_{OF})}{60 \cdot k\_{OF}}, ; P\_{\text{min}} \right), & \text{for } f > 60 + db\_{OF}.
\end{cases}
$$

where Ppre is the stored pre-disturbance active power, Prated is the rated active power, Pmin is the minimum active power constraint, f is the frequency, kuf and kof are the droop constants for under- and over-frequency, and dbuf and dbof are the lower and upper deadband limits.

Example (with Pmin = 0.2): kuf = kof = 0.05 and dbuf = dbof = 0.036 Hz; curves are traced for different pre-disturbance active powers.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-3007cfb97faa093d6d0cbe1bdd0b0cd0b079ea56%2FCSI_GFL_2nde_control_3P_freq_curves.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

## Mask parameters

{% tabs %}
{% tab title="General" %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-1c0dd15176074cc305278f4837b35aa50a85225e%2FCSI_GFL_2ndeCtrl_GeneralTab.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="190">Parameter</th><th>Description</th><th width="140">Variable &#x26; Constraints</th></tr></thead><tbody><tr><td><strong>Nominal Frequency</strong></td><td>Nominal grid frequency (Hz).</td><td>fnom unconstrained</td></tr><tr><td><strong>Minimum Active Power</strong></td><td>Minimum active power output capacity (pu).</td><td>Pmin unconstrained</td></tr><tr><td><strong>Voltage Support with Reactive Power Control</strong></td><td>4 options:<br>- <strong>Constant Power Factor (CPF)</strong>: maintain a constant power factor at the PoC.<br>- <strong>Voltage-Reactive Power (Volt-VAR)</strong>: output reactive power reference as a function of the measured point of coupling voltage<br>- <strong>Active power, Reactive power (Watt-VAR or PQ)</strong>: output reactive power reference as a function of the measured active power output.<br>- <strong>Constant reactive power</strong>: output the desired reactive power reference.</td><td>GSF_Q ∈ {1, 2, 3, 4}</td></tr><tr><td><strong>Voltage Support with Active Power Control</strong></td><td><p>2 options:</p><p>- <strong>None</strong>: no function is activated<br>- <strong>Voltage Active Power (Volt-Watt)</strong>: output active power reference as a function of the measured point of coupling voltage.</p></td><td>GSF_P ∈ {1, 2}</td></tr><tr><td><strong>Frequency Support with Active Power Control</strong></td><td><p>2 options:</p><p>- <strong>None</strong>: no function is activated<br>- <strong>Frequency Watt (Droop)</strong>: output active power reference as a function of the measured point of coupling frequency</p></td><td>GSF_F ∈ {1, 2}</td></tr><tr><td><strong>Power Priority</strong></td><td>2 options:<br>- <strong>Reactive Power Priority</strong>: active power output (Pr) is limited to keep apparent power less than or equal to 1 pu. Accordingly, active power will be curtailed for the required reactive power<br>- <strong>Active power (Pr)</strong>: reactive power output (Qr) is limited to keep apparent power less than or equal to 1 pu</td><td>Pow_Prio ∈ {1, 2}</td></tr><tr><td><strong>Initialization Freeze Time</strong></td><td>Time interval after simulation start during which Pr = 1 pu and Qr = 0 pu (s).</td><td>SC_FrzTime unconstrained</td></tr></tbody></table>
{% endtab %}

{% tab title="Voltage Support with Reactive Power Control" %}
All parameter sets are shown in this tab (Constant Power Factor, Volt–VAR, Watt–VAR, and Constant Reactive Power). Configure the parameters associated with the selected Voltage Support with Reactive Power Control option.

**Constant Power Factor**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-a34d5ae321d4ee61a8d9c6e607b6b1adc0271b4b%2FCSI_GFL_2ndeCtrl_VoltageSupportReactiveTab_CPF.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="190">Parameter</th><th>Description</th><th width="140">Variable &#x26; Constraints</th></tr></thead><tbody><tr><td><strong>Constant Power Factor Excitation</strong></td><td>Select Under-Excited (VAR absorption) or Over-Excited (VAR injection).</td><td>CPF_Ext ∈ {1, 2}</td></tr><tr><td><strong>PF Limits Injecting [Min, Max]</strong></td><td>Minimum and maximum power factor limits for over-excited mode (dimensionless). Active only when Over-Excited is selected.</td><td>[CPF_InjLimMin, CPF_InjLimMax] unconstrained</td></tr><tr><td><strong>Pf Injecting</strong></td><td>Power factor reference for injection (dimensionless). Active only when Over-Excited is selected.</td><td>CPF_InjSet unconstrained</td></tr><tr><td><strong>Pf Limits Absorbing [Min, Max]</strong></td><td>Minimum and maximum power factor limits for under-excited mode (dimensionless). Active only when Under-Excited is selected.</td><td>[CPF_AbsLimMin, CPF_AbsLimMax] unconstrained</td></tr><tr><td><strong>Pf Absorbing</strong></td><td>Power factor reference for absorption (dimensionless). Active only when Under-Excited is selected.</td><td>CPF_AbsSet unconstrained</td></tr><tr><td><strong>Open Loop Response Time</strong></td><td>Desired open-loop settling time for CPF mode (s). Maximum 10 s.</td><td>CPF_RspTms ∈ [0, 10]</td></tr></tbody></table>

<br>

**Voltage-Reactive Power (Volt-Var)**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-de67d165a75b5852c892ee850a4e62f300502105%2FCSI_GFL_2ndeCtrl_VoltageSupportReactiveTab_VoltVAR.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="190">Parameter</th><th>Description</th><th width="140">Variable &#x26; Constraints</th></tr></thead><tbody><tr><td><strong>Reference Voltage</strong></td><td>Voltage reference setpoint (center of the Volt–VAR curve) (pu).</td><td>VV_Vref unconstrained</td></tr><tr><td><strong>Voltage Points</strong></td><td>Voltage breakpoints of the Volt–VAR curve (pu).</td><td>[VV_V0, VV_V_1, VV_V_2, VV_V_3, VV_V_4] unconstrained</td></tr><tr><td><strong>Reactive Power Points</strong></td><td>Reactive power breakpoints of the Volt–VAR curve (pu).</td><td>[VV_Q_0, VV_Q_1, VV_Q_2, VV_Q_3, VV_Q_4] unconstrained</td></tr><tr><td><strong>Enable Autonomous Vref Adjustment</strong></td><td>When enabled, the Volt–VAR curve center (Vref) follows the moving average of the positive-sequence PoC voltage.</td><td>VV_VrefAuto ∈ {0, 1}</td></tr><tr><td><strong>Vref Adjustment Time Constant</strong></td><td>Time constant of the Vref moving-average filter (s). Active only when autonomous Vref adjustment is enabled.</td><td>VV_VrefTms unconstrained</td></tr><tr><td><strong>Open Loop Response Time</strong></td><td>Desired open-loop settling time for Volt–VAR mode (s).</td><td>VV_Rsp_Tms unconstrained</td></tr></tbody></table>

<br>

**Active Power - Reactive Power (Watt-Var or PQ)**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-20c15dfa481ef92f9ae927008385be75e76f7cb3%2FCSI_GFL_2ndeCtrl_VoltageSupportReactiveTab_PQ.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="190">Parameter</th><th>Description</th><th width="140">Variable &#x26; Constraints</th></tr></thead><tbody><tr><td><strong>Active Power Points</strong></td><td>Active power breakpoints of the Watt–VAR curve (pu). The first point is limited to the greater of 0.2·Prated or Pmin, per [1].</td><td>[WV_P0, WV_P1, WV_P2] unconstrained</td></tr><tr><td><strong>Reactive Power Points</strong></td><td>Reactive power breakpoints of the Watt–VAR curve (pu).</td><td>[WV_Q0, WV_Q1, WV_Q2] unconstrained</td></tr><tr><td><strong>Open Loop Response Time</strong></td><td>Desired open-loop settling time for Watt–VAR mode (s). Maximum 10 s.</td><td>WV_Rsp_Tms ∈ [0, 10]</td></tr></tbody></table>

<br>

**Constant Reactive Power**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-bec56b3ee6e519f7307c9a86aa6ad67d7c03fdcc%2FCSI_GFL_2ndeCtrl_VoltageSupportReactiveTab_CQ.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="190">Parameter</th><th>Description</th><th width="140">Variable &#x26; Constraints</th></tr></thead><tbody><tr><td><strong>Reactive Power Excitation</strong></td><td>Select under- or over-excited operation for constant Q (pu).</td><td>CQ_Ext ∈ {0, 1}</td></tr><tr><td><strong>Reactive Power Limits Injecting [Min Max]</strong></td><td>Minimum and maximum reactive power limits for injection (pu). Active only when over-excited is selected.</td><td>[CQ_InjLimMin, CQ_InjLimMax] unconstrained</td></tr><tr><td><strong>Reactive Power Injecting</strong></td><td>Reactive power injection reference (pu). Active only when over-excited is selected.</td><td>CQ_InjSet unconstrained</td></tr><tr><td><strong>Reactive Power Limits Absorbing [Min Max]</strong></td><td>Minimum and maximum reactive power limits for absorption (pu). Active only when under-excited is selected.</td><td>[CQ_AbsLimMin, CQ_AbsLimMax] unconstrained</td></tr><tr><td><strong>Reactive Power Absorbing</strong></td><td>Reactive power absorption reference (pu). Active only when under-excited is selected.</td><td>CQ_AbsSet unconstrained</td></tr><tr><td><strong>Open Loop Response Time</strong></td><td>Desired open-loop settling time for Constant Reactive Power mode (s). Maximum 10 s.</td><td>CQ_Rsp_Tms ∈ [0, 10]</td></tr></tbody></table>
{% endtab %}

{% tab title="Voltage Support with Active Power Control" %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8fe3c42020ef61a9c6c15b1ba17260605a5c25eb%2FCSI_GFL_2ndeCtrl_VoltageSupportActiveTab.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="190">Parameter</th><th>Description</th><th width="140">Variable &#x26; Constraints</th></tr></thead><tbody><tr><td><strong>Voltage Points [V1 V2]</strong></td><td>Voltage points for the Volt–Watt curve (pu).</td><td>[VW_V0, VW_V1] unconstrained</td></tr><tr><td><strong>Active Power Points [P1 P2]</strong></td><td>Active power points for the Volt–Watt curve (pu).<br>P1 = Prated (1 pu); P2 ≤ min(0.2·Prated, Pmin), per [1].</td><td>[VW_P0, VW_P1] unconstrained</td></tr><tr><td><strong>Open Loop Response Time</strong></td><td>Desired open-loop settling time (s). Maximum 60 s.</td><td>VW_RspTms unconstrained</td></tr></tbody></table>
{% endtab %}

{% tab title="Frequency Support with Active Power Control" %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-37f6032870763ceebb609a1a8c2bea1ad96292a6%2FCSI_GFL_2ndeCtrl_FrequencySupportActiveTab.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="190">Parameter</th><th>Description</th><th width="140">Variable &#x26; Constraints</th></tr></thead><tbody><tr><td><strong>Under-frequency Deadband</strong></td><td>Deadband value for under-frequency (Hz).</td><td>FW_dbUF unconstrained</td></tr><tr><td><strong>Under-frequency Droop Slope</strong></td><td>Droop slope for under-frequency (% in fpu/Ppu).</td><td>FW_kUF unconstrained</td></tr><tr><td><strong>Over-frequency Deadband</strong></td><td>Deadband value for over-frequency (Hz).</td><td>FW_dbOF unconstrained</td></tr><tr><td><strong>Over-frequency Droop Slope</strong></td><td>Droop slope for over-frequency (% in fpu/Ppu).</td><td>FW_kOF unconstrained</td></tr><tr><td><strong>Open Loop Response Time</strong></td><td>Desired open-loop settling time (s).</td><td>FW_RspTms unconstrained</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Inputs

| Input         | Description                                              |
| ------------- | -------------------------------------------------------- |
| **Frequency** | Measured frequency of inverter output voltage (Hz).      |
| **Vrms avg**  | Average RMS value of three-phase grid voltages (pu).     |
| **P**         | Measured inverter active power (pu).                     |
| **Q**         | Measured inverter reactive power (pu).                   |
| **Plim**      | Active power limit setpoint (pu).                        |
| **Disable**   | When 1, forces power references to zero (dimensionless). |

## Outputs

| Output | Description                                   |
| ------ | --------------------------------------------- |
| **Pr** | Active power reference (limiting value) (pu). |
| **Qr** | Reactive power reference (pu).                |

## Signals available for monitoring and external I/O connections (via sensors form)

All block inputs and outputs are available as signals for monitoring and for external I/O connections.

## References

\[1] IEEE, "IEEE Standard for Interconnection and Interoperability of Distributed Energy Resources with Associated Electric Power Systems Interfaces," IEEE Std 1547-2018 (Revision of IEEE Std 1547-2003), doi: 10.1109/IEEESTD.2018.8332112, pp. 1-138, 2018.

## Intellectual Property and Acknowledgements

{% hint style="danger" %}

## **Intellectual Property Disclaimer**

Natural Resources Canada owns all intellectual property rights in the Smart Inverter Modelling Toolbox software and related products.
{% endhint %}

{% hint style="info" %}

## Acknowledgements <a href="#acknowledgements" id="acknowledgements"></a>

The development of the <code class="expression">page.vars.block\_name</code> block in the Smart Inverter Control Library is a contribution of CanmetENERGY at Natural Resource Canada.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/library-blocks-reference/control-smart-inverters/gfl-secondary-control-three-phase.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
