KPI reference

Every result frame nagasim.api.run_model / nagasim.experiments.run_scenarios return, and every column each one carries -- probed against nagasim/models/job_shop_jackson.json so a new KPI column fails this generation until it has a definition here.

system

One row per metric (Metric, Value columns). Metrics observed on the probe run:

Metric	Definition
Run	Replication index (0-based).
Time Unit	The model's base time unit (simulation.time_unit); every duration without its own unit is already expressed in it.
Simulation Time	Length of the observed window (run end minus warm-up), in the model's time unit.
Total Entities Created	Entities with creation_time >= warmup, excluding one currently represented by a batch (in_batch set).
Total Entities Completed	Entities with deletion_time is not None and >= warmup.
Avg Throughput Time	Mean of deletion_time - creation_time over completed entities (link transfer time included).
Throughput (per time unit)	Completed entities divided by the observed simulation time.
Avg WIP (Little)	Little's-law estimate: throughput x average throughput time (not a measured time-average of live entities).
Max Queue Length	Largest queue length observed across every resource, resource set and store.
Avg Queue Length	Sum of the time-weighted average queue length across every resource, resource set and store.
Avg Resource Usage %	Mean utilization (busy time over scheduled/available capacity) across real resources only -- a resource set's own collector re-counts its members, so it is excluded here to avoid double counting.
Total Resource Cost	Sum of every real resource's busy + idle + per-use cost over the run.
Total Entity Holding Cost	Sum of every entity type's WIP holding cost accrued while entities were in the system.
Total Cost	Sum of cost attributed to this object/run (resource busy+idle+usage cost, or an entity's own accumulated cost, or the model-wide total).
Cost per Completed Entity	Total Cost divided by Total Entities Completed.
Entity Log Truncated	1 if the entity log hit simulation.entity_log_limit and older records were dropped (counts/costs stay exact via streaming accumulators either way).
Resource/Store Log Truncated	1 if any resource or store's bounded snapshot log dropped records (config.LOG_HISTORY); affects only the flat log sheets, not KPIs.

A run can also emit one WARNING row, absent from the probe above because a healthy run never produces it:

Metric	Definition
Short Statistics Window %	WARNING row, present only when it fires: the share of the intended post-warm-up horizon the statistics actually cover, when that is under 10%. The run drained at or just after the warm-up reset, so every other metric here is an average of almost nothing -- check the arrival blocks' max_arrivals, or lower the warm-up.

entity_summary

Column	Definition
Run	Replication index (0-based).
Entity Type	The entity type this row summarizes.
Total Created	Entities of this type created in the observed window.
Total Completed	Entities of this type completed in the observed window.
Avg Time	Mean throughput time for this entity type.
Min Time	Minimum throughput time for this entity type.
Max Time	Maximum throughput time for this entity type.
Mode Time	Most frequent throughput time (histogram mode); an event-sample statistic, not time-weighted.
Mode Time %	Share of observations at the modal throughput time.
P95 Time	95th percentile of throughput time.
P99 Time	99th percentile of throughput time.
Std Time	Sample standard deviation of throughput time (ddof=1).
Avg Cost	Mean total cost accumulated per entity of this type.
Total Cost	Sum of cost attributed to this object/run (resource busy+idle+usage cost, or an entity's own accumulated cost, or the model-wide total).

entity_log

Column	Definition
Run	Replication index (0-based).
Entity ID	The entity's identity counter value.
Type	The entity's type (e_type).
Created At	Simulation time the entity was created.
Exited At	Simulation time the entity was disposed (or None if still live at report time).
Throughput Time	Exited At - Created At (None while the entity is still live).
In Batch	Id of the batch entity currently representing this member, or null if not batched.
Cost	Total cost accumulated on this entity (usage + holding + model-assigned).
Initial	True for an entity the warm start injected at t=0 (initial_state), rather than one a CREATE block produced during the run.
Agent	":" for an entity with an agent (a CREATE block's population, or an agent's own "enter" action), else "" (H2).

resource_summary

Column	Definition
Run	Replication index (0-based).
Resource	The resource or resource set this row summarizes.
Total Seizes	Number of granted request units (a quantity-2 seize counts as 2), reset at warm-up.
Usage % (snapshot)	Busy time over the scheduled (available) capacity integral -- off-shift and failed time never dilutes it.
Idle %	Share spent holding no job.
Scheduled Capacity Avg	Time-average of capacity available after capacity schedules/failures.
Down %	Time-average of the resource's failure-active flag.
Busy Cost	Cost accrued while the resource was busy (cost_busy x busy time).
Idle Cost	Cost accrued while the resource was scheduled but idle (cost_idle x idle time).
Usage Cost	Cost accrued per seize (cost_per_use x seize count).
Total Cost	Sum of cost attributed to this object/run (resource busy+idle+usage cost, or an entity's own accumulated cost, or the model-wide total).
Queue Length Avg	Time-weighted average queue length.
Queue Length Max	Largest queue length observed (ignores zero-duration levels).
Queue Length Mode	Most frequent queue length (event-sample, not time-weighted).
Queue Length Mode %	Share of observations at the modal queue length.
Queue Len P95	95th percentile of the queue-length event samples.
Queue Len P99	99th percentile of the queue-length event samples.
Queue Len Std	Sample standard deviation of the queue-length event samples.
Time in Queue Avg	Mean wait time over completed acquisitions only (excludes requests still queued at report time).
Time in Queue Avg (incl. waiting)	Mean wait time including the censored wait of requests still queued at run end.
Time in Queue Max	Maximum wait time over completed acquisitions.
Time in Queue Mode	Most frequent wait time (event-sample).
Time in Queue Mode %	Share of observations at the modal wait time.
Wait P95	95th percentile of completed wait times.
Wait P99	99th percentile of completed wait times.
Wait Std	Sample standard deviation of completed wait times.
Bottleneck Score	round(utilization * avg_queue_length, 2), a heuristic ranking, not a standard KPI.
Bottleneck %	1 for the single highest-scoring resource with utilization >= 0.75, else 0.

resource_log

Column	Definition
Run	Replication index (0-based).
Resource	The resource or resource set this row summarizes.
time	Simulation time of this snapshot row.
in_use	Resource units in use at this snapshot.
queue_length	Entities queued at this snapshot.
event_type	What triggered this snapshot row (e.g. a request granted, released, put, get).

store_summary

Column	Definition

store_log

Column	Definition
Run	Replication index (0-based).
Store	The store this row summarizes (a Hold/Batch/Match block's internal store).
time	Simulation time of this snapshot row.
items	Number of items in the store at this snapshot.
event_type	What triggered this snapshot row (e.g. a request granted, released, put, get).

user_summary

Column	Definition
Run	Replication index (0-based).
Statistic	The RECORD statistic's name (stat_name).
Kind	In user_summary, the statistic's kind: count, tally, time_between or time_persistent. In cost_summary, the cost's kind: fixed (evaluated once at run start, never prorated), event (accrued as entities pass a RECORD kind="cost", reset at the warm-up) or peak (a flow's Peak Rate times its peak_price). In charging_summary, charge or swap.
Count	Number of observations (count's running total count, or a tally's/time_between's observation count); NaN for time_persistent, which has no discrete observations.
Value	The metric's/statistic's value, in the unit its row/kind implies.
Min	Minimum observed value (tally/time_between only).
Max	Maximum observed value (tally/time_between), or the highest level reached (time_persistent).
Std	Sample standard deviation of observed values (tally/time_between only).

order_summary

Column	Definition
Run	Replication index (0-based).
Order	The order's id, as declared in the model's "orders" section.
Entity Type	The entity type this row summarizes.
Sequence	Name of the routing the order's entities follow, blank for none.
Release	When the order was released into the model, in the base time unit.
Due	The order's due date, an ABSOLUTE time in the base time unit.
Quantity	How many entities the order releases.
Created	Entities this order actually released (warm-started ones included).
Completed	Entities of this order disposed so far / due-dated entities of this type completed after the warm-up.
Completion Time	When the LAST entity of the order was disposed; NaN while it is incomplete.
Lateness	Signed completion - due: negative is early, positive is late.
Tardiness	max(0, lateness): earliness does not offset lateness.
Late	1 if the order missed its due date / count of late entities of this type.
Status	complete (finished after the warm-up, the only status the means count), warmup (finished before it) or incomplete (still in the system at run end).

due_date_summary

Column	Definition
Run	Replication index (0-based).
Entity Type	The entity type this row summarizes.
Completed	Entities of this order disposed so far / due-dated entities of this type completed after the warm-up.
On Time	Due-dated entities of this type completed with lateness <= 0.
Service Level	On Time / Completed -- the fraction delivered on time.
Avg Lateness	Mean signed lateness over this type's completed due-dated entities.
Avg Tardiness	Mean tardiness over the same entities (earliness counts as 0).
Max Tardiness	Worst tardiness seen for this entity type.
Late	1 if the order missed its due date / count of late entities of this type.

queue_summary

Column	Definition
Run	Replication index (0-based).
Block	The SEIZE/PROCESS block the queue behaviour is declared on.
Resource	The resource or resource set this row summarizes.
Balked	Entities that saw the queue on arrival and never joined it.
Reneged	Entities that joined the queue and gave up before being served.
Preempted	Times a job of this block was interrupted by a higher-priority entity.
Avg Wait Before Renege	Mean time the entities that gave up had already waited.
Max Wait Before Renege	Longest wait before giving up.
Changeovers	Times this block's resource actually changed over -- the setup key differed from the previous job's.
Setup Time	Total time spent changing over at this block. It happens while the resource is held, so it is already inside its busy time and utilization.

motion_summary

Column	Definition
Run	Replication index (0-based).
Motion	<block>/<kind>: one segment kind of one MOTION block, or <block>/cycle.
Block	The SEIZE/PROCESS block the queue behaviour is declared on.
Segment Kind	move, pick, place, tool_change, dwell, process, or cycle for the whole cycle.
Segments	Segments of this kind completed (cycles, on the cycle row).
Mean Time	Mean duration of one segment of this kind (one cycle, on the cycle row), in the model's base unit.
Total Time	Summed duration of this kind's segments over completed cycles.
Cycle Share %	This kind's share of the total cycle time: the cycle-time breakdown.
Collaborative %	Of this block's moves, the share run at the collaborative speed (move row only).

charging_summary

Column	Definition
Run	Replication index (0-based).
Charger	The charger or battery-swap station this row summarizes.
Kind	In user_summary, the statistic's kind: count, tally, time_between or time_persistent. In cost_summary, the cost's kind: fixed (evaluated once at run start, never prorated), event (accrued as entities pass a RECORD kind="cost", reset at the warm-up) or peak (a flow's Peak Rate times its peak_price). In charging_summary, charge or swap.
Points	How many vehicles the charger serves at once.
Sessions	Charges or swaps completed, an interrupted opportunity charge included.
Utilization %	Share of the charger's point-time with a vehicle charging or swapping.
Avg Wait	Mean time from a vehicle's arrival to the start of its charge or swap (a wait for a charged pack included), in the model's base unit.
Avg Queue	Time-averaged number of vehicles waiting at the charger.
Grid kWh	Energy drawn from the grid: battery kWh / efficiency, booked when a session (or a swapped pack's recharge) ends. Also a row of energy_summary.
Peak kW	Highest total power of the batteries charging at once, the taper included.
Energy Cost	Total kWh x simulation.energy_price; 0 with no price set. Joins cost_summary (Kind "energy") and the system frame's Total Cost.

battery_summary

Column	Definition
Run	Replication index (0-based).
Fleet	The pool of vehicles this row summarizes. Its utilization, seize count and costs are in the RESOURCE frame -- a fleet is a resource; this frame adds what only a vehicle pool has.
Capacity kWh	One vehicle's battery capacity.
Charging %	Share of the fleet's total vehicle-time spent charging or swapping.
Charge Trips	Arrivals at a charger, summed over the vehicles.
Min SoC	Lowest state of charge any vehicle reached (0-1; negative after a depletion).
Mean Final SoC	Mean state of charge over the vehicles at the end of the run.
Depleted	Times a vehicle's state of charge crossed zero; it finishes its job regardless.
Drain kWh	Energy the vehicles drew from their batteries: power kW per state x time.

tending_summary

Column	Definition
Run	Replication index (0-based).
Station	The tending STATION this row summarizes, with the arm fleet in Fleet. A pair has a row once a cobot of the fleet has tended the station.
Fleet	The pool of vehicles this row summarizes. Its utilization, seize count and costs are in the RESOURCE frame -- a fleet is a resource; this frame adds what only a vehicle pool has.
Picks	Pick cycles completed: parts the fleet's cobots took out of the station.
Places	Place cycles completed: parts the cobots put into the station.
Exchanges	Visits on which a loaded cobot picked a finished part before placing its own (the fleet's exchange); each is also one pick and one place.
Avg Pick Time	Mean duration of a pick cycle, in the model's base unit.
Avg Place Time	Mean duration of a place cycle.
Avg Loaded Wait	Mean time a cobot held its part at the station, from its loaded arrival until the machine accepted the part (0 when the machine was free; an exchange's pick is inside it).
Avg Blocked For Pick	Mean time a finished part, and with it its machine, waited for a cobot: from the part reaching its TRANSPORT to the start of the pick cycle.
Avg Stay	Under cobot: "stay": mean time the cobot waited at the station, from the end of its place cycle until the part reached its next TRANSPORT or a DISPOSE.

timeseries

Column	Definition
Run	Replication index (0-based).
Time	Sample time on the fixed sampling grid.
Series	Which quantity this row samples, e.g. system/WIP, resource/<name>/queue, store/<name>/size, user/<name>, level/<name>, agents/<population>/<state>; for dashboard, the widget's series label (empty for a kpi/gauge widget).
Value	The metric's/statistic's value, in the unit its row/kind implies.
Warmup	True if this sample falls before the warm-up cutoff.