---

Project Owner	VirtualShip Team (virtualship@uu.nl)
Development status	Beta

VirtualShip is a command line simulator allowing users to plan and conduct a research expedition in a digital ocean, receiving measurements as if they were coming from actual oceanographic instruments including:

• ADCP (currents)
• CTD (conductivity and temperature + biogeochemical variables)
• XBT (temperature)
• Ship-mounted underwater measurements (salinity and temperature)
• Surface drifters (temperature)
• Argo float deployments (salinity and temperature)

Along the way, users will encounter realistic problems that may occur during an oceanographic expedition, requiring them to make decisions to adapt their plans accordingly. For example, delays due to equipment failures, pre-depature logistical issues or safety drills.

Installation

For a normal installation using Conda do:

conda create -n ship -c conda-forge virtualship
conda activate ship

which creates an environment named ship with the latest version of virtualship. You can replace ship with any name you like.

For a development installation (using Pixi), please follow the instructions detailed in the contributing page.

Usage

💡 Tip

See the Quickstart guide in our documentation for a step-by-step introduction to using VirtualShip.

You can run the VirtualShip via the command line interface (CLI) using the virtualship command. It has three subcommands: init, plan, and run.

$ virtualship --helpUsage: virtualship [OPTIONS] COMMAND [ARGS]...Options: --version Show the version and exit. --help Show this message and exit.Commands: init Initialize a directory for a new expedition, with an... plan Launch UI to help build expedition configuration (YAML) file. run Execute the expedition simulations.

$ virtualship init --helpUsage: virtualship init [OPTIONS] PATH Initialize a directory for a new expedition, with an expedition.yaml file. If --mfp-file is provided, it will generate the expedition.yaml from the MPF file instead.Options: --from-mfp TEXT Partially initialise a project from an exported xlsx or csv file from NIOZ' Marine Facilities Planning tool (specifically the "Export Coordinates > DD" option). User edits are required after initialisation. --help Show this message and exit.

$ virtualship plan --helpUsage: virtualship plan [OPTIONS] PATH Launch UI to help build expedition configuration (YAML) file. Should you encounter any issues with using this tool, please report an issue describing the problem to the VirtualShip issue tracker at: https://github.com/OceanParcels/virtualship/issues"Options: --help Show this message and exit.

$ virtualship run --helpUsage: virtualship run [OPTIONS] PATH Execute the expedition simulations.Options: --from-data TEXT Use pre-downloaded data, saved to disk, for expedition, instead of streaming directly via Copernicus Marine Assumes all data is stored in prescribed directory, and all variables (as listed below) are present. Required variables are: {'phyc', 'o2', 'so', 'uo', 'po4', 'thetao', 'no3', 'vo', 'chl', 'ph', 'nppv'} Assumes that variable names at least contain the standard Copernicus Marine variable name as a substring. Will also take the first file found containing the variable name substring. CAUTION if multiple files contain the same variable name substring. --help Show this message and exit.

For examples of VirtualShip simulation output post-processing, see the tutorials section of our documentation.

Input data

The code is written to work with A-grid ocean data from the Copernicus Marine Service.

Source code

The code for this project is hosted on GitHub.

Contributors

All contributions are welcome! See the contributing page in our documentation to see how to get involved. Image made with contrib.rocks.