upstage-des 0.4.0

A library for behavior-driven discrete event simulation.

UPSTAGE

UPSTAGE is a Universal Platform for Simulating Tasks and Actors with Graphs and Events built atop SimPy 4.

✨ Try it in your browser ✨

➡️ https://gtri.github.io/upstage/demo

What is UPSTAGE for?

UPSTAGE is a Python framework for creating robust, behavior-driven Discrete Event Simulations (DES). The primary goal of UPSTAGE is to enable the quick creation of simulations at any desired level of abstraction with built-in data recording, simulation integrity and runtime checks, and assistance for the usual pitfalls in custom discrete-event simulation: interrupts and cancellations. It is designed is to simplify the development process for simulation models of complex systems of systems.

UPSTAGE leverages the extensible SimPy library and adds two concepts to accelerate the generation of complex discrete-event simulations.

1. Actor - i.e., an entity that has State
2. Task - i.e., actions actors can perform and that can be organized into a TaskNetwork.

Actors can have multiple networks running on them, their states can be shared, and there are features for interactions between task networks running on the same actor. Those tasks modify the states on their actor, with features for real-time states that update on request without requiring time-stepping or modifying the existing events.

Additional features include:

1. Context-aware EnvironmentContext, accessed via UpstageBase, enabling thread-safe simulation globals for the Stage and Named Entities (see below).
2. Active States (e.g.,LinearChangingState) represent continuous-time attributes of actors that can be queried at discrete points in time, or trigger events when they reach a certain level.
3. Spatial-aware data types (e.g., CartesianLocation) and states like the waypoint-following GeodeticLocationChangingState.
4. Geodetic and cartesian positions, distances, and motion - with ranged sensing.
5. NamedEntity in a thread-safe global context, enabling easier "director" logic creation with less argument passing in your code
6. The Stage: a global context variable for simulation properties and attributes. This enables under-the-hood coordination of motion, geography, and other features.
7. Rehearsal: Write planning and simulation code in one place only, and "rehearse" an actor through a task network using planning factors to discover task feasibility before the actor attempts to complete the task.
8. All States are recordable, and some record dataclass and dictionary values
9. A Routine class for building reusable event behaviors to simplify Task coding.
10. Point-To-Point and Routing Table communications handlers.
11. Numerous runtime checks and error handling for typical DES pitfalls: based on more than a decade of custom DES-building experience.
12. And more!

See the documentation for tutorials and details.

Requirements

UPSTAGE only requires Python 3.11+ and Simpy 4+.

Installation

In an environment (Python 3.11+) of your choice:

pip install upstage-des

Documentation

See the documentation for tutorials and additional details.

How do I contribute or set up a develpment environment?

See CONTRIBUTING for instructions on setting up an environment and contributing.

For information on how to style your code, see the Style Guide.