UPSTAGE

The Universal Platform for Simulating Tasks and Actors with Graphs and Events (UPSTAGE) library 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.

UPSTAGE - which is built on the SimPy library - contains two primary components that are assembled to create a broad array of simulations.

The components are Actor - which contain State - and Task, which can be assembled 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, such as LinearChangingState which represent continuous-time attributes of actors at discrete points.

3. Spatial-aware data types like CartesianLocation, and states like the waypoint-following GeodeticLocationChangingState.

4. Geodetic and cartesian positions, distances, and motion - with ranged sensing.

5. NamedUpstageEntity in a thread-safe global context, enabling easier “director” logic creation with fewer args 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.

8. All States are recordable

9. Numerous runtime checks and error handling for typical DES pitfalls: based on years of custom DES-building experience.

10. And more!

Note

This project is under active development.

Installation

In a suitable Python environment (3.11+):

(venv) $ pip install upstage-des

Installation from source

Alternatively, you can download UPSTAGE and install it manually. Clone, or download the archive and extract it. From the extraction location (and within a suitable Python environment):

(venv) $ python -m pip install .

(or just pip install .)

User Guide

Guide

• User Guide
  • Starting Point
    • First UPSTAGE Simulation
    • Task Interrupts
    • Task Rehearsal
    • Best Practices
    • Simulation Data Gathering and Processing
    • UPSTAGE vs SimPy
  • Full Examples
    • First Simulation Full Source
    • Rehearsal Simulation Example
    • Complex Cashier Full Source
    • Data Gathering Example Full Source
  • How-to Guides
    • Environment Context
    • Resource Types
    • Resource States
    • Active States
    • Mimic States
    • Task Nucleus
    • Stage Variables
    • Time Units
    • Events
    • Geography
    • Decision Tasks
    • Task Networks
    • State Sharing
    • Named Entities
    • Motion Manager
    • Communications
    • Typing and UPSTAGE
    • Random Numbers

Contributing

To contribute to UPSTAGE, or to learn the steps for building documentation, running tests, and putting in PRs, see CONTRIBUTING.MD)

License and Attribution

This software is licensed under the BSD 3-Clause. Please see the LICENSE file in the repository for details.

Reference

This section contains information-oriented reference materials for developers looking to understand the UPSTAGE software components and its API.

The API documentation is auto-generated.

API

• upstage_des
  • upstage_des package