Adding 'problems' module

[j-atkins]

Summary

This PR adds a 'problems' module to VirtualShip, whereby as expeditions are run users are faced with authentic problems which may happen on a real-life research vessel. These can be "general" problems (e.g. delayed food/fuel deliveries, unplanned safety drills), or "instrument" problems (e.g. CTD winch breaks down).

Features & implementation

All problems are associated with a delay duration. There are checks of whether there is already enough contingency time built into the schedule to still reach the next waypoint in time. If there is then the simulation is allowed to continue. However, if the next waypoint would be missed, users are prompted to account for the delay in their schedules and the expedition cannot proceed until the scheduling is resolved.

The problems module interacts with Checkpoint objects to test that the scheduling issues have been resolved. A unique record of the problems is also cached to keep track of and determine whether they've been resolved etc. It may be that dealing with a problem at one waypoint causes more scheduling issues way down the chain of waypoints. This is by design (as similar headaches would be experienced in real life!) and the schedule/checkpoint verification methods should capture this and prompt further changes.

The selection of problems and their execution in the main virtualship run workflow is handled by a new ProblemSimulator class. Specific problem scenarios are housed in scenarios.py as problem classes, which are themselves sub-classes of GeneralProblem and InstrumentProblem base classes (to establish a structure for building complexity in further PRs).

When propagated through virtualship run, a selection of all the problems for the expedition is first created but the individual problems are only raised at the right time. For example, a pre-departure problem will occur before any instrument simulations and a CTD related problem only when the CTD instrument is being simulated.

A new 'prob-level' argument is now added to the virtualship run CLI command. There are three options to choose from:

• Level 0 = No problems encountered during the expedition (i.e. turn off problems module).
• Level 1 = 1-2 problems encountered across the expedition [DEFAULT].
• Level 2 = 1 or more problems encountered, depending on expedition length and complexity, where longer and more complex expeditions will encounter more problems.

N.B. I have set the default to prob_level = 1 for now, as this is best for upcoming in-class VirtualShip use.

Additional notes

I have set up the logic so that if waypoints are added/removed from the expedition, if a waypoint location changes or the instruments employed changes, this will prompt a new set of problems for the expedition. I see this as the expedition having materially changed and it being a 'new' expedition. This also prevents just re-running the same expedition until you get a 'nicer' set of problems (without manually removing the problems cache!).

---

• Tests

---

Closes #120

[j-atkins]

Thanks @VeckoTheGecko! PR now updated to reflect your suggestions.

I've also updated the logic for determining an expedition identifier (id). Before it was determining a new expedition (and therefore new set of problems) based on a change in instrument deployment at any waypoint. However, that could inadvertently lead to a new set of problems being returned if a user deletes a waypoint to deal with scheduling issues.

Now, instead, a new id is only returned when there is an addition to the set of instruments deployed across whole expedition (but not subtraction because this could be triggered, again, by deleting waypoints if the waypoint is the only one with that instrument type).

[j-atkins]

I've now changed "prob-level" to "difficulty-level" (as suggested by @VeckoTheGecko) and set the default to "easy". For in-class applications where we want to use problems then we can point to a custom installation with default set to e.g. "medium" instead.

Let me know when you're happy with the PR (cc @ammedd and @erikvansebille) and we'll get this merged 🚢

[ammedd]

I run into the same issue as #281
Good to check/fix before merging this PR?

[j-atkins]

I run into the same issue as #281 Good to check/fix before merging this PR?

To understand this better, are you encountering this problem because you have indeed made changes to the timings at waypoints before the waypoint affected by the problem? If so I would say this is the expected behaviour...as we only want users to make changes to waypoint timings after the problem waypoint?

[ammedd]

No, the message is "Waypoint 5 could not be reached in time. Current time: 1998-01-01 03:00:14.987829. Waypoint time: 1998-01-01 03:00:00."
I've only changed waypoint 5 and that is the last waypoint in the expedition.

[erikvansebille]

I don't have time to carefully go through the code again myself, but I think that the issue that Emma raised above is very important to get fixed before merging. Please keep me updated how you are progressing

[j-atkins]

If I understand this correctly, @ammedd your point is about the first part of #281 (waypoint not reached in time) rather than the second part (warning about not re-scheduling previous waypoints)?

In any case, I've asked for the expedition.yaml from @VeckoTheGecko in #281 so that I can investigate this further. In the meantime, and regarding the message:

Waypoint 5 could not be reached in time. Current time: 1998-01-01 03:00:14.987829. Waypoint time: 1998-01-01 03:00:00.

Have you ensured that your schedule includes sufficient time for taking measurements, e.g. CTD casts (in addition to the time it takes to sail between waypoints)?

Hint: previous schedule verification checks (e.g. in the `virtualship plan` tool or after dealing with unexpected problems during the expedition) will not account for measurement times, only the time it takes to sail between waypoints.

This alone is not necessarily unexpected behaviour in the code's existing form. It is possible that a user fixes a scheduling issue as a result of a problem, which passes the schedule.verify() checks (no knowledge of instrument deployment timings, only sailing time) but then the simulate_schedule methods identify that the instrument deployment timings would mean it's late to the following waypoint, so it throws another message saying the waypoint still cannot be reached. I would expect in the case above even adding a few minutes to the waypoint will solve the problem.

If indeed this is what's happening (I will check this thoroughly though using Nick's expedition.yaml), I do appreciate that this is quite clunky from the user's perspective. It reflects the existing workflow in run though where we have a schedule.verify() check and further checks in simulate_schedule. I'll have a look if this can be tidied up.

[j-atkins]

Update: Schedule.verify() now also takes the instrument deployment times into account when calculating whether the next waypoint can be reached in time. This should avoid situations where Schedule.verify() passes but simulate_measurements fails because instrument deployment timings have since been added to the calculation.