Skip to content

Commit

Permalink
fix references to missing mission model docs (#129)
Browse files Browse the repository at this point in the history
* fix references to missing mission model docs

* Changed old firesat references to new examples in mission model template

* update references to mission model example (removed firesat)

* update more firesat references to missionmodel

* update mission modeling introduction to link to tutorial

* use better URL to link to mission model tutorial page

* remove references to firesat

---------

Co-authored-by: Ferguson, Eric W (397B) <[email protected]>
Co-authored-by: Dan Delany <[email protected]>
  • Loading branch information
3 people authored Mar 4, 2024
1 parent ac1b875 commit c99e80a
Show file tree
Hide file tree
Showing 6 changed files with 21 additions and 20 deletions.
8 changes: 4 additions & 4 deletions docs/mission-modeling/activity-types/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ An **activity type** defines a simulated behavior that may be invoked by a plann
Activity types may define **parameters**, which are filled with **arguments** by a planner and provided to the activity upon execution.
Activity types may also define **validations** for the purpose of informing a planner when the parameters they have provided may be problematic.

For example, here is a simple activity type from the FireSat template mission model:
For example, here is a simple activity type from the examples in the template mission model:

<RemoteCodeBlock
language="java"
showLineNumbers
title="Aerie Mission Model Template (FireSat) - GncChangeControlMode.java"
url="https://raw.githubusercontent.com/NASA-AMMOS/aerie-mission-model-template/main/src/main/java/firesat/activities/gnc/GncChangeControlMode.java"
title="Aerie Mission Model Template - CollectData.java"
url="https://raw.githubusercontent.com/NASA-AMMOS/aerie-mission-model-template/main/examples/CollectData.java"
></RemoteCodeBlock>

Aerie automatically generates parameter serialization boilerplate for every activity type defined in the mission model's [package-info.java](../introduction.mdx#the-package-infojava-file).
Expand All @@ -23,7 +23,7 @@ Moreover, the generated Model base class provides helper methods for spawning ea
In order for Aerie to detect an activity type, its class must be annotated with the `@ActivityType` tag. An activity type is declared with its name using the following annotation:

```java
@ActivityType("GncChangeControlMode")
@ActivityType("CollectData")
```

By doing so, the Aerie annotation processor can discover all activity types declared in the mission model, and validate that activity type names are unique.
Expand Down
8 changes: 4 additions & 4 deletions docs/mission-modeling/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,18 @@ A **mission model configuration** enables mission modelers to set initial missio

To use a mission model configuration the `@WithConfiguration` annotation must be used within the mission model's [package-info.java](./introduction.mdx#the-package-infojava-file) to register the configuration with Aerie.

For example, the Aerie mission model template [package-info.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/firesat/package-info.java) makes use of this annotation:
For example, the Aerie mission model template [package-info.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/missionmodel/package-info.java) makes use of this annotation:

```java
@MissionModel(model = Mission.class)
@WithConfiguration(Configuration.class)
package firesat;
package missionmodel;

import gov.nasa.jpl.aerie.merlin.framework.annotations.MissionModel;
import gov.nasa.jpl.aerie.merlin.framework.annotations.MissionModel.WithConfiguration;
```

In this example `Configuration` is the class class containing all mission model configuration data. When the `@WithConfiguration` annotation is used, the model – defined within the `@MissionModel` annotation – must accept the configuration as the last constructor parameter. See [Mission.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/firesat/Mission.java):
In this example `Configuration` is the class class containing all mission model configuration data. When the `@WithConfiguration` annotation is used, the model – defined within the `@MissionModel` annotation – must accept the configuration as the last constructor parameter. See [Mission.java](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/src/main/java/missionmodel/Mission.java):

```java
public Mission(final Registrar registrar, final Configuration config) {
Expand All @@ -44,7 +44,7 @@ Similarly to activities, the annotation processor will take care of all serializ
A `Configuration` can be a simple data class. For example:

```java
package firesat;
package missionmodel;

import gov.nasa.jpl.aerie.merlin.framework.annotations.Export;
import java.nio.file.Path;
Expand Down
15 changes: 9 additions & 6 deletions docs/mission-modeling/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,22 @@ In Aerie, a mission model serves activity planning needs in two ways. First, it

## Creating a Mission Model

You can create your first mission model by using our [GitHub template mission model repository](https://github.com/NASA-AMMOS/aerie-mission-model-template).
See the template mission model repository [README](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/README.md#aerie-mission-model-template) for detailed build instructions.
If you want to learn how to develop a mission model, head to our [mission modeling tutorial](../../tutorials/mission-modeling/introduction/),
or check out our [GitHub template mission model repository](https://github.com/NASA-AMMOS/aerie-mission-model-template) for an empty template.
You will need a public [GitHub.com](https://github.com/) account to download the Aerie Maven packages.

If you do not want to develop a mission model and just want to try an example, you can download the [missionmodel.jar](https://github.com/NASA-AMMOS/aerie-modeling-tutorial/blob/main/missionmodel.jar) from the [Aerie modeling tutorial repository](https://github.com/NASA-AMMOS/aerie-modeling-tutorial).
Make sure you note where you downloaded the `.jar` file as you will need to browse to that location in the UI.

## The package-info.java File

A mission model must contain a [package-info.java](https://www.baeldung.com/java-package-info) file containing annotations that describe the highest-level features of the mission model. For example:

<RemoteCodeBlock
language="java"
showLineNumbers
title="Aerie Mission Model Template (FireSat) - package-info.java"
url="https://raw.githubusercontent.com/NASA-AMMOS/aerie-mission-model-template/main/src/main/java/firesat/package-info.java"
title="Aerie Mission Model Template - package-info.java"
url="https://raw.githubusercontent.com/NASA-AMMOS/aerie-mission-model-template/main/src/main/java/missionmodel/package-info.java"
></RemoteCodeBlock>

This `package-info.java` identifies the top-level class representing the mission model, and registers activity types that may interact with the mission model. Aerie processes these annotations at compile-time, generating a set of boilerplate classes which take care of interacting with the Aerie system.
Expand All @@ -35,8 +38,8 @@ The top-level model is received by activities, however, so it must make accessib
<RemoteCodeBlock
language="java"
showLineNumbers
title="Aerie Mission Model Template (FireSat) - Mission.java"
url="https://raw.githubusercontent.com/NASA-AMMOS/aerie-mission-model-template/main/src/main/java/firesat/Mission.java"
title="Aerie Mission Model Template - Mission.java"
url="https://raw.githubusercontent.com/NASA-AMMOS/aerie-mission-model-template/main/src/main/java/missionmodel/Mission.java"
></RemoteCodeBlock>

Mission resources are declared using `Registrar#discrete` or `Registrar#real` functions.
Expand Down
4 changes: 2 additions & 2 deletions docs/planning/upload-mission-model.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ To get the Aerie services running locally first follow the [fast track instructi

## Instructions

1. First develop your mission model using the [mission modeling documentation](../../mission-modeling/introduction). If you want to learn how to develop a mission model, head to our [mission modeling tutorial](../../tutorials/mission-modeling). If you do not want to develop a mission model and just want to try an example, you can download the [missionmodel.jar](https://github.com/NASA-AMMOS/aerie-modeling-tutorial/blob/main/missionmodel.jar) from the [Aerie modeling tutorial repository](https://github.com/NASA-AMMOS/aerie-modeling-tutorial). Make sure you note where you downloaded the `.jar` file as you will need to browse to that location in the UI.
1. First develop your mission model using the [mission modeling documentation](../../mission-modeling/introduction). If you want to learn how to develop a mission model, head to our [mission modeling tutorial](../../tutorials/mission-modeling/introduction). If you do not want to develop a mission model and just want to try an example, you can download the [missionmodel.jar](https://github.com/NASA-AMMOS/aerie-modeling-tutorial/blob/main/missionmodel.jar) from the [Aerie modeling tutorial repository](https://github.com/NASA-AMMOS/aerie-modeling-tutorial). Make sure you note where you downloaded the `.jar` file as you will need to browse to that location in the UI.

1. Navigate to the `/models` page in the Aerie UI. If you are running Aerie locally it is at [http://localhost/models](http://localhost/models).

1. Use the form on the `/models` page to upload the mission model `.jar` file. Give the mission model a name ("FireSat" in this example). The version can be any string (preferably a semantic version string like `1.0.0`). After you fill in all the fields click the 'Create' button to upload the model. Here is a video demonstration:
1. Use the form on the `/models` page to upload the mission model `.jar` file. Give the mission model a name ("MissionModel" in this example). The version can be any string (preferably a semantic version string like `1.0.0`). After you fill in all the fields click the 'Create' button to upload the model. Here is a video demonstration:

<video controls>
<source src={uploadMissionModel} type="video/webm" />
Expand Down
3 changes: 1 addition & 2 deletions docs/tutorials/mission-modeling/first-build.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Mission models require a couple of standard items for Aerie to process the model
1. A [`package-info.java`](https://nasa-ammos.github.io/aerie-docs/mission-modeling/introduction/#the-package-infojava-file) file containing a reference to the top-level mission model class, annotations referencing any activities defined in the model, an annotation referencing a configuration class that can expose configuration parameters that can be varied prior to simulation, and import statements to the Aerie modeling framework to bridge the framework to the model.
2. The top-level [mission model class](https://ammos.nasa.gov/aerie-docs/mission-modeling/introduction/#the-mission-model-class) that defines or delegates the behavior of the system being described in the model. Any quantity or state that you would like to track over the course of the simulation - which we define as a [**Resource**](https://ammos.nasa.gov/aerie-docs/mission-modeling/resources-and-models/) - should be declared and defined in this class or its delegates. The name of the top-level mission class can be anything as long as it matches the reference in `package-info.java`.

Fortunately, to save you some trouble, we've created a [mission model template repository](https://github.com/NASA-AMMOS/aerie-mission-model-template) that already has these items included for you along with a gradle build setup that takes care of including the right Aerie dependencies to get your mission model `.jar` file built hassle-free. In this repository, if you take a look in [`src/main/java/missionmodel`](https://github.com/NASA-AMMOS/aerie-mission-model-template/tree/main/src/main/java/firesat), you'll see the `package-info.java` file along with the top-level `Mission` and `Configuration` classes already defined for you.
Fortunately, to save you some trouble, we've created a [mission model template repository](https://github.com/NASA-AMMOS/aerie-mission-model-template) that already has these items included for you along with a gradle build setup that takes care of including the right Aerie dependencies to get your mission model `.jar` file built hassle-free. In this repository, if you take a look in [`src/main/java/missionmodel`](https://github.com/NASA-AMMOS/aerie-mission-model-template/tree/main/src/main/java/missionmodel), you'll see the `package-info.java` file along with the top-level `Mission` and `Configuration` classes already defined for you.

On the main page for the [mission model template repository](https://github.com/NASA-AMMOS/aerie-mission-model-template), click the "Use this template" button on the top right of the page and select "Create a new repository" to create a new repository for your SSR model. Clone your new repository and follow the instructions in the [`README.md`](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/README.md) to setup your environment and test out building a mission model `.jar` from the model. You'll find the `.jar` you built within a `build/libs` directory generated as part of the gradle build.

Expand All @@ -16,5 +16,4 @@ TODO:
- Update mission model template to align with David's new framework
- Account for his register in the Mission class
- Update dependencies in build.gradle
- Change name from firesat to missionmodel
- Remove activities/resources from the template (If they want content they could use the tutorial repo or other examples we provide)
3 changes: 1 addition & 2 deletions docs/tutorials/mission-modeling/mission-modeling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Mission models require a couple of standard items for Aerie to process the model
1. A [`package-info.java`](https://nasa-ammos.github.io/aerie-docs/mission-modeling/introduction/#the-package-infojava-file) file containing a reference to the top-level mission model class, annotations referencing any activities defined in the model, an annotation referencing a configuration class that can expose configuration parameters that can be varied prior to simulation, and import statements to the Aerie modeling framework to bridge the framework to the model.
2. The top-level [mission model class](https://ammos.nasa.gov/aerie-docs/mission-modeling/introduction/#the-mission-model-class) that defines or delegates the behavior of the system being described in the model. Any quantity or state that you would like to track over the course of the simulation - which we define as a [**Resource**](https://ammos.nasa.gov/aerie-docs/mission-modeling/resources-and-models/) - should be declared and defined in this class or its delegates. The name of the top-level mission class can be anything as long as it matches the reference in `package-info.java`.

Fortunately, to save you some trouble, we've created a [mission model template repository](https://github.com/NASA-AMMOS/aerie-mission-model-template) that already has these items included for you along with a gradle build setup that takes care of including the right Aerie dependencies to get your mission model `.jar` file built hassle-free. In this repository, if you take a look in [`src/main/java/missionmodel`](https://github.com/NASA-AMMOS/aerie-mission-model-template/tree/main/src/main/java/firesat), you'll see the `package-info.java` file along with the top-level `Mission` and `Configuration` classes already defined for you.
Fortunately, to save you some trouble, we've created a [mission model template repository](https://github.com/NASA-AMMOS/aerie-mission-model-template) that already has these items included for you along with a gradle build setup that takes care of including the right Aerie dependencies to get your mission model `.jar` file built hassle-free. In this repository, if you take a look in [`src/main/java/missionmodel`](https://github.com/NASA-AMMOS/aerie-mission-model-template/tree/main/src/main/java/missionmodel), you'll see the `package-info.java` file along with the top-level `Mission` and `Configuration` classes already defined for you.

On the main page for the [mission model template repository](https://github.com/NASA-AMMOS/aerie-mission-model-template), click the "Use this template" button on the top right of the page and select "Create a new repository" to create a new repository for your SSR model. Clone your new repository and follow the instructions in the [`README.md`](https://github.com/NASA-AMMOS/aerie-mission-model-template/blob/main/README.md) to setup your environment and test out building a mission model `.jar` from the model. You'll find the `.jar` you built within a `build/libs` directory generated as part of the gradle build.

Expand All @@ -32,7 +32,6 @@ TODO:
- Update mission model template to align with David's new framework
- Account for his register in the Mission class
- Update dependencies in build.gradle
- Change name from firesat to missionmodel
- Remove activities/resources from the template (If they want content they could use the tutorial repo or other examples we provide)

## Your First Resource
Expand Down

0 comments on commit c99e80a

Please sign in to comment.