Implement Temporal Subset Simulation

[Mythicaeda]

• Tickets addressed: Closes Allow setting simulation boundary on a subset of plan duration #680
• Review: By commit
• Merge strategy: Merge (no squash)

Description

Database Changes

• Columns for tracking simulation start time and simulation end time were added to simulation and simulation_template. They are both nullable, but between the two tables each column must have a value for a given row in simulation. For example, if a simulation row references a template, either the template or the simulation row can provide the sim start and end time, but if a simulation row doesn't reference a template, it must provide these values.
• A trigger was created to insert a row into simulation upon a row being inserted into plan
• A constraint was added to simulation to allow only one row per plan (If this constraint is currently violated in the DB, the migration introducing it will fail).
• simulation_dataset now has columns for what bounds the simulation was run over, as well as what the provided arguments were.
• simulation_dataset's offset_from_plan_start is now solely maintained via trigger rather than by direct update.
• The simulated_activity view was updated to have the correct start time for spans from temporal subset simulations

Merlin Changes

• Methods for adjusting the start offset of a List of ActivityDirectives and filtering out ActivityDirectives with negative start offsets have been added to StartOffsetReducer.
• Plan, SimulationRecord, SimulationTemplateRecord, and SimulationDatasetRecord all have had simulationStartTime and simulationEndTime added as fields.
• getPlan was split into getPlanForValidation and getPlanForSimulation in order to avoid needlessly hitting up the database.
• SimulationResults now has a duration field.
• Simulation start and end time must now be specified by either the sim config or the template (see Database Changes for more details)

Breaking Changes

The following breaking changes occurred:

1. The signature of SimulationDriver.simulate changed to

  public static <Model> SimulationResults simulate(
      final MissionModel<Model> missionModel,
      final Map<ActivityDirectiveId, ActivityDirective> schedule,
      final Instant simulationStartTime,
      final Duration simulationDuration,
      final Instant planStartTime,
      final Duration planDuration
  )

2. The signature of CreateSimulationMessage changed to

  public CreateSimulationMessage {
    Objects.requireNonNull(missionModelId);
    Objects.requireNonNull(simulationStartTime);
    Objects.requireNonNull(simulationDuration);
    Objects.requireNonNull(planStartTime);
    Objects.requireNonNull(planDuration);
    Objects.requireNonNull(activityDirectives);
    Objects.requireNonNull(configuration);
  }

3. The structure of a SimulationResults changed to

public SimulationResults(
        final Map<String, Pair<ValueSchema, List<ProfileSegment<RealDynamics>>>> realProfiles,
        final Map<String, Pair<ValueSchema, List<ProfileSegment<SerializedValue>>>> discreteProfiles,
        final Map<SimulatedActivityId, SimulatedActivity> simulatedActivities,
        final Map<SimulatedActivityId, UnfinishedActivity> unfinishedActivities,
        final Instant startTime,
        final Duration duration,
        final List<Triple<Integer, String, ValueSchema>> topics,
        final SortedMap<Duration, List<EventGraph<Pair<Integer, SerializedValue>>>> events)

4. Simulation bounds need to be specified in the database by either the simulation or template rows. (See Database Changes for more information)

Verification

• MerlinDatabaseTests were updated to reflect the added "one simulation row per plan" constraint and the "create simulation row when a plan is created" trigger.
• Tests were added to AnchorTests.StartOffsetReducerTests to test the new static methods. Notably, since the new methods and the constructor do some input validation/special behavior on null inputs, there are tests for these cases.
• A new set of tests, TemporalSubsetSimulationTests were added to verify that simulating a subset of a plan works. Since Aerie does not distinguish between full simulations and temporal subset simulations, the existing decomposition tests shouldn't need to be repeated here.

Documentation

Documentation ticket for the API changes can be found here.

Future work

• Since the simulation-related fields are only initialized for a Plan object when calling getPlanForSimulation, I'd like to split them from the Plan class, either by putting them in their own class or by moving them into a subclass of Plan.
• Adding a Plan End timestamp column, likely maintained via a trigger like simulation_dataset's offset_from_plan_start column.

[mattdailis]

Could you fill out the Documentation section of the PR template? If no documentation has been written - could you link to the ticket to write this documentation?

I just pulled this branch and will play around a bit now - I don't expect to do a super detailed code review since we chatted about this a couple weeks ago, and it sounds like you guys had a good code walkthrough last week, but I would like to glance over it with the freshest pair of eyes I've had in a while 😅

[mattdailis]

Looks reasonable to me. I didn't pull out my fine-toothed comb, but Adrien's review, and the level of testing give me confidence in this change. I'm looking forward to exercising it more as we implement the UI portion of this feature 🚀