Overhaul mission modeling documentation

[camargo]

The resources and models document is out of date. It needs to be updated with concrete examples of the different resources and how to add them to a model.

[ewferg]

While I am probably not the best person to write the detailed content of this section, I wanted to provide a draft outline for how we could organize this information based on my recent experience trying to learn mission modeling. This outline also references some thoughts I provided in #48, but this issue is focused on the explanatory docs as opposed to a tutorial.

Mission Modeling Doc Section Outline

• Overview
  • What is a mission model?
  • Link to mission modeling template/tutorial
  • How mission model is loaded into Aerie - diagram showing loading of .jar into Aerie system
  • Mission Model Constructs - Brief explanation of basic mission model constructs: activity types, resources, models (basically the arbitrary java code to describe your system), simulation configuration
  • Mission Model Structure - Top level explanation of how the concepts above manifest in code. Basically introduce the mission model class and configuration class and how the package-info.java file maps these classes to the constructs above.
• Mission Model Class
  • Note the available constructor types and when these are actually instantiated in process of loading the .jar and simulating
  • I almost feel like we could get away with an example here that shows no resources registrations but has code comments that say things like "enter resource registrations here", "spawn daemon tasks", etc.
• Activity Types
  • Overview/Structure (Parameters, Effect Model, Computed Attributes)
  • Parameters (annotation, defaults, validation)
  • Effect Model (actions, decomposition - wouldn't talk about valuemappers here, exceptions last)
  • Computed Attributes
  • Metadata
  • Presets??
  • Advanced - Activity Records? - my understanding is you can slim down your code a bit if you use records to define activity types instead of standard java classes, so perhaps an explanation of this here would be good. I think when folks are learning, it is better that they be explicit with everything, so this topic is a bit less important than the ones above
• Resources
  • Overview of resources (real/continuous vs. discrete)
  • Index of "out of the box" resources types and how they map to real vs. continuous (Clock, Register, Counter, Accumulator, Pointing??, Sampled, Derived). You could note that resource type definitions aren't actually part of the framework and exist in the "contrib" section of a model. More info could be found in the custom resource model section.
  • Examples of each available resource type without having to jump over to a repo
  • Ideally, we wouldn't have to go into detail here on value mappers, but would have a reference to a section on the subject. I think this should be separate from the "Activity Mappers" section that currently exists.
  • Advanced - Value Mappers
  • Advanced - Custom Resource Models
    • Value Schemas?
• Daemon Tasks
  • Overview of daemon task
  • Example of daemon task that sets resources
• Simulation Configuration
  • Overview
  • Note how constructor class is instantiated in process of loading the .jar and simulation. Note the need for empty constructor in addition to constructor that feeds in configuration from user.
  • Show example where parameters are explicitly annotated
  • Explanation of ways to reduce use of annotations with use of java records or if all members are parameters
• Package-Info
  • I put this here instead of up front since this is fairly boilerplate and can be a bit confusing to folks less familiar with Java. By this point all items in the package info have been explained so the concepts should feel more familiar to the reader.
• Testing
  • Explanation of the available mission model test framework provided by Aerie and basic examples for "unit" level and "simulation" level testing
• Other Advanced Topics
  • Annotations - general discussion of Java annotations, how they are used in Aerie mission modeling, and potential an index of all annotations available.
  • Incons
  • Activity Mappers
  • Decomposition vs. Scheduling - perhaps a description of when it may make sense to perform decomp vs. scheduling?
  • Merlin Interface - I am wondering if this makes more sense in the SDD?

[ewferg]

@camargo, @mattdailis - I am happy to create a branch that modifies our docs towards this outline after you have a chance to provide feedback.