WIP procedural scheduling docs

docs/overview/concept-of-operations.mdx

@@ -12,8 +12,8 @@ Aerie is designed to address the following capability gaps:
 - Allow missions to provide a web deployment of a planning tool such that operators with limited programming skills can create valid activity plans and run simulations
 - Support real time collaboration and and parallel hypothesis testing such that many more iterations of an activity plan can be tested within the same time frame
 - Allow automation and manual modifications to coexist throughout the planning process
-- Provide a low-code constraint checking mechanism to validate simulation outputs which can be largely automated
-- Provide a low-code scheduling mechanism that can scaffold parts of or generate complete activity plans according to goal snippets
+- Provide a flexible constraint checking mechanism to validate simulation outputs which can be largely automated
+- Provide a flexible scheduling mechanism that can scaffold parts of or generate complete activity plans according to goal snippets
 - Support an easy-to-use and verified translation from activities to sequences of commands that are recognized by the flight system
 
 Note that none of the capabilities above are completely new. Other software solutions have offered pieces of the listed capabilities in different or more limited flavors. Aerie's mission is to cover as many key steps in the whole activity planning and sequencing workflow in one deployed tool with dedicated components.

docs/overview/software-design-document.mdx

@@ -892,7 +892,7 @@ DSL, Merlin has little to no ability to see the actual Java code
 comprising a mission model. Merlin must instead make inferences about
 the mission model based on its observable behavior.
 
-Merlin is a spiritual successor to the 
+Merlin is a spiritual successor to the
 [Blackbird](https://trs.jpl.nasa.gov/handle/2014/52245) planning
 system, which similarly uses Java for activity and resource modeling.
 Blackbird's design shed light on the myriad choices made in designing
@@ -1225,7 +1225,7 @@ constraint expression operators, while the leaf nodes represent the
 operands. For example, operator nodes enable expressions such as 'or',
 'and', 'less than', 'greater than', while the operands are simulated
 resource profiles and activity instances. See our [constraints
-documentation](../../constraints/examples) for complete examples.
+documentation](../../scheduling-and-constraints/edsl/constraints/examples) for complete examples.
 
 ## Meta-Programming (Annotations Processing)
 

docs/scheduling/introduction.mdx → docs/scheduling-and-constraints/declarative/scheduling/introduction.mdx

@@ -1,8 +1,8 @@
 # Scheduling
 
-This guide explains how to use the scheduling service with the latest version of Aerie.
+This guide explains how to use the declarative scheduling service with Aerie.
 The scheduling service allows you to add activities to a plan based on goals that you define (this is something called "goal based scheduling").
-Goals are defined in [TypeScript](https://www.typescriptlang.org/) using an embedded domain specific language (EDSL) provided by Aerie.
+Declarative Goals are defined in [TypeScript](https://www.typescriptlang.org/) using an embedded domain specific language (EDSL) provided by Aerie.
 
 :::note
 

docs/scheduling/run-scheduling.mdx → docs/scheduling-and-constraints/execution.mdx

@@ -1,35 +1,11 @@
-# Run Scheduling
+# Execution
 
-## Scheduling Specification
+## Constraints
 
-After you have created one or several goals, you will see them in the scheduling pane of the plan in Aerie UI.
+Constraints can be checked inside the main plan view by opening the `Constraints` pane and clicking the checklist icon
+in the top right of the pane. Alternatively, you can hover over `Constraints` in the top bar and click "Check Constraints".
 
-The Aerie scheduler accepts a list of goals, and tries to satisfy them one by one by adding activities to your plan. We refer to this list of goals as a **scheduling specification**. Aerie creates one scheduling specification per plan. A goal's priority is a number reflecting that goal's position in the scheduling specification. The first goal will always have priority `0`, and the n-th goal will always have priority `n - 1`. Within a scheduling specification, a scheduling goal can be toggled enabled or disabled. A disabled scheduling goal will be excluded from scheduling execution. The priority ordering of the scheduling goals remains unchanged whether a goal is enabled or disabled.
-
-import schedulingSpecification from './assets/scheduling-specification.png';
-
-<figure>
-  <img alt="Aerie UI - Scheduling Specification" src={schedulingSpecification} />
-  <figcaption>Figure 1: Aerie UI Scheduling Specification</figcaption>
-</figure>
-
-In this image, you can see a specification with three goals. Goal 1 has priority `0`, and goal 3 has priority `2`. You can modify the priorities directly by typing numbers or use the arrows. You can disable a goal by toggling it off with the checkbox.
-
-:::caution
-
-You must use priorities in the `[0, n-1]` range, `n` being the number of goals.
-
-:::
-
-:::caution
-
-A given goal may be a part of zero or one specification - goals may not be shared between multiple specifications. If you need to do this, make a copy of the goal.
-
-There may be at most one specification at a time associated with a given plan.
-
-:::
-
-## Running the Scheduler
+## Scheduling
 
 To run the scheduler, click on the play button:
 
@@ -71,7 +47,7 @@ import schedulingSuccess from './assets/scheduling-success.png';
 - `174` means that there are `174` activity directives that contribute to the satisfaction of the goal
 - `+3` means that 3 new activities have been inserted in the plan to satisfied the goal during the last scheduling run
 
-## Running a Scheduling Analysis
+### Running a Scheduling Analysis
 
 The scheduler has an analysis mode that will evaluate the satisfaction of goals but will not place any new activities. To run the scheduler in analysis mode, click on the "analysis" button:
 

docs/scheduling-and-constraints/introduction.mdx

@@ -0,0 +1,43 @@
+# Scheduling & Constraints
+
+Aerie provides related frameworks for defining constraints and scheduling new activities in the plan, and two implementations
+of those frameworks: one for arbitrary procedures that run on the JVM, and a legacy system based on a declarative Typescript eDSL
+(embedded Domain-Specific Language). Both frameworks are documented here, but new users are encouraged to focus on
+creating JVM procedures. The declarative eDSL is significantly less capable, and the difference in capabilities is only expected to
+grow.
+
+## Constraints
+
+Constraints represent what is nominal for a plan or mission model, and when executed, the UI will display "violations"
+whenever the plan or model is off-nominal. They don't alter the behavior of the simulation engine or scheduler; they
+just serve as a warning, indicating that some requirement - perhaps a flight rule - was broken.
+
+## Scheduling
+
+The scheduler allows users to automate the creation of new activities, to remove some cognitive load from planners. A
+scheduling specification contains a list of goals and rules with a priority order; during a scheduling run, they are
+executed one at a time, starting from a priority of 0 and increasing from there.
+
+### Procedural Goals
+
+Procedural goals directly edit the plan, creating new activities at definite (grounded) times. They
+can simulate potential changes to the plan, but aren't required to. In fact, a scheduling specification composed entirely
+of procedures might run in its entirety without performing any simulations, potentially at the cost of optimality or even
+soundness.
+
+### eDSL Goals
+
+eDSL goals are more declarative, in that they don't allow you to directly create grounded activities; instead they allow
+you to describe a pattern of activities that should be present in the plan. If the pattern isn't found, the goal tries to
+create it for you. Currently eDSL goals are simpler to write than procedural goals, for patterns that they can represent.
+Many goals are more complex than can be represented in the eDSL, and will have to be written as a procedure.
+
+### Global Conditions
+
+Global scheduling conditions (or sometimes just "conditions") are supplemental pieces of code that define when scheduling
+goals can and cannot place activities. They are incorporated into the solver when attempting to resolve conflicts as
+a substitute for constraints. This is because it is too difficult to respect constraints during scheduling; constraints
+only indicate that something went wrong, not what caused it or how to fix it. So in cases when the scheduler keeps violating
+constraints, users can create a condition as a heuristic to help it satisfy the constraint.
+
+Conditions will be accessible to scheduling rules, but will be non-binding.

docs/scheduling-and-constraints/management.mdx

@@ -0,0 +1,41 @@
+# Management
+
+## Creating and Updating
+
+The recommended setup is to store goals/rules/conditions/constraints (hereafter called "peripheral code")
+in one or more repositories outside Aerie, and uploading
+them either through the UI or the unofficial [Aerie CLI](https://github.com/NASA-AMMOS/aerie-cli).
+
+For example, after creating a new goal as described in the following pages, you can upload it with the CLI using
+`aerie-cli goals new <path/to/MyGoal.jar>`. A new goal will be created in Aerie with a default name of `MyGoal`.
+See `aerie-cli goals new --help` for more details, such as automatically
+associating it with a model or plan. To update a goal afterward, you can run `aerie-cli goals update <path/to/MyGoal.jar>`,
+assuming that the default name was not changed. The same works for Typescript eDSL declarations, and similar workflows
+will be implemented for constraints and conditions soon.
+
+## Model and Plan Association
+
+In Aerie, peripherals live independently of plans and models, and can be associated with
+any number of plans and models, or none at all. Each model and plan has a scheduling specification and a constraints
+specification, which is simply a list of peripherals to run during the scheduling or constraints actions, respectively.
+
+Model specifications are never run directly, and instead populate the default spec for any plans created from that model.
+So if a particular constraint is widely applicable to all plans made from a particular model, you can associate it with
+the model by navigating to `Models -> <select your model> -> Edit details ... -> Constraints -> Library`. Click the checkbox
+on your constraint and select `Save`. Now any new plans made with this model will include your constraint in its specification.
+
+Peripherals that don't apply to all plans for a model can be associated with individual plans too. In the main plan view,
+navigate to the `Scheduling Goals` or `Constraints` pane, then click `Manage`. Click the checkbox for your peripheral and
+select `Save`.
+
+Additionally, the Aerie CLI provides options when creating a new goal to associate it with a given model ID or plan ID.
+
+## Version Locking
+
+Peripheral associations can be locked to a specific revision, on either the model or plan specification. In the specification,
+you can change `Always use latest` to a revision number of your choice.
+
+## Deleting
+
+Peripherals can be deleted in the UI by navigating to the `Scheduling` or `Constraints` view in the top left, and deleting
+them there. This action can't be done if the peripheral is being used by a plan or model.

docs/scheduling-and-constraints/procedural/constraints.mdx

@@ -0,0 +1,2 @@
+# Constraints
+

docs/scheduling-and-constraints/procedural/getting-started.mdx

@@ -0,0 +1,27 @@
+# Getting Started
+
+Currently only scheduling procedures are supported, not constraint procedures.
+
+## Create a project from the template
+
+We have created a template repository for your mission model and scheduling procedures [here](https://github.com/NASA-AMMOS/aerie-mission-model-template).
+If you don't already have a mission model project, you can just copy that template and follow the instructions.
+If you do, you can follow these steps to add a place for your procedures:
+
+1. Move your mission model code into a gradle subproject if it isn't already.
+2. Create a `scheduling` subproject.
+3. Copy the `build.gradle` from the `scheduling` subproject of the [mission model template repo](https://github.com/NASA-AMMOS/aerie-mission-model-template).
+4. You can now create procedures in a java package in the `scheduling` subproject, as long as the package path ends in `procedures`.
+   (i.e. `src/main/java/myorg/mymission/procedures`)
+
+## Compiling
+
+It is a two-part process to build your scheduling jars.
+1. Run `./gradlew :scheduling:compileJava` (or any command that delegates to it, such as `:scheduling:build` or a top-level `build`).
+2. Run `./gradlew :scheduling:buildAllSchedulingProcedureJars`. This produces the jar artifacts for each procedure.
+
+There should now be one jar for each scheduling procedure, at `scheduling/build/libs/<OriginalSourceCodeFileName>.jar`.
+
+## Creating a Goal
+
+See the examples in the mission model template repo, or see [the scheduling page](../scheduling) in this section.

docs/scheduling-and-constraints/procedural/introduction.mdx

@@ -0,0 +1,7 @@
+# Procedural Scheduling & Constraints
+
+Aerie allows users to write custom JVM procedures to check constraints or schedule new activities with complete freedom.
+Most users will choose to use Java, but since the libraries are written in Kotlin, they
+provide some quality-of-life improvements and syntactic sugar for those using Kotlin. Additionally, Kotlin's more intelligent
+type inference, null-safety, and currying syntax make writing peripheral procedures a more seamless experience, although
+the API is intended to work well with Java too.

docs/scheduling-and-constraints/procedural/parameterization.mdx

@@ -0,0 +1,3 @@
+# Parameterization
+
+TODO @mattdailis

docs/scheduling-and-constraints/procedural/plan-and-sim-results.mdx

@@ -0,0 +1,21 @@
+# The Plan & Simulation Results
+
+The two main interfaces you'll query data from are `Plan` and `SimulationResults`. In constraints, they are provided as
+separate objects, they are combined into one object called `EditablePlan`.
+
+## `Plan`
+
+The plan object contains information that defines the plan. It also provides utility functions for converting between
+java `Instant` objects and our `Duration` objects, which are relative to the start of the plan.
+
+The `plan.totalBounds()` method gives an interval that defines the extent of the plan. The whole plan might not be simulated,
+but the plan bounds won't change.
+
+The `plan.directives(...)` methods allow you to get the activity directive timelines that define the plan.
+`directives()` and `directives(type: String)` get a timeline of all directives or of just a specific activity type respectively;
+and it returns them as the generic `AnyDirective` representation. If you want to use a custom representation `A`, you can call
+`directives(type: String, deserializer: (SerializedValue) -> A)` and provide your own deserializer.
+
+The directives are always up-to-date, even if the simulation results aren't.
+
+## Simulation Results

docs/scheduling-and-constraints/procedural/running-externally.mdx

@@ -0,0 +1,3 @@
+# Running Externally
+
+TODO

docs/scheduling-and-constraints/procedural/scheduling.mdx

@@ -0,0 +1,2 @@
+# Scheduling
+

docs/scheduling-and-constraints/procedural/timelines/advanced/custom-operations.mdx

@@ -0,0 +1 @@
+# Custom Operations

docs/scheduling-and-constraints/procedural/timelines/advanced/custom-timelines.mdx

@@ -0,0 +1 @@
+# Custom Timelines

docs/scheduling-and-constraints/procedural/timelines/advanced/introduction.mdx

@@ -0,0 +1,3 @@
+# Advanced Timeline Concepts
+
+TODO

docs/scheduling-and-constraints/procedural/timelines/advanced/parallel-profiles.mdx

@@ -0,0 +1 @@
+# Parallel Profiles

docs/scheduling-and-constraints/procedural/timelines/basics/activities.mdx

@@ -0,0 +1,51 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Activities
+
+Activity timelines are the most common type of timeline that allow the objects to overlap. In most plans, activities
+of the same type won't overlap with each other, but you should never assume this in your code unless you have some
+algorithmic guarantee.
+
+There are two types of activity timelines: `Directives` and `Instances`. `Directives` are essentially the definition of
+the plan before simulation, and `Instances` are the results of simulation. They both contain the arguments that you gave
+them. `Directives` are instantaneous, since they haven't been simulated yet, but `Instance` objects have a duration.
+
+## `AnyDirective` and `AnyInstance`
+
+The activity timelines accept user-definable representations of the arguments, in their generic argument (i.e.
+`Directives<MyDirectiveType>`). In the future, we will implement support for linking to the mission model and directly
+using its activity types, but for now the only representations we provide are the `AnyDirective` and `AnyInstance` types.
+
+These representations give you flexibility at the cost of ergonomics. They store the arguments as `Map<String, SerializedValue>`
+(you can read about `SerializedValue` [here](/mission-modeling/activity-mappers/#what-is-a-serializedvalue)), which can be
+used for any activity type.
+
+For example, to get a timeline of `MyActivity`'s, where the `arg` argument is equal to `3`, you can do the following.
+(Filtering and querying from the plan are explained more later)
+
+<Tabs groupId="lang">
+<TabItem value="kt" label="Kotlin">
+
+```kotlin
+plan.directives("MyActivity")
+  .filter {
+    it.inner // this accesses the inner AnyDirective object
+      .arguments.get("arg").asInt().get() == 3
+  }
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+plan.directives("MyActivity")
+  .filter(
+    false,
+    $ -> $.inner // this accesses the inner AnyDirective object
+      .arguments.get("arg").asInt().get() == 3
+  )
+```
+
+</TabItem>
+</Tabs>