Build your own simulator

The four built-in simulators answer four questions. A carburizing depth profile, a Jominy end-quench, a laser-hardening pass, a cooling-rate sweep fed into a transformation diagram are all combinations of physics Phases already owns — and until Simulator Studio there was no way to name one, keep it, and hand it to a colleague.

A custom simulator is that name. It declares its own inputs with units and ranges, a typed workflow of steps, and named outputs, and it runs through operators the server owns rather than through anything the manifest brings with it. It is composition and bounded modelling, not new physics.

Simulator Studio is on for every workspace by default. Once a simulator is published, running it works from chat or from the Custom tab in the simulator strip.

Ask for it in chat#

There is no empty draft to create first and no form to fill in. You describe the problem:

Build me a simulator that computes the carbon profile through a 5 mm case after carburizing at 920 °C.

Phases answers with a design card and then stops. The card states the goal, the approach and the governing equations, the intended inputs and outputs with units and ranges, the workflow steps, the assumptions it intends to make, and — required for the design to be reviewable at all — what the model will deliberately not represent. It also lists any open questions it wants answered.

That design writes nothing, pins no operator and compiles nothing. It exists so the physics can be corrected while correcting it is still free. Correcting it after publication costs a new immutable version and a second admin approval, so read the "will not represent" list before you say yes.

The six steps#

The build always follows the same order, and the agent is instructed to stop and report between the steps rather than racing to publication.

Parameters for each are in the tool reference. You never call them yourself; you approve or correct what the agent shows you between steps.

Two habits pay for themselves. Ask for a corner sweep (corner_cases) before you approve publication: it evaluates the draft at the low, middle and high corners of its own declared input ranges, and a model that ignores an input returns the same number three times. And read the returned assumptions rather than the summary — a placeholder is invisible in a manifest and obvious in a sweep.

Start from a worked example#

Four starter templates ship with the product, and the agent will seed a draft from one when it fits. They are chosen to cover the ways a step can own its result, not to be a gallery. Every one of them is compiled against the live operator catalog in CI, so an operator signature change breaks the template rather than a user mid-build.

Starting from a template creates an ordinary owned draft with a fresh slug. Nothing about it is published, trusted or validated; each carries its own assumptions and the same experimental trust every authored simulator gets.

What a step can actually compute#

Four runtimes, and knowing which one produced a number tells you how much of the answer is Phases and how much is your manifest.

Existing Phases solvers. A node can pin heat treatment, CCT, V-Gleeble or flow stress and run it as a durable child with the same material, run and artifact policy a direct call gets. Good for anything the built-in simulators already model and for reusing calibrated kinetics rather than restating them. Not for RSW, which is not in the catalog, or for physics none of the four owns.

Restricted equations and ODEs. Algebraic expressions and bounded RK4 integration, evaluated in process against your declared inputs. The available functions are abs, acos, asin, atan, ceil, clip, cos, cosh, exp, floor, log, log10, maximum, minimum, round, sin, sinh, sqrt, tan, tanh and where, plus the constants pi and e, comparisons and conditional expressions. Good for closed-form correlations, lumped models such as Newton cooling, unit conversions and derived quantities. Not for spatial gradients or anything needing a mesh.

The Phases 1D transport solver. A conservative implicit finite-volume solver in slab, cylindrical or spherical coordinates, with state-dependent properties, sources, and Dirichlet, Neumann or Robin boundaries. Good for through-thickness conduction, carbon diffusion for carburizing, and depth profiles feeding pinned heat-treatment nodes. In the product's own words, this is not a general FEM solver: no 2D or 3D geometry, no moving mesh.

A generated Python package. A solver.py defining run(inputs, context), checked statically against an import allowlist, stored content-addressed by SHA-256, and executed by a fixed SDK inside a rootless, network-disabled sandbox. Good for bounded vectorised work the other runtimes cannot express. Not for anything needing network, subprocesses, dynamic imports, filesystem discovery or secrets — and available only where the deployment has a sandbox runtime. Where it does not, Phases refuses with one curated message naming the equation runtime to use instead rather than failing obscurely. Passing the static security checks is explicitly not scientific evidence.

This is the last resort, not the default. The agent is instructed to use generated code only when the catalog and the equation runtime cannot express the physics.

The operator catalog#

A published simulator can reach exactly nine server-owned operators, plus whatever equation and sandbox operators its own manifest declares. The boundary is enforced by the server, not by the manifest.

The native solver nodes carry the ordinary material rules, not a reduced set: a 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.

Limits that will not move#

These six are stated by the platform itself, and each names the supported alternative where one exists.

• No general-purpose FEM or CFD. The transport runtime is conservative and one-dimensional. Full 2D or 3D physics needs a separately validated generated package or a future Phases-owned operator.
• No runtime-sized map or fan-out. A graph is statically bounded. Expand a published number of locations as explicit nodes, or do the bounded vectorised work inside one generated package.
• No external solvers. OpenFOAM, CalculiX and LS-DYNA are outside this direction. A material .k file is an immutable solver input, not a workflow language.
• RSW is not in the operator catalog. Its mandatory review contract must first be expanded into a complete canonical configuration that can be shown and bound during preview. Use the RSW simulator directly.
• No network, shell, uploaded binaries or secrets. Nothing authored here reaches outside the sandbox, in any runtime.
• Publication is not validation. Compiling proves the manifest's shape. Passing declared examples proves they run. Neither is evidence that the physics is right.

Size and time budgets#

One non-obvious guarantee sits behind the transport numbers. The solver marches every node and every step at full resolution and only reports the declared subset of positions and time levels — but the minimum and maximum are still computed over the full solve, so a coarse report can never understate a peak the simulation actually reached. Both endpoints are always kept.

What "validated" means here#

The word was doing three different jobs, so the product now states three things that are true or false independently.

• Compiles — the manifest is well formed and every operator resolves. Says nothing about the physics. The product's own sentence: "Compiling proves the manifest's shape, not that the physics is right."
• Runs its own cases — its declared deterministic cases were executed and matched. "Passing declared cases proves the model is reproducible, not calibrated or applicable."
• Has reviewed evidence — someone compared it against reference data and recorded that review.

Only the third rung is about being correct, and nothing the agent does can raise it. No caller in the product supplies a verified evidence record today, so that rung is never green. A workspace-authored simulator sits on rung two, its trust status is experimental, and that is the normal, correct state — not a gap you are expected to close.

A manifest can also declare its own evidence_level. Nothing guards that field, so if it says experimentally_validated the product reports it as the author's own claim that nothing has verified, never as a reached rung.

The validation described in how we validate and the limits in known limits cover the built-in simulators. They say nothing about anything a workspace authored.

Publication, and the test that gates it#

A compile is not enough. Every V2 manifest must declare a complete default_inputs set — one valid value for every declared input, no more and no fewer — and the whole graph must finish once with exactly those inputs before the version can become published.

This is stricter than it sounds. A small validation example can pass while the real defaults blow a declared output bound, which is how published simulators have failed on their first real run. The check is enforced by a database trigger against the version, the manifest digest and the input digest together, so a stale or alternate input set cannot authorise publication and the agent cannot talk its way past it. The refusal reads simulator_default_test_required.

Publishing itself is a workspace admin action and takes two turns. The first call returns a review card bound to the exact simulator, version and manifest digest, with a phrase of the form:

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

Only an exact reply of that phrase on a later turn completes it. Changed drafts, same-turn approval, replayed approval and non-admin callers all fail closed. Publication makes an immutable version available to the workspace and changes nothing about trust.

Versions are immutable#

Published bytes never change. Editing after publication allocates the next version, and an already published version keeps running exactly as published even after a newer one exists — so the meaning of a saved run cannot drift underneath it.

The practical consequence: when you compare two runs of "the same" simulator, compare their version numbers and manifest digests. A similar name does not make two versions equivalent. Studio has a side-by-side version comparison for exactly this.

Deprecating retires a published version and is an admin action. Deleting is separate, irreversible and deliberately awkward: the dialog shows what would go (manifest versions, saved runs, run artifacts and their byte count, generated code bundles), requires the simulator's own slug typed by hand, is refused while any execution is still running, lets an authoring member remove only their own never-published draft, and needs a separate explicit opt-in before it discards saved run history and the chat messages that referenced it.

The model card#

Asking Phases to describe a simulator, or opening one in Studio, gives you a model card rather than a manifest dump: the name, the version, the trust status and lifecycle status, the description, the workflow graph, Takes (each input with its unit and declared range), Returns (each output with its unit), Assumes (the manifest's stated assumptions), and the three assurance rungs with their caveats spelled out.

Describe the carburizing profile simulator before I run it.

One honest detail in that card: when the description is read without loading the stored validation receipts, the "Runs its own cases" rung reports unknown rather than not reached, and tells you to open it in Studio to see its validation runs. "Nobody told me" and "it did not happen" are different claims.

When you write up a result from a custom simulator, name the simulator, the exact version, its trust status, the runtime the number came from, the declared assumptions, and the list of things the design said it would not represent.

Where Simulator Studio lives#

Simulator Studio appears in the workspace sidebar when the feature is enabled, at /ws/<slug>/simulators. It is a card grid with a search box, lifecycle filter chips carrying counts (All, My drafts, In review, Published, Retired), last-updated times and nine cards per page. In review is the admin's queue and appears only for admins; Retired appears only once something has been deprecated. Selecting a card replaces the grid with the full detail and editing surface behind an All simulators back link, with an Edit alongside chat toggle.

Studio is where you inspect, compare versions, edit in detail, publish, deprecate and delete. It is not where you start: its Create custom simulator button opens a chat prefilled for a new request, because designing one is a conversation.

Who can do what#

A draft is visible only to its author, and to admins for review — the In review filter is the admin's queue. Because every signed-in user is the admin of their own personal workspace, a solo user can complete the whole loop alone; in a shared organization workspace, publishing is deliberately a second person's decision. See workspaces and roles.

You need a workspace and a signed-in membership. Outside one, the tools refuse with A workspace is required to use custom simulators. or An authenticated workspace member is required.

If you do not see it#

Simulator Studio is a workspace capability. An organization admin can turn the group off under Settings → Feature flags, and the sidebar item and the Custom tab disappear with it. The group holds five switches:

feature.simulator_studio itself depends on feature.persistent_adk_sessions, because the one-use confirmation receipt has to survive into a later chat turn. Without it, both running and publishing refuse rather than accepting an unconfirmed action. See workspace limits and features.

Where to go next#

• Running a custom simulator for the run loop, the Custom tab and the result files
• Tool reference for every authoring tool's parameters
• How the conversation works for why the agent stops before anything expensive
• Capability matrix for what a pinned solver node needs from a grade
• Glossary for the vocabulary used above