diff --git a/docs/conf.py b/docs/conf.py
index ea12ec890..c4bc67040 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -70,11 +70,13 @@
always_document_param_types = True
nbsphinx_thumbnails = {
+ "user-guide/quickstart": "user-guide/_images/AnnaWeber.jpeg",
+ "user-guide/tutorials/index": "user-guide/_images/AnnaWeber.jpeg",
"user-guide/assignments/Research_proposal_intro": "user-guide/_images/MFPtimeline.jpg",
"user-guide/assignments/Research_Proposal_only": "user-guide/_images/MFP.jpg",
"user-guide/assignments/Virtualship_research_proposal": "user-guide/_images/AnnaWeber.jpeg",
"user-guide/assignments/sciencecommunication_assignment": "user-guide/_images/marine_ss.jpg",
- "user-guide/assignments/Sail_the_ship": "user-guide/_images/freepik_research_vessel.jpg",
+ "user-guide/assignments/sail_the_ship": "user-guide/_images/freepik_research_vessel.jpg",
"user-guide/assignments/Code_of_conduct": "user-guide/_images/freepik_code_of_conduct.jpg",
"user-guide/teacher-content/ILOs": "user-guide/_images/ILOs.jpg",
"user-guide/teacher-content/UU-ocean-of-future/Tutorial1": "user-guide/_images/freepik_assignment.png",
@@ -84,6 +86,9 @@
"user-guide/tutorials/working_with_expedition_yaml": "user-guide/_images/AnnaWeber.jpeg",
"user-guide/teacher-content/UU-dyoc/example_expedition": "user-guide/_images/AnnaWeber.jpeg",
"user-guide/teacher-content/UU-dyoc/file_permissions": "user-guide/_images/AnnaWeber.jpeg",
+ "user-guide/teacher-content/train-the-teacher/surf_set_up": "user-guide/_images/AnnaWeber.jpeg",
+ "user-guide/teacher-content/train-the-teacher/file_permissions": "user-guide/_images/AnnaWeber.jpeg",
+ "user-guide/teacher-content/train-the-teacher/surf_student_access": "user-guide/_images/AnnaWeber.jpeg",
}
sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"}
diff --git a/docs/user-guide/assignments/Sail_the_ship.ipynb b/docs/user-guide/assignments/Sail_the_ship.ipynb
deleted file mode 100644
index db2562b7c..000000000
--- a/docs/user-guide/assignments/Sail_the_ship.ipynb
+++ /dev/null
@@ -1,322 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "# Sail the ship\n",
- "\n",
- "```\n",
- "Note: This guide is specific to students who are enrolled at Utrecht University.\n",
- "```\n"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Welcome aboard VirtualShip!\n",
- "\n",
- "Welcome aboard, oceanography students, to our scientific research vessel! We're thrilled to have you join us for this exciting 3-week journey into the depths of the ocean. As we embark on this voyage of exploration and discovery, there are a few things we'd like to share with you to ensure a smooth and enriching experience:\n",
- "\n",
- "**Introduction to the Vessel:** Take some time to familiarize yourselves with the layout of the ship. Get to know key areas such as the laboratories, living quarters, dining area, and deck spaces. E.g. at https://viewer.foleon.com/preview/vo2PZClgA/rv-wim-wolff\n",
- "\n",
- "**Daily Routine:** Life on a research vessel follows a structured daily routine. We'll have designated times for meals, research activities, data analysis, and downtime. It's important to maintain this routine to ensure that our work is conducted efficiently and that everyone onboard has the opportunity to rest and recharge.\n",
- "\n",
- "**Safety Orientation:** Safety is our top priority. As we set sail, we'll conduct a comprehensive safety orientation. This will cover important topics such as emergency procedures, the location of safety equipment, and proper use of personal protective gear. Please pay close attention during this orientation to ensure your safety and the safety of others on board.\n",
- "\n",
- "**Respect for the Environment:** As we explore the ocean, it's essential to maintain a deep respect for the marine environment. We'll adhere to strict environmental protocols to minimize our impact on marine ecosystems and wildlife. Remember to dispose of waste properly and avoid disturbing marine life whenever possible.\n",
- "\n",
- "**Teamwork and Collaboration:** Oceanographic research is a collaborative effort that requires teamwork and cooperation. You'll be working closely with your fellow students. Embrace the opportunity to learn from each other and support one another throughout the journey."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Emergency procedures\n",
- "\n",
- "Before going on any research expedition you need follow a one day Safety at Sea course and get a medical check-up.\n",
- "\n",
- "Of course this is not needed for your virtual fieldwork, but we would like to draw for your attention to the following on-board emergency procedures.\n",
- "\n",
- "**Safety Drills:** We conduct regular safety drills to ensure that everyone on board is well-prepared in case of an emergency. Specifically, fire and boat drills are held once a week. These drills are not just routine; they are essential survival training and should be taken seriously. To minimize disruption to the research program, science party members are usually notified in advance of the scheduled drills. In the event that you must continue working during a drill, prior arrangements can be made through the Chief Scientist.\n",
- "\n",
- "**Emergency Signal:** In the event of an emergency signal, your immediate action is crucial. Don life jackets, put on long-sleeved garments, and wear a hat or head covering if available. Then, proceed to the designated station indicated on the station card located next to your bunk.\n",
- "\n",
- "**On-Call Readiness:** Please keep in mind that while on board the ship, you may be called upon without warning to assist during your off-watch periods. Emergencies can happen at any time, and your readiness to respond promptly and efficiently is essential to the safety of all aboard.\n",
- "\n",
- "**Boat Drill (Abandon Ship):** The signal for abandon ship is seven or more short blasts followed by one long blast of the ship’s whistle and general alarm. When this signal is heard, report to your designated life raft station. There the Mate in charge will explain the procedures for launching and embarking into the life rafts. The rafts will not be launched during a drill.\n",
- "\n",
- "**Fire and Emergency Drills:** The signal is one long blast on the ship’s whistle and general alarm bell, lasting for ten seconds or more. During this drill, members of the science party muster in the designated area. Attendance will be taken and reported to the bridge.\n",
- "\n",
- "**Man Overboard:** If someone falls overboard, throw a life-ring into the water towards the person. Keep your eye on the person at all times and point towards the person. Shout “MAN OVERBOARD, STARBOARD (or PORT),” and call the bridge on the sound powered phone or squawk box to inform them without losing sight of the person if possible. If you hear someone hail \"Man Overboard,\" pass the word to the bridge."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Your virtual expedition...\n",
- "\n",
- "Now let's get started on running your VirtualShip expedition. Follow the steps below to set up your coding environment, plan your expedition, and launch your simulation. \n",
- "\n",
- "
\n",
- "Before that though, make sure you have had your research question approved by your instructor!\n",
- "
"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 1) Register with the Copernicus Marine Data Store\n",
- "\n",
- "You will need to register for **Copernicus Marine Service** account (see [here](https://data.marine.copernicus.eu/register)), if you have not done so already. This is required to access the oceanographic data that VirtualShip uses to run your expedition."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 2) Set up your virtual machine\n",
- "\n",
- "In the class, we will use VirtualShip in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages:\n",
- "\n",
- "- You aren't limited to the power of your laptop.\n",
- "- The environment is pre-configured with all necessary software and dependencies.\n",
- "\n",
- "**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",
- "
\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",
- "
"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 3) Expedition route planning\n",
- "\n",
- "### NIOZ MFP tool\n",
- "\n",
- "The first step is to plan the expedition route for your chosen research question, bearing in mind the time needed for your sampling strategy, and traveling to and from a port suitable for research vessels (remember though, you have a three week ship time limit).\n",
- "\n",
- "Your route can be created with the online [NIOZ MFP tool](https://nioz.marinefacilitiesplanning.com/cruiselocationplanning#). Documentation on how to use the website can be found [here](https://surfdrive.surf.nl/files/index.php/s/84TFmsAAzcSD56F). Alternatively, you can watch this [video](https://www.youtube.com/watch?v=yIpYX2xCvsM&list=PLE-LzO7kk1gLM74U4PLDh8RywYXmZcloz&ab_channel=VirtualShipClassroom), which runs through how to use the MFP tool.\n",
- "\n",
- "\n",
- "### Export the coordinates from MFP\n",
- "\n",
- "Once you have finalised your MFP expedition route, select \"Export\" on the right hand side of the window --> \"Export Coordinates\" --> \"DD\". This will download your coordinates as an .xlsx (Excel) file, which we will later feed into the VirtualShip protocol to initialise the expedition.\\\n",
- "\n",
- "### Upload the coordinates to your virtual machine\n",
- "\n",
- "
\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",
- "
\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",
- "\n",
- "Then upload the exported .xlsx file (it will be called something like \"Coordinates-20251125T1403.xlsx\") by either dragging and dropping it from your laptop's Downloads into the file explorer, or by using the \"Upload Files\" button (the icon with an upward arrow) at the top of the file explorer panel."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 4) Expedition initialisation\n",
- "\n",
- "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",
- "
\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",
- "
\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",
- "
\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",
- "
\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."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 5) Expedition scheduling & ship configuration\n",
- "\n",
- "
\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",
- "
\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",
- "\n",
- "
\n",
- "**Note**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. For expeditions with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](../tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.\n",
- "
\n",
- "\n",
- "\n",
- "The easiest way to do so is to use the bespoke VirtualShip planning tool. Enter the following command in Terminal: `virtualship plan EXPEDITION_NAME`.\n",
- "\n",
- "
\n",
- "**TIP**: Using the `virtualship plan` tool is optional. Advanced users can also edit the `expedition.yaml` file directly if preferred.\n",
- "
\n",
- "\n",
- "### Ship speed\n",
- "\n",
- "In the planning tool which appears, under _Ship Config Editor_ > _Ship Speed & Onboard Measurements_, there is an option to change the ship speed. However, for this course, you should leave this as the default **10 knots** value.\n",
- "\n",
- "### Underway measurements\n",
- "\n",
- "VirtualShip is capable of taking underway temperature and salinity measurements, as well as onboard ADCP measurements, as the ship sails across the length of the expedition (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Underway-Data) for more detail). These underway measurements can be switched on/off under _Ship Config Editor_ > _Ship Speed & Onboard Measurements_ as well.\n",
- "\n",
- "For the underway ADCP, there is a choice of using the 38 kHz OceanObserver or the 300 kHz SeaSeven version (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#ADCP) for more detail on the two ADCP types).\n",
- "\n",
- "### Instrument/sensor configuration\n",
- "\n",
- "The most important instrument configuration setting to consider is the list of **sensors** for each instrument, which controls what type of measurements/variables the instrument records in the simulation and therefore what output data you will receive for each instrument.\n",
- "\n",
- "Sensor lists can be configured for each instrument under _Ship Config Editor_ > _Instrument Configurations_. For example, for the CTD instrument, you can specify which sensors to include in the simulation (e.g., `TEMPERATURE`, `SALINITY`, `OXYGEN`, etc.) by toggling the respective switches on or off.\n",
- "\n",
- "
\n",
- "**Note**: Sensor choices are only relevant for the instruments you plan to deploy as [underway measurements](#underway-measurements) or at waypoints across your expedition schedule [(see below)](#instrument-selection). For example, if you do not select to deploy a CTD at any of your waypoints, the CTD sensor choices will not affect any output data.\n",
- "
\n",
- "\n",
- "
\n",
- "**TIP**: See [here](../documentation/full_sensor_list.md) for more information on the sensors available for each instrument.\n",
- "
\n",
- "\n",
- "There are other instrument configurations settings that can be adjusted in the editor as well (e.g. `max_depth` for the CTD), but these are more advanced and in most cases do not need to be changed from the default values.\n",
- "\n",
- "### Waypoint datetimes\n",
- "\n",
- "
\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",
- "
\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",
- "
\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",
- "
\n",
- "\n",
- "
\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",
- "
\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",
- "
\n",
- "**Tip**: Click [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options) for more information on which instruments are available in VirtualShip, and a brief introduction to each.\n",
- "
\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",
- "\n",
- "\n",
- "### Save changes\n",
- "\n",
- "When you are happy with your ship configuration and schedule plan, press _Save Changes_ at the bottom of the planning tool.\n",
- "\n",
- "
\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",
- "
"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 6) Run the expedition\n",
- "\n",
- "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",
- "
\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",
- "
\n",
- "\n",
- "You can run your expedition simulation using the command: \n",
- "\n",
- "`virtualship run EXPEDITION_NAME`\n",
- "\n",
- "If this is your first time running VirtualShip, you will be prompted to enter your own Copernicus Marine Data Store credentials (these will be saved automatically for future use).\n",
- "\n",
- "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",
- "
\n",
- "**Important**: VirtualShip may encounter 'real-life challenges' during the expedition, which simulate the various problems 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",
- "
"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## 7) Results\n",
- "\n",
- "Upon successfully completing the simulation, results from the expedition will be stored in the `EXPEDITION_NAME/results` directory, written in `.parquet` [format](https://parquet.apache.org/).\n",
- "\n",
- "From here you can carry on your analysis. In general, we encourage you to use [Parcels](https://Parcels-code.org/) (i.e. `parcels.read_particlefile()`) to read in VirtualShip output files, and tools such as [Polars](https://www.pola.rs/) and/or [Pandas](https://pandas.pydata.org/) for further data analysis. We also provide various further [VirtualShip tutorials](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/index.html) which provide examples of how to visualise data recorded by the VirtualShip instruments. Use these to help you get started!\n",
- "\n",
- "If you are using VirtualShip in class, the same tutorial notebooks may be uploaded in your SURF RC environment for you to use and interact directly with the code. These should be available in e.g. the `data/storage/tutorials/` directory. You will notice that there is a notebook file dedicated to visualising each of the different instruments available in VirtualShip. \n",
- "\n",
- "To run these notebooks with your own data, you will need to copy the them over to your expedition working directory (i.e. `data/storage/{your-group-name}`). This can be done by either 1) using the file explorer panel in JupyterLab to copy the relevant files or the via the command line in Terminal. In the terminal, running `cp -r /data/storage/tutorials/* /data/storage/{your-group-name}/` would copy __all__ the tutorial notebooks to your group's directory, so if you only want to copy specific ones, make sure to adjust the command accordingly."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "## Reporting\n",
- "\n",
- "Reporting your journey is an essential aspect of our oceanographic research expedition. It allows us to share our experiences, communicate our findings, and contribute to the broader scientific community. After each scientific expedition a cruise report should be written (or in the case of this course, a presentation).\n",
- "\n",
- "You can find many cruise [reports](https://www.bodc.ac.uk/resources/inventories/cruise_inventory/reports/pe358.pdf) and [blogs](https://www.nioz.nl/en/news-and-blogs) online from many different cruises.\n",
- "\n",
- "Reporting our journey allows us to validate the data collected during our research activities. It provides context for our findings and helps ensure that our results are accurately interpreted and understood. Detailed reports enable us to cross-reference our observations with environmental conditions, sampling locations, and other relevant factors, enhancing the reliability and credibility of our data. \n",
- "\n",
- "Our reports also serve as valuable educational resources for students, educators, and the general public. They provide insights into the process of scientific inquiry, the challenges of conducting research at sea, and the significance of oceanographic discoveries. \n",
- "\n",
- "We look forward to seeing the impact of your collective efforts during the presentations in a few weeks time!\n",
- "\n",
- "Please don't worry if your results are insufficient to answer your research question. Share your failure and things you would do different a next time instead!\n",
- "\n",
- "For example:\n",
- "\n",
- "- [Normalizing failure: when things go wrong in participatory marine social science fieldwork](https://publications.csiro.au/publications/publication/PIcsiro:EP2022-3465).\n",
- "- [Emotions and failure in academic life: Normalising the experience and building resilience](https://www.cambridge.org/core/journals/journal-of-management-and-organization/article/emotions-and-failure-in-academic-life-normalising-the-experience-and-building-resilience/91FD71A50A32404D8EDFFB7886FF3521).\n",
- "\n",
- "---"
- ]
- }
- ],
- "metadata": {
- "kernelspec": {
- "display_name": "ship",
- "language": "python",
- "name": "python3"
- },
- "language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.12"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
diff --git a/docs/user-guide/assignments/sail_the_ship.md b/docs/user-guide/assignments/sail_the_ship.md
new file mode 100644
index 000000000..d1b7cd9e9
--- /dev/null
+++ b/docs/user-guide/assignments/sail_the_ship.md
@@ -0,0 +1,220 @@
+# Sail the ship
+
+## Welcome aboard VirtualShip!
+
+Welcome aboard, oceanography students, to our scientific research vessel! We're thrilled to have you join us for this exciting journey into the depths of the ocean. As we embark on this voyage of exploration and discovery, there are a few things we'd like to share with you to ensure a smooth and enriching experience:
+
+**Introduction to the Vessel:** Take some time to familiarise yourselves with the layout of the ship. Get to know key areas such as the laboratories, living quarters, dining area, and deck spaces.
+
+**Daily Routine:** Life on a research vessel follows a structured daily routine. We'll have designated times for meals, research activities, data analysis, and downtime. It's important to maintain this routine to ensure that our work is conducted efficiently and that everyone onboard has the opportunity to rest and recharge.
+
+**Safety Orientation:** Safety is our top priority. As we set sail, we'll conduct a comprehensive safety orientation. This will cover important topics such as emergency procedures, the location of safety equipment, and proper use of personal protective gear. Please pay close attention during this orientation to ensure your safety and the safety of others on board.
+
+**Respect for the Environment:** As we explore the ocean, it's essential to maintain a deep respect for the marine environment. We'll adhere to strict environmental protocols to minimize our impact on marine ecosystems and wildlife. Remember to dispose of waste properly and avoid disturbing marine life whenever possible.
+
+**Teamwork and Collaboration:** Oceanographic research is a collaborative effort that requires teamwork and cooperation. You'll be working closely with your fellow students. Embrace the opportunity to learn from each other and support one another throughout the journey.
+
+## Emergency procedures
+
+Before going on any research expedition you need follow a one day Safety at Sea course and get a medical check-up.
+
+Of course this is not needed for your virtual fieldwork, but we would like to draw for your attention to the following on-board emergency procedures.
+
+**Safety Drills:** We conduct regular safety drills to ensure that everyone on board is well-prepared in case of an emergency. Specifically, fire and boat drills are held once a week. These drills are not just routine; they are essential survival training and should be taken seriously. To minimize disruption to the research program, science party members are usually notified in advance of the scheduled drills. In the event that you must continue working during a drill, prior arrangements can be made through the Chief Scientist.
+
+**Emergency Signal:** In the event of an emergency signal, your immediate action is crucial. Don life jackets, put on long-sleeved garments, and wear a hat or head covering if available. Then, proceed to the designated station indicated on the station card located next to your bunk.
+
+**On-Call Readiness:** Please keep in mind that while on board the ship, you may be called upon without warning to assist during your off-watch periods. Emergencies can happen at any time, and your readiness to respond promptly and efficiently is essential to the safety of all aboard.
+
+**Boat Drill (Abandon Ship):** The signal for abandon ship is seven or more short blasts followed by one long blast of the ship’s whistle and general alarm. When this signal is heard, report to your designated life raft station. There the Mate in charge will explain the procedures for launching and embarking into the life rafts. The rafts will not be launched during a drill.
+
+**Fire and Emergency Drills:** The signal is one long blast on the ship’s whistle and general alarm bell, lasting for ten seconds or more. During this drill, members of the science party muster in the designated area. Attendance will be taken and reported to the bridge.
+
+**Man Overboard:** If someone falls overboard, throw a life-ring into the water towards the person. Keep your eye on the person at all times and point towards the person. Shout “MAN OVERBOARD, STARBOARD (or PORT),” and call the bridge on the sound powered phone or squawk box to inform them without losing sight of the person if possible. If you hear someone hail "Man Overboard," pass the word to the bridge.
+
+## Your virtual expedition...
+
+Now let's get started on running your VirtualShip expedition. Follow the steps below to set up your coding environment, plan your expedition, and launch your simulation.
+
+```{note}
+Before that though, make sure you have had your research question approved by your instructor!
+```
+
+## 1) Register with the Copernicus Marine Data Store
+
+You will need to register for **Copernicus Marine Service** account (see [here](https://data.marine.copernicus.eu/register)), if you have not done so already. This is required to access the oceanographic data that VirtualShip uses to run your expedition.
+
+## 2) Set up your virtual machine
+
+You will be informed by your teacher if you will be using a cloud-based, pre-configured environment for VirtualShip (e.g., SURF Research Cloud) or if you should set up a local installation of the software. Please follow the instructions provided by your teacher to set up your virtual machine accordingly.
+
+## 3) Expedition route planning
+
+### NIOZ MFP tool
+
+The first step is to plan the expedition route for your chosen research question, bearing in mind the time needed for your sampling strategy, and traveling to and from a port suitable for research vessels. Remember, your approved proposal from your instructor may limit the amount of ship time you have received, so make sure to plan your route accordingly!
+
+Your route can be created with the online [NIOZ MFP tool](https://nioz.marinefacilitiesplanning.com/cruiselocationplanning#). Documentation on how to use the website can be found [here](https://surfdrive.surf.nl/files/index.php/s/84TFmsAAzcSD56F). Alternatively, you can watch this [video](https://www.youtube.com/watch?v=yIpYX2xCvsM&list=PLE-LzO7kk1gLM74U4PLDh8RywYXmZcloz&ab_channel=VirtualShipClassroom), which runs through how to use the MFP tool.
+
+```{note}
+The MFP tool is used by professional oceanographers to plan research expeditions, so this is a great opportunity to get a feel for how real-world oceanographic research is planned!
+```
+
+### Export the coordinates from MFP
+
+Once you have finalised your MFP expedition route, select "Export" on the right hand side of the window --> "Export Coordinates" --> "DD". This will download your coordinates as an .xlsx (Excel) file, which we will later feed into the VirtualShip protocol to initialise the expedition.\
+
+### _If using the SURF Research Cloud_... upload the coordinates to your virtual machine
+
+```{important}
+If you have not done so already, make sure you create a folder for your group's expedition data in the persistent storage space. You can do so by running e.g. `mkdir /data/virtualship-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.
+```
+
+Back in the JupyterLab interface, use the **file explorer** on the left hand side to navigate to the directory where your group will be running your expedition (e.g. `data/virtualship-storage/{your-group-name}`).
+
+Then upload the exported `.xlsx` file (it will be called something like `Coordinates-20251125T1403.xlsx`) by either dragging and dropping it from your laptop's Downloads into the file explorer, or by using the "Upload Files" button (the icon with an upward arrow) at the top of the file explorer panel.
+
+## 4) Expedition initialisation
+
+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".
+
+```{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/virtualship-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.
+```
+
+Now enter the following command in the Terminal (changing `EXPEDITION_NAME` to something more meaningful for your group's expedition):
+
+`virtualship init EXPEDITION_NAME --from-mfp {CoordinatesExport}.xlsx`
+
+```{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 own file.
+```
+
+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.
+
+## 5) Expedition scheduling & ship configuration
+
+```{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.
+```
+
+
+
+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).
+
+```{note}
+This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. For expeditions with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](../tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.
+```
+
+The easiest way to do so is to use the bespoke VirtualShip planning tool. Enter the following command in Terminal: `virtualship plan EXPEDITION_NAME`.
+
+### Ship speed
+
+In the planning tool which appears, under _Ship Config Editor_ > _Ship Speed & Onboard Measurements_, there is an option to change the ship speed. However, for this course, you should leave this as the default **10 knots** value.
+
+### Underway measurements
+
+VirtualShip is capable of taking underway temperature and salinity measurements, as well as onboard ADCP measurements, as the ship sails across the length of the expedition (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Underway-Data) for more detail). These underway measurements can be switched on/off under _Ship Config Editor_ > _Ship Speed & Onboard Measurements_ as well.
+
+For the underway ADCP, there is a choice of using the 38 kHz OceanObserver or the 300 kHz SeaSeven version (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#ADCP) for more detail on the two ADCP types).
+
+### Instrument/sensor configuration
+
+The most important instrument configuration setting to consider is the list of **sensors** for each instrument, which controls what type of measurements/variables the instrument records in the simulation and therefore what output data you will receive for each instrument.
+
+Sensor lists can be configured for each instrument under _Ship Config Editor_ > _Instrument Configurations_. For example, for the CTD instrument, you can specify which sensors to include in the simulation (e.g., `TEMPERATURE`, `SALINITY`, `OXYGEN`, etc.) by toggling the respective switches on or off.
+
+```{note}
+Sensor choices are only relevant for the instruments you plan to deploy as [underway measurements](#underway-measurements) or at waypoints across your expedition schedule [(see below)](#instrument-selection). For example, if you do not select to deploy a CTD at any of your waypoints, the CTD sensor choices will not affect any output data.
+```
+
+```{tip}
+See [here](../documentation/full_sensor_list.md) for more information on the sensors available for each instrument.
+```
+
+There are other instrument configurations settings that can be adjusted in the editor as well (e.g. `max_depth` for the CTD), but these are more advanced and in most cases do not need to be changed from the default values.
+
+### Waypoint datetimes
+
+```{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.
+```
+
+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.
+
+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.
+
+```{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.
+```
+
+```{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.
+```
+
+### Instrument selection
+
+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.
+
+```{tip}
+Click [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options) for more information on which instruments are available in VirtualShip, and a brief introduction to each.
+```
+
+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.
+
+### Save changes
+
+When you are happy with your ship configuration and schedule plan, press _Save Changes_ at the bottom of the planning tool.
+
+```{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.
+```
+
+## 6) Run the expedition
+
+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).
+
+```{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.
+```
+
+You can run your expedition simulation using the command:
+
+`virtualship run EXPEDITION_NAME`
+
+If this is your first time running VirtualShip, you will be prompted to enter your own Copernicus Marine Data Store credentials (these will be saved automatically for future use).
+
+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 ;-)
+
+```{important}
+VirtualShip may encounter 'real-life challenges' during the expedition, which simulate the various problems 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!
+```
+
+## 7) Results
+
+Upon successfully completing the simulation, results from the expedition will be stored in the `EXPEDITION_NAME/results` directory, written in `.parquet` [format](https://parquet.apache.org/).
+
+From here you can carry on your analysis. In general, we encourage you to use [Parcels](https://Parcels-code.org/) (i.e. `parcels.read_particlefile()`) to read in VirtualShip output files, and tools such as [Polars](https://www.pola.rs/) and/or [Pandas](https://pandas.pydata.org/) for further data analysis. We also provide various further [VirtualShip tutorials](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/index.html) which provide examples of how to visualise data recorded by the VirtualShip instruments. Use these to help you get started!
+
+If you are using VirtualShip in class, the same tutorial notebooks may be uploaded in your SURF Research Cloud environment for you to use and interact directly with the code (ask your teacher!). If so, these should be available in e.g. the `data/virtualship-storage/tutorials/` directory. You will notice that there is a notebook file dedicated to visualising each of the different instruments available in VirtualShip.
+
+To run these notebooks with your own data, you will need to copy the them over to your expedition working directory (i.e. `data/storage/{your-group-name}`). This can be done by either 1) using the file explorer panel in JupyterLab to copy the relevant files or the via the command line in Terminal. In the terminal, running `cp -r /data/storage/tutorials/* /data/storage/{your-group-name}/` would copy **all** the tutorial notebooks to your group's directory, so if you only want to copy specific ones, make sure to adjust the command accordingly.
+
+## Reporting
+
+Reporting your journey is an essential aspect of our oceanographic research expedition. It allows us to share our experiences, communicate our findings, and contribute to the broader scientific community. After each scientific expedition a cruise report should be written (or potentially in the case of this course, a presentation).
+
+You can find many cruise [reports](https://www.bodc.ac.uk/resources/inventories/cruise_inventory/reports/pe358.pdf) and [blogs](https://www.nioz.nl/en/news-and-blogs) online from many different cruises.
+
+Reporting our journey allows us to validate the data collected during our research activities. It provides context for our findings and helps ensure that our results are accurately interpreted and understood. Detailed reports enable us to cross-reference our observations with environmental conditions, sampling locations, and other relevant factors, enhancing the reliability and credibility of our data.
+
+Our reports also serve as valuable educational resources for students, educators, and the general public. They provide insights into the process of scientific inquiry, the challenges of conducting research at sea, and the significance of oceanographic discoveries.
+
+If your course assignment involves a presentation, we look forward to seeing the impact of your collective efforts during the presentations in a few weeks time!
+
+Please don't worry if your results are insufficient to answer your research question. Share your failure and things you would do different a next time instead!
+
+For example:
+
+- [Normalizing failure: when things go wrong in participatory marine social science fieldwork](https://publications.csiro.au/publications/publication/PIcsiro:EP2022-3465).
+- [Emotions and failure in academic life: Normalising the experience and building resilience](https://www.cambridge.org/core/journals/journal-of-management-and-organization/article/emotions-and-failure-in-academic-life-normalising-the-experience-and-building-resilience/91FD71A50A32404D8EDFFB7886FF3521).
diff --git a/docs/user-guide/teacher-content/Drifter_data_tutorial.ipynb b/docs/user-guide/teacher-content/Drifter_data_tutorial.ipynb
new file mode 100644
index 000000000..ec22454e9
--- /dev/null
+++ b/docs/user-guide/teacher-content/Drifter_data_tutorial.ipynb
@@ -0,0 +1,366 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Drifter Trajectory Plotting\n",
+ "\n",
+ "This notebook demonstrates a simple plotting exercise for drifter trajectory data, using the output of a VirtualShip expedition. There are example plots embedded in this notebook, but these will ultimately be replaced by your own versions if you are working through the notebook with your own expedition output.\n",
+ "\n",
+ "The plots we will produce are simple plots which visualise the trajectories of the drifters released at each waypoint of the VirtualShip expedition. We will also have a look at adding the sea surface temperature recorded by the drifters as they move through the ocean. Finally, the notebook will conclude with some example questions that you can think about as you interpret the drifter trajectories, using the Agulhas region as a case study."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Set up\n",
+ "\n",
+ "### Imports\n",
+ "\n",
+ "The first step is to import the Python packages required for post-processing the data and plotting. \n",
+ "\n",
+ "
\n",
+ "**TIP**: You may need to set the Kernel to the relevant (Conda) environment in the top right of this notebook to access the required packages! \n",
+ "
"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import xarray as xr\n",
+ "import matplotlib.pyplot as plt\n",
+ "import cmocean.cm as cmo\n",
+ "import numpy as np\n",
+ "import cartopy.crs as ccrs\n",
+ "import cartopy.feature as cfeature\n",
+ "import matplotlib.colors as mcolors\n",
+ "from matplotlib.collections import LineCollection"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Data directory\n",
+ "\n",
+ "Next, you should set `data_dir` to be the path to your expedition results in the code block below. You should replace `\"/path/to/EXPEDITION/results/\"` with the path for your machine.\n",
+ "\n",
+ "
\n",
+ "**TIP**: You can get the path to your expedition results by navigating to the `results` folder in Terminal (using `cd`) and then using the `pwd` command. This will print your working directory which you can copy to the `data_dir` variable in this notebook. Don't forget to keep it as a string (in \"quotation\" marks)!\n",
+ "
"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# set data directory path\n",
+ "\n",
+ "data_dir = \"/path/to/EXPEDITION/results/\" # set this to be where your expedition output data is located on your (virtual) machine"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Load data\n",
+ "\n",
+ "We are now ready to read in the data using the `xarray` package. You can carry on executing the next cells without making changes to the code…"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# load drifter data\n",
+ "\n",
+ "drifter_ds = xr.open_dataset(f\"{data_dir}/drifter.zarr\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Plotting\n",
+ "\n",
+ "
\n",
+ "**NOTE**: The plots produced next are a starting point for your analysis. You are encouraged to make further adjustments and enhancements to suit your own data and research question.\n",
+ "
\n",
+ "\n",
+ "We will now produce a plot of the drifters: their release locations at each waypoint (scatter markers), and their trajectories as they move through the ocean (coloured lines).\n",
+ "\n",
+ "From this we'll be able to get a first impression of the flow dynamics in the region. Are there any eddies or other features that stand out? Do the drifters stay together or spread out over time?\n",
+ "\n",
+ "
\n",
+ "**TIP**: You can adjust the lifetime of your simulated drifters by changing the \"Lifetime\" parameter in the VirtualShip expedition setup (see the _Instrument Configurations_ > _Drifter_ section in the `virtualship plan` tool), if you want them to flow for longer. Note, however, this does mean you would need to re-run the expedition to generate new data with the updated lifetime.\n",
+ "
\n",
+ "**NOTE**: This next section has no code to run and will likely look different from your own results - you will have run your own drifter simulations with different initial positions and times! This is just an example to demonstrate the kinds of drifter flow dynamics questions you can start to think about.\n",
+ "
\n",
+ "\n",
+ "The Atlantic and Indian Ocean meet around South Africa, and this is one of the most dynamic and energetic regions in the world ocean. The Agulhas retroflection is a region where the Agulhas current retroflects back into the Indian Ocean. This region is known for its strong currents and eddies, and is a region where many drifters have been deployed.\n",
+ "\n",
+ "Below is an example of a previous VirtualShip drifter experiment in the Agulhas region, showing the trajectories of 20 virtual drifters launched from a line at 31S between 31E and 32E (see red dots) on the 2 and 21 July 2023, one each day at midnight, simulated forward in time 90 days.\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "As you see, the drifters all start in the Agulhas Current (red dots at 30S) and most are initially advected southwestwards (although some first move northeastwards). At least two drifters take a path farther offshore, where their trajectories are much more eddying. When the inshore drifters reach approximately 25E, some of them start to circulate in eddies, and their tracks become even more convoluted.\n",
+ "\n",
+ "One potentially interesting analysis could be to compare the starting longitude to the final longitude. Do the drifters that start on the inshore side of the Agulhas Current have a higher chance to end up in the Atlantic Ocean (aka Agulhas leakage) than the drifters that start on the offshore side?\n",
+ "\n",
+ "\n",
+ "\n",
+ "How do you interpret this plot? Is it what you expected? \n",
+ "\n",
+ "What other analyses could be interesting to do with this data? Would it be interesting to look at the temperature or salinity that the drifters experience along their trajectories?"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": []
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "ship",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.12.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/user-guide/teacher-content/index.md b/docs/user-guide/teacher-content/index.md
index 89389d8e6..6d3c45a08 100644
--- a/docs/user-guide/teacher-content/index.md
+++ b/docs/user-guide/teacher-content/index.md
@@ -18,7 +18,20 @@ The VSC design focuses on creating didactically sound, authentic learning experi
We evaluated in several (under)graduate courses and find that the VirtualShip Classroom is highly engaging, and students report on enhanced confidence and knowledge [(Daniels et al. 2025)](https://current-journal.com/articles/10.5334/cjme.121).
-### Teaching materials
+### Train the teacher
+
+This section provides a step-by-step guide for teachers to get started with the VirtualShip Classroom. It includes instructions on how to set up the software, navigate the tooling, and use the teaching materials effectively.
+
+```{toctree}
+:maxdepth: 2
+
+train-the-teacher/train_the_teacher.md
+
+```
+
+### Further teaching materials
+
+
```{toctree}
:maxdepth: 1
diff --git a/docs/user-guide/teacher-content/train-the-teacher/_images/catalog.png b/docs/user-guide/teacher-content/train-the-teacher/_images/catalog.png
new file mode 100644
index 000000000..258d1ca5f
Binary files /dev/null and b/docs/user-guide/teacher-content/train-the-teacher/_images/catalog.png differ
diff --git a/docs/user-guide/teacher-content/train-the-teacher/_images/new_workspace.png b/docs/user-guide/teacher-content/train-the-teacher/_images/new_workspace.png
new file mode 100644
index 000000000..f1bbf256b
Binary files /dev/null and b/docs/user-guide/teacher-content/train-the-teacher/_images/new_workspace.png differ
diff --git a/docs/user-guide/teacher-content/train-the-teacher/_images/surf_invite.png b/docs/user-guide/teacher-content/train-the-teacher/_images/surf_invite.png
new file mode 100644
index 000000000..4e8bb23de
Binary files /dev/null and b/docs/user-guide/teacher-content/train-the-teacher/_images/surf_invite.png differ
diff --git a/docs/user-guide/teacher-content/train-the-teacher/_images/surf_storage.png b/docs/user-guide/teacher-content/train-the-teacher/_images/surf_storage.png
new file mode 100644
index 000000000..e8b294dc5
Binary files /dev/null and b/docs/user-guide/teacher-content/train-the-teacher/_images/surf_storage.png differ
diff --git a/docs/user-guide/teacher-content/train-the-teacher/_images/virtualship_catalog.png b/docs/user-guide/teacher-content/train-the-teacher/_images/virtualship_catalog.png
new file mode 100644
index 000000000..83a788662
Binary files /dev/null and b/docs/user-guide/teacher-content/train-the-teacher/_images/virtualship_catalog.png differ
diff --git a/docs/user-guide/teacher-content/train-the-teacher/file_permissions.md b/docs/user-guide/teacher-content/train-the-teacher/file_permissions.md
new file mode 100644
index 000000000..f725747e4
--- /dev/null
+++ b/docs/user-guide/teacher-content/train-the-teacher/file_permissions.md
@@ -0,0 +1,31 @@
+# Learner guide: File Permissions on the SURF Research Cloud
+
+The shared storage directory in the SURF RC virtual machine (e.g. `data/virtualship-storage/`) is configured such that all users of the workspace can read and access the files within it, but only the owner of a file can edit it. This can prevent seamless collaboration on the same expedition content, for example within your group.
+
+## How to share and edit files
+
+To enable collaboration on expedition content within your group, you can change the permissions of files within the shared storage directory to allow editing by all users. This can be done using the `chmod` command in the terminal (see [here](https://en.wikipedia.org/wiki/Chmod) for more detail on the `chmod` command).
+
+For example, for your `expedition.yaml` file, you can run the following command in the terminal (after navigating to your group's directory and replacing `EXPEDITION_NAME` with your actual expedition directory):
+
+```
+chmod 777 /EXPEDITION_NAME/expedition.yaml
+```
+
+This will allow _all_ users in the SURF environment to edit the `expedition.yaml` file. You can repeat this process for any other files within the shared storage that you wish to collaborate on with your group members.
+
+```{warning}
+Be careful when using `chmod 777`, as it grants read, write, and execute permissions to **all** users. This means _everyone_ who has access to the SURF environment can edit the file (i.e. the whole class), which could cause accidental changes or deletions if not used carefully. We recommend you make backups of important files before changing permissions.
+
+This is generally fine for the purposes of this classroom activity where the virtual environment is a controlled setting, but in other contexts, it can pose security risks. Always ensure you understand the implications of changing file permissions and consider more restrictive permissions when necessary.
+
+**TL;DR the `chmod 777` command is fine for this unit, but be very careful when using it in other contexts!**
+```
+
+## Reverting the file permissions
+
+If you wish to revert the file permissions back to only allowing the owner to edit, you can run the following command in the terminal:
+
+```
+chmod 644 /EXPEDITION_NAME/expedition.yaml
+```
diff --git a/docs/user-guide/teacher-content/train-the-teacher/lesson_plans.md b/docs/user-guide/teacher-content/train-the-teacher/lesson_plans.md
new file mode 100644
index 000000000..d37409527
--- /dev/null
+++ b/docs/user-guide/teacher-content/train-the-teacher/lesson_plans.md
@@ -0,0 +1,79 @@
+# Example lesson plans
+
+## 1) Using the `VirtualShip` software
+
+This example lesson plan is suitable for students with programming knowledge. Students hand in a short research proposal and expedition plan for feedback. They use the `VirtualShip` software to conduct their virtual expedition and analyse the results. They show their results in a presentation that can be assessed. This assignment is recommended to be undertaken in groups, because collaborative learning is beneficial. Suggested learning goals are that students can:
+
+- identify and address (practical) challenges involved in sea-based research;
+- give examples of uncertainty and the synoptic nature of sea-based observations;
+- analyze and interpret sea-based observations;
+- plan a comprehensive research expedition.
+
+**An example lesson plan is as follows:**
+
+| Background lecture on observing the ocean |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _1-2 hours depending on the amount of detail, can also be viewed by student before class as preparation_ |
+| Presentation about observing and measuring the ocean, covering different types of observations and instruments followed by steps to conduct ocean research. Sample presentation sides are available on [Edusources](https://edusources.nl/materials/90a4df16-427b-4f95-b2c2-b7bc9b2c6b81/presentation-about-observing-and-measuring-the-ocean). |
+
+| Prep work / homework |
+| ------------------------------------------------------------------------------------------------------------------ |
+| _1 hour of homework_ |
+| Introduction to VirtualShip research proposals, available [here](../../assignments/Research_proposal_intro.ipynb). |
+
+| Tutorial 1 |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| _2 hours in class, 4 hours of homework_ |
+| Students hand in a short VirtualShip [research proposal](../../assignments/Virtualship_research_proposal.ipynb) for the lecturer (or an expert colleague) to provide feedback. We recommend ensuring that the research questions are focused enough to be researchable in the granted ship time (typically up to three weeks). |
+
+```{note}
+Because data are taken from the Copernicus Marine Data Store (see [here](../../documentation/copernicus_products.md) for more technical details), expeditions can take place from 1993 to present (up to 2 weeks into the future).
+```
+
+```{tip}
+An interesting addition can be to let students use the [MyOcean Pro viewer](https://data.marine.copernicus.eu/viewer/) to, for example, track an eddy using sea surface height and deploy their instruments therein.
+```
+
+| Tutorial 2 |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _4 hours in class_ |
+| Students begin their expedition simulations. Please refer back to the main train-the-teacher [documentation](train_the_teacher.md/#sailing-the-ship) for further instructions on running the software in the classroom. |
+
+| VR component |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A range of 360° videos are available on [YouTube](https://www.youtube.com/@VirtualShipClassroom). If time allows, let students watch one or more of the ship tours and a-day-at-sea videos. |
+
+| Tutorial 3 |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _2-4 hours in class, 10 hours of homework_ |
+| Encourage the students to analyze their own data using the [example tutorials](../../tutorials/index.md). For more advanced courses, students can be asked to produce further, derived quantities as part of their analysis. |
+
+| Presentations |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _Number of hours in class will depend on the number of groups that present, we suggest at least 10-15 minutes for each group including questions_ |
+| Students present their results. An example presentation rubric is available on [Edusources](https://edusources.nl/materials/44ff66eb-537d-4ab9-a844-0fba9bd8d240/rubric-to-grade-advanced-student-presentations). |
+
+## 2) _Not_ using the software
+
+It is also possible to skip using the `VirtuaShip` software entirely and instead use the Open Education Resources (and potentially the VR component) to teach about oceanography and research methods. This is a good option if you want to focus on the learning outcomes without the technical overhead of using the software.
+
+This example lesson plan is suitable for all students, regardless of programming knowledge. Students hand in a research proposal and an accompanying expedition plan that can be assessed. The assignment can be conducted in groups or individually. Suggested learning goals are that students can:
+
+- identify practical challenges of planning sea-based research;
+- plan a comprehensive research expedition.
+
+**An example lesson plan is as follows:**
+
+| Background lecture on observing the ocean |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _1-2 hours depending on the amount of detail, can also be viewed by student before class as preparation_ |
+| Presentation about observing and measuring the ocean, covering different types of observations and instruments followed by steps to conduct ocean research. Sample presentation sides are available on [Edusources](https://edusources.nl/materials/90a4df16-427b-4f95-b2c2-b7bc9b2c6b81/presentation-about-observing-and-measuring-the-ocean). |
+
+| Tutorial |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _2 hours in class, 4-8 hours of homework_ |
+| In class, students discuss their research questions and approach with an expert before submitting a VirtualShip [research proposal](../../assignments/Research_Proposal_only.ipynb). This is a good opportunity to invite oceanography experts to share their perspectives and insights, if you are not one yourself. |
+
+| VR component |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A range of 360° videos are available on [YouTube](https://www.youtube.com/@VirtualShipClassroom). If time allows, let students watch one or more of the ship tours and a-day-at-sea videos. |
diff --git a/docs/user-guide/teacher-content/train-the-teacher/surf_set_up.md b/docs/user-guide/teacher-content/train-the-teacher/surf_set_up.md
new file mode 100644
index 000000000..6a5bd2dff
--- /dev/null
+++ b/docs/user-guide/teacher-content/train-the-teacher/surf_set_up.md
@@ -0,0 +1,104 @@
+# Educator guide: Set up the SURF Research Cloud (RC)
+
+```{note}
+For this guide, we will assume that you are the course convenor, already have access to the SURF Research Cloud and have credits available.
+```
+
+```{tip}
+For general information on how to use the SURF Research Cloud, please refer to their [documentation](https://servicedesk.surf.nl/wiki/spaces/WIKI/pages/9798172/SURF+Research+Cloud).
+```
+
+In this documentation, we will primarily be working from the SURF Research Cloud dashboard (or "portal") which is available at: [https://portal.live.surfresearchcloud.nl/dashboard/workspaces](https://portal.live.surfresearchcloud.nl/dashboard/workspaces). You can log in to the dashboard using your institutional credentials.
+
+## The VirtualShip Catalog item
+
+The VirtualShip Team has created a pre-configured "Catalog item" on the SURF Research Cloud that contains all the necessary software and dependencies for running VirtualShip. This includes a JupyterLab environment, the VirtualShip software itself, and a selection of useful post-processing packages (`xarray`, `matplotlib`, `cartopy`, `plotly` etc.).
+
+This means you can deploy VirtualShip on a SURF Research Cloud workspace 'out of the box'. This guide will go through the steps you'll need to take to get access to this pre-configured environment and to set up a workspace for your students.
+
+First please log in to the SURF Research Cloud [dashboard/portal](https://portal.live.surfresearchcloud.nl/dashboard/workspaces) and navigate to the "Catalog" heading (Figure 1).
+
+
+_Figure 1. Navigating to the Catalogue via the SURF Research Cloud dashboard (screenshot)._
+
+You should see a wide selection of available catalogue items. You can search for the VirtualShip catalogue item by typing "VirtualShip" in the search bar (Figure 2). When you find the VirtualShip catalogue item, click on it to view more details and to **request access**. The VirtualShip Team will then review your request and grant accesss.
+
+
+_Figure 2. The pre-configured VirtualShip Catalogue item (screenshot)._
+
+## Arranging storage space
+
+```{important}
+The persistent storage space is different from the `home` directory of the workspace, which you first enter when launching the workspace. `home` is not persistent and its contents will be lost when the workspace is stopped!
+```
+
+It is important to have persistent `storage` associated with your workspace. This is where students should base their work and save any expedition, configuration or output files. You can request a persistent storage space via the SURF Research Cloud dashboard (Figure 3).
+
+
+_Figure 3. Creating persistent storage space via the SURF Research Cloud dashboard (screenshot)._
+
+As a rough rule of thumb, a 50GB storage space should be sufficient for a classroom activity, as the VirtualShip output files are generally not very large.
+
+```{tip}
+Once attached to the workspace you create (see the next section), the storage space (with the name you chose during set up) should be available under the `/data` directory in the workspace. Typical VirtualShip workflows will then get (groups of) students to make their own subdirectory in `/data/{storage-name}` for their expeditions.
+```
+
+## Creating a new workspace
+
+Next, return to the main dashboard and click to create a new `workspace` (Figure 4).
+
+
+_Figure 4. Creating a new workspace via the SURF Research Cloud dashboard (screenshot)._
+
+From here, you can run through the steps to create a new workspace. You will be prompted to select a catalogue item, and you should select the VirtualShip catalogue item that you requested access to in the previous step. You will probably have to use the search bar again and it should be visible once you have been granted access.
+
+You should also attach the `storage` you created in the previous step. This ensures persistent storage for students across sessions. You can also select the size of the workspace (CPU, RAM, storage) and the duration for which it will be available.
+
+```{tip}
+When it comes to selecting a "Cloud Provider" (and if you have multiple choices), we recommend simply sticking to the SURF HPC Cloud for reduced credit consumption.
+
+Generally, a classroom VirtualShip activity will not require large amounts of resource, so you can also usually select a smaller workspace size (e.g. 2 or 4 CPU, 16 GB RAM). Choosing a higher CPU count will use up more credits!
+
+You can always "pause" a workspace when it is not in use, which will reduce credit consumption, and then "resume" it when needed again.
+```
+
+## Inviting students to the workspace
+
+Once your workspace is set up, you can invite students to join it. This is facilitated through the separate [SURF Research Access Management (SRAM)](https://sram.surf.nl/collaborations-overview) platform.
+
+After logging in, select to your collaboration and, as an admin, you should be able to navigate to the "Members" tab and invite new members to the collaboration (Figure 5).
+
+
+_Figure 5. Inviting students to the collaboration via SRAM (screenshot)._
+
+You will need to provide the email addresses of your students and they will receive an invitation to join the collaboration. Once they have accepted the invitation, they should be able to log in to the SURF Research Cloud via their institutional credentials and see/access the workspace you created before.
+
+## Student access to the workspace
+
+Please refer back to the main train-the-teacher [documentation](train_the_teacher.md/#student-access-to-the-workspace) for information on how students can access the workspace and perform the final steps to use the VirtualShip software.
+
+## Updating the workspace
+
+The VirtualShip Team will be responsible for maintaining and keeping the catalogue item up to date. However, if you ever come across a problem with the software (e.g. suspected bugs) or you would like to request a new feature which should be added to the version in the catalogue item, please get in touch with the Team via our [GitHub issue tracker](https://github.com/Parcels-code/virtualship/issues) or by email: [virtualship@uu.nl](mailto:virtualship@uu.nl). We are open to requests and will try to accommodate them as quickly as possible!
+
+If the software has been updated when your workspace is already active, you will need to update your own version in the workspace to use the new version.
+
+You can do so by running the following commands in the Terminal in your launched workspace (see the Note block below though as you will need to replace `{branch-name}` with the name of the branch you want to install):
+
+```bash
+# activiate the VirtualShip environment
+conda activate virtualship
+
+# this will install the updated version of VirtualShip
+sudo /etc/miniconda/envs/virtualship/bin/pip install --upgrade git+https://github.com/Parcels-code/virtualship@{branch-name}
+```
+
+After a successful update, you should restart the workspace to ensure that the new version is being used. Students should then also have access to the updated version of VirtualShip.
+
+```{note}
+The specific branch name to use (`{branch-name}`) will depend on the version of VirtualShip you want to install. For example, if we have coordinated to add a new feature which is not yet in the `main` branch, we may ask you to install from a specific branch. If you are unsure which branch to use, please [contact](train_the_teacher.md/#feedback-support) the VirtualShip Team.
+```
+
+```{important}
+This instruction involves the use of `sudo` to install the updated version of VirtualShip, so this should only be done by the course convenor (or someone with admin privileges).
+```
diff --git a/docs/user-guide/teacher-content/train-the-teacher/surf_student_access.md b/docs/user-guide/teacher-content/train-the-teacher/surf_student_access.md
new file mode 100644
index 000000000..5ad506af9
--- /dev/null
+++ b/docs/user-guide/teacher-content/train-the-teacher/surf_student_access.md
@@ -0,0 +1,80 @@
+# Learner guide: Accessing the SURF Research Cloud
+
+## Accepting SURF Research Cloud invite
+
+In your student email you will have an invite from SURF Research Access Management (SRAM) to join a project on the SURF Research Cloud. Please accept this invite.
+
+## Open the environment
+
+Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), or click on the link in the email, and click "access" on the shared workspace.
+
+```{important}
+A known issue is that you may hit a "server error" when accessing the workspace. If this happens, keep on trying (refresh), as the server spin-up can be a bit overloaded at times, but should get through eventually.
+
+Unfortunately this is out of our control. Clearing your browser cache and cookies, and/or trying via an incognito/private window may also help. We find that with persistence, the workspace will eventually load.
+```
+
+## The JupyterLab workspace layout and additional config
+
+```{note}
+This only needs to be done once during setup!
+```
+
+In the JupyterLab workspace, you'll see the following (or similar) in your file explorer (left-hand side of the screen):
+
+```
+.
+├── KERNEL-README.ipynb
+├── data
+│ └── datasets
+| └── virtualship-storage <--- The shared persistent storage
+└── scratch
+```
+
+```{note}
+The persistent storage folder may be called something slightly different in your instance, for example it may have a name specific to the course you are enrolled on, such as `data/storage-osl`, `data/storage-dyoc` or `data/storage-1-sept`.
+```
+
+In the Jupyter launcher, you can open a Terminal session by clicking on "Terminal" button under the "Other" section, or by going to the "File" menu --> "New" --> "Terminal". From here you can navigate the workspace directory structure and run commands.
+
+```{tip}
+`VirtualShip` is a command line interface (CLI) based tool. We will be working predominantly via the command line in Terminal (typing out commands instead of pointing and clicking). If you are unfamiliar with what a CLI is, see [here](https://www.w3schools.com/whatis/whatis_cli.asp) for more information. In our case, the Terminal is just a way to access the CLI on the SURF Research Cloud virtual machine.
+```
+
+The `data/virtualship-storage` folder is your persistent storage. Here you can make a folder (e.g., by running `mkdir data/virtualship-storage/{your-group-name}` as a command in the Terminal, replacing `{your-group-name}` with your group name) to house your work for the unit. It is important to save all your work in this folder, so that it is still there the next time you log onto the remote workspace. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it.
+
+## Initialize conda
+
+To be able to run VirtualShip from the Terminal, we need to take some additional steps. To make the already installed conda-tool available for yourself, you have to initialise your Terminal shell.
+
+Back in the "Terminal" tab, type: `/etc/miniconda/bin/conda init`
+
+Close the Terminal tab and start a new one.
+You will see that the Terminal prompt has changed to something like
+
+```bash
+(base) metheuser@mywsp:
+```
+
+This is conda telling you that you are currently in the "base" environment.
+
+From here, you already have another environment set up for you. Running `conda env list` in the Terminal, you should see:
+
+```bash
+conda env list
+
+# conda environments:
+#
+base * /etc/miniconda
+virtualship /etc/miniconda/envs/virtualship`
+```
+
+Here you can do `conda activate virtualship` to activate the environment called "virtualship". This environment is a shared environment among all workspace users that can be centrally updated.
+
+With the `virtualship` environment, you now have access to the `virtualship` command in your Terminal, which can be confirmed by running `virtualship --help`.
+
+From here you can `cd` ('change directory') into `data/virtualship-storage/{your-group-name}` and run `virtualship` commands. You can now return to your course materials and follow the instructions to run the VirtualShip software.
+
+## Extra tip: Working in Jupyter _Notebooks_
+
+Finally, when you're working in Jupyter _Notebooks_ (`*.ipynb` files), you are able to access the conda environment with `virtualship` and related dependencies by switching the Kernel in the top right of the UI.
diff --git a/docs/user-guide/teacher-content/train-the-teacher/train_the_teacher.md b/docs/user-guide/teacher-content/train-the-teacher/train_the_teacher.md
new file mode 100644
index 000000000..eb374c522
--- /dev/null
+++ b/docs/user-guide/teacher-content/train-the-teacher/train_the_teacher.md
@@ -0,0 +1,235 @@
+# Train the teacher
+
+We're pleased that you've chosen to use VirtualShip in your teaching! This guide is designed to help you get started with the platform and make the most of its features in your classroom.
+
+The instructions are currently tailored primarily for educators at partner instutions, as part of the [VirtualShip NKO Scale Up project](https://virtualship.parcels-code.org/blog/scaleup-grant). However, we welcome all educators to explore the guide and adapt it to their own teaching contexts. For more tailored support, please see the [Feedback & support](#feedback-support) section at the end of this guide!
+
+For this guide, we will assume that you're familiar with the purpose and motivations for using VirtualShip. We will be going through all the practical steps to get you up and running.
+
+```{tip}
+This is a long guide, intended as a blueprint for setting up your teaching... use the table of contents (on the right) to navigate to the sections that are most relevant to you!
+```
+
+```{important}
+No matter how you choose to implement the VirtualShip Classroom, we ask that you please ask your students to complete the end-of-course survey (see [below](#end-of-course-survey)) so that we can collect feedback on their experience with the VirtualShip Classroom.
+
+This is really important for us to continue to research, evaluate and improve the VirtualShip Classroom! 🙂
+```
+
+## Foreword
+
+### Introduction
+
+As a reminder, where we refer to the VirtualShip Classroom, we refer to the combination of three core pillars: the `VirtualShip` software, VR / 360° videos and the Open Education Resources. The VirtualShip Classroom is designed to be flexible, the different components interchangable and can be used in a variety of ways, from highly structured to more open-ended activities.
+
+We discuss some example lesson plans [below](#lesson-plan-approaches), but we encourage you to adapt these to your own teaching context and learning objectives. We don't intend for the guidance to be rigid and we encourage you to think about the intended learning outcomes (ILOs) for your students and adapt the activities accoridingly.
+
+### Our advice
+
+In our experience, the most successful implementations of VirtualShip are those where the activities have a strong **narrative** ("You have been granted _ weeks of ship time!") and where students are given ample **freedom**, for example to choose their own research question, location and timing (perhaps from a selection of [case studies](../../assignments/case_studies_virtualship.ipynb)).
+
+```{note}
+Check out evaluations of the VirtualShip Classroom in published paper(s) [here](https://virtualship.parcels-code.org/publications), for more information on the pedagogical approach!
+```
+
+That being said, the VirtualShip Classroom is a flexible platform and can be used in a variety of ways, from highly structured to more open-ended activities.
+
+## Lesson plans
+
+The 'core' implementation of the VirtualShip Classroom has traditionally followed a structure of:
+
+1. Background lecture on observing the ocean and research methods
+2. Introduction to the VirtualShip software (if applicable)
+3. In-class tutorials and exercises
+4. Assignment hand-in (presentation or article) and feedback.
+
+**More detail on all of these components (including links to lecture slides etc.) can be found in the [example lesson plans](lesson_plans.md) documentation.**
+
+```{tip}
+No matter how you choose to implement the VirtualShip Classroom, it may be useful to check out some case study [examples](../../assignments/case_studies_virtualship.ipynb) of research questions and expeditions that students could undertake.
+```
+
+### Adding the VR / 360° videos component
+
+The example lesson plans referred to above suggest including the VR component in your teaching. This is not a requirement, but we do recommend it as it can enhance the learning experience and provide students with a more immersive understanding of the challenges of sea-based research.
+
+All the videos, available on [YouTube](https://www.youtube.com/@VirtualShipClassroom), can be viewed on students' own devices using their mouse to view in 360° if on a laptop/desktop or by moving their devices if watching on a mobile device. However, if the facilities exist at your instition, or you have access to VR headsets, you could use videos in a full VR environment. For more advice on how to arrange this, please get in touch with the VirtualShip Team at [virtualship@uu.nl](mailto:virtualship.uu.nl).
+
+
+
+## Setting up a programming environment
+
+```{tip}
+As mentioned in the [Lesson plans section](#lesson-plans), it is not necessary to use the `VirtualShip` software component as part of the VirtualShip Classroom. If this is the case, you can skip the next sections, and refer to the Open Education Resources mentioned in the relevant [example lesson plan](./lesson_plans.md/#not-using-the-software).
+
+❗️ Please do still ask students to complete the end-of-course survey (see [below](#end-of-course-survey)) though so that we can collect feedback on their experience with the VirtualShip Classroom.
+```
+
+There are broadly two ways to set up the `VirtualShip` software for teaching:
+
+1. Each student uses a local installation of the software (on their own device), installed via a package manager such as `pip`, `conda` or `pixi`.
+2. A software environment is pre-configured on a cloud-based platform.
+
+Option 1) requires less preparation but can be more challenging for students to set up (especially if inexperienced) with frequent machine-dependent issues (and a lot of time spent on troubleshooting during lesson time!). Option 2) requires more preparation as the course convenor but is generally easier to support in-class, especially for larger groups. It also has the advantage that all students are working with the same resources, versions and infrastructure, which is beneficial for reproducibility and fairness.
+
+In previous implementations at Utrecht University (where the VirtualShip Classroom originated), we have primarily used Option 2) on the [SURF Research Cloud](https://www.surf.nl/en/services/compute/surf-research-cloud).
+
+### Local installation
+
+Students can install the `VirtualShip` software on their own devices using `conda` from the command line:
+
+```bash
+# create a new conda environment called 'virtualship' and install the software from the conda-forge channel
+conda create -n virtualship -c conda-forge virtualship
+
+# activate the environment
+conda activate virtualship
+```
+
+This creates an environment named `virtualship` with the latest version of the `VirtualShip` software installed. Students can then run the software from the command line in this environment.
+
+```{tip}
+If you have access to a computer lab, you may also consider installing the software on the those machines. This is similar to a local installation but can bring similar benefits to a cloud-based environment (i.e. the environment is prepared ahead of the lesson, each student has the same resources), but with less flexibility for students to work from home or on their own devices.
+```
+
+### Pre-configured environment (cloud based)
+
+This documentation focuses on a set up specifically on the [SURF Research Cloud](https://www.surf.nl/en/services/compute/surf-research-cloud)). The concepts are similar for other cloud-based platforms, but you may need to adapt them to your own context.
+
+```{important}
+Note, the SURF Research Cloud is only available to Dutch institutions. Other cloud-based platforms (e.g. Google Colab, Binder, etc.) could be used as well but we have not extensively tested these platforms.
+```
+
+For detailed instructions on how to set up the pre-configured VirtualShip environment on the SURF Research Cloud, please refer to the set up guide below:
+
+```{nbgallery}
+
+surf_set_up.md
+```
+
+#### Student access to the workspace
+
+When students log in to the SURF Research Cloud and click to access the workspace, they will be taken to a JupyterLab environment. This is where they can run the VirtualShip software and work on their expeditions.
+
+```{important}
+A known issue is that students may hit a "server error" when accessing the workspace. If this happens, keep on trying (refresh), as the server spin-up can be a bit overloaded at times, but should get through eventually.
+
+Unfortunately this is out of our control. Clearing your browser cache and cookies, and/or trying via an incognito/private window may also help. We find that with persistence, the workspace will eventually load for all users.
+```
+
+We recommend distributing the following instructions sheet to your students once you have invited them to the workspace and ahead of first using the `VirtualShip` software, which outlines how to access the workspace and initialise the pre-configured environment in their respective account spaces:
+
+```{nbgallery}
+
+surf_student_access.md
+```
+
+```{note}
+If you, as the course convenor/workspace owner, would also like to use the `VirtualShip` software, you will also need to carry out the steps in the instructions sheet above to initialise the environment in your own account space, as a one-time set up step.
+```
+
+#### Collaboration within groups
+
+We often recommend that students work in small groups (e.g. 2-3 students) for their VirtualShip projects. Each student should have their own account/access to the workspace and they can work from the same sub-directory in the `/data/{storage-name}` storage space.
+
+Unfortunately, though, the SURF Research Cloud does not currently support smooth, simultaneous collaboration on the same files in the workspace. This means that students will need to coordinate amongst themselves to ensure that they are not overwriting each other's work. You can refer the students to the file permissions tutorial below for more information on how to arrange access to each other's files and directories in the workspace:
+
+```{nbgallery}
+
+file_permissions.md
+```
+
+## Sailing the ship
+
+Now that the technical set up is complete, we are ready to start getting students going with using the `VirtualShip` software! 🚢 🥳
+
+The general-purpose **Quickstart guide** below provides a minimal overview of the basic commands and workflow to get started with the software... perhaps useful for you as the course convenor to get a quick overview of the software.
+
+However, for teaching applications we recommend distributing the student-focused **"Sail the ship" guide** below, which is designed to be more accessible and includes additional context and narrative elements for students.
+
+```{nbgallery}
+
+../../quickstart.md
+../../assignments/sail_the_ship.md
+
+```
+
+### Reviewing Expedition proposals
+
+The "Sail the ship" guide above is designed to be used in conjunction with a lesson plan similar to that presented in the [example lesson plans](lesson_plans.md) documentation. It relies on students having already chosen a research question, submitting a proposal and having it approved by their instructor/you.
+
+Reviewing and approving the proposals is a good time to check that students have a realistic plan for their expedition, and we find it is beneficial to prescribe a maximum ship time limit (e.g. 3 weeks) to ensure that students are thinking about the practicalities of their research question and sampling strategy.
+
+```{tip}
+The ship time limit can not currently be set in the `VirtualShip` software, but you could enforce it as part of your assignment instructions.
+```
+
+### Additional resources used in the VirtualShip workflow
+
+You will notice in the "Quickstart" and "Sail the Ship" guides that there are a number of additional resources that get used in the VirtualShip workflow. These include the:
+
+- [Copernicus Marine Data Store](https://data.marine.copernicus.eu/).
+ - This source of the oceanographic data used in VirtualShip (streamed under-the-hood in the `VirtualShip` software).
+ - As mentioned in the guides, students will need to set up a _free_ account to access the data. We recommend asking students to do this ahead of time, to avoid delays during the lesson.
+ - Users are prompted to enter their credentials when they first run the `VirtualShip` software, and the credentials are then stored for future use.
+- [Marine Facilities Planning (MFP) tool](https://nioz.marinefacilitiesplanning.com/cruiselocationplanning#)
+ - This tool is used to plan the expedition route and generate the coordinates for the VirtualShip protocol.
+ - It is an authentic tool used by real-life oceanographers to plan their research expedtions, and is a good example of the type of software that students may encounter in their future careers.
+ - There is no sign-up required to use the tool, but students may need some time to get familiar with it.
+ - As mentioned in the guides, the `VirtualShip` software can ingest exported coordinate files straight from MFP.
+
+### Simulating Real Life Challenges
+
+You will notice mentions to "Real Life Challenges" (RLCs) in the "Quickstart" and "Sail the Ship" guides. These are a module in the `VirtualShip` software that can be used to simulate real-life challenges that oceanographers may encounter during their research expeditions. These include things like equipment failures, bad weather, and other unexpected events. They usually require active intervention from the students to resolve.
+
+They are not 'bugs' and are instead a feature that can be used to teach students about the challenges of oceanographic research: that things rarely go to plan, the scheudle will probably have to adapted and that some contingency planning is required.
+
+The RLCs can be configured by setting the difficulty level (`--difficulty-level`) parameter in the virtualship run command. It can be set to `“easy”` (no problems, default in the main software distribution), `“medium”` or `“hard”` (e.g. `virtualship run EXPEDITION_NAME --difficulty-level medium`).
+
+For maximum authenticity, you can set `--difficulty-level hard`, which will scale the number of problems encountered by the complexity of the expedition (longer duration, more waypoints, more instruments will lead to more problems). `--difficulty-level medium` will limit the number of problems to a maximum of 2, regardless of the expedition complexity.
+
+```{tip}
+We can arrange that the default difficulty level is set to `medium` for your course, if you would like to use the RLCs in your teaching without having to ask students to add the `--difficulty-level` parameter themselves on each run. This can enhance immersivity as the RLCs appear more unexpected from the students' perspective. Please [get in touch](train_the_teacher.md/#feedback-support) if this is something you would like to do.
+```
+
+```{note}
+It's possible that students will explore this VirtualShip documentation site and understand that they can disable the RLCs by setting `--difficulty-level easy`. If you would like to ensure that students must encounter the RLCs, we suggest making a discussion of how they dealt with these issues part of their assignment. Similar to the ship time limit mentioned previously.
+```
+
+### VirtualShip output
+
+Once the simulations have run, the VirtualShip output files will be available in the workspace. These are in `.parquet` format.
+
+```{tip}
+`VirtualShip` depends heavily on `Parcels` under-the-hood for simulating the instrument behaviours. As such, the VirtualShip output is built on `Parcels` output formats. See the `Parcels` [documentation](https://docs.oceanparcels.org/en/main/user_guide/getting_started/tutorial_output.html) for more information on how to work with the `.parquet` files.
+```
+
+VirtualShip does not provide explicit tooling for analysis, as this will be dependent on the specific learning objectives and research questions of the students. However, we have provided a number of **example tutorials** (see below), which provide sample code for simple first analysis of the VirtualShip output, for each instrument type.
+
+```{nbgallery}
+
+../../tutorials/index.md
+
+```
+
+We suggest that you encourage students to explore these tutorials and use them as a starting point for their own analysis. You might consider uploading copies of these notebooks to the shared storage space if you are using a cloud-based environment, so that students can access them without having to copy them from the documentation site. The easiest way to do so is to 'wget' the raw notebooks from the codebase, for example:
+
+```bash
+
+# copy the drifter data tutorial to the current directory
+wget http://raw.githubusercontent.com/Parcels-code/virtualship/refs/heads/main/docs/user-guide/tutorials/Drifter_data_tutorial.ipynb
+```
+
+## ❗️ End-of-course survey
+
+```{important}
+We would be really grateful for your help in collecting feedback from your students on their experience with VirtualShip. This will help us to improve the platform, research its impact and to better understand how it is being used in different contexts.
+
+Please distribute the following survey link to your students at the end of the course: https://survey.uu.nl/jfe/form/SV_0OLu4lKYPyLhAxM
+```
+
+## Feedback & support
+
+If you have any feedback on this guide, would like additional support or if you have suggestions for improvements, please reach out to us via our [GitHub issue tracker](https://github.com/Parcels-code/virtualship/issues) or by email: [virtualship@uu.nl](mailto:virtualship@uu.nl).
+
+We are always happy to hear from educators and will do our best to support you in your teaching with VirtualShip!