-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
4a492dc
commit 665c5c4
Showing
17 changed files
with
324 additions
and
536 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.