3. Input generation

There are a number of helpers designed to ease the creation of input fields.

3.1. Grid object

The grid object contains the axes for variables on tracer points, both velocity points, and vorticity points. This allows users to create their inputs in a resolution independent manner by specifying functions based on physical location, rather than grid point number. Changing resolution therefore becomes a trivial exercise that requires changing only the nx, ny, dx, and dy parameters.

class aronnax.Grid(nx, ny, layers, dx, dy, x0=0, y0=0)

Make a grid object containing all of the axes.

Parameters:

• nx (int) – Number of grid points in the x direction
• ny (int) – Number of grid points in the y direction
• layers (int) – Number of active layers
• dx (float) – Grid size in x direction in metres
• dy (float) – Grid size in y direction in metres
• x0 (float) – x value at lower left corner of domain
• y0 (float) – y value at lower left corner of domain

The initialisation call returns an object containing each of the input parameters as well as the following arrays:

• x: x locations of the tracer points
• y: y locations of the tracer points
• xp1: x locations of the u velocity points and vorticity points
• yp1: y locations of the v velocity points and vorticity points

3.2. Inputs

3.2.1. Pre-existing Fortran files

Fortran unformatted files (often called Fortran binary files) can be used as input. To do this, they should be placed in the ‘input’ folder, and the name of the file given either in the aronnax.conf file, or passed as a keyword argument in the call to aronnax.driver.simulate.

The fields need to be the correct shape and size. If they aren’t the error messages may be difficult to comprehend or nonexistent depending on whether the field is too big, too small, or the wrong shape. The parameter DumpWind can be helpful for ensuring that the wind stress has been set correctly.

3.2.2. Generator functions

The use of input generator functions allows the model to be passed user defined functions describing the inputs. Aronnax will evaluate the user defined functions or constants to create the input fields, and save these fields to the ‘input’ folder in the format required by the Fortran core.

The generator functions can be called in two ways:

• either directly from the aronnax.conf file, using the syntax :generator_name:arg1,arg2,…,argn. In this case the arguments must be numerical (generating very simple layerwise constant value fields).
• or they can be included in the call to aronnax.driver.simulate() using the syntax field_name=[arg1, arg2, …, argn]. In this case the arguments may be either numerical or functions and must be passed as a list. That is, they must be wrapped in square brackets [], even if that list has only one element. Aronnax will check that the length of the list equals the number of layers the field is expected to have and will throw an error if they are not equal.

Regardless of the method used, each argument is evaluated for a single layer. That is, arg1 is used to create the field for the upper layer.

For use in aronnax.driver.simulate call

When using generator functions to create the inputs through the call to aronnax.driver.simulate() it is possible to use Python functions to create the fields. This is an extremely powerful method for creating arbitrary forcings and initial conditions.

If a function is passed to the generator functions it must depend on:

• X and Y, created from a np.meshgrid call with the appropriate axis, if it is for a 2D field; or
• nTimeSteps and dt if it is for a time series.

All other values used within the function must be set in a namespace that the function has access to, or be hard-coded.

For use in aronnax.conf file

These generic generator functions can be used in the aronnax.conf file to create simple inputs or initial conditions using the syntax :generator_name:arg1,arg2,…,argn. The arguments must be numeric.

For specific grid locations

These generator functions are passed one numeric argument per layer.

aronnax.tracer_point_variable(grid, field_layers, *funcs)

Input generator for a variable at the tracer location of the grid. If passed a function, then that function can depend only on X and Y.

aronnax.u_point_variable(grid, field_layers, *funcs)

Input generator for a variable at the u location of the grid. If passed a function, then that function can depend only on X and Y.

aronnax.v_point_variable(grid, field_layers, *funcs)

Input generator for a variable at the v location of the grid. If passed a function, then that function can depend only on X and Y.

aronnax.time_series_variable(nTimeSteps, dt, func)

Input generator for a time series variable. If passed a function, then that function can depend on the number of timesteps, nTimeSteps, and the timestep, dt.

Coriolis fields

The \(f\)-plane generator functions are passed one numeric argument, the value for \(f\), and the \(\beta\)-plane functions are passed two numeric arguments.

aronnax.f_plane_f_u(grid, field_layers, coeff)

Define an f-plane approximation to the Coriolis force (u location).

aronnax.f_plane_f_v(grid, field_layers, coeff)

Define an f-plane approximation to the Coriolis force (v location).

aronnax.beta_plane_f_u(grid, field_layers, f0, beta)

Define a beta-plane approximation to the Coriolis force (u location).

aronnax.beta_plane_f_v(grid, field_layers, f0, beta)

Define a beta-plane approximation to the Coriolis force (v location).

Domain shape

This generator function is passed without arguments in the aronnax.conf file.

aronnax.rectangular_pool(grid, field_layers)

The wet mask file for a maximal rectangular pool.