ccc_esmf module reference¶

CCCma specific routines that use ESMF procedures.

Data Types¶

`cpl_grid_t`	Define the grid of the coupler.
`regrid_t`	Hold all values needed to define a transformation from one grid to another.

Functions/Subroutines¶

`get_atm_lon_1d()`	Extract 1D lon coordinate values from the atm grid definition.
`get_atm_lat_1d()`	Extract 1D lat coordinate values from the atm grid definition.
`get_atm_lon()`	Extract the 2D lon coordinate values from the atm grid definition.
`get_atm_lat()`	Extract the 2D lat coordinate values from the atm grid definition.
`get_ocn_lon()`	Extract the 2D lon coordinate values from the ocn grid definition.
`get_ocn_lat()`	Extract the 2D lat coordinate values from the ocn grid definition.
`get_ocn_mask()`	Extract the 2D mask values from the ocn grid definition.
`get_ocn_area()`	Extract the 2D area values from the ocn grid definition.
`get_grid_coord_2di4()`	Extract 2D integer*4 coordinate values from a defined grid.
`get_grid_coord_2di8()`	Extract 2D integer*4 coordinate values from a defined grid.
`get_grid_coord_2dr4()`	Extract 2D real*4 coordinate values from a defined grid.
`get_grid_coord_2dr8()`	Extract 2D real*8 coordinate values from a defined grid.
`get_grid_item()`	Extract mask or area values from a defined grid.
`create_atm_grid_file()`	Create a netcdf file containing AGCM grid information.
`create_ocn_grid_file()`	Create a netcd file containing NEMO grid information This will contain the coordinate, mask and cell area data that is available at run time.
`read_atm_grid_file()`	Read coordinate information from a netcdf file containing AGCM grid data that was created by create_atm_grid_file.
`read_ocn_grid_file()`	Read coordinate information from a netcd file containing NEMO grid data that was created by create_ocn_grid_file.
`copy_cpl_grid_t()`	Copy one `cpl_grid_t()` variable to another variable to another `cpl_grid_t()` variable.
`handle_esmf_err()`	Error handling for ESMF routines.
`get_time_string()`	Return a string containing time on a given clock.
`init_esmf()`	Initialize ESMF.
`define_events()`	Allocate and assign the global event array.
`set_alarms()`	Allocate and assign the global alarm array.
`append_regrid_list()`	Append an entry to regrid_list.
`copy_regrid_t()`	Copy one `regrid_t()` to another.
`print_regrid_t()`	Print elements of `regrid_t()`.
`find_regrid_id()`	Find the first regrid ID in regrid_list that matches the input.
`check_remap_global_sum()`	Evaluate source and destination global areas for this regrid operation.
`define_regrid()`	Create a route handle for a particular regrid operation.
`regrid_field_cv()`	Wrapper for a conservative, fracarea remap.
`regrid_fieldbyname()`	Regrid one field onto another field NOTE: dst_field will always be reallocated to be the size of dst_name.
`regrid_fieldbyid()`	Regrid one field onto another field using the specifed route handle.
`calc_global_integral()`	Calculate the global integral and average for field given the regrid ID Note that ESMF_Field contains a pointer to an ESMF_FieldType class so that passing an ESMF_Field effectively passes a pointer (ie not data)
`find_grid_id()`	Find the grid ID given a grid name and, optionally, a mask If no initialized grid is found then return grid ID = 0 unless the grid name is one of atm, ocn, canom (in which case we abort)
`grid_desc_file_name()`	Given a grid ID return the associated grid description file name.
`init_grids()`	Create grid objects from SCRIP format grid description files.
`add_grid()`	Add a grid object using info from a grid description file.
`define_grid_from_file()`	Define a grid object using data read from a grid description file.
`compute_grid_area()`	Compute grid cell area using ESMF_FieldRegridGetArea.
`agcm_coords_available()`	Determine if all relevant AGCM grid information is available in memory.
`define_grid_from_agcm_coords()`	Define a grid object using internal AGCM coordinate and mask data.
`nemo_coords_available()`	Determine if all relevant NEMO grid information is available in memory.
`define_grid_from_nemo_coords()`	Define a grid object using internal NEMO coordinate and mask data.
`print_grid_info()`	Print info about a particular grid.
`store2array()`	Given a storage record, return a pointer to an ESMF array containing data from the storage record.
`is_conservative()`

Detailed Description¶

CCCma specific routines that use ESMF procedures.

Type Documentation¶

type ccc_esmf/cpl_grid_t¶

Define the grid of the coupler.

Type fields

% title [character(128)]
% file_name [character(128)]
% nx [integer]
% ny [integer]
% size [integer]
% integer (2 edges [2)
% mask [integer(esmf_kind_i4)(:,:),pointer]
% grid [type(esmf_grid),pointer]

type ccc_esmf/regrid_t¶

Hold all values needed to define a transformation from one grid to another.

Type fields

% regrid_id [integer]
% src_grid_id [integer]
% dst_grid_id [integer]
% use_src_mask [logical]
% use_dst_mask [logical]
% regrid_method [character(32)]
% norm_type [character(32)]
% line_type [character(32)]
% src_grid_name [character(128)]
% dst_grid_name [character(128)]
% src_grid_file_name [character(128)]
% dst_grid_file_name [character(128)]
% wgt_grid_file_name [character(128)]
% src_mask_values [integer(esmf_kind_i)(:),pointer]
% dst_mask_values [integer(esmf_kind_i)(:),pointer]
% src_frac [real(esmf_kind_r8)(:,:),pointer]
% dst_frac [real(esmf_kind_r8)(:,:),pointer]
% src_area [real(esmf_kind_r8)(:,:),pointer]
% dst_area [real(esmf_kind_r8)(:,:),pointer]
% rh [type(esmf_routehandle),pointer]

Function/Subroutine Documentation¶

subroutine ccc_esmf/get_atm_lon_1d(atm_lon, overlap)¶

Extract 1D lon coordinate values from the atm grid definition.

Parameters

atm_lon :: Atmospheric longitudes at the T-point
overlap :: [in] How many cells overlap in the zonal directions

Call to

id_atm_grid com_cpl::nlon_a com_cpl::olap_a

Called from

find_regrid_id

subroutine ccc_esmf/get_atm_lat_1d(atm_lat)¶

Extract 1D lat coordinate values from the atm grid definition.

Call to: id_atm_grid
Called from: find_regrid_id

subroutine ccc_esmf/get_atm_lon(atm_lon, overlap)¶

Extract the 2D lon coordinate values from the atm grid definition.

Call to: id_atm_grid com_cpl::nlat_a com_cpl::nlon_a com_cpl::olap_a
Called from: history::history_open restart::restart_create

subroutine ccc_esmf/get_atm_lat(atm_lat, overlap)¶

Extract the 2D lat coordinate values from the atm grid definition.

Call to: id_atm_grid com_cpl::nlat_a com_cpl::nlon_a com_cpl::olap_a
Called from: history::history_open restart::restart_create

subroutine ccc_esmf/get_ocn_lon(ocn_lon, overlap)¶

Extract the 2D lon coordinate values from the ocn grid definition.

Call to: id_ocn_grid com_cpl::nlat_o com_cpl::nlon_o
Called from: history::history_open restart::restart_create

subroutine ccc_esmf/get_ocn_lat(ocn_lat, overlap)¶

Extract the 2D lat coordinate values from the ocn grid definition.

Call to: id_ocn_grid com_cpl::nlat_o com_cpl::nlon_o
Called from: history::history_open restart::restart_create

subroutine ccc_esmf/get_ocn_mask(ocn_mask, overlap)¶

Extract the 2D mask values from the ocn grid definition.

Call to: get_grid_item id_ocn_grid com_cpl::nlat_o com_cpl::nlon_o
Called from: create_ocn_grid_file history::history_open

subroutine ccc_esmf/get_ocn_area(ocn_area, overlap)¶

Extract the 2D area values from the ocn grid definition.

Call to: get_grid_item id_ocn_grid com_cpl::nlat_o com_cpl::nlon_o

subroutine ccc_esmf/get_grid_coord_2di4(coord, gridID, stagger, cdim)¶

Extract 2D integer*4 coordinate values from a defined grid.

Call to: get_grid_coord_2dr8

subroutine ccc_esmf/get_grid_coord_2di8(coord, gridID, stagger, cdim)¶

Extract 2D integer*4 coordinate values from a defined grid.

Call to: get_grid_coord_2dr8

subroutine ccc_esmf/get_grid_coord_2dr4(coord, gridID, stagger, cdim)¶

Extract 2D real*4 coordinate values from a defined grid.

Call to: get_grid_coord_2dr8

subroutine ccc_esmf/get_grid_coord_2dr8(coord, gridID, stagger, cdim)¶

Extract 2D real*8 coordinate values from a defined grid.

Call to: grid_list handle_esmf_err com_cpl::lowerc n_grid_list zero
Called from: get_grid_coord_2di4 get_grid_coord_2di8 get_grid_coord_2dr4

subroutine ccc_esmf/get_grid_item(item_data, gridID, stagger, item)¶

Extract mask or area values from a defined grid.

Call to: grid_list handle_esmf_err com_cpl::lowerc n_grid_list
Called from: check_remap_global_sum create_atm_grid_file create_ocn_grid_file get_ocn_area get_ocn_mask

subroutine ccc_esmf/create_atm_grid_file(fname)¶

Create a netcdf file containing AGCM grid information. This will contain the coordinate, fractional land mask and cell area data that is available at run time.

Call to: com_cpl::atm_earth_radius com_cpl::atm_fland com_cpl::atm_grid_cell_area com_cpl::atm_gwt com_cpl::atm_lat com_cpl::atm_lon get_grid_item id_atm_grid
Called from: cpl_main

subroutine ccc_esmf/create_ocn_grid_file(fname)¶

Create a netcd file containing NEMO grid information This will contain the coordinate, mask and cell area data that is available at run time.

Call to: com_cpl::atm_earth_radius get_grid_item get_ocn_mask id_ocn_grid com_cpl::nemo_e1t com_cpl::nemo_e2t com_cpl::nemo_glamf com_cpl::nemo_glamt com_cpl::nemo_gphif com_cpl::nemo_gphit com_cpl::nemo_jpiglo com_cpl::nemo_jpjglo com_cpl::nemo_tmask
Called from: cpl_main

subroutine ccc_esmf/read_atm_grid_file(fname)¶

Read coordinate information from a netcdf file containing AGCM grid data that was created by create_atm_grid_file.

Call to: com_cpl::atm_earth_radius com_cpl::atm_fland com_cpl::atm_grid_cell_area com_cpl::atm_gwt com_cpl::atm_lat com_cpl::atm_lon com_cpl::atm_nlat com_cpl::atm_nlon com_cpl::msg
Called from: define_grid_from_agcm_coords

subroutine ccc_esmf/read_ocn_grid_file(fname)¶

Read coordinate information from a netcd file containing NEMO grid data that was created by create_ocn_grid_file.

Call to: com_cpl::atm_earth_radius com_cpl::msg com_cpl::nemo_e1t com_cpl::nemo_e2t com_cpl::nemo_glamf com_cpl::nemo_glamt com_cpl::nemo_gphif com_cpl::nemo_gphit com_cpl::nemo_jpiglo com_cpl::nemo_jpjglo com_cpl::nemo_tmask
Called from: define_grid_from_nemo_coords

subroutine ccc_esmf/copy_cpl_grid_t(in, out)¶: Copy one cpl_grid_t() variable to another variable to another cpl_grid_t() variable. variable.

subroutine ccc_esmf/handle_esmf_err(rc, txt, line, method)¶

Error handling for ESMF routines.

Call to: default_log_file com_cpl::msg
Called from: calc_global_integral compute_grid_area cpl_main define_grid_from_agcm_coords define_grid_from_file define_grid_from_nemo_coords define_regrid get_grid_coord_2dr8 get_grid_item get_time_string history::history_write init_esmf print_grid_info regrid_fieldbyid set_alarms regrid_mod::test_grid

function ccc_esmf/get_time_string(this_clock, time_type) [character(len=32)]¶

Return a string containing time on a given clock.

Call to: handle_esmf_err
Called from: cpl_main execute_event

subroutine ccc_esmf/init_esmf(mpi_group, logname)¶

Initialize ESMF.

Call to: default_log_file handle_esmf_err
Called from: cpl_main

subroutine ccc_esmf/define_events()¶

Allocate and assign the global event array. This will define the set of events the coupler will handle.

Call to: com_cpl::atm_gid com_cpl::atm_master com_cpl::canom_gid com_cpl::cpl_master com_cpl::event com_cpl::find_cpl_vinfo com_cpl::ice_gid com_cpl::ice_master com_cpl::is_special_op com_cpl::lowerc com_cpl::msg_gid com_cpl::nevents com_cpl::ocn_gid com_cpl::ocn_master com_cpl::other_gid com_cpl::uniq_names verbose
Called from: cpl_main

subroutine ccc_esmf/set_alarms(this_clock, start_time)¶

Allocate and assign the global alarm array. Associate alarms with events.

Call to: alarm com_cpl::event handle_esmf_err com_cpl::nevents verbose
Called from: cpl_main

function ccc_esmf/append_regrid_list(new_regrid) [integer]¶

Append an entry to regrid_list.

Call to: copy_regrid_t max_regrid_list n_regrid_list regrid_list
Called from: find_regrid_id

subroutine ccc_esmf/copy_regrid_t(regrid_in, regrid_out)¶

Copy one regrid_t() to another. to another.

Called from: append_regrid_list

subroutine ccc_esmf/print_regrid_t(rid)¶

Print elements of regrid_t(). .

Called from: find_regrid_id

subroutine ccc_esmf/find_regrid_id(id, src_grid_name, dst_grid_name, regrid_method, use_src_mask, use_dst_mask, src_mask_values, dst_mask_values, src_grid_id, dst_grid_id, norm_type, line_type, create)¶

Find the first regrid ID in regrid_list that matches the input. Optionally generate weights for a new regrid ID if an existing regrid ID is not found.

Call to: append_regrid_list com_cpl::atm_fland com_cpl::atm_lat com_cpl::atm_lon check_remap_global_sum cpl_grid define_regrid find_grid_id get_atm_lat_1d get_atm_lon_1d grid_desc_file_name id_atm_grid id_ocn_grid com_cpl::landfrac_bug n_grid_list n_regrid_list com_cpl::overlap print_regrid_t regrid_list
Called from: regrid_mod::create_fractional_land_mask regrid_fieldbyname

subroutine ccc_esmf/check_remap_global_sum(regridID)¶

Evaluate source and destination global areas for this regrid operation.

Call to: compute_grid_area get_grid_item id_atm_grid id_ocn_grid n_regrid_list regrid_list
Called from: find_regrid_id

subroutine ccc_esmf/define_regrid(id_regrid, use_src_mask, use_dst_mask, ignore_unmapped)¶

Create a route handle for a particular regrid operation. This route handle will be associated with the id_regrid index of the global array regrid_rh_list(:)

Call to: com_cpl::add_cpl_var cpl_grid com_cpl::cpl_var_new_tag esmf_regridmethod_conserve_2nd ccc_netcdf::grid_desc_file_type grid_list handle_esmf_err is_conservative n_regrid_list one com_cpl::other_gid ccc_netcdf::read_nemo_mesh_mask_file ccc_netcdf::read_scrip_grid_file regrid_list regrid_rh_list store::store_listrecord t_esmf two verbose
Called from: find_regrid_id

subroutine ccc_esmf/regrid_field_cv(src_name, src_data, dst_name, dst_data, alt_name)¶

Wrapper for a conservative, fracarea remap.

Call to: com_cpl::find_cpl_vinfo
Called from: restart::read_nemo_restart

subroutine ccc_esmf/regrid_fieldbyname(src_name, src_data, dst_name, dst_data, regridID, src_gavg, dst_gavg, src_grid_id, dst_grid_id, src_fld_name, dst_fld_name, method, norm_type, line_type, renormalize_destarea, use_src_mask, use_dst_mask, src_mask_values, dst_mask_values, missing_value)¶

Regrid one field onto another field NOTE: dst_field will always be reallocated to be the size of dst_name.

Call to: com_cpl::find_cpl_vinfo find_grid_id find_regrid_id n_grid_list com_cpl::print_cpl_vinfo_t regrid_fieldbyid verbose

subroutine ccc_esmf/regrid_fieldbyid(id_regrid, src_olap, dst_olap, wrk, missing_value, renormalize_destarea, src_fld_name, dst_fld_name, src_gavg, dst_gavg)¶

Regrid one field onto another field using the specifed route handle.

Call to: calc_global_integral com_cpl::fillvalue grid_list handle_esmf_err n_regrid_list regrid_list regrid_rh_list t_esmf verbose
Called from: regrid_fieldbyname

function ccc_esmf/calc_global_integral(field_in, regridID, src_or_dst, mode, gsum) [real(esmf_kind_r8)]¶

Calculate the global integral and average for field given the regrid ID Note that ESMF_Field contains a pointer to an ESMF_FieldType class so that passing an ESMF_Field effectively passes a pointer (ie not data)

Call to: handle_esmf_err n_regrid_list regrid_list
Called from: regrid_fieldbyid

function ccc_esmf/find_grid_id(grid_name, imask) [integer]¶

Find the grid ID given a grid name and, optionally, a mask If no initialized grid is found then return grid ID = 0 unless the grid name is one of atm, ocn, canom (in which case we abort)

Call to: cpl_grid grid_desc_file_name id_atm_grid id_canom4_grid id_ocn_grid
Called from: add_grid find_regrid_id regrid_fieldbyname

function ccc_esmf/grid_desc_file_name(grid_id, sfx, fid) [character(128)]¶

Given a grid ID return the associated grid description file name.

Call to: cpl_grid n_grid_list
Called from: define_grid_from_agcm_coords define_grid_from_file define_grid_from_nemo_coords find_grid_id find_regrid_id

subroutine ccc_esmf/init_grids()¶

Create grid objects from SCRIP format grid description files.

Call to: com_cpl::atm_grid_desc com_cpl::canom4_grid_desc cpl_grid define_grid_from_agcm_coords define_grid_from_file define_grid_from_nemo_coords grid_list com_cpl::ice_grid_desc id_atm_grid id_canom4_grid id_ice_grid id_ocn_grid max_grid_list n_grid_list com_cpl::ocn_grid_desc print_grid_info verbose
Called from: cpl_main

subroutine ccc_esmf/add_grid(grid_id, grid_desc_file, imask, overlap, cartesian, grid_dims, grid_edges, grid_size)¶

Add a grid object using info from a grid description file.

Call to: cpl_grid define_grid_from_file find_grid_id grid_list max_grid_list n_grid_list print_grid_info verbose
Called from: regrid_mod::define_grids regrid_mod::test_grid

subroutine ccc_esmf/define_grid_from_file(grid_id, file_name, imask, use_mask, overlap, grid_dims, grid_edges, grid_size, cartesian)¶

Define a grid object using data read from a grid description file.

Call to: com_cpl::agcm_grid_area_file com_cpl::atm_grid_cell_area cpl_grid cpl_petcount grid_desc_file_name ccc_netcdf::grid_desc_file_type grid_list handle_esmf_err id_atm_grid id_ocn_grid ccc_io::locate_file n_grid_list com_cpl::nemo_mesh_mask_file com_cpl::ocn_grid_cell_area one ccc_netcdf::read_agcm_grid_area_file ccc_netcdf::read_nemo_mesh_mask_file ccc_netcdf::read_scrip_grid_file two verbose zero
Called from: add_grid init_grids

subroutine ccc_esmf/compute_grid_area(gridID, area)¶

Compute grid cell area using ESMF_FieldRegridGetArea. Given a grid ID (ie index into the global grid_list (rray) compute grid cell area for the grid defined at that index.

Call to: grid_list handle_esmf_err
Called from: check_remap_global_sum define_grid_from_agcm_coords define_grid_from_nemo_coords

function ccc_esmf/agcm_coords_available() [logical]¶

Determine if all relevant AGCM grid information is available in memory. If the AGCM is coupled, this infomation is passed from the AGCM to the coupler at runtime. If it is not then this information is read from a file named cplrs_atm_grid.nc which is saved in the coupler restart. The following required variables are found in the module cpl_com atm_lon, atm_lat, atm_gwt, atm_grid_cell_area, atm_nlon, atm_nlat atm_earth_radius.

Call to: com_cpl::atm_earth_radius com_cpl::atm_grid_cell_area com_cpl::atm_gwt com_cpl::atm_lat com_cpl::atm_lon com_cpl::atm_nlat com_cpl::atm_nlon
Called from: define_grid_from_agcm_coords

subroutine ccc_esmf/define_grid_from_agcm_coords(grid_id)¶

Define a grid object using internal AGCM coordinate and mask data. This information is passed to the coupler from the AGCM at run time.

Call to: agcm_coords_available com_cpl::atm_earth_radius com_cpl::atm_grid_cell_area com_cpl::atm_gwt com_cpl::atm_lat com_cpl::atm_lon com_cpl::atm_nlat com_cpl::atm_nlon compute_grid_area cpl_grid cpl_petcount grid_desc_file_name grid_list handle_esmf_err n_grid_list one rad2deg read_atm_grid_file two verbose zero
Called from: init_grids

function ccc_esmf/nemo_coords_available() [logical]¶

Determine if all relevant NEMO grid information is available in memory. If NEMO is coupled, this infomation is passed from NEMO to the coupler at runtime. If it is not then this information is read from a file named cplrs_ocn_grid.nc which is saved in the coupler restart. The following required variables are found in the module cpl_com nemo_glamt, nemo_gphit, nemo_glamf, nemo_gphif, nemo_tmask, nemo_e1t, nemo_e2t.

Call to: com_cpl::nemo_e1t com_cpl::nemo_e2t com_cpl::nemo_glamf com_cpl::nemo_glamt com_cpl::nemo_gphif com_cpl::nemo_gphit com_cpl::nemo_tmask
Called from: define_grid_from_nemo_coords

subroutine ccc_esmf/define_grid_from_nemo_coords(grid_id)¶

Define a grid object using internal NEMO coordinate and mask data. This information is passed to the coupler from NEMO at run time.

Call to: com_cpl::atm_earth_radius compute_grid_area cpl_grid cpl_petcount grid_desc_file_name grid_list handle_esmf_err ccc_netcdf::mm_corner_lat ccc_netcdf::mm_corner_lon n_grid_list nemo_coords_available com_cpl::nemo_e1t com_cpl::nemo_e2t com_cpl::nemo_glamf com_cpl::nemo_glamt com_cpl::nemo_gphif com_cpl::nemo_gphit com_cpl::nemo_tmask com_cpl::ocn_grid_cell_area one read_ocn_grid_file two verbose zero
Called from: init_grids

subroutine ccc_esmf/print_grid_info(this_grid)¶

Print info about a particular grid.

Call to: handle_esmf_err one two verbose
Called from: add_grid init_grids

function ccc_esmf/store2array(rec_ptr) [type(esmf_array)]¶

Given a storage record, return a pointer to an ESMF array containing data from the storage record.

Call to: com_cpl::find_cpl_vinfo

function ccc_esmf/is_conservative(esmf_regrid_method) [logical]¶

Parameters: esmf_regrid_method :: The regrid method to be requested in ESMF
Call to: esmf_regridmethod_conserve_2nd
Called from: define_regrid