> 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/device-symbols-and-libraries.md).

# Device Symbols & Libraries

## Overview

**Device symbols** are a critical component of the design process. Whether you use the symbols supplied with the standard HYPERSIM libraries or develop custom libraries for specific applications, the quality and accuracy of symbol data can significantly impact design efficiency and reliability.

**Library files** are valuable long-term assets that often outlive individual projects and are reused across multiple designs over many years. In addition, many HYPERSIM features rely on symbol customization and the proper configuration of library data. To support these requirements, HYPERSIM provides a comprehensive set of tools for creating, editing, and maintaining device symbols and symbol libraries.

Creating a device symbol involves more than simply drawing its graphical representation. Many HYPERSIM functions depend on the presence of correctly defined attributes and metadata within the symbol. Properly configured text attributes ensure that the symbol behaves correctly within the design environment and supports features such as attribute management, automation, reporting, and simulation.

## Symbol Libraries and Design Data

When a device is first added to a design, its symbol definition is copied into the design file. Only one copy of each symbol is stored, regardless of how many instances are used. This ensures that the design remains self-contained and is not affected by subsequent changes to the source library.

Whenever a symbol definition is modified, HYPERSIM also generates a **checksum** that identifies its version. The checksum is created automatically and can be included in reports using the **$CHECKSUM** script command. It can be useful for detecting unintended changes to a symbol.

### Update devices from library

In some cases, however, symbols in a design need to be updated from the library, or symbol changes made in a design need to be saved back to the library. To support this, HYPERSIM stores the source library information in the **LibName**, **LibPath**, and **LibDate** attributes. These attributes are used by **Options > Part Type > Update from Lib** to locate the original symbol and determine whether it has changed.

{% columns %}
{% column %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-4140cd73e23218850219cdd8d156f86702ca1d17%2Fupdate-device-library.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-d6a3dd5510fcecd1f646ec02511e5334348218fb%2Fupdate-device-select-library.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Only options relevant to the selected device are displayed.

**Source Library Options**

<table><thead><tr><th width="200">Command</th><th>Description</th></tr></thead><tbody><tr><td><strong>Select a new source library</strong></td><td>This selection causes a sequence of two prompt boxes to be displayed requesting a library and then a part within the library. This new symbol is used to update the selected device.</td></tr><tr><td><strong>Update from original library</strong></td><td>This selection locates the original library that the device was derived from using information stored in its attribute fields. As long as the library can be located and a part with the same name can be located in the library, the user is not prompted to locate a source.</td></tr></tbody></table>

**Scope Options & Attributes Options**

<table data-search="false"><thead><tr><th width="200">Command</th><th>Description</th></tr></thead><tbody><tr><td><strong>Update selected devices only</strong></td><td>This option updates only the selected devices. This redefines the device to be different from others originally derived from the same library part.</td></tr><tr><td><strong>Update all devices of the same type</strong></td><td>This option updates all devices in the design originally derived from the same part type. Note that this is determined by the internal logical linkage between the device instances and the part definition, not by the type name. If multiple type definitions got the same name in the design, this option will only update the devices linked to the same type as the selected one.</td></tr><tr><td><strong>Update all devices with the same type name</strong></td><td><p>This option updates all devices derived from a type with the same name as the selected one, even if the definitions have become separated by some previous operation. This is specifically intended to remedy the case where a design inadvertently contains multiple definitions of similar devices.</p><p><br>The <strong>Attribute Options</strong> dropdown menu allows choosing how attribute values are updated if the new symbol definition has different values than the existing device instance:</p></td></tr><tr><td><strong>Keep all old values</strong></td><td>This selection maintains all attribute values in the current instance, even if the new symbol definition has different values.</td></tr><tr><td><strong>Keep all old values modified in the instance</strong></td><td>This selection indicates keeping any attribute values in the device instance that was changed from the default value in the original definition. Any value that still has the default specified in the old symbol will be updated to the new default value in the new symbol.</td></tr><tr><td><strong>Use all new non-null values</strong></td><td>This selection indicates using the value specified in the new definition if there is one, but keep any old values that are not overridden by new ones.</td></tr><tr><td><strong>Use all New values-all old values will be discarded</strong></td><td>In this case, the updated instance will have exactly the values in the new definition, even if they are empty. All attribute data present in the old definition will have been replaced by new values.<br>It is noted that the Name attribute is not modified by this operation. It is also recalled that all device simulation data, as seen in HYPERSIM side, is saved into attributes, so the user must be careful with the updating process since it can affect previously entered data and change the numerical behaviour of a device. The first attribute updating option is less dangerous.</td></tr><tr><td><strong>Recalculate attribute positions</strong></td><td>This checkbox allows the user to determine whether displayed attribute values will be left at their old positions or recalculated to fit with the symbol. If the symbol has not changed in shape appreciably and the user has manually repositioned the displayed values, this option should be turned off.</td></tr><tr><td><strong>Update attributes only--symbol not changed</strong></td><td><p>If this box is checked, only attribute values are affected, the device symbol, pins, subcircuit and other aspects of the part type will not be affected.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>In some cases, the updated symbol may differ significantly from the original. For example, pin locations or spacing may have changed, making it difficult for HYPERSIM to reconnect signals correctly and preserve connectivity. In such situations, it may be preferable to enable this option.</p></div></td></tr></tbody></table>

### Save to library

The **Save to Lib..** in the **Options** ribbon command saves the type definition of the selected device to a library.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-608007b521c233b99b281f43f03e223bd71d8f61%2Fsave-device-library.png?alt=media" alt="" width="369"><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="200.0001220703125" valign="top">Command</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><strong>Save the symbol image and its original orientation</strong></td><td valign="top">Saves the device in its original orientation, as originally created.</td></tr><tr><td valign="top"><strong>Save the symbol rotated…</strong></td><td valign="top">Saves the device as the device appears in the design.</td></tr><tr><td valign="top"><strong>Save attributes from the original definition only</strong></td><td valign="top">If this option is selected, only attributes originally defined for the library part are saved.</td></tr><tr><td valign="top"><strong>Save all attributes in the selected instance</strong></td><td valign="top">If this option is selected, all the attribute values associated with the selected device will be made part of the saved library part.</td></tr><tr><td valign="top"><strong>Save positions of all visible attributes in the selected instance</strong></td><td valign="top">If this box is checked, then a Pt position field is saved for each attribute visible on the instance and for which the associated Pt field is defined in the design’s attribute table (available if Save all attributes in the selected instance is checked).<br>This option saves the desired position of a visible attribute after adjusting it with the mouse pointer.</td></tr><tr><td valign="top"><strong>Save internal circuit definition</strong></td><td valign="top">If this box is checked, the internal circuit attached to the selected device is saved with the part definition. It is very important to remember to check this box if the device has a subcircuit since it is not saved to the library otherwise.</td></tr><tr><td valign="top"><strong>Part Name</strong></td><td valign="top">The part name under which the new library entry is saved. This is the name that appears in the library listing.</td></tr><tr><td valign="top"><strong>Open Library</strong></td><td valign="top">Opens a library which is not listed.</td></tr><tr><td valign="top"><strong>New Library</strong></td><td valign="top"><p>This button will display a standard file save box for the creation of a new, empty library.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>It is strongly recommended that user libraries be created in a directory other than the default HYPERSIM library directory (HyLibs).</p></div></td></tr></tbody></table>

## Manage libraries

### Automatically Open Libraries at Startup

You can configure libraries to open automatically when the application starts.

To manage startup libraries, in the **Options ribbon** click on **Library Operations**, or right-click anywhere in the **Parts Palette** to select **Auto-Open Libraries**

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

In the **Auto-Open Libraries** window:

* Click **Add** to select a library to open at startup.
* Select a library and click **Delete** to remove it from the auto-open list.

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

By default, the HYPERSIM installation creates a folder named **HyLibs**, which contains the standard libraries provided with the software.

### Librairies maintenance

The **Library Maintenance** command is available from the right-click menu in the Parts palette or use in the Options ribbon in Library Operations.

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

<table data-search="false"><thead><tr><th width="200">Command</th><th>Description</th></tr></thead><tbody><tr><td><strong>Delete</strong></td><td>Deletes one or more symbols from the Source Library. This operation cannot be undone.</td></tr><tr><td><strong>Duplicate</strong></td><td>Duplicates symbols within the Source Library. The user will be prompted for each selected item to enter a new name. Names must be unique within a library.</td></tr><tr><td><strong>Promote</strong></td><td>Causes the selected items in the Source Library to be moved up the list.</td></tr><tr><td><strong>Denote</strong></td><td>Causes the selected items in the Source Library to be moved down the list.</td></tr><tr><td><strong>Rename</strong></td><td>Used to rename a single selected symbol in the Source Library.</td></tr><tr><td><strong>Sort</strong></td><td>Sorts the entire list alphabetically.</td></tr><tr><td><strong>Repair</strong></td><td>Useful for fixing library problems.</td></tr><tr><td><strong>Copy</strong></td><td>This button is used to copy one or more symbols from one library to another.</td></tr><tr><td><strong>Compact</strong></td><td>When parts are deleted from a library, the free space in the file is not automatically recovered. In most cases, this is not a significant overhead. However, if a large percentage of the parts in a library has been deleted then the user may wish to compact the file. The modified library could be compacted in a new one. The previous library should be deleted after verifying the new library.</td></tr></tbody></table>

The **Shift** and **Ctrl keys** can be used for selecting more than one symbol in some operations.

{% hint style="info" %}
Items displayed in the **Parts Palette** are always sorted alphabetically. Therefore, the **Promote**, **Demote**, and **Sort** commands do not affect their display order.

These commands modify the order in which symbols are indexed within the library file, which can influence certain internal library operations.
{% endhint %}


---

# 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/device-symbols-and-libraries.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.
