Forking a run to try a what-if

"Exploring results" treated a finished run as something to look at. This page is about something you can do with it: pick a moment in the run, change a decision from that moment on and watch what would have happened instead, without losing the original.

That is a fork. A fork starts from the exact state the simulation was in at the moment you choose, so nothing before that moment is recomputed or changed. The original run stays exactly as it was. Together they form a small tree of branches that you can switch between and compare.

This page uses the Position Controlled Joint example from the Examples dialog. A controller drives a joint towards a target angle, the setpoint, which starts at 1.2 radians. The question for the fork is simple: what happens if the target changes halfway through the run?

Run the baseline first

Load the example and run it for 10 seconds. This is the run every fork will start from, called Baseline. Left alone, the joint swings towards 1.2 radians and settles there.

Choose the moment

Drag the timeline to the sample you want to branch from. Here that is 5 seconds, roughly halfway. Then open the Branches button at the right of the transport bar, which is labeled Baseline for now.

The menu offers Fork at 5 s. Every sample the run produced can be forked, not only the end, so you can branch from a moment in the middle of an event rather than only from the last result.

Change a decision

Choosing the fork opens a panel listing the model's live parameters: the ones marked as adjustable while a model runs, as the controller's setpoint is in this example. Each one has a slider, a value field and a transition.

The transition says how the change arrives. Step switches to the new value at the fork time. Ramp moves there over a duration you give, and Pulse applies the value for a duration and then returns to the old one. Here the setpoint steps from 1.2 to 0.4 radians.

You can change several parameters at once, or none. A fork with no changes is a way to re-run the second half with different numerics, covered next.

Continue the run

Continue opens the same run dialog as a normal run, headed "Fork from 5 s with parameter changes".

The target time says how far to run the branch. The numerics section lets the branch use its own global timestep and output interval. A branch can use a smaller timestep, for example, to check that a result holds up. The change applies only to that branch from the fork on, and the model's saved run configuration and the parent are untouched. Press Start and the branch runs from the 5 second state, offline or paced, like any other run.

Reading the tree

When the branch finishes, the button at the right shows its name and color, here Fork · 5 s in orange. Open it again for the tree.

The fork sits under Baseline in the tree, because that is the run it came from. You can fork a fork, which adds a level, or fork the baseline again at a different time or with a different change. Each branch keeps its own color everywhere it appears.

• Clicking a branch makes it the one you are looking at. The canvas, the node cards and the playback all show that branch.
• Ticking the boxes overlays further branches on the plots, so you can compare them at the same time.

Comparing branches

With both branches ticked, open any node and its Results tab. Every state is drawn once per branch, in the branch's color, and the legend names each line.

The two curves lie on top of each other until 5 seconds and then separate. That is the point of a fork: whatever differs afterwards is down to the one decision you changed, because everything before it is shared.

What to remember

• A fork is a branch of the same run, not a copy of the project. The parent is never changed.
• Any sample can be a fork point.
• A change arrives as a step, a ramp or a pulse, and applies on whichever execution backend the run uses.
• A branch can use its own timestep and output interval without changing the model.
• Branches are compared by ticking them in the Branches panel, and each keeps its color throughout.

From here, "Running a simulation" explains offline and paced runs, including Extend simulation, the other way to carry on from the end of a result.