> 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/model-and-simulation/optimize-the-model/use-variables-and-expressions.md).

# Use Variables & Expressions

## **Overview**

**HYPERSIM**, **ScopeView**, and **TestView** allow users to define values using **variables** and **mathematical expressions**, which may optionally reference parameters or variables from other components. Expressions can include standard mathematical functions and constants, such as `sqrt`, `ln`, `pi`, and `e`, as well as component attributes.

The **Examples** [**Expression Usage**](https://www.opal-rt.com/docs/hypersim/examples/how-to/expression-usage.md) model demonstrates how expressions can be used throughout HYPERSIM to define and calculate parameter values dynamically.

{% hint style="danger" %}
Before evaluating expressions, click **Analyze** on the **HYPERSIM** ribbon to build the network topology. This allows HYPERSIM to resolve references and dependencies between components correctly.
{% endhint %}

## Use expressions for parameter values

To use an expression for a parameter value, open the block's parameter dialog box and locate a parameter that supports expressions. Click in the parameter field to open the **Expression Editor**, where you can create and evaluate the desired expression.

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

The **Analyze Expression** button evaluates the expression and verifies its validity. If an error is detected, the **OK** button is disabled, the message **"Invalid Expression"** is displayed, and a pop-up window provides details about the error.

The **OK** button automatically evaluates the expression if it has not already been analyzed. If no errors are found, the expression is applied to the parameter field from which the **Expression Editor** was opened. While editing an expression, press **Enter** as a shortcut for **OK**.

The **Cancel** button closes the **Expression Editor** without applying any changes. While editing an expression, press **Esc** as a shortcut for **Cancel**.

Expressions can also be used with **combo box** and **radio button** controls. To open the **Expression Editor**, right-click the **?** icon next to the control.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-939f0698ff886c3bc852e2fe914189b0006f600d%2Fcombo-box-expression-editor.png?alt=media" alt=""><figcaption></figcaption></figure>

### Attribute name for a parameter

To identify the attribute name associated with a parameter, hover the mouse pointer over the parameter name for a few seconds. The attribute name is displayed in square brackets. In the example below, the attribute name is **ConnexPrim**.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c6ca4d6d99f2dbeab43679cb3a3bc8446a315367%2Fattribute-name-parameter.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

You can also identify attribute names using the **Netlist** tool available on the **HYPERSIM** ribbon.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-d61ed1fd92ff2fef8afc8f33e4ef7db7bd75a87d%2Fattribute-name-parameter-netlist.png?alt=media" alt=""><figcaption></figcaption></figure>

### Supported expression syntax

#### **Mathematical constants and functions**

* pi
* e (2.718...)
* sqrt(37)
* log(2) *(Note: log represents the natural logarithm, ln.)*
* 3e3 *(equivalent to 3000)*

#### Parameter by name

* In the circuit : \[ComponentName].\[AttributeName], for example =DelayOn3.Td
* In a subcircuit : \[SubCircuitN].\[ComponentName].\[AttributeName]. For example, if we wrap RL101 in a subcircuit FR3: =FR3.RL101.pBase

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

To assign an expression on a **parameter of a subircuit**, in the subcircuit form, it is required to add an **"=" symbol** as the first character. If the symbol is missing, then the parameter will be considered of *String* type instead of *Double*. To prevent this issue, the **Expression Editor** automatically restores the leading `=` if it has been removed.

### **Analyze the expression** <a href="#analyze-the-expression" id="analyze-the-expression"></a>

If the expression contains only a numeric value (for example, 37, -54.7, or 3.1415), it is stored as a number rather than as an expression.

If the expression contains only mathematical operations and no references to circuit parameters, the message **"Nothing to analyze"** is displayed. The expression is still accepted when **OK** is clicked.

When an expression references component attributes, the **Expression Editor** displays a table listing all referenced parameters. During evaluation, each parameter is replaced by its corresponding value; units, prefixes, and suffixes are ignored.

The **Analyze Expression** function validates the expression, evaluates it, and verifies that the result falls within the allowed range of the target parameter.

When **OK** is clicked, the expression is applied to the original parameter field. For numeric-only expressions, the leading = is removed. After **Apply** or **OK** is clicked, expression-based fields are displayed in **blue**. Selecting one of these fields reopens the **Expression Editor**, and the complete expression is shown in the **fx:** field at the top of the parameter dialog box.

Once defined, the target parameter remains linked to all referenced parameters. Any change to a referenced parameter automatically triggers re-evaluation of the expression.

## Limitations

The following limitations apply when using expressions in HYPERSIM:

* Most **three-phase parameters** cannot currently be referenced in expressions. Syntax such as `Ld1.R[2]` is not supported. However, individual phase attributes can be assigned expressions separately.
* If an expression references another component and the component is later moved into a subcircuit, the expression may no longer evaluate correctly because the parameter path is not updated automatically.
* Circular or cross-referenced expressions should be avoided. For example:\
  Comp1.Attr1 = Comp2.A\
  Comp2.A = Comp1.Attr1\
  Such dependencies can lead to evaluation errors.
* If the name of a referenced component is changed, any expressions that reference it are **not** updated automatically and must be corrected manually.
* Complex circular dependencies can cause application instability. For example:\
  Master

  Slave1 = Slave2\
  Slave2 = Slave3\
  Slave3 = Slave1 + Master\
  Modifying Master repeatedly may result in a fatal evaluation error, preventing parameter dialog boxes from being opened.
* Expressions cannot be used to assign values to individual **matrix** or **vector** elements.
* In the [Python API](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/hypersim-api-references.md), expressions can be assigned using **setComponentParameter()**. However, because commas (,) are used to separate phase and array elements, expressions containing commas are not currently supported.

{% code overflow="wrap" lineNumbers="true" %}

```python
## Don't use
HyWorksApi.setComponentParameter('Sine1', 'A', '=Max(10, 5)')
# HYPERSIM understands this as 2 phases on Sine1.A, first phase being "=Max(10" and second phase being "5)"
## Use
HyWorksApi.setComponentParameter('Sine1', 'A', '=Max(10; 5)')
## HYPERSIM understands this as 1 phase because there are no comma by replacing the "," with ";"
```

{% endcode %}


---

# 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/model-and-simulation/optimize-the-model/use-variables-and-expressions.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.
