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

Warning

Work-In-Progress

(venv) $ pip install upstage

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

Installation for running tests

Note that the tests include the two full examples from the documentation.

(venv) $ pip install uptage[test]
(venv) $ pytest

Installation for building docs

Unless you’re adding to the codebase, you won’t need to run the sphinx-apidoc command.

(venv) $ pip install upstage[docs]
(venv) $ sphinx-apidoc -o .\docs\source\ .\src\upstage\ .\src\upstage\test\
(venv) $ sphinx-build -b html .\docs\source\ .\docs\build\

User Guide

Guide

• User Guide
  • Starting Point
    • First UPSTAGE Simulation
    • Task Interrupts
    • Task Rehearsal
    • Best Practices
    • UPSTAGE vs SimPy
  • Full Examples
    • First Simulation Full Source
    • Rehearsal Simulation Example
    • Complex Cashier Full Source
  • How-to Guides
    • Resource States
    • Active States
    • Mimic States
    • Task Nucleus
    • Stage Variables
    • 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 and running tests, 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 API
  • upstage package