power_statespace

(To be removed) Compute state-space model of linear electrical circuit

The Specialized Power Systems library will be removed in R2026a. Use the Simscape™ Electrical™ blocks and functions instead. For more information on updating your models, see Upgrade Specialized Power System Models to use Simscape Electrical Blocks.

Syntax

[A,B,C,D,states,x0,x0sw,rlsw,u,x,y,freq,Asw,Bsw,Csw,Dsw,Hlin] = power_statespace(rlc,switches,source,line_dist,yout,y_type,unit ) [A,B,C,D,states,x0,x0sw,rlsw,u,x,y,freq,Asw,Bsw,Csw,Dsw,Hlin] = power_statespace(rlc,switches,source,line_dist,yout,y_type,unit , net_arg1,net_arg2,net_arg3,...,netsim_flag,fid_outfile, freq_sys,ref_node,vary_name,vary_val)

Description

[A,B,C,D,states,x0,x0sw,rlsw,u,x,y,freq,Asw,Bsw,Csw,Dsw,Hlin] = power_statespace(rlc,switches,source,line_dist,yout,y_type,unit ) computes the state-space model of a linear electrical circuit expressed as

$\begin{array}{l} \dot{x} = A x + B u \\ y = C x + D u \end{array}$

where x is the vector of state-space variables (inductor currents and capacitor voltages), u is the vector of voltage and current inputs, and y is the vector of voltage and current outputs.

When you build a circuit from Simscape Electrical Specialized Power Systems blocks, power_statespace is automatically called by the power_analyze command. power_statespace is also available as a stand-alone command for expert users. This allows you to generate state-space models without using the Simscape Electrical Specialized Power Systems block modeling interface and to access options that are not available through the Simscape Electrical Specialized Power Systems library. For example, using power_statespace, you can model transformers and mutual inductances with more than three windings.

You must call power_statespace with a minimum of seven input arguments.

The linear circuit can contain any combination of voltage and current sources, RLC branches, multiwinding transformers, mutually coupled inductances, and switches. The state variables are inductor currents and capacitor voltages.

The state-space representation (matrices A,B,C,D, and vector x0) computed by power_statespace can then be used in a Simulink^® system, via a State-Space block, to perform simulation of the electrical circuit. Nonlinear elements (mechanical or power electronic switches, transformer saturation, machines, distributed parameter lines, etc.) can be connected to the linear circuit.

These Simulink models are interfaced with the linear circuit through voltage outputs and current inputs of the state-space model. You can find the models of the nonlinear elements provided with Simscape Electrical software in the Specialized Power Systems library.

[A,B,C,D,states,x0,x0sw,rlsw,u,x,y,freq,Asw,Bsw,Csw,Dsw,Hlin] = power_statespace(rlc,switches,source,line_dist,yout,y_type,unit , net_arg1,net_arg2,net_arg3,...,netsim_flag,fid_outfile, freq_sys,ref_node,vary_name,vary_val) computes the same as above but you can also specify optional arguments. To use these optional arguments, the number of input arguments must be 12, 13, 14 or 16.

Input Arguments

The number of input arguments must be 7, 12, 13, 14, or 16. Arguments 8 to 16 are optional. The first seven arguments that must be specified are

rlc: Branch matrix specifying the network topology as well as the resistance R, inductance L, and capacitance C values. See format below.
switches: Switch matrix. Specify an empty variable if no switches are used. See format below.
source: Source matrix specifying the parameters of the electrical voltage and current sources. Specify an empty variable if no sources are used. See format below.
line_dist: Distributed parameter line matrix. Specify an empty variable if no distributed lines are used. See format below.
yout: Matrix of output, expressed as character vectors. See format below.
y_type: Integer vector indicating output types (0 for voltage output, 1 for current output).
unit: Character vector specifying the units to be used for R, L, and C values in the rlc matrix. If unit = 'OHM', R L C values are specified in ohms Ω at the fundamental frequency specified by freq_sys (default value is 60 Hz). If unit = 'OMU', R L C values are specified in ohms (Ω), millihenries (mH), and microfarads (µF).

The last nine arguments are optional. The first three are used to pass arguments from the power_analyze command. Hereafter, only the arguments to be specified when power_statespace is used as a stand-alone command are described:

net_arg1, net_arg2, net_arg3: Used to pass arguments from power_analyze. Specify an empty variable [] for each of these arguments.
netsim_flag: Integer controlling the messages displayed during the execution of power_statespace. Default value is 0.
If netsim_flag = 0, the version number, number of states, inputs, outputs, and modes are displayed. Output values are displayed in polar form for each source frequency.
If netsim_flag = 1, only version number, number of states, inputs, and outputs are displayed.
If netsim_flag = 2, no message is displayed during execution.
fid_outfile: File identifier of the power_statespace output file containing parameter values, node numbers, steady-state outputs, and special messages. Default value is 0.
freq_sys: Fundamental frequency (Hz) considered for specification of X_L and X_C reactances if unit is set to 'OHM'. Default value is 60 Hz.
ref_node: Reference node number used for ground of PI transmission lines. If −1 is specified, the user is prompted to specify a node number.
vary_name: Matrix containing the symbolic variable names used in output, expressed as character vectors. These variables must be defined in your MATLAB^® workspace.
vary_val: Vector containing the values of the variable names specified in vary_name.

Output Arguments

A,B,C,D: state-space matrices of the linear circuit with all switches open.
```
A(nstates, nstates) , B(nstates, ninput), 
C(noutput, nstates) , D(noutput, ninput),
```
where nstates is the number of state variables, ninput is the number of inputs, and noutput is the number of outputs.
states: Matrix containing the names of the state variables. Each name has the following format:
Inductor currents: Il_bxx_nzz1_zz2
Capacitor voltages: Uc_bxx_nzz1_zz2
where
```
xx = branch number
zz1 = first node number of the branch
zz2 = second node number of the branch
```

The last lines of the states matrix, which are followed by an asterisk, indicate inductor currents and capacitor voltages that are not considered as state variables. This situation arises when inductor currents or capacitor voltages are not independent (inductors forming a cut set – for example, inductors connected in series – or capacitors forming a loop). The currents and voltages followed by asterisks can be expressed as a linear combination of the other state variables:

x0: Column vector of initial values of state variables considering the open or closed status of switches.
x0sw: Vector of initial values of switch currents.
rlsw: Matrix (nswitch,2) containing the R and L values of series switch impedances in ohms (Ω) and henries (H). nswitch is the number of switches in the circuit.
u,x,y: Matrices u(ninput,nfreq), x(nstates,nfreq), and y(noutput,nfreq) containing the steady-state complex values of inputs, states, and outputs. nfreq is the length of the freq vector. Each column corresponds to a different source frequency, as specified by the next argument, freq.
freq: Column vector containing the source frequencies ordered by increasing frequency.
Asw,Bsw,Csw,Dsw: State-space matrices of the circuit including the closed switches. Each closed switch with an internal inductance adds one extra state to the circuit.
Hlin: Three-dimensional array (nfreq, noutput, ninput) of the nfreq complex transfer impedance matrices of the linear system corresponding to each frequency of the freq vector.

Format of the RLC Input Matrix

Two formats are allowed:

Six columns: Implicit branch numbering. Branch numbers correspond to the RLC line numbers.
Seven columns: Explicit branch numbering. Branch number Nobr is assigned by the user.

Each line of the RLC matrix must be specified according to the following format.

[node1, node2, type, R, L, C, Nobr] for RLC branch or line branch

[node1, node2, type, R, L, C, Nobr] for transformer magnetizing branch

[node1, node2, type, R, L, U, Nobr] for transformer winding

[node1, node2, type, R, L, U, Nobr] for mutual inductances

node1: First node number of the branch. The node number must be positive or zero. Decimal node numbers are allowed.
node2: Second node number of the branch. The node number must be positive or zero. Decimal node numbers are allowed.
type: Integer indicating the type of connection of RLC elements, or, if negative, the transmission line length:
type = 0: Series RLC element
type = 1: Parallel RLC element
type = 2: Transformer winding
type = 3: Coupled (mutual) winding
If type is negative, the transmission line is modeled by a PI section of length |type|. See details below.

For a mutual inductor or a transformer having N windings, N+1 consecutive lines must be specified in RLC matrix:

N lines with type = 2 or type = 3; (one line per winding). Each line specifies R/L/U or R/Xl/Xc where [R/L, R/Xl = winding resistance and leakage reactance for a transformers or winding resistance and self reactance for mutually coupled windings. U is the nominal voltage of transformer winding (specify 0 if type = 3).
One extra line with type = 1 for the magnetizing branch of a transformer (parallel Rm/Lm or Rm/Xm) or one line with type = 0 for a mutual impedance (series Rm/Lm or Rm/Xm).

For a transformer magnetizing branch or a mutual impedance, the first node number is an internal node located behind the leakage reactance of the first winding. The second node number must be the same as the second node number of the first winding.

To model a saturable transformer, you must use a nonlinear inductance instead of the linear inductance simulating the reactive losses. Set the Lm/Xm value to 0 (no linear inductance) and use the Saturable Transformer block, set with proper flux-current characteristics.

This block can be found in the Fundamental Blocks/Elements library. It must be connected to the linear part of the system (State-Space block or S-function) between a voltage output (voltage across the magnetizing branch) and a current input (current source injected into the transformer internal node).

If type is negative, its absolute value specifies the length (km) of a transmission line simulated by a PI section. For a transmission line, the R/L/C or R/Xl/Xc values must be specified in Ω/km, mH/km, and µF/km, or in Ω/km.

Parameter	Description
`R`	Branch resistance (Ω)
`Xl`	Branch inductive reactance (Ω at `freq_sys`) or transformer winding leakage reactance (Ω at `freq_sys`)
`L`	Branch inductance (mH)
`Xc`	Branch capacitive reactance (Ω at `freq_sys`). The negative sign of `Xc` is optional.
`C`	Capacitance (µF)
`U`	Nominal voltage of transformer winding. The same units (volts or kV) must be used for each winding. For a mutual inductance (`type=3`), this value must be set to zero.
Zero value for `R`, `L` or `Xl`, `C` or `Xc` in a series or parallel branch indicates that the corresponding element does not exist.

The following restrictions apply for transformer winding R-L values. Null values are not allowed for secondary impedances if some transformer secondaries form loops (as in a three-phase delta connection). Specify a very low value for R or L or both (e.g., 1e-6 pu based on rated voltage and power) to simulate a quasi-ideal transformer. The resistive and inductive parts of the magnetizing branch can be set to infinite (no losses; specify Xm = Rm = inf).

Format of the Source Input Matrix

Three formats are allowed:

Five columns: All sources are generating the same frequency specified by freq_sys.
Six columns: The frequency of each source is specified in column 6.
Seven columns: The seventh column is used to specify the type of nonlinear element modeled by the current source.

Each line of the source matrix must be specified according to the following format:

[ node1, node2, type, amp, phase, freq, model ]

node1, node2: Node numbers corresponding to the source terminals. These are the polarity conventions:
- Voltage source: node1 is the positive terminal.
- Current source: Positive current flowing from node1 to node2 inside the source.
type: Integer indicating the type of source: 0 for voltage source, 1 for current source.
amp: Amplitude of the AC or DC voltage or current (V or A).
phase: Phase of the AC voltage or current (degree).
freq: Frequency (Hz) of the generated voltage or current. Default value is 60 Hz. For a DC voltage or current source, specify phase = 0 and freq = 0. amp can be set to a negative value. The generated signals are
amp * sin(2π*freq*t + phase)for AC, amp for DC.
model: Integer specifying the type of nonlinear element modeled by the current source (saturable inductance, thyristor, switch,...). Used by power_analyze only.

Order in Which Sources Must Be Specified

The commands that compute the state-space representation of a system expect the sources in a certain order. You must respect this order in order to obtain correct results. You must be particularly careful if the system contains any switches. This is the proper ordering of sources:

The currents from all switches that have a null inductance (Lon = 0), if any.
The currents from all nonlinear models that have a finite inductance (switches with Lon > 0, the magnetizing inductance in saturable transformers, etc.), if any.
All other voltage and current sources in any order, if any.

Refer to the Example section below for an example illustrating proper ordering of sources for a system containing nonlinear elements.

Format of the Switches Input Matrix

Switches are nonlinear elements simulating mechanical or electronic devices such as circuit breakers, diodes, or thyristors. Like other nonlinear elements, they are simulated by current sources driven by the voltage appearing across their terminals. Therefore, they cannot have a null impedance. They are simulated as ideal switches in series with a series R-L circuit. Various models of switches (circuit breaker, ideal switch, and power electronic devices) are available in the Simscape Electrical Specialized Power Systems library. They must be interconnected to the linear part of the system through appropriate voltage outputs and current inputs.

The switch parameters must be specified in a line of the switches matrix in seven different columns, according to the following format.

[ node1, node2, status, R, L/Xl, no_I , no_U ]

Parameter	Description
`node1, node2`	Node numbers corresponding to the switch terminals
`status`	Code indicating the initial status of the switch at t = 0: 0 = open; 1 = closed
`R`	Resistance of the switch when closed (Ω)
`L/Xl`	Inductance of the switch when closed (mH) or inductive reactance (Ω at freq_sys)
For these last two fields, you must use the same units as those specified for the RLC matrix. Either field can be set to 0, but not both.

The next two fields specify the current input number and the voltage output number to be used for interconnecting the switch model to the State-Space block. The output number corresponding to the voltage across a particular switch must be the same as the input number corresponding to the current from the same switch (see Example section below):

no_I: Current input number coming from the output of the switch model
no_U: Voltage output number driving the input of the switch model

Format of the Line_Dist Matrix

The distributed parameter line model contains two parts:

A linear part containing current sources and resistances that are connected at the line sending and receiving buses together with the linear circuit.
A nonlinear part available in the Distributed Parameters Line block of the Elements library. This block performs the phase-to-mode transformations of voltage and currents and simulates the transmission delays for each mode. The distributed_param_line block must be connected to appropriate voltage outputs and current inputs of the linear part of the system. The line parameters have to be specified in the line_dist matrix and also in the Distributed Parameters Line block.

Each row of the line_dist matrix is used to specify a distributed parameter transmission line. The number of columns of line_dist depends on the number of phases of the transmission line.

For an nphase line, the first (4 + 3 * nphase + nphase^2) columns are used. For example, for a three-phase line, 22 columns are used.

[nphase, no_I, no_U, length, L/Xl, Zc, Rm, speed, Ti]

Parameter	Description
`nphase`	Number of phases of the transmission line
`no_I`	Input number in the source matrix corresponding to the first current source Is_1 of the line model. Each line model uses 2*nphase current sources specified in the source matrix as follows: Is_1, Is_2,..., Is_nphase for the sending end followed by Ir_1, Ir_2,..., Ir_nphase for the receiving end.
`no_U`	Output number of the state-space corresponding to the first voltage output Vs_1 feeding the line model. Each line model uses 2*nphase voltage outputs in the source matrix as follows: Vs_1, Vs_2,..., Vs_nphase for the sending end followed by Vr_1, Vr_2,..., Vr_nphase for the receiving end.
`length`	Length of the line (km)
`Zc`	Vector of the nphase modal characteristic impedances (Ω)
`Rm`	Vector of the nphase modal series resistances (Ω/km)
`speed`	Vector of the nphase modal propagation speeds (km/s)
`Ti`	Transformation matrix from mode to phase currents such that Iphase = Ti * Imod. The nphase * nphase matrix must be given in vector format, [col_1, col_2,... col_nphase].

Format of the Yout Matrix

The desired outputs are specified by the matrix yout. Each line of the yout matrix must be an algebraic expression containing a linear combination of states and state derivatives, specified according to the following format.

Parameter	Description
`Uc_bn`	Capacitor voltage of branch n
`Il_bn`	Inductor current of branch n
`dUc_bn`	Derivative of `Uc_bn` or `Il_bn`
`Un, In`	Source voltage or current specified by line n of the source matrix
`U_nx1_x2`	Voltage between nodes x1 and x2 = Ux1 −Ux2
`I_bn`	Current in branch n flowing from node1 to node2 (See format of RLC matrix). For a parallel RLC branch, `I_bn` corresponds to the total current IR + IL + IC.
`I_bn_nx`	Current flowing into node x of a PI transmission line specified by line n of the RLC matrix. This current includes the series inductive branch current and the capacitive shunt current.

Each output expression is built from voltage and current variable names defined above, their derivatives, constants, other variable names, parentheses and operators (+ − * / ^), in order to form a valid MATLAB expression. For example

yout =
char(['R1*I_b1+Uc_b3-L2*dIl_b2','U_n10_20','I2+3*I_b5']);

If variable names are used (R1 and L2 in the above example), their names and values must be specified by the two input arguments vary_name and vary_val.

Sign Conventions for Voltages and Currents

Parameter	Sign Convention
`I_bn, Il_bn, In`	Branch current, inductor current of branch n, or current of source #n is oriented from `node1` to `node2`
`I_bn_nx`	Current at one end (node x) of a PI transmission line. If x = `node1`, the current is entering the line. If x = `node2`, the current is leaving the line.
`Uc_bn, Un`	Voltage across capacitor or source voltage (`Unode1 − Unode2`)
`U_nx1_x2`	Voltage between nodes x1 and x2 = Ux1 − Ux2. Voltage of node x1 with respect to node x2.

Order in Which Outputs Must Be Specified

The commands that compute the state-space representation of a system expect the outputs to be in a certain order. You must respect this order in order to obtain correct results. You must be particularly careful if the system contains any switches. The following list gives the proper ordering of outputs:

The voltages across all switches that have a null inductance (Lon = 0), if any
The currents of all switches that have a null inductance (Lon = 0), if any, in the same order as the voltages above
The voltages across all nonlinear models that have a finite inductance (switches with Lon > 0, the magnetizing inductance in saturable transformers, etc.)
All other voltage and current measurements that you request, in any order

Refer to the Example section below for an example illustrating proper ordering of outputs for a system containing nonlinear elements.