-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Procedural scheduling documentation (#184)
* Procedural scheduling docs * fix broken links in docs * Update deserialization docs * Clarify constraint edsl docs * No longer recommend CLI for goal upload * Link to generated kotlin docs * Hide unimplemented docs --------- Co-authored-by: dandelany <[email protected]>
- Loading branch information
1 parent
9d88646
commit 09819b5
Showing
57 changed files
with
1,347 additions
and
74 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
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
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
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
File renamed without changes.
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
Empty file.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes.
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
4 changes: 2 additions & 2 deletions
4
docs/scheduling/introduction.mdx → ...s/declarative/scheduling/introduction.mdx
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
File renamed without changes.
File renamed without changes.
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,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. |
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,37 @@ | ||
# 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 through the UI. | ||
|
||
For example, after creating a new goal as described in the following pages, you can upload it with the UI by selecting | ||
`New` on the `Scheduling` option in main top-left dropdown. Or, you can upload it with an automatic association with your | ||
plan by opening the `Scheduling Goals` pane in your plan, and navigating to `Manage Goals -> New`. Here you have the | ||
option to either upload a JAR file, or copy-paste a typescript eDSL file. | ||
|
||
## 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`. | ||
|
||
## 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. |
3 changes: 3 additions & 0 deletions
3
docs/scheduling-and-constraints/procedural/assets/duplicate-invocation.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions
3
docs/scheduling-and-constraints/procedural/assets/parameterized-goal.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.