Cache effects python-side and update docs

README.md

@@ -1,20 +1,23 @@
 # pymerlin
 
 <!-- start elevator-pitch -->
-A python modeling framework for Aerie.
+pymerlin is a discrete event simulation framework, built for use in the [Aerie](https://github.com/NASA-AMMOS/aerie>) ecosystem.
+
+To learn more about Aerie, read the [Aerie Docs](https://nasa-ammos.github.io/aerie-docs).
 <!-- end elevator-pitch -->
 
 ### TODO:
 
 - [ ] Daemon tasks
-- [ ] More interesting cells and resources
-- [x] Conditions on discrete cells
-- [ ] Conditions on continuous cells
+- [x] More interesting cells and resources
+- [x] Conditions on static cells
+- [x] Conditions on autonomous cells
 - [x] Child tasks
 - [ ] Spiceypy
 - [ ] JPL time
 - [ ] pip-installable models
 - [ ] build Aerie-compatible jars and provide docker-compose file with python
+- [ ] checkpoint restart
 
 ## Prerequisites
 
@@ -50,8 +53,13 @@ hybrid system, which may be more difficult to characterize.
 
 ## Building pymerlin.jar
 
+If any changes are made to the java code, rebuild the jar and place it in the correct location as follows:
+
 ```shell
-cd pymerlin-java
+cd java
 ./gradlew assemble
 mv pymerlin/build/libs/pymerlin.jar ../pymerlin/_internal/jars
-```
+```
+
+The jar lives inside of the `pymerlin` python source directory because that ensures that it will be packaged
+(and accessible) in a distribution.

docs-src/2_guides/build-jar.md

@@ -0,0 +1,3 @@
+# Build an Aerie-compatible JAR file
+
+This isn't yet supported! But this page will be populated as soon as it is.

docs-src/2_guides/index.md

@@ -9,4 +9,5 @@ powermodel
 telecom
 scheduling
 spice
+build-jar
 ```

docs-src/3_explanation/command-errors.md

@@ -9,14 +9,14 @@ A command error, sometimes called a command file error, describes the situation
 The consequence of a command error can range from lost opportunities (e.g. a spacecraft does not record data of a particular event of interest), to loss of mission (the spacecraft is permanently incapacitated).
 
 The flight system’s fault protection subsystem is designed to minimize the consequence of command error by putting the spacecraft into a “safe mode” when certain automatic fault detection, isolation, and recovery (FDIR) mechanisms are triggered. There are, however, command errors that FDIRs are powerless against:
-- CFDP 2 delayed packets (Clipper)
-- Incorrect inputs to maneuvers (Mars Climate Orbiter)
-- Unexpected failure modes of FSW (MSL sol 200)
-- Incorrect observation timings (I don’t have a specific example here)
-- Incorrect Earth vector values (Viking)
-- Concurrent communication of multiple spacecraft in a constellation (MMS)
-- Unintentional sequence deletes (MSL)
-- Sequences that don’t set a new parameter that was added in a new FSW version (MSL)
+- CFDP 2 delayed packets
+- Incorrect inputs to maneuvers
+- Unexpected failure modes of FSW
+- Incorrect observation timings
+- Incorrect Earth vector values
+- Concurrent communication of multiple spacecraft in a constellation
+- Unintentional sequence deletes
+- Sequences that don’t set a new parameter that was added in a new FSW version
 
 ## Avoiding Command Errors
 In order to reduce the risk of command error, the ground system may perform certain checks before allowing a message to be sent to the spacecraft. These checks range from constraints on the syntax of command files, to some abstract interpretation of the command files, to simulation of these command files. Some desirable characteristics of a ground system check:

docs-src/architecture.md

@@ -13,4 +13,21 @@ The main tenet of pymerlin is approachability, and its aim is to enable rapid pr
 While where possible, performance will be considered, it is expected that someone who wants to seriously engineer the
 performance of their simulation will port their code to Java - which has the double benefit of removing socket
 communication overhead, as well as giving the engineer a single Java process to instrument and analyze, rather than a
-hybrid system, which may be more difficult to characterize.
+hybrid system, which may be more difficult to characterize.
+
+## Round trips
+Some objects that the mission model provides to the simulation driver are _pass-through_ objects - i.e. the driver
+merely returns these objects to the mission model when it is appropriate to do so. These objects need not be converted
+to Java types - it is sufficient to pass a handle to the simulation driver, as long as the handle can be used to look
+up the original object when needed. This is why certain global variables exist in `_globals.py` - they are used to cache
+python objects and pass only their id to the Java process.
+
+:::{warning}
+As implemented, this can be a source of a memory leak. Some careful cleanup is required to make this approach viable
+for larger use cases 
+:::
+
+For resources and activity arguments (i.e. things that are represented as "SerializedValue" on the Java side), it is
+important _not_ to make use of the python cache. This will help with integrating a python mission model with the rest
+of the Aerie system by allowing the python code to handle inputs generated elsewhere in the system, and provide outputs
+that can be understood by the rest of the system.

docs-src/developer.md

@@ -7,4 +7,12 @@ For pymerlin development, you'll need:
 Additional libraries:
 - build (for packaging)
 - twine (for publishing)
-- pytest (for running tests)
+- pytest (for running tests)
+
+## Building pymerlin.jar
+
+```shell
+cd java
+./gradlew assemble
+mv pymerlin/build/libs/pymerlin.jar ../pymerlin/_internal/jars
+```

docs-src/documentation.md

@@ -12,4 +12,17 @@ make clean html
 
 This documentation is built using [sphinx](https://www.sphinx-doc.org/en/master/) with the [MyST](https://mystmd.org/)
 plugin, using the [Furo](https://pradyunsg.me/furo/) theme. Python docstrings are automatically parsed and included in
-this documentation using the [sphinx-autodoc2](https://sphinx-autodoc2.readthedocs.io) extension.
+this documentation using the [sphinx-autodoc2](https://sphinx-autodoc2.readthedocs.io) extension.
+
+## Style
+
+Refer to [https://developers.google.com/style](https://developers.google.com/style) for guidance. Any particularly salient points should be reproduced in this document.
+
+pymerlin is always lowercase. It may be styled as regular text or in a code block like this: `pymerlin` depending on the
+context.
+
+## Referencing Aerie
+
+pymerlin documentation should be self-contained for users who are not using an Aerie deployment - this means that
+some concepts will be repeated across pymerlin and Aerie documentation. In these scenarios, the relevant Aerie
+documentation page should be linked in a "Further reading" section at the bottom of the page. 

docs-src/index.md

@@ -4,17 +4,13 @@ hide-toc: true
 
 # pymerlin
 
-pymerlin is a discrete event simulation framework, built for use in the [Aerie](https://github.com/NASA-AMMOS/aerie>) ecosystem.
-
-To learn more about Aerie, read the [Aerie Docs](https://nasa-ammos.github.io/aerie-docs).
-
-Ready to get started? Check out the [Quickstart](./quickstart.md) guide.
-
 ```{include} ../README.md
 :start-after: <!-- start elevator-pitch -->
 :end-before: <!-- end elevator-pitch -->
 ```
 
+Ready to get started? Check out the [Quickstart](./quickstart.md) guide.
+
 ## Source code
 
 You can access the source code at: [https://github.com/mattdailis/pymerlin](https://github.com/mattdailis/pymerlin).

docs-src/quickstart.md

@@ -23,4 +23,4 @@ Check that the installation succeeded by running:
 python3 -c "import pymerlin; pymerlin.checkout()"
 ```
 
-If that succeeds, you're ready to get started with the [tutorial](1_tutorials/1_gettingstarted).
+If you see `pymerlin checkout successful: All systems GO 🚀`, you're ready to get started with the [tutorial](1_tutorials/1_gettingstarted).

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: dc8fc5ce81b9f5652bf3b83679e73bfb
+config: 8c5ea12c0d4f9c266bf0fec544c2a925
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/1_tutorials/1_gettingstarted.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="next" title="Going further" href="tutorial2.html" /><link rel="prev" title="Tutorials" href="index.html" />
 
     <!-- Generated with Sphinx 7.3.7 and Furo 2024.05.06 -->
-        <title>Getting Started - pymerlin 0.0.5 documentation</title>
+        <title>Getting Started - pymerlin 0.0.6 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=387cc868" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=36a5483c" />
@@ -179,7 +179,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../index.html"><div class="brand">pymerlin 0.0.5 documentation</div></a>
+      <a href="../index.html"><div class="brand">pymerlin 0.0.6 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -203,7 +203,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html">
 
 
-  <span class="sidebar-brand-text">pymerlin 0.0.5 documentation</span>
+  <span class="sidebar-brand-text">pymerlin 0.0.6 documentation</span>
 
 </a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -225,6 +225,7 @@
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/telecom.html">Modeling Telecom</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/scheduling.html">Scheduling</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/spice.html">Using spice for geometry</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../2_guides/build-jar.html">Build an Aerie-compatible JAR file</a></li>
 </ul>
 </li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../3_explanation/index.html">Background</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Background</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
@@ -485,7 +486,7 @@ <h2>Your First Resource<a class="headerlink" href="#your-first-resource" title="
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=282f96c0"></script>
+</div><script src="../_static/documentation_options.js?v=1fd71caa"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=4e2eecee"></script>

docs/1_tutorials/index.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="next" title="Getting Started" href="1_gettingstarted.html" /><link rel="prev" title="Quickstart" href="../quickstart.html" />
 
     <!-- Generated with Sphinx 7.3.7 and Furo 2024.05.06 -->
-        <title>Tutorials - pymerlin 0.0.5 documentation</title>
+        <title>Tutorials - pymerlin 0.0.6 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=387cc868" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=36a5483c" />
@@ -179,7 +179,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../index.html"><div class="brand">pymerlin 0.0.5 documentation</div></a>
+      <a href="../index.html"><div class="brand">pymerlin 0.0.6 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -203,7 +203,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html">
 
 
-  <span class="sidebar-brand-text">pymerlin 0.0.5 documentation</span>
+  <span class="sidebar-brand-text">pymerlin 0.0.6 documentation</span>
 
 </a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -225,6 +225,7 @@
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/telecom.html">Modeling Telecom</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/scheduling.html">Scheduling</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/spice.html">Using spice for geometry</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../2_guides/build-jar.html">Build an Aerie-compatible JAR file</a></li>
 </ul>
 </li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../3_explanation/index.html">Background</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Background</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
@@ -358,7 +359,7 @@ <h1>Tutorials<a class="headerlink" href="#tutorials" title="Link to this heading
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=282f96c0"></script>
+</div><script src="../_static/documentation_options.js?v=1fd71caa"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=4e2eecee"></script>

docs/1_tutorials/tutorial2.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="next" title="Guides" href="../2_guides/index.html" /><link rel="prev" title="Getting Started" href="1_gettingstarted.html" />
 
     <!-- Generated with Sphinx 7.3.7 and Furo 2024.05.06 -->
-        <title>Going further - pymerlin 0.0.5 documentation</title>
+        <title>Going further - pymerlin 0.0.6 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=387cc868" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=36a5483c" />
@@ -179,7 +179,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../index.html"><div class="brand">pymerlin 0.0.5 documentation</div></a>
+      <a href="../index.html"><div class="brand">pymerlin 0.0.6 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -203,7 +203,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html">
 
 
-  <span class="sidebar-brand-text">pymerlin 0.0.5 documentation</span>
+  <span class="sidebar-brand-text">pymerlin 0.0.6 documentation</span>
 
 </a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -225,6 +225,7 @@
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/telecom.html">Modeling Telecom</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/scheduling.html">Scheduling</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../2_guides/spice.html">Using spice for geometry</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../2_guides/build-jar.html">Build an Aerie-compatible JAR file</a></li>
 </ul>
 </li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../3_explanation/index.html">Background</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Background</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
@@ -348,7 +349,7 @@ <h1>Going further<a class="headerlink" href="#going-further" title="Link to this
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=282f96c0"></script>
+</div><script src="../_static/documentation_options.js?v=1fd71caa"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=4e2eecee"></script>