Skip to content

Command Line

The desflow command runs a model without a line of Python, and also checks it, compares designs, fits measured times and converts a distribution's parameters. This page uses each command in the order a study uses it, on one shop, and says what each output tells you.


What It Is

desflow is installed with the package: uv tool install desflow, or pip install desflow. Each task is a command of its own, such as desflow run or desflow explain. desflow on its own lists them by task, with examples. The --help of each command, such as desflow run --help, lists its options and ends with examples of that command. Each command below links to a page with its full help:

Command What it does
desflow run Build the simulation in FILE and run it, or run replications of it.
desflow check Check that each blueprint or builder file in FILE... builds, without running it.
desflow test Run the tests of each file in FILE... and report the statistics that differ.
desflow explain Show the model in SOURCE as a graph, with its utilisation, status, waits and tuning hints where the queueing formulas apply, and why where they do not.
desflow experiment Run the experiment in FILE and write its artifacts and report.
desflow report Build the report of an experiment again from the artifacts in FOLDER.
desflow fit Fit a column of FILE to the distribution families, and exit 1 if none is usable.
desflow dist List the distribution families, or convert parameters to a mean and std and back.
desflow schema Print the blueprint JSON Schema.
desflow examples List the examples, or download one at the version you have installed.
desflow examples list List the examples, with what each shows and what it needs.
desflow examples get Download an example into <dest>/<name>/<api>/, at the installed release.
The help of desflow
Usage: desflow [OPTIONS] COMMAND [ARGS]...

  Run, explain and analyse desflow simulations, fit their inputs, and download
  the examples.

Options:
  --version  Print the installed version and exit.
  --help     Show this message and exit.

Commands:
  run         Build the simulation in FILE and run it, or run replications...
  check       Check that each blueprint or builder file in FILE...
  test        Run the tests of each file in FILE...
  explain     Show the model in SOURCE as a graph, with its utilisation,...
  experiment  Run the experiment in FILE and write its artifacts and report.
  report      Build the report of an experiment again from the artifacts in...
  fit         Fit a column of FILE to the distribution families, and exit 1...
  dist        List the distribution families, or convert parameters to a...
  schema      Print the blueprint JSON Schema.
  examples    List the examples, or download one at the version you have...

  Examples:

    # Run a blueprint, sending its records to its sinks

    $ desflow run shop.yaml

    # Print the first five events, with no services

    $ desflow run shop.yaml --sample 5

    # Find the bottleneck before running

    $ desflow explain shop.yaml

    # List the examples, then download one

    $ desflow examples list

    $ desflow examples get local

The shop on this page is the model of the experiment example: two packers, an order every 2.5 seconds on average, and 4 seconds of packing on average. Every command runs in one folder and needs no Docker service. desflow fit needs the fit extra: uv tool install "desflow[fit]", or pip install "desflow[fit]".


How to Use It

Get an Example

desflow --version prints the release you installed. desflow examples list, or desflow examples alone, lists every example with the service it needs, such as (no service) or (odctl up kafka-lite):

1
2
3
desflow --version
desflow examples list
desflow examples

desflow examples get downloads one example at the release you installed, into a folder named after it:

desflow examples get experiment --api yaml
1
2
3
4
5
6
wrote experiment/yaml/experiment.yaml
wrote experiment/yaml/experiment_shop.yaml
wrote experiment/observed_waits.csv

Find the bottleneck, with no run: cd experiment/yaml && desflow explain experiment_shop.yaml
Run the yaml version: cd experiment/yaml && desflow experiment experiment.yaml

The model is experiment_shop.yaml, and experiment.yaml is the experiment that compares two designs of it. observed_waits.csv holds the mean wait measured in the real shop. The line before the last runs desflow explain on the model, and the last line is the command that runs the example from its own folder. --api builder or --api low-level downloads the same example in Python.

--dest downloads into another folder, and --ref downloads from another tag or branch, such as main for an example added after your release:

desflow examples get experiment --api builder --dest shop --ref main
1
2
3
4
wrote shop/experiment/builder/experiment_example.py
wrote shop/experiment/observed_waits.csv

Run the builder version: cd shop/experiment/builder && python experiment_example.py

The builder version goes under shop/experiment/builder, and the last line runs it from there. A file that is already there stops the download before anything is written, and --force replaces it instead. This line downloads the YAML version again, over the files of the first download, and prints the same lines as the first download:

desflow examples get experiment --api yaml --force

Check a File Before You Run It

desflow check builds each blueprint or builder file you give it, and does not run it. It reports what desflow run reports before the clock starts: YAML errors, unknown keys, missing names, unset variables, !python references that cannot be imported, and connectors whose extra is missing or whose settings are refused. It does not call run.before, contact a broker, a database or a catalog, or run a !python function. Importing a !python module runs its top-level code, as desflow run does. It prints ok FILE (sim_id ID) for each valid file and every error of an invalid one, and exits 1 if any file is invalid.

The commands below use a small shop in a file of its own. Its packers come from the variable PACKERS, 2 when it is not set, and it holds one test. Save it as shop.yaml:

docs/snippets/yaml/command_line_shop.yaml
# A small shop for the commands of the Command Line page that need a file with a
# variable and a test. The packers come from PACKERS, 2 when it is not set.
# Run it with: desflow run shop.yaml --sample 5
simulation: {sim_id: Shop, factor: 0, random_seed: 42}

resources:
  packers: {current_cap: "${PACKERS:-2}", max_cap: 5}

services:
  packing: {dist: gamma, shape: 4, scale: 1 s}

arrivals:
  orders: {dist: exponential, rate: 0.4, spawn: pack}

tasks:
  pack:
    service: packing
    resource: packers
    payload: {event_type: order_packed}

stats: basic

run: {until: 10 min}

# desflow test runs the model once at the seed and compares these statistics
tests:
  - name: two packers
    expect:
      tasks.pack.finished: 224
      tasks.pack.wait_mean: {value: 2.299, within: 0.001}

A builder file has no ${PACKERS} variable and no test section: its values are Python. desflow check and desflow run take a builder file too, and Test a Model shows how to test one with pytest.

A low-level script is not a file the command reads. Run it with python, and test it with pytest as Test a Model shows.

desflow check takes more than one file, and --var NAME=VALUE fills ${NAME} in the files and in the files they include, before the environment does. Repeat --var for more variables:

desflow check shop.yaml
desflow check shop.yaml experiment/yaml/experiment_shop.yaml --var PACKERS=3

It also warns about a run with no end: an arrival with a dist or a gap and no max_events, in a file with no run.until, run.stop or run.segments. The experiment's shop gives no until, because the experiment file gives it, so check warns about it and still prints ok. A tests entry with no seed, in a file with no seed of its own, is reported as desflow test reports it.

desflow ships no pre-commit hook. A repository that keeps its blueprints in a folder can add its own to .pre-commit-config.yaml. pre-commit passes the changed files as the arguments, which check takes:

.pre-commit-config.yaml
1
2
3
4
5
6
7
8
repos:
  - repo: local
    hooks:
      - id: desflow-check
        name: desflow check
        entry: desflow check
        language: system
        files: ^models/.*\.ya?ml$

desflow test runs the tests that a file holds under tests. A test names a seed, an end time and the statistics its run must give. It runs the model once, unpaced, with no ingress and no egress, so a test contacts no service. It prints ok for each passing test and each difference of a failing one, and exits 1 if any test fails. A file with no tests prints no tests. A builder file reads its tests from a tests.yaml in its folder. --fix writes the measured statistics into the values that differ, and into a test with none, in place of reporting the differences. A statistic the run published as NaN cannot be written, so --fix reports that test as failed. Read the changes before you keep them, because a test states its numbers at one seed of one desflow version. Test a Model writes tests step by step.

desflow test shop.yaml
desflow test shop.yaml --fix --var PACKERS=2

Check It Before a Long Run

desflow explain reads the model without running it. It draws the model as a graph and works out each resource's utilisation, the share of its units that the arrivals keep busy. SOURCE is a blueprint, a builder Python file with a module-level SimulationContext, or a URI such as s3://bucket/sims/shop.yaml. A URI that ends in a folder is refused with its name, such as Error: no file s3://bucket/models/.

desflow explain experiment/yaml/experiment_shop.yaml

desflow explain on the experiment's shop: the graph of orders, pack and packers, the resources table with utilisation 0.8, the table of 1 to 4 packers and the hints

The same output as text:

Shop
`-- orders (arrival, rate 0.4/s)
    `-- spawn -> pack (task, rate 0.4/s)
        +-- uses packers (resource)
        `-- next (share 1) -> exit
Resources
+---------------------------------------------------+
| resource |   λ |    μ | c |   ρ | Wq | L | status |
|----------+-----+------+---+-----+----+---+--------|
| packers  | 0.4 | 0.25 | 2 | 0.8 |  - | - | OK     |
+---------------------------------------------------+
packers by units
+-----------------------+
| c |      ρ | status   |
|---+--------+----------|
| 1 |    1.6 | UNSTABLE |
| 2 |    0.8 | OK       |
| 3 | 0.5333 | OK       |
| 4 |    0.4 | OK       |
+-----------------------+
Bottleneck: packers
Not estimated:
  wait at packers: no closed formula for c > 1 with non-exponential times; run --verify to measure it
Hints for utilisation 0.85:
  packers with 2 units: utilisation 0.8, at most 0.85
  packers with 2 units: utilisation 0.85 at a request every 2.35 seconds (25.5 a minute, 0.425 a second)

The packers are at utilisation 0.8: they are busy 80% of the time. An order arrives every 2.5 seconds on average (24 a minute, rate 0.4/s in the graph). Each order needs 4 seconds of a packer, and 2 packers share the work. The resources table names its columns with the usual queueing symbols:

  • λ (lambda) is the arrival rate, 0.4 orders a second.
  • μ (mu) is the rate one packer serves, 0.25 orders a second (4 seconds each).
  • ρ (rho) is the utilisation.
  • Wq is the mean wait in the queue, and L the mean number of orders in the shop. Both show - when no formula applies.

The line Bottleneck: packers names the resource with the highest utilisation. Relieving it makes the next busiest resource the bottleneck. The status is OK below 0.85, CONGESTED from 0.85 and UNSTABLE from 1, where the queue grows for as long as the run lasts. The table by units shows that one packer would be UNSTABLE. The hints give the units and the arrival rate that reach the target of 0.85. A hint of more units than the resource's max_cap also says to raise max_cap, because a current_cap above max_cap is lowered to it.

To keep a resource stable, lower its utilisation or its variability: more units (a higher current_cap), a shorter service time, a lower arrival rate, or less variable gaps or service times. To test how a consumer of the records copes, do the opposite on purpose. From utilisation 0.85 a resource is congested, with long waits that come and go. Above 1 it is overloaded and its queue grows for as long as the overload lasts.

--target sets the utilisation the hints aim for, 0.85 by default. At 1 or above the hints are for deliberate overload. This command uses the shop of Queues and Capacity, saved as queues_and_capacity.yaml:

desflow explain queues_and_capacity.yaml --target 1.2

The end of the output is the hints:

1
2
3
Hints for utilisation 1.2:
  packers with 2 units: utilisation 1.35, at least 1.2, for deliberate overload
  packers with 1 unit: utilisation 1.2 at a request every 1.25 seconds (48 a minute, 0.8 a second)

With 2 packers the shop runs at utilisation 1.35, above the target of 1.2. With 1 packer, an arrival rate of 0.8 orders a second (an order every 1.25 seconds, 48 a minute) gives exactly 1.2.

The formulas give no wait for two packers with gamma packing times, so the line under Not estimated says to measure it. Queues and Capacity works the same numbers out by hand.

--verify measures it. It runs the model unpaced and compares each statistic with the analysis, as Check Against Theory shows. With --replications, it runs the model that many times from --seed, each to --until, and compares with each measure's 95% interval. --target sets the utilisation the hints aim for:

# Ten one-hour runs compared with the analysis, and hints for utilisation 0.9
desflow explain experiment/yaml/experiment_shop.yaml --verify --replications 10 --seed 42 --until 1h --target 0.9
Shop
`-- orders (arrival, rate 0.4/s)
    `-- spawn -> pack (task, rate 0.4/s)
        +-- uses packers (resource)
        `-- next (share 1) -> exit
Resources
+---------------------------------------------------+
| resource |   λ |    μ | c |   ρ | Wq | L | status |
|----------+-----+------+---+-----+----+---+--------|
| packers  | 0.4 | 0.25 | 2 | 0.8 |  - | - | OK     |
+---------------------------------------------------+
packers by units
+-----------------------+
| c |      ρ | status   |
|---+--------+----------|
| 1 |    1.6 | UNSTABLE |
| 2 |    0.8 | OK       |
| 3 | 0.5333 | OK       |
| 4 |    0.4 | OK       |
+-----------------------+
Bottleneck: packers
Not estimated:
  wait at packers: no closed formula for c > 1 with non-exponential times
Hints for utilisation 0.9:
  packers with 2 units: utilisation 0.8, at most 0.9
  packers with 2 units: utilisation 0.9 at a request every 2.22 seconds (27 a minute, 0.45 a second)
Verify: 10 runs to 3600 s, seed 42
+------------------------------------------------------------------------+
| node    | measure      | analysis | measured |        ± | result       |
|---------+--------------+----------+----------+----------+--------------|
| packers | utilization  |      0.8 |   0.8017 |  0.01893 | agrees       |
| packers | queue_length |        - |    1.753 |   0.2404 | not compared |
| pack    | wait         |        - |    4.354 |   0.5143 | not compared |
| orders  | throughput   |      0.4 |   0.3992 | 0.009612 | agrees       |
+------------------------------------------------------------------------+
Not compared:
  packers queue_length: no closed formula for c > 1 with non-exponential times
  pack wait: no closed formula for c > 1 with non-exponential times
--verify checks the implementation against the queueing analysis where it applies; it does not show that the model is close enough to the real system

The measured utilisation of 0.8017 and throughput of 0.3992 agree with the analysis, so the model does what the formulas say. The wait has no formula here, so the runs only measure it: 4.354 seconds. With a target of 0.9, the hints say that two packers reach it at an order every 2.22 seconds. --json prints the same explanation as one JSON object, for a script to read. Its schema_version names the shape, which the Explanation class describes:

desflow explain experiment/yaml/experiment_shop.yaml --json > explain.json

Run It

desflow run --sample prints the first events as JSON lines. It runs the model unpaced, with no ingress, and with no sinks of the file's own, so a model that writes to Kafka or a database needs no service:

desflow run experiment/yaml/experiment_shop.yaml --sample 5
1
2
3
4
5
{"stream_type":"event","sim_ts":0.7853891641174294,"timestamp":"...","key":"orders-1","task":"pack","instance":0,"value":{"path_id":"Shop.service.packing","sim_id":"Shop","service":"packing","status":"queued"}}
{"stream_type":"event","sim_ts":0.7853891641174294,"timestamp":"...","key":"orders-1","task":"pack","instance":0,"value":{"path_id":"Shop.service.packing","sim_id":"Shop","service":"packing","status":"started"}}
{"stream_type":"event","sim_ts":4.186525464662821,"timestamp":"...","key":"orders-1","task":"pack","instance":0,"value":{"event_type":"order_packed"}}
{"stream_type":"event","sim_ts":6.1679236265239235,"timestamp":"...","key":"orders-2","task":"pack","instance":1,"value":{"path_id":"Shop.service.packing","sim_id":"Shop","service":"packing","status":"queued"}}
{"stream_type":"event","sim_ts":6.1679236265239235,"timestamp":"...","key":"orders-2","task":"pack","instance":1,"value":{"path_id":"Shop.service.packing","sim_id":"Shop","service":"packing","status":"started"}}

Each order publishes queued when it joins the packers' queue and started when a packer takes it. The first two orders find a packer free, so each starts at the moment it queues. Without --sample, desflow run runs the model with its own settings and sinks. A model that runs out of events before the sample is full ends with exit 0 and the records it made.

--var NAME=VALUE fills ${NAME} in the file and in the files it includes, before the environment does, and check and test take it too. explain and experiment do not take --var. --watch runs the file in a child process and runs it again whenever the file, or a .py file beside it, changes, so a change to a blueprint shows its first events at once. It needs the watch extra: pip install "desflow[watch]". Press Ctrl+C to stop it:

desflow run shop.yaml --var PACKERS=3 --sample 5
desflow run shop.yaml --sample 5 --watch

One run is one sample, so measure the wait with replications: the same model with ten seeds, each run for one hour:

desflow run experiment/yaml/experiment_shop.yaml --replications 10 --seed 42 --until 1h
measure                                n          mean    half-width (95%)
resources.packers.capacity            10             2                   0
resources.packers.in_use              10           1.9              0.2262
resources.packers.queue_length        10           3.9               2.298
resources.packers.utilization         10            95               11.31
resources.packers.utilization_avg     10         80.17               1.893
resources.packers.queue_length_avg    10         1.753              0.2404
tasks.pack.in_progress                10           5.8               2.404
tasks.pack.finished                   10          1437                34.6
tasks.pack.wait_mean                  10         4.354              0.5143
tasks.pack.wait_max                   10         28.17               3.833
tasks.pack.service_mean               10         4.013             0.03767
tasks.pack.service_max                10         15.15               1.292
flows.orders.finished                 10          1437                34.6
flows.orders.started                  10          1443               33.77
flows.orders.in_system                10           5.8               2.404

Seed 42; replication seeds: 2684470948, 4091952314, 233227757, 3276785861, 3644269654, 1206282609, 3543069911, 3479688010, 877132087, 1244265337
Repeat one replication with: desflow run experiment/yaml/experiment_shop.yaml --seed <its seed> --until 1h

The mean wait is 4.354 seconds, and its half-width of 0.5143 says that the true mean lies within about 0.51 seconds of it, with 95% confidence. The packers are busy 80.17% of the time, close to the 0.8 that explain worked out. The last line repeats any one replication, with its events. This shop has no sinks. A model with a sink, such as type: Console, also sends the result to it as telemetry: one reading for each replication and measure. A Console sink therefore prints those lines before the table, as What the Sinks Receive explains.

--measure names a statistic to summarise, and repeats for more. --level sets the confidence level of the intervals. --workers runs that many replications at once, each in its own process, and gives the same results, because each replication keeps its seed. The three apply to --replications, and desflow run refuses them without it:

# Two statistics at a 99% level, two replications at a time
desflow run experiment/yaml/experiment_shop.yaml --replications 10 --seed 42 --until 1h --measure tasks.pack.wait_mean --measure resources.packers.utilization_avg --level 0.99 --workers 2
1
2
3
4
5
6
measure                               n          mean    half-width (99%)
tasks.pack.wait_mean                 10         4.354              0.7389
resources.packers.utilization_avg    10         80.17                2.72

Seed 42; replication seeds: 2684470948, 4091952314, 233227757, 3276785861, 3644269654, 1206282609, 3543069911, 3479688010, 877132087, 1244265337
Repeat one replication with: desflow run experiment/yaml/experiment_shop.yaml --seed <its seed> --until 1h

The means are the same as before. At 99%, the half-width of the mean wait grows from 0.5143 to 0.7389 seconds, because more confidence needs a wider interval.

--stdout prints the run's records as JSON lines, instead of writing to the file's sinks. The run keeps its ingress connectors, so a KafkaIngress still applies its topic_policy: it creates the control topic, and with drop_and_create it deletes it and creates it again. --drain stops the arrivals at the end time and runs on until every order has left. This run stops the arrivals at 20 seconds, and its last record is the seventh order packed, at 20.502310430365075 seconds. A record keeps its time unrounded:

# Every record of a 20-second run that drains, as JSON lines in a file
desflow run experiment/yaml/experiment_shop.yaml --seed 42 --until 20 --drain --stdout > records.jsonl

Compare Designs

desflow experiment runs an experiment: here two packers against three, 20 replications of each with the same seeds, with a check that three packers keep the mean wait under 2 seconds. --output names the folder for its files, here results/packers in the current folder. Without it, they go to the folder the file's output names, beside the file:

desflow experiment experiment/yaml/experiment.yaml --output results/packers
Wrote the artifacts and report.md to results/packers
passed: three: tasks.pack.wait_mean max 2, checked 0.5816

The check passed: the upper end of the interval of the mean wait with three packers is 0.5816 seconds, under the bound of 2. The command exits with status 1 when a check fails, so a CI job that runs it fails too. The six files in results/packers hold every value, and report.md compares the designs, as Experiment Results describes. After editing experiment.json by hand, desflow report builds the report again from the files, without running anything:

desflow report results/packers
Wrote results/packers/report.md

Fit Measured Times

A packing time in a model comes from measured times. The fitting example holds 40 packing times measured at a bench, for a shop of its own, and desflow fit fits every family of times to them:

desflow examples get fitting --api yaml
desflow fit fitting/packing_times.csv --column packing_seconds --lower 0
40 rows: 40 used, 0 missing, 0 invalid
family            status              AIC  KS stat KS p (approx.)  parameters or reason
exponential       rejected                                         its std is 1.5, the data's is 0.4832: more than 25% apart
normal            fitted            59.33    0.157         0.2504  mean=1.5, std=0.483218 (can draw below the lower bound 0)
lognormal         fitted            57.33  0.09406         0.8385  mean=1.50251, std=0.511854
truncated_normal  fitted            59.25   0.1558         0.2579  mean=1.49836, std=0.48579, low=0
constant          skipped                                          the values are not all equal
uniform           fitted            59.45    0.225        0.02923  low=0.7, high=2.7
triangular *      fitted            56.68   0.1258          0.511  low=0.546332, mode=1.2, high=2.83766
gamma             fitted            56.79   0.1157         0.6165  shape=9.55777, scale=0.15694
weibull           fitted            58.99   0.1502         0.2972  shape=3.33522, scale=1.67203
empirical         fitted                                           values: 40 numbers
* best: triangular

The first line counts the values. Each row is one family: fitted with its AIC, where lower is better, or the reason it was not fitted. The triangular has the lowest AIC, 56.68, and the gamma is within 0.11 of it, so the data cannot tell the two apart. Fitting the Inputs checks what the choice changes.

The other options shape the fit, as Input Fitting describes:

  • --unit names the data's unit, ms, s, min or h, and the settings are written in seconds.
  • --upper is the highest plausible value, and a family that can draw above it is marked.
  • --candidates names the families to try. The default is every family that fits times, ten of them. poisson and geometric count whole numbers, so a fit does not try them, and named in --candidates they are skipped with the reason that they count whole numbers.
  • --bins offers the empirical distribution as a histogram with that many bins.
  • --min-count is the fewest values a family is fitted to.
  • --tolerance is how far a fitted mean and standard deviation may be from the data's, as a share of the data's. A tolerance that is negative or NaN, and a bound that is NaN, are refused, and so is a name in --candidates that is not a family, which the refusal quotes.
  • --drop-invalid leaves out values that are not numbers or lie outside the bounds, instead of stopping.
  • --out writes the best fit as YAML that a blueprint includes, and --plot draws the data against it as a PNG.
# Three families, a histogram of 8 bins, and the best fit written for the blueprint
desflow fit fitting/packing_times.csv --column packing_seconds --unit s --lower 0 --upper 10 --candidates triangular,gamma,empirical --bins 8 --min-count 30 --tolerance 0.2 --drop-invalid --out fitting/yaml/packing_fit.yaml --plot packing_fit.png
1
2
3
4
5
6
7
8
40 rows: 40 used, 0 missing, 0 invalid
family            status              AIC  KS stat KS p (approx.)  parameters or reason
triangular *      fitted            56.68   0.1258          0.511  low=0.546332, mode=1.2, high=2.83766
gamma             fitted            56.79   0.1157         0.6165  shape=9.55777, scale=0.15694 (can draw above the upper bound 10)
empirical         fitted                                           edges: 9 numbers, counts: 8 numbers
* best: triangular
Wrote fitting/yaml/packing_fit.yaml
Wrote packing_fit.png

The empirical row is now a histogram of 8 bins, and the gamma row is marked because a gamma can draw above 10 seconds. fitting/yaml/packing_fit.yaml is the file the fitting example's blueprint includes, so fitting/yaml/fitting.yaml now draws its packing times from this triangular.

Convert Parameters

A gamma takes a shape and a scale, not a mean and a standard deviation. desflow dist converts the measured times' mean of 1.5 seconds and standard deviation of 0.4832 seconds into them:

desflow dist gamma --mean 1.5 --std 0.4832
1
2
3
4
5
6
parameters: shape 9.63671, scale 0.155655
mean 1.5, std 0.4832
variability: low (std / mean 0.322)
with no random generator, every draw is 1.5
YAML: {dist: gamma, shape: 9.63671, scale: 0.155655}
Python: dist="gamma", shape=9.63671, scale=0.155655

The shape and scale are close to the gamma that desflow fit found from the 40 values. The last two lines are the service in a blueprint and in the builder.

Given a family's own parameters, desflow dist converts the other way. Each of these lines prints the family's mean and standard deviation, as in the output above, for each kind of parameter: a rate, a constant's value, a low and a high, and a shape and a scale:

1
2
3
4
desflow dist exponential --rate 0.4
desflow dist constant --value 4
desflow dist uniform --low 0.7 --high 2.7
desflow dist gamma --shape 9.63671 --scale 0.155655

The shop's arrivals, rate: 0.4, are 2.5 seconds apart on average. A triangular also takes a mode, its most likely value. The one desflow fit found has a mean of 1.53 seconds, close to the measured 1.5:

desflow dist triangular --low 0.55 --mode 1.2 --high 2.84
1
2
3
4
5
6
parameters: low 0.55, mode 1.2, high 2.84
mean 1.53, std 0.481785
variability: low (std / mean 0.315)
with no random generator, every draw is 1.53
YAML: {dist: triangular, low: 0.55, mode: 1.2, high: 2.84}
Python: dist="triangular", low=0.55, mode=1.2, high=2.84

poisson takes --mean, and geometric takes --p, the chance of success on each try. Both give whole numbers:

desflow dist geometric --p 0.25

desflow dist alone prints a table of every family with its parameters and a one-line summary, and Choosing Inputs explains the variability line:

desflow dist

Set Up an Editor

desflow schema prints the JSON Schema of a blueprint, for the release you installed. An editor that reads it offers the keys as you type and marks a misspelt one:

desflow schema > blueprint.schema.json

Set Up Your Editor names the file in the editor's settings.


How It Works

Each command reads its file and calls the library function a Python script would call. desflow run loads the model with load_context and runs it once, or calls replicate when --replications is given. desflow experiment calls run_experiment, desflow report calls write_report, and desflow fit reads the column and calls fit_column. desflow dist, desflow schema and desflow examples read the distribution table, the blueprint schema and the list of examples. A command therefore gives the same result as the Python call with the same arguments.

desflow explain takes the most steps. Look at them in order:

desflow explain loads the model, builds the graph from what the model declares, works out each task's rate by flow balance, marks the tasks the formulas do not cover, then gives each resource its utilisation, status and wait by Kingman's formula or Erlang C, and names the bottleneck and the hints. --verify runs the model unpaced with no ingress or egress and compares utilisation, queue length, wait and throughput with the analysis, within 10% for one run, or for replications within the 95% interval's half-width or 1%, whichever is larger

Graph. explain builds the graph from what the model declares: its arrivals, tasks, resources, stores, containers and next shares. It builds and runs nothing. Code the model does not declare, such as a hand-written arrival loop or an add_process function, becomes an opaque node. The graph also has an edge with no share from a task to each task it starts by an on: or listen spawn, a task branch of wait, open or subscribe, a spawn in the on: of a signal it fires, and on_interrupt_next and on_interrupt_run. next weights, fixed or computed, end no flow.

Rates. Each task's arrival rate comes from flow balance: the rate from its arrivals plus the share of each task that sends work to it. A next function or a hand-written arrival loop makes the rates unknown, because the graph cannot see where the work goes. A task reached by an edge with no share has no rate either, with the reason "how often starts it is not known before a run" or "the split after depends on the run".

Coverage. The formulas hold for a plain network of queues:

  • Each task holds at most one resource.
  • Each queue serves in arrival order, fifo or lifo, which give the same mean wait.
  • Nothing blocks, removes, delays or reorders work by priority.

Anything else marks tasks, and the rate of a marked task is unknown. These mark tasks:

  • A task feature, such as put, patience, fail, a service_time (computed service time) or an interrupt that names the task (interruptions (an interrupt names it)), marks that task and every task after it.
  • An arrival feature gives the arrival no rate, so the tasks it starts have none: a gap (computed gaps), a count, keys, a key that can repeat or max_events (limited or repeated arrivals), a group other than 1, and active: false. A spawn count other than 1 is a feature too.
  • A resource feature, such as queue_limit, breakdowns, a capacity that an on: entry sets, a resource family, or a resource picked by key or lowest, marks the tasks that use it and every task after them.
  • A router with a weight that is an expression ends no flow and has no shares.
  • A priority queue whose tasks have different priorities marks every task after its tasks. The resource keeps its utilisation but has no wait.
  • An unstable resource marks every task after its tasks. The resource keeps its status.
  • A scenario step, an on: entry that sets an arrival or a service, live ingress or an add_process function marks every arrival and every task.

A resource used by a marked task has no supported utilisation, status or wait, and the output names the reason under Not estimated.

Waits. The utilisation ρ is λ ÷ (c × μ): the arrival rate divided by the units times the rate one unit serves. The status follows from it. The wait depends on the units and the input:

  • With no unit limit, the wait is 0.
  • At one unit, the wait comes from Kingman's formula. It is exact when the input is Poisson, and an approximation when one arrival with other gaps feeds the resource's only task.
  • At more than one unit, the wait comes from Erlang C, which needs Poisson arrivals and one exponential service time shared by every task that uses the resource.
  • With any other input or times there is no wait, and the output says to run --verify.

Little's law then gives the queue length and the number in the system. The bottleneck is the resource with the highest supported utilisation. The hints solve the utilisation alone for the units and the arrival rate that reach --target.

Verify. --verify runs the model as one replication does: unpaced, with no ingress or egress, and with the typical statistics. It measures from the end of the warm-up to --until, or to the blueprint's run.until when --until is not given. It compares four measures with the analysis: each resource's utilisation and queue length, the wait of each task that holds one resource, and each arrival's throughput. A measure agrees with the analysis:

  • For one run, when it is within 10% of the analysis, or measures 0 where the analysis gives 0.
  • For replications, when it is within the 95% interval's half-width or 1%, whichever is larger.

A measure is not compared in these cases:

  • The analysis has no value for it.
  • Its resource is unstable.
  • Its wait comes from Kingman's formula as an approximation.
  • For a throughput, the arrival starts no task the graph shows, its flow passes a marked task or an unstable resource, or the blueprint has a run.stop that can end a run before until.

Stability and Limits

  • Inputs are files. run reads a blueprint, or a builder file with --sample (not with --stdout, --var or --watch), check a blueprint or a builder file, test a blueprint or a builder file with a tests.yaml, explain a blueprint or a builder file with a module-level SimulationContext, experiment an experiment file, and fit a CSV file. For a Python model, use replicate and run_experiment, as Replications shows.
  • Examples need the network. examples get downloads from GitHub at the installed release's tag. --ref picks another tag or branch.
  • explain --json is experimental. Its shape can change in 1.x, and schema_version changes with it.
  • Exit statuses: 0 on success, 1 on a failure, 2 on a usage error.
    • 1: run, check, test or explain cannot load the file, a test differs from the measured statistics, an experiment check fails (its files are still written), fit finds no usable family, or dist has no formula from a mean and a standard deviation for the family.
    • 2: a missing file, an option value that is not valid such as --until abc, a value that is not a number in a fit column, or an experiment file that is not valid.