Optimization

Optimization is a search question put to the Digital Twin: across many combinations of input variables, which combination moves a target metric the most in the desired direction?

Unlike a prediction, which estimates the outcome of one specified input, or an intervention, which forces a chosen set of variables to values you specify and reports the downstream effect, an optimization explores a space. You name the objective and the levers the optimizer may pull; it returns the best combination it can find.

For the workflow that produces a Digital Twin in the first place, see Step 5: Build Digital Twin.

---

Starting a simulation

Open a Digital Twin from the Digital Twins list, open its Simulations row (or click Run Simulation in the toolbar), then click New Simulation. This opens the type picker — choose Optimization.

The New Simulation screen. Each type opens its own setup form.

The setup form has three numbered sections plus a configuration summary at the foot. Only the first two — the objective and at least one decision variable — are required; constraints are optional and can be skipped on a first pass.

---

Objective and decision variables

Two ideas drive every optimization.

The objective. The metric the optimizer will push in one direction — Maximize TotalCharges, Minimize Churn, Maximize NPS. The direction matters: maximize and minimize are different searches.

The decision variables. The levers the optimizer may pull on the way to the objective. A handful of well-chosen levers produces a recommendation a business can act on; selecting every variable invites combinations no operator would ever apply.

The example below minimizes the customer churn rate with three levers as decision variables: Contract, OnlineSecurity, and TechSupport.

---

Step 1: Optimization objectives

An objective has a Goal (Maximize or Minimize), an Objective name, a Unit, and a SQL expression for the metric. On a temporal twin it also takes a time preference.

The metric can be specified three ways, matching the metric builder used elsewhere in the product: Natural Language describes it in plain English and lets the system generate the SQL; Builder offers aggregation and column pickers for standard metrics; SQL writes the query by hand.

Natural Language. Describe the metric in plain English, say the share of customers who churn, and Generate SQL writes the query.

SQL. Test SQL confirms the baseline before the run: here, the current churn rate is 0.241.

The result of Test SQL is the baseline against which all improvements are measured. + Add objective stacks a second objective, in which case the optimizer returns a frontier of plans trading the two off against each other, and the plan table gains a delta column per objective. (The SDK and REST paths accept a per-objective weight; the wizard does not expose one.)

---

Step 2: Decision variables

A scrollable list of every variable in the twin, with a checkbox against each one. Tick the levers the optimizer is allowed to change; selections appear as chips below the list so the chosen set is visible at a glance.

Anything left unchecked is held at its current distribution. That is useful for pinning demographics or contract terms while letting the optimizer play with product offerings.

---

Step 3 (optional): Constraints

Three sections narrow the search space, all optional.

Variable constraints bound an individual decision variable — PhoneService can only be set to Yes, or MonthlyCharges must stay between 30 and 100. Auto Generate Constraints asks the model to suggest sensible bounds based on the variables you picked; the suggestions can be edited manually before the run.

Metric constraints set rules the optimizer must respect even at the cost of a weaker objective — average Churn must stay below 0.1, Electronic check share of PaymentMethod must not rise. They are how you encode trade-offs the objective alone cannot express.

Plan size caps how many variables a single plan may change, through Max changes per plan; leave it empty for no limit.

The example below uses none of the three — the optimizer is free to explore the unconstrained search space.

---

Configuration Summary

The card at the foot of the form mirrors back the run in plain English, with the version of the twin the simulation will run against.

The completed configuration. The summary mirrors the run back in plain English: Minimize Customer churn rate by adjusting Contract, OnlineSecurity, and TechSupport, with both constraint sections left empty. Validate checks the setup; Run Simulation launches the search.

---

Reading the result

A completed run carries a green Completed pill and the actions Create app and Edit Config; its duration is shown on the run's row in the list. The plan table has its own button to export the plans as CSV or JSON. To get a PDF, tick the run in the list, click Export 1 as report, and use Export PDF in the report editor.

The result leads with an eyebrow naming the plan you are looking at, whether it is the recommended one, how many plans were found, and the constraint verdict, then a deterministic headline sentence stating the recommendation.

A completed run. The eyebrow names the plan and the constraint verdict; the headline sentence states the recommendation; the chart sits beside the details panel.

Below that, the result is laid out as a chart beside a details panel, with the causal subgraph underneath and the plan table last.

• The chart and details panel report the selected objective baseline versus optimized, with the absolute and percentage change.

• The causal subgraph shows the paths from the variables the plan moves to the objective.

• All plans · best first on the first objective is the table of every candidate the search produced. Its columns are Plan, Changes, and one delta column per objective ("vs today"); the baseline is an italic Today / no changes row at the top. The chosen plan carries a Recommended badge, and a plan that breaks a constraint is marked as such. Useful for comparing runner-up strategies — a slightly worse-scoring plan sometimes involves fewer or cheaper changes. On a run with two or more objectives a frontier chart is drawn beside the table; with a single objective the table fills the width.

---

Past simulations

Past runs appear in the twin's run list, which the Simulations row on the twin's Home opens. The workflow is the same as for any other simulation type — see Prediction › Past simulations.

---

Outside the UI

This simulation runs from the Python SDK and from the REST API, with the same configuration the wizard collects.

>>> twin.optimise([rc.objective("Churn share", sql, "minimise")], decision_vars=["Contract"])

Over REST it is a scenario on POST /api/v1/workspaces/{workspaceId}/simulations with "type": "optimisation", or temporal_optimisation / panel_optimisation. Note the field value is spelled optimisation, whichever way the UI labels it. A temporal optimization also needs a horizon.

See Working with Digital Twins for the SDK, and Running Simulations over REST for the request body.

---

Other Simulation Types

• Prediction — predict an outcome for a specific input.

• Intervention — change a single variable and observe propagation.

• Best Action — find the minimum change needed to reach a target outcome.

• Explanation — understand the drivers and impacts behind an outcome.

• Root Cause Analysis — diagnose the cause of a specific abnormal value.

• Anomaly Scan & Diagnosis — scan every variable for anomalies and diagnose each one.

See Step 6: Run Simulations — general overview.