Package gov.nasa.jpl.aerie.merlin.protocol

package gov.nasa.jpl.aerie.merlin.protocol

The interfaces and data types describing the interactions between a mission model and its external environment.

This package tree defines the foundational interfaces and data types for interactions between a mission model and the system interacting with it (generically referred to as a "driver"). A particular driver can leverage these interactions for various scenarios, including simulation; but these packages have little to say about how simulation is actually performed. Only, when a simulator needs to ask the model what its effect on the simulation is, it will use the interfaces defined here to make that request.

In addition, the MerlinPlugin interface provides a ServiceLoader-friendly service interface, as it hides the generic type parameters of an underlying ModelType. Implementors of the latter should typically also provide the former, for interoperability with plugin-based multi-mission systems such as an Aerie deployment.

A typical exchange for simulation will look something like the following.

• Driver obtains a MerlinPlugin (e.g. by reflection from a JAR).
• Driver calls MerlinPlugin.getModelType() to obtain the top-level ModelType.
• Driver calls ModelType.getConfigurationType() to obtain the InputType describing the model's configuration type.
• Driver calls InputType.instantiate(java.util.Map) to construct a configuration input.
• Driver calls ModelType.instantiate(java.time.Instant, java.lang.Object, gov.nasa.jpl.aerie.merlin.protocol.driver.Initializer) to construct a model instance, providing a Initializer.
  • Model calls Initializer.allocate(java.lang.Object, gov.nasa.jpl.aerie.merlin.protocol.model.CellType, java.util.function.Function, gov.nasa.jpl.aerie.merlin.protocol.driver.Topic) any number of times to allocate mutable internal state described by a CellType and subscribe it to an internal stream of events.
  • Model calls Initializer.daemon(gov.nasa.jpl.aerie.merlin.protocol.driver.Initializer.TaskFactory) any number of times to spawn internal Tasks independent of any external directive.
  • Model calls Initializer.resource(java.lang.String, gov.nasa.jpl.aerie.merlin.protocol.model.Resource) any number of times to register an observable Resource.
  • Model calls Initializer.topic(java.lang.String, gov.nasa.jpl.aerie.merlin.protocol.driver.Topic, gov.nasa.jpl.aerie.merlin.protocol.model.OutputType) any number of times to register an observable Topic.
  • Model returns a model instance.
• Driver calls ModelType.getDirectiveTypes() to obtain the DirectiveTypes the model can react to.
• For each scheduled directive to simulate, Driver calls DirectiveType.getInputType() and then DirectiveType.getTaskFactory(java.lang.Object, java.util.Map) to instantiate a Task modeling the model's reaction to the directive.
• Whenever a task needs to be advanced, Driver calls Task.step(gov.nasa.jpl.aerie.merlin.protocol.driver.Scheduler), providing a Scheduler.
  • Model calls Scheduler.emit(java.lang.Object, gov.nasa.jpl.aerie.merlin.protocol.driver.Topic) any number of times to record an event on some topic.
  • Model calls Scheduler.get(gov.nasa.jpl.aerie.merlin.protocol.driver.CellId) any number of times to get the current value for an allocated stateful cell.
    • Driver converts all events not yet consumed by the cell to per-cell effects by using the topic and projection registered with the cell.
    • Driver calls CellType.getEffectType() and uses the returned EffectTrait to combine concurrent effects.
    • Driver calls CellType.step(java.lang.Object, gov.nasa.jpl.aerie.merlin.protocol.types.Duration) and CellType.apply(java.lang.Object, java.lang.Object) to bring the cell's state up to the time at the Model's request.
    • Driver returns the current state of the cell.
  • Model calls Scheduler.spawn(InSpan taskSpan, TaskFactory task) any number of times to spawn additional concurrent Tasks.
  • Model returns a TaskStatus describing the conditions under which to resume the task, or produces a terminal output if the task is complete.
• Whenever the Driver wants to observe the current value of a Resource, Driver calls Resource.getDynamics(gov.nasa.jpl.aerie.merlin.protocol.driver.Querier), providing a Querier.
  • Model calls Querier.getState(gov.nasa.jpl.aerie.merlin.protocol.driver.CellId) any number of times to get the current value for an allocated stateful cell. (The Driver responds as in the analogous case when a Task queries a cell.)
  • Model returns the current observable value of the resource.

See Also:

• gov.nasa.jpl.aerie.merlin.protocol.driver
• gov.nasa.jpl.aerie.merlin.protocol.model

Related Packages

Package	Description
gov.nasa.jpl.aerie.merlin.protocol.driver	Interfaces implemented by the external environment of a mission model.
gov.nasa.jpl.aerie.merlin.protocol.model	Interfaces implemented by a mission model.
gov.nasa.jpl.aerie.merlin.protocol.types

Annotation Interfaces

Class	Description
Capability	A Capability has object identity.