> 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/get-started/build-and-simulate-a-simple-circuit-using-sps.md).

# Build and Simulate a Simple Circuit Using SPS

## Introduction

SPS allows you to build and simulate electrical circuits containing linear and nonlinear elements.

In this section, you

* Explore the SPS library.
* Learn how to build a simple circuit from the SPS library.
* Interconnect Simulink® blocks with your circuit.

The circuit in the figure represents an equivalent power system feeding a 300-km transmission line. The line is compensated by a shunt inductor at its receiving end. A circuit breaker allows energizing and de-energizing of the line. To simplify matters, only one of the three phases is represented. The parameters shown in the figure are typical of a 735-kV power system.

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

## Building the electrical circuit with the SPS library

The graphical user interface uses Simulink functionality to interconnect various electrical components. The electrical components are grouped in the SPS library.

{% stepper %}
{% step %}

### Open the SPS library and create a new model

* At the MATLAB® command prompt, enter: *sps\_lib*
* Open a new blank model to contain your first circuit and save it as circuit1.
  {% endstep %}

{% step %}

### Add an AC Voltage Source

* Add the AC Voltage Source block from the **SPS** > **Sources** library.
* Set the Amplitude, Phase, and Frequency parameters of the AC Voltage Source block according to the values shown in Circuit to Be Modeled.

{% hint style="info" %}
The amplitude to be specified for a sinusoidal source is its peak value (424.4e3 \* sqrt(2) volts in this case).
{% endhint %}

* Change the name of this block from AC Voltage Source to Vs.
  {% endstep %}

{% step %}

### Add and configure the equivalent impedance

* Add the Impedance/Branch block from the **SPS** > **Passives** library, set its parameters as shown in Circuit to Be Modeled, and name it Z\_eq.
* Duplicate the same block in the circuit1 window and select R for the Branch Type and set the R parameter accordingly to obtain Rs\_eq. After closing the dialog, the L and C components disappear so the icon shows a single resistor.
* Name this block Rs\_eq
  {% endstep %}

{% step %}

### Interconnect components

* Resize the various components and interconnect blocks by dragging lines from outputs to inputs of appropriate blocks.

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

{% step %}

### Add transmission line model (PI section line)

* Add a PI section line block from the **SPS** > **Power Grid Elements** library. A model of a line with uniformly distributed R, L, and C parameters is normally represented by a delay equal to wave propagation time; to approximate it with a finite number of states, cascade several PI circuits, each representing a small section of the line (a PI section = series R-L branch and two shunt C branches).
* Copy the line block into the circuit1 window, set its parameters as shown in Circuit to Be Modeled, and specify one line section.
  {% endstep %}

{% step %}

### Model the shunt reactor (110 Mvar)

* The shunt reactor is modeled by a resistor in series with an inductor. You could use the Branch block and compute R and L manually (from Q and quality factor), but it's more convenient to use a block that accepts active and reactive powers directly.
* Add the reactive power block from the **SPS** > **Passives** library and name it `110 Mvar`. Set parameters as follows:

  | Parameter | Value                              |
  | --------- | ---------------------------------- |
  | **Vn**    | 424.4e3 V                          |
  | **fn**    | 60 Hz                              |
  | **P**     | 110e6/300 W (quality factor = 300) |
  | **QL**    | 110e6 VARs                         |
  | **Qc**    | 0                                  |
* Because no reactive capacitive power is specified, the capacitor disappears from the block icon when the dialog box is closed. Interconnect the new blocks as shown.

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

{% step %}

### Add voltage measurement at node B1

* Add the Voltage Measurement block from the **SPS** > **Sensors and Measurements** library. Name it U1
* Connect its positive input to node B1 and its negative input to a new Ground block.
  {% endstep %}

{% step %}

### Display measured voltages using normalized units (per unit)

* Add a Scope block into your circuit1 window.
* Instead of connecting the scope directly to the voltage measurement (which would show volts), electrical engineers often use per-unit normalization. The scaling factor K is:

<p align="center"><span class="math">K = \frac{1} {424.4 × 10^3 × \sqrt2}</span></p>

* Add a Gain block and set its gain to K. Connect the Voltage Measurement output to the Gain block and the Gain output to the Scope.
* Duplicate this voltage measurement system at node B2 as shown.

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

{% step %}

### Add the Powergui block

* Add the Powergui block from the **SPS** library. The purpose and use of this block are discussed in [Using the Powergui Block to Simulate SPS Models](#using-the-powergui-block-to-simulate-sps-models).
  {% endstep %}

{% step %}

### Start simulation and observe

* Start the simulation.
* Open the Scope blocks and observe the voltages at nodes B1 and B2.
* While the simulation is running, open the Vs block dialog and modify amplitude, frequency, or phase. Observe the effect on the scopes. You can zoom in on waveforms by drawing a box around the region of interest with the left mouse button.
  {% endstep %}
  {% endstepper %}

## Interfacing the electrical circuit with other Simulink blocks

The Voltage Measurement block acts as an interface between SPS blocks and Simulink blocks. In the system above, you implemented an interface from the electrical system to the Simulink system: the Voltage Measurement block converts measured voltages into Simulink signals.

Similarly, the Current Measurement block from the **SPS** > **Sensors and Measurements** library converts measured currents into Simulink signals.

You can also interface from Simulink blocks to the electrical system. For example, use the Injected Voltage block to inject a voltage into an electrical circuit.

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

{% hint style="info" %}

### Electrical Terminal Ports and Connection Lines

* Lines that connect normal Simulink ports are directional signal lines.
* Lines that connect electrical terminal ports are special electrical connection lines: nondirectional, can be branched, but cannot connect to Simulink ports or normal Simulink signal lines.
* You can connect Simulink ports only to other Simulink ports, and electrical terminal ports only to other electrical terminal ports.
* Converting between Simulink signals and electrical connections requires using an SPS block that features both Simulink ports and electrical terminal ports.
* Some SPS blocks feature only one type of port.
  {% endhint %}

## Measuring voltages and currents

* When measuring current using a Current Measurement block, the block icon indicates the positive direction (positive current flowing from + terminal to − terminal).
* When measuring voltage using a Voltage Measurement block, the measured voltage is the voltage of the + terminal with respect to the − terminal.

## Basic principles of connecting capacitors and inductors

When connecting capacitor elements with voltage sources or inductors with current sources, be careful: SPS will display an error at simulation start if one of the following connection errors exists.

{% stepper %}
{% step %}

### Capacitor connection issue

* Problem: A voltage source connected in parallel with a capacitor (or a series of capacitors in series) will cause an error.
* Example:

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

To fix this problem, add a small resistance in series between the voltage source and the capacitors.
{% endstep %}

{% step %}

### Inductor connection issue

* Problem: A current source in series with an inductor, or a series of inductors connected in parallel, will cause an error.
* Example:

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

To fix this issue, add a large resistance in parallel with the inductor.
{% endstep %}
{% endstepper %}

## Using the Powergui block to simulate SPS models

The Powergui block is the environment block for SPS models. It:

* stores the equivalent Simulink circuit representing the state-space equations of SPS blocks.
* opens tools for steady-state and simulation results analysis and for advanced parameter design.

When you start the simulation, you will get an error if no Powergui block is found in your model.


---

# 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/get-started/build-and-simulate-a-simple-circuit-using-sps.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.
