Getting started


Using pip


You should only install Veros via pip if you want to get going as quickly as possible, and do not plan to access or modify the Veros source code. The recommended way to install Veros is through Conda (see below).

If you already have Python installed, the quickest way to get a working Veros installation is to run

$ pip install veros

and, optionally:

$ pip install bohrium

to use Veros with Bohrium (Linux and OSX only).

Without Conda (Linux / OSX)

  1. Ensure you have a working Python 3.x installation.

  2. Clone our repository:

    $ git clone -b v0.2.2

    (or any other version of Veros), or use

    $ pip download veros

    to download a tarball of the latest version (needs to be unpacked).

  3. Install Veros (preferably in a virtual environment) via

    $ pip install -e ./veros

    You might have to add the --user flag to pip install if you are using your system interpreter. The -e flag ensures that changes to the code are immediately reflected without reinstalling.

  4. Optionally, install Bohrium via

    $ pip install bohrium

Setting up a model

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 Veros setup base class in a setup script that is written in Python. You should have a look at the pre-implemented model setups in the repository’s setup folder, or use the veros copy-setup command to copy one into your current folder. A good place to start is the ACC model:

$ veros copy-setup acc

By working through the existing models, you should quickly be able to figure out how to write your own simulation. Just keep in mind this general advice:

  • You can (and should) use any (external) Python tools you want in your model setup. Before implementing a certain functionality, you should check whether it is already provided by a common library. Especially the SciPy module family provides countless implementations of common scientific functions (and SciPy is installed along with Veros).

  • If you decorate your methods with @veros_method, the variable np inside that function will point to the currently used backend (i.e., NumPy or Bohrium). Thus, if you want your setup to be able to dynamically switch between backends, you should write your methods like this:

    from veros import Veros, veros_method
    class MyVerosSetup(Veros):
        def my_function(self):
            arr = np.array([1,2,3,4]) # "np" uses either NumPy or Bohrium
  • If you are curious about the general procedure in which a model is set up and ran, you should read the source code of veros.VerosSetup (especially the setup() and run() methods). This is also the best way to find out about the order in which methods and routines are called.

  • Out of all functions that need to be implemented by your subclass of veros.VerosSetup, the only one that is called in every time step is set_forcing() (at the beginning of each iteration). This implies that, to achieve optimal performance, you should consider moving calculations that are constant in time to other functions.

If you want to learn more about setting up advanced configurations, you should check out our tutorial that walks you through the creation of a realistic configuration with an idealized Atlantic.

Running Veros

After adapting your setup script, you are ready to run your first simulation. It is advisable to include something like:
def run(*args, **kwargs):
    simulation = MyVerosSetup()

if __name__ == "__main__":

in your setup file, so you can run it as a script:

$ python

However, you are not required to do so, and you are welcome to write include your simulation class into other Python files and call it dynamically or interactively (e.g. in an IPython session).

All Veros setups decorated with accept additional options via the command line when called as a script or as arguments to their __init__() function when called from another Python module. You can check the available commands through

$ python --help

Reading Veros output

All output is handled by the available diagnostics. The most basic diagnostic, snapshot, writes some model variables to netCDF files in regular intervals (and puts them into your current working directory).

NetCDF is a binary format that is widely adopted in the geophysical modeling community. There are various packages for reading, visualizing and processing netCDF files (such as ncview and ferret), and bindings for many programming languages (such as C, Fortran, MATLAB, and Python).

In fact, after installing Veros, you will already have installed the netCDF bindings for Python, so reading data from an output file and plotting it is as easy as:

import matplotlib.pyplot as plt
import h5netcdf

with h5netcdf.File("", "r") as datafile:
    # read variable "u" and save it to a NumPy array
    u = datafile.variables["u"][...]

# plot surface velocity at the last time step included in the file
plt.imshow(u[-1, -1, ...])

For further reference refer to the netcdf4-python documentation.

Using Bohrium


While Bohrium yields significant speed-ups for large to very large setups, the overhead introduced by Bohrium often leads to (sometimes considerably) slower execution for problems below a certain threshold size (see also Which backend should I choose to run my model (NumPy / Bohrium)?). You are thus advised to test carefully whether Bohrium is beneficial in your particular use case.

For large simulations, it is often beneficial to use the Bohrium backend for computations. When using Bohrium, all number crunching will make full use of your available architecture, i.e., computations are executed in parallel on all of your CPU cores, or even GPU when using BH_STACK=opencl or BH_STACK=cuda. You may switch between NumPy and Bohrium with a simple command line switch:

$ python -b bohrium

or, when running inside another Python module: (must be done before initializing you setup):

from veros import runtime_settings as rs

rs.backend = "bohrium"

Re-starting from a previous run

Restart data (in HDF5 format) is written at the end of each simulation or after a regular time interval if the setting restart_frequency is set to a finite value. To use this restart file as initial conditions for another simulation, you will have to point restart_input_filename of the new simulation to the corresponding restart file. This can (as all settings) also be given via command line:

$ python -s restart_input_filename /path/to/restart_file.h5

Running Veros on multiple processes via MPI


This assumes that you are familiar with running applications through MPI, and is most useful on large architectures like a compute cluster. For smaller architectures, it is usually easier to stick to Bohrium.

Running Veros through MPI requires some addititonal dependencies:

  • A recent MPI implementation, such as OpenMPI or MPICH

  • mpi4py that is linked to the correct MPI library

  • A parallel-enabled version of the HDF5 library

  • h5py built against this parallel version of HDF5

  • For optimal performance, PETSc and petsc4py, linked to the rest of the stack

After you have installed everything, you can start Veros on multiple processes like so::

$ python -n 2 2

Or, by explicitly using mpirun (might be required on some architectures):

$ mpirun -n 4 python -n 2 2

In this case, Veros would run on 4 processes, each process computing one-quarter of the domain. The arguments of the -n flag specify the number of chunks in x and y-direction, respectively.

You can combine MPI and Bohrium like so::

$ OMP_NUM_THREADS=2 mpirun -n 2 python -n 2 1 -b bohrium

This starts 2 independent processes, each being parallelized by Bohrium using 2 threads (hybrid run).

See also

For more information, see Running Veros on a cluster.

Enhancing Veros

Veros was written with extensibility in mind. If you already know some Python and have worked with NumPy, you are pretty much ready to write your own extension. The model code is located in the veros subfolder, while all of the numerical routines are located in veros/core.

We believe that the best way to learn how Veros works is to read its source code. Starting from the Veros base class, you should be able to work your way through the flow of the program, and figure out where to add your modifications. If you installed Veros through pip -e or develop, all changes you make will immediately be reflected when running the 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 adding a custom diagnostic.

A convenient way to implement your modifications is to create your own fork of Veros on GitHub, and submit a pull request if you think your modifications could be useful for the Veros community.

See also

More information is available in our developer guide.