Autres pages › populations

Autres pages

Cette page n’est pas encore traduite : voici la version anglaise.

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 }
Diagramme : Depot
Ce qu’archec dessine depuis ce code : Depot
Essayer

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
  }
}
Diagramme : Depot
Ce qu’archec dessine depuis ce code : Depot
  • spawn every 15s adds 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 Delivered takes 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), so archec gen never 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 population does not repeat the run over many seeds, and a count written as a distribution is read at its mean. A study does not draw populations yet.
  • A test case's expect reads one part, not a population (population-test). A limit is the way to bound one.
  • archec why does 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-deployed warns where a deployment builds one. archec sim and 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 limit today, as on geometry and on a profile. If check becomes the one word for every bound, limit mean(robots.waited) <= 30s is check mean(robots.waited) <= 30s: the same aggregate, after and at end.