> 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/create-manage-subcircuits.md).

# Create & Manage Subcircuits

## Overview

A **subcircuit** allows you to encapsulate portions of a circuit into reusable, hierarchical blocks. It is represented by a device symbol that contains an internal circuit, with the symbol's pins corresponding to specific input and output connection points within that circuit.

Using subcircuits provides several advantages:

* **Simplifies complex designs** by representing detailed circuitry as compact, easy-to-read blocks.
* **Supports hierarchical design**, allowing subcircuits to be nested within other subcircuits with no practical limit on the number of levels.
* **Promotes reuse and consistency**, as the same subcircuit can be instantiated in multiple locations. Any modification to the subcircuit definition is automatically propagated to all instances of that subcircuit type

Key characteristics of subcircuits include:

* A subcircuit may contain **one or more pins**, including both **standard pins** and **bundle pins**.
* A subcircuit may have **no pins**, in which case it represents an electrically independent circuit.
* A subcircuit can contain both **electrical and non-electrical objects**.
* A subcircuit may contain **one or more nested subcircuits**, enabling multi-level hierarchical designs.
* A subcircuit can span **multiple pages**, allowing large circuits to be organized across several schematic pages.

Subcircuits can be created from virtually any portion of a design, ranging from a small group of components to an entire circuit. During the creation process, the user has full control over the subcircuit interface, including the selection and placement of its pins.

## Create a subcircuit from the portions of the model

{% stepper %}
{% step %}

### Add the port connectors

In the **Options** ribbon, click **New Port Connector** in the **Subcircuit** section to open the dialog box. Select **Power** as the signal port connector type for a power signal, then enter a name for the port.

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

{% hint style="info" %}
Port blocks are also availabale in the Signal Routing library.
{% endhint %}

<table><thead><tr><th width="180.33331298828125" align="center">Port representation</th><th>Description</th></tr></thead><tbody><tr><td align="center"><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-81a0a479158cd30e7971c681eade27dedcae835a%2Fimage%20(330).png?alt=media" alt="" data-size="line"></td><td>Subcircuit port, bundle: use to connect a bundle signal</td></tr><tr><td align="center"><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b7cbd0f55fe44e4ab887d5b9ea67e5fc9659bff6%2Fimage%20(827).png?alt=media" alt="" data-size="line"></td><td>Subcircuit port, power signal: use to connect a network signal</td></tr><tr><td align="center"><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-bd9bd2f2b9d70a60890b56ae0a94605f6fbc5e87%2Fimage%20(1196).png?alt=media" alt="" data-size="line"></td><td>Subcircuit port, control input: use to connect a control signal <strong>entering</strong> the subsystem</td></tr><tr><td align="center"><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-75b0d2577e172c8caaa408588be87fdeaa154069%2Fimage%20(1197).png?alt=media" alt="" data-size="line"></td><td>Subcircuit port, control output: use to connect a control signal <strong>leaving</strong> the subsystem</td></tr></tbody></table>
{% endstep %}

{% step %}

### Create the subcircuit

Select the portions of the model that you want to encapsulate in a subcircuit. On the **Options** ribbon, click **Create Subcircuit Block** in the **Subcircuit** section to open the dialog box. Configure the desired options, enter a name for the subcircuit, and then create the subcircuit block.

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

Double-click the subcircuit block to open its internal design in a new window.

By default, the subcircuit is opened in **read-only mode**, and an alert window appears each time you attempt to move a block. Click **Unlock Circuit** to enable editing. To return the circuit to read-only mode, right-click anywhere in the design area and select **Properties**, or go to the **Home** ribbon and click **Properties** in the **Operations** section.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-28ddccdeb76613a288433ce239ebe2d84c03149b%2Fread-only-alert.png?alt=media" alt="" width="278"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Create an empty subcircuit

{% columns %}
{% column %}

1. On the **Options** ribbon, click **Create Subcircuit Block** in the **Subcircuit** section to open the dialog box.
   {% endcolumn %}

{% column %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8ea0fcf55f579577c6853db911916b4ef875e84b%2Fcreate_subcircuit-step1.png?alt=media" alt="" width="348"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}
2\. Choose the appropriate **option** from the list.
{% endcolumn %}

{% column %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-9c984429fa2dc4827e8181a602734ca503d23109%2Fcreate_subcircuit-step2.png?alt=media" alt="" width="348"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}
3\. Specify the desired **pin locations** and click Next. The corresponding port blocks are automatically added to the design.
{% endcolumn %}

{% column %}

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-3a83aadc63c901fd94cf5ae879e3f382a3b99987%2Fcreate_subcircuit-step3.png?alt=media" alt="" width="348"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}
4\. Assign a **name** to the subcircuit.
{% endcolumn %}

{% column %}

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

{% columns %}
{% column %}
5\. To **save** the subcircuit in a **library**, select the corresponding checkbox, enter the target library name, and click **Finish**.
{% endcolumn %}

{% column %}

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

## Manage subcircuit

### **Hierarchical naming system**

When a subcircuit is copied, HYPERSIM maintains a single definition of the subcircuit's internal circuit. As a result, all instances of the same subcircuit type share the same underlying implementation. Any modification made to the subcircuit definition is automatically propagated to every instance of that type throughout the design.

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

A subcircuit is **encapsulated**, meaning its contents are hidden from the **parent circuit** that contains it. The only connections between a parent circuit and a subcircuit are through the subcircuit's interface pins. As a result, signals inside a subcircuit are isolated from those in the parent circuit. Two signals may have the same name, but they are not connected unless linked through interface pins.

HYPERSIM uses a **hierarchical naming system** to uniquely identify objects. Global names are formed by combining the names of parent subcircuits with the local object name. For example:

* DEV1/Brk1 – device **Brk1** inside subcircuit **DEV1**
* DEV1/DEV2/XX1/power\_line – signal **power\_line** inside **XX1**, which is inside **DEV2**, which is inside **DEV1**

This naming convention ensures that every object in a design has a unique identifier.

### **Make Unique Type** <a href="#make-unique-type" id="make-unique-type"></a>

Because subcircuits of the same type share a common definition, any instance that needs to be modified independently must first be made unique using the **Make Unique Type** command in the **Part Type** section of the **Options** ribbon.

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

In the example below, **DEV2** is created by duplicating **DEV1** and then making it unique. Once detached, DEV2 has its own internal circuit and can be modified without affecting DEV1 or any other instances.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-079e7085c8ccde196d9a3ed3c554faa462baf256%2Fduplicate-add-unique.png?alt=media" alt="" width="311"><figcaption></figcaption></figure>

To avoid confusion when working with multiple subcircuit types, it is recommended to display the **Part** name or customize the subcircuit symbol using the **Symbol Editor**. HYPERSIM also maintains a **PartTemp** attribute to help detect unintended changes and verify subcircuit uniqueness.

Subcircuits imported from a library become automatically unique when modified. To clearly distinguish them from the original library version, consider assigning a new **Part** name and updating the symbol.

### **Lock and unlock subcircuits** <a href="#locking-and-unlocking-subcircuits" id="locking-and-unlocking-subcircuits"></a>

A subcircuit can be **locked** to prevent it from being opened or modified accidentally. This is particularly useful for subcircuits imported from libraries or for implementation details that should not be edited as part of the parent design.

To lock a subcircuit, select it, click **Properties** on the **Options** ribbon, and then enable the **Lock Opening Subcircuit** option.

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

### **Subcircuit properties** <a href="#subcircuit-properties" id="subcircuit-properties"></a>

Right-click the subcircuit to access its context menu, then select **Subcircuit Info..** to open the **Subcircuit Properties** dialog box.

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


---

# 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/create-manage-subcircuits.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.
