Running a custom simulator

Once someone in your workspace has published a simulator, running it is close to running a built-in one: you say what you want, you check a review card, you confirm, and a run appears in your history with plots and files attached. The differences are worth knowing, and they are all in the direction of caution — a custom simulator is experimental by construction, and the product never lets you forget which version produced a number.

If nothing is published yet, or you want to build one, start at Build your own simulator.

Only published versions can be run#

run_simulator reads published versions only. A draft can be exercised only by its author or a workspace admin, only through test_simulator_draft, and it never appears in the Custom tab or in the chat catalog. That is deliberate: an unpublished manifest can change between two calls, so a saved run against one would mean nothing later.

Find one#

Ask what exists:

What custom simulators does this workspace have?

That reaches list_available_simulators, which returns the published entries with their stable identifiers, current published versions, classification and trust status. It takes an optional query string that filters on slug, name, kind and description. It never returns another user's draft, and the agent is instructed to report only what the tool returned rather than inventing one from a saved preset.

Then read the one you care about before you run it:

Describe the carburizing profile simulator.

describe_simulator loads one exact version — the latest published unless you name one — and returns the input schema, the operator workflow, the declared outputs, the resource limits, the manifest digest and the authoritative trust status. Web chat renders it as a model card: Takes with units and ranges, Returns with units, Assumes, the workflow graph, and the three assurance rungs. Use it before relying on a custom simulator's meaning. A similar name does not make two versions equivalent.

Run it from chat#

Name the simulator and the values:

Run the carburizing profile simulator at 920 °C for 6 hours with a 5 mm depth.

The agent calls run_simulator with confirm_parameters=false. That first call starts no physics. It returns:

• the exact simulator, its slug and its immutable version number
• the manifest digest
• the trust status
• your complete inputs after unit conversion and bounds checks — every declared input, including the ones you did not mention and which took their default
• a confirmation phrase

The phrase has the shape:

CONFIRM CUSTOM SIMULATOR <slug> VERSION <n> CODE <16 hex characters>

You reply with exactly that phrase, on a later turn, and the agent repeats the identical call with the explicit version and confirm_parameters=true.

The receipt behind that phrase is one-use and bound to you, the workspace, the simulator, the version, the manifest digest and the input digest together. It refuses same-turn confirmation, changed inputs, a replayed phrase and a non-matching version — so a confirmed run can never quietly follow a moving "latest" pointer. If anything about the request changed, you get:

Run this exact simulator version and input set once with confirm_parameters=false, review it, then confirm without changing the inputs.

Over MCP the host's own approval prompt takes the place of the typed phrase. See Use Phases from an MCP client.

Web chat additionally needs durable sessions for this, because the receipt has to survive into a later turn. Where that is unavailable the tool refuses up front: Custom simulator execution requires durable cross-turn confirmation, which is not enabled for this workspace.

Accepted is not finished#

A confirmed run comes back as queued, running, waiting_for_operation or retrying. That is acceptance, not an answer.

The agent is instructed to say only that the durable run was accepted, and specifically not to infer a result from run history, recompute the formula itself, or reuse a validation-case value as the answer. Any number that appears in the prose before the execution card completes did not come from the simulator.

The custom simulator execution card owns the rest. It polls at the interval the backend asks for, shows the status and node-by-node progress, offers a Cancel run button while the run is still live, and renders the declared outputs when the backend reaches a terminal state. The terminal states are completed, failed, cancelled and expired; cancel_requested is what you see between pressing Cancel and the worker acknowledging it.

The run continues if you close the tab. See long-running simulations.

Run it from the Custom tab#

You do not have to type anything. When Studio is enabled, the simulator tab strip gains a Custom tab alongside HT Sim, CCT, RSW and V-Gleeble.

It lists the workspace's published simulators in a select. Choosing one shows the name, the version, the description, and — for an experimental simulator, which is all of them — the line "Experimental — review results before relying on them." Below that it builds an input form directly from the manifest's declared schema and seeds every field with the manifest's own default value.

Press Run simulator and it submits into chat for the same two-turn review. The tab says so itself: "Phases reviews these inputs in chat and asks you to confirm before anything runs." There is no path that skips the confirmation.

Three things the tab will tell you rather than hide:

• Outside a workspace: "Open a workspace to run its custom simulators."
• With nothing published: "This workspace has no published custom simulators yet," and a link to Simulator Studio.
• For a simulator still on the older manifest format: "This simulator uses the older manifest format. Ask Phases in chat to run it."

How inputs are declared and checked#

A simulator declares each input with a key, a label, a value type, an optional unit, optional minimum and maximum, an optional enumeration and an optional default. An input with a default is optional; a required input has no default.

The Custom tab renders a control for the types a person can type: material, enum, boolean, integer, number, quantity and string. Structured types — curves, tables, plots, history sets, reports — are produced by an upstream node, never typed into a field, and an unrecognised type fails safe to an unsupported control rather than collecting something the backend can only reject later. The form checks bounds and integer-ness locally so you get an immediate answer, but it is not the authority: the backend re-validates every value against the manifest before a run is admitted, and it is that normalized set which appears on the review card and which the confirmation receipt is bound to.

Materials follow the ordinary rules. A pinned heat-treatment or CCT node needs a grade with a base card and transformation kinetics, exactly as a direct call does — see the capability matrix. A manifest binds an explicit built-in grade; workspace-material revision binding is not available yet.

What comes back#

The execution card renders the declared outputs in the shapes the manifest declared them: a metric as a number with its unit, a line or scatter or bar output as a chart, a table output as a table.

Underneath that, a completed custom run is a first-class run. It reserves a run version on your session the same way a built-in simulation does, and it writes files into that run's own folder under session/<sessionId>/run_NNN/:

Every one of those files is a pure function of the verified result, so a retried completion reproduces identical bytes rather than a second copy. Because they land in an ordinary run folder, the Results tab, run history and downloads behave exactly as they do for a heat-treatment or CCT run. See sessions, runs and artifacts.

A generated Python package can also write its own artifacts through context.write_artifact. Those count against the manifest's artifact budget; the derived summary, CSV and PNG files do not.

Custom runs in run history#

Custom runs share the run numbering of the session they were created in — the next version is one more than the highest ever used, built-in runs included, so a run number always refers to exactly one execution.

List my runs.

Inspect run 7 and show me what it produced.

list_runs and inspect_run have no feature flag and are always available. A custom run records its simulator type as custom, and the interface labels it Custom rather than naming one of the four built-ins.

When you compare a custom run with anything else, quote the simulator version and the manifest digest from summary.json, not just the name. Two versions of one simulator are two different models. Reuse and share runs and compare and analyse runs cover the mechanics.

The budgets a run is held to#

These are the defaults a manifest starts from. A manifest can declare its own resource_policy, and the contract caps how far it may raise each one; the last two rows are fixed and cannot be raised at all.

Exceeding the artifact budget fails the run permanently with Custom simulator artifacts exceed the published limit. An equation result over its size cap names the fix in the error: declare fewer outputs, or for a transport model set history_positions and output_samples to report fewer positions and time levels.

A transport model still solves at full resolution and reports only the declared subset — with the minimum and maximum computed over the whole solve, so a coarse report cannot understate a peak the simulation reached.

When it does not work#

Common problems covers the messages shared with the built-in simulators, and reporting a problem covers what to send when none of the above fits.

What a result does and does not prove#

A custom simulator's trust status is experimental, and it stays there no matter how cleanly it runs. The version you ran passed a structural compile and finished once on its declared default inputs; that means the manifest is well formed and the graph computes something reproducible. It is not evidence that the physics is right, and nothing in the authoring loop can make it so.

The validation work described in how we validate, and the documented accuracy limits in known limits, apply to the four built-in simulators. They carry over to a custom simulator only for the parts of it that are a pinned built-in solver node — and not at all to the equations, transport model or generated code wrapped around them.

Where to go next#

• Build your own simulator for the authoring loop, the runtimes and the operator catalog
• Tool reference for list_available_simulators, describe_simulator and run_simulator parameters
• Sessions, runs and artifacts for where runs and files live
• Workspaces and roles for who can run and who can publish
• Glossary for the vocabulary used above