> 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/import-models-from-external-software-or-code/create-user-coded-models-ucm.md).

# Create User-Coded Models (UCM)

## Overview

The **User‑Coded Model (UCM)** feature is a HYPERSIM capability that allows users to create and integrate **custom models** that cannot be built using standard library components. UCMs are defined by user‑written C code following HYPERSIM‑specific rules and are compiled into native HYPERSIM components.

This mechanism enables users to model both **power and control behaviors**, while ensuring that the power part of the model is solved **directly within the network equations**, providing improved numerical stability and full compatibility with real‑time simulation.

UCM is designed to support both **offline and real‑time simulation workflows**, enabling advanced modeling and integration within large‑scale HYPERSIM simulations.

## When to use UCM

UCM is particularly well suited for:

* Modeling **custom or proprietary components**
* Implementing **advanced control algorithms tightly coupled with the network**
* Representing **nonlinear or dynamic behaviors** not supported by standard blocks
* Developing **high-fidelity real‑time models**
* Extending HYPERSIM with **user-defined functionality**

## Key capabilities

Using UCM, users can:

* Create **custom power system components** not available in the standard library
* Combine **power and control logic** within a single model
* Define both **linear and nonlinear behaviors**
* Integrate directly into the **network solution (nodal equations)**
* Use **tunable parameters** configurable from the HYPERSIM interface
* Implement advanced behaviors such as:
  * Iterative nonlinear models
  * Custom initialization and load flow participation
* Link **external C libraries** to reuse existing code

## Typical workflow

Creating and using a UCM in HYPERSIM generally follows these steps:

1. **Create a new UCM** ang build it using either a **text editor** or the **UCM Builder** interface
2. **Define the model structure** (parameters, nodes, control I/O, and simulation behavior) in the `.def` file
3. **Implement the model logic** using C code for:
   * Preparatory calculations
   * Simulation functions (before and after node voltage calculation)
4. **Update the UCM** in the HYPERSIM schematic to compile and validate the code
5. **Configure parameters and run the simulation**

Each step is documented in detail in the corresponding sections of this guide.


---

# 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/import-models-from-external-software-or-code/create-user-coded-models-ucm.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.
