μ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 time start 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

Enum describing the possible status() of a Task.

usim.TaskClosed and usim.VolatileTaskClosed

The exception value of a Task that was forcefully closed by its Scope.

usim.CancelTask and usim.TaskCancelled

Exception used to cancel() a Task, and the resulting exception value of the Task.

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 Conditions.

usim.Flag

A Condition with a fixed value which can be explicitly set() to either True or False.

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 a Condition which triggers once the value matches.

Sharing State

Concurrently running activities frequently need to access, modify or exchange state. μSim provides several types to easily write activities that safely share state.

usim.Lock

Ensure mutually exclusive access for multiple activities.

usim.Channel

Broadcast messages to multiple subscribers.

usim.Queue

Send and receive unique messages.

usim.StreamClosed

Exception for operations not supported by a closed Channel or Queue

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.

Detailed Topics