> 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/gfm-primary-control-three-phase.md).

# GFM Primary 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-9d9784fe5a536a7dcbb98082fa6b9b9672aecdac%2FCSI_GFM_1Control_3P_block.png?alt=media" alt="" width="321"><figcaption></figcaption></figure>

The **GFM Primary Control Three Phase** block, located in the **Control Smart Inverters library**, provides setpoints for the Inner Control Loop and aims to meet system-level specifications such as supplying pre-specified active and reactive power and providing services like inertia and primary frequency response. Its general structure includes a power synchronization loop and voltage profile management. The power system X/R ratio determines how active power, reactive power, frequency, and voltage are coupled. At high X/R ratios (typical at transmission level), active power links to frequency/angle and reactive power links to voltage magnitude. Accordingly, the active power reference and measurement feed the power synchronization loop, while the reactive power reference and measurement feed the voltage profile management unit.

The block integrates three primary control strategies: Droop Control, Virtual Synchronous Generator (VSG) control, and Synchronverter control. Droop Control and VSG require an Inner Control Loop; Synchronverter does not.

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

### Droop Control

Inspired by synchronous generators’ self-regulation, droop-controlled grid-forming inverters reduce active power when frequency rises (and vice versa). Based on power references and operating conditions, the controller sets the angular frequency, phase angle, and magnitude of the virtual voltage source for the Inner Control Loop.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8c5f15312606de123ef2e0a56b9ef5e19db18dba%2FCSI_GFM_1Control_3P_droop_control.png?alt=media" alt="" width="309"><figcaption><p>Droop control architecture</p></figcaption></figure>

The droop coefficients for active and reactive power are *m*<sub>*P*</sub> and *m*<sub>*Q*</sub>. *P*<sub>*meas*</sub> and *Q*<sub>*meas*</sub> are the measured output active and reactive power, and *ω*<sub>*ref*</sub> is the reference angular frequency.

### Virtual Synchronous Generator (VSG) Control

VSG-controlled grid-forming inverters mimic synchronous generator dynamics and inertia. Based on power references and operating conditions, the controller sets the angular frequency, phase angle, and magnitude of the virtual voltage source for the Inner Control Loop.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8059ca20f2ac00ced96c60c1309718e755222a9b%2FCSI_GFM_1Control_3P_VSG_control.png?alt=media" alt="" width="341"><figcaption><p>Virtual synchronous generator control architecture</p></figcaption></figure>

The frequency and angle are generated using the swing equation, where *J*<sub>*s*</sub> is the moment of inertia and *D*<sub>*P*</sub> is the damping constant. VSG governs active power (frequency); reactive power is controlled by a droop strategy as above.

### Synchronverter Control

Similar to VSG, Synchronverter mimics synchronous generator behavior but does not require a synchronization unit during pre-synchronization or normal operation \[1]. Depending on power references and operating conditions, it directly generates the reference control signal in d–q coordinates and removes the need for the Inner Control Loop.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-9d8a3fee287d0d7e7777cf2333a5ceb4fb76a468%2FCSI_GFM_1Control_3P_synchroverter.png?alt=media" alt="" width="359"><figcaption><p>Synchronverter control architecture</p></figcaption></figure>

Frequency and angle are produced from the swing equation, and the inner voltage magnitude from field electromagnetic equations. In the active power control part, *J*<sub>*s*</sub> is the rotor’s equivalent moment of inertia, *T*<sub>*e*</sub> the electromagnetic torque, and *D*<sub>*P*</sub> the damping factor. In the reactive power control part, *M*<sub>*f*</sub> is the peak mutual inductance between rotor and stator windings, and *i*<sub>*f*</sub> the field current \[2]. The product *M*<sub>*f*</sub>*i*<sub>*f*</sub> comes from the reactive power control loop; *T*<sub>*e*</sub>, reactive power, and the emulated three-phase voltages *E* follow the established Synchronverter equations in \[2]; reactive power can be computed from these equations without direct measurement.

## Mask parameters

Mask parameters vary depending on the selected Primary Control Loop Type. Complete the section that corresponds to your selection.

{% 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-987bbd05e6f27a667146ebbe43017307edfb3236%2FCSI_GFM_1Control_3P_mask_GeneralTab.png?alt=media" alt="" width="546"><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>Primary Control Loop Type</strong></td><td>Select the control type:<br>1–Droop Control,<br>2–VSG Control Loop,<br>3–Synchronverter</td><td>out_loop_cntrl ∈ {1, 2, 3}</td></tr><tr><td><strong>Nominal Frequency</strong></td><td>Nominal operating frequency of the grid-forming converter (Hz)</td><td>f_nom_out unconstrained</td></tr></tbody></table>
{% endtab %}

{% tab title="Droop Control" %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b23140bd5e067c57522f728da44d13e8268c7c6a%2FCSI_GFM_1Control_3P_mask_DroopTab.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 Droop Coefficient</strong></td><td>Droop coefficient for active power control (%)</td><td>m_P_droop unconstrained</td></tr><tr><td><strong>Reactive Power Droop Coefficient</strong></td><td>Droop coefficient for reactive power control (%)</td><td>m_Q_droop unconstrained</td></tr><tr><td><strong>Power LPF Cut-off Frequency</strong></td><td>Cut-off frequency of the power measurement filter (rad/s)</td><td>omega_c_power_droop unconstrained</td></tr></tbody></table>
{% endtab %}

{% tab title="VSG Control" %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b13d225ba3451d895e104cbf37bfbc28b05b2bcf%2FCSI_GFM_1Control_3P_mask_VSGTab.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>Moment of Inertia</strong></td><td>Moment of inertia (kg·m<sup>2</sup>)</td><td>J_vsg unconstrained</td></tr><tr><td><strong>Damping Factor</strong></td><td>Damping constant (pu)</td><td>Dp_vsg unconstrained</td></tr><tr><td><strong>Reactive Power Droop Coefficient</strong></td><td>Droop coefficient for reactive power control (%)</td><td>m_Q_vsg unconstrained</td></tr><tr><td><strong>Power LPF Cut-off Frequency</strong></td><td>Cut-off frequency of the power measurement filter (rad/s)</td><td>omega_C_power_vsg unconstrained</td></tr></tbody></table>
{% endtab %}

{% tab title="Synchronverter" %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-f3234575051f9221b9913833dfc404649c9437b1%2FCSI_GFM_1Control_3P_mask_SychronverterTab.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>Moment of Inertia</strong></td><td>Moment of inertia (kg·m<sup>2</sup>)</td><td>J_sychronverter unconstrained</td></tr><tr><td><strong>Damping Factor</strong></td><td>Damping constant (pu)</td><td>Dp_sychronverter unconstrained</td></tr><tr><td><strong>Flux Integrator Gain</strong></td><td>Integral gain of the flux integrator (pu/s)</td><td>K_sychronverter unconstrained</td></tr><tr><td><strong>Reactive Power Droop Coefficient</strong></td><td>Droop coefficient for reactive power control (%)</td><td>Dq_sychronverter unconstrained</td></tr><tr><td><strong>Power LPF Cut-off Frequency</strong></td><td>Cut-off frequency of the power measurement filter (rad/s)</td><td>omega_c_power_sychron unconstrained</td></tr><tr><td><strong>Voltage Upper Limit</strong></td><td>Voltage upper limit (pu)</td><td>V_UpLim unconstrained</td></tr><tr><td><strong>Voltage Lower Limit</strong></td><td>Voltage lower limit (pu)</td><td>V_LoLim unconstrained</td></tr></tbody></table>
{% endtab %}

{% tab title="Initial Conditions" %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8b44e5dcdb30e76627b26ba3ea5437e9270f06d6%2FCSI_GFM_1Control_3P_mask_InitCondTab.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>Initial Active Power</strong></td><td>Initial active power at the output terminal. (pu)</td><td>Po_pu_init unconstrained</td></tr><tr><td><strong>Initial Reactive Power</strong></td><td>Initial reactive power at the output terminal. (pu)</td><td>Qo_pu_init unconstrained</td></tr><tr><td><strong>Initial Output Voltage Magnitude</strong></td><td>Initial voltage at the output terminal. (pu)</td><td>Vo_pu_init unconstrained</td></tr><tr><td><strong>Initial Output Voltage Angle</strong></td><td>Initial voltage angle at the output terminal. (°)</td><td>Th_init unconstrained</td></tr><tr><td><strong>Initial Frequency</strong></td><td>Initial frequency at the output terminal. (pu)</td><td>Freq_pu_init unconstrained</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Inputs

| Input         | Description                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| **Vodq**      | D-axis and Q-axis output voltage (pu)                                                                    |
| **Iodq**      | D-axis and Q-axis output current (pu)                                                                    |
| **Vref**      | Reference input voltage (pu)                                                                             |
| **Omega ref** | Reference angular velocity (pu)                                                                          |
| **Pref**      | Reference active power (pu)                                                                              |
| **Qref**      | Reference reactive power (pu)                                                                            |
| **Iinv (pu)** | Current at the inverter-side inductor of the filter; available only when Synchronverter is selected (pu) |
| **Reset**     | Reset signal                                                                                             |

## Outputs

| Output     | Description                                                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Po**     | Active power measured at the output terminal (pu)                                                                                              |
| **Qo**     | Reactive power measured at the output terminal (pu)                                                                                            |
| **Vdref**  | D-axis reference magnitude of the virtual voltage source; available when Droop or VSG is selected (pu)                                         |
| **wt**     | Angle variation with time, synchronized to zero crossings of the fundamental (positive sequence) of phase A (rad)                              |
| **Omega**  | Angular velocity; available when Droop or VSG is selected (pu)                                                                                 |
| **Vdqref** | D-axis and Q-axis reference control signal; connect directly to the Reference Generation block; available when Synchronverter is selected (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] X. W., M. L., X. L., and S. E. R. Rosso, "Grid-Forming Converters: Control Approaches, Grid-Synchronization, and Future Trends—A Review," IEEE Open Journal of Industry Applications, vol. 2, pp. 93–109, 2021.

\[2] Q.-C. Z. and G. Weiss, "Synchronverters: Inverters that mimic synchronous generators," IEEE Transactions on Industrial Electronics, vol. 58, no. 4, pp. 1259–1267, Apr. 2011.

## 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/gfm-primary-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.
