> 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-sources/ac-v-source-programmable.md).

# AC V Source, Programmable

## Description

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

The **AC Voltage programmable source** or **Programmable variable voltage source (PVS)** block, located in the **Network Sources** library, lets you program custom activation times and durations for a voltage source with an RLC impedance. The RLC elements can be connected in series or in parallel, and at least one of R, L, or C must be non-zero.

{% hint style="info" %}
By default, the voltage/current source block operates in single-phase mode. When it is connected to a three-phase bus signal, it automatically switches to three-phase operation.
{% endhint %}

## Mask parameters

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

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

<table><thead><tr><th width="240">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Source status</strong></td><td>Enables or disables the source.</td></tr><tr><td><strong>Starting mode</strong></td><td>If Fast, the source activates/deactivates immediately.<br>If Slow, the source amplitude ramps linearly from zero to its steady-state value on activation, and from steady state to zero on deactivation (see captures below).</td></tr><tr><td><strong>RLC type</strong></td><td>Series (series R, L, C) or parallel (parallel R, L, C).</td></tr><tr><td><strong>Frequency</strong></td><td>Source frequency (Hz).</td></tr><tr><td><strong>Phase sequence</strong></td><td><ul><li><strong>1 Direct or Inverse (positive or negative):</strong> Maintains a constant 120-degree phase shift between phases as the angle is changed (numerically or via the dial). In negative sequence, signs for phases b and c are inverted.</li><li><strong>2 Zero (homopolar):</strong> Phases a, b, and c are in phase (zero differential). Changing one field or dial sets all phases to the same value.</li><li><strong>3 Per phase:</strong> Assigns the same angle to selected phases (checked). Non-selected phases are unaffected. Editing one selected phase updates the others to the same value.</li></ul></td></tr><tr><td><strong>Amplitude (msLL)</strong></td><td>Peak amplitude of the source voltage in volts (or pu).</td></tr><tr><td><strong>DC offset</strong></td><td>Direct current superimposed on the source signal.</td></tr><tr><td><strong>Angle</strong></td><td>Angle of each phase in degrees. Values can be entered numerically or via the dial. Angle input behavior depends on the selected sequence.</td></tr><tr><td><strong>R</strong></td><td>Resistance for phases a, b, c in ohms (or pu).</td></tr><tr><td><strong>L</strong></td><td>Inductance for phases a, b, c in henry (or pu).</td></tr><tr><td><strong>C</strong></td><td>Capacitance for phases a, b, c in farad (or pu).</td></tr><tr><td><strong>Synchronization</strong></td><td>Starts the programmed sequence with the rising edge of a synchronizing signal. Synchronization interacts with Programming status (Start/Stop) and Repetitive mode. Operations must be initiated in ScopeView for synchronization to take effect. At the time of writing, only internal synchronization (POW) is supported; external synchronization is planned.</td></tr><tr><td><strong>Programming status</strong></td><td>Allows or prevents starting programmed event sequences. The effect depends on synchronization and Repetitive mode.</td></tr><tr><td><strong>Repetitive mode</strong></td><td>If enabled, repeats the programmed event sequence indefinitely; if disabled, executes the sequence once (requires Start).</td></tr><tr><td><strong>Base power (total)</strong></td><td>Base power per phase in MVA.</td></tr><tr><td><strong>Base voltage (msll)</strong></td><td>Base phase-to-ground voltage (kV)</td></tr><tr><td><strong>Base frequency</strong></td><td>Base frequency (hz)</td></tr></tbody></table>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-05403a39c2b5fa929006d35cf71e02af8af7865d%2Ffast_slow_mode.jpg?alt=media" alt=""><figcaption><p>a) fast mode - b)slow mode</p></figcaption></figure>
{% endtab %}

{% tab title="Harmonic" %}

<table><thead><tr><th width="219.9364013671875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Harmonic Numbers</strong></td><td>List of harmonic orders from 1 (fundamental) to 50. The fundamental (1) need not be specified. Elements can be integers or compact notation B/E/I for ranges.</td></tr><tr><td><strong>Amplitude</strong></td><td>List of amplitudes relative to the fundamental (Ar, with 0.0 &#x3C; Ar ≤ 1.0). Elements can be numbers or compact notation B/E/I for equidistant values. Must match the Harmonic Numbers list length.</td></tr><tr><td><strong>Angle</strong></td><td>List of phase angles in degrees relative to the fundamental. Elements can be numbers or compact notation B/E/I. Must match the Harmonic Numbers list length.</td></tr><tr><td><strong>Sequence</strong></td><td><p>List of sequence specifications per harmonic. Can be empty to use positive sequence for all. Otherwise must match Harmonic Numbers list length. Each element is:</p><ul><li><strong>D</strong>: positive sequence (0, -120, +120 degrees)</li><li><strong>I</strong>: negative sequence (0, +120, -120 degrees)</li><li><strong>H</strong>: zero sequence (0, 0, 0 degrees)</li><li><strong>P</strong>: per phase</li></ul></td></tr><tr><td><strong>Phase</strong></td><td>List of phases for per-phase (P) items in Sequence. Each element is a concatenation of A, B, C (e.g., A, ABC). The case ABC can be programmed by using positive sequence (D).</td></tr><tr><td><strong>Timing</strong></td><td>List of enable/disable times. Elements can be numeric values or B/E/I for equidistant series. Must contain at least one element to generate harmonics.</td></tr><tr><td><strong>Operating activation</strong></td><td>List aligned with Timing that specifies activation (1) or deactivation (0). Must contain at least one 1 to generate harmonics. Harmonic generation continues until programming is stopped (Stop on the first page).</td></tr><tr><td><strong>Harmonics activation (Enable/Disable)</strong></td><td>Global activation of harmonic injection. When disabled, the source operates without harmonics; programming is preserved.</td></tr></tbody></table>
{% endtab %}

{% tab title="Timing" %}

<table><thead><tr><th width="219.539306640625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Timed variations (Enable/Disable)</strong></td><td>Activates/deactivates timed variations that modify the steady-state settings (amplitude, phase, frequency, DC component). When disabled, programming values are retained.</td></tr><tr><td><strong>Modulation types</strong></td><td><ul><li><strong>None:</strong> No modulation.</li><li><strong>Amplitude:</strong> Sinusoidal modulation of amplitude.</li><li><strong>Frequency:</strong> Sinusoidal modulation of frequency.</li><li><strong>Phase:</strong> Sinusoidal modulation of phase angle.</li><li><strong>Random:</strong> Random modulation of amplitude (only). Periodically adds or subtracts a constant with 50% probability.</li></ul></td></tr><tr><td><strong>Amplitude (modulation)</strong></td><td>Amplitude of the modulation sine.</td></tr><tr><td><strong>Frequency (modulation)</strong></td><td>Frequency of the modulation sine.</td></tr><tr><td><strong>Phase (modulation)</strong></td><td>Phase of the modulation sine.</td></tr><tr><td><strong>Timing (modulation)</strong></td><td>Start and end times for the modulation. Steady state applies before and after.</td></tr><tr><td><strong>Random modulation amplitude</strong></td><td>Value added to or subtracted from the modulated quantity.</td></tr><tr><td><strong>Random modulation frequency and phase</strong></td><td>Not used.</td></tr><tr><td><strong>Random modulation timing</strong></td><td>Start (B) and end (E) times and period (t) = multiple of time step between successive random updates. The period must be greater than the simulation time step.</td></tr><tr><td><strong>Types (AC, DC, Phase, Frequency, Sequence)</strong></td><td>Selects which parameter(s) to apply step, ramp, or staircase variations to. Variations can coincide with a modulation. Steady-state operation precedes and follows each variation unless an infinite (no end time) variation is programmed.</td></tr><tr><td><strong>Amplitude list</strong></td><td><p>Defines variation shape and values per event using:</p><ul><li><strong>B</strong>: step (initial value only)</li><li><strong>B/E</strong>: ramp (initial and final values)</li><li><strong>B/E/I</strong>: staircase (initial, final, increment)</li></ul><p>Each list element corresponds to one event and must align with Timing and Phase lists.</p></td></tr><tr><td><strong>Timing list</strong></td><td>Start (B) and end (E) times per event (seconds). Both are required for ramps and staircases. For an indefinite step, specify only the start time. Must align with Amplitude and Phase lists.</td></tr><tr><td><strong>Phase list</strong></td><td>Phases to apply each event to, using A, B, C (e.g., A; ABC). Must align with Amplitude and Operation Timing lists.</td></tr><tr><td><strong>Frequency list</strong></td><td>Specified like Amplitude. Frequency variation always applies to all phases.</td></tr><tr><td><strong>Sequence list</strong></td><td>List of sequence types to apply.</td></tr></tbody></table>
{% endtab %}

{% tab title="Load flow" %}

<table><thead><tr><th width="219.9364013671875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Type</strong></td><td><ul><li><strong>PQ:</strong> P and Q specified; V and θ calculated.</li><li><strong>PV:</strong> P and V specified; Q and θ calculated.</li><li><strong>Swing:</strong> V and θ specified; P and Q calculated.</li></ul></td></tr><tr><td><strong>Voltage</strong></td><td>Pu voltage; specified for PV-bus and Slack-bus, calculated for PQ-bus.</td></tr><tr><td><strong>Angle</strong></td><td>Voltage phase angle; specified for Slack-bus, calculated for PQ-bus and PV-bus.</td></tr><tr><td><strong>Q minimum limit</strong></td><td>Minimum reactive power generation limit for PV-bus (Mvar).</td></tr><tr><td><strong>Q maximum limit</strong></td><td>Maximum reactive power generation limit for PV-bus (Mvar).</td></tr><tr><td><strong>P</strong></td><td>Specified generation for PV-bus and Slack-bus; specified load for PQ-bus (MW).</td></tr><tr><td><strong>Q</strong></td><td>Specified load for PQ-bus; calculated within limits for PV-bus; calculated for Slack-bus (Mvar).</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Examples

<details>

<summary>1- <strong>Amplitude modulation</strong></summary>

In the General Controls tab enter the parameters as follows:

* **Module**: 1 V peak
* **Angle**: 0 deg.
* **DC offset**: 0V
* **Frequency**: 10Hz
* **Phase sequence**: Direct
* **Source status**: Enable
* **Starting mode**: Slow
* **Programming**: Start
* **Repetitive**: Disable\
  This mode, when enabled, leaves the program variation running forever after the first Synchronization signal received (from Scopeview). To stop it, you have to toggle the parameters Programming from Start to Stop.
* **Programming:** Enable\
  This parameter displays the timed programming in a table format in the HYPERSIM® window.

In the Time variations tab, enter parameters as follows:

* Select the **Amplitude** modulation type button
* **Timed variations**: Enable
* **Amplitude**: 0.5 Volts (Amplitude of the modulation)
* **Frequency**: 2 Hz (Frequency of the modulation)
* **Phase angle**: 0.0 deg.
* **Timing**: 0/2 s

Use a Time length of 2.5 seconds and a sampling rate associated with the time step of the simulation. You will see a frequency modulation of ±10 Hz over a 10 Hz signal (meaning a variation from 0 to 20 Hz), at a rate of 1 Hz, during a two-second time span.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b7a93fdd19aef98c60de36146b46adfe08dc6ebb%2Fimage%20(1153).png?alt=media" alt=""><figcaption><p>ScopeView - Vabc and Iabc at the source</p></figcaption></figure>

</details>

<details>

<summary>2- <strong>Frequency modulation</strong></summary>

In the General Controls tab, enter the parameters as follows:

* **Module**: 1 V peak
* **Angle**: 0 deg.
* **DC offset**: 0V
* **Frequency**: 10Hz
* **Phase sequence**: Direct
* **Source status**: Enable
* **Starting mode**: Slow
* **Programming**: Start
* **Repetitive**: Disable\
  This mode, when enabled, leaves the program variation running forever after the first Synchronization signal received (from Scopeview). To stop it, you have to toggle the parameters Programming from Start to Stop.
* **Programming:** Enable\
  This parameter displays the timed programming in a table format in the HYPERSIM window.

In the Time variations tab, enter parameters as follows:

* **Timed variations**: Enable
* Select the **Frequency** modulation type button
* **Amplitude**: 10 Volts (Amplitude of the modulation + and –)
* **Frequency**: 1 Hz (Rate of the modulation)
* **Phase angle**: 0.0 deg.
* **Timing**: 0/2 s

Use a Time length of 2.5 seconds and a sampling rate associated with the time step of the simulation. You will see a frequency modulation of ±10 Hz over a 10 Hz signal (meaning a variation from 0 to 20 Hz), at a rate of 1 Hz, during a two-second time span.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-a30060f3f019dab3ca7dafc2a6b6793165d126ec%2Fimage%20(1154).png?alt=media" alt=""><figcaption><p>ScopeView - Vabc and Iabc at the source</p></figcaption></figure>

</details>

<details>

<summary>3- <strong>Harmonic voltage source programming</strong></summary>

In the General Control tab, enter the parameters as follows:

* **Module**: 1 Vpeak
* **Angle**: 0
* **DC offset:** 0 V
* **Frequency**: 10 Hz
* **Phase sequence:** Direct
* **Source mode:** Enable
* **Starting mode**: Slow
* **Programming**: Start
* **Repetitive**: Disable\
  This mode when enabled, leaves the program variation running forever after the first Synchronization trig received (from Scopeview). To stop it, you have to toggle the parameters Programming from start to stop
* **Programming:** Enable\
  These parameters print the timed programming in a table format in the HYPERSIM® window.

In the Harmonics tab, enter the following parameters:

* **Harmonic number**: 10
* **Amplitude**: 0.25pu
* **Activation**: 1, 0, 1, 0
* **Timing**: 0.1, 1, 1.1, 2 s
* **Phase**: ABC
* **Angle**: 0
* **Sequence**: D

Use a Time length of 2.5 seconds and a sampling rate associated with the time step of the simulation. You will get a generation of 0.25 pu of the 10th harmonic in direct sequence over impose with the main signal of 10 Hz, and so between 0.1 and 1 second and also between 1.1 and 2 seconds.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-03bd9eed3245f610666677781009e2f72333235e%2Fimage%20(388).png?alt=media" alt=""><figcaption><p>ScopeView - Vabc and Iabc at the source</p></figcaption></figure>

</details>

<details>

<summary>4- <strong>Ramp and Step generation</strong></summary>

**First Example**

The steady-state peak voltage of the source is 100 kV. The objective is to increase this voltage progressively to 125 kV over a period of 0.3 s, following a delay of 0.1 s. The delay is measured from a reference time that depends on the source synchronization mode (see Section F, *Source Control*). This variation is applied simultaneously to all phases.

In the Time variations tab, enter parameters as follows:

* enable the **AC Ramp/Step** option
* **Amplitude:** 100 000 / 125 000 V
* **Timing:** 0.1 / 0.3 s
* **Phase:** ABC

**Second Example**

Suppose the user wants to modify the base voltage source using the following sequence of events:

1. **First ramp**
   * Start time: 0.1 s
   * End time: 0.3 s
   * Initial amplitude: 0 V
   * Final amplitude: 600 000 V
2. **Second ramp**
   * Start time: 0.35 s
   * End time: 0.45 s
   * Initial amplitude: 1 000 000 V

**DC component step**

* Start time: 0.2 s
* End time: 0.3 s
* Amplitude: 200 000 V

Assuming all phases are active, in the Time variations tab, enter parameters as follows:

* enable the **AC Ramp/Step** option
* Amplitude: 0.0/600000, 1000000/100V
* Timing: 0.1/0.3,0.35/0.45s
* Phase: ABC
* enable the D**C Ramp/Step** option
* Amplitude: 200000
* Operation timing: 0.2/0.3
* Phase: ABC

The AC amplitude values are entered on separate vertical lines to distinguish between events occurring at different times. Multiple events affecting the same parameter cannot occur simultaneously. However, events acting on different source parameters—such as the AC waveform amplitude and the DC component amplitude—may occur at the same time without restriction.

**Third example**

Enable **AC and DC ramp/step** and fill in the fields with the corresponding parameters:

**AC**

* Amplitude: 1/10V
* Timing: 0.5/2s
* Phase: ABC

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-ebc2fe148bbe581255744b0cac87f807206d3a20%2Fimage%20(1157).png?alt=media" alt=""><figcaption><p>Scopeview - VINT(a,b,c) and I(a,b,c)</p></figcaption></figure>

</details>

## Conserving ports

<table><thead><tr><th width="199.6922607421875">Port</th><th>Description</th></tr></thead><tbody><tr><td><strong>Net_1</strong></td><td>The voltage source has only one network connector (port), since is always referenced to the ground.</td></tr></tbody></table>

## Inputs

This block has no inputs.

## Outputs

This block has no outputs.

## Signals available for monitoring and external I/O connections (via sensors form)

All block inputs and outputs are available as signals for monitoring and for external I/O connections.

Additional signals are also available and are listed below with their descriptions.

<table><thead><tr><th width="200.20794677734375">Signal</th><th>Description</th></tr></thead><tbody><tr><td><strong>VlNT</strong></td><td>Source voltage (V)</td></tr><tr><td><strong>I</strong></td><td>Measured current (A)</td></tr></tbody></table>


---

# 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-sources/ac-v-source-programmable.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.
