Core API

End preparation and start the run (spec §10). Idempotent; :meth:run calls it on first use.

The sequence is: run the initializers in registration order, capture :attr:initial_state, notify the projection listeners and activate the projection, then execute the queued deferrable commands in call order at the current time, before any scheduled event is processed. An exception from an initializer or a command propagates; commands after a failing one are dropped. Calling it again after a failed initializer, or from an initializer, raises RuntimeError.

Resolve value into the callback of a binding kind (spec §8.2).

• scalar (() -> float): a description with sampler(rng) or a number.
• routing (() -> Sequence[Server]): a routing description or a fixed sequence of servers.
• contextual ((*context) -> float): a description or a number; the context is ignored.

Descriptions draw from :meth:rng (stream). Any other callable is opaque: it is returned unchanged and owner is recorded in :attr:opaque_sampler_owners. Raises ValueError for an unknown kind and TypeError for a value of no accepted form. In debug mode binding a value to a stream already bound to a different value raises ValueError: the two samplers would share one stream and the result would depend on the order of their draws.

Close the trace recorders attached to this environment, then its log sinks. Idempotent.

Every recorder and sink is closed even if one raises; the exception propagates afterwards. A closed sink receives no further event; :attr:log_history keeps its records. After closing, :meth:emit is a no-op, including events emitted by finalizers of unfinished simulation processes.

Set the warm-up of the KPI observation window (spec §12.2), recorded in the requested manifest.

The window starts at warmup, a finite time >= 0; see :func:simulatte.kpi.observation_window. Raises RuntimeError once activation started and ValueError for an invalid warm-up.

Emit a DEBUG :class:~simulatte.events.LogEvent at the current simulation time.

Parameters:

Stamp event and deliver it to the subscribers of its type.

Stamps t, seq and, for domain events while the projection is active, ordinal. Raises ValueError for an instance that was already emitted or a non-domain event carrying deltas, RuntimeError for a domain event emitted while subscribers are being called, and TypeError for an instance of a subclass of a registered event type that is not registered itself (it would be recorded under its parent's type with undeclared fields). Exceptions raised by subscribers propagate.

Attach the semantic digest of the run and return it; later calls return the same digest.

Raises RuntimeError after activation unless the digest was already enabled.

Emit an ERROR :class:~simulatte.events.LogEvent; arguments as for :meth:debug.

The digest (None unless :meth:enable_digest was called) and the KPI scalars of the run.

The scalars are those of every attached :class:~simulatte.kpi.Collector, keyed "<scope id>/<kpi name>" and sorted by key.

Emit an INFO :class:~simulatte.events.LogEvent; arguments as for :meth:debug.

The manifest of the run: the requested part, plus the final part once :meth:run was called.

Register fn as an activation initializer.

Initializers run in registration order when the environment activates; one registered after the initializers of :meth:activate ran (for example by a projection listener, or after activation) runs immediately. While an initializer runs, scheduling any SimPy event raises RuntimeError, and simulated time must not advance.

Request the semantic projection; on_initial_state receives the initial state at activation.

Digests and trace recorders call this when they attach; every listener receives the same read-only :attr:initial_state. Domain events get ordinals only once the projection is active, which happens after every listener received the initial state; the first domain event after activation has ordinal 0. Raises RuntimeError after activation.

The RNG stream name, created on first use and cached.

Its seed is :func:simulatte.rng.derive_seed of :attr:seed and name, so streams are independent of each other and of their creation order. In debug mode the stream counts its draws, and drawing while subscribers are being called raises RuntimeError.

Activate the environment on first use (see :meth:activate), then run the simulation.

The stopping policy of the manifest is the one of the last call: a horizon for a numeric until, exhaustion for None. If it raises, trace recorders report the run as failed.

Process the next event in the queue.

If user interrupts the simulation via KeyboardInterrupt raise a StopSimulation exception to gently pause the simulation; trace recorders then report the run as cancelled.

Host, wall-clock start and wall-clock time spent in :meth:run; separate from the manifest.

Emit a WARNING :class:~simulatte.events.LogEvent; arguments as for :meth:debug.

Release a job from the Pre-Shop Pool onto the shop floor.

This method performs the following actions: 1. Adds the job to the active jobs 2. Updates WIP values via the configured WIP strategy 3. Emits shopfloor.entered 4. Records the PSP exit timestamp on the job 5. Spawns the main processing coroutine for the job

Parameters:

Wire a dispatcher object's hook methods to this shopfloor.

Detects which hook methods exist on the dispatcher and registers only those that are callable. This allows partial implementations where a dispatcher only handles a subset of events.

Parameters:

Execute the main processing loop for a job through all its servers.

This generator manages the complete lifecycle of a job as it moves through its routing. For each server in the job's routing, it:

1. Requests and acquires the server resource (queuing if busy)
2. Executes on_before_operation hooks
3. If a MaterialCoordinator is configured, waits for material delivery
4. Processes the job for the specified duration
5. Updates WIP via the configured WIP strategy
6. Executes on_after_operation hooks
7. Signals processing completion (job_processing_end event + on_processing_end callbacks)

After all operations complete, it: - Records the finish timestamp on the job - Moves the job from active (jobs) to completed (jobs_done) - Emits job.finished (the default EMACollector and other collectors update on it) - Calls on_job_finished callbacks - Signals job completion via signal_job_finished() - Retires the job from the environment's entity registry (entity.retired); jobs_done and other Python references keep it

Parameters:

Yields:

Register a hook to run after each operation.

Hooks registered post-construction execute after any hooks passed via init, in registration order.

Register a hook to run before each operation.

Hooks registered post-construction execute after any hooks passed via init, in registration order.

Register a callback for when a job completes its entire routing.

Callbacks registered post-construction execute after any callbacks passed via init, in registration order.

Register a callback for when a job completes processing at any server.

Callbacks are invoked synchronously after the server is released (servers_exit_at is stamped and job.previous_server is available). This fires after each operation, not just when the job finishes its entire routing.

Parameters:

Replace the shopfloor's WIP strategy.

Signal that a job has completed its entire routing.

This method triggers the job_finished_event with the completed job as the event value, notifying any waiting processes that a job has finished all operations. The event is then recreated for the next signal.

Unlike job_processing_end, this is only called once per job when it completes its final operation.

Parameters:

completed = 0
while completed < target:
    job = yield shop_floor.job_finished_event
    completed += 1
    print(f"Job {job.id} completed. Total: {completed}")

Current entity state: WIP per server id and the number of jobs in the system.

Simulate processing a job for a given duration.

This generator yields a timeout event for the processing duration and updates worked_time, then emits server.work_credited. Should be called within a request context.

Parameters:

Yields:

Release the server after job processing.

Records the job's exit time. SimPy removes the request from users while creating the Release event; if it was there, the job's location becomes transit and job.released is emitted. Releasing a request that was never granted or was already released changes neither and emits nothing.

Parameters:

Returns:

Request server access for a job with priority-based queueing.

Creates a priority request that enters the server queue. The request should be used as a context manager to ensure proper release.

Parameters:

Returns:

Current entity state: capacity, job ids of users and queue (in order) and worked time.

Refresh queued requests' priority keys and resort.

For each request in the queue, calls req.job.priority(req.server) to obtain the current priority and rewrites req.key accordingly, then sorts the queue in ascending order by the refreshed keys.

Called automatically before every dispatch decision via _trigger_put. May also be invoked explicitly by user code that has mutated priority_policy and wants to observe the new order before the next dispatch event.

Note: req.priority is not refreshed; it remains the snapshot taken at request construction. To inspect a queued job's current priority, call req.job.priority(req.server) directly.

Requires that every queued request expose job, server, time, and preempt attributes (which ServerPriorityRequest does).

When the relative order changes, emits server.queue_reordered with the minimal set of move operations.

Get material requirements for a specific operation.

Parameters:

Returns:

Current entity state; times are floats and servers are referenced by id.

Infinite generator that creates and routes jobs at random intervals.

This method runs as a SimPy process for the simulation's duration. On each iteration it:

1. Waits for the inter-arrival time
2. Samples a random SKU based on configured weights
3. Generates a routing and processing times for the selected SKU
4. Creates a ProductionJob with computed due date
5. Routes the job to PSP (if configured) or directly to ShopFloor

Each draw comes from its own stream, in this order per job: inter-arrival time (before the timeout), SKU, routing, one service time per operation, due-date offset.

Yields:

Current entity state: the owning shop floor's id.

Add a job to the pool and signal its arrival.

Appends the job to the end of the queue and triggers the new_job event, allowing event-driven processes (e.g., starvation avoidance) to react immediately to the new arrival.

Parameters:

Return jobs in the pool whose routing begins at the given server.

Parameters:

Returns:

Subscribe a callback to be invoked each time a job arrives in the pool.

Callbacks are invoked synchronously during add(), before the SimPy new_job event fires. No env.run() priming is needed.

Parameters:

Remove a job from the pool and release it to the shopfloor.

Convenience method combining remove() and shopfloor.add(). Use remove() instead if you want to discard a job without releasing it.

Parameters:

Raises:

Remove a job from the pool and record its exit timestamp.

Supports two modes: FIFO removal (default) or specific job removal. Sets job.psp_exit_at to the current simulation time before returning and emits psp.exited.

Parameters:

Returns:

Raises:

Current entity state: job ids in FIFO order and the owning shop floor's id.

Run all simulations.

Parameters:

Returns:

Step plot of the jobs on the shop floor over time (RuntimeError without data).

Scatter plot of job lateness at completion, tardy jobs red and early ones green (RuntimeError without data).

Step plot of the cumulative throughput over time (RuntimeError before the first completion).

Step plot of the total WIP over time (RuntimeError without data).

Step plot of the queue length over time (RuntimeError without data).

Step plot of the utilization over time, up to the current time.