Classes and Configuration ¶

This page describes the classes that are implemented in SOCA. It explains in broad terms what they are responsible for, how they are implemented, the configuration options that are available for controlling their behavior.

Table of Contents

Classes and Configuration

Geometry ¶

The Geometry class is responsible for creating and storing the MOM6 grid structure. The MOM6 geometry object includes the grid specifcation, generated by calling MOM_domains_init() that lives within the MOM6 model. In practice, MOM_domains_init() is only called once using the soca_gridgen.x application which then saves the geometry object to disk for use by the subsequent applications.

A complete configuration yaml file for the geometry is given as follows:

geometry:
  geom_grid_file: soca_gridspec.nc        # file name containing the geometry specification for soca
  save_local_domain: true                 # save the local fms grid for each pe's, useful for debugging
  full_init: true                         # call `MOM_domains_init` for a full initialization if true
  mom6_input_nml: ./inputnml/input.nml    # location of the fms input.nml namelist
  fields metadata: ./fields_metadata.yml  # list of soca metadata describing the fields

State / Increment ¶

The State and Increment classes in SOCA have a fair amount of overlap between them. The constructors are largely the same and they share a number of methods, such as read and write and computing of norms. In order to simplify the code SOCA implements a fortran soca_fields class in soca/src/soca/Fields/soca_fields_mod.F90 that both State and Increment make use of.

State ¶

State objects are defined by a few keys in a yaml file. All of the options available to instantiate a state are given in the following table

state key	Description
`read_from_file`	0 : set the states to 0 1, 3 : read from files
`basename`	base path to `ocn_filename`, `ice_filename`, `sfc_filename`, and `wav_filename`
`ocn_filename`	MOM6 file name
`ice_filename`	name of file containing the sea ice fields (optional)
`sfc_filename`	name of the file containing the surface fields (optional)
`wav_filename`	name of the file containing significant wave height (optional)
`date`	ISO8601-formatted date
`state variables`	`[cicen, hicen, socn, tocn, ssh, hocn, uocn, vocn]`

where each of the state variables elements is defined inside the fields metadata file ( soca/test/Data/fields_metadata.yml). This file should not need to be modified unless the user want to create new field types for use by SCOA. The metadata file specifies the following for each state variable:

Field metadata key	Description
`name`	Internal name used by soca code and config files
`grid`	`h`, `u`, or `v` (Default: `h`)
`masked`	use land mask if true (Default: true)
`levels`	`1` or `full_ocn` (Default: `1`)
`getval_name`	variable name expected by `GetValues` (Default: <name>)
`getval_name_surface`	`GetValues` variable name for 2D surface of 3D field (Default: <unused>)
`io_file`	The restart file domain `ocn`, `sfc`, or `ice` (Default: <unused>)
`io_name`	The variable name used in the restart IO (Default: <unused>)
`property`	physical property of the variable `positive_definite` (Default: <unused>)

for example, the following snippet of yaml configuration

state:
  read_from_file: 1
  basename: ./INPUT/
  ocn_filename: MOM.res.nc
  ice_filename: cice.res.nc
  sfc_filename: sfc.res.nc
  wav_filename: wav.res.nc
  date: 2018-04-15T00:00:00Z
  state variables: [cicen, hicen, socn, tocn, ssh, hocn, uocn, vocn, swh]

will instantiate a State object valid at 2018-04-15T00:00:00Z by reading the ocean variables [socn, tocn, ssh, hocn, uocn, vocn] from ./INPUT/MOM.res.nc, the sea ice variable [cicen, hicen] from ./INPUT/cice.res.nc and significant wave height from ./INPUT/wav.res.nc. Since the State’s read and write method in SOCA are implemented using FMS, the provided files for the ocean, sea ice, surface, and wave will have to be in an FMS compatible format.

Increment ¶

The Increment class defines the control variables and implements the linear algebra methods necessary to solve the data assimilation problem. In a similar way to the State, they are instantiated through the use of configuration yaml files. For example, the yaml snippet

analysis variables: [ socn, tocn, ssh, hocn]

will create an Increment object with salinity (socn), potential temperature (tocn) and sea surface height (ssh). The field hocn represents the layer thickness and is currently necessary to instantiate an Increment, eventhough it is not currently used.

GetValues and LinearGetValues ¶

The GetValues and LinearGetValues methods are responsible for interpolating the fields to the observation locations set by the observation operators. There are currently no configurable parameters for these two classes.

Model ¶

The Model class is where SOCA interacts with the MOM6 model physics to advance a state forward in time. There are currently two implementations of the advance step, one that uses MOM6’s time-stepping in-core and is implemented in a similar way to the MOM6 solo driver, and another one that reads previously generated backgrounds in lieu of time-stepping. The choice to interact with the model advance in-core or through files depends on the application being run. For example, there are clear benefits running the model advance in-core for a multiple outer loop variational data assimilation system or when simulating observations over a specific time window. However, there is little benefits to including the model for a 3D applications that only make use of one single background per data assimilation windows.

Instantiation of Model objects is controlled through the use of a factory. The yaml code snippet below illustrates how to instantiate a model object that will run the time stepping from MOM6 in-core. This Model name is called SOCA:

model:
  name: SOCA
  tstep: PT1H
  advance_mom6: 1
  model variables: [socn, tocn, uocn, vocn, ssh, hocn,
                    mld, layer_depth]

model key	Description
`name`	`SOCA` - in-core use of MOM6 model advance `PseudoModel` - model states read in through file IO
`tstep`	the time stepping length for which OOPS interacts with MOM6
`advance_mom6`	only used for debugging purpose. `0`: skip the model advance `1`: advance MOM6
`model variables`	list of variables that will interact with the model

The other model factory available to use within SOCA is the generic PseudoModel from OOPS. This model reads background files that were previously generated by a MOM6 forecast application. The yaml code snippet below illustrates how to instantiate a PseudoModel valid for a 6 hour forecast:

model:
  name: PseudoModel
  tstep: PT1H
  state variables: &model_vars [socn, tocn, uocn, vocn, ssh, hocn,
                                mld, layer_depth]
  states:
  - date: 2018-04-15T01:00:00Z
    basename: ./Data/
    ocn_filename: ocn.mom6.fc.2018-04-15T00:00:00Z.PT1H.nc
    read_from_file: 1
  - date: 2018-04-15T02:00:00Z
    basename: ./Data/
    ocn_filename: ocn.mom6.fc.2018-04-15T00:00:00Z.PT2H.nc
    read_from_file: 1
  - date: 2018-04-15T03:00:00Z
    basename: ./Data/
    ocn_filename: ocn.mom6.fc.2018-04-15T00:00:00Z.PT3H.nc
    read_from_file: 1
  - date: 2018-04-15T04:00:00Z
    basename: ./Data/
    ocn_filename: ocn.mom6.fc.2018-04-15T00:00:00Z.PT4H.nc
    read_from_file: 1
  - date: 2018-04-15T05:00:00Z
    basename: ./Data/
    ocn_filename: ocn.mom6.fc.2018-04-15T00:00:00Z.PT5H.nc
    read_from_file: 1
  - date: 2018-04-15T06:00:00Z
    basename: ./Data/
    ocn_filename: ocn.mom6.fc.2018-04-15T00:00:00Z.PT6H.nc
    read_from_file: 1

Linear and nonlinear Variable Changes ¶

Ana2Model ¶

The analysis to model variable change is responsible for rotating u/v pairs from the model grid to north, as well as performing a log transformation on certain variables.

Configuration	Description
`rotate`	vector rotation from logical grid to meridional/zonal basis. Variables are listed in pairs between the `u` and `v` parameters.
`log`	Variables to undergo a log transform

- variable change: Ana2Model
  rotate:
    u: [uocn, taux]
    v: [vocn, tauy]
  log:
    var: [chl]
  output variables: *soca_vars

Balance ¶

The balance linear variable change is applied to the unbalanced variables and defines the cross correlation between ocean and sea ice variables.

Configuration	Description
`dsdtmax`	ignore the dS/dT Jacobian for values greater than `dsdtmax`
`dsdzmin`	ignore the dS/dT Jacobian if the vertical salinity gradient is less than `dsdzmin`
`dtdzmin`	ignore the dS/dT Jacobian if the vertical temperature gradient is less than `dtdzmin`
`nlayers`	set the dynamic height based Jacobian to 0 for the top `nlayers` levels
`dcdt`	read the sea ice concentration Jacobian from file specified in the yaml configuration

variable changes:
- variable change: BalanceSOCA
  dsdtmax: 0.1
  dsdzmin: 3.0e-6
  dtdzmin: 1.0e-6
  nlayers: 2
  dcdt:
    filename: ./Data/kmask.nc
    name: dcdt
  input variables: *soca_vars
  output variables: *soca_vars

BkgErr ¶

This linear variable change reads the diagonal of the background error covariance matrix from a file.

Configuration	Description
`t_min` `t_max`	sets the minimum and maximum value of the temperature background error to `t_min` `t_max`
`s_min` `s_max`	sets the minimum and maximum value of the unbalanced salinity background error to `s_min` `s_max`
`ssh_min` `ssh_max`	sets the minimum and maximum value of the unbalanced ssh background error to `ssh_min` `ssh_max`
`cicen_min` `cicen_max`	sets the minimum and maximum value of the unbalanced ice concentration background error to `cicen_min` `cicen_max`
`hicen_min` `hicen_max`	sets the minimum and maximum value of the ice thickness background error to `hicen_min` `hicen_max`
`chl_min` `chl_max`	sets the minimum and maximum value of the chlorophyll background error to `chl_min` `chl_max`
`biop_min` `biop_max`	sets the minimum and maximum value of the chlorophyll background error to `biop_min` `biop_max`
`swh_min` `swh_max`	sets the minimum and maximum value of the significant wave height background error to `biop_min` `biop_max`

variable changes:
- variable change: BkgErrSOCA
  read_from_file: 3
  basename: ./
  ocn_filename: ocn.bkgerror.nc
  ice_filename: ice.bkgerror.nc
  wav_filename: wav.bkgerror.nc
  date: *bkg_date
  t_min: 0.0
  t_max: 2.5
  s_min: 0.0
  s_max: 0.2
  ssh_min: 0.0 # std ssh=0 => ssh balance applied as
  ssh_max: 0.0 #              strong constraint
  cicen_min: 0.1
  cicen_max: 0.5
  hicen_min: 10.0
  hicen_max: 100.0
  chl_min: 0.003
  chl_max: 10.0
  biop_min: 0.0
  biop_max: 1.0e-6
  swh_min: 0.1
  swh_max: 1.0
  #fixed_std_sst: 0.005 # OK to create pretty increments
  #fixed_std_sss: 0.001 # but that option should not exist!
  input variables: *soca_vars
  output variables: *soca_vars

BkgErrFilt ¶

This linear variable change is used in conjunction with a background error covariance matrix variable change. It returns the identity for varaibles that are not salinity, potential temperature or sea surface height.

Configuration	Description
`ocean_depth_min`	returns 0 where the ocean depth is less than `ocean_depth_min`
`rescale_bkgerr`	rescaling factor
`efold_z`	exponential e-folding scale

Output:¶

0 for salinity, potential temperature and sea surface height if the ocean is too shallow (less than ocean_depth_min).
rescale_bkgerr * exp(-z/efold_z) for salinity, potential temperature and sea surface height where z is the positive ocean depth.
1 for variables other than salinity, potential temperature and sea surface height.

variable changes:
- variable change: BkgErrFilt
  ocean_depth_min: 0    # [m]
  rescale_bkgerr: 1.0
  efold_z: 2500.0       # [m]
  input variables: *soca_vars
  output variables: *soca_vars

BkgErrGodas ¶

This variable change derives the background error from the vertical gradient of the background potential temperature, with a horizontally varying surface minimum for temperature that is read in from a file.

Configuration	Description
`t_min` / `t_max`	set minimum and maximum values for the potential temperature background error
`t_dz`	rescaling of the potential temperature background error
`t_efold`	e-folding scale for sea surface temperature background error
`s_min` / `s_max`	set minimum and maximum values for the unbalanced salinity background error
`ssh_min` / `ssh_max`	set minimum and maximum values for the unbalanced sea surface height background error
`ssh_phi_ex`	set ssh background error to `ssh_max` where \|latitude\| >= `ssh_phi_ex`
`cicen_min` / `cicen_max`	set minimum and maximum values for the unbalanced sea ice concentration background error
`hicen_min` / `hicen_max`	set minimum and maximum values for the sea ice thickness background error

variable changes:
- variable change: BkgErrGODAS
  t_min: 0.1
  t_max: 2.0
  t_dz:  20.0
  t_efold: 500.0
  s_min: 0.0
  s_max: 0.25
  ssh_min: 0.0   # value at EQ
  ssh_max: 0.1   # value in Extratropics
  ssh_phi_ex: 20 # lat of transition from extratropics
  cicen_min: 0.1
  cicen_max: 0.5
  hicen_min: 10.0
  hicen_max: 100.0
  input variables: *soca_vars
  output variables: *soca_vars

HorizFilt ¶

This linear variable change applies a 9-point stencil horizontal smoother to a field.

Configuration	Description
`niter`	number of iterations
`filter variables`	apply the filter to `filter variables`

variable changes:
- variable change: HorizFiltSOCA
  niter: 2
  filter variables: *soca_vars
  input variables: *soca_vars
  output variables: *soca_vars

Model2GeoVaLs ¶

This class is responsible for converting State and Increment fields into the fields required by GetValues and LinearGetValues.

The linear version is a simple identity operator, returning either a full 3D field, or the top level if a surface field is required.

The non-linear version, in addition to providing the same identity operators, returns several derrived values:

distance_from_coast - distance to the closest land grid box
sea_area_fraction - 1.0 where the mask indicates ocean, otherwise 0.0
mesoscale_representation_error - dx/R
surface_temperature_where_sea - sst in Kelvin
sea_floor_depth_below_sea_surface - vertical summation of the ocean layer thicknesses.

VertConv ¶

This linear variable change applys a vertical convolution to a field.

Configuration	Description
`Lz_min`	minimum vertical decorrelation scale [m]
`Lz_mld`	if not 0, Use the mixed layer depth to calculate the vertical decorrelation scale within the mixed layer
`Lz_mld_max`	limit the application of the mixed layer depth deocrrelation scale to depth less than `Lz_mld_max`
`scale_layer_thick`	minimum decorrelation scale as a multiple of the layer thickness

variable changes:
- variable change: VertConvSOCA
  Lz_min: 2.0
  Lz_mld: 1
  Lz_mld_max: 500.0
  scale_layer_thick: 1.5
  input variables: *soca_vars
  output variables: *soca_vars