Creating a Design Document

[VeckoTheGecko]

In the issues and discussions I've been seeing a lot of talk about adding different features to Virtual Ship. Whether that be graphical user interface features, scientific features, analysis of outputs etc. I really appreciate the ideas, and the enthusiasm here (full stop). Saying that, I think that I've been on somewhat of a different page to others in the team about the scope of Virtual Ship.

I think it would be best if we create a design document that defines the avenues of development for Virtual Ship so that the everyone is on the same page - and so that we can have focussed discussions in the issue tracker.

Questions:

• What is the essence of Virtual Ship?
  • Is it:
    • A command line simulator that takes in configuration files? Or, is it
    • currently a command line simulator taking configuration files, but would be better to move to a graphical user interface (for some or all parts)?
• What is "in scope" for Virtual Ship?
  • Mission planning? (no, the Marine Facilities Planning tool is for that, but still useful to formally document)
  • Simulation itself:
    • What sort of features would we accept for the simulation itself? What is the spirit of the features here?
  • Post analysis of outputs?
    • if yes, what sort of analysis? Derived variables? Visualisation? Statistical analysis?
• What is "out of scope" for Virtual Ship?
  • important to also have as a section, as it documents what we've considered and rejected

This document can be as rigid or as flexible as we want it to be. I hope though that it can be used to limit the scope of Virtual Ship so that we can provide a cohesive tool (while pointing to other tools for features not included in Virtual Ship - e.g., MFP for planning, xarray for post-analysis).

This email was somewhat inspired by the hackathon I went to last week. The design document for the project I was working on ("xdggs") allowed everyone to be on the same page about the goals of the project - and I think something similar here would be really beneficial for Virtual Ship (though not necessarily as rigid, as the xdggs project has very specific goals).

Keen to hear thoughts about this.

If you're keen @ammedd , perhaps it would be best to meet 1 on 1 to create a draft (that way we have the scientific and engineering perspectives) that we can then bring to the rest of the team for discussion?

[VeckoTheGecko]

cc @iuryt @erikvansebille @j-atkins

[erikvansebille]

Thanks for starting this discussion, @VeckoTheGecko. I full agree that we need a good design document (including a list of 'non-goals'!); but what makes it especially complicated in the case of the Virtual Ship is that the platform is actually even more than the code hosted here. There's also the VR component, the lessons (including e.g the science communication assignment) and other aspects not related to education.

So yes, we do need to sit down with everyone involved to discuss what the scope of the tooling here is in relation to the bigger Virtual Ship platform

[VeckoTheGecko]

Done in #194

[iuryt]

I just realized I missed this discussion. Below is my take on this matter. I would love to know what @erikvansebille thinks about this:

What is the essence of Virtual Ship? Is it:
A command line simulator that takes in configuration files? Or, is it
currently a command line simulator taking configuration files, but would be better to move to a graphical user interface (for some or all parts)?

I see two main types of users for this package.
For more advanced users, especially those running repeated simulations across different mission plans, I think it’s important that VirtualShip remains usable as a Python package, so it can be integrated directly into scripts and workflows.

However, many users (particularly students or those doing one-off mission planning) would likely prefer a GUI. In that case, a web-based interface would be ideal. To ensure flexibility, ease of use, and a well-designed interface that works well across platforms.

What is "in scope" for Virtual Ship?
Mission planning? (no, the Marine Facilities Planning tool is for that, but still useful to formally document)

I see a clear distinction between what the Marine Facilities Planning (MFP) tool offers and what VirtualShip could provide. As far as I know, the MFP tool doesn't account for spatial and temporal distributions of ocean properties.

My vision for VirtualShip is that it becomes a platform where users can test different mission plans and evaluate which one is most effective in answering specific scientific questions. So even if VirtualShip doesn’t handle logistical planning, it plays a crucial role in science-focused planning. How should we manage this integration to take into account the advantages of each tool?

Simulation itself:
What sort of features would we accept for the simulation itself? What is the spirit of the features here?

For me, anything that supports realistic cruise planning and simulation should be in scope. This includes simulation of various onboard instruments, autonomous vehicles, and potentially user-defined instruments. Allowing users to design and simulate their own instruments could greatly enhance flexibility and educational value.

Post analysis of outputs?
if yes, what sort of analysis? Derived variables? Visualisation? Statistical analysis?
What is "out of scope" for Virtual Ship?
important to also have as a section, as it documents what we've considered and rejected

Curious to hear what others think, but from my side: in terms of post-analysis, I think we should focus on visualizing the campaign itself. That includes the mission schedule, the final sampling pattern, instrument trajectories that are influenced by ocean currents, the locations of stations, and the ship's track.

I’m especially excited to work on this visualization aspect. I’ve had some recent deadlines for other projects, but I’m planning to return to it this month.

As for what’s out of scope, I’d suggest we avoid trying to build general-purpose tools for processing or visualizing oceanographic data. That’s best left to the user, who can choose their preferred tools for analysis.

[VeckoTheGecko]

Hi @iuryt , thanks for your response and for thinking along here! We've came up with the document outlined in #194 - which I think is very compatible in terms of design decisions for the usecases that you mention above. At the moment we're focussing on reducing the technical debt within virtualship, to tidy things up from a code architecture POV to help with maintainability and extending it down the line. From there we will take stock, but the design document was mainly to focus on the fundamental design so that the code can be organised around it. This is something that @j-atkins is working on, and that I'm helping with.

As for what’s out of scope, I’d suggest we avoid trying to build general-purpose tools for processing or visualizing oceanographic data. That’s best left to the user, who can choose their preferred tools for analysis.

I agree. This is especially since in a classroom setting we would be looking to promote the use of the preferred tools of the domain (e.g., Python, or other more specific tools)

Curious to hear what others think, but from my side: in terms of post-analysis, I think we should focus on visualizing the campaign itself. That includes the mission schedule, the final sampling pattern, instrument trajectories that are influenced by ocean currents, the locations of stations, and the ship's track.

I’m especially excited to work on this visualization aspect. I’ve had some recent deadlines for other projects, but I’m planning to return to it this month.

I'm not sure if I understand correctly, but wouldn't the ship track already be visualised via MFP? (I guess not the final final trajectory, since the user might modify the yaml, but close enough?) I think that this is quite a significant featureset with several added dependencies. Feel free to raise an issue in the issue tracker if you have a solid idea (what features?, what dependencies?, are the deps optional?, value add, etc.) for what you would like this to look like :) , then we can see whether it is in scope (though my impression so far has been that we're focusing quite a bit on simulation, and been avoiding visualisation tooling).