Adding 'problems' module

README.md

@@ -43,7 +43,7 @@ VirtualShip is a command line simulator allowing students to plan and conduct a
 - Surface drifters
 - Argo float deployments
 
-<!-- TODO: future. Along the way students will encounter difficulties such as: -->
+Along the way, students will encounter realistic problems that may occur during an oceanographic expedition, requiring them to make decisions to adapt their plans accordingly. For example, delays due to equipment failures, pre-depature logistical issues or safety drills.
 
 ## Installation
 

docs/user-guide/assignments/Sail_the_ship.ipynb

@@ -89,7 +89,7 @@
     "**Follow the instructions [here](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/surf_research_cloud_setup.html) to set up your SURF RC environment for VirtualShip.**\n",
     "\n",
     "<div class=\"alert alert-block alert-info\"> \n",
-    "**NOTE**: If you have Anaconda installed on your local machine and would like to run VirtualShip locally instead of on SURF RC, please see [VirtualShip - Installation](https://virtualship.readthedocs.io/en/latest/#installation) for instructions.\n",
+    "**Note**: If you have Anaconda installed on your local machine and would like to run VirtualShip locally instead of on SURF RC, please see [VirtualShip - Installation](https://virtualship.readthedocs.io/en/latest/#installation) for instructions.\n",
     "</div>"
    ]
   },
@@ -113,7 +113,7 @@
     "### Upload the coordinates to your virtual machine\n",
     "\n",
     "<div class=\"alert alert-block alert-warning\"> \n",
-    "**IMPORTANT**: _If you have not done so already_, make sure you create a folder for your group's expedition data in the persistent storage on SURF RC (i.e. the `data/storage/` folder). You can do so by running `mkdir /data/storage/{your-group-name}` in Terminal, replacing `{your-group-name}` with your actual group name, or by using the \"New Folder\" button in the JupyterLab file explorer panel.\n",
+    "**Important**: _If you have not done so already_, make sure you create a folder for your group's expedition data in the persistent storage on SURF RC (i.e. the `data/storage/` folder). You can do so by running `mkdir /data/storage/{your-group-name}` in Terminal, replacing `{your-group-name}` with your actual group name, or by using the \"New Folder\" button in the JupyterLab file explorer panel.\n",
     "</div>\n",
     "\n",
     "Back in the SURF RC JupyterLab interface, use the **file explorer** on the left hand side to navigate to the directory where your group will be running your expedition (i.e. `data/storage/{your-group-name}`). \n",
@@ -130,15 +130,15 @@
     "Open a Terminal window if you do not already have one open. Remember, this can be done from the Launcher tab by clicking on \"Terminal\" button under the \"Other\" section, or by going to the \"File\" menu --> \"New\" --> \"Terminal\".\n",
     "\n",
     "<div class=\"alert alert-block alert-warning\"> \n",
-    "**IMPORTANT**: Once in Terminal, navigate to where you would like your expedition to be run on your (virtual) machine. You can do so by `cd /data/storage/{your-group-name}`, replacing `{your-group-name}` with your actual group name. This is where you will be working from for the rest of the session.\n",
+    "**Important**: Once in Terminal, navigate to where you would like your expedition to be run on your (virtual) machine. You can do so by `cd /data/storage/{your-group-name}`, replacing `{your-group-name}` with your actual group name. This is where you will be working from for the rest of the session.\n",
     "</div>\n",
     "\n",
     "Now enter the following command in the Terminal (changing `EXPEDITION_NAME` to something more meaningful for your group's expedition):\n",
     "\n",
     "`virtualship init EXPEDITION_NAME --from-mfp {CoordinatesExport}.xlsx`\n",
     "\n",
     "<div class=\"alert alert-block alert-success\"> \n",
-    "**TIP**: The `{CoordinatesExport}.xlsx` in the command above refers to the .xlsx file exported from MFP and uploaded to your virtual machine earlier. Replace the filename with the name of your .xlsx file.\n",
+    "**Tip**: The `{CoordinatesExport}.xlsx` in the command above refers to the .xlsx file exported from MFP and uploaded to your virtual machine earlier. Replace the filename with the name of your .xlsx file.\n",
     "</div>\n",
     "\n",
     "This will create a folder/directory called `EXPEDITION_NAME` (or what you have changed this to) with a single file: `expedition.yaml`. This file contains details on the ship and instrument configurations, as well as the expedition schedule based on the sampling site coordinates that you specified in your MFP export. The `--from-mfp` flag indicates that the exported coordinates should be used."
@@ -151,7 +151,7 @@
     "## 5) Expedition scheduling & ship configuration\n",
     "\n",
     "<div class=\"alert alert-block alert-success\"> \n",
-    "**TIP**: From here, you should replace any references to `EXPEDITION_NAME` with the actual name you used for your expedition when running any `virtualship` commands.\n",
+    "**Tip**: From here, you should replace any references to `EXPEDITION_NAME` with the actual name you used for your expedition when running any `virtualship` commands.\n",
     "</div>\n",
     "\n",
     "The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (including any underway measurement instruments). \n",
@@ -172,27 +172,27 @@
     "### Waypoint datetimes\n",
     "\n",
     "<div class=\"alert alert-block alert-info\"> \n",
-    "**NOTE**: VirtualShip supports running experiments in the years 1993 through to the present day by leveraging the suite of products available on the Copernicus Marine Data Store.\n",
+    "**Note**: VirtualShip supports running experiments in the years 1993 through to the present day by leveraging the suite of products available on the Copernicus Marine Data Store.\n",
     "</div>\n",
     "\n",
     "You will need to enter dates and times for each of the sampling stations/waypoints selected in the MFP route planning stage. This can be done under _Schedule Editor_ > _Waypoints & Instrument Selection_ in the planning tool.\n",
     "\n",
     "Each waypoint has its own sub-panel for parameter inputs (click on it to expand the selection options). Here, the time for each waypoint can be inputted. There is also an option to adjust the latitude/longitude coordinates and you can add or remove waypoints.\n",
     "\n",
     "<div class=\"alert alert-block alert-info\"> \n",
-    "**NOTE**: It is important to ensure that the timings for each station are realistic. There must be enough time for the ship to travel to each site at the prescribed speed (10 knots). The expedition schedule will be automatically verified when you press _Save Changes_ in the planning tool.\n",
+    "**Note**: It is important to ensure that the timings for each station are realistic. There must be enough time for the ship to travel to each site at the prescribed speed (10 knots). The expedition schedule will be automatically verified when you press _Save Changes_ in the planning tool.\n",
     "</div>\n",
     "\n",
     "<div class=\"alert alert-block alert-success\"> \n",
-    "**TIP**: The MFP route planning tool will give estimated durations of sailing between sites at the 10 knots sailing speed. This can be useful to refer back to when planning the expedition timings and entering these into the `virtualship plan` tool.\n",
+    "**Tip**: The MFP route planning tool will give estimated durations of sailing between sites at the 10 knots sailing speed. This can be useful to refer back to when planning the expedition timings and entering these into the `virtualship plan` tool.\n",
     "</div>\n",
     "\n",
     "### Instrument selection\n",
     "\n",
     "You should now consider which measurements are to be taken at each sampling site (think about those required for your chosen research question), and therefore which instruments need to be selected in the planning tool at each waypoint.\n",
     "\n",
     "<div class=\"alert alert-block alert-success\"> \n",
-    "**TIP**: Click [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options) for more information on what measurement options are available, and a brief introduction to each instrument.\n",
+    "**Tip**: Click [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options) for more information on what measurement options are available, and a brief introduction to each instrument.\n",
     "</div>\n",
     "\n",
     "You can make instrument selections for each waypoint in the same sub-panels as the [waypoint time](#waypoint-datetimes) selection by simply switching each on or off. Multiple instruments are allowed at each waypoint.\n",
@@ -203,11 +203,11 @@
     "When you are happy with your ship configuration and schedule plan, press _Save Changes_ at the bottom of the planning tool.\n",
     "\n",
     "<div class=\"alert alert-block alert-info\"> \n",
-    "**NOTE**: On pressing _Save Changes_ the tool will check the selections are valid (for example that the ship will be able to reach each waypoint in time). If they are, the changes will be saved to the `expedition.yaml` file, ready for the next steps. If your selections are invalid you should be provided with information on how to fix them.\n",
+    "**Note**: On pressing _Save Changes_ the tool will check the selections are valid (for example that the ship will be able to reach each waypoint in time). If they are, the changes will be saved to the `expedition.yaml` file, ready for the next steps. If your selections are invalid you should be provided with information on how to fix them.\n",
     "</div>\n",
     "\n",
     "<div class=\"alert alert-block alert-warning\"> \n",
-    "**CAUTION**: The `virtualship plan` tool will check that the ship can reach each waypoint according to the prescribed ship speed (10 knots). However, before the ultimate simulation step (i.e. step 6 below) there will be a final, automated check that the schedule also accounts for the time taken to conduct the measurements at each site (e.g. a CTD cast in deeper waters will take longer). Therefore, we recommend to take this extra time into account at this stage of the planning by estimating how long each measurement will take and adding this time on.\n",
+    "**Caution**: The `virtualship plan` tool will check that the ship can reach each waypoint according to the prescribed ship speed (10 knots). However, before the ultimate simulation step (i.e. step 6 below) there will be a final, automated check that the schedule also accounts for the time taken to conduct the measurements at each site (e.g. a CTD cast in deeper waters will take longer). Therefore, we recommend to take this extra time into account at this stage of the planning by estimating how long each measurement will take and adding this time on.\n",
     "</div>"
    ]
   },
@@ -220,7 +220,7 @@
     "You are now ready to run your virtual expedition! This stage will take all the measurements for each of instruments you selected at each waypoint in your expedition schedule, using input data sourced from the [Copernicus Marine Data Store](https://data.marine.copernicus.eu/products).\n",
     "\n",
     "<div class=\"alert alert-block alert-info\"> \n",
-    "**NOTE**: You will need to register for a Copernicus Marine Service account (you can do so [here](https://data.marine.copernicus.eu/register)), if you have not done so already.\n",
+    "**Note**: You will need to register for a Copernicus Marine Service account (you can do so [here](https://data.marine.copernicus.eu/register)), if you have not done so already.\n",
     "</div>\n",
     "\n",
     "You can run your expedition simulation using the command: \n",
@@ -232,7 +232,11 @@
     "Small simulations (e.g. small space-time domains and fewer instrument deployments) will be relatively fast. For large, complex expeditions, it _could_ take up to an hour to simulate the measurements depending on your choices. Waiting for simulation is a great time to practice your level of patience. A skill much needed in oceanographic fieldwork ;-)\n",
     "\n",
     "<div class=\"alert alert-block alert-success\"> \n",
-    "**TIP**: Not using underway instruments will speed up the simulation time considerably. So, if you do not plan to use underway temperature/salinity or ADCP measurements, make sure to switch these off in the planning tool before running the expedition.\n",
+    "**Tip**: Not using underway instruments will speed up the simulation time considerably. So, if you do not plan to use underway temperature/salinity or ADCP measurements, make sure to switch these off in the planning tool before running the expedition.\n",
+    "</div>\n",
+    "\n",
+    "<div class=\"alert alert-block alert-warning\"> \n",
+    "**Important**: VirtualShip will encounter 'problems' during the expedition, which simulate the various challenges and unexpected events that can occur during real-life oceanographic expeditions (e.g. instrument and/or equipment failure, logistical challenges etc.). These may require your intervention to ensure your expedition schedule can continue!\n",
     "</div>"
    ]
   },

docs/user-guide/quickstart.md

@@ -4,7 +4,7 @@ Welcome to this Quickstart to using VirtualShip. In this guide we will conduct a
 
 This Quickstart is available as an instructional video below, or you can continue with the step-by-step guide.
 
-```{warning}
+```{caution}
 Please note the video below may show output from an earlier version of VirtualShip, as the codebase is in active development. The instructions in the video are still generally applicable for the current version. However, for the most up-to-date instructions, please follow the text in this Quickstart guide.
 ```
 
@@ -150,6 +150,16 @@ Small simulations (e.g. small space-time domains and fewer instrument deployment
 
 Why not browse through previous real-life [blogs and expedition reports](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Sail_the_ship.html#Reporting) in the meantime?!
 
+#### Encountering 'problems' during the expediton (configurable)
+
+By default, VirtualShip will encounter 'problems' during the expedition, which simulate the various challenges and unexpected events that can occur during real-life oceanographic expeditions (e.g. instrument and/or equipment failure, logistical challenges etc.) and may require your intervention to ensure your expedition schedule can continue.
+
+The 'problems' add authenticity to the simulation. However, if you require a 'problem'-free expedition, you can run the simulation with the "problem level" (`prob-level`) set to 0 (i.e. `virtualship run EXPEDITION_NAME --prob-level 0`).
+
+```{tip}
+For maximum authenticity, you can set `--prob-level 2`, which will scale the number of problems encountered by the complexity of your expedition (longer duration, more waypoints, more instruments will lead to more problems). By default, the `prob-level` = 1, which limits the number of problems to a maximum of 2, regardless of the expedition complexity.
+```
+
 #### Using pre-downloaded data (optional)
 
 By default, VirtualShip will stream data 'on-the-fly' from the Copernicus Marine Data Store, meaning no prior data download is necessary. However, if you prefer to use pre-downloaded data instead (e.g. due to limited internet connection or wanting to use different input data) you can do so by running `virtualship run EXPEDITION_NAME --from-data <PATH_TO_DATA_DIR>`.