Docs update, drop python api docs

.github/workflows/build-doc-deploy.yaml

@@ -20,27 +20,7 @@ jobs:
  - name: Setup Python
  uses: actions/setup-python@v3
  - run: pip install poetry
- - run: poetry build
- docs-python:
- needs: build-python
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v3
- with:
- fetch-depth: 0
- - name: Setup Python
- uses: actions/setup-python@v3
- - run: pip install poetry
- - run: poetry install --with dev,docs
- - name: Export notebooks as examples
- run: poetry run make ipynb2md
- - name: MkDocs build
- run: poetry run mkdocs build
- - uses: actions/upload-artifact@v3
- with:
- name: site
- path: site
+ - run: cd learning ; poetry build
 
  build-rust:
  runs-on: ubuntu-latest
@@ -61,6 +41,7 @@ jobs:
  with:
  command: build
  args: --release --all-features
+
  docs-rust:
  needs: build-rust
  runs-on: ubuntu-latest
@@ -73,15 +54,35 @@ jobs:
  toolchain: stable
  override: true
  components: rust-docs
- - name: Build marcopolo-rs docs
- working-directory: learning/demos/marcopolo-rs
- run: cargo doc --no-deps --all-features --release --target-dir docs/rust
+ - name: Doc
+ uses: actions-rs/cargo@v1
+ with:
+ command: doc
+ args: --no-deps --target-dir=docs/api
+
+ docs-site:
+ needs: docs-rust
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
+ - name: Setup Python
+ uses: actions/setup-python@v3
+ - run: pip install -r docs/requirements.txt
+ - name: Export notebooks as examples
+ run: make ipynb2md
+ - name: MkDocs build
+ run: mkdocs build
+ - uses: actions/upload-artifact@v3
+ with:
+ name: site
+ path: site
 
  docs-deploy:
  if: github.ref == 'refs/heads/main'
- needs:
- - docs-python
- - docs-rust
+ needs: docs-site
  # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
  permissions:
  pages: write # to deploy to Pages

Makefile

@@ -1,15 +1,15 @@
-NOTEBOOKS ?= learning/notebooks/
-PYTHON_DOCS ?= docs/python/notebooks/
+SRC ?= learning/SRC/
+DEST ?= docs/SRC/
 
 define ipynb-to-md
- jupyter nbconvert $(join $(NOTEBOOKS), $(1).ipynb) --to html ;
- mv $(join $(NOTEBOOKS), $(1).html) $(join $(PYTHON_DOCS), $(1).md) ;
+ jupyter nbconvert $(join $(SRC), $(1).ipynb) --to html ;
+ mv $(join $(SRC), $(1).html) $(join $(DEST), $(1).md) ;
 endef
 
 ipynb2md:
- mkdir -p $(PYTHON_DOCS)
+ mkdir -p $(DEST)
  $(foreach nb, \
- $(basename $(notdir $(wildcard $(NOTEBOOKS)*.ipynb))), \
+ $(basename $(notdir $(wildcard $(SRC)*.ipynb))), \
  $(call ipynb-to-md, $(nb)) \
  )
- cp $(NOTEBOOKS)*.png $(PYTHON_DOCS)
+ cp $(SRC)*.png $(DEST)

README.md

@@ -21,50 +21,47 @@ Lunar Reference Frame.
 
 **Documentation is available at [philiplinden.github.io/clocss-abm](https://philiplinden.github.io/clocss-abm/).**
 
-## Getting Started with Python
+## Quickstart
 
-### Setup
+Install the dependencies for your operating system that are needed to run Bevy: [The Bevy Book - Setup](https://bevyengine.org/learn/book/getting-started/setup/)
 
-Install dependencies to a virtual environment using Python Poetry.
+Then run the project.
+```shell
+cargo run
+```
+
+## Learning
+Learning is one of the main objectives of this project. As such, several code demos and iPy notebooks can be found in
+the `learning` directory.
+
+The repository contains a mix of Python and Rust. See [the docs](https://philiplinden.github.io/clocss-abm) for more
+discussion on code architectures for this project. It's been an exploration with surprising twists.
+
+There are two Python demo models that run interactively in the browser. Install dependencies to a virtual environment
+using [Python Poetry](https://python-poetry.org/). Poetry is then used to spin up the demo projects.
+
+From the `learning` directory:
 ```shell
 # install python poetry
 pip install poetry
 
 # install all dependencies
 poetry install
 ```
-
-### Usage
-There are two demo models that run interactively in the browser.
-
-#### Orbits
-The Orbits model uses Nyx to spawn a collection of satellites and propagate their
+The **Orbits** model uses Nyx to spawn a collection of satellites and propagate their
 trajectories. Mesa is used to set up and execute the simulation.
 
 ```shell
 poetry run mesa runserver learrning/demos/orbits
 ```
 
-#### Marco Polo
-The Marco Polo model uses Mesa to spawn a collection of agents to play the
+The **Marco Polo** model uses Mesa to spawn a collection of agents to play the
 children's game _Marco Polo_.
 
 ```shell
 poetry run mesa runserver learning/demos/marcopolo
 ```
 
-## Getting Started with Rust
-
-### Setup
-Install the dependencies for your operating system that are needed to run Bevy:
-< link >
-
-### Usage
-
-```shell
-cargo run
-```
-
 ## Attribution
 
 This project borrows from example code provided by

docs/agents.md

@@ -0,0 +1,59 @@
+# Agents
+
+Agents are the generic term for “things with clocks” in this context. It might be a satellite, rover, ground station, etc. This section aims to identify the minimal set of traits that are required for agents in this model. Hopefully this will tease out areas of overlap between different types of agents and a blueprint for the model will take shape.
+
+## Attributes
+
+Some agents are attached to other entities, like ground stations or rovers. If an agent must translate and rotate together with another entity, that other entity is 
+
+### Mass
+
+Total mass of the agent in kg.
+
+### Clock Precision
+
+Likelihood of a missed or double counted tick of the clock
+
+### Radio Band
+
+An agent may only transmit or receive messages from other agents if the message is within the agent’s radio band.
+
+### Radio Field of View (FoV)
+
+An agent may only transmit or receive messages from other agents along a vector that originates at the agent* and lies within a cone** with a given field of view (FoV) angle. For example, an FoV of $2\pi$ would define an omnidirectional radio’s field of view.
+
+A message is only received if the message vector between the sender’s radio and receiver’s radio is completely encapsulated by both agents’ radio fields of view.
+
+*For simplicity’s sake, let’s assume agents are points with no shape.
+
+**A possible extension of this is to define the radio field of view as a set of lobes instead of a cone, but a cone is the simplest shape that meets this need.
+
+### Radio Transmitter Power
+
+Messages originating at the agent have an initial power (in dBm). The message signal power is distributed across the radio’s entire field of view. Signal power falls off with the inverse square law.
+
+### Radio Receiver Noise Floor
+
+The power (in dBm) of an agent’s receiver’s noise floor.
+
+### Radio Receiver Sensitivity
+
+An agent may only detect a message if the instantaneous signal power at the receiver is greater than a certain threshold. The ratio between the signal power and the noise floor power is the signal-to-noise ratio (SNR). Receiver sensitivity is the minimum SNR that results in a message being received, otherwise a message is “dropped” or ignored by the receiver.
+
+## States
+
+### Position, Velocity, and Acceleration
+
+Agents exist in a 2D or 3D simulation space* and may translate across the space. Agents also have a heading and may rotate. Agents have translational and rotational velocity and accelerations. In short, I want some rigid body physics here. The agent may only change its velocity through accelerations.
+
+Accelerations may be imparted on an agent from itself (thrust) or the environment (gravity, collisions).
+
+*Obviously 3D space is the goal, but all fundamental principals can be demonstrated on a single 2D plane.
+
+### Clock Epoch
+
+Agents keep track of time with imperfect clocks. The agent’s observation of the epoch may diverge from the environment’s true epoch.
+
+### Stratum
+
+How far removed from canonical time source.

docs/structure.md → docs/design-decisions.md

@@ -1,54 +1,84 @@
-# Model Structure
-The code structure of the model will have a significant impact on its complexity
-and performance. It is important for complexity to be minimized and performance
-to be maximized in order for the results to be trusted and reproducible.
-
-## Entity-Component-System (ECS)
-
-An ECS architecture allows for a modular and scalable design, making it easier
-to manage the simulation's complexity. Components store data, and systems
-operate on that data, while resources hold shared data needed across systems.
-This separation of concerns and data-driven approach is a key characteristic of
-ECS.
-
-![Unity ECS diagram](https://docs.unity3d.com/Packages/com.unity.entities@0.1/manual/images/ECSBlockDiagram.png)
-
-[Rust Example](https://github.com/bevyengine/bevy/blob/main/examples/ecs/ecs_guide.rs)
-
-In our simulation, the _schedule_ is critical. The engine or framework we choose
-will need to decide the order of operations each "tick" of the simulation, and
-we must consider this order when designing the system.
-
-## Choosing a Framework
-ECS frameworks like [Bevy](https://bevyengine.org/) enable real-time,
-interactive simulations, but it can be less deterministic and structured than a
-discrete-event simulation, since it is [not specially tailored for that purpose](https://github.com/bevyengine/bevy/discussions/1678).
-
-[krABMaga](https://krabmaga.github.io/)[^1] is a purpose-built discrete-events
-simulation engine writting in Rust and designed to be a batteries-included tool
-for building Agent-Based Models (ABMs). While krABMaga can leverage Bevy to
-visualize the model, under the hood it maintains a stricter state and execution
-schedule based on the popular [MASON library](https://cs.gmu.edu/~eclab/projects/mason/).
-
-![ECS in krABMaga](https://krabmaga.github.io/images/krabmaga-arch.jpg)
-
-In the end, both are ECS frameworks that can be used here. krABMaga adds some
-creature comforts but encourages a certain style. Bevy is the toolbox that can
-be used to build whatever you want, but elbow grease is a necessity. Since both
-are ECS frameworks, our model can be built from first principles and we can
-decide how to run and visualize it later. We might find that the best approach
-is using both together.
-
-[^1]: ```bibtex
-@ARTICLE{AntelmiASIASIM2019,
- author={Antelmi, A. and Cordasco, G. and D’Auria, M. and De Vinco, D. and Negro, A. and Spagnuolo, C.},
- title={On Evaluating Rust as a Programming Language for the Future of Massive Agent-Based Simulations},
- journal={Communications in Computer and Information Science},
- note={Conference of 19th Asia Simulation Conference, AsiaSim 2019 ; Conference Date: 30 October 2019 Through 1 November 2019; Conference Code:233729},
- year={2019},
- volume={1094},
- pages={15-28},
- doi={10.1007/978-981-15-1078-6_2},
- issn={18650929},
- isbn={9789811510779},
-}```
+# Design Decisions
+The code structure of the model will have a significant impact on its complexity
+and performance. It is important for complexity to be minimized and performance
+to be maximized in order for the results to be trusted and reproducible.
+
+## Rust, not Python
+I am an intermediate-advanced Python developer. I have absolute faith in my ability to build something at least
+marginally functional to meet the goals I set out to achieve with this project. In fact, I already used python in this
+project to illustrate core concepts and practice thinking through the problem.
+
+But I chose Rust for this project, not Python.
+
+The primary motivator here is personal growth. I have been looking for a reason to learn Rust for years. This project
+affords me low stakes (consequence of failure is ruined pride and that's it), a flexible deadline (no dependents), and a
+use case that potentially demands a performant engine to drive it. The conditions are right for me to push outside my
+comfort zone and dive head first into the deep end of Rust development.
+
+So far it has certainly been slower (and more tedious) to create functional demos in Rust compared to Python. Part of
+that is definitely from me climbing the (steep af) learning curve, and part is inherent to the tenets of Rust that give
+it all those superpowers.
+
+I have dipped into Python to "think out loud" and it has been fruitful. My familiarity and comfort working with Rust
+projects has dramatically improved in the last month, and I quite enjoy it.
+
+I think it was a wise choice in the long run to go with Rust over python for this project.
+
+## Entity-Component-System (ECS)
+An ECS architecture allows for a modular and scalable design, making it easier
+to manage the simulation's complexity. Components store data, and systems
+operate on that data, while resources hold shared data needed across systems.
+This separation of concerns and data-driven approach is a key characteristic of
+ECS. It is a natural fit for a Rust project.
+
+![Unity ECS diagram](https://docs.unity3d.com/Packages/com.unity.entities@0.1/manual/images/ECSBlockDiagram.png)
+
+[Rust Example](https://github.com/bevyengine/bevy/blob/main/examples/ecs/ecs_guide.rs)
+
+In our simulation, the _schedule_ is critical. The engine or framework we choose
+will need to decide the order of operations each "tick" of the simulation, and
+we must consider this order when designing the system.
+
+## Choosing a Framework
+### ECS & ABM
+ECS frameworks like [Bevy](https://bevyengine.org/) enable real-time,
+interactive simulations, but it can be less deterministic and structured than a
+discrete-event simulation, since it is [not specially tailored for that purpose](https://github.com/bevyengine/bevy/discussions/1678).
+
+[krABMaga](https://krabmaga.github.io/)[^1] is a purpose-built discrete-events
+simulation engine writting in Rust and designed to be a batteries-included tool
+for building Agent-Based Models (ABMs). While krABMaga can leverage Bevy to
+visualize the model, under the hood it maintains a stricter state and execution
+schedule based on the popular [MASON library](https://cs.gmu.edu/~eclab/projects/mason/).
+
+![ECS in krABMaga](https://krabmaga.github.io/images/krabmaga-arch.jpg)
+
+In the end, both are ECS frameworks that can be used here. krABMaga adds some
+creature comforts but encourages a certain style. Bevy is the toolbox that can
+be used to build whatever you want, but elbow grease is a necessity. Since both
+are ECS frameworks, our model can be built from first principles and we can
+decide how to run and visualize it later. We might find that the best approach
+is using both together.
+
+[^1]: ```bibtex
+@ARTICLE{AntelmiASIASIM2019,
+ author={Antelmi, A. and Cordasco, G. and D’Auria, M. and De Vinco, D. and Negro, A. and Spagnuolo, C.},
+ title={On Evaluating Rust as a Programming Language for the Future of Massive Agent-Based Simulations},
+ journal={Communications in Computer and Information Science},
+ note={Conference of 19th Asia Simulation Conference, AsiaSim 2019 ; Conference Date: 30 October 2019 Through 1 November 2019; Conference Code:233729},
+ year={2019},
+ volume={1094},
+ pages={15-28},
+ doi={10.1007/978-981-15-1078-6_2},
+ issn={18650929},
+ isbn={9789811510779},
+}```
+
+### Astrodynamics
+- **[nyx_space](https://nyxspace.com/)**. The documentation is... sparse. Expect to spend a lot of time in the source
+ code or DMing the author. There is a wide set of tools tailored specifically for LEO missions up to lunar
+ trajectories, including thrust maneuvers and simulated orbit determination from terrestrial ground stations.
+- **[particular](https://particular.rs/)**. Easy to get the demos running and the demos are beautiful. I found it
+ surprisingly difficult to adapt the demos to my own use cases, despite the apparently simple interface. The demos are
+ top tier examples of Bevy and egui. The simulation results "look right" but I was not able to set up a physically
+ representative system to test accuracy.