> 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/edit-a-model-schematic.md).

# Design a Model Schematic

## Overview

In HYPERSIM, a "design" refers to a complete, self-contained logical entity stored in a single file. A circuit can be designed on a single page or organized functionally across multiple pages (up to 1000). Each page is displayed in its own circuit window (tab), with logical connections between pages established using page connector devices from the built-in Signal Routing library.

An **HYPERSIM circuit** is composed of five types of entities: **devices, pins, signals, text objects, and picture objects**.

* A **device** is an object that includes a graphical symbol, signal connection points called *pins*, and optional elements such as text attributes, internal circuitry, and simulation data. A device may represent a physical component, a subcircuit block, or a pseudo-device such as a page connector.
* A **pin** is a connection point on a device. Pins are not independent entities—they exist only as part of a device and cannot be created or removed separately. However, each pin can have its own attributes, such as pin numbers and parameters, which may vary within the same device. A **bus (bundle) pin** is a special type that represents multiple internal pins. These internal connections are not visible on the schematic but retain the same logical properties as standard pins.
* A **signal** represents a conductive path between devices. Connections can be created either visually, by drawing lines between device pins, or logically, by assigning signal names.
* A **text object** is used to add titles, annotations, or other descriptive information to the schematic. Text can be entered and edited directly within HYPERSIM or pasted from external sources. Text objects are independent and are not linked to devices or signals. To associate text with specific elements, attribute fields should be used instead.
* A **picture object** allows insertion of graphical elements imported from other applications or from the symbol editor via the clipboard. While picture objects can be moved, copied, or deleted within the Schematic tool, they cannot be edited directly. However, they can be transferred to and modified in the symbol editor or other external applications.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-90e53402065da71faca5d32f308e9bbe74362bf8%2FCircuit-example-design.png?alt=media" alt="" width="480"><figcaption><p>HYPERSIM circuit example</p></figcaption></figure>

## The HYPERSIM user interface overview

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

The **Schematic** is the main workspace where your model is designed and components are placed, while the **Parts Library** lists [all available blocks](broken://spaces/N9x5CUu79pubjsBH7Ja1/pages/CkgCJ6bLso31hzRDfitz) that can be dragged into the schematic.

The **log console** (area 4 at the bottom of the image) displays simulation logs (.simout file), compilation information, and system messages.

The **toolbar ribbon** (area 1 at the top of the image) provides access to simulation controls, tools, and configuration options.

## Toolbar ribbon

### **File Ribbon** <a href="#basicschematicediting-fileribbon" id="basicschematicediting-fileribbon"></a>

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

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Save</strong></td><td>Save the current circuit</td></tr><tr><td><strong>Save As..</strong></td><td>Open a standard file dialog prompting you to enter a name for the new file</td></tr><tr><td><strong>New</strong></td><td>Create an empty circuit with a single page</td></tr><tr><td><strong>Open</strong></td><td>Open a file dialog to choose the circuit file</td></tr><tr><td><strong>Close</strong></td><td>Close the current document.</td></tr><tr><td><strong>File > Revert</strong></td><td>Revert to the last saved version of this design.</td></tr><tr><td><strong>File > Options</strong></td><td>Various options for opening files and creating new designs.</td></tr><tr><td><strong>Print</strong></td><td></td></tr><tr><td><strong>Print Setup</strong></td><td></td></tr><tr><td><strong>Help &#x26; Support</strong></td><td>Top Help and support section of HYPERSIM®.</td></tr></tbody></table>

### **Home ribbon** <a href="#basicschematicediting-homeribbon" id="basicschematicediting-homeribbon"></a>

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

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Clipboard > Cut</strong></td><td>Copy selected items to the clipboard and remove from the screen</td></tr><tr><td><strong>Clipboard > Copy</strong></td><td>Copy selected items to the clipboard</td></tr><tr><td><strong>Clipboard > Paste</strong></td><td>Paste from the clipboard in the current screen</td></tr><tr><td><strong>Clipboard > Paste Special</strong></td><td>Paste from the clipboard in the current screen with options.</td></tr><tr><td><strong>Tools > Point</strong></td><td>Returns to standard pointer to select or move object.</td></tr><tr><td><strong>Tools > Zap</strong></td><td>Selects the Zap (delete) cursor.<br>You can use ESC button or spacebar to return to the standard pointer.</td></tr><tr><td><strong>Tools > Name</strong></td><td><p>This is the same as the Naming tool used for device attributes, pins and signal attributes. Selecting and clicking on a device, signal or pin gives access to the name attribute. Selecting and clicking on a visible attribute gives access to that attribute contents. This tool can be also used for editing text created with “Home>Draw Graphics>Text”.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Note that the following list of characters is not supported : " !@#$%^~&#x26;*-+=</p></div></td></tr><tr><td><strong>Tools > Draw Signal</strong></td><td>Creates signals.<br>Use the selector to choose the signal type, such as general, diagonal, bundle, 3‑phase bus, or individual phases (A, B, or C).</td></tr><tr><td><strong>Tools > Move</strong></td><td>Returns to move pointer to move or stretch objects.</td></tr><tr><td><strong>Tools > Attribute Probe</strong></td><td>Displays attributes and information on the selected (clicked) object.</td></tr><tr><td><strong>Operations > Properties</strong></td><td>Shows the properties of the selected device or of the circuit (when no selected device). This is the same as the Ctrl+I shortcut and this menu is available from actual object (device) right-click menu or circuit right-click menu.</td></tr><tr><td><strong>Operations > Orientation</strong></td><td>Sets device orientation for the next device dragged in from a library.</td></tr><tr><td><strong>Operation > Rotate Left</strong></td><td>Rotate the selected item 90° to the left.</td></tr><tr><td><strong>Draw Graphics</strong></td><td>Various tools for drawing graphics objects on the schematic.</td></tr><tr><td><strong>Find > Quick Find</strong></td><td>Search for entered object name (signal or device). Only partial information can be entered. You can use the Ctrl+G shortcut to zoom in on found signal or device.</td></tr><tr><td><strong>Find > Advanced Find</strong></td><td>Opens the Find tool tab. See Locating Circuit Objects with the Find Tool. You can use the Ctrl+G shortcut to zoom in on found signal or device.</td></tr><tr><td><strong>Find > Property Browser</strong></td><td>Opens the Attribute Browser tool.</td></tr></tbody></table>

### **Options ribbon** <a href="#basicschematicediting-optionsribbon" id="basicschematicediting-optionsribbon"></a>

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

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Design > Pages</strong></td><td>Create, delete and modify circuit pages.</td></tr><tr><td><strong>Design > Import Sheet Info</strong></td><td>Used to set the sheet border and background style.</td></tr><tr><td><strong>Design > Sheet Size Wizard</strong></td><td>View and change sheet size.</td></tr><tr><td><strong>Design > Border Wizard</strong></td><td>View and change border settings.</td></tr><tr><td><strong>Design > Design Attributes</strong></td><td>View and change design attributes.</td></tr><tr><td><strong>Design > Define Attribute Fields</strong></td><td>Create or modify attribute field definitions.</td></tr><tr><td><strong>Naming Options</strong></td><td>Various naming options for devices and signals.</td></tr><tr><td><strong>Part Type > Update from Lib</strong></td><td>Update the selected device from a library.</td></tr><tr><td><strong>Part Type > Save to Lib</strong></td><td>Save the part definition of the selected device to a library.</td></tr><tr><td><strong>Part Type > Make Unique Type</strong></td><td>Make a new part type definition for the selected device.</td></tr><tr><td><strong>Subcircuit > Create Subcircuit Block</strong></td><td>This is the top dialog for creating subcircuits.</td></tr><tr><td><strong>Subcircuit > New Port Connector</strong></td><td>Creates a port connector for the subcircuit interface pins.</td></tr><tr><td><strong>Subcircuit > Attach Subcircuit</strong></td><td>Attach a subcircuit to the selected symbol.</td></tr><tr><td><strong>Subcircuit > Detach Subcircuit</strong></td><td>Detach the subcircuit associated with the selected symbol, making it a separate design.</td></tr><tr><td><strong>Subcircuit > Discard Subcircuit</strong></td><td>Discard the subcircuit associated with the selected symbol.</td></tr><tr><td><strong>Subcircuit > Push Into</strong></td><td>To get into a selected subcircuit contents (same as Ctrl+Shift+I).</td></tr><tr><td><strong>Subcircuit > Pop Up</strong></td><td>Close the current subcircuit and go to the parent level (same as Ctrl+Shift+U).</td></tr><tr><td><strong>Export</strong></td><td>Export operations</td></tr><tr><td><strong>Libraries> New Part</strong></td><td>Opens the Symbol Editor for creating a new part.</td></tr><tr><td><strong>Libraries> Library Operations</strong></td><td>Various library maintenance functions.</td></tr></tbody></table>

### **View ribbon** <a href="#basicschematicediting-viewribbon" id="basicschematicediting-viewribbon"></a>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7a157324567375aa51cb2b16aa70835696df43e1%2Fview-ribbon.png?alt=media" alt="" width="494"><figcaption></figcaption></figure>

| **Scroll**                 | Various tools for scrolling for navigating within the screen                                 |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| **Zoom**                   | Various tools for screen zoom control                                                        |
| **Zoom > Pan**             | Allows panning the circuit diagram. Same as holding Ctrl button and using left mouse button. |
| **Zoom > Redraw**          | Refresh the circuit drawing.                                                                 |
| **Panels > Parts Library** | Shows or hides the Parts Palette.                                                            |
| **Panels > Console**       | Shows or hides the Console window.                                                           |

### **Design ribbon** <a href="#basicschematicediting-designribbon" id="basicschematicediting-designribbon"></a>

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

This menu is scripted. It is created in the **hyperworks.ini** file and uses the HYPERSIM scripting techniques for programming various tasks. You can open the scripts associated with each item and learn on script programming methods.

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Device Operations > Exclude Devices</strong></td><td>Exclude the selected devices from the Netlist. This command is similar to the Exclude/Include available from device right-click menu. The difference is that in this case it can act on one or more selected devices in the design. You can select entire circuit sections using the Shift and Ctrl keys while clicking on devices, or using a bounding box.</td></tr><tr><td><strong>Device Operations > Include Devices</strong></td><td>Include the selected devices back into the Netlist. This command is similar to the Exclude/Include available from device right-click menu. There is no change if the selected devices are already included. The difference is that in this case it can act on one or more selected devices in the design. You can select entire circuit sections using the Shift and Ctrl keys while clicking on devices, or using a bounding box.</td></tr><tr><td><strong>Device Operations > Show/Hide</strong></td><td>Commands for showing or hiding various device attributes.</td></tr><tr><td><strong>Signal Operations > Signal Parameters</strong></td><td>Allows setting properties for selected signals. This is similar to the item “Signal Parameters” available from individual signal right-click menu. The difference is that you can now selected one or more signals and apply simultaneous changes.</td></tr><tr><td><strong>Signal Operations > Show Hide</strong></td><td>Commands for showing or hiding signal names.</td></tr><tr><td><strong>Utilities > Define Global Variables</strong></td><td>See documentation link available after selecting this option. This option allows creating Global Variables to be used in various locations in HYPERSIM mask scripts.</td></tr><tr><td><strong>Utilities > Run a script</strong></td><td>Allows to select and run a script on the current design.</td></tr></tbody></table>

### **HYPERSIM ribbon** <a href="#basicschematicediting-hypersimribbon" id="basicschematicediting-hypersimribbon"></a>

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

This menu is created in the hyperworks.ini file.

<table data-header-hidden data-search="false"><thead><tr><th width="199.77783203125"></th><th></th></tr></thead><tbody><tr><td><strong>Tools > ScopeView</strong></td><td>A graphical data acquisition and signal processing software</td></tr><tr><td><strong>Tools > TestView</strong></td><td>A powerful GUI enabling the definition and execution of automated tests</td></tr><tr><td><strong>Tools > Sequencer</strong></td><td>A GUI allowing you to execute simulation sequences written in Python</td></tr><tr><td><strong>Tools > Preferences</strong></td><td>Allow the user to manage display units (SI/PU) and various other global parameters</td></tr><tr><td><strong>Tools > Targets</strong></td><td>Allow the user to manage the target's HYPERSIM version, license, compilation/simulation parameters, as well as run diagnostics and other advanced parameters.</td></tr><tr><td><strong>Tools > Dashboard</strong></td><td>An application designed to create intuitive tables of parameters and signals, along with customizable panels for displaying and controlling widgets.</td></tr><tr><td><strong>Import/Export> Project</strong></td><td>Import or export HYPERSIM project as zip file</td></tr><tr><td><strong>Import/Export> UCM</strong></td><td></td></tr><tr><td><strong>Import/Export> Simulink</strong></td><td></td></tr><tr><td><strong>Import/Export> Import Network</strong></td><td></td></tr><tr><td><strong>Sensors &#x26; I/Os> I/O Interface</strong></td><td></td></tr><tr><td><strong>Sensors &#x26; I/Os>Sensors Summary</strong></td><td></td></tr><tr><td><strong>Sensors &#x26; I/Os> Load</strong></td><td></td></tr><tr><td><strong>Sensors &#x26; I/Os> Append</strong></td><td></td></tr><tr><td><strong>Sensors &#x26; I/Os> Clear</strong></td><td></td></tr><tr><td><strong>Sensors &#x26; I/Os> Save</strong></td><td></td></tr><tr><td><strong>Sensors &#x26; I/Os> SAve As</strong></td><td></td></tr><tr><td><strong>Data Logger> Control Center</strong></td><td></td></tr><tr><td><strong>Data Logger> Recording Manager</strong></td><td></td></tr><tr><td><strong>Network> Topology Analysis</strong></td><td></td></tr><tr><td><strong>Network> Set Initial Conditions</strong></td><td></td></tr><tr><td><strong>Network> Netlist</strong></td><td></td></tr><tr><td><strong>Network> Disable Breakers/Faults</strong></td><td></td></tr><tr><td><strong>Network> Impedance Measurement</strong></td><td></td></tr><tr><td><strong>Network> Task Manager</strong></td><td></td></tr><tr><td><strong>Network> Analyze</strong></td><td></td></tr><tr><td><strong>Network> Load Flow</strong></td><td></td></tr><tr><td><strong>Network> map Tasks</strong></td><td></td></tr><tr><td><strong>Network> Generate Code</strong></td><td>Converts the model into C code</td></tr><tr><td><strong>Simulation> Start</strong></td><td>Starts the simulation</td></tr><tr><td><strong>Simulation> Stop</strong></td><td>Stops the simulation</td></tr><tr><td><strong>Simulation> Settings</strong></td><td>Opens the Simulation Settings window.</td></tr><tr><td><strong>Simulation> Snapshot</strong></td><td>Takes or Load a snapshot during a simulation.</td></tr><tr><td><strong>Simulation> Monitoring</strong></td><td>Starts and stops Monitors during the simulation.</td></tr><tr><td><strong>Simulation> Real-Time Monitor</strong></td><td>Opens the RT Monitor window.</td></tr><tr><td><strong>help> Diagnostic</strong></td><td>Opens the Diagnostic window.</td></tr></tbody></table>

## The parts library

The **Parts Library** is divided into two main categories: **Network** and **Control**. This distinction is important because HYPERSIM processes them differently during simulation.

Network blocks are solved using a **nodal analysis approach**, whereas Control blocks are evaluated as **algebraic functions**.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-1e71ca6dd0a5776b198cb9a625f6ae6fcbdeb594%2Fparts-library-organisation.png?alt=media" alt="" width="265"><figcaption></figcaption></figure>

The **control libraries** include blocks required to model control and auxiliary functions within the network. Unlike network elements, these blocks do not directly represent physical electrical phenomena. They also provide pre-configured control algorithms, such as IEEE exciters, governors, and protection relay functions, allowing users to avoid building these models from scratch.

The **network libraries** contain blockts that represent elements of the electrical network through which power flows, such as machines, breakers, transmission lines, and transformers. All blocks are preconfigured with realistic default values based on typical real-world conditions.

### Filter the library

The **Filter** text box is available when **All Parts** is selected from the **Parts by Library** drop-down menu. Enter one or more characters in the **Filter** text box to narrow the list of available parts and quickly locate the desired component. After a brief pause, the list is automatically updated to display only the parts whose names contain the entered text.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-89b4ba5a6847f6cac4b49dbcc618490566293c5b%2Ffilter-library-parts.png?alt=media" alt="" width="272"><figcaption></figcaption></figure>

To restore the full list, simply clear the contents of the **Filter** text box.


---

# 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/edit-a-model-schematic.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.
