Veros, *the versatile ocean simulator*, aims to be the swiss army knife of ocean modeling. It is a full-fledged :abbr:`GCM (general circulation model)` that supports anything between highly idealized configurations and realistic set-ups, targeting students and seasoned researchers alike. Thanks to its seamless interplay with `Bohrium <https://github.com/bh107/bohrium>`_, Veros runs efficiently on your laptop, gaming PC (with experimental GPU support through OpenCL & CUDA), and small cluster. Veros has a clear focus on simplicity, usability, and adaptability - *because the Baroque is over*.
Veros, *the versatile ocean simulator*, aims to be the swiss army knife of ocean modeling. It is a full-fledged :abbr:`GCM (general circulation model)` that supports anything between highly idealized configurations and realistic set-ups. Thanks to its interplay with `Bohrium <https://github.com/bh107/bohrium>`_, Veros runs efficiently on your laptop, gaming PC (with experimental GPU support through OpenCL & CUDA), and small cluster. In short, we want to enable ocean modelling with a clear focus on simplicity, usability, and adaptability.
If you want to learn more about the background and capabilities of Veros, you should check out :doc:`quickstart/introduction`. If you are already convinced, you can jump right into action, and :doc:`learn how to get started <quickstart/get-started>` instead!
...
...
@@ -36,6 +36,14 @@ If you want to learn more about the background and capabilities of Veros, you sh
If you want to report a bug in Veros, have a technical inquiry, or want to ask for a missing feature, please use our `issue tracker <https://github.com/dionhaefner/veros/issues>`_ on GitHub.
If you want to report a bug in Veros, have a technical inquiry, or want to ask for a missing feature, please use our `issue tracker <https://github.com/team-ocean/veros/issues>`_ on GitHub.
In case you have general questions about Veros, please contact `the maintainer <https://github.com/dionhaefner>`_ of the Veros repository.
In case you have general questions about Veros, please contact `the maintainer <https://github.com/team-ocean>`_ of the Veros repository.
A plug-in can be any Python package that accepts a :class:`VerosState <veros.state.VerosState>` object.
The plug-in is then free to modify the model state in any way it pleases.
The only requirement for the plug-in to be usable in Veros setups is that it declares a special object in its top :file:`__init__.py` file:
::
__VEROS_INTERFACE__ = dict(
name='my-plugin',
setup_entrypoint=my_setup_function,
run_entrypoint=my_main_function
)
The functions passed in :obj:`setup_entrypoint` and :obj:`run_entrypoint` are then called by Veros during model set-up and after each time step, respectively, with the model state as the sole argument.
In this case, the setup function does nothing, while the main function sets temperature and salinity forcing to 0 where the surface temperature is smaller than -1.8 degrees (a very crude sea ice model).
Custom settings, variables, and diagnostics
-------------------------------------------
In real-world applications, you probably want to use custom settings, variables, and/or diagnostics in your plug-in.
You can specify those as additional arguments to :obj:`__VEROS_INTERFACE__`:
::
__VEROS_INTERFACE__ = dict(
name='my-plugin',
setup_entrypoint=my_setup_function,
run_entrypoint=my_main_function,
settings=my_settings,
variables=my_variables,
conditional_variables=my_conditional_variables,
diagnostics=[MyDiagnostic]
)
In this case, :obj:`my_settings` is a :class:`dict` mapping the name of the setting to a :class:`Setting <veros.settings.Setting>` object:
::
from collections import OrderedDict # to preserve order
from veros.settings import Setting
my_settings = OrderedDict([
('enable_my_plugin', Setting(False, bool, 'Enable my plugin')),
A plug-in is an optional extension for Veros that you can use to enable additional physics, outputs, or diagnostics.
.. note::
Plug-ins do not necessarily meet the same quality standards as the Veros core, and not all plug-ins are directly affiliated with Veros or the Veros developers. You should carefully check whether a given plug-in fits your needs.
As a first step, install the plug-in you want to use, e.g. :obj:`veros-bgc` via
::
$ pip install veros-bgc
You can then immediately use any custom setups included in the plug-in:
::
$ veros copy-setup bgc_global_4deg
To use a plug-in in a Veros setup, all you need to do is to import it and add it to the :obj:`__veros_plugins__` attribute of your setup class:
::
import veros_bgc
class MySetup(VerosSetup):
__veros_plugins__ = (veros_bgc,)
# - rest of the setup definition -
This step is probably not necessary if you use a setup that was shipped with the plug-in, but in doubt you should double-check that the plug-in is activated properly.
.. seealso::
For more information, refer to the documentation of the plug-in in question. You can find some suggestions in the contents of this section.
3. Install Veros (preferably in a virtual environment) via::
...
...
@@ -209,7 +209,7 @@ We believe that the best way to learn how Veros works is to read its source code
In case you want to add additional output capabilities or compute additional quantities without changing the main solution of the simulation, you should consider :doc:`adding a custom diagnostic </reference/diagnostics>`.
A convenient way to implement your modifications is to create your own fork of Veros on GitHub, and submit a `pull request <https://github.com/dionhaefner/veros/pulls>`_ if you think your modifications could be useful for the Veros community.
A convenient way to implement your modifications is to create your own fork of Veros on GitHub, and submit a `pull request <https://github.com/team-ocean/veros/pulls>`_ if you think your modifications could be useful for the Veros community.
This tutorial walks you through some of the most common challenges that are specific to large, shared architectures like clusters and supercomputers. In case you are still having trouble setting up or running Veros on a large architecture after reading it, you should first contact the administrator of your cluster. Otherwise, you should of course feel free to `open an issue <https://github.com/dionhaefner/veros/issues>`_.
This tutorial walks you through some of the most common challenges that are specific to large, shared architectures like clusters and supercomputers. In case you are still having trouble setting up or running Veros on a large architecture after reading it, you should first contact the administrator of your cluster. Otherwise, you should of course feel free to `open an issue <https://github.com/team-ocean/veros/issues>`_.
