μSim API Reference
The usim
package provides access to the entire μSim API in one
convenient, flat namespace.
Logically, the API can be divided into different topics.
In addition, usim.typing
allows for type annotations to statically
verify simulations.
Hint
μSim provides a compatibility layer
to the SimPy simulation framework.
The usim.py
package is a drop-in replacement
for the simpy
package.
Starting a Simulation
Simulations in μSim are always defined based on a number of initial root
activities,
which may branch out to more activities.
A simulation is started by calling usim.run()
, passing in its
activities and optionally the time window to simulate.
- usim.run(*activities: Coroutine, start: float = 0, till: Optional[float] = None)[source]
Run a simulation from the initial
activities
at timestart
until completion- Parameters
activities – initial activities of the simulation
start – initial time of the simulation
till – time at which to terminate the simulation
Simulating Time
μSim provides a number of primitives to check or wait for specific points in time of a simulation.
usim.time
Expressions define points in time or delays. For example,
await (time + 20)
delays for 20 time units.usim.eternity
A point in time indefinitely far into the future.
usim.instant
A point in time indistinguishable from the current moment.
In addition, recurring actions can be repeated at specific delays or intervals
in async for
blocks.
usim.interval
Repeat in fixed intervals, regardless of any time spent in a block.
usim.delay
Repeat after fixed delays, in addition to any time spent in a block.
Branching and Multitasking
An activity may not only await
another,
it may also run one or more activities concurrently.
This requires opening a scope in an async with
context
which defines the lifetime of child activities.
usim.Scope
An asynchronous context manager which can concurrently run activities until it is closed. A scope is forcefully closed if an exception occurs in the hosting activity or a child.
usim.until()
A
Scope
that is forcefully closed if a specific notification triggers.
Each child activity is represented by a Task
.
Tasks can be inspected for their current status,
and various exceptions only occur when interacting with tasks.
usim.TaskState
usim.TaskClosed
andusim.VolatileTaskClosed
The exception value of a
Task
that was forcefully closed by itsScope
.usim.CancelTask
andusim.TaskCancelled
Exception used to
cancel()
aTask
, and the resulting exception value of theTask
.
During a usim.Scope
,
multiple child activities may fail with an exception at the same time.
The usim.Scope
collects and propagates all exceptions from child activities.
usim.Concurrent
Exception that propagates all exceptions from child activities at once; also occurs if only a single child activity fails. Never includes an exception raised in the scope itself.
Synchronising Conditions
μSim allows to model any boolean that may change at a later time
as a Condition
.
These can be combined and negated to derive new Condition
s.
It is common for types to return a Condition
instead of
a plain bool
.
usim.Tracked
A mutable value which can be explicitly
set()
or modified using arithmetic operators, such as+
,-
,*
or/
. Comparison operators, such as==
,<=
or>
, provide aCondition
which triggers once the value matches.
Modelling Resources
Simulations commonly revolve around resources which are produced/consumed, blocked or waited for. μSim implements a range of generic, ready-to-use resources for various use-cases.
usim.Resources
Supply of named resources which can be temporarily borrowed or permanently produced/consumed.
usim.Capacities
Fixed supply of named resources which can be temporarily borrowed.
usim.typing.ResourceLevels
Current, expected or desired levels of resources.
usim.ResourcesUnavailable
Exception raised when an attempt to
claim()
resources fails.
Common Building Blocks
usim.first()
Run several activities concurrently and yield results as they become available.
usim.collect()
Run several activities concurrently and return their results in order.