> 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/data-logger.md).

# Data Logger

## Description

The **Data Logger** example, located in **File > Open an Example File > How To**, demonstrates how to configure and use the data logger and how to visualize recordings in ScopeView.

The objectives are to illustrate automatic and manual recording, frame management, trigger configuration, and basic automation with a Python script.

This example can run on the workstation or on a real-time simulator.

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

## Requirements

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

## Detailed explanation

In this example, different scenarios are tested. The configuration records 10 frames of 2 seconds each (total acquisition time: 20 seconds).

Data logger can be access from the HYPERSIM ribbon. Click on Control Center button to open the Data Logger configuration.

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

{% hint style="info" %}
When running the simulation on the workstation, configure the data logger with ***No data loss***.
{% endhint %}

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

## Simulation and results

{% stepper %}
{% step %}

### **Record in automatic mode**

* Starting the simulation automatically records all signals listed in the **Sensor Summary** window.
* After stopping the simulation, open **Recording Manager** (under Data Logger section in the ribbon) to access the recorded files.
* For visualization, open ScopeView and select the data source (.oprec file in the data folder). For more details, see [ScopeView | Main Window.](https://www.opal-rt.com/docs/scopeview/)
  {% endstep %}

{% step %}

### **Record in manual mode**

* Set the Recording Mode to Manual in the Data Logger configuration (see Data Logger Configuration).
* In order to proceed, keep the Data Logger configuration window open and go to *Signal Groups (N)*.
* Start the simulation and click the record button to start recording.

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

* To stop, either let the 20-second recording complete (10 frames of 2 seconds) or click the stop button.
* After recording and stopping the simulation, open Recording Manager (under Data Logger section in the ribbon) to access the data.
  {% endstep %}

{% step %}

### **Play with frames**

For each signal group, in the Data Logger configuration, configure the recording using:

* **Decimation factor:** Number of steps recorded = total number of steps divided by the decimation factor. A value of 1 stores every calculation step; 2 stores every second step, etc.
* **Frame length:** Maximum number of samples per frame (unit set below) to be stored. This limits the maximum expected file size.
* **Frame units:** Choose number of steps, a duration (from nanoseconds to hours), or a file size in megabytes.
* **Number of frames to record:** Total frames to record. Example: with a frame length of 1 second and 10 frames, the total recorded time is 10 seconds.

{% hint style="info" %}
The data file size updates every time a frame is written. If you record 100 seconds in 1 frame, results are available only after 100 seconds. If you record 1 second per frame for 100 frames, you can view waveforms after each second while recording continues.
{% endhint %}

**Example:** Record 1 second per frame for 100 frames.

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

As soon as the simulation starts, the file size increases in the IOData sub-folder of the code directory. Press F5 to refresh and see the updated file size.

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

{% step %}

### **Use a trigger**

* To select a signal as a trigger, use the **trigger checkbox** in Sensor Summary window.

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

* In this scenario, the trigger signal is the current Ia through Di1 (Di1.Ia).

You can set up different parameters such as:

* **Trigger level:** Value that activates the trigger.
* **Trigger function:** Activate on an edge or level event.
* **Trigger polarity:** **Positive** or **negative**. For edge triggers, select rising (positive) or falling (negative) around the specified level.
* **Pre-trigger percentage:** Percentage of the record length to log before the trigger condition. Example: for 25%, enter 25.0.
* **Trigger holdoff:** Duration after a trigger during which subsequent triggers are ignored. Uses the unit set in **Frame length units**.

{% hint style="info" %}
**Only one trigger** can be set per signal group.
{% endhint %}

**Play with trigger level:**

* Compare Trigger Level = 0.0 and 2000.0: with 2000.0, acquisition starts when Ia crosses 2000.0 V. In this case, the data logger records a single frame.

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

* With a Pre-trigger percentage of 25% and a 2-second frame, acquisition starts 0.5 s before Ia reaches 2000.0 V.

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

{% step %}

### **Python script**

**The script datalogger.py placed in the folder runs two of the four scenarios**: “Recording in Automatic Mode” on the fly and “Using a trigger” with pre-recorded .oprec files.

{% hint style="info" %}
The provided Python script is configured for the workstation; to run it in real time, update the simulator IP address in the script.
{% endhint %}

* Before running the script, you need to edit **hypersimDir**

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

* **Automatic recording step**: the script runs the simulation and records in automatic mode, opens the ScopeView template, and displays the .oprec results. Waveforms may vary depending on the simulation duration configured in the script.

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

* **Trigger comparison step**: the template shows three graphs—no trigger, trigger level at 2000.0 V on Di1.Ia, and trigger level at 2000.0 V with a 25% pre-trigger.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-dca68f723ddc290876450940e02e2b21dcc89542%2Fimage%20(511).png?alt=media" alt=""><figcaption></figcaption></figure>
{% 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/examples/how-to/data-logger.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.
