Skip to content

Commit 843b66e

Browse files
VeckoTheGeckoVeckoTheGecko
committed
Add design document
1 parent 56424ed commit 843b66e

3 files changed

Lines changed: 140 additions & 0 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@
33
- Closes #xxxx
44
- [ ] Tests added
55
- [ ] Re-ran README.md help commands if the CLI has changed
6+
- [ ] PR adheres with the current [design document](./design-doc.md) (or design document is updated)

‎design-doc.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Virtualship Design Document
2+
3+
> Document created as a result of [this discussion topic](https://github.com/OceanParcels/virtualship/discussions/187).
4+
5+
## Essence of Virtualship
6+
7+
Virtualship interpolates hydrodynamical fields the way instruments would. Users can combine these observations into an expedition ("cruise"). Users can also deploy individual instruments in the flowfield, either as part of an expedition or independently, to compare against actual observations.
8+
9+
### For Researchers
10+
11+
- Define or configure instruments to make **deployments** of virtual instruments in the flow field (passed to parcels).
12+
13+
### For Students or Researchers Planning an Expedition
14+
15+
A layer on top allows them to:
16+
17+
- Run an **expedition** that chains together **deployments** at different **stations**.
18+
19+
---
20+
21+
## Key Concepts
22+
23+
### Measurement
24+
25+
- A spacetime interpolation of a hydrodynamic or biogeochemical field.
26+
- A set of measurements forms a timeseries output (serialised to disk as a zarr output).
27+
- In the case of students, this would be serialized with artificial errors to simulate real-world data and also be serialized in the original binary format of the instrument.
28+
29+
### Instrument
30+
31+
- A device that takes measurements. Two types:
32+
- **Underway-instruments**: Measure continuously during the expedition (e.g., Thermosalinograph, shipboard ADCP, and (to be developed) meteorology).
33+
- Conducted for the entirety of the expedition.
34+
- **Overboard-instruments**: Deployed at specific times (e.g., CTD, drifters, Argo, XBT, and (to be developed) gliders).
35+
- Deployed at stations during the expedition.
36+
37+
### Deployment
38+
39+
- A complete set of measurements for an overboard-instrument (from deployment to retrieval).
40+
- Each deployment is executed independently of the ship's movement.
41+
- Components:
42+
- An instrument.
43+
- A station.
44+
- A start time.
45+
46+
### Ship Track
47+
48+
- A set of line segments between stations where underway-instruments take measurements.
49+
- **Planned ship track**: Includes arrival and departure times at stations.
50+
- **Realised ship track**: Actual path taken.
51+
52+
### Waypoint
53+
54+
- A horizontal location with no associated time.
55+
- **Planned waypoint** - has no associated time
56+
- **Realised waypoint** - has an associated time (since the timing has been calculated from the ship speed).
57+
58+
### Station
59+
60+
- A waypoint where multiple deployments can occur. The ship does not drift horizontally while at a station.
61+
- Features:
62+
- One horizontal location.
63+
- An associated time for deployment start.
64+
- A configured time to stay at the location.
65+
- Ships travel between stations at maximum speed; if arriving early, they wait at the station.
66+
67+
### Port
68+
69+
- A waypoint where a ship track starts or ends, but no deployments are possible.
70+
71+
---
72+
73+
pseudocode
74+
75+
```
76+
for each station
77+
 for each overboard-instrument
78+
do deployment
79+
 while track to next station
80+
  for each underway-instrument
81+
   do measurement
82+
```
83+
84+
---
85+
86+
### Problems
87+
88+
Simulated problems that are encountered during an expedition.
89+
90+
# Technical Decisions
91+
92+
## Running the expedition
93+
94+
Two possible approaches:
95+
96+
1. Run a planning phase and deploy instruments after
97+
98+
- Steps:
99+
- The planned ship track is known, validated[^1], and then iterated through (encountering problems along the way).
100+
- Users adjust their plans based on the problems encountered.
101+
- Once completed, the ship track is finalised (i.e., is _realized_) and then all the deployments are made and measurements are taken.
102+
- Pros:
103+
- Easier to implement and test (distinct phases in the running of the code).
104+
- Instruments can be run in non-chronological order (i.e., as different particlesets with different fieldsets) - simplifying code and output.
105+
- Cons:
106+
- Problems become limited (can only make problems based on the planned ship track. Not possible to encounter problems based on the conditions of the Parcels simulation (e.g., currents)).
107+
- Students cannot make decisions based on the data they have "collected" up to the point that they have to make a decision[^2] .
108+
109+
2. Encounter problems during the expedition
110+
111+
- Steps:
112+
- The planned ship track is known, validated[^1], and then the expedition is run.
113+
- Expedition is paused when a problem is encountered, and users can adjust their plans.
114+
- Pros:
115+
- Problems can be flexible and based on the Parcels simulation (e.g., currents).
116+
- Cons:
117+
- More complex to implement and test (need to run the code in a single phase).
118+
- Everything is a single particleset and fieldset, making kernels more complex, requiring splitting of the outputs into separate zarr files.
119+
- Students can't make decisions based on the data they have "collected".
120+
121+
We have decided for approach (1) for the timebeing. Down the line we may want to explore approach (2).
122+
123+
## Configuration Files
124+
125+
- **ship_config.yaml** and **schedule.yaml** can be updated to match the current structure.
126+
- These can be consolidated into a single **expedition.yaml** file.
127+
128+
# FAQ
129+
130+
- How does this "Essence of Virtualship" above fit for biological oceanography? Do they also have a concept of 'instruments'?
131+
- For now let's focus on field data that is provided through Copernicus marine (down the line we might support other data providers).
132+
133+
---
134+
135+
[^1]: Validate -> Make sure that ship track isn't on land, make sure that the ship track isn't unrealistic for the ship speed.
136+
137+
[^2]: If we want to support this, there will be added complexity: we will need to show the users the binary files, but the zarr files behind the scenes will still need to be cached so that the simulation can continue from where it left off.

‎docs/contributing/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
All contributions are welcome no matter your background or experience! We collaborate on GitHub using issues to track bugs, features, and discuss future development. We use pull requests to collaborate on changes to the codebase (and modifications to the tutorials).
44

5+
We have a design document providing a conceptual overview of virtualship. This document can be found [here](https://github.com/OceanParcels/virtualship/blob/main/design-doc.md). Suggested features will be worked on in a way that is consistent with the design document - but if you have suggestions on how we can improve the design of virtualship (e.g., to enable other features) please let us know!
6+
57
## For developers
68

79
### Development installation

0 commit comments

Comments
 (0)