> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/more-details/applications/application-modules/optimisationsim.md).

# Optimisation

> Find optimal variable settings for a target outcome.

Searches a digital twin for the lever settings that best hit a target, inside the constraints given.

Durable and long-running: it is many twin runs behind one node, so it is measured in twin evaluations rather than in a single call. `results` is the Pareto front it found, one row per plan: `plan` carries the run page's label (`P1`, `P2`, ...), `recommended` is true on the plan the run page badges Recommended, and each lever has a column with the setting that plan chooses. Filter `results` on `recommended` to get the Recommended plan.

## At a glance

|                          |                        |
| ------------------------ | ---------------------- |
| Module type              | `OptimisationSim`      |
| Category                 | Intelligence           |
| Default tier             | `durable`              |
| Runs on                  | `reactive`, `durable`  |
| Starts a flow            | no                     |
| Holds a body             | no                     |
| Keeps state between runs | no                     |
| Available in             | every application type |

## Parameters

### `digitalTwinId`

`string` · required · defaults to `""`

The twin to run against.

### `digitalTwinName`

`string` · optional

Its name when it was chosen, for the node's label.

### `digitalTwinVersionIds`

`string[]` · optional

Pin the run to specific twin versions; empty means the latest.

### `scenario`

`Record<string, unknown>` · optional

The saved scenario. Anything arriving on the `scenario` port is merged over this.

### `scenarioDraft`

`Record<string, unknown>` · optional

What the inspector is editing, before it is applied to `scenario`.

### `scenarioValidationErrors`

`string[]` · optional

What was wrong with the draft the last time it was checked.

### `entityColumns`

`object` · optional · defaults to `{"id":null,"target":null,"constraints":null,"levers":null}`

Which columns of the `entities` frame carry what: `id` the environment id, and `target`, `constraints` and `levers` the optional per-row overrides. Any may be null.

## Inputs

| Port       | Kind        | Required | Description                                                                                                                           |
| ---------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `on`       | `event`     | no       | Implicit on every module that does not itself start a flow: wire an event here to make this module the start of what that event runs. |
| `scenario` | `json`      | no       | The objective, the levers to move and the bounds on them, per run.                                                                    |
| `entities` | `dataframe` | no       | One row per environment to optimise; `entityColumns` maps its columns.                                                                |
| `baseline` | `dataframe` | no       | Rows to optimise from; unconnected, the twin's own baseline is used.                                                                  |

## Outputs

| Port      | Kind        | Connects to                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------- | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `results` | `dataframe` | `dataframe`, `signal`      | One row per Pareto solution: `solution` (its position in the front), `plan` (its run page label, such as `P23`), `recommended` (true on the Recommended plan), a column per objective, a column per lever holding the setting the plan chooses (suffixed `_recommended` when the name is taken), `n_interventions`, and the plan's notes. `plan` and `recommended` take a `_plan` suffix when an objective or lever already has that name. |
| `summary` | `json`      | `json`, `scalar`, `signal` | The run's identity, not its findings: `{runId, status, outputs}`, where `outputs` is the simulator's raw per-version result. The numbers a reader wants are in `results`.                                                                                                                                                                                                                                                                  |

***

[← All application modules](/more-details/applications/application-modules.md)