Populations and fleets
Some answers do not come from one part. How long an order waits depends on
forty robots at once, each with its own battery and its own trips.
A population is a part whose number of instances a run decides, measured as a
whole. This page shows how, on the delivery robots of
examples/fleet.
Extension — not covered by the 1.0 stability promise (
population; the core)
A first population#
A population is written where a part is, with population in place of part
and how many there are:
component Robot "Delivery robot" {
var battery: float64 = uniform(50.0, 100.0) unit %
var delivered: int32 = 0
states {
state Idle "Idle"
state Delivering "Delivering"
Idle -> Delivering on "after uniform(10s, 30s)"
Delivering -> Idle on "after triangular(2min, 4min, 9min)" / delivered = delivered + 1
}
}
system Depot "Depot" {
population robots: Robot count 40
}
requirement REQ-WORK "The fleet works" { limit sum(robots.delivered) >= 400 at end }
simulation { model Depot; horizon 1h }Each of the 40 robots has its own variables, its own state and its own
mailbox. Robot is an ordinary component: nothing in it says it will be many.
$ archec population main.arche
population robots — Delivery robot: 40 × Robot in Depot, over 1h (seed 1, measured every 18s)
count 40 at the start, 40 at the end
in each state mean least most at the end
Idle 2.682 0 40 0 0%
Delivering 37.318 0 40 40 100%
across them, at the end mean min p50 p95 max sum highest mean
battery (%) 71.958 51.443 65.588 99.606 99.795 2878.313 71.958, at the start
delivered 10.9 9 11 13 13 436 10.9, 59min 42s in
✓ REQ-WORK sum(robots.delivered) at end 436 at the end; the limit is >= 400
A population and a repeated part#
part wheels: Wheel[4] and population robots: Robot count 40 both say
"several of these". They are not the same thing.
part wheels: Wheel[4] |
population robots: Robot count 40 |
|
|---|---|---|
| The number | is in the product: a car has four wheels | is a run's: 40 today, 25 to see what happens |
| Decided | when the model is built | when the run starts, and it changes during the run |
| In the Arche project | four components, wheels_0 … wheels_3, linked copy by copy |
one block |
| In a budget | counted four times | counted once |
In archec sim and archec test |
four parts, wheels[0] … wheels[3], each on its own and in the trace |
as many instances as there are, each on its own |
| In the generated code | one instance: a deployment that builds it is warned of (repeated-deployed) |
not built: see below |
| What you read | each copy's state and variables: wheels[2].state |
aggregates over all of them |
Each wheel is a part of its own: its own variables, state machine and mailbox,
and its number (0 … 3) in index when the component declares var index, as
an instance of a population has. A link names the copies the way it names a
population's instances, with a fixed number of them:
| Written | The message goes to |
|---|---|
ctl.all -> pads.cmd |
every copy (pads[*].cmd is the same) |
ctl.one -> pads[slot].cmd |
the copy whose number is the message's field slot |
ctl.test -> pads[3].cmd |
copy 3 |
pads.done -> ctl.back |
the one controller, from whichever copy sends |
wheels[*].can -> hubs[*].can |
copy i to copy i |
There is no pads[any]: a copy is a part of the product, not one drawn at
random. A message whose field names no copy is dropped, and the trace says so.
A test line reads and sends from one copy: expect pads[2].state == Busy,
do send pads[1].done DONE { slot: 1 }. The copy is a number, one
there is (pads[7] of four is an error, repeated-index), and what the line
reads is the copy's: a variable, a port, a part or its state (repeated-test).
The component that holds the copies does not read their variables: a body that
names pads[1].drone (or one.drone, a part not repeated) is an error that says
so. A part's variables are its own, whatever its owner, in every target: each
part runs in its own thread or on its own board in the generated code, and is a
component of its own in the Arche project. A copy tells its owner what the owner
needs through a port, saying which copy it is, and the owner keeps it:
component Pad {
var index: int32 = 0
out to_ctl: data sends PAD_FREE
fn on_takeoff() ```arche
send to_ctl PAD_FREE { pad: index }
```
}
component StationController {
const PADS = 4
part pads: Pad[PADS]
var pad_drone: int32[PADS] // who has each pad: what the pads said
pads.to_ctl -> free_in
in free_in: data receives PAD_FREE { handler PAD_FREE -> on_pad_free }
fn on_pad_free(pad: int32) ```arche
pad_drone[pad] = -1
```
}
archec sim traces each copy by its number:
100.000 ms ctl.all → pads[0].cmd CMD {"slot":0}
100.000 ms ctl.all → pads[1].cmd CMD {"slot":0}
…
3.100 s ctl.one → pads[2].cmd CMD {"slot":2}
3.100 s pads[2]: Idle → Busy
In the Arche project, ctl.one -> pads[slot].cmd is a link to each copy:
Arche's links do not pick a copy by a field, so every copy gets the message
there, and archec build warns of it.
Use T[N] for what the product is made of, and a population for what there
are many of around it or of it: a fleet, a crowd, customers, orders, packets.
How many#
| Written | A run starts with | It never holds more than |
|---|---|---|
count 40 |
40 | 40 |
count 40..80 |
40 | 80 |
count uniform(20, 60) |
40, the mean | 60 |
The count goes on the first line, or inside the block with the rest.
archec population --count robots=25 starts a run with another number, from 0
to the most it holds. That is how you find how many robots it takes.
Instances come and leave during the run:
system Depot "Depot" {
population orders: Order count 0..400 {
spawn every exponential(15s)
retire in Delivered
}
}spawn every 15sadds one instance each 15 s. Written as a distribution, the time to the next arrival is drawn each time.- An arrival that finds the population full is refused, and the report counts it.
retire in Deliveredtakes an instance out when it enters that state, after the state's on-enter. Nothing reaches it any more, and it is no longer counted.
Each instance is its own#
Every instance draws what the component writes as a distribution:
- a variable's start, once, when the instance is made:
var battery: float64 = uniform(50.0, 100.0); - a transition's
after, each time the instance enters the state:on "after triangular(2min, 4min, 9min)".
A single part reads the mean of both, as everywhere else. The generated code does too.
A variable named index, when the component has one, is the instance's
number: 0, 1, 2… in the order they are made. A number is never used twice.
An instance puts it in a message to say who is speaking.
The draws come from the run's seed (simulation { seed 7 }, or --seed), so
the same model gives the same run every time.
Messages#
A link's end at a population says which instances a message goes to:
| Written | The message goes to |
|---|---|
dispatch.all -> robots.stop |
every instance (robots[*].stop is the same) |
dispatch.jobs -> robots[any].job |
one instance, drawn at random |
dispatch.picked -> orders[order].news |
the instance whose number is the message's field order |
dispatch.test -> robots[3].job |
instance 3 |
robots.status -> dispatch.status |
the one dispatcher, from whichever instance sends |
A message to an instance that is not there is dropped. With the trace kept
(archec sim), the drop is in it.
Messages take the link's latency, as between two parts.
The fleet example uses all of it. An order asks the dispatcher for a robot. The dispatcher offers it to one robot at random. A robot that takes it says so, and the dispatcher tells that very order.
system Depot "Depot" {
part dispatch: Dispatcher
population robots: Robot count 40..80
population orders: Order count 0..400 {
spawn every exponential(15s)
retire in Delivered
}
orders.ask -> dispatch.orders
dispatch.jobs -> robots[any].job
robots.status -> dispatch.status
dispatch.picked -> orders[order].news
dispatch.done -> orders[order].news
}
Aggregates, and what bounds them#
A population is not read instance by instance. It is measured: every 1/200 of
the run, or every sample 10s.
| Written | What it is |
|---|---|
count(robots) |
how many instances there are |
count(robots.Charging) |
how many are in that state |
share(robots.Charging) |
the share of them in that state |
sum(robots.delivered) |
the variable added up over the instances |
mean(…), min(…), max(…) |
its mean, its lowest and its highest value |
median(…), p95(…) |
the value half of them, or 95 % of them, are under (p50 … p99) |
These are the words of a data app's metric, with share.
A population needs no declaration for them: archec population prints them
all, and a requirement bounds the ones that matter with limit.
requirement REQ-WAIT "Orders are picked up soon" {
text "95 % of the orders shall be picked up within 90 s."
limit p95(orders.waited) <= 90s
}
requirement REQ-CHARGE "Most robots work" {
text "No more than a third of the robots shall be charging at a time."
limit share(robots.Charging) <= 33% after 10min
}
requirement REQ-THROUGHPUT "A day's work in an hour" {
text "The fleet shall deliver 200 orders in the hour."
limit sum(robots.delivered) >= 200 at end
}
| Written after the bound | The limit holds when |
|---|---|
| nothing | every sample of the run is within it |
after 10min |
every sample from then on is |
at end |
the last one is |
A variable's bound is in the variable's unit (var waited: float64 unit s).
A time is converted to a time (<= 2min on seconds), and nothing else is.
An aggregate is taken over the instances that are there at that moment: one
that retired is no longer in the sum.
$ archec population main.arche
✓ REQ-WAIT p95(orders.waited) highest 33.5s, 39min 54s in; the limit is <= 90s
✓ REQ-BACKLOG count(orders.Waiting) highest 3, 35min 42s in; the limit is <= 15
✓ REQ-CHARGE share(robots.Charging) highest 12.5%, 51min 36s in; the limit is <= 33%
✓ REQ-THROUGHPUT sum(robots.delivered) at end 217 at the end; the limit is >= 200
$ archec population main.arche --count robots=25
✗ REQ-WAIT p95(orders.waited) highest 535.5s, 58min 12s in; the limit is <= 90s
✗ REQ-BACKLOG count(orders.Waiting) highest 18, 49min 12s in; the limit is <= 15
archec population records each limit, and archec status shows it with the
other evidence. Change the system, a component in it or the simulation's
settings, and the record is out of date.
$ archec status main.arche
REQ-WAIT Orders are picked up soon
✓ population p95(orders.waited) sim just now highest 33.5s, 39min 54s in; the limit is <= 90s (over 1h, 40 robots, 0 orders, seed 7)
The record is the model's own run: its horizon, its seed, its counts.
A run with --for, --count, --seed or --system prints its verdicts and
records nothing.
The command#
archec population [main.arche] [--for 1h] [--count robots=2000] [--seed N] [--system S] [--json] [--svg build/]
It runs the system that holds populations: the simulation's model when it
has some, else the first that does. The run lasts the simulation's horizon,
or 10 s when there is none.
--svg draws each population over the run: how many in each state, then each
variable's mean, lowest and highest. --json gives every sample.
archec sim runs the same system with its trace. The shared parts are in it
as usual, each message to a population once, and a line says how each
population stands at the end.
What the generators do#
A population is simulated and measured. It is not built: no generator writes code for a number of instances that a run decides.
- A deployment of a system that holds a population is an error
(
population-deployed), soarchec gennever meets one. - The component is built as any other. Put it in the product's system as a
part, and keep the fleet in a system of its own, as the example does. - In the Arche project a population is one block, with its links.
How fast#
The instances share one compiled part. The simulator keeps no trace of them, and waits on a heap of events. 3000 instances of a three-state machine for a simulated hour, about 190 000 trips and as many messages, took 2.6 s in node on a loaded laptop. 5000 took 4.3 s, and 20 000 took 24 s. The time grows with the count.
Limits#
- One run draws one story.
archec populationdoes not repeat the run over many seeds, and acountwritten as a distribution is read at its mean. A study does not draw populations yet. - A test case's
expectreads one part, not a population (population-test). A limit is the way to bound one. archec whydoes not explain an instance: instances leave no trace. What goes wrong in one is reported once, with how many times it happened.- An instance is one component. A component that holds parts, or an FPGA component, is not a population.
- Python bodies the action language cannot say do not run in
archec population: it starts no Python, and says so. - The Arche app shows a population as one block, and its simulator runs it as one part. It has no aggregates.
- A repeated part's copies are built as one instance by the generators (C,
C++, Rust, Go):
repeated-deployedwarns where a deployment builds one.archec simand Arche's simulator run every copy. - A bound's unit is the variable's. Only a time is converted to a time.
- A bound on an aggregate is a
limittoday, as on geometry and on a profile. Ifcheckbecomes the one word for every bound,limit mean(robots.waited) <= 30sischeck mean(robots.waited) <= 30s: the same aggregate,afterandat end.