Live Parameters: SimulationRegistry
Every parameter of a run can change while the run goes on: an arrival rate, a number of packers, a stock level. This page shows how to name a parameter, the ways to change it, how to record what a change was for, and what happens to a value once it arrives.
What It Is
Every run has one SimulationRegistry, at env.registry. It maps dot-notation paths, such as Shop.resources.packers.current_cap, to the values the simulation reads. A scenario, an ingress connector or a process changes a parameter by updating its path, and the simulation follows the change without restarting. Changing a parameter takes three steps:

The tutorial page Live Changes teaches these features step by step.
How to Use It
Find the Path
A path is the sim_id, the kind of parameter, its name and the field:
| Declared with | Paths |
|---|---|
| an arrival or a service | <sim_id>.arrival.<name>.<parameter> and <sim_id>.service.<name>.<parameter>, one per scalar parameter of its family: .rate for an exponential, .mean and .std for a normal, .low, .mode and .high for a triangular, and so on; an empirical has none |
| a resource | <sim_id>.resources.<name>.current_cap, .max_cap and .queue_limit (None while the resource has no limit) |
| a container | <sim_id>.containers.<name>.current_cap, .max_cap and .level |
| a store | <sim_id>.stores.<name>.current_cap and .max_cap |
| a breakdown of a resource | <sim_id>.breakdown.<resource>.time_to_failure.<parameter> and <sim_id>.breakdown.<resource>.repair.<parameter>, one per scalar parameter of each distribution's family, as for a service |
| a variable | <sim_id>.variables.<name> |
Arrivals and Services lists each family's parameters. An update to a path that does not exist, including a parameter the family does not take, is logged as a warning and ignored, so a misspelt path changes nothing.
A blueprint's paths follow from the names it declares, as the table above shows. To list them with their starting values, load it with SimulationContext.from_yaml and call registry_paths() on the context it returns, as the Builder tab does.
compile_parameters() returns the SimParameter a SimulationContext will register, which shows the names to use. A resource appears in it as a ResourceConfig with current_cap, max_cap and queue_limit:
| docs/snippets/pages/live_parameters.py:compile | |
|---|---|
registry_paths() returns the paths a run will register with their starting values, in the order a run registers them. It runs no model code and starts no connector. A capacity with no limit has the value math.inf, which JSON cannot hold, so convert it before you write JSON:
| docs/snippets/pages/live_parameters.py:paths | |
|---|---|
You register the parameters yourself, and read a value with registry.get(path).value:
Send a Value
Each source of a change suits a different job and lands at a different moment:
| Source | Use it for | Lands at |
|---|---|---|
a scenario: YAML scenario, builder add_scenario, low-level run_scenario |
an experiment that must repeat exactly | the exact simulation time given |
LocalIngress |
a local run with changes after set wall-clock delays | a wall-clock delay from the start |
FileIngress |
a local run steered by editing a file | within one poll of the save |
KafkaIngress, RedisIngress, PostgresIngress |
an operator or another program steering a running model | when the message arrives |
a process calling env.registry.update or env.registry.change |
a change that depends on the state of the simulation | when the process makes it |

Ingress gives the message each connector reads. A process changes a value directly:
A blueprint's process function, listed under processes, calls the same registry.update on context.env.registry, as Processes shows.
A builder process calls the same registry.update on context.env.registry, as Processes shows.
Know What a Path Accepts
Each path checks a value by its own rule before it stores it:
- A resource's or a store's
max_cap, and a resource'squeue_limit, are whole numbers of 0 or more, and acurrent_capis a whole number, stored clamped to 0 tomax_capwith a warning. Text is accepted only if the whole text is such a number, so"6"is 6 and"abc"is refused. A store capacity with a fraction, such as 2.5, is refused and not rounded down. Aqueue_limitofNonemeans no limit. - A container's
levelis a finite number. A level above the capacity is stored as the capacity. - A path that holds true or false takes
true,falseor that text. Any other text is refused.truewritten over a path that holds a number is stored as 1.
A resource's limit changes through its path. DynamicResource.queue_limit is a read-only property that shows the value now, so assigning to it raises AttributeError.
An on: entry with a path needs a value, and so does a scenario step with a path. A value that the path's rule refuses, such as many for a capacity, is refused when the blueprint loads, with the line of the entry. A path that is not in the registry is logged as a warning with the entry's line.
registry.change, which a process calls, raises ParamRejected for a value that breaks these rules. The next section shows it.
Know Whether a Change Was Refused
update logs a refused value and goes on, so its caller cannot tell whether the value landed. registry.change(path, value) runs the same checks and returns a ParamChange for an accepted value. For a refused value it raises ParamRejected, a ValueError whose path, value and reason say what the registry refused. A value that the registry converts or clamps is accepted, and new shows the value it stored.
A ParamChange has these fields:
path: the path that changed.old: the value before the change.new: the value stored.requested: the value asked for.at: the simulation time of the change.source,actorandreason: who made the change and why, whichchangetakes as keywords.
Its changed property is True when new differs from old.
A blueprint's process function, listed under processes, calls the same registry.change on context.env.registry, as Processes shows for update.
A builder process calls the same registry.change on context.env.registry, as Processes shows for update.
Follow Every Change
on_change is a list of callbacks. The registry calls each one with the ParamChange of every accepted change, in the order they were added, after it has stored the value. A change that leaves the value as it was is reported too, with changed False. A lower max_cap that lowers the current_cap beside it gives two changes, the current_cap first. A callback that raises is logged, and the other callbacks still run.
The source and actor of a change say where it came from:
- An ingress connector's change has the source
"ingress"and the connector's class name as actor, such asLocalIngress. - A scenario step has the source
"scenario". - The overrides of
start()have thesource,actorandreasonthatstart()takes. - A change that a process or an
on:action makes has no source unless the process passes one.
The context that SimulationContext.from_yaml returns takes the callbacks on context.on_change.
app.on_change takes the same callbacks for every run start() builds, as Builder API says.
| docs/snippets/pages/registry.py:on_change | |
|---|---|
Script an Experiment
A blueprint's scenario lists changes, each with the simulation time it applies at. Here a second packer starts at 30 seconds. From one minute, orders arrive twice as fast: the average gap between orders falls from 5 seconds to 2.5 seconds (rate from 0.2 to 0.4). The extra packer leaves at two minutes:
add_scenario takes the same steps as a list of mappings, as Vary Arrivals by Time shows.
run_scenario takes the same steps as a list of mappings, and runs as a SimPy process, as Vary Arrivals by Time shows.
The builder and the low-level API take the same steps, as a list of mappings. Vary Arrivals by Time shows one schedule in each API.
A scenario is not a connector. It is a SimPy process that waits on the simulation clock, so each step lands at exactly its at, on every run and at any factor, including 0. Its steps follow these rules, and Vary Arrivals by Time shows each case:
- A step applies before every other event at its time, so an arrival gap drawn at that moment uses the new value.
- Steps at the same time apply in the order written.
- A step at or after
untilnever applies. - A scenario's paths and values are checked before the run, as Stability and Limits says.
LocalIngress waits on the wall clock instead, and an unknown path is only logged when it is due. A scenario and an ingress connector can run together, so a scripted baseline can run while an operator changes values over Kafka. When both change the same path, the later write wins.
Record What a Change Was For
A detector or an agent that watches the data is scored against what really happened. A scenario step with a record publishes a ground-truth record of it: stream_type: "label", with the step's path, the value before (old) and after (new), and the step's record mapping as label. A step can have a record and no path, for something that happened outside the model, and then path, old and new are null.
| docs/snippets/yaml/ground_truth.yaml:record | |
|---|---|
add_scenario takes the same steps, record included. A process publishes a label itself with context.env.publish_label(label, path=..., old=..., new=...).
run_scenario takes the same steps, record included. A process publishes a label itself with env.publish_label(label, path=..., old=..., new=...).
Labels go only to sinks with when: labels, and those sinks receive nothing else. The labels therefore never reach the pipeline under test, and a scorer reads them apart from the data. Choose What Each Sink Gets shows the sinks of this blueprint.

The labels sink writes one file per batch under labels/, such as labels/labels_1a2b3c4d.jsonl, with one line per label:
In Python, env.publish_label(label, path=..., old=..., new=...) publishes one, and add_egress(sink, when="labels") or setup_egress(..., labels=[...]) makes a labels sink, as the measuring example shows.
How It Works
Registration. run(), or register_sim_parameter in the low-level API, flattens the SimParameter into the registry. The registry holds one DynamicValue per path, with the value and a change signal. Beside them, it keeps the configuration objects that the paths belong to, such as each DistributionConfig.
An update. registry.update(path, value) and registry.change(path, value) apply one change by the same checks. update logs a refused value, and change raises ParamRejected. The checks run in order, and an accepted value reaches the parts that read it:

- A path that does not exist is logged as a warning, and the update is ignored.
- A value of another type is converted to the type the path holds, so the string
"5"sent to an integer path becomes 5. Python's conversion is used, so 2.5 sent to an integer path becomes 2. A value that cannot be converted is logged as an error and ignored. - A distribution parameter is checked on a copy of its configuration, by the rules used at build. One out of range is logged as an error, and the old value stays.
- A
current_capoutside 0 tomax_cap, or a containerleveloutside 0 tocurrent_cap, is stored clamped to that range, with a warning. A lowermax_capclamps the storedcurrent_capthe same way. - A value equal to the current one gives no change signal.
- Otherwise the value is stored, and the attribute of the configuration object is set too, found by splitting the path at its last dot:
Shop.service.packing.meansetsmeanon the object atShop.service.packing. TheSamplerreads that object at every draw, so it sees the new value. - Then each
on_changecallback receives the change, in the order they were added; a callback that raises is logged and the others still run.
Change Signal. Each value has a SimPy Store with one slot as its signal. An update puts a token in it if it is empty, and wait_for_change() waits for that token. The slot holds one token, so several changes before a waiter wakes give one signal, and only one waiting process takes it. Resources, stores and containers already wait on their own paths, and a token that your process takes does not reach them. Wait only on paths that nothing else waits on, such as variables:
A container's level also changes with every put and get. The registry keeps that level, so a reader sees it, but does not signal the container again.
Under Live Changes
What follows a change:
- Distributions. The next draw uses the new value. The arrival already being waited for keeps its gap, and a task that has drawn its service time keeps it.
- Resources, stores and containers. The capacity follows at once, and a container's level follows its path, as Resources and Stores and Containers describe.
- Variables. The new value is stored, and a process reads it with
env.registry.get(path).value.
A change is easiest to see in the telemetry. With stats: minimal, the scenario above shows the second packer land:
The reading at 30 seconds still shows 1. The resource applies a change within the same simulation instant, but after the step that made it. The reading was taken before that. The builder publishes the same readings with with_stats:
stats: minimal in the blueprint above publishes these readings every 10 seconds.
env.setup_stats("Shop", "minimal", interval=2.0) publishes the same readings, as Statistics shows.
Stability and Limits
- An unknown path is a warning, not an error, for an ingress message or a process that calls
update;changeraisesParamRejected. The paths of a scenario and of everyon:action, and a scenario's values, are checked when the model loads. - A scenario's values are checked before the run. Every path and value of a blueprint's scenario is checked against the model's registry when the file loads, so a misspelt path, a path on a family member the family can never have (
desk[7]of a family withmembers: 2that no task picks bykey), or a refused value stops the load with its line. A member that a task can make at its first use is accepted, and a step on it before it is made ends the run withKeyError.start()checks them again with its overrides, and that is where a builder model's scenario is checked. A run still stops withParamRejectedat a step's time when an ingress message, anon:action or a process has changed a related value before the step, because the check cannot know those values. A low-levelrun_scenariochecks nothing in advance, so it raisesParamRejectedwhenever it reaches a refused value. - A family is fixed. There is no path that turns a
normalinto anexponential. That is a new model. - Several changes, one signal. A process waiting on a path wakes once for several changes made before it runs, and reads the latest value.
- Ingress lands on the wall clock. A message's change lands at whatever simulation time the run has reached when it arrives. A change that must happen at an exact simulation time needs a scenario step.