> 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/network-rlc/state-space.md).

# State-Space

## Description

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-4da227f3d40a7e68e734dff4c93fe20c8baca8bc%2Fimage%20(1217).png?alt=media" alt="" width="198"><figcaption></figcaption></figure>

The **State-Space Device** block, located in the **Network RLC** library, models the generic current–voltage relationship of a device using state-space equations. The relationship may originate in the frequency domain, where a vector of currents entering the device is related to a vector of voltages at external nodes (connectivity pins) through an admittance matrix. This frequency-domain formulation can be converted to an equivalent state-space representation in the time domain.

The size of the current vector must equal the size of the voltage vector, which defines the dimensions of the corresponding square matrices. The time-domain equations are discretized using trapezoidal integration. The resulting discrete system integrates into the main HYPERSIM network equations for simultaneous solution.

### Example

## Single phase network

This simple example compares the simulation of an actual circuit to its equivalent state-space model. It has one independent state variable and two external connectivity pins (nodes). The current and voltage vectors have a size of 2. The currents i1 and i2 are entering the circuit pins as shown on the diagram. Along the real network, the state space representation is tested using the two methods to import input data (data file and manually entered matrices). The voltage sources have been set to 600V with a 60 Hz frequency. One-phase node connectors have been used to connect bundle pins to buses.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-73304faf8d07ccf9c6c1ddcbbcfcf1a62048f1be%2Fimage%20(317).png?alt=media" alt=""><figcaption><p>Single-phase example diagram</p></figcaption></figure>

The symbolic matrix A is given by:

$$
A =- \frac{1}{R1C1}
$$

The other matrices are:

$$
B = \begin{bmatrix}
\frac{1}{R\_1 C\_1} & -\frac{1}{R\_1 C\_1}
\end{bmatrix} \space , \space C = \begin{bmatrix}
-\frac{1}{R\_1} \\
\frac{1}{R\_1}
\end{bmatrix} \space , \space
D = \begin{bmatrix}
-\dfrac{1}{R\_1} + \dfrac{1}{R\_2} & -\dfrac{1}{R\_1} - \dfrac{1}{R\_2} \\
\dfrac{1}{R\_1} - \dfrac{1}{R\_2} & \dfrac{1}{R\_1} + \dfrac{1}{R\_2}
\end{bmatrix} \text{ and }
D\_1 = \begin{bmatrix}
C\_2 & -C\_2 \\
-C\_2 & C\_2
\end{bmatrix}
$$

Since both state-space and circuit representations are mathematically identical, the simulation waveforms from both circuits should be the same. During the simulation, the breaker is opened at t=30ms and then closed at t=60ms. The simulation results (v2 voltage) validate the state space for both input methods.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c7b7c80a1cc95f198c7751f80a64adecb3ac5cb7%2Fimage%20(318).png?alt=media" alt=""><figcaption><p>Simulation results</p></figcaption></figure>

## Three-phase network

The test case is a reduction of a small 225kV network as presented below

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-57d78b9a4ed606ed66c161ac2ccea7a7c1519742%2Fimage%20(319).png?alt=media" alt="" width="563"><figcaption><p>Three-phase network diagram</p></figcaption></figure>

The network equivalent has two terminals BUS1 and BUS3. Only the two central PI-lines will be kept. A 10 Ohm single phase fault (phase A) is applied between these PI-lines at t=30ms and is\
eliminated at t=60ms. This scenario is used for both networks (reduced one and complete one).

The network reduction has been done within EMTP to get the 25 poles input data file. Figure 10 below shows the reduced network.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-cb73fec88268fefb370f993829e4ba014cb96800%2Fimage%20(320).png?alt=media" alt="" width="563"><figcaption><p>Reduced network diagram</p></figcaption></figure>

Voltage sources have been replaced by a Norton equivalent to cope with the State Space modelling which is considered as an impedance. Simulation results of the fault current and voltage node are superposed for the complete network (HYP1) and the reduced one (HYP2).

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-e20fb2307fca7a0fd6440a2e568c500c77bf7f00%2Fimage%20(321).png?alt=media" alt="" width="563"><figcaption><p>Fault node voltage (phase A)</p></figcaption></figure>

The superposition of the results is quite good. It demonstrates the State-Space representation relevance where precision is equally the same as the real network (relative difference).

<details>

<summary><strong>Data used for each cases</strong></summary>

* 50Hz frequency
* RL load on BUS3 R=480 Ohm, L=3.06H
* Coupling PI-Line between AC1 and AC2 voltage source R=17.5 Ohm, L=351mH, C=189µF
* Other PI-Lines R=1.75 oHm, L=35.1 mH, C=189 µF
* BUS1 and BUS3 resistance R=1 MOhm
* The two Thevenin equivalent voltage sources (AC1 and AC2) are initialized from Load Flow. Constraints are a swing bus on AC1 which set the voltage as 240kV RMS
* (225kV is the reference voltage) A PQ constraint is set for AC2 voltage source P=-200 MW and Q=-10 MVar. The source RL values are R=4 Ohm, L=70 mH
* Single phase fault applied at t=30ms and eliminated at t=60ms
* Fault resistance value R=10 Ohm

Then, for the reduced network the two Norton equivalents have also been initialized from EMTP Load Flow. Values of each current (balanced three-phase system) source are:

* AC2 5.562e3 for module peak and -90.2 deg for angle
* AC1 6.923e3 for module peak and -74.8 deg for angle

</details>

## Mask parameters

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-1b15a6dc8a3e8631b87acae30022636fdc52e6ae%2Fstate-space.jpg?alt=media" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="General" %}

<table><thead><tr><th width="208">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>The source page does not provide parameter details.</td></tr><tr><td><strong>EMT .data file</strong></td><td>Name of the file which contains all necessary matrix data (EMTP .dat file)</td></tr><tr><td><strong>Type</strong></td><td>Select mode : Load File to automatically update data or Matrix to enter manually state-space model matrices A,B,C,D and D1</td></tr><tr><td><strong>Number of nodes</strong></td><td>n_inputs size of the input matrices, automatically fill with the .data file</td></tr><tr><td><strong>Number of states</strong></td><td><p>n_states size of the input matrices, automatically fill with the .data file</p><ul><li>The dimensions of the square <strong>matrix A</strong> n_states.</li><li><strong>Matrix B</strong> must have n_states rows and n_inputs (size of voltage vector and the number of connectivity pins) columns.</li><li><strong>Matrix C</strong> must have n_inputs rows and n_states columns.</li><li><strong>Matrix D</strong> must have n_inputs rows and n_inputs columns.</li><li><strong>Matrix D1</strong> is optional and must have n_inputs rows and n_inputs columns.</li></ul></td></tr><tr><td><strong>Number of poles</strong></td><td>In the load file input mode, the number of poles indicates the complexity of the State Space. It is related to the frequency range and precision of the vector fitting used to get the input file.</td></tr></tbody></table>
{% endtab %}

{% tab title="Matrix" %}
After setting sizes in General tab, matrices values can be entered manually in the Matrix tab. Checkboxes allow the user to include or exclude matrix definition.\
By default, optional D1 matrix is unchecked.
{% endtab %}

{% tab title="Initial Conditions" %}

<table><thead><tr><th width="285">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>I<strong>nitial conditions for states</strong></td><td>Must be check, to activate the initialization</td></tr><tr><td><strong>A,B,C,D,E,F</strong></td><td>Initial values for the states vector, can be any real number</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

<details>

<summary><strong>EMTP .data file format</strong></summary>

* First line, free format, space separated numbers: n\_outs n\_inputs n\_states n\_D1\
  In this version the number of outputs n\_outs is strictly equal to the number of inputs n\_inputs (number of nodes field). This means that the size of the current vector is equal to the size of the voltage vector. The size of matrix D1 is given by n\_D1, it is equal to 0 when there is no D1 matrix or n\_inputs otherwise.
* Matrix A rows, free format, space separated cells, one matrix row by text line.
* Matrix B rows, free format, space separated cells, one matrix row by text line.
* Matrix C rows, free format, space separated cells, one matrix row by text line.
* Matrix D rows, free format, space separated cells, one matrix row by text line.
* Optional matrix D1 rows, free format, space separated cells, one matrix row by text line.

</details>

## Conserving ports

When the device data is completed its bundle pin is automatically updated to include the required number of pins (n\_inputs). This is the size of the voltage vector. To connect to any pin it is necessary to extend the bundle signal and right-click to select the Breakout command. The available pins are listed in the appearing panel. Non-required pins must be erased from this panel before clicking the OK button. In the case of all pins have been selected.

<table><thead><tr><th width="172">Port</th><th>Description</th></tr></thead><tbody><tr><td><strong>net_1, ..net_i</strong></td><td>Network connection, i is the n_inputs</td></tr></tbody></table>

## Inputs

This block has no inputs

## Outputs

This block has no outputs

## References

\[1] B. Bruned, C. Martin, S. Dennetière, Y. Vernay, "Implementation of a unified modelling between EMT tools for network Studies", submitted to the International Conference on Power Systems Transients (IPST2017) in Seoul, Republic of Korea, 2017.


---

# 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/network-rlc/state-space.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.
