> 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/mmc-library/mmcvalves.md).

# MMCValves

## Description

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

The **MMC Valves** block, located in the **MMC/MMC blocks** library, simulates a set of modular multilevel converter (MMC) valves. It supports up to 12 valves and three model types: CPU-based Average Model (AVM), CPU-based Switched Function Model (SFM), and FPGA-based Switched Function Model.

In the average model, each valve’s sub-module (SM) capacitors are replaced by a single equivalent capacitor representing the total stored energy. In the switched function model, individual SM control and voltages are modeled.

The switched function model can run on the simulator CPU or on the FPGA. With CPU implementation, the simulation time step is typically limited to tens of microseconds (depending on system complexity and the number of SMs). With FPGA implementation, the SM time step can be below 1 microsecond.

The total number of SMs per valve in CPU implementation is constrained by the selected time step. For FPGA implementation, it depends on the user license; up to 511 SMs per valve are supported in the current firmware, with higher counts available upon request.

Use this block together with the [**MMCValvesParam**](https://www.opal-rt.com/docs/rt-lab/simulink-blocks-reference/mmc-library/mmcvalvesparam.md) and [**MMCValvesLowLvlCtrl**](https://www.opal-rt.com/docs/rt-lab/simulink-blocks-reference/mmc-library/mmcvalveslowlvlctrl.md) blocks. The **MMCValvesParam** block sets its parameters, and the **MMCValvesLowLvlCtrl** block provides the required control inputs.

{% hint style="danger" %}
When its parameter **Model Type** is set to **CPU**, this block requires a valid RT-LAB license on the simulator with the following features:

* **ARTEMIS** = enabled

When its parameter **Model Type** is set to **FPGA**, this block requires a valid RT-LAB license on the simulator with the following features:

* **XSG\_MMC\_VALVES** ≥ Σ(Number of Valves from every MMCValves block in the model)
* **XSG\_MMC\_VALVE\_CONTROLLERS** ≥ Σ(Number of Valves from every MMCValves block in the mode

**Examples**

If the model contains **one block** with **Number of Valves** = 6, the license must include:\
→ **XSG\_MMC\_VALVES ≥ 6**\
→ **XSG\_MMC\_VALVE\_CONTROLLERS ≥ 6**

If the model contains **two blocks**, one with **Number of Valves** = 6 and one with **Number of Valves** = 6:\
→ **XSG\_MMC\_VALVES ≥ 6 + 6 = 12**\
→ **XSG\_MMC\_VALVE\_CONTROLLERS ≥ 6 + 6 = 12**
{% endhint %}

## Mask parameters

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

{% tabs %}
{% tab title="Model Type = CPU" %}

<table><thead><tr><th width="224.45452880859375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Model Type</strong></td><td>Selects the implementation location.</td></tr><tr><td><strong>Number of Valves</strong></td><td>Number of valves simulated by the block (up to 12).</td></tr><tr><td><strong>Intercalate Ports</strong></td><td>Controls the arrangement of electrical terminals to ease circuit connections.<br><strong>Checked:</strong> Positive and negative terminals alternate across sides (left: +1, −2, +3, …; right: −1, +2, −3, …)<br><strong>Unchecked:</strong> All positive terminals appear on the left and all negative on the right (left: +1, +2, …; right: −1, −2, …)</td></tr><tr><td><strong>Diode resistance Ron (Ohm)</strong></td><td>Resistance of the diode.</td></tr><tr><td><strong>External snubber</strong></td><td>Determines snubber topology per valve.<br><strong>Checked:</strong> An external RC snubber is placed in parallel with each valve. The parallel resistance is internally set to obtain a 4 ms time constant (modifiable upon request).<br><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-a2a3dd77a3ebfe541034ce4ac08c524a9720fbc7%2FMMC_valves_model.png?alt=media" alt=""><br><strong>Unchecked:</strong> The RC snubber is placed in parallel with the valve’s equivalent model diodes. Snubber values are set by <em>Rs</em> and <em>Cs</em>.<br><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-60af1d44bc9666e192966803dc3d79ade89a6377%2FMMC_valves_model2.png?alt=media" alt=""></td></tr><tr><td><strong>Snubber resistance Rs (Ohm)</strong></td><td>Snubber resistance value.</td></tr><tr><td><strong>Snubber capacitance Cs (Farads)</strong></td><td>Snubber capacitance value.</td></tr><tr><td><strong>CPU Model Type</strong></td><td>Determines the CPU model: Average Model (AVM) or Switched Function Model (SFM).</td></tr><tr><td><strong>Base value for total Vcap (Volts)</strong></td><td>Nominal valve voltage (maximum valve voltage with all SMs inserted at 1 p.u. capacitor voltage).</td></tr><tr><td><strong>Initial SM capacitor voltage Vcap (Volts)</strong></td><td>Initial voltage of each SM capacitor. For 1 p.u. start, set to <strong>Base value for total Vcap</strong> divided by the number of SMs per valve.</td></tr><tr><td><strong>Sample time (seconds)</strong></td><td>Discrete sample time for CPU calculations.</td></tr><tr><td><strong>Number of capacitors per valve</strong></td><td>Number of capacitors per valve. For Half-Bridge or Full-Bridge SMs, this equals the number of SMs. For SMs with two capacitors (e.g., CD-SM), set twice the number of SMs.</td></tr><tr><td><strong>SM Switch forward voltage Vf (Volts)</strong></td><td>Equivalent ON-state forward voltage per semiconductor switch in each SM. Unit: Volts.</td></tr><tr><td><strong>SM Switch Ron (Ohms)</strong></td><td>Equivalent ON-state resistance per semiconductor switch in each SM.</td></tr></tbody></table>
{% endtab %}

{% tab title="Model Type = FPGA" %}

<table><thead><tr><th width="210">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Model Type</strong></td><td>Selects the implementation location.</td></tr><tr><td><strong>Number of Valves</strong></td><td>Number of valves simulated by the block (up to 12).</td></tr><tr><td><strong>Intercalate Ports</strong></td><td>Controls the arrangement of electrical terminals to ease circuit connections.<br><strong>Checked:</strong> Positive and negative terminals alternate across sides (left: +1, −2, +3, …; right: −1, +2, −3, …)<br><strong>Unchecked:</strong> All positive terminals appear on the left and all negative on the right (left: +1, +2, …; right: −1, −2, …)</td></tr><tr><td><strong>Diode resistance Ron (Ohm)</strong></td><td>Resistance of the diode.</td></tr><tr><td><strong>External snubber</strong></td><td>Determines snubber topology per valve.<br><strong>Checked:</strong> An external RC snubber is placed in parallel with each valve. The parallel resistance is internally set to obtain a 4 ms time constant (modifiable upon request).<br><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-a2a3dd77a3ebfe541034ce4ac08c524a9720fbc7%2FMMC_valves_model.png?alt=media" alt=""><br><strong>Unchecked:</strong> The RC snubber is placed in parallel with the valve’s equivalent model diodes. Snubber values are set by <em>Rs</em> and <em>Cs</em>.<br><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-60af1d44bc9666e192966803dc3d79ade89a6377%2FMMC_valves_model2.png?alt=media" alt=""></td></tr><tr><td><strong>Snubber resistance Rs (Ohm)</strong></td><td>Snubber resistance value.</td></tr><tr><td><strong>Snubber capacitance Cs (Farads)</strong></td><td>Snubber capacitance value.</td></tr><tr><td><strong>OpCntrl / OpLnk block</strong></td><td>Selects the OpCntrl or OpLnk block used to connect the FPGA with the CPU model. The <strong>MMC Valves</strong> data is exchanged with the FPGA specified here. The list shows the OpCntrl/OpLnk blocks available in the same computation subsystem; if none are present, a warning/error is issued. The model can still compile, but the FPGA will not be connected and the model will not behave as expected.</td></tr><tr><td><strong>FPGA Control / Link Name</strong></td><td>Displays the name configured in the selected OpCntrl or OpLnk block. This field is read-only and updates automatically when a block is selected in <em>OpCntrl / OpLnk block</em>.</td></tr><tr><td><strong>Maximum number of SMs per valve in FPGA license</strong></td><td>Must match the number of SMs per valve allowed by the FPGA license.</td></tr><tr><td><strong>Valve group ID</strong></td><td>Logical group inside the FPGA where the valves run.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Conserving ports

<table><thead><tr><th width="166">Port</th><th>Description</th></tr></thead><tbody><tr><td><strong>+1, +2,+3 ,.... +12</strong></td><td>Positive valve terminals. The number identifies the corresponding valve.</td></tr><tr><td><strong>-1, -2,-3 ,.... -12</strong></td><td>Negative valve terminals. The number identifies the corresponding valve.</td></tr></tbody></table>

## Inputs

<table><thead><tr><th width="166">Input</th><th>Description</th></tr></thead><tbody><tr><td><strong>MMCPara</strong></td><td>Bus carrying parameter values from the <a href="https://www.opal-rt.com/docs/rt-lab/simulink-blocks-reference/mmc-library/mmcvalvesparam.md"><strong>MMCValvesParam</strong></a> block.</td></tr><tr><td><strong>ValveCtrl</strong></td><td><p>Control signals for the valves, generated by the <a href="https://www.opal-rt.com/docs/rt-lab/simulink-blocks-reference/mmc-library/mmcvalveslowlvlctrl.md"><strong>MMCValvesLowLvlCtrl</strong> </a>block. Format depends on the selected model:</p><ul><li>CPU implementation – Average Model (AVM): Bus with signals v1, v2, …, vN (N equals the <em>Number of Valves</em>). Each vX carries the modulation index for valve X. Range: [0, 1] for unipolar SMs (e.g., Half-Bridge) or [−1, 1] for bipolar SMs (e.g., Full-Bridge). Values outside the range may cause unexpected behavior.</li><li>CPU implementation – Switched Function Model (SFM): Bus with signals v1, v2, …, vN. Each vX is a bus with g1, g2, g3, g4, g5, where each gY is a vector of gate commands for all SMs in the valve. Vector index maps to SM position from the positive to the negative terminal. Gate values: 1 = closed, 0 = open. Always provide g1–g5; for SMs with fewer switches (e.g., Half-Bridge), send zeros to unused gates.</li><li>FPGA implementation: Empty; control signals are handled entirely on the FPGA.</li></ul></td></tr></tbody></table>

## Outputs

<table><thead><tr><th width="130">Output</th><th>Description</th></tr></thead><tbody><tr><td><strong>meas</strong></td><td><p>Bus containing valve measurements:</p><ul><li><strong>Ival</strong>: Vector of valve currents. Index maps to valve number (1→valve 1, 2→valve 2, …). Positive current flows from the positive terminal (+) to the negative terminal (−).</li><li><strong>v_vlv</strong>: Vector of valve terminal voltages. Index maps to valve number. Voltage measured from the negative to the positive terminal.</li><li><p><strong>Vs</strong>: Bus with:</p><ul><li><strong>Vsp</strong>: Vector of equivalent internal source voltages for positive current direction, per valve.</li><li><strong>Vsn</strong>: Vector of equivalent internal source voltages for negative current direction, per valve.</li></ul></li></ul></td></tr><tr><td><strong>Vcap</strong></td><td><p>Bus containing capacitor voltage measurements:</p><ul><li><strong>Vcap</strong>: Available only for CPU SFM. Bus with Vc1, Vc2, …, Vc12. Each VcX is a vector of SM capacitor voltages for valve X. Vector index maps to SM position from the positive terminal.</li><li><strong>Vcapave</strong>: Average SM capacitor voltage per valve (ΣVcap / Nsm). Available for CPU models (AVM and SFM). For FPGA implementation, this quantity is provided by the <a href="broken://pages/e03599c0e1de95e9c30d2a3ea67734c08bff72d2">MMC Valves Low Level Control Block</a> block. Output is a vector where index maps to valve number. Values are in p.u. and non-negative.</li></ul></td></tr></tbody></table>

## Characteristics and limitations

<table><thead><tr><th width="281">Characteristic</th><th>Value</th></tr></thead><tbody><tr><td>Maximum valves per block</td><td>The number of valves per <strong>MMCValves</strong> block is limited to 12. Multiple <strong>MMC Valves</strong> blocks can be used in the same system. Current firmware limits to 12 valves per FPGA.</td></tr><tr><td>Valve uniformity within a block</td><td>All valves share the same characteristics (number/type of SMs, snubber, switch resistance, SM capacitance). On FPGA, SM capacitance and discharge resistance can vary among SMs. Use multiple blocks to model different valve types in the same simulation.</td></tr><tr><td>SM type mixing</td><td>CPU SFM: one SM type per valve only. FPGA: up to three SM types per valve. AVM mixing is not recommended in the current version.</td></tr><tr><td>Changing model type at run time</td><td>Not supported. Stop the simulation and recompile when changing the model type.</td></tr></tbody></table>


---

# 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/mmc-library/mmcvalves.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.
