> 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-inner-control-loop-three-phase.md).

# GFM Inner Control Loop 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-8abb73f95fd965ed7158ffc0c096179d318f3d25%2FCSI_GFM_inner_control_loop_3P_block.png?alt=media" alt="" width="222"><figcaption></figcaption></figure>

The **GFM Inner Control Loop Three Phase** block, located in the **Control Smart Inverters library**, generates the d-q reference control signal for the Reference Generation block. It responds to the angular frequency, phase angle, and magnitude commanded by the outer control loop. The block provides two grid-forming (GFM) converter structures: single-loop control and double-loop control.

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

### **Single-loop control.**

This approach uses only a voltage feedback loop; there is no current feedback loop.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-287a2ee4ef63ec8302d369af42967fcd8e7b2be1%2FCSI_GFM_inner_control_loop_3P_architecture.png?alt=media" alt="" width="408"><figcaption><p>Inner loop control architecture</p></figcaption></figure>

The outer control loop sets the reference voltage V<sub>ref</sub>, V<sub>o</sub> is the inverter output voltage measured across the filter capacitor. Initial d- and q-axis references (V<sub>td</sub>*, V*<sub>*tq*</sub>) are adjusted by the virtual impedance logic to produce the final references.

During faults, the apparent impedance at the GFM inverter terminals decreases. As a voltage source, the inverter attempts to maintain its pre-fault voltage, which can drive excessive current.

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

To limit current, the block emulates a voltage drop across a virtual resistance, effectively reducing the voltage reference when the measured current magnitude exceeds a threshold I<sub>th</sub>. The current magnitude is subtracted from I<sub>th</sub>, scaled by the **virtual impedance** gain k<sub>VI</sub>, and passed through a hard limiter that outputs zero for negative values. This activates current limiting only when the current exceeds I<sub>th</sub> \[1]. Final d-q references are computed as:

$$
V\_d^*=V^**{td}-(I*{od}R\_{VI}-I\_{oq}X\_{VI})
$$

$$
V\_q^*=V^**{tq}-(I*{od}R\_{VI}+I\_{oq}X\_{VI})
$$

### Double-loop control

This approach uses cascaded voltage and current feedback loops.

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

Cross-decoupling terms $\omega C\_fV\_q, \omega C\_fV\_d, \omega L\_fI\_d, \text{and } \omega L\_fI\_q$ remove coupling between synchronous reference frame (SYRF) signals introduced by the filter inductor and capacitor. F is the feedforward coefficient for the inverter output current. $V\_d^*$ and $V\_q^*$ are the SYRF reference components for the inverter terminal voltages. The current loop uses a current saturation technique to constrain current during large disturbances.

### Comparison between the Inner Control Loop Methods <a href="#comparison-between-the-inner-control-loop-methods" id="comparison-between-the-inner-control-loop-methods"></a>

For similar filter settings, a grid-forming inverter typically has a larger small-signal stability margin with the single-loop structure because it regulates the inverter’s internal voltage, resulting in a larger coupling reactance than with the double-loop structure, which regulates the filter capacitor voltage. However, the single-loop structure lacks current controllability and may trip on overcurrent during short circuits \[2]. In the double-loop structure, the current references allow direct current limiting.

## 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-a2a614865aef6a65aa98a871523165ac177b8a1b%2FCSI_GFM_inner_control_loop_3P_mask_GeneralTab.png?alt=media" alt="" width="500"><figcaption></figcaption></figure>

| Parameter                   | Description                                                                        | Variable & Constraints       |
| --------------------------- | ---------------------------------------------------------------------------------- | ---------------------------- |
| **Inner Control Loop Type** | <p>Two options:<br>1- Single Loop Inner Control Loop<br>2- Double Loop Control</p> | Inn\_loop\_cntrl ∈ {1, 2, 3} |
| {% endtab %}                |                                                                                    |                              |

{% tab title="Single Loop Control" %}

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

**Voltage Loop Parameters**

| Parameter               | Description                                       | Variable & Constraints           |
| ----------------------- | ------------------------------------------------- | -------------------------------- |
| **Integral Gain**       | Integral gain of the voltage control loop (pu/s). | in\_sig\_vol\_gain unconstrained |
| **Voltage Upper Limit** | Upper voltage saturation control loop (pu).       | in\_sing\_V\_UpLim unconstrained |
| **Voltage Lower Limit** | Lower voltage saturation control loop (pu).       | in\_sing\_V\_LoLim unconstrained |

**Current Limiter Parameters**

| Parameter                  | Description                                                                             | Variable & Constraints              |
| -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------- |
| **Current Limit**          | Current threshold that activates virtual impedance limiting (pu).                       | in\_sig\_Imax unconstrained         |
| **Virtual Impedance Gain** | Virtual impedance gain used to limit inverter current during faults (pu).               | in\_sig\_KpVR\_gain unconstrained   |
| **X/R ratio**              | Reactance to Resistance ratio. This parameter limits the inverter current during fault. | in\_sig\_XR\_gain unconstrained     |
| **Freeze Time**            | Freeze Time for Current Limiter (s)                                                     | in\_sing\_Feeze\_Time unconstrained |
| {% endtab %}               |                                                                                         |                                     |

{% tab title="Double Loop Control" %}

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

**Nominal Values**

| Parameter                     | Description                                                      | Variable & Constraints       |
| ----------------------------- | ---------------------------------------------------------------- | ---------------------------- |
| **Nominal Power**             | Nominal capacity of the inverter (VA).                           | in\_dbl\_Sbase unconstrained |
| **Nominal Operating Voltage** | Nominal line‑to‑line RMS voltage of the inverter (V, Vrms, L-L). | in\_dbl\_Vnom unconstrained  |
| **Nominal Frequency**         | Nominal operating frequency of the grid-forming converter (Hz)   | in\_dbl\_fnom unconstrained  |

<br>

**Filter Parameters**

| Parameter                                         | Description                                               | Variable & Constraints    |
| ------------------------------------------------- | --------------------------------------------------------- | ------------------------- |
| **Filtering Inductance**                          | Total inductance of the filter (H).                       | in\_dbl\_LF unconstrained |
| **Internal Resistance of the Filtering Inductor** | Total intrinsic resistance of the filtering inductor (Ω). | in\_dbl\_Rf unconstrained |
| **Filtering Capacitance**                         | Total capacitance of the filter (F).                      | in\_dbl\_Cf unconstrained |

<br>

**Voltage Loop Parameters**

| Parameter                            | Description                                                | Variable & Constraints               |
| ------------------------------------ | ---------------------------------------------------------- | ------------------------------------ |
| **Proportional Gain (Kp)**           | Proportional gain of the voltage control loop (pu).        | in\_dbl\_vol\_Kp\_gain unconstrained |
| **Integral Gain (Ki)**               | Integral gain of the voltage control loop (pu/s).          | in\_dbl\_vol\_Ki\_gain unconstrained |
| **Output Current Feed Forward Gain** | Current feedforward gain in the voltage control loop (pu). | F\_in\_dbl unconstrained             |
| **Voltage Upper Limit**              | Upper voltage saturation control loop (pu).                | in\_dbl\_V\_UpLim unconstrained      |
| **Voltage Lower Limit**              | Lower voltage saturation control loop (pu).                | in\_dbl\_V\_LoLim unconstrained      |

<br>

**Current Loop Parameters**

| Parameter                  | Description                                         | Variable & Constraints               |
| -------------------------- | --------------------------------------------------- | ------------------------------------ |
| **Proportional Gain (Kp)** | Proportional gain of the current control loop (pu). | in\_dbl\_cur\_Kp\_gain unconstrained |
| **Integral Gain (Ki)**     | Integral gain of the current control loop (pu/s).   | in\_dbl\_cur\_Ki\_gain unconstrained |

<br>

**Current Limiter Parameters**

| Parameter                | Description                                                                                                                                                                                                    | Variable & Constraints              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **Current Limiter Type** | <p>Selector of Current Limiter Method, 4 options:<br>1- No Current Limiter (External)<br>2- Magnitude Current Limiter<br>3- Current Limiter prioritizing D-Axis<br>4- Current Limiter prioritizing Q-Axis.</p> | Curr\_limit\_type ∈ {1, 2, 3, 4}    |
| **Current Limit**        | Maximum Current limit (pu).                                                                                                                                                                                    | dbl\_vloop\_lim unconstrained       |
| **Freeze Time**          | Freeze Time for Current Limiter (s)                                                                                                                                                                            | in\_dbl\_Freeze\_Time unconstrained |
| {% 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-1275a6c905d7b0aaa7db434a350321503a2e3305%2FCSI_GFM_inner_control_loop_3P_mask_InitCondTab.png?alt=media" alt="" width="350"><figcaption></figcaption></figure>

| Parameter                            | Description                                            | Variable & Constraints     |
| ------------------------------------ | ------------------------------------------------------ | -------------------------- |
| **Initial Active Power**             | Initial active power at the output terminal (pu).      | Po\_pu\_init unconstrained |
| **Initial Reactive Power**           | Initial reactive power at the output terminal (pu).    | Qo\_pu\_init unconstrained |
| **Initial Output Voltage Magnitude** | Initial voltage magnitude at the output terminal (pu). | Vo\_pu\_init unconstrained |
| {% endtab %}                         |                                                        |                            |
| {% endtabs %}                        |                                                        |                            |

## Inputs

| Input      | Description                                                                                                                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Vdref**  | D‑axis reference magnitude of the virtual voltage source (pu). For Single Loop Control, this is the reference at the inverter terminal; for Double Loop Control, this is the reference across the filter capacitor. |
| **Iodq**   | D‑axis and Q‑axis output current (pu).                                                                                                                                                                              |
| **Vodq**   | D‑axis and Q‑axis output voltage (pu).                                                                                                                                                                              |
| **Omega**  | Angular velocity (pu).                                                                                                                                                                                              |
| **Iinvdq** | D‑axis and Q‑axis current in the inverter‑side inductor of the filter (pu).                                                                                                                                         |
| **Reset**  | Reset signal (unitless).                                                                                                                                                                                            |

## Outputs

| Output     | Description                                      |
| ---------- | ------------------------------------------------ |
| **Vdqref** | D‑axis and Q‑axis reference control signal (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] Y. G. Y. Z. A. J.-F. X. X. a. T. C. G. Y. Li, "Impedance Circuit Model of Grid-Forming Inverter: Visualizing Control Algorithms as Circuit Elements," IEEE Transactions on Power Electronics, vol. 36, no. 3, pp. 3377-3395, March 2021.

\[2] X. W. M. L. X. L. a. 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.

## 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-inner-control-loop-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.
