MODULE model_mod (POP)

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: model_mod.html 11626 2017-05-11 17:27:50Z nancy@ucar.edu $

NAMELIST / INTERFACES / FILES / REFERENCES / ERRORS / PLANS / PRIVATE COMPONENTS / TERMS OF USE

Overview

The Parallel Ocean Program (POP) may be used with the Data Assimilation Research Testbed (DART). Both main variants - LANL POP and CESM1.0 POP2 have been tested. We are assimilating salinity and temperature observations from either the World Ocean Database (2005) or (2009).

The following POP variables are extracted from the POP netCDF restart files and are conveyed to DART: SALT_CUR, TEMP_CUR, UVEL_CUR, VVEL_CUR, and PSURF_CUR. These variables are then adjusted to be consistent with real observations and stuffed back into the same netCDF restart files. Since DART is an ensemble algorithm, there are multiple restart files for a single restart time: one for each ensemble member. Creating the initial ensemble of ocean states is an area of active research. At present, it may be sufficient to use a climatological ensemble; e.g., using the restarts for '1 January 00Z' from 50 consecutive years. Experience has shown that having a paired (unique) atmospheric forcing maintains the ensemble spread better than simply forcing all the ocean ensemble members with one single atmospheric state.

DART reads the grid information for POP from the files specified in POP's &grid_nml. When DART is responsible for starting/stopping POP, the information is conveyed through POP's &time_manager_nml.

CESM1.0 POP2

was tested and run in production on NCAR's bluefire computer from IBM. This implementation is a significant departure from the DART 'business as usual' model in that DART is not responsible for advancing the model - in this case, ALL of CESM! Instead, the CESM Interactive Ensemble facility is used to manage the ensemble and the Flux Coupler is responsible for stopping POP at the times required to perform an assimilation. DART simply runs 'end-to-end' at every assimilation time, while CESM runs continuously. This is a complete role-reversal from the normal DART operation but was relatively simple to implement because CESM had infrastructure to exploit.

Several modifications to CESM CASEROOT scripts will be required and will be documented more later in this document. The DART/models/POP/shell_scripts/assimilate.csh script is inserted into the CESM run script. The Flux Coupler stops POP every midnight and all the observations within +/- 12 hours are assimilated. The observation sequence files have been parsed into 'daylong' chunks and have names derived from the date to facilitate manipulation in the UNIX shell.

The DART components were built with the following settings:

      MPIFC = mpxlf95_r
      MPILD = mpxlf95_r
      FC = xlf90_r
      LD = xlf90_r
      INCS = -I/usr/local/lib64/r4i4 -I/usr/local/include
      LIBS = -L/usr/local/lib64/r4i4 -lnetcdf
      FFLAGS = -qsuffix=f=f90:cpp=F90 -q64 -b64 -qarch=auto -qmaxmem=-1 -O2 $(INCS)
      LDFLAGS = $(FFLAGS) $(LIBS)
   

LANL POP

Has not been tested with this version of DART and must be verified.

is invoked the same way as any other high-order model. Important: This interface was tested with the LANL/POP 2_0_1 version of POP ... but STILL CANNOT BE USED for assimilation until the POP code is modified to do a forward euler timestep for an 'assimilation' restart.

DART is invoked and POP is started/stopped multiple times. It was checked in the gx3v5 geometry and POP was built in the 'default' configuration: one which requires no forcing files, no boundary conditions, etc., so I have no idea what to expect when confronting this with real observations ...

      setenv ARCHDIR linux
      gmake OPTIMIZE=no COUPLED=no
   

Given the wide range of input files and modes for running POP - the DART scripts will surely have to be modified to accomodate moving the boundary/forcing files required for different usage patterns.

There are several scripts in the DART/models/POP/shell_scripts directory that are employed when using DART to assimilate with a LANL/POP model: advance_model.csh, run_perfect_model_obs.batch, and run_filter.batch .

The DART components compile and run on our Intel-based cluster running SLES10 with the ifort 10.1 20090203 compiler with the following flags (the value of NETCDF was appropriate for our system):

      MPIFC = mpif90
      MPILD = mpif90
      FC = ifort
      LD = ifort
      INCS = -I$(NETCDF)/include
      LIBS = -L$(NETCDF)/lib -lnetcdf -lmkl -lmkl_lapack -lguide -lpthread
      FFLAGS = -O0 -fpe0 -vec-report0 -assume byterecl $(INCS)
      LDFLAGS = $(FFLAGS) $(LIBS)
   

Intel-based machines are natively little-endian, so I like to append a ".le" suffix on all binary files.

On our machine, with the openmpi framework, it is necessary to specify input.nml:&mpi_utilities_nml:reverse_task_layout = .true., to be able to simultaneously run (2) MPI programs on the same set of nodes.

Observations.

The observations come from the World Ocean Database 2005 and are processed by DART routines in the DART/observations/WOD directory.

Converting between DART files and POP restart files.

Is not needed. DART natively reads and writes netCDF files.

Generating the initial ensemble.

Creating the initial ensemble of ocean states is an area of active research. The POP model cannot take one single model state and generate its own ensemble (typically done with pert_model_copies).

The ensemble has to come from 'somewhere else'. At present, it may be sufficient to use a climatological ensemble; e.g., using the POP restarts for '1 January 00Z' from 50 consecutive years from a hindcast experiment.

BTW - Experience has shown that having a paired (unique) atmospheric forcing maintains the ensemble spread better than simply forcing all the ocean ensemble members with one single atmospheric state.

Generating a set of observations for a 'perfect model' experiment using the LANL/POP executable and scripts.

A perfectly sensible approach to get to know the system would be to try to

  1. assimilate data for the first assimilation period and stop. Do not advance the model at all. The filter namelist can control all of this and you do not need to have a working advance_model.csh script, or even a working ocean model (as long as you have input data files).
  2. advance the model first and then assimilate data for the first assimilation period and stop.
  3. advance, assimilate and advance again. This tests the whole DART facility.

I always like running something akin to a 'perfect model' experiment to start. Since I have not come up with a good way to perturb a single model state to generate an ensemble, here's the next best thing. The details for running each program are covered in their own documentation.

  1. Create a set of initial conditions for DART by running one instance of POP for a very long time and saving restart files 'every so often'. Use one of these as the initial condition for perfect_model_obs and the rest as the ensemble for the assimilation experiment. Since no one in their right mind would use a high-resolution model for a proof-of-concept case (hint, hint), running a low-resolution model for a 'very long time' should not be a problem.
  2. create a TINY (i.e. 1) set of 'perfect' observations in the normal fashion: create_obs_sequence and then create_fixed_network_seq to create an empty observation sequence file (usually called obs_seq.in). The programs will prompt you for all the information they require. Read their documentation if necessary.
  3. break the pop_in namelist that comes with POP into two pieces - one called pop_in.part1, that contains the &time_manager_nml and put the rest in pop_in.part2. The &time_manager_nml will be repeatedly updated as the POP model is repeatedly called by advance_model.csh.
  4. modify POP/work/input.nml as needed.
  5. modify DART/models/POP/shell_scriptsrun_perfect_model_obs.batch to reflect the location of your DART directory, the POP directory, and which POPFILE to use as the initial condition.
  6. Run the experiment and populate the observation sequence file by executing/submitting the script DART/models/POP/shell_scripts/run_perfect_model_obs.batch. The script may require some modification, but not much. Please let me know if I can improve the readability or comments. run_perfect_model_obs.batch runs perfect_model_obs
  7. run_filter.batch runs filter in a similar fashion. I have not finished the documentation for this yet.

Exploring the Output.

Is pretty much like any other model. The netCDF files have the model prognostic variables before and after the assimilation. There are Matlab® scripts for perusing the netCDF files in the DART/matlab directory. There are Matlab® scripts for exploring the performance of the assimilation in observation-space (after running obs_diag to explore the obs_seq.final file) - use the scripts starting with 'plot_', i.e. DART/diagnostics/matlab/plot_*.m. As always, there are some model-specific item you should know about in DART/models/POP/matlab, and DART/models/POP/shell_scripts.

It is also worthwhile to convert your obs_seq.final file to a netCDF format obs_sequence file with obs_seq_to_netcdf

[top]

NAMELIST

We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/' for all our namelist input. Consider yourself forewarned that character strings that contain a '/' must be enclosed in quotes to prevent them from prematurely terminating the namelist. The variables and their default values are listed here:

&model_nml
   assimilation_period_days     = -1
   assimilation_period_seconds  = -1
   model_perturbation_amplitude = 0.2
   binary_grid_file_format      = 'big_endian'
   debug                        = 0,
   model_state_variables        = 'SALT_CUR ', 'QTY_SALINITY             ', 'UPDATE',
                                  'TEMP_CUR ', 'QTY_POTENTIAL_TEMPERATURE', 'UPDATE',
                                  'UVEL_CUR ', 'QTY_U_CURRENT_COMPONENT  ', 'UPDATE',
                                  'VVEL_CUR ', 'QTY_V_CURRENT_COMPONENT  ', 'UPDATE',
                                  'PSURF_CUR', 'QTY_SEA_SURFACE_PRESSURE ', 'UPDATE'
  /

This namelist is read in a file called input.nml. This namelist provides control over the assimilation period for the model. All observations within (+/-) half of the assimilation period are assimilated. The assimilation period is the minimum amount of time the model can be advanced, and checks are performed to ensure that the assimilation window is a multiple of the ocean model dynamical timestep.

Contents Type Description
assimilation_period_days integer The number of days to advance the model for each assimilation. If both assimilation_period_days and assimilation_period_seconds are ≤ 0; the value of the POP namelist variables restart_freq and restart_freq_opt are used to determine the assimilation period. WARNING: in the CESM framework, the restart_freq is set to a value that is not useful so DART defaults to 1 day - even if you are using POP in the LANL framework.
assimilation_period_seconds integer In addition to assimilation_period_days, the number of seconds to advance the model for each assimilation. Make sure you read the description of assimilation_period_days
model_perturbation_amplitude real(r8) Reserved for future use.
binary_grid_file_format character(len=32) The POP grid files are in a binary format. Valid values are 'native', 'big_endian', or 'little_endian'. Modern versions of Fortran allow you to specify the endianness of the file you wish to read when they are opened as opposed to needing to set a compiler switch or environment variable.
debug integer The switch to specify the run-time verbosity. 0 is as quiet as it gets. > 1 provides more run-time messages. > 5 provides ALL run-time messages. All values above 0 will also write a netCDF file of the grid information and perform a grid interpolation test.
model_state_variables character(:,3) Strings that associate POP variables with a DART kind and whether or not to write the updated values to the restart files. These variables will be read from the POP restart file and modified by the assimilation. Some (perhaps all) will be used by the forward observation operators. If the 3rd column is 'UPDATE', the output files will have the modified (assimilated,posterior) values. If the 3rd column is 'NO_COPY_BACK', that variable will not be written to the restart files. The DART diagnostic files will always have the (modified) posterior values. Diagnostic variables that are useful for the calculation of the forward observation operator but have no impact on the forecast trajectory of the model could have a value of 'NO_COPY_BACK'. The DART kind must be one found in the DART/assimilation_code/modules/observations/obs_kind_mod.f90 AFTER it gets built by preprocess. Most of the ocean observation kinds are specified by DART/observations/forward_operators/obs_def_ocean_mod.f90, so it should be specified in the &preprocess_nml:input_files variable.


namelist /time_manager_nml/  runid, stop_option, stop_count, &
       time_mix_opt, fit_freq, time_mix_freq, dt_option, dt_count, impcor, laccel, &
       accel_file, dtuxcel, allow_leapyear, date_separator, &
       iyear0, imonth0, iday0, ihour0, iminute0, isecond0

This namelist is read in a file called pop_in . This namelist is the same one that is used by the ocean model and is used to control the integration length of POP. It is unimportant for the CESM/POP experiments but is critically important for the LANL/POP experiments. The values are explained in full in the POP documentation. The DART code reads the namelist and simply overwrites several values with the new time integration information. All the other values are unchanged.

dart_to_pop writes out a new &time_manager_nml in pop_in.DART if the DART state being converted has the 'advance_to_time' record in it. This is the case during the middle of a DART experiment, but is not typically encountered if one is working with DART 'initial conditions' or 'restart' files. The pop_in.DART must be concatenated with the other namelists needed by POP into a file called pop_in . We have chosen to store the other namelists (which contain static information) in a file called pop_in.part2. Initially, the time_manager_nml is stored in a companion file called pop_in.part1 and the two files are concatenated into the expected pop_in - then, during the course of an assimilation experiment, DART keeps writing out a new time_manager_nml with new integration information - which gets appended with the static information in pop_in.part2 

If you are running the support programs in a standalone fashion (as you might if you are converting restart files into an intial ensemble), the 'valid time' of the model state comes from the restart file - NOT - the namelist. You can always patch the times in the headers with restart_file_utility.

Only the namelist variables of interest to DART are discussed. All other namelist variables are ignored by DART - but mean something to POP.

Contents Type Description
stop_option character [default: 'nday'] The units for stop_count.
stop_count integer [default: 1] The duration of the model integration. The units come from stop_option.

Example

&time_manager_nml
  runid          = 'gx3v5'
  stop_option    = 'nday'
  stop_count     = 1
  time_mix_opt   = 'avgfit'
  fit_freq       = 1
  time_mix_freq  = 17
  dt_option      = 'auto_dt'
  dt_count       = 1
  impcor         = .true.
  laccel         = .false.
  accel_file     = 'unknown_accel_file'
  dtuxcel        = 1.0
  allow_leapyear = .true.
  iyear0         = 2000
  imonth0        = 1
  iday0          = 1
  ihour0         = 0
  iminute0       = 0
  isecond0       = 0
  date_separator = '-'
   /

[top]

OTHER MODULES USED

types_mod
time_manager_mod
threed_sphere/location_mod
utilities_mod
obs_kind_mod
mpi_utilities_mod
random_seq_mod
dart_pop_mod
[top]

PUBLIC INTERFACES

Only a select number of interfaces used are discussed here. Each module has its own discussion of their routines.

Required Interface Routines

use model_mod, only : get_model_size
 adv_1step
 get_state_meta_data
 model_interpolate
 get_model_time_step
 static_init_model
 end_model
 init_time
 init_conditions
 nc_write_model_atts
 nc_write_model_vars
 pert_model_copies
 get_close_maxdist_init
 get_close_obs_init
 get_close_obs
 query_vert_localization_coord
 vert_convert
 read_model_time
 write_model_time

Unique Interface Routines

use model_mod, only : get_gridsize
 restart_file_to_sv
 sv_to_restart_file
 get_pop_restart_filename
 test_interpolation

Ocean model namelist interfaces &PARM03, &PARM04, and &PARM04 are read from file data. Ocean model namelist interface &CAL_NML, is read from file data.cal.

use location_mod, only : get_close_obs

The presence of 'dry' gridpoints causes a little extra work for the get_close_obs() routine. The routine normally comes from the location_mod which has no notion of wet/dry grid cell attributes. As such, the POP model_mod will be augmenting the work done by location_mod/get_close_obs() .

Fundamentally, the location_mod calculates and returns all the 'close' observations. DART is designed such that the routine that uses the list of close observations is in model_mod.f90. Consequently, the POP model_mod can take that information and adjust as necessary. This creates some logistical issues in that the POP model_mod needs to intercept all calls to location_mod:get_close_obs() - which can be achieved with the following syntax:

   use location_mod, only : loc_get_close_obs => get_close_obs

A note about documentation style. Optional arguments are enclosed in brackets [like this].

Required Interface Routines


model_size = get_model_size( )
integer :: get_model_size

Returns the length of the model state vector. Required.

model_size The length of the model state vector.


call adv_1step(x, time)
real(r8), dimension(:), intent(inout) :: x
type(time_type),        intent(in)    :: time

adv_1step is not used for the POP model. Advancing the model is done through the advance_model script. This is a NULL_INTERFACE, provided only for compatibility with the DART requirements.

x State vector of length model_size.
time    Specifies time of the initial model state.


call get_state_meta_data (index_in, location, [, var_type] )
integer,             intent(in)  :: index_in
type(location_type), intent(out) :: location
integer, optional,   intent(out) ::  var_type 

get_state_meta_data returns metadata about a given element of the DART representation of the model state vector. Since the DART model state vector is a 1D array and the native model grid is multidimensional, get_state_meta_data returns information about the native model state vector representation. Things like the location, or the type of the variable (for instance: salinity, temperature, u current component, ...). The integer values used to indicate different variable types in var_type are themselves defined as public interfaces to model_mod if required.

index_in    Index of state vector element about which information is requested.
location Returns the 3D location of the indexed state variable. The location_ type comes from DART/location/threed_sphere/location_mod.f90. Note that the lat/lon are specified in degrees by the user but are converted to radians internally.
var_type Returns the type of the indexed state variable as an optional argument. The type is one of the list of supported observation types, found in the block of code starting ! Integer definitions for DART TYPES in DART/assimilation_code/modules/observations/obs_kind_mod.f90

The list of supported variables in DART/assimilation_code/modules/observations/obs_kind_mod.f90 is created by preprocess using the entries in input.nml[&preprocess_nml, &obs_kind_nml], DEFAULT_obs_kin_mod.F90 and obs_def_ocean_mod.f90.



call model_interpolate(x, location, itype, obs_val, istatus)
real(r8), dimension(:), intent(in)  :: x
type(location_type),    intent(in)  :: location
integer,                intent(in)  :: itype
real(r8),               intent(out) :: obs_val
integer,                intent(out) :: istatus

Given a model state, model_interpolate returns the value of the desired observation type (which could be a state variable) that would be observed at the desired location. The interpolation method is either completely specified by the model, or uses some standard 2D or 3D scalar interpolation routines. Put another way, model_interpolate will apply the forward operator H to the model state to create an observation at the desired location.

If the interpolation is valid, istatus = 0. In the case where the observation operator is not defined at the given location (e.g. the observation is below the lowest model level, above the top level, or 'dry'), interp_val is returned as 0.0 and istatus = 1.

x A model state vector.
location    Location to which to interpolate.
itype Integer indexing which type of observation is desired.
obs_val The interpolated value from the model.
istatus Integer flag indicating the success of the interpolation.
success == 0, failure == anything else


var = get_model_time_step()
type(time_type) :: get_model_time_step

get_model_time_step returns the forecast length to be used as the "model base time step" in the filter. This is the minimum amount of time the model can be advanced by filter. This is also the assimilation window. All observations within (+/-) one half of the forecast length are used for the assimilation. In the POP case, this is set from the namelist values for input.nml&model_nml:assimilation_period_days, assimilation_period_seconds.

var    Smallest time step of model.


call static_init_model()

static_init_model is called for runtime initialization of the model. The namelists are read to determine runtime configuration of the model, the grid coordinates, etc. There are no input arguments and no return values. The routine sets module-local private attributes that can then be queried by the public interface routines.

See the POP documentation for all namelists in pop_in . Be aware that DART reads the POP &grid_nml namelist to get the filenames for the horizontal and vertical grid information as well as the topography information.

The namelists (all mandatory) are:
input.nml&model_mod_nml,
pop_in&time_manager_nml,
pop_in&io_nml,
pop_in&init_ts_nml,
pop_in&restart_nml,
pop_in&domain_nml, and
pop_in&grid_nml.



call end_model()

end_model is used to clean up storage for the model, etc. when the model is no longer needed. There are no arguments and no return values. The grid variables are deallocated.



call init_time(time)
type(time_type), intent(out) :: time

init_time returns the time at which the model will start if no input initial conditions are to be used. This is frequently used to spin-up models from rest, but is not meaningfully supported for the POP model. The only time this routine would get called is if the input.nml&perfect_model_obs_nml:start_from_restart is .false., which is not supported in the POP model.

time    the starting time for the model if no initial conditions are to be supplied. This is hardwired to 0.0


call init_conditions(x)
real(r8), dimension(:), intent(out) :: x

init_conditions returns default initial conditions for model; generally used for spinning up initial model states. For the POP model it is just a stub because the initial state is always provided by the input files.

x    Initial conditions for state vector. This is hardwired to 0.0


ierr = nc_write_model_atts(ncFileID)
integer             :: nc_write_model_atts
integer, intent(in) :: ncFileID

nc_write_model_atts writes model-specific attributes to an opened netCDF file: In the POP case, this includes information like the coordinate variables (the grid arrays: ULON, ULAT, TLON, TLAT, ZG, ZC, KMT, KMU), information from some of the namelists, and either the 1D state vector or the prognostic variables (SALT,TEMP,UVEL,VVEL,PSURF). All the required information (except for the netCDF file identifier) is obtained from the scope of the model_mod module. Both the input.nml and pop_in files are preserved in the netCDF file as variables inputnml and pop_in, respectively.

ncFileID    Integer file descriptor to previously-opened netCDF file.
ierr Returns a 0 for successful completion.

nc_write_model_atts is responsible for the model-specific attributes in the following DART-output netCDF files: true_state.nc, preassim.nc, and analysis.nc.



ierr = nc_write_model_vars(ncFileID, statevec, copyindex, timeindex)
integer,                intent(in) :: ncFileID
real(r8), dimension(:), intent(in) :: statevec
integer,                intent(in) :: copyindex
integer,                intent(in) :: timeindex
integer                            :: ierr

nc_write_model_vars writes a copy of the state variables to a NetCDF file. Multiple copies of the state for a given time are supported, allowing, for instance, a single file to include multiple ensemble estimates of the state. Whether the state vector is parsed into prognostic variables (SALT, TEMP, UVEL, VVEL, PSURF) or simply written as a 1D array is controlled by input.nml&model_mod_nml:output_state_vector. If output_state_vector = .true. the state vector is written as a 1D array (the simplest case, but hard to explore with the diagnostics). If output_state_vector = .false. the state vector is parsed into prognostic variables before being written.

ncFileID file descriptor to previously-opened netCDF file.
statevec A model state vector.
copyindex    Integer index of copy to be written.
timeindex The timestep counter for the given state.
ierr Returns 0 for normal completion.


call pert_model_copies(state_ens_handle, ens_size, pert_amp, interf_provided)
type(ensemble_type), intent(inout) :: state_ens_handle
integer,             intent(in)    :: ens_size
real(r8),            intent(in)    :: pert_amp
logical,             intent(out)   :: interf_provided

This routine does not work with POP. Given a handle to an ensemble of model states, pert_model_copies produces an ensemble of perturbed model states. This is used to generate ensemble initial conditions perturbed around some control trajectory state when one is preparing to spin-up ensembles. Since the DART state vector for the POP model contains both 'wet' and 'dry' cells, it is imperative to provide an interface to perturb just the wet cells (interf_provided == .true.).

The magnitude of the perturbation is wholly determined by input.nml&model_mod_nml:model_perturbation_amplitude and utterly, completely fails.

A more robust perturbation mechanism is needed. Until then, avoid using this routine by using your own ensemble of initial conditions. This is determined by setting input.nml&filter_nml:start_from_restart = .false.

state_ens_handle the handle to the ensemble of state vectors to be perturbed.
ens_size The number of ensemble members desired.
pert_amp not used, since we have no viable method for perturbing POP.
interf_provided    Because of the 'wet/dry' issue discussed above, this is always .true., indicating a model-specific perturbation is available.


call get_close_maxdist_init(gc, maxdist)
type(get_close_type), intent(inout) :: gc
real(r8),             intent(in)    :: maxdist

Pass-through to the 3-D sphere locations module. See get_close_maxdist_init() for the documentation of this subroutine.



call get_close_obs_init(gc, num, obs)
type(get_close_type), intent(inout) :: gc
integer,              intent(in)    :: num
type(location_type),  intent(in)    :: obs(num)

Pass-through to the 3-D sphere locations module. See get_close_obs_init() for the documentation of this subroutine.



call get_close_obs(gc, base_obs_loc, base_obs_kind, obs, obs_kind, &
          num_close, close_ind [, dist])
type(get_close_type),              intent(in ) :: gc
type(location_type),               intent(in ) :: base_obs_loc
integer,                           intent(in ) :: base_obs_kind
type(location_type), dimension(:), intent(in ) :: obs
integer,             dimension(:), intent(in ) :: obs_kind
integer,                           intent(out) :: num_close
integer,             dimension(:), intent(out) :: close_ind
real(r8), optional,  dimension(:), intent(out) :: dist

Given a DART location (referred to as "base") and a set of locations, and a definition of 'close' - return a subset of locations that are 'close', as well as their distances to the DART location and their indices. This routine intentionally masks a routine of the same name in location_mod because we want to be able to discriminate against selecting 'dry land' locations.

Given a single location and a list of other locations, returns the indices of all the locations close to the single one along with the number of these and the distances for the close ones. The list of locations passed in via the obs argument must be identical to the list of obs passed into the most recent call to get_close_obs_init(). If the list of locations of interest changes, get_close_obs_destroy() must be called and then the two initialization routines must be called before using get_close_obs() again.

For vertical distance computations, the general philosophy is to convert all vertical coordinates to a common coordinate. This coordinate type is defined in the namelist with the variable "vert_localization_coord".

gc Structure to allow efficient identification of locations 'close' to a given location.
base_obs_loc Single given location.
base_obs_kind Kind of the single location.
obs List of candidate locations.
obs_kind Kind associated with candidate locations.
num_close Number of locations close to the given location.
close_ind Indices of those locations that are close.
dist Distance between given location and the close ones identified in close_ind.


coordinate_system = query_vert_localization_coord( )
integer :: query_vert_localization_coord

Defines the vertical coordinate system to be used by assim_tools_mod.

coordinate_system The length of the model state vector.


call vert_convert(state_handle, location, obs_kind, istatus)
type(ensemble_type), intent(in)  :: state_handle
type(location_type), intent(in)  :: location
integer,             intent(in)  :: obs_kind
integer,             intent(out) :: istatus

This subroutine converts a given ob/state vertical coordinate to the vertical localization coordinate type requested through the model_mod namelist. POP has a default vertical coordinate system of 'height'.

state_handle The handle to the ensemble of model states.
location The 3D location and vertical coordinate system of interest. The location_ type comes from DART/location/threed_sphere/location_mod.f90. Note that the lat/lon are specified in degrees by the user but are converted to radians internally.
obs_kind Kind associated with candidate locations.
istatus Integer flag indicating the success of the conversion.
success == 0, failure == anything else


model_time = read_model_time(filename)
character(len=*), intent(in) :: filename
type(time_type) :: model_time

Reads the valid time of the model state contained in filename. Since each model may store the time in their own manner, each model must supply their own routine to read it.

filename The name of the netCDF file containing the valid time of the model state.
model_time The time - in DART's own derived type (seconds and days since 1601-01-01 00:00:00)


call write_model_time(ncid, dart_time)
integer,         intent(in) :: ncid
type(time_type), intent(in) :: dart_time

Writes the time to a netCDF file. For POP, this is actually a 'pass-through' to a routine of the same name in io/dart_time_io_mod.f90 which will write variables dart_days and dart_seconds to the netCDF file if they do not already exist.

ncid The netCDF ID of the file to receive the model time.
dart_time The time - in DART's own derived type (seconds and days since 1601-01-01 00:00:00)

Optional Public Interface Routines


call get_gridsize( num_x, num_y, num_z )
integer, intent(out) :: num_x, num_y, num_z

get_gridsize returns the dimensions of the compute domain. The horizontal gridsize is determined from pop.r.nc. The values of the horizontal grid cells is determined from the binary file specified in the pop_in&grid_nml:horiz_grid_file setting. pop_in&grid_nml:vert_grid_file specifies the name of the ASCII file containing the number and values of the vertical levels. The actual values (not just the size) is needed by get_state_meta_data().

num_x The number of longitudinal gridpoints.
num_y The number of latitudinal gridpoints.
num_z The number of vertical gridpoints.


call restart_file_to_sv(filename, state_vector, model_time)
character(len=*),       intent(in)    :: filename
real(r8), dimension(:), intent(inout) :: state_vector
type(time_type),        intent(out)   :: model_time

restart_file_to_sv Reads the list of variables specified in input.nml&:model_nml:model_state_variables from a POP netCDF format restart file and packs them into a DART state vector. The DART vector is simply a 1D vector that includes all the 'dry' cells as well as the 'wet' ones.

filename The name of the netCDF format POP restart file.
state_vector The 1D array to be used by DART.
model_time the 1D array containing the concatenated POP variables. To save storage, it is possible to modify the definition of r8 in DART/common/types_mod.f90 to be the same as that of r4.


call sv_to_restart_file(state_vector, filename, statedate)
real(r8), dimension(:), intent(in) :: state_vector
character(len=*),       intent(in) :: filename
type(time_type),        intent(in) :: statedate

sv_to_restart_file updates the variables specified in input.nml&:model_nml:model_state_variables in the POP netCDF-format restart file with values from the DART vector state_vector. The time in the file must match the statedate.

state_vector the 1D array containing the DART state vector.
filename the netCDF-format POP restart file to be updated.
statedate the 'valid_time' of the DART state vector.


call get_pop_restart_filename( filename )
character(len=*), intent(out) :: filename

get_pop_restart_filename is actually a 'pass-through' to a routine of the same name in dart_pop_mod.f90, since the filename is in module storage in dart_pop_mod.

filename    The name of the POP restart file. Hardcoded to pop.r.nc . This simplifies the scripting portions - dereference the pointer files, make a link to pop.r.nc and you're done.


call test_interpolation( test_casenum )
integer, intent(in) :: test_casenum

test_interpolation is a rigorous test of the interpolation routine and relies completely on data files that are not normally distributed with DART. This routine is only used by test_dipole_interp.f90 and is not normally part of the user-callable routines.


[top]

FILES

filename purpose
input.nml to read the model_mod namelist
pop_in to read the model_mod namelist
pop.r.nc provides grid dimensions and 'valid_time' of the model state
&grid_nml "horiz_grid_file" contains the values of the horizontal grid
&grid_nml "vert_grid_file" contains the number and values of the vertical levels
true_state.nc the time-history of the "true" model state from an OSSE
preassim.nc the time-history of the model state before assimilation
analysis.nc  the time-history of the model state after assimilation
dart_log.out [default name] the run-time diagnostic output
dart_log.nml [default name] the record of all the namelists actually USED - contains the default values

[top]

REFERENCES

[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
update_reg_list max_reg_list_num (##) is too small ... increase values. The max_reg_list_num controls the size of temporary storage used for initializing the regular grid. Four arrays of size num_reg_x*num_reg_y*max_reg_list_num are needed. The initialization fails and returns an error if max_reg_list_num is too small. A value of 30 is sufficient for the x3 POP grid with 180 regular lon and lat boxes and a value of 80 is sufficient for for the x1 grid. Look at the output from init_dipole_interp() for values for new grids.
restart_file_to_sv cannot open file "xxxx" for reading The POP restart file "xxxx" does not exist.
restart_file_to_sv 'WARNING!!! year 0 not supported; setting to year 1 Some POP restart files have year 0 ... which is not supported in a Gregorian calendar. Our intent here is to do data assimilation, normally 'real' observations have 'real' dates.
sv_to_restart_file current time /= model time. FATAL error. The DART time does not match the time of the POP restart file. This message is preceeded by several lines indicating the expected times of both DART and POP.
test_interpolation mismatch nx,nx_temp ##,## or ny,ny_temp ##,## The file sizes do not match the expected sizes for the interpolation test case being performed.

KNOWN BUGS

none at this time

[top]

FUTURE PLANS

dart_pop_mod:set_model_time_step() must ensure the forecast length is a multiple of the ocean model dynamical timestep declared by ????

Provide a better mechanism for generating a set of perturbed initial conditions - pert_model_copies()

[top]

PRIVATE COMPONENTS

N/A

[top]

Terms of Use

DART software - Copyright UCAR. This open source software is provided by UCAR, "as is", without charge, subject to all terms of use at http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: DART core group
Revision: $Revision: 11626 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Manhattan/models/POP/model_mod.html $
Change Date: $Date: 2017-05-11 11:27:50 -0600 (Thu, 11 May 2017) $
Change history:  try "svn log" or "svn diff"