Actual initial commit

.gitignore

@@ -0,0 +1,125 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+cov_html/
+cov.xml
+test-reports/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/source/modules.rst
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+Untitled*.ipynb
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.envs
+.venv*
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# doit
+.doit*
+.env
+.report.json
+.venv
+
+# VSCode
+.vscode
+
+# temporary files
+tmp/
+
+# direnv
+.envrc
+
+# Map Cache
+.tile-cache/
+
+# Temporary Reporting Artifacts
+classes.png
+packages.png

CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contribution Guide
+
+If you wish to contribute to UPSTAGE, we ask that you follow these steps to ensure code quality.
+
+## Prerequisites
+
+First, get Python 3.11 or 3.12 through your preferred means (conda, mamba, venv, e.g.). We prefer [Mambaforge](https://github.com/conda-forge/miniforge).
+
+> When installing `mambaforge` on Windows, try to install it on `C:\mf`.
+This will minimize the path length to avoid issues with the Windows
+maximum path restriction. You may need to create the folder first if you
+do not have administrator permissions.
+
+Ensure that the pip version is >= `21.3` to allow editable installations with just `pyproject.toml` and the `flit` backend.
+
+```bash
+python -m pip install --upgrade pip
+```
+
+## Get Started
+
+Clone the repo locally, then install to your environment with:
+
+``pip install -e .[docs,test]``
+
+## Code Quality
+
+Code quality is enforced using these steps:
+
+1. pyproject.toml format (only if you are modifying dependencies, e.g.)
+2. SSort
+3. Ruff
+4. mypy
+
+```bash
+pyproject-fmt .\pyproject.toml
+ssort .\src\
+ruff format .\src\
+mypy --show-error-codes -p upstage
+```
+
+### Testing
+
+To run the unit tests in `src/upstage/test`, run:
+
+```bash
+pytest
+```
+
+from the top level of the repo.
+
+Test reports will be in `.\build\reports`
+
+### Building the documentation
+
+Documentation is built from autodocs first, then the source build.
+
+From the top level of the repo:
+
+```bash
+sphinx-apidoc -o .\docs\source\ .\src\upstage\ .\src\upstage\test\
+sphinx-build -b html .\docs\source .\build\docs
+```
+
+Then the docs can be loaded from `.\build\docs\index.html`
+
+## Making Merge Requests
+
+The valid target for all merge requests is `dev`. Please ensure that your merge request includes documentation and explanation for its purpose and sufficient documentation to explain its usage.

LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2024, Georgia Tech Research Institute (GTRI)
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in
+   the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this
+   software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GEORGIA TECH RESEARCH CORPORATION,
+THE GEORGIA INSTITUTE OF TECHNOLOGY, THE BOARD OF REGENTS OF THE UNIVERSITY SYSTEM OF GEORGIA, THEIR EMPLOYEES, OFFICERS, BOARD MEMBERS, OR AGENTS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+THIS SOFTWARE MAY NOT BE EXPORTED WITHOUT FULLY COMPLYING WITH ALL UNITED STATES EXPORT CONTROL REGULATIONS AND LAWS.  GEORGIA TECH RESEARCH CORPORATION
+MAKES NO WARRANTY OR REPRESENTATION REGARDING THE EXPORT CONTROL STATUS (EAR OR ITAR CLASSIFICATION) OF SOFTWARE PROVIDED UNDER THIS LICENSE.
+
+No other rights to any other intellectual property of Georgia Tech Research Corporation, including any patent, copyright, trademark, proprietary information,
+or other form recognized by law is granted under this license.

README.md

@@ -0,0 +1,81 @@
+# UPSTAGE
+
+UPSTAGE is a **U**niversal **P**latform for **S**imulating
+**T**asks and **A**ctors with **G**raphs and **E**vents built atop
+[*SimPy 4*][simpy].
+[*SimPy 4*][simpy].
+
+## What is UPSTAGE for?
+
+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. It is designed is to simplify the development process for simulation models of *complex systems of systems*.
+
+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.
+
+[image](docs/source/_static/upstage-flow.png)
+
+Additional features include:
+
+1. Context-aware `EnvironmentContext`, accessed via `UpstageBase`, enabling thread-safe simulation globals for the Stage and Named Entities (see below).
+1. Active States, such as `LinearChangingState` which represent continuous-time attributes of actors at discrete points.
+1. Spatial-aware data types like `CartesianLocation`, and states like the waypoint-following `GeodeticLocationChangingState`.
+1. Geodetic and cartesian positions, distances, and motion - with ranged sensing.
+1. `NamedEntity` in a thread-safe global context, enabling easier "director" logic creation with fewer args in your code
+1. The STAGE: a global context variable for simulation properties and attributes. This enables under-the-hood coordination of motion, geography, and other features.
+1. 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.
+1. All States are recordable
+1. Numerous runtime checks and error handling for typical DES pitfalls: based on years of custom DES-building experience.
+1. And more!
+
+## Requirements
+
+UPSTAGE only requires Python 3.11+ and Simpy 4+.
+
+## Installation
+
+**Pending:**
+
+```console
+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):
+
+```console
+python -m pip install .
+```
+
+(or just `pip install .`)
+
+### Installation for tests
+
+To run the tests: clone locally, install into a fresh environment, and run using:
+
+```console
+pip install -e .[test]
+pytest
+```
+
+## Documentation
+
+Pending ReadTheDocs.
+
+## How do I report an issue?
+
+Using the issue feature, please explain in as much detail as possible:
+
+1. The Python version and environment
+2. How UPSTAGE was installed
+3. A minimum working example of the bug, along with any output/errors.
+
+## How do I contribute?
+
+To set up a suitable development environment, see [CONTRIBUTING](CONTRIBUTING.md).
+
+For style, see [STYLE_GUIDE](STYLE_GUIDE.md).
+
+[simpy]: https://gitlab.com/team-simpy/simpy/