Structure of a CVMix module

###Sequence of calls (init, calc, finalize)

Note for future Mike (from present Mike): finalize routine for methods that allocate memory (background mixing) as well as those using cvmix_data_type

At a minimum, a CVMix module must support at least three public subroutines to conduct the following procedure: initialize, calculate and finalize. Multiple entries into the CVMix module calculate are permitted, but initialize and finalize should each be a single subroutine.

###Passing/setting parameters

During initialization (cvmix_init_MODULE), every parameter associated with that module (and stored in a cvmix_MODULE_params_type) has a documented default value that can be overridden with an optional argument. Once a module has been initialized, individual variables can be changed by calling cvmix_put_MODULE. Parameters can also be set explicitly:

cvmix_MODULE_param%parameter_name = value

There is a private cvmix_MODULE_params_type variable in each module that is used by default, but all routines can take an optional parameter datatype as an argument if you want to use different parameters for the same type of mixing in two regimes. More details on the parameters contained in each module can be found in [MNL note: where will this info be???]

###Encapsulation of variables in a column

Within CVMix, time-dependent / column-specific variables that are commonly used for input / output in vertical mixing parameterizations are contained within a single derived data structure (cvmix_data_type) defined in the cvmix_kinds_and_types module. As discussed below, CVMix can be used without this datatype (in fact, we only recommend using this structure for small problems). Variables can be set either by calling cvmix_put or explicitly stating

cvmix_vars%variable_name = value

Note that all non-scalar variables are defined as pointers - they can either point directly to the target variable, or they can be treated as though they are allocatable. More details on the variables contained in this structure can be found in [MNL note: where will this info be???]

###Low level calls vs CVMix data structures

The routine that computes the diffusivity coefficients in each module (cvmix_MODULE_coeffs) has two interfaces - the “low level” interface accepts intent(in) and intent(out) variables individually (for example, cvmix_tidal_coeffs_low requires an array for the temperature diffusivity output as well as buoyancy frequency, column level interface heights, column level center heights, and column ocean depth) while the “wrapped” interface only requires a CVMix data derived type (described above). Note that the wrapped interface simply unpacks the required variables from cvmix_data_type and then calls the low-level routine -- this design allows us to provide an easy-to-use wrapped interface without writing any duplicate code. The low level interface is recommended for best performance, but the wrapped routine may be preferable for small problems where performance is not a concern.