Native simulation

TokLang.Sim

The native discrete-event simulator of TokLang.jl, for large experiments: many scenarios, many replications, parallel runs on the threads of Julia. The model comes from the Rust engine (model reads a document with Engine.sim_model), and so do the conditions of flows, which the engine evaluates as its own simulator does. The semantics are those of the engine's simulator for every element the native simulator runs; a model with other features (unsupported) is rejected with UnsupportedModel and runs in the engine.

m = TokLang.Sim.model(read("kwerenda-symulacja.tok", String))
r = TokLang.Sim.simulate(m; seed=7)
e = TokLang.Sim.experiment([m, TokLang.Sim.scenario(m; name="3 archivists", resources=Dict("archiwisci" => 3))];
                       replications=100)
TokLang.Sim.summarize(e)

SimModel

A process ready for the native simulator: built with model from the text of a document. unsupported lists the features the native simulator does not run (empty when it runs the model).

model(text; name="model", cases=nothing, seed=nothing) -> SimModel

The simulation model of a tok document, read by the engine. cases and seed override the attributes of simulate.

supported(m) -> Bool

Whether the native simulator runs the model; unsupported lists what it does not.

The features of the model the native simulator does not run, as (element, feature) pairs.

scenario(m; name=m.name, resources=Dict(), arrival=nothing, durations=Dict(),
         probabilities=Dict(), cases=nothing) -> SimModel

A copy of a model with other parameters: resource counts ("archiwisci" => 3), the time between arrivals, activity durations ("ocena" => "lnorm(25m, 8m)") and branch probabilities (("mozliwa", "odmowa") => 0.2, the flow from a gateway to a node). Distributions are texts of the language or Dist values.

Dist(name, kind, args, labels)

A distribution of the simulation statements as the engine parses it: name is one of :fixed, :unif, :tri, :norm, :lnorm, :exp, :bern, :cat; kind is :duration (arguments in seconds), :number, :bool or :cat; labels are the labels of cat (text, booleans or numbers) with the probabilities in args.

simulate(m; seed=m.seed, replication=1, cases=m.cases, log=true) -> Run

One run of the native simulator. The random stream depends only on seed and replication, so the same arguments always give the same run.

experiment(models; replications=10, seed=nothing, cases=nothing, threads=true,
           common_random_numbers=true, log=false) -> Experiment

Run every scenario replications times. models is one SimModel, a vector of them, or pairs name => model (or name => text of a document). With threads=true the runs are distributed over the threads of Julia (julia -t N); the result does not depend on the number of threads, because every run has its own random stream, derived from seed (default: the seed of the first model) and the replication number, and with common_random_numbers=false also from the scenario number. Common random numbers (the default) give every scenario the same streams, which makes differences between scenarios more precise.

Run

One simulation run of the native simulator: cycle_times (seconds) and end_events of the finished cases in case order, with their numbers in case_ids; by_end_event, the activities and the utilization of every resource (as in tok sim), horizon_s, warnings, and, when the run was asked to keep it, the event log log (one named tuple per activity instance, times in seconds from the simulation start).

Experiment

The runs of experiment: runs[s, r] is replication r of scenario s; scenarios holds the names.

Mean, median and 90th percentile of the cycle times of a run, in seconds.

Utilization of a resource in a run (busy time / (count × simulated period)).

indicators(e::Experiment) -> Vector{NamedTuple}

The indicators of every run in long form: one named tuple (scenario, replication, indicator, value) per indicator — cases_started, cases_finished, cycle_time_mean_s, cycle_time_median_s, cycle_time_p90_s, utilization:RESOURCE, mean_wait_s:ACTIVITY, mean_processing_s:ACTIVITY and end_event:EVENT (the share of finished cases).

summarize(e::Experiment; level=0.95) -> Vector{NamedTuple}

For every scenario and indicator: the mean over the replications, its standard deviation, the half-width of the confidence interval of the mean (normal approximation) and the number of replications.

An error of the simulation: a model that cannot run, or an invalid value.

UnsupportedModel(features)

The model uses features the native simulator does not run; features lists them as (element, feature) pairs. Such models run in the engine (Engine.simulate).