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

# power\_analyze

## Description

The **power\_analyze function** computes the equivalent state-space model of the SPS electrical model built with SPS Software.

It evaluates the *A, B, C, D* standard matrices of the state-space system described by the equations

$$
\dot{x}=Ax+Bu \\\[8pt]
y=Cx+Du
$$

where the state vector *x* represents the inductor currents and capacitor voltages, the input vector u represents the voltage and current sources, and the output vector y represents the voltage and current measurements of the model.

Nonlinear elements, such as the switch devices, motors and machines, are simulated by current sources driven by the voltages across the nonlinear element terminals. The nonlinear elements produce additional current source inputs to the *u* vector, and additional voltage measurements outputs to the *y* vector.

The Simulink® blocks of the model, as well as internal Simulink models of the SPS nonlinear elements are not represented in the state-space matrices.

### State-Space Matrices

The *A, B, C, D* matrices are computed for the particular circuit topology where all the switch devices, if any, are considered to be open status (that is, with infinite impedance).

power\_analyze also computes the Aswitch, Bswitch, Cswitch, and Dswitch matrices for the circuit topology that take into account the initial state (open/closed) of the Breaker and Ideal Switch blocks present in the model. The initial state of power electronic devices (Diodes, Thyristors, and so on) is considered to be open, unless a nonzero initial current value is specified in the mask of the device when Lon parameter is different from zero.

For a circuit that contains no switches, the Aswitch, Bswitch, Cswitch, and Dswitch matrices have exactly the same values as the *A, B, C, D* matrices.

#### States

In SPS Software, each state variable name begins with a prefix Uc\_ for capacitor voltages or Il\_ for inductor currents, followed by the name of the block in which the element (C or L) is found.

A character vector is added to this prefix for blocks containing more than one inductance or capacitor. For example, the Linear Transformer block is represented with four state variables, one for each of the three leakage inductances, defined with the prefixes Il\_winding\_x:, where x is the winding number of the transformer, and one state for the magnetization inductance defined with the prefix Il\_Lm:.

#### Inputs

Each input state variable name begins with a prefix Uc\_ for voltage sources or Il\_ for current sources, followed by the name of the source block. Text can be added to the prefix for blocks containing more than one source. For example, the Synchronous Machine block produces two current inputs with prefixes I\_A: and I\_B: (phase A and phase B machine currents).

#### Outputs

Each output state variable name begins with a prefix U\_ for voltage outputs or I\_ for current outputs, followed by the name of the block that produces the output.

Text can be added to the prefix for blocks containing more than one output. For example, the Synchronous Machine block produces two voltage outputs with prefixes U\_AB: and U\_BC: (two machine phase-to-phase voltages).

### Sign Conventions

The following conventions are used for inputs:

* Source current flowing in the arrow direction is positive.
* Positive source voltage is indicated by a + sign on the icon.

The sign conventions used for voltages and currents of state variables and measurement outputs are described in [Measuring Voltages and Currents](https://www.opal-rt.com/docs/smart-power-simulation-software-sps/get-started/build-and-simulate-a-simple-circuit-using-sps.md#measuring-voltages-and-currents).

## Syntax

{% code lineNumbers="true" %}

```matlab
sps = power_analyze('sys','structure')
[A,B,C,D,x0,states,inputs,outputs,uss,xss,yss,frequencies,Hlin] =...
power_analyze('sys')
sps = power_analyze('sys','sort')
sps = power_analyze('sys','ss')
power_analyze('sys','net')
SW = power_analyze('sys','getSwitchStatus')
sps = power_analyze('sys','setSwitchStatus',SW)
```

{% endcode %}

## Output Arguments: Structure

{% code lineNumbers="true" %}

```matlab
sps = power_analyze('sys','structure')
```

{% endcode %}

**sps:** Structure array with fields and values describing the model sys. The fields of the structure array are defined in the following order.

The table uses the following conventions:

* nstates is the number of states.
* ninput is the number of inputs.
* noutput is the number of outputs.
* nfreq is the number of input source frequencies.

<table data-header-hidden><thead><tr><th width="249.88885498046875"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td></tr><tr><td>circuit</td><td>Name of the model</td></tr><tr><td>states</td><td>char array of state variable names</td></tr><tr><td>inputs</td><td>char array of system input names</td></tr><tr><td>outputs</td><td>char array of system output names</td></tr><tr><td>A</td><td>nstates-by-nstates state-space <em>A</em> matrix</td></tr><tr><td>B</td><td>nstates-by-ninput state-space <em>B</em> matrix</td></tr><tr><td>C</td><td>noutput-by-nstates state-space <em>C</em> matrix</td></tr><tr><td>D</td><td>noutput-by-ninput state-space <em>D</em> matrix</td></tr><tr><td>x0</td><td>nstates-by-1 vector of initial conditions of the state variables listed in states</td></tr><tr><td>xss</td><td>nstates-by-nfreq steady-state values of states. A set of values is computed for every frequency specified in the frequencies vector.</td></tr><tr><td>uss</td><td>ninput-by-nfreq steady-state values of inputs. A set of values is computed for every frequency specified in the frequencies vector.</td></tr><tr><td>yss</td><td>noutput-by-nfreq steady-state values of outputs. A set of values is computed for every frequency specified in the frequencies vector.</td></tr><tr><td>frequencies</td><td>1-by-nfreq vector of input source frequencies ordered by increasing values</td></tr><tr><td>DependentStates</td><td>char array of dependent state variable names. The dependent states are not included in the state-space equations.</td></tr><tr><td>x0DependentStates</td><td>Vector of initial conditions of dependent states</td></tr><tr><td>xssDependentStates</td><td>nstates-by-nfreq steady-state values of dependent states</td></tr><tr><td>Adiscrete</td><td><p>Discrete state-space <em>A</em> matrix.</p><p>Returns an empty value when the Powergui is in continuous or in phasor mode.</p></td></tr><tr><td>Bdiscrete</td><td><p>Discrete state-space <em>B</em> matrix.</p><p>Returns an empty value when the Powergui is in continuous or in phasor mode.</p></td></tr><tr><td>Cdiscrete</td><td><p>Discrete state-space <em>C</em> matrix.</p><p>Returns an empty value when the Powergui is in continuous or in phasor mode.</p></td></tr><tr><td>Ddiscrete</td><td><p>Discrete state-space <em>D</em> matrix.</p><p>Returns an empty value when the Powergui is in continuous or in phasor mode.</p></td></tr><tr><td>x0discrete</td><td><p>Vector of discrete initial conditions.</p><p>Returns an empty value when the Powergui is in continuous or in phasor mode.</p></td></tr><tr><td>SampleTime</td><td>Sample time value used to compute discrete state-space matrices</td></tr><tr><td>Aswitch</td><td><em>A</em> matrix taking into account the initial status of switch devices</td></tr><tr><td>Bswitch</td><td><em>B</em> matrix taking into account the initial status of switch devices</td></tr><tr><td>Cswitch</td><td><em>C</em> matrix taking into account the initial status of switch devices</td></tr><tr><td>Dswitch</td><td><em>D</em> matrix taking into account the initial status of switch devices</td></tr><tr><td>x0switch</td><td>Vector of initial values of switch currents</td></tr><tr><td>Hlin</td><td><p>noutput-by-ninput-by-nfreq complex transfer function of impedances of the linear system corresponding to the frequencies contained in the frequencies vector.</p><p>For a particular frequency, Hlin is defined byyss(:,i) = Hlin(:,:,i) * uss(:,i)</p></td></tr><tr><td>OscillatoryModes</td><td>Display the oscillatory modes of the state-space system</td></tr></tbody></table>

\[A,B,C,D,x0,states,inputs,outputs,uss,xss,yss,frequencies,Hlin] =... power\_analyze('sys') returns the state-space calculations in separate variables.

### Output Arguments: Sort

{% code lineNumbers="true" %}

```matlab
sps = power_analyze('sys','sort')
```

{% endcode %}

**sps:** Structure array with the following fields related to the interconnection of SPS blocks in a model.

The fields are defined in the following order.

<table data-header-hidden><thead><tr><th width="249.888916015625"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td></tr><tr><td>circuit</td><td>Name of the model</td></tr><tr><td>SampleTime</td><td>Sample time for discrete systems</td></tr><tr><td>RlcBranch</td><td>rlc matrix in the power_statespace format</td></tr><tr><td>RlcBranchNames</td><td>List of blocks containing the state variable</td></tr><tr><td>SourceBranch</td><td>Source matrix in the power_statespaceformat</td></tr><tr><td>SourceBranchNames</td><td>Names of the blocks defined as sources</td></tr><tr><td>InputNames</td><td>Names of the inputs of the system</td></tr><tr><td>OutputNames</td><td>Names of the outputs of the system</td></tr><tr><td>OutputExpressions</td><td>Output expression in the power_statespace format</td></tr><tr><td>OutputMatrix</td><td>Output expression in matrix format (internal)</td></tr><tr><td>MeasurementBlocks</td><td>Names of the voltage and current measurement blocks</td></tr></tbody></table>

### Output Arguments: ss

{% code lineNumbers="true" %}

```matlab
sps = power_analyze('sys','ss') 
```

{% endcode %}

creates a continuous state-space model of the model sys with matrices *A, B, C, D*. You must have Control System Toolbox™ software installed for this option.

The output is a state-space object.

### Output Arguments: Net

{% code lineNumbers="true" %}

```matlab
power_analyze('sys','net') 
```

{% endcode %}

generates a netlist stored in a file, sys.net. The file contains the node numbers automatically generated by power\_analyze, as well as parameter values of all linear elements. See the formats described in the power\_statespace reference page.

### Output Arguments: getSwitchStatus

{% code lineNumbers="true" %}

```matlab
SW = power_analyze('sys','getSwitchStatus')
```

{% endcode %}

**SW:** Structure array with switch names and their initial status. You can use the SW structure to specify switch statuses for a particular circuit topology and to compute the corresponding state-space matrices using the command sps = power\_analyze('sys','setSwitchStatus',SW). The SW structure contains the following fields.

<table data-header-hidden><thead><tr><th width="250.111083984375"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td></tr><tr><td>SwitchNames</td><td>Names of the switches of the system</td></tr><tr><td>SwitchStatus</td><td>Vector of initial states of switches</td></tr></tbody></table>

### Output Arguments: setSwitchStatus

{% code lineNumbers="true" %}

```matlab
sps = power_analyze('sys','setSwitchStatus',SW)
```

{% endcode %}

**sps:** Structure array with fields and values describing the state-space matrices of model sys for the switch status defined in SW. Use the command SW = power\_analyze('sys','getSwitchStatus') to obtain the SW structure array.

<table data-header-hidden><thead><tr><th width="249.5555419921875"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td></tr><tr><td>A</td><td>nstates-by-nstates state-space <em>A</em> matrix</td></tr><tr><td>B</td><td>nstates-by-ninput state-space <em>B</em> matrix</td></tr><tr><td>C</td><td>noutput-by-nstates state-space <em>C</em> matrix</td></tr><tr><td>D</td><td>noutput-by-ninput state-space <em>D</em> matrix</td></tr><tr><td>x0</td><td>nstates-by-1 vector of initial conditions of the state variables listed in states</td></tr></tbody></table>

## Examples

Obtain the state-space matrices and steady-state voltages and currents for the **power\_netsim2** circuit.

The command

{% code lineNumbers="true" %}

```matlab
sps=power_analyze('power_netsim2','structure');
```

{% endcode %}

returns the state-space model in the sps structure variable.

{% code lineNumbers="true" %}

```matlab
sps.A =
1.0e+04 *
			 0    			6.2500
-0.0083			-1.4250
sps.uss =
	0
	1000
sps.xss =
	1.0e+02 *
	4.8392 - 5.1314i
	0.0310 + 0.0292i
sps.yss =
	1.0e+02 *
	8.5535 - 1.6287i	
	 0
sps.inputs = 
	I_Breaker
	U_Source
sps.outputs =
	U_Breaker
	I_Current Measurement
```

{% endcode %}

The inductor current of the 51-ohm, 12-mH block and the capacitor voltage of the 120-ohm, 16-µF block are the two state variables in this circuit. The Breaker block is a nonlinear element that is represented by a current source (the first input) driven by the voltage across its terminals (the first output).


---

# 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/power_analyze.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.
