Generators

A generator draws a value each time a blueprint makes a record. This section has one page for each kind, with its keys, an example in YAML, Builder and Low-level, the records the example prints, and its JSON Schema.

What a Generator Is

A place that takes a value, such as a field of a task's payload or of an arrival's attributes, takes a constant or a generator. A generator is a mapping with a gen key that names its kind, such as {gen: integer, bounds: [1, 6]}. The tables of this section call such a place Value. YAML Keys calls the generator part of such a place Generator: a key that takes a generator, an integer or text is written Generator or integer or text.

Each generator draws from a random sequence of its own, named for the place it is written at. The same seed gives the same values. Adding a field to a mapping moves no other draw. Inserting an item into a list moves the draws of the items after it. The keys of every other part of a blueprint are on YAML Keys.

Choose a Kind

The sidebar groups the kinds by the sort of value they give:

• Random Numbers: Numbers and flags drawn from a range or a distribution.
• Choices: A value picked from a list you write.
• Text and IDs: Names, identifiers and text.
• Time: The simulation clock as text or numbers.
• Maths: Arithmetic on other values.
• Conditions: A value that depends on a condition or a case, or that is kept as written.
• Structure: Mappings and lists built from other generators.
• Model State: Values the model already holds: the entity, the task's vars and the registry.
• Related Records: Values from the records other tasks or earlier orders published, and from files.
• Python: A value from your own Python function, the one kind that runs !python.

Group	Kind	Use it for
Random Numbers	integer	A count or a quantity in which every whole number in the range is as likely as any other.
Random Numbers	uniform	A price or a size in which every value in the range is as likely as any other.
Random Numbers	normal	A measurement that clusters around a mean, such as a weight.
Random Numbers	sample	A duration or a size whose shape you know, such as exponential gaps, or one that follows the live distribution of a service.
Random Numbers	boolean	A flag that is true for a share of the orders, such as a gift.
Choices	one_of	One value out of a list, each equally likely, such as a colour.
Choices	weighted	One value out of a list in which some values are more likely, such as a region.
Choices	pick	Several different values out of a list, such as optional extras.
Text and IDs	fake	Names, addresses and other realistic text, when invented values are enough.
Text and IDs	uuid	A unique identifier, such as an order id.
Text and IDs	sequence	An order number or a label that counts up.
Text and IDs	format	Text built from parts, such as a label made of a region and a number.
Text and IDs	lower	A code or a label that must be in one standard case, whatever case it was drawn in.
Text and IDs	upper	A code or a label that must be in one standard case, whatever case it was drawn in.
Time	now	A time field of a record, with an offset when it is dated before or after the clock.
Time	format_time	A time in the form another system expects, such as epoch milliseconds or a local time zone.
Maths	add	A total, or a time that falls some seconds after another time.
Maths	subtract	A difference, or a time that falls some seconds before another time.
Maths	multiply	A cost, such as a quantity times a price.
Maths	divide	A ratio, such as a total divided by a count.
Maths	min	A cap: the smaller of a drawn value and a limit.
Maths	max	A floor: the larger of a drawn value and a minimum.
Conditions	when	A value that changes with one condition, such as a discount for a large order.
Conditions	switch	One value out of several, chosen by an exact match or by a range.
Conditions	expr	A value computed from vars and numbers by an expression.
Conditions	literal	A value that must be kept as written, even when it looks like a generator.
Structure	object	A nested record that is sometimes null or left out as a whole.
Structure	repeat	The items of an order: a list in which each item is drawn on its own.
Model State	attr	A value the entity has carried since it started, such as a size the arrival gave it.
Model State	var	A value drawn once for the task and used in several places.
Model State	param	A live setting of the simulation, which a scenario step or an ingress update can change.
Model State	entity	A payload field that names the entity the record belongs to.
Related Records	lookup	A value from a record that another task already published, such as an existing customer.
Related Records	previous	A value from the last finished record of the same task, such as the previous reading.
Related Records	upstream	A value from the record of the task that routed to this one.
Related Records	aggregate	A mean, sum, minimum, maximum or count over earlier records of another task.
Related Records	row	A whole row of a CSV or Parquet file, such as a product from a price list.
Python	call	A value that your own Python function computes.

Keys Every Kind Accepts

These four keys go on any kind.

Key	Type	Default	What it does
null_rate	number	none	The chance, from 0 to 1, that the value is null instead of a draw.
unique	boolean	false	When true, a draw that repeats an earlier value of this generator is drawn again, up to 1000 times, and the run stops with an error if no new value is found.
omit_rate	number	none	The chance, from 0 to 1, that the field of a mapping is left out.
omit_when	text	none	An expression. The field of a mapping is left out when it holds.

omit_rate and omit_when apply to a field of a mapping, such as a field of a payload. A blueprint that writes them on any other value is refused when it loads.

Run the Examples

Every example is a model in which an order starts every 60 seconds and the run lasts 200 seconds, so three orders start. The seed is 42 and factor is 0, so a run takes no wall-clock time and prints the same records each time. No example needs a service.

Each kind has three files in examples/generators/ of the repository: <kind>.yaml, <kind>_builder.py and <kind>_low_level.py. Run them from the repository's root folder:

desflow run examples/generators/integer.yaml
python examples/generators/integer_builder.py
python examples/generators/integer_low_level.py

fake needs the fake extra, which pip install "desflow[fake]" adds. row reads products.csv and call imports call_helpers.py, both in the same folder.