Skip to content

Commit c11f0aa

Browse files
VeckoTheGeckoVeckoTheGecko
authored
Add design document (#194)
* Add design document * Review feedback * Review Feedback * Define instrument * Review feedback * Remove duplicate subheading
1 parent 56424ed commit c11f0aa

File tree

3 files changed

+143
-0
lines changed

3 files changed

+143
-0
lines changed

‎.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: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
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 and biogeographical fields the way instruments would. **Student Users** can combine these observations into an expedition (also known as a "cruise"). **Research Users** can also deploy individual instruments in these field, 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 could be serialized with artificial errors to simulate real-world data and also be serialized in the original (binary or csv) 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 and continues recording when ship is stationary at a **station**.
34+
- **Overboard-instruments**: Deployed at specific times (e.g., CTD, drifters, Argo, XBT).
35+
- Deployed at stations during the expedition.
36+
- Components:
37+
- A Parcels fieldset (which relates to a Copernicus Marine dataset)
38+
- A Parcels kernel
39+
- (optional) A configuration object controlling any important parameters.
40+
41+
### Deployment
42+
43+
- A complete set of measurements for an overboard-instrument (from deployment to retrieval or end-of-life).
44+
- Each deployment is executed independently of the ship's movement.
45+
- Components:
46+
- An instrument.
47+
- A station.
48+
- A start time.
49+
50+
### Ship Track
51+
52+
- A set of line segments between stations where underway-instruments take measurements.
53+
- **Planned ship track**: Includes arrival and departure times at stations.
54+
- **Realised ship track**: Actual path taken.
55+
56+
### Waypoint
57+
58+
- A horizontal location with no associated time.
59+
- **Planned waypoint** - has no associated time
60+
- **Realised waypoint** - has an associated time (since the timing has been calculated from the ship speed).
61+
62+
### Station
63+
64+
- A waypoint where multiple deployments can occur. The ship does not drift horizontally while at a station.
65+
- Features:
66+
- One waypoint.
67+
- An associated time for deployment start.
68+
- Ships travel between stations at maximum speed; if arriving early, they wait at the station.
69+
70+
### Port
71+
72+
- A waypoint where a ship track starts or ends, but no deployments are possible.
73+
74+
---
75+
76+
pseudocode
77+
78+
```
79+
for each station
80+
 for each overboard-instrument
81+
do deployment
82+
 while track to next station
83+
  for each underway-instrument
84+
   do measurement
85+
```
86+
87+
---
88+
89+
### Problems
90+
91+
Simulated problems that are encountered during an expedition.
92+
93+
# Technical Decisions
94+
95+
## Running the expedition
96+
97+
Two possible approaches:
98+
99+
1. Run a planning phase and deploy instruments after
100+
101+
- Steps:
102+
- The planned ship track is known, verified[^1], and then iterated through (encountering problems along the way).
103+
- Users adjust their plans based on the problems encountered.
104+
- Once completed, the ship track is finalised (i.e., is _realized_) and then all the deployments are made and measurements are taken.
105+
- Pros:
106+
- Easier to implement and test (distinct phases in the running of the code).
107+
- Instruments can be run in non-chronological order (i.e., as different particlesets with different fieldsets) - simplifying code and output.
108+
- Cons:
109+
- 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)).
110+
- Students cannot make decisions based on the data they have "collected" up to the point that they have to make a decision[^2] .
111+
112+
2. Encounter problems during the expedition
113+
114+
- Steps:
115+
- The planned ship track is known, verified[^1], and then the expedition is run.
116+
- Expedition is paused when a problem is encountered, and users can adjust their plans.
117+
- Pros:
118+
- Problems can be flexible and based on the Parcels simulation (e.g., currents).
119+
- Cons:
120+
- More complex to implement and test (need to run the code in a single phase).
121+
- Everything is a single particleset and fieldset, making kernels more complex, requiring splitting of the outputs into separate zarr files.
122+
- Students can't make decisions based on the data they have "collected".
123+
124+
We have decided for approach (1) for the timebeing. Down the line we may want to explore approach (2).
125+
126+
## Configuration Files
127+
128+
- **ship_config.yaml** and **schedule.yaml** can be updated to match the current structure.
129+
- These can be consolidated into a single **expedition.yaml** file.
130+
131+
# FAQ
132+
133+
- How does this "Essence of VirtualShip" above fit for biological oceanography? Do they also have a concept of 'instruments'?
134+
- For now let's focus on field data that is provided through the Copernicus Marine Service (down the line we might support other data providers).
135+
136+
---
137+
138+
[^1]: Verify -> Make sure that ship track isn't on land, make sure that the ship track isn't unrealistic for the ship speed.
139+
140+
[^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)