<p align="center">
<img src="doc/_images/veros-logo-400px.png?raw=true">
</p>
<p align="center">
<i>Versatile Ocean Simulation in Pure Python</i>
</p>
<p align="center">
<a href="http://veros.readthedocs.io/?badge=latest">
<img src="https://readthedocs.org/projects/veros/badge/?version=latest" alt="Documentation status">
</a>
<a href="https://github.com/team-ocean/veros/actions/workflows/test-all.yml">
<img src="https://github.com/team-ocean/veros/actions/workflows/test-all.yml/badge.svg" alt="Test status">
</a>
<a href="https://codecov.io/gh/team-ocean/veros">
<img src="https://codecov.io/gh/team-ocean/veros/branch/main/graph/badge.svg" alt="Code Coverage">
</a>
<a href="https://zenodo.org/badge/latestdoi/87419383">
<img src="https://zenodo.org/badge/87419383.svg" alt="DOI">
</a>
</p>
Veros, *the versatile ocean simulator*, aims to be the swiss army knife of ocean modeling. It is a full-fledged primitive equation ocean model that supports anything between idealized toy models and [realistic, high-resolution, global ocean simulations](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2021MS002717). And because Veros is written in pure Python, the days of struggling with complicated model setup workflows, ancient programming environments, and obscure legacy code are finally over.
*In a nutshell, we want to enable high-performance ocean modelling with a clear focus on flexibility and usability.*
Veros supports a NumPy backend for small-scale problems, and a
high-performance [JAX](https://github.com/google/jax) backend
with CPU and GPU support. It is fully parallelized via MPI and supports
distributed execution on any number of nodes, including multi-GPU architectures (see also [our benchmarks](https://veros.readthedocs.io/en/latest/more/benchmarks.html)).
The dynamical core of Veros is based on [pyOM2](https://wiki.cen.uni-hamburg.de/ifm/TO/pyOM2), an ocean model with a Fortran backend and Fortran and Python frontends.
To learn more about Veros, make sure to [visit our documentation](https://veros.readthedocs.io/en/latest/).
#### How about a demonstration?
<p align="center">
<a href="https://vimeo.com/391237951">
<img src="doc/_images/veros-preview.gif?raw=true" alt="0.25×0.25° high-resolution model spin-up">
</a>
</p>
<p align="center">
(0.25×0.25° high-resolution model spin-up, click for better
quality)
</p>
## 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.
Raw data
{
"_id": null,
"home_page": "https://veros.readthedocs.io",
"name": "veros",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "oceanography python parallel numpy multi-core geophysics ocean-model mpi4py jax",
"author": "Dion H\u00e4fner (NBI Copenhagen)",
"author_email": "dion.haefner@nbi.ku.dk",
"download_url": "https://files.pythonhosted.org/packages/06/f0/5f5986f773696a9fa058035047dc8b7da425991c5ec50b56293e6c4824d5/veros-1.5.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<img src=\"doc/_images/veros-logo-400px.png?raw=true\">\n</p>\n\n<p align=\"center\">\n<i>Versatile Ocean Simulation in Pure Python</i>\n</p>\n\n<p align=\"center\">\n <a href=\"http://veros.readthedocs.io/?badge=latest\">\n <img src=\"https://readthedocs.org/projects/veros/badge/?version=latest\" alt=\"Documentation status\">\n </a>\n <a href=\"https://github.com/team-ocean/veros/actions/workflows/test-all.yml\">\n <img src=\"https://github.com/team-ocean/veros/actions/workflows/test-all.yml/badge.svg\" alt=\"Test status\">\n </a>\n <a href=\"https://codecov.io/gh/team-ocean/veros\">\n <img src=\"https://codecov.io/gh/team-ocean/veros/branch/main/graph/badge.svg\" alt=\"Code Coverage\">\n </a>\n <a href=\"https://zenodo.org/badge/latestdoi/87419383\">\n <img src=\"https://zenodo.org/badge/87419383.svg\" alt=\"DOI\">\n </a>\n</p>\n\nVeros, *the versatile ocean simulator*, aims to be the swiss army knife of ocean modeling. It is a full-fledged primitive equation ocean model that supports anything between idealized toy models and [realistic, high-resolution, global ocean simulations](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2021MS002717). And because Veros is written in pure Python, the days of struggling with complicated model setup workflows, ancient programming environments, and obscure legacy code are finally over.\n\n*In a nutshell, we want to enable high-performance ocean modelling with a clear focus on flexibility and usability.*\n\nVeros supports a NumPy backend for small-scale problems, and a\nhigh-performance [JAX](https://github.com/google/jax) backend\nwith CPU and GPU support. It is fully parallelized via MPI and supports\ndistributed execution on any number of nodes, including multi-GPU architectures (see also [our benchmarks](https://veros.readthedocs.io/en/latest/more/benchmarks.html)).\n\nThe dynamical core of Veros is based on [pyOM2](https://wiki.cen.uni-hamburg.de/ifm/TO/pyOM2), an ocean model with a Fortran backend and Fortran and Python frontends.\n\nTo learn more about Veros, make sure to [visit our documentation](https://veros.readthedocs.io/en/latest/).\n\n#### How about a demonstration?\n\n<p align=\"center\">\n <a href=\"https://vimeo.com/391237951\">\n <img src=\"doc/_images/veros-preview.gif?raw=true\" alt=\"0.25\u00d70.25\u00b0 high-resolution model spin-up\">\n </a>\n</p>\n\n<p align=\"center\">\n(0.25\u00d70.25\u00b0 high-resolution model spin-up, click for better\nquality)\n</p>\n\n## Features\n\nVeros provides\n\n- a fully staggered **3-D grid geometry** (*C-grid*)\n- support for both **idealized and realistic configurations** in\n Cartesian or pseudo-spherical coordinates\n- several **friction and advection schemes**\n- isoneutral mixing, eddy-kinetic energy, turbulent kinetic energy,\n and internal wave energy **parameterizations**\n- several **pre-implemented diagnostics** such as energy fluxes,\n variable time averages, and a vertical overturning stream function\n (written to netCDF4 output)\n- **pre-configured idealized and realistic set-ups** that are ready to\n run and easy to adapt\n- **accessibility and extensibility** - thanks to the\n power of Python!\n\n## Veros for the impatient\n\nA minimal example to install and run Veros:\n\n```bash\n$ pip install veros\n$ veros copy-setup acc --to /tmp/acc\n$ veros run /tmp/acc/acc.py\n```\n\nFor more detailed installation instructions, have a look at [our\ndocumentation](https://veros.readthedocs.io).\n\n## Basic usage\n\nTo run Veros, you need to set up a model --- i.e., specify which settings\nand model domain you want to use. This is done by subclassing the\n`VerosSetup` base class in a *setup script* that is written in Python. You\nshould use the `veros copy-setup` command to copy one into your current\nfolder. A good place to start is the\n[ACC model](https://github.com/team-ocean/veros/blob/main/veros/setups/acc/acc.py):\n\n```bash\n$ veros copy-setup acc\n```\n\nAfter setting up your model, all you need to do is call the `setup` and\n`run` methods on your setup class. The pre-implemented setups can all be\nexecuted via `veros run`:\n\n```bash\n$ veros run acc.py\n```\n\nFor more information on using Veros, have a look at [our\ndocumentation](http://veros.readthedocs.io).\n\n## Contributing\n\nContributions to Veros are always welcome, no matter if you spotted an\ninaccuracy in [the documentation](https://veros.readthedocs.io), wrote a\nnew setup, fixed a bug, or even extended Veros\\' core mechanics. There\nare 2 ways to contribute:\n\n1. If you want to report a bug or request a missing feature, please\n [open an issue](https://github.com/team-ocean/veros/issues). If you\n are reporting a bug, make sure to include all relevant information\n for reproducing it (ideally through a *minimal* code sample).\n2. If you want to fix the issue yourself, or wrote an extension for\n Veros - great! You are welcome to submit your code for review by\n committing it to a repository and opening a [pull\n request](https://github.com/team-ocean/veros/pulls). However,\n before you do so, please check [the contribution\n guide](http://veros.readthedocs.io/quickstart/get-started.html#enhancing-veros)\n for some tips on testing and benchmarking, and to make sure that\n your modifications adhere with our style policies. Most importantly,\n please ensure that you follow the [PEP8\n guidelines](https://www.python.org/dev/peps/pep-0008/), use\n *meaningful* variable names, and document your code using\n [Google-style\n docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).\n\n## How to cite\n\nIf you use Veros in scientific work, please consider citing [the following publication](https://gmd.copernicus.org/articles/11/3299/2018/):\n\n```bibtex\n@article{hafner_veros_2018,\n\ttitle = {Veros v0.1 \u2013 a fast and versatile ocean simulator in pure {Python}},\n\tvolume = {11},\n\tissn = {1991-959X},\n\turl = {https://gmd.copernicus.org/articles/11/3299/2018/},\n\tdoi = {10.5194/gmd-11-3299-2018},\n\tnumber = {8},\n\tjournal = {Geoscientific Model Development},\n\tauthor = {H\u00e4fner, Dion and Jacobsen, Ren\u00e9 L\u00f8we and Eden, Carsten and Kristensen, Mads R. B. and Jochum, Markus and Nuterman, Roman and Vinter, Brian},\n\tmonth = aug,\n\tyear = {2018},\n\tpages = {3299--3312},\n}\n```\n\nOr have a look at [our documentation](https://veros.readthedocs.io/en/latest/more/publications.html)\nfor more publications involving Veros.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The versatile ocean simulator, in pure Python, powered by JAX.",
"version": "1.5.1",
"project_urls": {
"Homepage": "https://veros.readthedocs.io"
},
"split_keywords": [
"oceanography",
"python",
"parallel",
"numpy",
"multi-core",
"geophysics",
"ocean-model",
"mpi4py",
"jax"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "06f05f5986f773696a9fa058035047dc8b7da425991c5ec50b56293e6c4824d5",
"md5": "8beb7816439a6afc57222bf5534a1108",
"sha256": "67cb1b8917b16c3df8fb0574c08b10be813546df9d9e6ec3475e864da26ec6c1"
},
"downloads": -1,
"filename": "veros-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "8beb7816439a6afc57222bf5534a1108",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 329667,
"upload_time": "2023-10-11T08:44:24",
"upload_time_iso_8601": "2023-10-11T08:44:24.775660Z",
"url": "https://files.pythonhosted.org/packages/06/f0/5f5986f773696a9fa058035047dc8b7da425991c5ec50b56293e6c4824d5/veros-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-11 08:44:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "veros"
}
JSON