> 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/automation-api-and-scripting/automate-using-testview/testview-examples/use-excel-to-define-test-parameters.md).

# Use Excel to Define Test Parameters

## Description

This example builds on the [**Automate Fault Timing Tests**](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-using-testview/testview-examples/automate-fault-timing-tests.md) and [**Use Variables & Conditional Logic**](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-using-testview/testview-examples/use-variables-and-conditional-logic.md) examples by showing how to use an **Excel file** to define the parameters of a test directly. It focuses on using TestView's Excel integration to modify the resistance of **Ld2** in the **HVAC\_500kV\_6Bus** example model found under **Transmission** and to run multiple fault scenarios.

## Detailed explanation

{% stepper %}
{% step %}
**Prepare the example**

Prepare the base of the example by follow the steps in **Launch TestView & Run a Test** section: Open the **HVAC\_500kV\_6Bus** example model, load the `.csv` sensors file, start and stop the simulation once, then launch TestView and create a new TestView project, study, and test, adding the required **HYPERSIM Test** and **HYPERSIM Settings** commands.
{% endstep %}

{% step %}
**Verify HYPERSIM Settings**

In the TestView test sequence, double‑click the **HYPERSIM Settings** command to open the dialog and ensure **Disable Time Events (clrtab)** is **unchecked**. This ensures time‑based events (faults, operations) will be executed.

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

{% step %}
**Add a 1‑second delay using the Sleep command**

Adding a 1-second delay ensures the simulation reaches steady‑state before the fault. In the **Palette** tab, click **Sleep**, accept the default **1‑second** delay and click **Apply**.

The script now begins with:

* HYPERSIM Test
* HYPERSIM Settings
* Sleep (1s)
  {% endstep %}

{% step %}
**Add a Snapshot command**

Snapshots preserve currents and voltages, ensuring each iteration starts under identical conditions.

Add a **Snapshot** command, select **Take a snapshot of the simulation** and click **Apply**.

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

{% step %}
**Add a Loop command**

Add a **Loop** command, **uncheck** the **User defined box** and check the **Operation** box. Click **Apply**.

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

{% step %}
**Create an Excel File**

Before adding commands inside the loop, prepare the Excel file that will supply the test parameters.

1. Create a new `.xlsx` file anywhere on your system (In this example, it is created in the TestView project directory under the name `example3.xlsx`).
2. Fill in the Excel to be compatible with the TestView [**Excel** ](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-using-testview/test-commands-reference/main/excel.md)command.

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

{% hint style="info" %}
Parameter names can be found in the **Netlist** or by hovering over components in HYPERSIM.

`%{}` denotes a **variable**.

`Ld2.R` refers to the **resistance parameter** of component **Ld2**.

If a component has multiple parameters to modify, you can place the component name in one column (e.g., column **I**) and put parameter names in the following columns (`.R`, `.tOpen`, etc.) to improve readability.

Columns starting with **#** are comments and are ignored by TestView.
{% endhint %}

3. TestView uses **named ranges** in Excel to identify **input values** (imported through the Excel command) and the **results** (written using the **TableOut** command). In the Excel file, define the **Input** **named range** by selecting all input data **including the header**, right‑clicking the selection and choosing **Define Name…**

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

4. Assign a name such as `inputs_testview` and click **OK**.

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

5. To define the **Output** **named range** in Excel, select an **empty area** in the Excel sheet where the results will be written (the exact number of rows and columns does not matter - TestView will automatically resize the range as needed). Define a name, for example `output_testview`.
6. Verify the named ranges, use **Formulas → Name Manager** to confirm both named ranges exist and they do **not** overlap.

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

7. Save and close the Excel file.

{% hint style="danger" %}
CSV files use commas to separate values, but in some locales the **comma ( , )** and **period ( . )** are used differently for decimal notation. Ensure that the language settings of your `.xls` or `.xlsx` file are compatible with your system’s Excel configuration when importing or exporting data.
{% endhint %}
{% endstep %}

{% step %}
**Import the Excel data in the TestView loop**

In TestView, after the **Loop** command, add an **Excel** command, then click the **ellipsis (…)** to browse and select the Excel file you created; once selected, click **Import from Excel** so the parameters defined in the file appear in the **Excel** command window, and finally click **Apply** to add the command.

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

{% step %}
**Load the Snapshot inside the loop**

Add a **Snapshot** command. Uncheck **Take snapshot**, check **Load the current snapshot**, and click **Apply**. This ensures each iteration starts from the same steady‑state.

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

{% step %}
**Add a Processing command**

Add a **Processing** command from the **Main** folder to acquire signals using ScopeView’s engine.

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

In the **General** tab:

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

1. Set the **Sampling rate** = `1 / timestep` = **20,000 Hz** for 50 µs timestep and check both the **Synchronization** (POW-based) and **Operation sequence** (executes fault and breaker sequence) boxes.
2. Ensure **Show graphic** boxes are **checked** for both processing modes.
3. Click **Signals Key**, select the **Breaker** category and click once on **Fault.CMDa** (command signal from **Fault** block), **Di1.Ia**, **Di1.Ib** and **Di1.Ic** (currents from the breaker near the fault location) to select them.

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

4. Save as a new keyname, give a name and then click **Ok**.

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

In the **Processing** tab:

1. Only the signals from the Signals Key appear. Click once on **Fault.CMDa**, **Di1.Ia**, **Di1.Ib** and **Di1.Ic** to select them.

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

2. In the **Selected Signals** list, type the two following functions:

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

In the **Post-Processing** tab:

Add the two resulting values.

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

The test sequence should now look like this:

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

{% step %}
**Export results to Excel**

Add a **TableOut** command outside the loop, enable **Export to Excel**, then click the **ellipsis (…)** to browse and select the Excel file you created, choose **Named Range**, enter `output_testview`, select the results you want to export (`max_current_phaseA` and `time_CMDa`), then click **Apply** to confirm.

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

{% step %}
**Review the test sequence**

The test sequence is now complete and should look like in the following image.

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

{% step %}
**Run the test**

In the **Runner** tab, choose **Current test only**, then press **Play**. When completed, open the Excel file to verify that:

* The results were written to the `output_testview` range
* Parameter values, fault types, and timing match expectations

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

{% hint style="info" %}
**`time_CMDa` = 1.79e+308**\
This is normal in the second test (BG fault), since phase A does not switch.

**Different Output File**\
Results may be written to a separate Excel file if desired.

**Re‑importing Excel Data**\
If the Excel file is changed, re‑import the data or enable

**Auto‑import on play**.\
Otherwise, updates will not be reflected in TestView.

**Appending Instead of Overwriting**\
TableOut supports **Append Test Data**, allowing data to accumulate across runs.\
Use with caution to avoid excessively large files.
{% endhint %}
{% endstep %}
{% endstepper %}


---

# 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/automation-api-and-scripting/automate-using-testview/testview-examples/use-excel-to-define-test-parameters.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.
