> 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/smart-power-simulation-software-sps/blocks-functions-tools/simulation-and-analysis/powergui.md).

# powergui

## Description

<figure><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-363a3b695183f6044afe5ca9ff522220ec21f6d7%2Fpowergui_block.png?alt=media" alt=""><figcaption></figcaption></figure>

The **powergui** block, located in the **OPAL-RT SPS Software** library, allows you to choose one of these methods to solve your circuit:

* **Continuous**, which uses a variable-step solver from Simulink®
* **Discretization of the electrical system** for a solution at fixed time steps
* **Continuous or discrete phasor solution**. The powergui block also opens tools for steady-state and simulation results analysis and for advanced parameter design.

You need the powergui block to simulate any Simulink model containing SPS blocks. It stores the equivalent Simulink circuit that represents the state-space equations of the model.

When using one powergui block in a model:

* Place the powergui block in the top-level diagram for optimal performance.
* Make sure that the block is named powergui.

{% hint style="info" %}
The powergui block becomes disabled during model update. To ensure proper model execution, do not restore the library link for the powergui block.
{% endhint %}

You can use multiple powergui blocks in a system that contains two or more independent electrical circuits that you want to simulate with different powergui solvers. For example, this system simulates the upper electrical circuit in discrete mode and the bottom circuit in continuous mode. The system compares the simulation performance of the two methods.

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

To do so, put each circuit in a different subsystem, and then add a powergui block inside each subsystem.

When you use more than one powergui block in a model:

* Do not place a powergui block in the top-level diagram.
* Place every independent model in a different subsystem.
* Place a single powergui block in the top level diagram of every subsystem.

Do not include commented-out powergui blocks in your model. Doing so will prevent the model from simulating.

## Parameters

### Solver

<table data-header-hidden><thead><tr><th width="249.77783203125"></th><th></th></tr></thead><tbody><tr><td><strong>Simulation type</strong> — Simulation type<br>Continuous (default) | Discrete | Phasor | Discrete phasor</td><td><p>Simulation type for the model:</p><ul><li>Continuous — Perform a continuous solution of the model.</li><li>Discrete — Perform a discretization of the model using the sample time specified by the <strong>Sample time (s)</strong> parameter.</li><li>Phasor — Perform continuous phasor simulation of the model at the frequency specified by the <strong>Frequency (Hz)</strong> parameter.</li><li>Discrete phasor — Perform a phasor simulation at fixed time steps specified by the <strong>Sample time (s)</strong> parameter, and at the frequency specified by the <strong>Frequency (Hz)</strong> parameter. The Discrete phasor solver uses simplified machine models that produce simulation results similar to transient stability software.</li></ul></td></tr><tr><td><strong>Sample time (s)</strong> — Sample time for discretization<br>50e-6 (default) | positive scalar</td><td><p>Sample time used to discretize the electrical circuit, in s. The powergui block displays the value of the sample time.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete or Discrete phasor.</p></td></tr><tr><td><strong>Frequency (Hz)</strong> — Frequency for phasor simulation<br>60 (default) | positive scalar</td><td><p>Frequency, in Hz, for performing the phasor simulation of the model. The powergui block displays the value of the phasor frequency.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Phasor or Discrete phasor.</p></td></tr></tbody></table>

### Apps

<table data-header-hidden><thead><tr><th width="249.6666259765625"></th><th></th></tr></thead><tbody><tr><td><strong>Measurement and States Analyzer</strong> — Display steady-state voltages and currents, initial capacitor voltages, and inductor currents<br>button</td><td>Open the Measurements and States Analyzer app to display the steady-state voltages and currents of the model as well as the initial capacitor voltages and inductor currents.</td></tr><tr><td><strong>Line Parameter Calculator</strong> — Compute RLC parameters of overhead transmission line<br>button</td><td>Open the Power Line Parameters app to compute RLC parameters of overhead transmission line from its conductor characteristics and tower geometry.</td></tr><tr><td><strong>Cable Parameter Calculator</strong> — Compute RLC matrices and frequency-dependent parameters<br>button</td><td>Open the Cable Parameter Calculator app to compute RLC matrices and frequency-dependent parameters of cable arrangements.</td></tr><tr><td><strong>Line Decoupler</strong> — Replace Distributed Parameters Line blocks with Decoupling Line blocks<br>button</td><td>Open the Specify Decoupling Lines app to replace selected Distributed Parameters Line blocks with Decoupling Line blocks.</td></tr><tr><td><strong>Load Flow Analyzer</strong> — Perform load flow and initialize three-phase networks and machines<br>button</td><td><p>Open the Load Flow Tool dialog box to perform load flow analysis and initialize three-phase networks and machines so that the simulation starts in steady state.</p><p>The Load Flow Tool uses the Newton-Raphson method to provide a robust and faster convergence solution compared to the Machine Initialization Tool.</p><p>The Load Flow Tool offers most of the functionality of other tools available in the power utility industry.</p><p>For more information, see power_loadflow.</p></td></tr><tr><td><strong>Max iterations</strong> — Maximum iterations used by Load Flow Tool<br>50 (default) | positive integer</td><td><p>Maximum number of times the Load Flow Tool iterates until the P and Q powers mismatch at each bus is lower than the <strong>PQ tolerance</strong> parameter value (in pu/Pbase).</p><p>The power mismatch is defined as the difference between the net power injected into the bus by generators and loads and the power transmitted on all links leaving that bus. For example, if the base power is 100 MVA and <strong>PQ tolerance</strong> is set to 1e-4, the maximum power mismatch at all buses does not exceed 0.1 MW or 0.1 Mvar.</p></td></tr><tr><td><strong>Frequency (Hz)</strong> — Frequency for load flow computations<br>60 (default) | positive scalar</td><td>Frequency, in Hz, used by the Load Flow Tool to compute the normalized Ybus network admittance matrix of the model and to perform the load flow calculations.</td></tr><tr><td><strong>Base power (VA)</strong> — Base power used by Load Flow Tool<br>100e6 (default) | positive scalar</td><td><p>Base power, in VA, used by the Load Flow Tool to compute the normalized Ybus network admittance matrix in pu/Pbase and bus base voltages of the model, at the frequency specified by the <strong>Frequency (Hz)</strong> parameter for load flow computations.</p><p>To avoid a badly conditioned Ybus matrix, select a base power value in the range of nominal powers and loads of the model.</p><p>For a transmission network with voltages ranging from 120 kV to 765 kV, a 100 MVA base is usually selected.</p><p>For a distribution network or for a small plant consisting of generators, motors, and loads that have a nominal power in the range of hundreds of kilowatts, a 1 MVA base power is better adapted.</p></td></tr><tr><td><strong>PQ tolerance (pu)</strong> — Tolerance between P and Q<br>1e-4 (default) | positive scalar</td><td>Tolerance between P and Q when the Load Flow Tool stops to iterate.</td></tr><tr><td><strong>Voltage units</strong> — Voltage units used by Load Flow Tool<br>kV (default) | V</td><td>Voltage units used by the Load Flow Tool to display voltages.</td></tr><tr><td><strong>Power units</strong> — Power units used by Load Flow Tool<br>MW (default) | kW | W</td><td>Power units used by the Load Flow Tool to display powers.</td></tr><tr><td><strong>Impedance Calculator</strong> — Display the impedance versus frequency<br>button</td><td>Open the app to display the impedance versus the frequency, as defined by the Impedance Measurement blocks. For more information, see power_zmeter.</td></tr><tr><td><strong>FFT Analyzer</strong> — Perform Fourier analysis of signals<br>button</td><td><p>Open the FFT Analysis Tool dialog box to perform Fourier analysis of signals stored in a structure with time format.</p><p>For more information, see power_fftscope.</p><p>For an example that uses the FFT Analysis tool, see Performing Harmonic Analysis Using the FFT Tool.</p></td></tr><tr><td><strong>Linear System Analyzer</strong> — Time and frequency domain responses<br>button</td><td><p>Open the Linear System Analyzer dialog box to generate the state-space model of your system (if you have a Control System Toolbox™ license) or to view time and frequency domain responses.</p><p>For more information, see power_ltiview.</p></td></tr><tr><td><strong>Hysteresis Designer</strong> — Design hysteresis characteristic for the saturable core<br>button</td><td><p>Open the Hysteresis Design Tool to design a hysteresis characteristic for the saturable core of the Saturable Transformer block and the Three-Phase Transformer blocks (Two Windings and Three Windings).</p><p>For more information, see power_hysteresis.</p></td></tr><tr><td><strong>Block Customizer</strong> — Create custom blocks<br>button</td><td><p>Open the power_customize dialog box to create custom SPS blocks.</p><p>For more information, see <a href="https://opal-rt.atlassian.net/wiki/spaces/PSPS/pages/1551795335/power_customize">power_customize</a>.</p></td></tr><tr><td><strong>Report Generator</strong> — Generate report of steady-state variables, initial states, and machine load flow<br>button</td><td><p>Open the Generate Report Tool dialog box to generate a report of steady-state variables, initial states, and machine load flow for a model.</p><p>For more information, see power_report.</p></td></tr></tbody></table>

### Preferences

<table data-header-hidden><thead><tr><th width="249.6666259765625"></th><th></th></tr></thead><tbody><tr><td><strong>Disable SPS warnings</strong> — Disable warnings during analysis and simulation<br>off (default) | on</td><td>Control display of SPS warnings during model analysis and simulation.</td></tr><tr><td><strong>Display SPS compilation messages</strong> — Display echo messages during analysis<br>off (default) | on</td><td>Control display of the command-line echo messages during model analysis.</td></tr><tr><td><strong>Use TLC file when in Accelerator Simulation Mode and for code generation</strong> — Use TLC state-space S-functions<br>off (default) | on</td><td><p>Select to use TLC state-space S-functions in accelerator mode and for code generation.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete.</p></td></tr><tr><td><strong>Disable ideal switching</strong> — Control model switching devices as current sources<br>off (default) | on</td><td><p>Select to model switching devices as current sources. By default, this option is not selected, which corresponds to the recommended setting for most of your applications.</p><p>Modeling switches, such as circuit breakers or power electronic devices, as current sources implies that the on-state switch resistance (Ron) cannot be zero.</p><p>In this modeling method, the switches cannot be connected in a series with an inductive circuit or with another switch or current source.</p><p>When this option is enabled, you must add a circuit (R or RC snubber) in parallel with the switches in your model so that the switches' off-state impedance has a finite value.</p><p>If your real circuit does not use snubbers, or if you want to simulate ideal switches with no snubber, you must at least use resistive snubbers with a high resistance value to introduce a negligible leakage current.</p><p>The drawback of introducing such high-impedance snubbers is that the large difference between the on-state and the off-state switch impedance produces a stiff state-space model.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Continuous.</p></td></tr><tr><td><strong>Disable snubbers in switching devices</strong> — Control snubber devices of power electronic and breaker blocks<br>off (default) | on</td><td><p>Select to disable the snubber devices of the power electronic and breaker blocks in your model.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Continuous and clear <strong>Disable ideal switching</strong>.</p></td></tr><tr><td><strong>Disable Ron resistances in switching devices</strong> — Control internal resistance of switches and power electronic devices<br>off (default) | on</td><td><p>Select to disable the internal resistance of switches and power electronic devices and to force the value to zero ohms.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Continuous and clear <strong>Disable ideal switching</strong>.</p></td></tr><tr><td><strong>Disable forward voltages in switching devices</strong> — Control internal forward voltage of power electronic devices<br>off (default) | on</td><td><p>Select to disable the internal forward voltage of power electronic devices and to force the value to zero volts.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Continuous and clear <strong>Disable ideal switching</strong>.</p></td></tr><tr><td><strong>Display circuit differential equations</strong> — Display differential equations in Diagnostic Viewer<br>off (default) | on</td><td><p>Select to display the differential equations of the model in the Diagnostic Viewer when the simulation starts.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Continuous and clear <strong>Disable ideal switching</strong>.</p></td></tr><tr><td><strong>Automatically handle Discrete solver and Advanced tab solver settings of blocks</strong> — Set descretization method automatically<br>off (default) | on</td><td><p>Select to automatically set the discretization method to Trapezoidal robust in models that contain at least one of the following blocks:</p><ul><li>Asynchronous Machine</li><li>Permanent Magnet Synchronous Machine</li><li>Simplified Synchronous Machine</li><li>Synchronous Machine</li><li>Surge Arrester</li><li>Variable Resistor</li><li>Variable Inductor</li><li>Variable Capacitor</li><li>Nonlinear Resistor</li><li>Nonlinear Inductor</li><li>Variable-Ratio Transformer</li><li>Any transformer blocks that are modeling saturation</li></ul><p>If your model contains none of these blocks, the discretization method is automatically set to Tustin/Backward Euler (TBE).<strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete.</p></td></tr><tr><td><strong>Discrete solver</strong> — Discrete solver to use to simulate model<br>Tustin/Backward Euler (TBE) (default) | Tustin | Backward Euler</td><td><p>Set to Tustin/Backward Euler (TBE) to simulate the model using a combination of the Tustin and Backward Euler methods.</p><p>Set to Tustin to discretize the electrical model using the Tustin method. If you use this solver, you need to specify the <em>Rs</em> and <em>Cs</em> snubber values to avoid numerical oscillations when the firing pulses are blocked (when the bridge is operating as a rectifier).</p><p>You can use the following formulas to compute the values of <em>Rs</em> and <em>Cs</em>:</p><p><span class="math">Rs > 2* Ts / Cs \\[8pt] Cs &#x3C; Pn /(1000*2pi* f * Vn ^2</span></p><p>where:</p><ul><li><em>Pn</em> is the nominal power of the single-phase or three-phase converter, in VA.</li><li><em>Vn</em> is the nominal line-to-line AC voltage, in Vrms.</li><li><em>f</em> is the fundamental frequency, in Hz.</li><li><em>Ts</em> is the sample time, in s.</li></ul><p>These values are derived from these criteria:</p><ul><li>The snubber leakage current at the fundamental frequency is less than 0.1% of the nominal current when power electronic devices are not conducting.</li><li>The RC time constant of the snubbers is larger than two times the sample time, <em>Ts</em>.</li></ul><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The <em>Rs</em> and <em>Cs</em> values that guarantee the numerical stability of the discretized bridge can be different from the actual values used in the physical circuit.</p></div><p>Set to Backward Euler to discretize the electrical model using the Backward Euler method.</p><p><strong>Dependencies:</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete and clear <strong>Automatically handle Discrete solver and Advanced tab solver settings of blocks</strong>.</p></td></tr><tr><td><strong>Interpolate switching events</strong> — Increase simulation speed<br>off (default) | on</td><td><p>Select to increase simulation speed by enabling the solver to interpolate in discrete models using power electronics.</p><p>When selected, the solver captures gate transitions of power electronic devices occurring between two sample times, allowing larger sample times (typically 20×) than you use with the standard solvers. For example, simulating a 5 kHz PWM converter with Tustin (no interpolation) or Tustin/Backward Euler normally requires a 1.0 µs sample time (sampling frequency = 200 × PWM frequency) to obtain a good resolution on pulse generation and guarantee accurate results. With interpolation enabled, using a sample time as large as 20 µs executes faster while preserving model accuracy.</p><p>When you select this option:</p><ul><li>Use a continuous pulse generator to guarantee the best accuracy on pulse generation. (Specify sample time = 0 in pulse-generation blocks.)</li><li>In the Configuration Parameters dialog box, select a continuous, variable-step solver (ode45 or ode23tb with default settings).</li><li>The continuous solver is required by the interpolation solver to compute the gate signals' time delays with respect to discrete sample times. The solver uses these pulse delays to interpolate between sample times and produce accurate results.</li></ul><p>To see how interpolation increases accuracy and simulation speed, see the Increased Accuracy and Simulation Speed Using Interpolation example model.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete, clear <strong>Automatically handle Discrete solver and Advanced tab solver settings of blocks</strong>, and set <strong>Discrete solver</strong> to Tustin.</p></td></tr><tr><td><strong>Use time-stamped gate signals</strong> — Capture evolution of states at different switching times<br>off (default) | on</td><td><p>When selected, the interpolation method computes model outputs at fixed sample times while taking into account switching events that occur between two sample times. The method receives pulses at fixed time steps and computes the time delays of the gate signals arriving within each time step. Computing the time delays enables the method to capture the evolution of states at different switching times.</p><p>When cleared, the interpolation method computes the time delays of the gate signal. When selected, the block does not compute the time delays of gate signals.</p><p>You then need to directly provide time-stamped gate signals to the switching devices in your model. For more information on the concept of time-stamped gate signals in SPS switching devices, see the Increased Accuracy and Simulation Speed Using Interpolation example.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete, clear <strong>Automatically handle Discrete solver and Advanced tab solver settings of blocks</strong>, set <strong>Discrete solver</strong> to Tustin, and select <strong>Interpolate switching events</strong>.</p></td></tr><tr><td><strong>Store switching topologies</strong> — Increase simulation speed<br>off (default) | on</td><td><p>Select to increase simulation speed by enabling the solver to store and reuse matrix computation results.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Continuous or Discrete and clear <strong>Automatically handle Discrete solver and Advanced tab solver settings of blocks</strong>.</p></td></tr><tr><td><strong>Buffer size (MBytes)</strong> — Buffer size for saving computations<br>100 (default) | positive scalar</td><td><p>Buffer size for saving state-space matrix computations.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Continuous or Discrete, clear <strong>Automatically handle Discrete solver and Advanced tab solver settings of blocks</strong>, and select <strong>Store switching topologies</strong>.</p></td></tr><tr><td><strong>Start simulation with initial electrical states from</strong> — Initial state value<br>blocks (default) | steady | zero</td><td><p>If you select:</p><ul><li>blocks — Initial state values defined in blocks are used for the simulation</li><li>steady — Forces all initial electrical state values to steady-state values</li><li>zero — Forces all initial electrical state values to zero</li></ul></td></tr><tr><td><strong>Solver tolerance</strong> — Maximum solver error<br>1e-4 (default) | positive scalar</td><td><p>Largest acceptable solver error.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete and expand <strong>Solver details for nonlinear elements</strong>.</p></td></tr><tr><td><strong>Maximum number of iterations</strong> — Iteration limit<br>100 (default) | positive scalar</td><td><p>Maximum number of iterations.</p><p>Iterations stop when the <strong>Solver tolerance</strong> is achieved, or when the <strong>Maximum number of iterations</strong> is reached.</p><p>A solution is usually found within 1 to 3 iterations.</p><p>An error message is returned and simulation stops if a solution is not found when the maximum number of iterations is exceeded.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete and expand <strong>Solver details for nonlinear elements</strong>.</p></td></tr><tr><td><strong>Continue Simulation if maximum number of iterations is reached</strong> — Limit maximum number of iterations<br>off (default) | on</td><td><p>Select to limit the maximum number of iterations. This parameter is used for real-time applications. Usually, limiting the number of iterations to 2 produces acceptable results.</p><p><strong>Dependencies</strong> To enable this parameter, set <strong>Simulation type</strong> to Discrete and expand <strong>Solver details for nonlinear elements</strong>.</p></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/smart-power-simulation-software-sps/blocks-functions-tools/simulation-and-analysis/powergui.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.
