From ea3b58cae3fd57e9f4edfcb9bcfefdb09c22a798 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Mon, 16 Feb 2026 11:13:00 +0100 Subject: [PATCH 1/3] add example_expedition tutorial --- docs/conf.py | 1 + .../UU-dyoc/example_expedition.md | 75 +++++++++++++++++++ docs/user-guide/teacher-content/index.md | 7 ++ 3 files changed, 83 insertions(+) create mode 100644 docs/user-guide/teacher-content/UU-dyoc/example_expedition.md diff --git a/docs/conf.py b/docs/conf.py index 3995449c..a630f491 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -83,6 +83,7 @@ "user-guide/tutorials/surf_collaborative_setup": "user-guide/_images/freepik_research_vessel.jpg", "user-guide/tutorials/surf_research_cloud_setup": "user-guide/_images/freepik_research_vessel.jpg", "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", } sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"} diff --git a/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md b/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md new file mode 100644 index 00000000..a1dd0fe9 --- /dev/null +++ b/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md @@ -0,0 +1,75 @@ +# VirtualShip Example Expedition + +In this guide we will conduct an example virtual expedition. This expedition is not intended to be an in-depth tutorial on how to use all features of VirtualShip, but rather a general overview of the main steps of running the code itself, in preparation for your own expeditions. You will become more familiar with the SURF virtual environment, the command line interface and VirtualShip configuration files. + +--- + +```{important} +This guide assumes you have already logged into and set up (initialised conda) the SURF virtual environment. +``` + +## 1) Create a new directory for your VirtualShip expeditions + +First, you should navigate to the shared storage directory on the virtual machine (e.g. `cd data/virtualship_storage/`) and create a new directory for your group's VirtualShip expeditions (e.g. `mkdir {group_name}`, replacing `{group_name}` with your actual group name). This is where you will run your expeditions and store the results. + +## 2) Expedition initialisation + +```{note} +For your real expeditions, there will be a more involved expedition planning stage before this, including route planning and scheduling. Here, we are just going to use the default VirtualShip example expedition route and schedule. +``` + +You should now navigate to your group's directory (i.e. `cd data/virtualship_storage/{group_name}/`). Then run the following command in the terminal: + +``` +virtualship init EXPEDITION_NAME +``` + +This will create an expedition folder/directory called `EXPEDITION_NAME` (or change the name as desired) with a single file: `expedition.yaml` containing details on the ship and instrument configurations, as well as an _example_ expedition route and schedule. + +## 3) Expedition planning and the `expedition.yaml` file + +```{important} +For the purposes of this example expedition, you do not need to make any _edits_ to the `expedition.yaml`! This section is just to introduce you to the file and its purpose. +``` + +Navigate to the `expedition.yaml` file and open it in the (Jupyter Lab) text editor. This is where the configuration of your expedition is stored and where you can make changes to the expedition route, schedule and ship/instrument configurations. + +You will see that the default is a basic route comprised of five waypoints on or near the equator, chosen for no particular scientific reason but just as an example, with deployment of a variety of different instruments (CTDs, Argo floats, Drifters etc.). + +```{tip} +See [here](../../tutorials/working_with_expedition_yaml.md) for more detail on the `expedition.yaml`: what it is, how to edit it, and how to ultimately use it to configure your own expeditions. +``` + +Alternatively, you can view and edit the `expedition.yaml` file using the command: + +``` +virtualship plan EXPEDITION_NAME +``` + +This will launch a planning tool with an intuitive user interface to make changes to the expedition schedule and instrument selection. Changes made in the planning tool will be automatically saved to the `expedition.yaml` file. + +For long and complex expeditions, it is often easier to edit the `expedition.yaml` file directly, but the planning tool can be useful for smaller expeditions, quick checks, or for small edits to the schedule and instrument selection. + +## 4) Run the expedition + +You are now ready to run your example expedition! This stage will simulate the measurements taken by the instruments selected at each waypoint in your expedition schedule, using input data sourced from the [Copernicus Marine Data Store](https://data.marine.copernicus.eu/products). + +You will need to register for Copernicus Marine Service account (see [here](https://data.marine.copernicus.eu/register)), but the data access in VirtualShip will be automated. + +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). + +For the example expedition, you can expect the simulation to take approximately 20 minutes, but this can vary depending on different factors including the machine set-up, system performance, and internet connection. Waiting for simulation is a great time to practice your level of patience. A skill much needed in oceanographic fieldwork ;-) + +Why not browse through previous real-life [blogs and expedition reports](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Sail_the_ship.html#Reporting) in the meantime?! + +## 5) Results + +Upon successfully completing the simulation, results from the expedition will be stored in the `EXPEDITION_NAME/results` directory, written as [Zarr](https://zarr.dev/) files. + +From here you will be able to carry on your analysis. We won't go into this here for the example expedition, but when it comes to your own expeditions, you will be expected to analyse, derive quantities and visualise your results, and to ultimately present your findings. diff --git a/docs/user-guide/teacher-content/index.md b/docs/user-guide/teacher-content/index.md index 9e6c07ef..bdd0f95f 100644 --- a/docs/user-guide/teacher-content/index.md +++ b/docs/user-guide/teacher-content/index.md @@ -34,3 +34,10 @@ UU-ocean-of-future/Tutorial2.ipynb UU-ocean-of-future/CTD_transects.ipynb UU-ocean-of-future/plot_slider.py ``` + +```{nbgallery} +--- +caption: UU Dynamical Oceanography +--- +UU-dyoc/example_expedition.md +``` From a5e04add3527d08a8e7abc91f85e304dfab6a2f9 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Mon, 16 Feb 2026 11:28:37 +0100 Subject: [PATCH 2/3] only new dir if not done so already --- docs/user-guide/teacher-content/UU-dyoc/example_expedition.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md b/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md index a1dd0fe9..28c73f3e 100644 --- a/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md +++ b/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md @@ -10,7 +10,7 @@ This guide assumes you have already logged into and set up (initialised conda) t ## 1) Create a new directory for your VirtualShip expeditions -First, you should navigate to the shared storage directory on the virtual machine (e.g. `cd data/virtualship_storage/`) and create a new directory for your group's VirtualShip expeditions (e.g. `mkdir {group_name}`, replacing `{group_name}` with your actual group name). This is where you will run your expeditions and store the results. +First, you should navigate to the shared storage directory on the virtual machine (e.g. `cd data/virtualship-storage/`). If you have not done so already, please create a new directory for your group's VirtualShip expeditions (e.g. `mkdir {your-group_name}`, replacing `{your-group_name}` with your actual group name). This is where you will run your expeditions and store the results. ## 2) Expedition initialisation From 8b199cfacd059a647d2f798bd116e62861c75516 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Mon, 16 Feb 2026 14:29:22 +0100 Subject: [PATCH 3/3] add tutorial on changing file permissions on SURF --- docs/conf.py | 1 + .../UU-dyoc/file_permissions.md | 31 +++++++++++++++++++ docs/user-guide/teacher-content/index.md | 1 + 3 files changed, 33 insertions(+) create mode 100644 docs/user-guide/teacher-content/UU-dyoc/file_permissions.md diff --git a/docs/conf.py b/docs/conf.py index a630f491..c93f3c5e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -84,6 +84,7 @@ "user-guide/tutorials/surf_research_cloud_setup": "user-guide/_images/freepik_research_vessel.jpg", "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", } sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"} diff --git a/docs/user-guide/teacher-content/UU-dyoc/file_permissions.md b/docs/user-guide/teacher-content/UU-dyoc/file_permissions.md new file mode 100644 index 00000000..9317f4aa --- /dev/null +++ b/docs/user-guide/teacher-content/UU-dyoc/file_permissions.md @@ -0,0 +1,31 @@ +# File Permissions on the SURF RC Virtual Machine + +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 within the shared storage + +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 unit 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/index.md b/docs/user-guide/teacher-content/index.md index bdd0f95f..d6a39eb0 100644 --- a/docs/user-guide/teacher-content/index.md +++ b/docs/user-guide/teacher-content/index.md @@ -40,4 +40,5 @@ UU-ocean-of-future/plot_slider.py caption: UU Dynamical Oceanography --- UU-dyoc/example_expedition.md +UU-dyoc/file_permissions.md ```