> 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/prepare-the-simulation/manage-performance-with-task-manager.md).

# Manage Performance with Task Manager

## Overview

The **Task Manager** (accessible from the **HYPERSIM** ribbon) provides a graphical view of the simulation tasks generated from the network and their distribution across available processor cores. It also allows users to manually assign and optimize tasks on specific processors to improve simulation performance and load balancing \[1].

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-db522fbf31ddd496fa4e72b577d73ff05444a9c9%2Ftask-manager-window.png?alt=media" alt="" width="509"><figcaption></figcaption></figure>

## Summary and preferences

**Preferences** contains configurable parameters that influence task mapping and processor allocation.

For improved performance, disable the **Legacy Task Mapper** and enable the new automatic task mapper based on the **Scotch** library. This mapper generally provides more efficient task distribution and better load balancing across available processor cores.

<table data-search="false"><thead><tr><th width="170">Parameter</th><th>Description</th><th width="170">Python API preference name</th></tr></thead><tbody><tr><td><strong>Time Step</strong></td><td>Simulation time step defined by the user</td><td>simulation.calculationStep</td></tr><tr><td><strong>Performance factor</strong></td><td><p>The performance factor is used to calculate the execution time step based on the user-defined time step.</p><p>Execution time step = performance factor * simulation time step.</p></td><td>simulation.performance</td></tr><tr><td><strong>Processor load level</strong></td><td>Set the maximum processor load considered during task mapping (value between 0 and 1).</td><td>simulation.procLoadLevel</td></tr><tr><td><strong>Processor reservation mode</strong></td><td><p>Optimization for multi-user usage. Dynamic CPU reservation can enhance performance</p><p>1 → Dynamic</p><p>2 → Dynamic and Static</p><p>3 → Static</p></td><td>simulation.taskMappingMode</td></tr><tr><td><strong>Use legacy task mapper</strong></td><td><p>Not recommended: If selected, the task manager will use the legacy task mapper.</p><p><strong>Note:</strong> The legacy task mapper is automatically activated if the <code>mapping.useBeta</code> preference is set to false.</p></td><td>mapping.useBeta</td></tr><tr><td><strong>Mapping strategy</strong></td><td>Select task mapping strategy: load balancing (Balance) or minimizing communications (Quality).</td><td>mapping.strategy</td></tr><tr><td><strong>Processor imbalance ratio</strong></td><td>Load balancing target for the task mapper. The value ranges from 0 to 1, with 1 representing perfect balance.</td><td>mapping.procImbalanceRatio</td></tr><tr><td><strong>Requested # of processors</strong></td><td>The number of processors specified by the user for the task mapper.<br>If set to the default value of 0, an optimized number will be automatically determined.<br>If the number of processors requested by the user exceeds the available hardware, then all physical cores will be reserved by the task mapper.</td><td>mapping.requestedProcs</td></tr></tbody></table>

## Tasks view

All tasks are displayed in a table, with each row representing a single task and its properties. The columns are grouped into three categories:

* **Information** – Read-only task properties and status information.
* **Inputs** – User-editable parameters that affect task mapping.
* **Results** – Outputs generated by the **Map Tasks** operation, including task assignment and mapping results.

<table data-header-hidden data-search="false"><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Task</strong></td><td>Task Name.</td></tr><tr><td><strong>Id</strong></td><td>Task Id.</td></tr><tr><td><strong>Category</strong></td><td>Task category, three categories are possible (SUSBSTATION, LINE, CONTROL).</td></tr><tr><td><strong>Exec Time</strong></td><td>Estimated execution time for the task.<br>The execution time can be also modified. When the entered value differed from the original one (computed by HYPERSIM), the figure is highlighted in orange.<br><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-97f1950e0f22f3477ee4ce18329b59be578c2456%2Ftask-manger-exec-time.png?alt=media" alt="" data-size="original"></td></tr><tr><td><strong>Set ProcId</strong></td><td>Pre-allocated processor number by the user (empty if there is no pre-allocation).<br>Tasks can be manually pre-allocated on a processor (strict constraints are applied to automatic task mapping). A combo box enables selection of the processor number from the available ones in the simulator.</td></tr><tr><td><strong>ProcId</strong></td><td>Map Tasks result, the processor number which has been automatically assigned to the task (empty if no Map Tasks has been run).</td></tr></tbody></table>

### Task view menu

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

<table><thead><tr><th width="200" valign="top">Command</th><th>Description</th></tr></thead><tbody><tr><td valign="top"><strong>Open and save config</strong></td><td>Modified data (Exec Time and Set ProcId) are saved as an XML file (preallocatedTasks.xml) within the model repertory modele_hyp/mapping/.<br>Open Config loads these saved files and Save Config saved the current configuration. It is useful for multi-architecture simulation (different number of processors, different computational power…). For a given architecture, the right XML configuration file has just to be selected. For instance preallocatedTasks_Windows.xml, preallocatedTasks_RTLinux1.xml or preallocatedTasks_RTLinux2.xml.</td></tr><tr><td valign="top"><strong>Clear config</strong></td><td>Deletes all user-defined values. Set ProcId column will be empty as Exec Time (no more orange value).</td></tr><tr><td valign="top"><strong>Map Tasks</strong></td><td>Runs the automatic task mapping. The processor set by the mapTasks will be displayed on the ProcId column.<br>If Set ProcId is not empty, normally Set ProcId=ProcId (manual pre-allocation principle as to force some tasks to be allocated to processors set by the user).<br><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-0a568392b6a489c26a1719fb357716d06f4a2012%2Fmap-tasks.png?alt=media" alt=""></td></tr><tr><td valign="top"><strong>Exec Time Unit Tasks</strong></td><td>Allows to change task execution time unit (by default in μs otherwise a percentage of the time step %Ts). Through the time step percent unit %Ts, the weight of each tasks can be more appreciated toward the real-time constraint.</td></tr></tbody></table>

A context menu is also available through right-click on selected tasks (multi-selection is enable).

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-920d1ac5cb9492f126628bdb788feaef6794cda0%2Ftask-manaager-context-menu.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

<table><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Select Task</strong></td><td>Enables visualization of task components within the design which are highlighted.</td></tr><tr><td><strong>Set Exec Time</strong></td><td></td></tr><tr><td><strong>Copy selected results to inputs</strong></td><td></td></tr><tr><td><strong>Set ProcId...</strong></td><td>Allows to set the pre-allocated processor for selected tasks. Multi-selection accelerate the pre-allocation of a group of tasks on the same processor.</td></tr></tbody></table>

## **REFERENCES**

\[1] P. Le-Huy, M. Woodacre, S. Guérette, É. Lemieux, Massively Parallel Real-Time Simulation of Very-Large-Scale Power Systems, International Conference on Power Systems Transients (IPST2017) in Seoul, Republic of Korea, 2017.


---

# 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/prepare-the-simulation/manage-performance-with-task-manager.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.
