Model file format (generated)

Current schema version: 29 (nagasim/core/schema/migrate.py). See Model file format for the full field-by-field guide; this page is the generated top-level key list. naga schema prints the whole JSON Schema; a file saved by an older version is migrated forward when it is read.

Top-level keys

Key	Meaning
blocks	Every block in the model: name, type, position (centre, scene units), params.
resources	Named resources: capacity, queue discipline, optional ranking expression, capacity schedule, cost fields.
links	Ordered list of {source, target, delay?, source_port?, target_port?}; array order is branch order, and several links may join the same pair of blocks (a link is identified by source, target and which of the parallel links it is).
scenarios	Named parameter-override sets, run and compared by nagasim.experiments.
orders	Released jobs with a due date, emitted by a CREATE block in "Orders" arrival mode.
resource_sets	Named groups of resources with a selection rule, seized as one pseudo-resource.
schedules	Piecewise-constant arrival-rate or capacity schedules, optionally repeating.
failures	Resource failures: uptime/downtime distribution pairs per named resource group.
tables	Named 1-D/2-D lookup tables read by TABLE("name", k1[, k2]) in any expression.
sequences	Named routings: ordered steps through STATION blocks, walked by a ROUTE block.
variables	Model-level variables, read and written by expressions; reset to initial each replication.
entities	Entity types: shape, colour, optional WIP holding cost.
timeseries_inputs	Named time-series profiles read by TS("name") in any expression.
levels	Continuous quantities with bounds (battery energy, tank volume, an inventory position), read by LEVEL("name").
flows	Rate-based transfers between levels, re-evaluated at events.
conversions	Delayed conversions with a yield curve: feed in, product released over the following hours or days.
fixed_costs	Costs of the scenario rather than of the run: capex (flagged capex: true for the investment case), or an annuity over a sized parameter.
fleets	Pools of vehicles that carry entities on the network; a fleet is a resource under its own name.
motion_profiles	How robots, people and mechanisms move: speed, acceleration, payload derating and a collaborative speed, named by a MOTION block's profile.
chargers	Chargers and battery-swap stations at network nodes, used by fleets that declare a battery.
auxiliaries	Named expressions read by AUX("name"), evaluated on read.
delays	Delays read by DELAY("name"): input, delay time, kind and order.
subscripts	Dimensions: a record with "dims" is flattened into one record per element.
agent_types	Statecharts run for every agent of a population: parameters, states, transitions.
populations	Agent populations: a type, a count and an initial placement.
reality_checks	Vensim-style reality checks: a test input and a constraint the model must then satisfy.
network	Optional path network: nodes at layout coordinates and the segments joining them.
annotations	Text notes and frames drawn behind blocks on the canvas; ignored by the engine.
submodels	Reusable definitions (parameters, inner blocks/links/ports), flattened before a run.
background	Optional floor-plan image: path, position, scale, opacity, lock, real-world scale.
info	Optional model metadata: description, author, notes; shown in the report header.
data_sources	Declared CSV/Excel/SQLite/SQL/JSON sources model parameters can be read from.
data_bindings	Which column, filtered and transformed how, feeds which override path.
initial_state	Warm start: entities already in blocks, variable values and resource states the run begins with.
simulation	Run settings: time_limit, warmup, replications, time_unit, currency, entity_log_limit, and the optional real-date calendar.
assertions	Model assertions: a KPI, a comparison operator/value and a replication/confidence budget, checked by naga check.

Units

Every quantity field names its unit in a sibling key; a missing unit or "base" means the model's own (simulation.time_unit, simulation.length_unit).

Quantity	Units
time	milliseconds, seconds, minutes, hours, days, weeks, months, years
length	millimeters, centimeters, meters, kilometers
speed	m/s, m/min, km/h (any <length>/<time>, e.g. mm/s)
mass	g, kg, t
energy	Wh, kWh, MWh
power	W, kW, MW
rate	milliseconds, seconds, minutes, hours, days, weeks, months, years

Plant mapping format (*.plantmap.json)

Format 1, from nagasim/plant.py. Start one with naga plant init, judge one with naga plant check. See A plant as a timeline for the guide.

The time section:

Key	Meaning
epoch	ISO 8601 instant that model time 0 stands for; with no offset it is UTC.
unit	The model's time unit (default: the model's own).
stamp	Which stamp of an observation is its time (default: the source's).

A signals entry:

Key	Meaning
source	Only observations of this data source.
key	The observation's key. An "at" key holds one {id}; a "job" key may hold one *.
field	The cell to read when the value is a row.
as	What the key asserts.
resource	A resource or a fleet of the model.
block	A block of the flattened model.
level	A level of the model.
fleet	"vehicle", "load": a fleet of the model.
unit	"vehicle", "load": which vehicle of the fleet, from 0 (default 0).
nodes	"vehicle": plant value -> the network node the vehicle is at.
states	Plant value -> busy, idle, blocked, down, up.
blocks	Plant value -> block.
gone	Values that end the entity (a null always does).
merged	Values that take it into a batch.
type	The entity type of what this signal names.
type_field	The cell of a row that holds the product.
types	Product -> entity type.
leaves	"seen": the entity has left.
scale	"level": model value = value * scale.
rollover	"counter": the value the plant's counter returns to 0 at.