Merge branch 'main' into teacher-content-permissions

Author: j-atkins

docs/user-guide/teacher-content/UU-dyoc/example_expedition.md

@@ -5,20 +5,20 @@ In this guide we will conduct an example virtual expedition. This expedition is
 ---
 
 ```{important}
-This guide assumes you have already logged into and set up (initialised conda) the SURF virtual environment.
+This guide assumes you have already logged into and set up (initialised conda) the SURF virtual environment. If not, please follow the instructions in the [SURF virtual environment guide](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/surf_research_cloud_setup.html) to do so.
 ```
 
 ## 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/`). 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.
+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 GROUP{your-group_letter}`, replacing `{your-group_letter}` with the letter of 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:
+You should now navigate to your group's directory (i.e. `cd data/virtualship_storage/GROUP{your-group_letter}/`). Then run the following command in the terminal:
 
 ```
 virtualship init EXPEDITION_NAME
@@ -72,4 +72,4 @@ Why not browse through previous real-life [blogs and expedition reports](https:/
 
 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.
+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, compute derived quantities and visualise your results, and to ultimately present your findings.

docs/user-guide/tutorials/working_with_expedition_yaml.md

@@ -78,6 +78,10 @@ This section contains a list of `waypoints` that define the expedition's route.
 Full list of instruments supported for deployment at waypoints (case-sensitive): `CTD`, `CTD_BGC`, `DRIFTER`, `ARGO_FLOAT`, `XBT` (or `null`).
 ```
 
+```{tip}
+You can do multiple `DRIFTER` deployments at the same waypoint by adding multiple `DRIFTER` entries in the list (on separate lines). Note, this is not the case for other instruments, e.g. `CTD`, which can only be deployed once at a given waypoint.
+```
+
 - **Location (`location`)**: The geographical coordinates (latitude and longitude) of the waypoint. These must be in decimal degrees (DD) format and within valid ranges: latitude between -90 and 90, longitude between -180 and 180.
 
 - **Time (`time`)**: The scheduled time for reaching the waypoint, specifically in YYYY-MM-DD HH:MM:SS format.

src/virtualship/cli/_run.py

@@ -83,7 +83,8 @@ def _run(
     expedition = _get_expedition(expedition_dir)
 
     # unique id to determine if an expedition has 'changed' since last run (to avoid re-selecting problems when user makes tweaks to schedule to deal with problems encountered)
-    expedition_id = _unique_id(expedition, expedition_dir)
+    cache_dir = expedition_dir.joinpath(CACHE)
+    expedition_id = _unique_id(expedition, cache_dir)
 
     # dedicated problems directory for this expedition
     problems_dir = expedition_dir.joinpath(
@@ -234,6 +235,10 @@ def _run(
     if os.path.exists(expedition_dir.joinpath(CHECKPOINT)):
         os.remove(expedition_dir.joinpath(CHECKPOINT))
 
+    # delete cache dir if when --difficulty-level is 'easy' (no useful information to cache in this case, and can interfere with re-runs)
+    if difficulty_level == "easy" and os.path.exists(cache_dir):
+        shutil.rmtree(cache_dir)
+
     print("\n------------- END -------------\n")
 
     # end timing
@@ -242,7 +247,7 @@ def _run(
     print(f"[TIMER] Expedition completed in {elapsed / 60.0:.2f} minutes.")
 
 
-def _unique_id(expedition: Expedition, expedition_dir: Path) -> str:
+def _unique_id(expedition: Expedition, cache_dir: Path) -> str:
     """
     Return a unique id for the expedition (marked by datetime), which can be used to determine whether the expedition has 'changed' since the last run.
 
@@ -252,7 +257,6 @@ def _unique_id(expedition: Expedition, expedition_dir: Path) -> str:
     new_id = datetime.now().strftime("%Y%m%d%H%M%S")
     previous_id = None
 
-    cache_dir = expedition_dir.joinpath(CACHE)
     if not cache_dir.exists():
         cache_dir.mkdir()
     id_path = cache_dir.joinpath(EXPEDITION_IDENTIFIER)

src/virtualship/utils.py

@@ -569,7 +569,7 @@ def _find_files_in_timerange(
     return [fname for _, fname in files_with_dates]
 
 
-def _random_noise(scale: float = 0.01, limit: float = 0.03) -> float:
+def _random_noise(scale: float = 0.05, limit: float = 0.1) -> float:
     """Generate a small random noise value for drifter seeding locations."""
     value = np.random.normal(loc=0.0, scale=scale)
     return np.clip(value, -limit, limit)  # ensure noise is within limits

tests/cli/test_run.py

@@ -33,6 +33,8 @@ def execute(self, measurements, out_path):
 
 def test_run(tmp_path, monkeypatch):
     """Testing as if using pre-downloaded, local data."""
+    difficulty_level = "easy"
+
     expedition_dir = tmp_path / "expedition_dir"
     expedition_dir.mkdir()
     (expedition_dir / EXPEDITION).write_text(get_example_expedition())
@@ -54,7 +56,7 @@ def test_run(tmp_path, monkeypatch):
     fake_data_dir.mkdir()
 
     _run(
-        expedition_dir, difficulty_level="easy", from_data=fake_data_dir
+        expedition_dir, difficulty_level=difficulty_level, from_data=fake_data_dir
     )  # problems turned off here
 
     results_dir = expedition_dir / "results"
@@ -64,3 +66,8 @@ def test_run(tmp_path, monkeypatch):
     assert cost_file.exists()
     content = cost_file.read_text()
     assert "cost:" in content
+
+    # check cache dir is deleted at end of expedition when difficulty-level is easy
+    if difficulty_level == "easy":
+        cache_dir = expedition_dir / "cache"
+        assert not cache_dir.exists()

tests/instruments/test_drifter.py

@@ -39,7 +39,7 @@ def test_simulate_drifters(tmpdir) -> None:
     drifters = [
         Drifter(
             spacetime=Spacetime(
-                location=Location(latitude=0.05, longitude=0.05),
+                location=Location(latitude=0.5, longitude=0.5),
                 time=base_time + datetime.timedelta(days=0),
             ),
             depth=0.0,