> 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/regfm_b1.md).

# REGFM\_B1

## Description

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

The **Renewable Energy Grid-Forming Model Type B1 (REGFM\_B1)** block, located in the **Control Smart Inverters library**, is a WECC positive-sequence virtual synchronous machine (VSM) grid-forming inverter model. It represents a controllable internal voltage source behind a coupling impedance and includes a VSM control loop, a voltage control loop, a PLL observer, and transient current limiting. \[1]

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

The block behaves as a controllable voltage source behind a coupling reactance. The following figure shows the interface circuit implemented in this block.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b0da72afb384a42825912d67d23f91564daf989b%2FCSI_REGFM_B1_circuit.png?alt=media" alt="" width="250"><figcaption><p>REGFM\_B1 interface circuit</p></figcaption></figure>

The REGFM\_B1 block contains four main functional parts.

### VSM control

This control develops the internal voltage angle (and frequency) command and provides active-power sharing. See the diagram below.

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

### Voltage control

Develops the internal voltage magnitude command and provides voltage regulation as shown in the following diagram.

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

### PLL

In the REGFM\_B1 block, the PLL does not serve as a synchronization mechanism — that role belongs to the VSM control. Instead, it acts as a network observer, providing a terminal voltage angle (δPLL) used exclusively for dq-frame transformations of measured signals. This ensures measurement consistency during transients, when the VSM internal angle (δVSM) may temporarily diverge from the actual terminal voltage due to virtual inertia dynamics. See diagram below.

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

### Fault current limiting function:

The following image shows the function that limits inverter current during short-circuit conditions by modifying the internal voltage source. Current limiting function is shown in the figure below.

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

### Load Flow

This block is implemented so the IBR can be initialized in steady-state operation. For load flow purposes, REGFM\_C1 is generally considered a PV bus, so it is necessary to define the voltage magnitude in pu and the active power P to be delivered by the IBR at the terminals in W. In the case of the SLACK bus, the voltage magnitude and angle in pu and degrees, respectively, must be defined.

To calculate the initial conditions of the model from the load flow, it is important to know the type of filter used in the model's interface circuit. In the original model described in \[1], only the RL filter option can be used, but if an external current limiting function with an RLC (or simply LC) filter is used, this filter type must be selected, and the capacitance value added in the general tab to correctly calculate the initial conditions.

## Mask parameters

{% hint style="info" %}
Note: Always run load flow using this block to correctly initialize internal model states.
{% endhint %}

{% 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-1c7f28dd0d09b932a21bc6cbb6f9106a30408256%2FCSI_REGFM_B1_mask_GeneralTab.png?alt=media" alt="" width="500"><figcaption></figcaption></figure>

| Parameter                                                                | Description                                                                            | Variable & Constraints              |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------- |
| **Base Voltage**                                                         | Defines the voltage base used to convert electrical quantities to per-unit values (V). | Vbase ∈ \[0, 1e64]                  |
| **Base Power**                                                           | Defines the apparent power base used for per-unit normalization (VA).                  | Sbase ∈ \[0, 1e64]                  |
| **Base frequency**                                                       | Sets the nominal grid frequency for model calculations (Hz).                           | fnom ∈ \[0, 1e64]                   |
| **Inverter coupling resistance**                                         | Equivalent resistance between the inverter internal source and the terminal bus (pu).  | Re recommended range: \[0, 0.25]    |
| **Inverter coupling reactance**                                          | Equivalent reactance between the inverter internal source and the terminal bus (pu).   | Xe recommended range: \[0.04, 0.40] |
| **Time constant of the low-pass filter for power measurements**          | Time constant of the low-pass filter for active power measurement (s).                 | Tpf ∈ \[0, 1e64]                    |
| **Time constant of the low-pass filter for reactive power measurements** | Time constant of the low-pass filter for reactive power measurement (s).               | TQf ∈ \[0, 1e64]                    |
| **Time constant of the low-pass filter for voltage measurements**        | Time constant of the low-pass filter for voltage measurements (s).                     | Tvf ∈ \[0, 1e64]                    |
| **Time constant of the low-pass filter for current measurements**        | Time constant of the low-pass filter for current measurements (s).                     | Tif ∈ \[0, 1e64]                    |
| **Filter Type**                                                          | <p>Selects the filter model used for initialization:<br>- RL (1)<br>- RLC (2)</p>      | FilterRL ∈ {1, 2}                   |
| **Filter capacitance**                                                   | Capacitance value of the output filter used during initialization (pu)                 | Cf unconstrained                    |
| {% endtab %}                                                             |                                                                                        |                                     |

{% tab title="VSM" %}

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

| Parameter    | Description                                                                            | Variable & Constraints |
| ------------ | -------------------------------------------------------------------------------------- | ---------------------- |
| **mp**       | Power-frequency droop gain.                                                            | mp unconstrained       |
| **Tp**       | Time constant of the low-pass filter in the VSM control block (s).                     | Tp ∈ \[0, 1e64]        |
| **H**        | Inertia time constant (s).                                                             | H ∈ \[0, 1e64]         |
| **D1**       | Damping coefficient.                                                                   | D1 unconstrained       |
| **D2**       | Transient damping coefficient.                                                         | D2 unconstrained       |
| **wD**       | Angular frequency of the washout filter (pu).                                          | wD ∈ \[0, 1e64]        |
| **Dwmin**    | Lower limit of delta frequency (pu).                                                   | Dwmin ∈ \[-1e64, 0]    |
| **Dwmax**    | Upper limit of delta frequency (pu).                                                   | Dwmax ∈ \[0, 1e64]     |
| **wFlag**    | <p>Flag selecting frequency signal used in P-f droop:<br>- Dwm (0)<br>- DwPLL (1)</p>  | wFlag ∈ {0, 1}         |
| **FFlag**    | <p>Flag enabling/disabling power-frequency droop:<br>- Disable (0)<br>- Enable (1)</p> | FFlag ∈ {0, 1}         |
| {% endtab %} |                                                                                        |                        |

{% tab title="Voltage Control" %}

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

| Parameter    | Description                                                                       | Variable & Constraints |
| ------------ | --------------------------------------------------------------------------------- | ---------------------- |
| **mq**       | Q-V droop gain.                                                                   | mq unconstrained       |
| **kpv**      | Proportional gain of the voltage controller.                                      | kpv unconstrained      |
| **kiv**      | Integral gain of the voltage controller (pu/s).                                   | kiv ∈ \[0, 1e64]       |
| **VdrpFlag** | <p>Selection Q-V droop input:<br>- Reactive power (0)<br>- Q-axis current (1)</p> | VdrpFlag ∈ {0, 1}      |
| **QVflag**   | <p>Selection plant controller input:<br>- Qref (0)<br>- Vref (1)</p>              | QVflag ∈ {0, 1}        |
| {% endtab %} |                                                                                   |                        |

{% tab title="PLL" %}

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

| Parameter    | Description                                           | Variable & Constraints     |
| ------------ | ----------------------------------------------------- | -------------------------- |
| **Vpllfrz**  | Voltage threshold to freeze PLL state variables (pu). | Vpllfrz ≤ 0.10 recommended |
| **kppll**    | Proportional gain of the PLL controller (pu).         | kpPLL unconstrained        |
| **kipll**    | Integral gain of the PLL controller (pu/s).           | kiPLL ∈ \[0, 1e64]         |
| **DwPLLmin** | Lower limit of PLL output (pu).                       | DwPLLmin ∈ \[-1e64, 0]     |
| **DwPLLmax** | Upper limit of PLL output (pu).                       | DwPLLmax ∈ \[0, 1e64]      |
| {% endtab %} |                                                       |                            |

{% tab title="Current Limiter" %}

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

| Parameter                     | Description                                                                                    | Variable & Constraints            |
| ----------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------- |
| **ImaxSS**                    | Steady-state current limit (pu).                                                               | ImaxSS ≤ 1/Xe and ImaxSS ≤ ImaxF  |
| **ImaxF**                     | Inverter maximum transient output current (pu).                                                | ImaxF > 0                         |
| **Current limiting function** | <p>Current Limiting function:<br>- External (0)<br>- Internal (1)</p>                          | isCurrentLimiterInternal ∈ {0, 1} |
| **ki**                        | Integral gain for active current limiting (pu/s).                                              | ki unconstrained                  |
| **kf**                        | Factor used to determine Iqmax or Idmax.                                                       | kf > 0                            |
| **Ke**                        | Scalar on Idmax for negative active steady-state current limitation.                           | 0 ≤ Ke ≤ 1                        |
| **ESFlag**                    | <p>Battery-source operation selection:<br>- Non-battery source (0)<br>- Battery source (1)</p> | ESFlag ∈ {0, 1}                   |
| **PQFlag**                    | <p>Priority:<br>- Q (0)<br>- P(1)</p>                                                          | PQFlag ∈ {0, 1}                   |
| {% endtab %}                  |                                                                                                |                                   |

{% tab title="Load Flow" %}

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

| Parameter                  | Description                                                                                    | Variable & Constraints    |
| -------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------- |
| **Bus Type**               | Initialization bus mode: Swing (fixed V and angle), PV (fixed P and V), or PQ (fixed P and Q). | BusType ∈ {Swing, PV, PQ} |
| **Voltage**                | Desired terminal voltage for initialization (pu).                                              | V0 unconstrained          |
| **Angle**                  | Desired terminal voltage angle for initialization (°).                                         | delta0 unconstrained      |
| **Active power**           | Desired terminal active power for initialization (W).                                          | P0 unconstrained          |
| **Reactive power minimum** | Minimum terminal reactive power used during load-flow initialization (VAR).                    | QminLF ≤ QmaxLF           |
| **Reactive power maximum** | Maximum terminal reactive power used during load-flow initialization (VAR).                    | QmaxLF ≥ QminLF           |
| **Reactive power**         | Desired terminal reactive power for initialization (VAR).                                      | Q0 unconstrained          |
| {% endtab %}               |                                                                                                |                           |
| {% endtabs %}              |                                                                                                |                           |

## Inputs

| Input    | Description                                                                   |
| -------- | ----------------------------------------------------------------------------- |
| **Vref** | Network-measured terminal voltage at the Point of Interconnection (POI) (pu). |
| **Pref** | Network-measured active power injection reference at the POI (pu).            |

## Outputs

| Output  | Description               |
| ------- | ------------------------- |
| **ABC** | Three phase terminal port |

## 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] W. Du, S. Achilles, D. Ramasubramanian et al., "Virtual Synchronous Machine Grid-Forming Inverter Model Specification (REGFM\_B1)," UNIFI-2024-6-1, 2024.

\[2] U.S. Department of Energy, "Model Specification of Grid-Forming Inverters (REGFM\_B)," 2024. Available: <https://docs.nlr.gov/docs/fy24osti/90260.pdf>

\[3] PowerWorld Corporation, "Machine Model: REGFM\_B1." Available: <https://www.powerworld.com/WebHelp/Content/TransientModels\\_HTML/Machine%20Model%20REGFM\\_B1.htm>

## Acknowledgements

{% 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/regfm_b1.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.
