Aerie Mission Data Storage Architecture

[stalnikar]

Hello! I'm writing as part of a team working on building a mission operations toolkit and came across Aerie recently. The first aspect which was not entirely clear to me is how does Aerie access and store any mission specific data such as the orbit information and any specifications of the spacecraft required by the mission model. I see that the mission model is a JAR file with constituent classes of relevant attributes. I also referred to the FireSat template but I did not come across any files in the mission model which house specific information about the orbit, spacecraft, instruments etc. Is there a separate database which hosts this information (i.e. the values for these parameters) for Aerie to map the corresponding class attributes? Does this happen when the mission model is uploaded to the Aerie-UI? How does Aerie unpack the JAR mission model and map the data? Thanks and I look forward to a response. Since I'm posting the first message in the Q&A section, please let me know if there's another more applicable page where this should be posted instead.

[mattdailis]

Thanks and I look forward to a response. Since I'm posting the first message in the Q&A section, please let me know if there's another more applicable page where this should be posted instead.

This is a perfectly appropriate place to ask these questions! The other avenues for discussion are our slack channel and direct email.

how does Aerie access and store any mission specific data?

You’re spot on that the mission model is responsible for encoding mission-specific data. The way in which that data is encoded is somewhat up to the mission, and what level of fidelity they want to put into their model. Aerie expects missions to designate one Java class as their “model”, but the structure of that class is up to the specific mission.

A good example is the aerie-lander model, which is composed of a dozen sub-models, some of which refer to instruments, while others refer to other spacecraft subsystems or behaviors:
https://github.com/NASA-AMMOS/aerie-lander/blob/26ca46fee1b2d9b72c1b2ed7421f7433710d315c/src/main/java/gov/nasa/jpl/aerielander/Mission.java#L21

public final class Mission {
  public final Configuration config;
  public final Clocks clocks;
  public final DataModel dataModel;
  public final DSNModel dsnModel;
  public final WakeModel wakeModel;
  public final CommModel commModel;
  public final PowerModel powerModel;
  public final EngModel engModel;
  public final HeatProbeModel HeatProbeModel;
  public final IDSModel idsModel;
  public final APSSModel apssModel;
  public final SeisModel seisModel;

  public Mission(final Registrar registrar, final Instant planStart, final Configuration config) {
    this.config = config;
    this.clocks = new Clocks(Mars_Time_Origin);
    this.dataModel = new DataModel();
    this.dsnModel = new DSNModel();
    this.wakeModel = new WakeModel();
    this.commModel = new CommModel();
    this.powerModel = new PowerModel();
    this.engModel = new EngModel();
    this.HeatProbeModel = new HeatProbeModel();
    this.idsModel = new IDSModel();
    this.apssModel = new APSSModel();
    this.seisModel = new SeisModel();

Instrument capabilities, behaviors, and specifications can be encoded in these sub-models in Java code. These models can declare resources, and publish values to them throughout a simulation run. These resources can then be visualized in the UI or used to check constraints, or read into other tools.

Non-java files can also be included in a mission model using Java’s resources feature (not to be confused with Aerie’s resources) https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html This can be useful if aspects of the spacecraft specification are best expressed in a different file format. The mission model will need to include code that can parse that file, and use its contents to influence a simulation run.

Similarly, if there are files that describe an orbit (SPICE kernels, for example), these files can be uploaded to Aerie separately from the mission model. The mission model can be configured to read these files from the file system. This technique is useful if the orbit information is expected to be updated at a different cadence from the mission model itself - it allows the user to update one without updating the other.

Is there a separate database which hosts this information (i.e. the values for these parameters) for Aerie to map the corresponding class attributes?

Yes, absolutely - an Aerie deployment includes a postgres database that stores all of the data produced by planners - including the values for any activity parameters in a given plan. The mission model provides the set of activity type definitions, and a planner can choose from those activity types when they are working on a plan via the UI. Simulation results and constraint definitions are more examples of data stored in this database. One goal that Aerie set for itself is to move certain concepts, including constraints, out of the mission model and into the UI, which allows constraint definitions to be updated without necessarily updating the mission model as well.

Does this happen when the mission model is uploaded to the Aerie-UI?

When a mission model is uploaded, Aerie will load it, and ask it to provide its set of activity type definitions. These definitions are cached in the database, so that they can be referenced without re-loading the JAR.

How does Aerie unpack the JAR mission model and map the data?

Aerie expects the JAR to declare the services it provides using the Java service provider standard. In effect, that means it must contain a META-INF/services/gov.nasa.jpl.aerie.merlin.protocol.model.MerlinPlugin text file, whose contents designate the fully qualified name of the Java class in that JAR that implements the MerlinPlugin interface

aerie/merlin-sdk/src/main/java/gov/nasa/jpl/aerie/merlin/protocol/model/MerlinPlugin.java

Line 16 in f9cfe6f

public interface MerlinPlugin {

That interface defines all of the functionality that Aerie expects from a mission model. The top level of that interface is pretty sparse, but you can dig deeper into ModelType:

aerie/merlin-sdk/src/main/java/gov/nasa/jpl/aerie/merlin/protocol/model/ModelType.java

Lines 34 to 79 in f9cfe6f

	public interface ModelType<Config, Model> {
	/**
	* Gets the directive types supported by this model.
	*
	* @return
	* The family of named types of directive supported by this model.
	*/
	Map<String, ? extends DirectiveType<Model, ?, ?>> getDirectiveTypes();
	/**
	* Gets the configuration type accepted by this model.
	*
	* @return
	* The configuration type accepted by this model.
	*/
	InputType<Config> getConfigurationType();
	/**
	* Constructs a model instance with the given configuration, allocating cells from the given initializer.
	*
	* <p> <b>The returned model instance must be immutable.</b> All mutable state must be allocated via the provided
	* initializer. In turn, the initializer returns {@link gov.nasa.jpl.aerie.merlin.protocol.driver.CellId}s, which do
	* not contain the cell state, but rather identify the cell to the driver in future read/write interactions. This
	* makes it possible to give each concurrent task a transactional view of the model state, to resolve any concurrent
	* effects on state in a coherent way, and to identify which resources need to be recomputed based on when the cells
	* they are computed from are updated. </p>
	*
	* <p> The state of the resulting model instance can be evolved by either instantiating directives and running their
	* associated tasks, or by progressing time on the simulation-aware state allocated by the model instance. </p>
	*
	* <p> The model also exports resources and topics via the initializer. Notably, the exported resources and topics
	* must not vary with the configuration. The {@code ModelType} API may be changed in the future to enforce this. </p>
	*
	* @param planStart
	* The real-time instant against which the behavior of this model will be compared to other temporal data.
	* @param configuration
	* A configuration to instantiate this model with.
	* @param builder
	* An allocator to allocate cells with.
	* @return
	* An instance of this model.
	*/
	// TODO: Every model instance should export the same resources and topics, independent of any provided configuration.
	// Extract resource and topic registration from the `Initializer` to the top-level `ModelType`.
	Model instantiate(Instant planStart, Config configuration, Initializer builder);
	}

Notably, all Aerie expects from a mission model is

1. A way to get the full set of defined activity types
2. An “input type”, which defines the configuration options that the mission model exposes. Users can edit this configuration in the UI before running a simulation
3. A way to instantiate the mission model prior to simulation

   You can find a write-up of the data types used during simulation here: https://nasa-ammos.github.io/aerie-docs/mission-modeling/advanced-the-merlin-interface/ 


Most of these details are abstracted away by the mission modeling framework - annotating classes with the @ActivityType and related annotations helps the framework generate Java code that conforms to the MerlinPlugin interface. https://nasa-ammos.github.io/aerie-docs/mission-modeling/activity-types/introduction/

Thanks for the great questions, keep them coming! 🎉