> 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/examples/how-to/expression-usage.md).

# Expression Usage

## Description

The **Expression Usage** example, located in **File > Open an Example File > How To**, demonstrates how to assign [**variables and expressions**](https://github.com/Opal-RT-Technologies/product-docs-hypersim/tree/release-2026.4/model-and-simulation/use-variables-and-expressions/README.md) to block parameters.

The objective is to show practical patterns across control elements, preferences, network elements, the Python API, and subcircuits, and to highlight a common mistake when mixing expressions and units.

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

## Requirements

This example model does not require any additional hardware or licenses.

## Detailed explanation

This model offers six different cases

### Case 1 - Control elements

Use expressions to enforce consistent parameterization between blocks. This ensures that dependent outputs remain aligned.

* Gain1.g = GainMultiplier.A

### Case 2 - Preferences

Expressions can reference simulation and loadflow preferences so model parameters follow the configured settings.

* ExpressionTs.A = simulation.calculationStep
* SineFromPrefs.f = loadflow\.frequency
* SineFromPrefs.A = simulation.calculationStep

These links bind the parameters to values set in the [Simulation Settings](https://github.com/Opal-RT-Technologies/product-docs-hypersim/tree/release-2026.4/model-and-simulation/set-simulation-parameters/README.md). As a result, the sine wave output value will not exceed the time step of 50us.

{% hint style="info" %}
Use this pattern primarily at the top level of the model to keep expressions simple and maintainable.
{% endhint %}

### Case 3 - Network elements

Expressions can also be applied to network elements to coordinate voltages and base voltages across the system. Here, the goal is 10KV on the transformer primary and 5KV on the secondary.

* Vsrc1.module = PrimaryVoltage.A ; BusPrimary.baseVolt = PrimaryVoltage.A
* PQLoad1.Voltage = SecondaryVoltage.A ; BusSecondary.baseVolt = SecondaryVoltage.A

{% hint style="info" %}
This approach standardizes voltages across the network and facilitates running the loadflow.
{% endhint %}

### Case 4 - Python API

Using the Python API | Commands, you can set both literal values and expressions. From the Sequence Manager, execute the script **"Expression\_Usage.py"** to configure the square wave. After execution, the expression is visible in the block form. The same syntax is used in the user interface and in the Python API.

### Case 5 - Subcircuits

Expressions are also commonly used with subcircuits.

* Following Transmitting Variables within a Subcircuit, create a mask for the subcircuit to expose symbols usable inside it. For example:
  * DEV1.Gain2.g = GainValue ; where GainValue is defined in the mask of DEV1
* Blocks at the same level as the subcircuit can be referenced from within it. For example:
  * Dev1.Sine1.A = ForSubCircuit.A
  * This is often used to build a control panel for runtime adjustments.
* Linking can also be done from inside the subcircuit to the parent level. For example:
  * Triang1.A = DEV1.Amplitude.A

{% hint style="info" %}
Prefer the first method to keep subcircuits independent and portable across models.
{% endhint %}

### Case 6 - Common mistake

This case illustrates the expression editor warning and the difference between view units and model units when using expressions.

* VsrcNoExp has no expression on its amplitude. In the block form, set the value to 0.707 (1/sqrt(2)) rmsLN. LaTeX: `\frac{1}{\sqrt{2}}`
  * In model units, this corresponds to 0.707 \* sqrt(2) = 1 V peakLN. LaTeX: `0.707 \times \sqrt{2} = 1`
* VsrcWithExp.A = "=0.70710" is set as an expression. Because of the equals sign, HYPERSIM treats the value as an expression and interprets it in model units (peakLN) instead of view units (rmsLN).
  * After Apply, the blue value shows "VsrcWithExp.A = 0.500" rmsLN, which corresponds to 0.707 peakLN.

Because the two voltage amplitudes differ, the current output will also differ.

{% columns %}
{% column %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-46b7f63ceb327e7940f735e9e38ce7d8047289af%2Fimage%20(1245).png?alt=media" alt=""><figcaption><p>Witout expressions</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-94c4afc148c87a08061459c1156449e5f0837ddf%2Fimage%20(1244).png?alt=media" alt=""><figcaption><p>With expressions</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

## Simulation and results

Run the simulation and review the results using the ScopeView template **"Expression\_Usage.svt"**. In Case 6, observe that the different voltage amplitudes produce different current outputs, as expected.

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


---

# 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/examples/how-to/expression-usage.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.
