> 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-i-source-programmable.md).

# AC I 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-3fdfa4475050351015b5b941748336d116152cc2%2FAC-I-prog-block.png?alt=media" alt="" width="163"><figcaption></figcaption></figure>

The **AC I programmable source** or **Programmable Variable Current Source (PVS)** block, located in the **Network Sources** library, provides a current source with a configurable RLC impedance and user-programmable event timing. The RLC elements can be connected in series or parallel, and at least one of R, L, or C must be nonzero. The source injects current between two buses (ungrounded).

Timed variations allow users to program sequences of events affecting the steady-state of the source, as defined by the settings for the amplitude, phase, frequency, and DC component on page General of the control panel.

It is possible to vary the amplitude, phase angle, frequency, and DC component of the source. These variations can be in modulation form (sinusoidal or random), step, ramp, or staircase. It is possible to execute some variations simultaneously. For example, the amplitude and frequency of a source can be made to vary in the same period of time. It is also possible to apply simultaneously a modulation and a ramp.

{% 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-cbf187271246cf63b1926c3e9dcad289ef6174dd%2FACIP.jpg?alt=media" alt=""><figcaption></figcaption></figure>

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

<table><thead><tr><th width="240">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Starting mode (Slow/Fast)</strong></td><td>If Fast, the source activates or deactivates immediately. If Slow, activation ramps the amplitude linearly from zero to the steady-state value; deactivation ramps it from the steady-state value to zero (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>Direct or Inverse (positive or negative):</strong> Maintains 120° phase displacement between phases; changing one phase angle preserves the 120° differential. In negative sequence, the signs for phases b and c are inverted.</li><li><strong>Zero (homopolar):</strong> Phases a, b, and c are in phase (0° differential). Adjusting one phase sets all to the same value.</li><li><strong>Per phase:</strong> Allows setting the same angle for selected phases only; unselected phases are unaffected.</li></ul></td></tr><tr><td><strong>Amplitude (peak)</strong></td><td>Peak amplitude (A) of the current source in amperes.</td></tr><tr><td><strong>DC offset</strong></td><td>Direct current component superimposed on the source signal.</td></tr><tr><td><strong>Angle</strong></td><td>Angle of phase A (degrees). The current source is always balanced and in positive sequence.</td></tr><tr><td><strong>R</strong></td><td>Resistance value (ohms or pu)</td></tr><tr><td><strong>L</strong></td><td>Inductance value (henry or pu)</td></tr><tr><td><strong>C</strong></td><td>Capacitance value (farad or pu)</td></tr><tr><td><strong>Synchronization</strong></td><td>Starts a programmed sequence on the rising edge of a synchronizing signal. Synchronization is tied to Programming status (Start/Stop) and Repetitive mode and must be initiated in ScopeView.<br>Only Internal (POW) is available;</td></tr><tr><td><strong>Programming status</strong></td><td>Allows or prohibits the start of programmed sequences (Start/Stop).Behavior depends on Synchronization and Repetitive mode.</td></tr><tr><td><strong>Repetitive</strong></td><td><ul><li><strong>Disable:</strong> The sequence runs once when started. With Synch OFF, it starts immediately on Start. With Synch ON, it starts on the rising edge of the synch signal (Start must be pressed).</li><li><strong>Enable:</strong> The sequence repeats indefinitely. With Synch OFF, it runs after Start until Stop. With Synch ON, it starts on the rising edge and continues until Stop; subsequent synch signals are ignored until Start is pressed again.</li></ul></td></tr><tr><td><strong>Programming status</strong></td><td>If Enabled, the programmed sequence of events is displayed in the windows where HYPERSIM was launched.</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="Harmonics" %}

<table><thead><tr><th width="220">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Enable</strong></td><td>Global activation of harmonic injection. When Disabled, the source operates without harmonics but the programming is preserved.</td></tr><tr><td><strong>Harmonic Numbers</strong></td><td>List of harmonic indices from 1 (fundamental) to 50; the fundamental (1) is not required. Elements can be integers or compact notation B/E/I to specify sequences.</td></tr><tr><td><strong>Amplitude</strong></td><td>List of amplitudes relative to the fundamental (Ar, 0.0 &#x3C; Ar ≤ 1.0). Elements can be numbers or B/E/I sequences. Must match the length of Harmonic Numbers.</td></tr><tr><td><strong>Operating activation</strong></td><td>List aligned with Timing that specifies activation (1) or deactivation (0). The minimum valid list contains at least one “1”. Harmonic generation that starts at a given time remains active until programming is stopped (Stop on the first page).</td></tr><tr><td><strong>Timing</strong></td><td>List of times (s) for activation/deactivation events. Elements can be numbers or B/E/I sequences. Must contain at least one element to generate harmonics.</td></tr><tr><td><strong>Phase</strong></td><td>List of phases (A, B, C combinations) used only for entries marked P in Sequence. Can be empty if no per-phase entries.</td></tr><tr><td><strong>Sequence</strong></td><td>List specifying the sequence for each harmonic: D (positive), I (negative), H (zero), or P (per phase). Can be empty if all are positive. If not empty, length must match Harmonic Numbers.</td></tr><tr><td><strong>Angle</strong></td><td>List of phase-angle displacements (degrees) relative to the fundamental. Elements can be numbers or B/E/I sequences. Must match the length of Harmonic Numbers.</td></tr></tbody></table>
{% endtab %}

{% tab title="Timed variation" %}

<table><thead><tr><th width="220">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Timed variations status</strong></td><td>Enables or disables execution of programmed variations affecting amplitude, phase, frequency, and DC component. Disabling preserves programmed values.</td></tr><tr><td><strong>Modulation type</strong></td><td><ul><li><strong>None:</strong> No modulation.</li><li><strong>Amplitude:</strong> Sinusoidal amplitude modulation.</li><li><strong>Frequency:</strong> Sinusoidal frequency modulation.</li><li><strong>Phase:</strong> Sinusoidal phase-angle modulation.</li><li><strong>Random:</strong> Random amplitude modulation (periodically adds or subtracts a constant value with 50% probability each).</li></ul><p>Sinusoidal modulation applies to only one parameter at a time. Random modulation applies to amplitude only. Other events (steps, ramps, staircases) can run simultaneously with a modulation.</p></td></tr><tr><td><strong>Sinusoidal modulation — Amplitude</strong></td><td>Amplitude of the modulation sine.</td></tr><tr><td><strong>Sinusoidal modulation — Frequency</strong></td><td>Frequency of the modulation sine.</td></tr><tr><td><strong>Sinusoidal modulation — Phase</strong></td><td>Phase of the modulation sine.</td></tr><tr><td><strong>Sinusoidal modulation — Timing</strong></td><td>Start and end times of the modulation. Steady state applies before and after the modulation period.</td></tr><tr><td><strong>Random modulation — Amplitude</strong></td><td>Value added to or subtracted from the modulated quantity at each update.</td></tr><tr><td><strong>Random modulation — Timing</strong></td><td>Start (B) and end (E) times and period (I) between successive random updates (I must be greater than the simulation time step). Format: B/E/I.</td></tr><tr><td><strong>Ramp/Step types</strong></td><td><ul><li><strong>AC:</strong> Peak amplitude variation.</li><li><strong>DC:</strong> DC component variation.</li><li><strong>Phase:</strong> Phase-angle variation.</li><li><strong>Frequency:</strong> Frequency variation.</li><li><strong>Sequence:</strong> Sequence change.</li></ul><p>Steady state precedes and follows each variation unless an infinite variation (no end time) is programmed.</p></td></tr><tr><td><strong>Amplitude list</strong></td><td><p>Defines variation type and values per event:</p><ul><li><strong>B</strong>: Step to initial value B.</li><li><strong>B/E</strong>: Ramp from B to E.</li><li><strong>B/E/I</strong>: Staircase from B to E with increment I.</li></ul><p>Each list element must align with the corresponding element in Timing and Phase lists.</p></td></tr><tr><td><strong>Timing list</strong></td><td><p>Start/end times per event in seconds:</p><ul><li><strong>B/E</strong>: Start at B, end at E.</li><li><strong>B</strong>: Start at B (for a step that holds indefinitely).</li></ul><p>Each element must align with Amplitude and Phase lists.</p></td></tr><tr><td><strong>Phase list</strong></td><td>Phases to which each event applies, using A, B, C (e.g., A, BC, ABC). Each element must align with Amplitude and Timing lists.</td></tr><tr><td><strong>Frequency variation</strong></td><td>Specified like Amplitude list (B, B/E, B/E/I). Applies to all phases.</td></tr><tr><td><strong>Sequence variation</strong></td><td><p>Sequence per event:</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 (use Phase list to select A/B/C).</li></ul></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 page, 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 page, 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 page, 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 page, 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 page, 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>

## Conserving ports

| Port               | Description                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| **Net\_1, Net\_2** | The current source injects a current from one bus (port) to another (port), without grounding. |

## Inputs

| Input       | Description                          |
| ----------- | ------------------------------------ |
| **I input** | The current source amplitude signal. |

## 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.

| Signal | Description                |
| ------ | -------------------------- |
| **I**  | Current source signal (A). |


---

# 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-i-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.
