> 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/rt-lab/simulink-blocks-reference/smart-inverter-library/gfm-inner-control-loop-three-phase.md).

# GFM Inner Control Loop Three Phase

## Description

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-6090c9799180a450130de5a7fd296708994154ad%2FCSI_RT_GFM_inner_control_loop_3P_block.png?alt=media" alt="" width="133"><figcaption></figcaption></figure>

The \*\*inner Control Loop 3-phase\*\* block, located in the \*\*Smart Inverter 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://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%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://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%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://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%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 C\_fV\_d, \text{and } \omega L\_fL\_d$$ 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.

### Current Limiting Function <a href="#current-limiting-function" id="current-limiting-function"></a>

The current limiting function is designed to protect the inverter switches from exposure to excessive current levels. Several approaches to implementing current limiting are described in the literature; in this block, a **magnitude limiter** is used.

The magnitude limiter reduces only the magnitude of the reference current by passing it through a saturator set to the maximum allowable value, $$I\_{max}$$. The phase angle of the reference current remains unchanged.

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

### 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

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-60ed8c77407e57d0db583156126180388c490b0c%2FCSI_RT_GFM_inner_control_loop_3P_mask.png?alt=media" alt=""><figcaption></figcaption></figure>

Parameters vary with the selected Inner Control Loop Type.

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

<table><thead><tr><th width="190">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Inner Control Loop Type</strong></td><td>Two options:<br>1- Single Loop Inner Control Loop<br>2- Double Loop Control</td></tr><tr><td><strong>Freeze Time</strong></td><td>Freeze Time for Current Limiter (s)</td></tr><tr><td><strong>Sample Time</strong></td><td>Input sampling period (s).</td></tr><tr><td><strong>Virtual Impedance Gain</strong></td><td>Virtual impedance gain used to limit inverter current during faults (pu).</td></tr><tr><td><strong>X/R ratio</strong></td><td>Reactance to Resistance ratio. This parameter limits the inverter current during fault.</td></tr><tr><td><strong>Threshold Current</strong></td><td>Current threshold that activates virtual impedance limiting (pu).</td></tr><tr><td><strong>Voltage Loop Proportional Gain</strong></td><td>Proportional Gain of the Voltage Control Loop (pu)</td></tr><tr><td><strong>Voltage Loop Integral Gain</strong></td><td>Integral gain of the voltage control loop (pu/s).</td></tr><tr><td><strong>Voltage Loop Initial Condition PI Controller</strong></td><td>PI Controller Initial Condition of the Voltage Control Loop (pu)</td></tr></tbody></table>
{% endtab %}

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

<table><thead><tr><th width="190">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Nominal Power</strong></td><td>Nominal capacity of the inverter (VA).</td></tr><tr><td><strong>Nominal Operating Voltage</strong></td><td>Nominal line‑to‑line RMS voltage of the inverter (V).</td></tr><tr><td><strong>Nominal Frequency</strong></td><td>Nominal operating frequency of the inverter (Hz).</td></tr><tr><td><strong>Voltage Loop Gains (Kp)</strong></td><td>Proportional gain of the voltage control loop (pu).</td></tr><tr><td><strong>Voltage Loop Gains (Ki)</strong></td><td>Integral gain of the voltage control loop (pu/s).</td></tr><tr><td><strong>Initial Condition PI Controller - Axis D</strong></td><td>PI Controller Initial Condition of the D Axis Voltage Control Loop (pu)</td></tr><tr><td><strong>Initial Condition PI Controller - Axis Q</strong></td><td>PI Controller Initial Condition of the D Axis Voltage Control Loop (pu)</td></tr><tr><td><strong>Current Loop Gains (Kp)</strong></td><td>Proportional gain of the current control loop (pu).</td></tr><tr><td><strong>Current Loop Gains (Ki)</strong></td><td>Integral gain of the current control loop (pu/s).</td></tr><tr><td><strong>Initial Condition PI Controller - Axis D</strong></td><td>PI Controller Initial Condition of the D Axis Current Control Loop (pu)</td></tr><tr><td><strong>Initial Condition PI Controller - Axis Q</strong></td><td>PI Controller Initial Condition of the D Axis Current Control Loop (pu)</td></tr><tr><td><strong>Current Limiter Type</strong></td><td><p>Selector of Current Limiter Method, 4 options:</p><p>External,</p><p>Current Magnitude Limiter,</p><p>Current Limiter prioritizing D-Axis and,</p><p>Current Limiter prioritizing Q-Axis.</p></td></tr><tr><td><strong>Current Limit</strong></td><td>Maximum Current limit (pu)</td></tr><tr><td><strong>Output Current Feed Forward Gain</strong></td><td>Current feedforward gain in the voltage control loop (pu).</td></tr><tr><td><strong>Filtering Inductance</strong></td><td>Total inductance of the filter (H).</td></tr><tr><td><strong>Internal Resistance of the Filtering Inductor</strong></td><td>Total intrinsic resistance of the filtering inductor (Ω).</td></tr><tr><td><strong>Filtering Capacitance</strong></td><td>Total capacitance of the filter (F).</td></tr></tbody></table>
{% 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‑ and q‑axis output current (pu).                                                                                                                                                                                  |
| **Vodq**   | d‑ and q‑axis output voltage (pu).                                                                                                                                                                                  |
| **Omega**  | Angular velocity (pu).                                                                                                                                                                                              |
| **Iinvdq** | d‑ and q‑axis current in the inverter‑side inductor of the filter (pu).                                                                                                                                             |
| **Reset**  | Reset signal (unitless).                                                                                                                                                                                            |

## Outputs

| Output       | Description                                  |
| ------------ | -------------------------------------------- |
| **Vdq\_ref** | d‑ 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.

{% 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/rt-lab/simulink-blocks-reference/smart-inverter-library/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.
