> 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/basics/sources/three-phase-programmable-voltage-source.md).

# Three Phase Programmable Voltage Source

## Description

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

The **Three Phase Programmable Voltage Source** block, located in the **OPAL-RT SPS Software/Sources** library, models a three-phase sinusoidal voltage with time-varying parameters. You can program the time variation for the amplitude, phase, or frequency of the fundamental component of the source. In addition, two harmonics can be programmed and superimposed on the fundamental signal.

## Ports

#### Conserving

|                                                                |                                                                      |
| -------------------------------------------------------------- | -------------------------------------------------------------------- |
| <p><strong>N</strong> — Neutral terminal<br>SPS electrical</p> | SPS electrical conserving port associated with the neutral terminal. |
| <p><strong>A</strong> — Phase A terminal<br>SPS electrical</p> | SPS electrical conserving port associated with the phase A terminal. |
| <p><strong>B</strong> — Phase B terminal<br>SPS electrical</p> | SPS electrical conserving port associated with the phase B terminal. |
| <p><strong>C</strong> — Phase C terminal<br>SPS electrical</p> | SPS electrical conserving port associated with the phase C terminal. |

## Parameters

To edit block parameters interactively, use the Property Inspector. From the Simulink<sup>®</sup> Toolstrip, on the **Simulation** tab, in the **Prepare** gallery, select **Property Inspector**.

#### Parameters

<table data-header-hidden><thead><tr><th width="226.79998779296875"></th><th></th></tr></thead><tbody><tr><td><strong>Positive-sequence</strong> — Parameters of positive-sequence component<br><code>[100 0 60]</code> (default) | vector of scalars</td><td>The amplitude in volts RMS phase-to-phase, the phase in degrees, and the frequency in hertz of the positive-sequence component of the three voltages. Default is <code>[100 0 60]</code>. Phase B and phase C internal voltages lag phase A by 120 degrees and 240 degrees, respectively ([0 -120 +120]).</td></tr><tr><td><strong>Time variation of</strong> — Parameter for which you want to program time variation<br><code>None</code> (default) | <code>Amplitude</code> | <code>Phase</code> | <code>Frequency</code></td><td>Specify the parameter for which you want to program the time variation. Select <code>None</code> (default) if you do not want to program the time variation of the source parameters. Select <code>Amplitude</code> if you want to program the time variation of the amplitude. Select <code>Phase</code> if you want to program the time variation of the phase. Select <code>Frequency</code> if you want to program the time variation of the frequency. The time variation applies to the three phases of the source except when the <strong>Type of variation</strong> parameter is set to <code>Table of amplitude-pairs</code>. In that case you can apply a variation to phase A only.</td></tr><tr><td><strong>Type of variation</strong> — Type of variation<br><code>Table of amplitude-pairs</code> (default) | <code>Step</code> | <code>Ramp</code> | <code>Modulation</code></td><td>Specify the type of variation that is applied to the parameter specified by the <strong>Time variation of</strong> parameter. Select <code>Step</code> to program a step variation. Select <code>Ramp</code> to program a ramp variation. Select <code>Modulation</code> to program a modulated variation. Select <code>Table of amplitude-pairs</code> to program a series of step changes of amplitudes at specific times. The <code>Table of amplitude-pairs</code> option is available only when the <strong>Time variation of</strong> parameter is set to <code>Amplitude</code>.<code>Table of amplitude-pairs</code> is the default when <strong>Time variation of</strong> is set to <code>Amplitude</code>. <code>Step</code> is the default when <strong>Time variation of</strong> is set to <code>Phase</code> or <code>Frequency</code>.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Time variation of</strong> to <code>Amplitude</code>, <code>Phase</code>, or <code>Frequency</code>.</td></tr><tr><td><strong>Variation on phase A only</strong> — Variation on phase A only<br><code>off</code> (default) | <code>on</code></td><td>If selected, the programmed time variation of the amplitude is applied only to phase A of the Three-Phase Programmable Voltage Source block.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Time variation of</strong> to <code>Amplitude</code> and <strong>Type of variation</strong> to <code>Table of amplitude-pairs</code>.</td></tr><tr><td><strong>Amplitude values (pu)</strong> — Amplitude variation points<br><code>[1 0.8 1.2 1.0]</code> (default) | vector of positive values</td><td>Specifies the amplitude variation points taken by the voltage source during the simulation. The specified values are in pu, based on the positive-sequence amplitude of the voltage source. The corresponding times where the variation will take place are defined by the <strong>Time values</strong> parameter.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Time variation of</strong> to <code>Amplitude</code> and <strong>Type of variation</strong> to <code>Table of amplitude-pairs</code>.</td></tr><tr><td><strong>Time values</strong> — Transition times<br><code>[0 0.1 0.15 0.2]</code> (default) | vector of positive values</td><td>Specifies the transition times, in seconds, of the amplitude variation defined in the <strong>Amplitude values (pu)</strong> parameter.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Time variation of</strong> to <code>Amplitude</code> and <strong>Type of variation</strong> to <code>Table of amplitude-pairs</code>.</td></tr><tr><td><strong>Step magnitude</strong> — Amplitude of step change<br><code>0.5</code> (default) | nonnegative scalar</td><td>Specify the amplitude of the step change. The variation of amplitude is specified in pu of the positive-sequence amplitude.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Type of variation</strong> to <code>Step</code>.</td></tr><tr><td><strong>Rate of change</strong> — Rate of change<br><code>10</code> (default) | positive scalar</td><td>Specify the rate of change, in volt/seconds. The rate of change of voltage is specified in (pu of the positive-sequence voltage)/second.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Type of variation</strong> to <code>Ramp</code>.</td></tr><tr><td><strong>Amplitude of the modulation</strong> — Amplitude of modulation<br><code>0.3</code> (default) | positive scalar</td><td>Specify the amplitude of the modulation for the source parameter that is specified in the <strong>Time variation of</strong> parameter. When the varying quantity is the voltage amplitude, the amplitude of the modulation is specified in pu of the positive-sequence amplitude.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Type of variation</strong> to <code>Modulation</code>.</td></tr><tr><td><strong>Frequency of the modulation</strong> — Frequency of modulation<br><code>2</code> (default) | positive scalar</td><td>Specify the frequency of the modulation for the source parameter that is specified in the <strong>Time variation of</strong> parameter.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Type of variation</strong> to <code>Modulation</code>.</td></tr><tr><td><strong>Variation timing (s)</strong> — Variation timing<br><code>[1 2]</code> (default) | vector of positive values</td><td>Specify the time, in seconds, when the programmed time variation takes effect and the time when it stops.</td></tr><tr><td><strong>Fundamental and/or Harmonic generation</strong> — Fundamental and/or harmonic generation<br><code>off</code> (default) | <code>on</code></td><td>If selected, two harmonics can be programmed to be superimposed on the fundamental voltage of the source.</td></tr><tr><td><strong>A: [Order Amplitude Phase Seq]</strong> — Order, amplitude, phase, and type of sequence of first harmonic<br><code>[3 0.2 -25 0]</code> (default) | vector of nonnegative values</td><td>Specify the order, amplitude, phase, and the type of sequence (1 = positive-sequence; 2 = negative-sequence; 0 = zero-sequence) of the first harmonic to be superimposed on the fundamental signal. The voltage of the harmonic is specified in pu of the positive-sequence voltage. Specify <code>1</code> for the harmonic order and <code>0</code> or <code>2</code> for the sequence to produce a voltage imbalance without harmonics.<br><strong>Dependencies</strong> To enable this parameter, select the <strong>Fundamental and/or Harmonic generation</strong> parameter.</td></tr><tr><td><strong>B: [Order Amplitude Phase Seq]</strong> — Order, amplitude, phase, and type of sequence of second harmonic<br><code>[2 0.15 35 2]</code> (default) | vector of nonnegative values</td><td>Specify the order, amplitude, phase, and the type of sequence (1 = positive-sequence; 2 = negative-sequence; 0 = zero-sequence) of the second harmonic to be superimposed on the fundamental signal. The voltage of the harmonic is specified in pu of the positive-sequence voltage. Specify <code>1</code> for the harmonic order and <code>0</code> or <code>2</code> for the sequence to produce a voltage imbalance without harmonics.<br><strong>Dependencies</strong> To enable this parameter, select the <strong>Fundamental and/or Harmonic generation</strong> parameter.</td></tr><tr><td><strong>Timing (s)</strong> — Time when harmonic generation is superimposed<br><code>[0.05 3]</code> (default) | vector of positive values</td><td>Specify the time, in seconds, when the harmonic generation is superimposed on the fundamental signal and the time when it stops.<br><strong>Dependencies</strong> To enable this parameter, select the <strong>Fundamental and/or Harmonic generation</strong> parameter.</td></tr></tbody></table>

## Load Flow

The load flow parameters are used to define block parameters for use with the Load Flow tool of the powergui block. These load flow parameters are used for model initialization only. They have no impact on the block model and on the simulation’s performance.

The configuration of the **Load Flow** tab depends on the option selected for the **Generator type** parameter.

<table data-header-hidden><thead><tr><th width="194.7999267578125"></th><th></th></tr></thead><tbody><tr><td><strong>Generator type</strong> — Generator type of voltage source<br><code>swing</code> (default) | <a data-footnote-ref href="#user-content-fn-1"><code>PV</code> </a>| <a data-footnote-ref href="#user-content-fn-2"><code>PQ</code></a></td><td>Specify the generator type of the voltage source. Select <code>swing</code> (default) to implement a generator controlling magnitude and phase angle of its terminal voltage. The reference voltage magnitude and angle are specified by the <strong>Swing bus or PV bus voltage</strong> and <strong>Swing bus voltage angle</strong> parameters of the Load Flow Bus block connected to the voltage source terminals. Select <code>PV</code> to implement a generator controlling its output active power P and voltage magnitude V. P is specified by the <strong>Active power generation P</strong> parameter of the block. V is specified by the <strong>Swing bus or PV bus voltage</strong> parameter of the Load Flow Bus block connected to the voltage source terminals. You can control the minimum and maximum reactive power generated by the block by using the <strong>Minimum reactive power Qmin</strong> and <strong>Maximum reactive power Qmax</strong> parameters. Select <code>PQ</code> to implement a generator controlling its output active power P and reactive power Q. P and Q are specified by the <strong>Active power generation P</strong> and <strong>Reactive power generation Q</strong> parameters of the block, respectively.</td></tr><tr><td><strong>Active power generation P</strong> — Active power generated by source<br><code>0</code> (default) | nonnegative scalar</td><td>Specify the active power that you want generated by the source, in watts.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Generator type</strong> to <code>PV</code> or <code>PQ</code>.</td></tr><tr><td><strong>Reactive power generation Q</strong> — Reactive power generated by source<br><code>0</code> (default) | nonnegative scalar</td><td>Specify the reactive power that you want generated by the source, in vars.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Generator type</strong> to <code>PQ</code>.</td></tr><tr><td><strong>Minimum reactive power Qmin</strong> — Minimum reactive power generated by the source<br><code>-inf</code> (default) | scalar</td><td>Minimum reactive power that can be generated by the source while keeping the terminal voltage at its reference value. This reference voltage is specified in the <strong>Swing bus or PV bus voltage</strong> parameter of the Load Flow Bus block connected to the source terminals. The default value is <code>-inf</code>, which means that there is no lower limit on the reactive power output.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Generator type</strong> to <code>PV</code>.</td></tr><tr><td><strong>Maximum reactive power Qmax</strong> — Maximum reactive power generated by the source<br><code>inf</code> (default) | scalar</td><td>Maximum reactive power that can be generated by the source while keeping the terminal voltage at its reference value. This reference voltage is specified in the <strong>Swing bus or PV bus voltage</strong> parameter of the Load Flow Bus block connected to the source terminals. The default value is <code>inf</code>, which means that there is no upper limit on the reactive power output.<br><strong>Dependencies</strong> To enable this parameter, set <strong>Generator type</strong> to <code>PV</code>.</td></tr></tbody></table>

## Example

The [Three-Phase Programmable Source, V-I Measurement and Sequence Analyzer](https://opal-rt.atlassian.net/wiki/spaces/PSPS/pages/1551735253/Three-Phase+Programmable+Source+V-I+Measurement+and+Sequence+Analyzer) circuit illustrates the use of the Three-Phase Programmable Voltage Source block to produce a step variation of the positive-sequence voltage and to inject harmonics into the circuit.

A 25 kV, 100 [MVA ](#user-content-fn-3)[^3]short-circuit level, equivalent network feeds a 5 MW[^4], 2 Mvar capacitive load. The internal voltage of the source is controlled by the Discrete 3-phase Programmable Voltage Source block.

A positive sequence of 1.0 pu, 0 degrees is specified for the fundamental signal. At t = 0.05 s a step of 0.5 pu is applied to the positive-sequence voltage magnitude, then at t = 0.1 s, 0.08 pu of fifth harmonic in negative sequence is added to the 1.5 pu voltage.

The three-phase voltage and current are measured at the output of the source impedance. Two Discrete Sequence Analyzer blocks are used to measure the positive-sequence fundamental component and the negative-sequence fifth harmonic of the three-phase voltage.

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

[^1]: **PV** stands for **Photovoltaic**, which refers to technology that converts sunlight directly into electricity using solar cells. A **PV array** consists of multiple solar panels connected together, allowing for increased energy production. The performance of PV systems is influenced by factors such as solar irradiance and temperature, which affect the current and voltage output of the solar cells.

[^2]: **PQ** refers to a type of generator or load in power systems that specifies both active power (P) and reactive power (Q). In this context, the generator controls its output of active power and reactive power, allowing for flexibility in managing power flow within the system. This configuration is essential for balancing the electrical network and ensuring stable operation.

[^3]: **MVA** stands for **Mega Volt-Amperes**, a unit of measurement used to express the apparent power in an electrical system. It represents the product of voltage (in volts) and current (in amperes) divided by one million. MVA is commonly used in power systems to describe the capacity of transformers and generators, indicating how much power they can handle without overheating.

[^4]: **MW**, or megawatt, is a unit of power equal to one million watts. It is commonly used to measure the output of power plants or the power consumption of large electrical devices. In the context of electrical systems, 1 MW can power approximately 1,000 average homes in the United States. This measurement is crucial for understanding energy production and consumption in various applications, including renewable energy sources like solar and wind.


---

# 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/basics/sources/three-phase-programmable-voltage-source.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.
