Versatile Ocean Simulation in Pure Python
(0.25×0.25° high-resolution model spin-up, click for better quality)
## Features Veros provides - a fully staggered **3-D grid geometry** (*C-grid*) - support for both **idealized and realistic configurations** in Cartesian or pseudo-spherical coordinates - several **friction and advection schemes** - isoneutral mixing, eddy-kinetic energy, turbulent kinetic energy, and internal wave energy **parameterizations** - several **pre-implemented diagnostics** such as energy fluxes, variable time averages, and a vertical overturning stream function (written to netCDF4 output) - **pre-configured idealized and realistic set-ups** that are ready to run and easy to adapt - **accessibility and extensibility** - thanks to the power of Python! ## Veros for the impatient A minimal example to install and run Veros: ```bash $ pip install veros $ veros copy-setup acc --to /tmp/acc $ veros run /tmp/acc/acc.py ``` For more detailed installation instructions, have a look at [our documentation](https://veros.readthedocs.io). ## Basic usage To run Veros, you need to set up a model --- i.e., specify which settings and model domain you want to use. This is done by subclassing the `VerosSetup` base class in a *setup script* that is written in Python. You should use the `veros copy-setup` command to copy one into your current folder. A good place to start is the [ACC model](https://github.com/team-ocean/veros/blob/main/veros/setups/acc/acc.py): ```bash $ veros copy-setup acc ``` After setting up your model, all you need to do is call the `setup` and `run` methods on your setup class. The pre-implemented setups can all be executed via `veros run`: ```bash $ veros run acc.py ``` For more information on using Veros, have a look at [our documentation](http://veros.readthedocs.io). ## Contributing Contributions to Veros are always welcome, no matter if you spotted an inaccuracy in [the documentation](https://veros.readthedocs.io), wrote a new setup, fixed a bug, or even extended Veros\' core mechanics. There are 2 ways to contribute: 1. If you want to report a bug or request a missing feature, please [open an issue](https://github.com/team-ocean/veros/issues). If you are reporting a bug, make sure to include all relevant information for reproducing it (ideally through a *minimal* code sample). 2. If you want to fix the issue yourself, or wrote an extension for Veros - great! You are welcome to submit your code for review by committing it to a repository and opening a [pull request](https://github.com/team-ocean/veros/pulls). However, before you do so, please check [the contribution guide](http://veros.readthedocs.io/quickstart/get-started.html#enhancing-veros) for some tips on testing and benchmarking, and to make sure that your modifications adhere with our style policies. Most importantly, please ensure that you follow the [PEP8 guidelines](https://www.python.org/dev/peps/pep-0008/), use *meaningful* variable names, and document your code using [Google-style docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). ## How to cite If you use Veros in scientific work, please consider citing [the following publication](https://gmd.copernicus.org/articles/11/3299/2018/): ```bibtex @article{hafner_veros_2018, title = {Veros v0.1 – a fast and versatile ocean simulator in pure {Python}}, volume = {11}, issn = {1991-959X}, url = {https://gmd.copernicus.org/articles/11/3299/2018/}, doi = {10.5194/gmd-11-3299-2018}, number = {8}, journal = {Geoscientific Model Development}, author = {Häfner, Dion and Jacobsen, René Løwe and Eden, Carsten and Kristensen, Mads R. B. and Jochum, Markus and Nuterman, Roman and Vinter, Brian}, month = aug, year = {2018}, pages = {3299--3312}, } ``` Or have a look at [our documentation](https://veros.readthedocs.io/en/latest/more/publications.html) for more publications involving Veros.