4. Running Aronnax

To run a simulation with Aronnax one needs to have a Python session active in the folder for the simulation. This folder should contain a file, aronnax.conf that contains the configuration choices for the simulation. Some, or all, of these choices may be overridden by arguments passed to the simulate function, but it is likely simpler to specify many of the choices in a configuration file.

Note

Despite requiring MPI Aronnax is currently stuck on one processor (MPI is required for the Hypre library). We aspire to have Aronnax running in parallel, but it hasn’t happened yet.

As described above, it is possible to define functions that can be passed to aronnax.driver.simulate and used to create input or forcing fields. The test suite, found in the ‘test’ folder uses this functionality to create the zonal wind stress for the \(\beta\)-plane gyre tests. The relevant code is shown below:

def wind(_, Y):
    return 0.05 * (1 - np.cos(2*np.pi * Y/np.max(grid.y)))

with working_directory(p.join(self_path, "beta_plane_gyre_red_grav")):
    drv.simulate(zonalWindFile=[wind],
                 nx=10, ny=10, exe="aronnax_test", dx=xlen/10, dy=ylen/10)

Warning

Parameters cannot be set to 0 or 1 in the call to drv.simulate because the Python wrapper gets confused between numerical and logical variables, as described in https://github.com/edoddridge/aronnax/issues/132

4.1. Executables

Aronnax includes multiple targets for the Makefile. These produce executables intended either for testing or production runs. The different options for exe are discussed below. For a comparison on the execution speed of these executables see Benchmarking.

  • aronnax_core
    • Uses the internal Fortran code and aggressive compiler optimisation. This is the best executable to use for reduced gravity (\(n+1/2\) layer) simulations. It may also be used for \(n\) layer simulations but is considerably slower than aronnax_external_solver since it does not use the external Hypre library for the pressure solve.
  • aronnax_test
    • Uses the internal Fortran code and no compiler optimisations. This is the best executable to use for assessing code coverage when running tests. The Fortran error messages might be helpful.
  • aronnax_prof
    • Executable intended solely for profiling the Fortran core. Unlikely to be of general use.
  • aronnax_external_solver_test
    • Uses the external Hypre library to solve the matrix inversion in the \(n\) layer mode. Uses no optimisations for the internal Fortran code and is intended for assessing code coverage when running tests.
  • aronnax_external_solver
    • Uses the external Hypre library and aggressive compiler optimisations. This is the fastest executable to use in \(n\) layer mode. It can also be used in \(n+1/2\) layer mode, but there is no advantage over aronnax_core.

4.2. Parameters

Parameters can be passed to the model in two ways. Either they can be included in a file called aronnax.conf in the working directory, or they can be passed as keyword arguments to aronnax.driver.simulate(). The main directory of the repository includes an example aronnax.conf file.

Note

Aronnax takes a deliberately strict approach towards specifying parameter choices. The model contains very few default values, except in situations where a default of zero can sensibly be applied. As such, you will need to specify your parameter choices, either through the configuration file, or the function call. However, parameters that are not required, for example, bottom drag in n+1/2 layer mode, need not be set.

The example file is reproduced here with comments describing the parameters and their units. All possible parameters are included, but they are not all assigned values. After modifying this file for your simulation, any unassigned parameters should be deleted.

# Aronnax configuration file. Change the values, but not the names.

#------------------------------------------------------------------------------
# au is the lateral friction coefficient in m^2 / s
# ah is thickness diffusivity in m^2 / s
# ar is linear drag between layers in 1/s
# dt is time step in seconds
# slip is free-slip (=0), no-slip (=1), or partial slip (something in between)
# niter0: the timestep at which the simulation begins. If not zero, then there 
#   must be checkpoint files in the 'checkpoints' directory.
# nTimeSteps: number of timesteps before stopping
# dumpFreq: time between snapshot outputs in seconds
# avFreq: time between averaged output in seconds
# checkpiontFreq: time between checkpoints in seconds 
#   (these are used for restarting simulations)
# diagFreq: time between dumping layerwise diagnostics of the simulation. These
#   are mean, min, max, and std of h, u, and v in each layer.
# hmin: minimum layer thickness allowed by model (for stability) in metres
# maxits: maximum iterations for the pressure solver algorithm. Should probably
#   be at least max(nx,ny), and possibly nx*ny
# eps: convergence tolerance for pressure solver. Algorithm stops when error is 
#   less than eps*initial_error
# freesurfFac: 1. = linear implicit free surface, 0. = rigid lid.
# botDrag is the linear bottom friction in 1/s
# thickness_error is the  discrepancy between the summed layer thicknesses and 
#   the depth above which the model emits a warning. 1e-2 is a 1% discrepancy.
# debug_level controls the level of output produced by the model. When set to
#   zero, or not specified (it defaults to zero), the model outputs h, u, and v
#   at the frequency controlled by dumpFreq and avFreq. Specifying larger
#   integer values results in progressively more output more frequently. See
#   the documentation for details.

[numerics]
au = 500.
ah = 0.0
ar = 0.0
dt = 600.
slip = 0.0
niter0 = 0
nTimeSteps = 502
dumpFreq = 1.2e5
avFreq = 1.2e5
checkpointFreq = 1.2e5
diagFreq = 6e3
hmin = 100
maxits = 1000
eps = 1e-5
freesurfFac = 0.
botDrag = 1e-6
thickness_error = 1e-2
debug_level = 0
#------------------------------------------------------------------------------

# RedGrav selects whether to use n+1/2 layer physics (RedGrav=yes), or n-layer 
#   physics with an ocean floor (RedGrav=no)
# depthFile defines the depth of the ocean bottom below the sea surface in metres.
# hmean is a list of initial thicknesses for the layers in metres. Each value is 
#   separated by a comma. This input was a useful short cut for specifying 
#   initial conditions with constant layer thicknesses, but has been superseded 
#   and may be removed in the future.
# H0 is the depth of the ocean basin and is only required in n-layer mode. This 
#   input was a useful short cut for specifying a flat bottomed ocean, but has 
#   been superseded and may be removed in the future.

[model]
RedGrav = no
depthFile
hmean = 400.,1600.
H0 = 2000.
#------------------------------------------------------------------------------

# these variables set the number of processors to use in each direction. 
#   Currently the model only runs on one processor, so nProcX and nProcY must 
#   be set to 1

[pressure_solver]
nProcX = 1
nProcY = 1
#------------------------------------------------------------------------------

# g_vec is the reduced gravity at interfaces in m/s^2. g_vec must have as many 
#   entries as there are layers. The values are given by the delta_rho*g/rho_0. 
#   In n-layer mode the first entry applies to the surface, i.e. the top of the 
#   upper layer. In n+1/2 layer mode the first entry applies to the bottom of 
#   the upper layer.
# rho0 is the reference density in kg/m^3, as required by the Boussinesq assumption.

[physics]
g_vec = 9.8, 0.01
rho0 = 1035.
#------------------------------------------------------------------------------

# nx is the number of grid points in the x direction
# ny is the number of grid points in the y direction
# layers is the number of active layers
# dx is the x grid spacing in metres
# dy is the y grid spacing in metres
# fUfile defines the Coriolis parameter on the u grid points in 1/s
# fVfile defines the Coriolis parameter on the v grid points in 1/s
# wetMaskFile defines the computational domain - which grid points are ocean, 
#   with wetmask=1, and which are land, with wetmask=0. The wetmask is defined 
#   at the centre of each grid cell, the same location as thickness.

[grid]
nx = 10
ny = 10
layers = 2
dx = 2e4
dy = 2e4
fUfile = :beta_plane_f_u:1e-5,2e-11
fVfile = :beta_plane_f_v:1e-5,2e-11
wetMaskFile = :rectangular_pool:
#------------------------------------------------------------------------------

# These files define the values towards which the model variables are relaxed 
#   (in metres or m/s), and the timescale for the relaxation, in 1/s.
[sponge]
spongeHTimeScaleFile
spongeUTimeScaleFile
spongeVTimeScaleFile
spongeHFile
spongeUfile
spongeVfile

#------------------------------------------------------------------------------

# These files define the initial values used in the simulation. If no values are
#   defined for the velocities (in m/s) or the free surface elevation (in m), 
#   they will be initialised with zeros. Layer thickness (in m) must be initialised, 
#   either by passing a file, or using the generator functions.

[initial_conditions]
initUfile
initVfile
initHfile
initEtaFile

#------------------------------------------------------------------------------

# The wind files define the momentum forcing in N/m^2 or m/s
# wind_mag_time_series_file defines the constant factor by which the wind is 
#   multiplied by at each timestep.
# DumpWind defines whether the model outputs the wind field when it outputs other 
#   variables (at the rate controlled by DumpFreq).
# RelativeWind selects whether the wind forcing is given in 
#   N/m^2 (RelativeWind = no), or
#   m/s   (RelativeWind = yes)
# Cd is the quadratic drag coefficient used if RelativeWind = yes

[external_forcing]
zonalWindFile = 'wind_x.bin'
meridionalWindFile = 'wind_y.bin'
wind_mag_time_series_file
DumpWind = no
RelativeWind = no
Cd = 0.

#------------------------------------------------------------------------------

Warning

The configuration file shown above includes all of the possible input parameters and fields since it forms part of the documentation. IT WILL NOT WORK AS IS. To use it in an actual simulation the file will need to be modified either by giving values to the parameters that are currently unspecified, or deleting them from the file. If you wish to see a configuration file that corresponds to a successful simulation, look in any of the test, benchmark, or reproduction directories.

4.2.1. debug_level

This parameter determines whether the model produces additional outputs. It should be set to an integer value greater than or equal to zero. The different values have the following effects:

  • 0: no additional outputs. Output frequency controlled by DumpFreq and AvFreq
  • 1: output tendencies at frequency given by DumpFreq
  • 2: output tendencies and convergence diagnostics from the linear solve at frequency given by DumpFreq (not implemented)
  • 3: output convergence diagnostics and tendencies before and after applying some or all of sponges, barotropic correction, winds, and boundary conditions at frequency controlled by DumpFreq (not implemented)
  • 4: dump all of the above fields every time step (mostly implemented)
  • 5: dump everything every time step including the two initial RK4 steps (not implemented)

4.2.2. niter0

This parameter allows a simulation to be restarted from the given timestep. It requires that the appropriate files are in the ‘checkpoints’ directory. All parameters, except for the number of grid points in the domain, may be altered when restarting a simulation. This is intended for breaking long simulations into shorter, more manageable chunks, and for running perturbation experiments.

4.2.3. wetMaskFile

The wetmask defines which grid points within the computational domain contain fluid. The wetmask is defined on the tracer points, and a value of 1 defines fluid, while a value of 0 defines land. The domain is doubly periodic in x and y by default. To produce a closed domain the wetmaks should be set to 0 along the edges of the domain. To close the domain it is sufficient to place a strip of land along either the northern or southern boundary and either the western or eastern boundary. You may find it conceptually easier to close both edges.

4.2.4. RelativeWind

If this is false, then the wind input file is given in N m–2. If true, then the wind input file is in m s–1 and a quadratic drag law is used to accelerate the fluid with Cd as the quadratic drag coefficient.