virtualship 0.3.6

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 --help
Usage: 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 --help
Usage: 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 --help
Usage: 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 --help
Usage: 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.