The Initialisation Phase
There are multiple methods to initialise YAC (more details: Initialising YAC). The basic method, which is collective for all processes in MPI_COMM_WORLD is:
- C
- Fortran
- Python
import yac
Initializies a YAC instance and provides further functionality.
Alternatively, it is possible to initialise YAC with a previously generated MPI communicator (using for example MPI handshake algorithm).
- C
MPI_Comm yac_comm;
MPI_COMM_WORLD, 1, &yac_group_name, &yac_comm );
void yac_cmpi_handshake(MPI_Comm comm, size_t n, char const **group_names, MPI_Comm *group_comms)
const char * yac_cget_mpi_handshake_group_name(void)
Retrieve the MPI handshake group name used by YAC.
void yac_cinit_comm(MPI_Comm comm)
- Fortran
CHARACTER(len=YAC_MAX_CHARLEN) :: yac_group_name(1)
INTEGER :: yac_comm(1)
mpi_comm_world, yac_group_name, yac_comm)
Fortran interface for getting mpi_handshake group name.
Fortran interface for the coupler initialisation.
Fortran2C interface for YAC collective routines.
After the initialisation we have the possibility to read in a coupling configuration file.
- C
void yac_cread_config_yaml(const char *yaml_filename)
- Fortran
CHARACTER(LEN=YAC_MAX_CHARLEN) :: yaml_filename
yaml_filename = "coupling.yaml"
Fortran interface for the reading of configuration files.
- Python
yaml_filename = "coupling.yaml"
yac_instance.read_config_yaml(yaml_filename)
If not defined in a coupling configuration file, the calendar has to be set. It is required for YAC be able to interpret the start- and end date, and timesteps provided by the field definition.
- C
void yac_cdef_calendar(int calendar)
int const YAC_PROLEPTIC_GREGORIAN
- Fortran
@ yac_proleptic_gregorian
- Python
def_calendar(Calendar calendar)
The start- and end date needs to be defined by at least one process in the YAC instance. This information is synchronized across all processes in the YAC instance by the synchronisation of definitions. It can be defined within a coupling configuration file or set through the interface.
- C
const char * start_datetime = "1850-01-01T00:00:00";
const char * end_datetime = "1850-12-31T00:00:00";
void yac_cdef_datetime(const char *start_datetime, const char *end_datetime)
- Fortran
CHARACTER(LEN=YAC_MAX_CHARLEN) :: start_datetime
CHARACTER(LEN=YAC_MAX_CHARLEN) :: end_datetime
start_datetime = '1850-01-01T00:00:00'
end_datetime = '1850-12-31T00:00:00'
end_datetime = end_datetime )
Fortran interface for the definition of time parameters.
- Python
start_datetime = "1850-01-01T00:00:00"
end_datetime = "1850-12-31T00:00:00"
yac_instance.def_datetime ( start_datetime, end_datetime )
A coupled run configuration may consist of multiple executables or programs, e.g. model_a.x and model_b.x. If the processes of a single excutable have to register multiple components, these processes may required their own individual communicator that contain only the processes of their respective executable in order to be able to determine the component associated to each process.
Initialising YAC contains more information on how to handle more complex setups than the one described above.
The Definition Phase
Component Definition
Each process can be part of zero, one, or more components. The components are identified by a unique component name. The definition of the component associated with each process is a collective call for all processes in the communicator passed to the initialisation routine (or MPI_COMM_WORLD if none was provided) and is called once. For each defined component an ID is returned, which is used in subsequent calls to identify the respective component.
- C
char const * comp_name = "ocean";
void yac_cdef_comp(char const *comp_name, int *comp_id)
- Fortran
INTEGER :: comp_id
CHARACTER(LEN=YAC_MAX_CHARLEN) :: comp_name
comp_name = 'Ocean'
comp_id ) ! [out]
- Python
component = yac_instance.def_comp ( "ocean" )
- C
int const nbr_comps = 2;
char const * comp_names[nbr_comps] = { "ocean", "carbon" };
void yac_cdef_comps(char const **comp_names, int num_comps, int *comp_ids)
- Fortran
INTEGER :: comp_ids(2)
CHARACTER(LEN=YAC_MAX_CHARLEN) :: comp_names(2)
comp_names(1) = 'ocean'
comp_names(2) = 'carbon'
comp_names, &
comp_ids ) ! [out]
- Python
component = yac_instance.def_comps ( ["ocean", "carbon"] )
Once, all components have been defined, a component communicator can be retrieved for each component identified by its local comp ID. In case of Python a mpi4py communicator can be obtained.
- C
MPI_Comm comp_communicator;
void yac_cget_comp_comm(int comp_id, MPI_Comm *comp_comm)
- Fortran
INTEGER :: comp_comm
comp_comm ) ! [out]
Fortran interface for getting back a local MPI communicator.
- Python
comp_communicator = component.comp_comm
In addition, YAC can provide a communicator, which encompasses all processes of a provided list of components. Not all components in this list have to be locally defined.
The generation of this communicator is collective for all processes that defined at least one component in this list. The list of component names has to be consistent across all involved processes.
- C
MPI_Comm oce_atm_comm;
char const * comp_names[2] = { "ocean", "atmosphere" };
void yac_cget_comps_comm(const char **comp_names, int num_comps, MPI_Comm *comps_comm)
- Fortran
INTEGER :: oce_atm_comm
CHARACTER(LEN=YAC_MAX_CHARLEN) :: comp_names(2)
comp_names(1) = 'ocean'
comp_names(2) = 'atmosphere'
2, &
oce_atm_comm ) ! [out]
Fortran interface for getting back a MPI communicator for communication between components.
- Python
oce_atm_comm = yac_instance.get_comps_comm(["ocean", "atmosphere"])
In some use-cases it might be difficult to provide all component names at once for the collective component definition. In this case it possible to "pre-define" components. The component ids for these "pre-defined" components are valid, however the component query routines can only be called after collective component definition is finished.
- C
char const * comp_name = "I/O";
void yac_cpredef_comp(char const *name, int *comp_id)
- Fortran
INTEGER :: comp_id
CHARACTER(LEN=YAC_MAX_CHARLEN) :: comp_name
comp_name = 'I/O'
comp_id ) ! [out]
Fortran interface for the component definition.
- Python
component = yac_instance.predef_comp ( "I/O" )
Grid Definition
YAC requires the user to provide basic information about the grids used in the coupling. This information consists of the geographical locations of all vertices, connectivity information (i.e. which vertices form a particular cell) and information about which line on the sphere the edges follow (great circles or circles of longitude or latitude). Each process has to provide this information only for its local part of the grid.
There are grid definition routines available for various grid types.
For an unstructed grid geographical locations of the vertices and the connectivity has to be provided explicitly. For this grid type it is assumed that all grid edges follow great circles.
- C
int m,n;
int const nbr_vertices = 20;
int const nbr_cells = 5;
int const nbr_connections = ...;
double x_vertices[nbr_vertices];
double y_vertices[nbr_vertices];
char * grid_name = "ocean_grid";
nbr_vertices,
nbr_cells,
x_vertices,
y_vertices,
int nbr_vertices_per_cell[NBR_CELLS]
void yac_cdef_grid_unstruct(const char *grid_name, int nbr_vertices, int nbr_cells, int *num_vertices_per_cell, double *x_vertices, double *y_vertices, int *cell_to_vertex, int *grid_id)
- Fortran
CHARACTER(LEN=YAC_MAX_CHARLEN) :: grid_name
INTEGER, PARAMETER :: nbr_vertices = 20
INTEGER, PARAMETER :: nbr_cells = 5
INTEGER :: nbr_connections = ...
INTEGER :: grid_id
INTEGER :: nbr_vertices_per_cell(nbr_cells)
INTEGER :: cell_to_vertex(nbr_connections)
DOUBLE PRECISION :: x_vertices(nbr_vertices)
DOUBLE PRECISION :: y_vertices(nbr_vertices)
grid_name = 'ocean_grid'
nbr_vertices, &
nbr_cells, &
nbr_vertices_per_cell, &
x_vertices, &
y_vertices, &
cell_to_vertex, &
grid_id ) ! [out]
Fortran interface for the definition of grids.
- Python
nbr_vertices_per_cell = [...]
x_vertices = [...]
y_vertices = [...]
cell_to_vertex = [...]
grid = UnstructuredGrid ( "ocean_grid",
nbr_vertices_per_cell,
x_vertices,
y_vertices,
cell_to_vertex)
Ordering of Edges
Depending on the grid definition routine being used, the local ordering of cells, vertices, and edges is given implicitly or explicitly by the user.
If not given explicitly (for example by using yac_cdef_grid_unstruct_edge, the ordering of the edges of the grid is defined as follows:
Generate for each edge a tuple containing the local indices of the adjacent vertices (lowest index first). Sort this list by the vertex indices; this gives the the local order of edges.
Point Definition
If data do not represent values of the complete cell, it is possible to define sets of points. Here we specify points at some location (in radian) inside of a cell (location can be YAC_LOCATION_CELL, YAC_LOCATION_CORNER, or YAC_LOCATION_EDGE).
As for the grid definition, there are multiple routines for defining points. For an unstructured grid points at the center of each cell may be defined as follows:
- C
int nbr_cells = 200;
x_points = malloc ( nbr_cells * sizeof(*x_points) );
y_points = malloc ( nbr_cells * sizeof(*y_points) );
nbr_cells,
x_points,
y_points,
int const YAC_LOCATION_CELL
void yac_cdef_points_unstruct(int const grid_id, int const nbr_points, int const located, double const *x_points, double const *y_points, int *point_id)
- Fortran
INTEGER, PARAMETER :: nbr_points = 5
INTEGER :: point_id
DOUBLE PRECISION :: x_points(nbr_points)
DOUBLE PRECISION :: y_points(nbr_points)
nbr_points, &
x_points, &
y_points, &
point_id ) ! [out]
Fortran interface for the definition of points.
- Python
nbr_cells = 200
x_points = [...]
y_points = [...]
cell_points = grid.def_points ( Location.CELL,
x_points,
y_points)
Decomposition Information
The user can provide global ids for all cell, vertices, and/or edges, if they are available. These have to be consistent across all processes. Otherwise, YAC will generate them. However, the generation of global ids may take some time. Therefore, it is recommended to provide them. Additionally, this makes interpretation of weight files (if they are generated) easier.
- C
int * global_cell_ids;
void yac_cset_global_index(int const *global_index, int location, int grid_id)
- Fortran
INTEGER :: global_cell_ids(nbr_cells)
grid_id )
Fortran interface for the setting of grid global ids.
- Python
global_cell_ids = [...]
grid.set_global_index ( global_cell_ids,
Location.CELL)
The core mask allows the user to define cells, vertices, and/or edges that YAC is supposed to ignore, for example because they are halo points that do not contain valid data. These points will not be used as a source or destination in a put/get/exchange operation.
- C
int * is_core_cell;
void yac_cset_core_mask(int const *is_core, int location, int grid_id)
- Fortran
INTEGER :: is_core_cell(nbr_cells)
grid_id )
Fortran interface for the setting of a grid core masks.
- Python
is_core_cell = [...]
grid.set_core_mask ( is_core_cell,
Location.CELL)
Definition of Masks
While core masks are supposed to allow YAC to differentiate between the compute domain and halo/dummy points. YAC also allows to define additional masks that can set for each field individually (see here). These masks can be used to specify that YAC should for example only consider coast or coean cells.
The is_valid array should have the appropriate size for the number of cells, vertices, or edges of the respective grid.
- C
int coast_mask_id;
int * is_coast_cell;
nbr_cells,
is_coast_cell,
&coast_mask_id );
void yac_cdef_mask(int const grid_id, int const nbr_points, int const located, int const *is_valid, int *mask_id)
- Fortran
INTEGER :: coast_mask_id
INTEGER :: is_coast_cell(nbr_cells)
nbr_cells, &
is_coast_cell, &
coast_mask_id ) ! [out]
Fortran interface for the definition of masks.
- Python
is_coast_cell = np.array( ... )
coast_mask = grid.def_mask ( Location.CELL,
is_coast_cell)
It is also possible to assign a default mask to a set of previously defined points. The is_valid array should again have the approriate size.
- C
int * is_ocean_cell;
void yac_cset_mask(int const *is_valid, int points_id)
- Fortran
LOGICAL :: is_ocean_cell (nbr_cells)
cell_point_id ) ! [in]
Fortran interface for the setting of default pointset masks.
- Python
is_ocean_cell = [...]
cell_points.set_mask ( is_ocean_cell )
A field usually gets assigned a mask when it is defined. However, masks for the source and target fields can also be defined for each couple either using the user interface or the through the configuration file. In these cases the masks are referenced through their names, which can be set when defining them.
- C
int coast_mask_id;
int * is_coast_cell;
char const * mask_name = "ocean mask";
nbr_cells,
is_coast_cell,
mask_name,
&coast_mask_id );
void yac_cdef_mask_named(int const grid_id, int const nbr_points, int const located, int const *is_valid, char const *name, int *mask_id)
- Fortran
INTEGER :: coast_mask_id
INTEGER :: is_coast_cell(nbr_cells)
CHARACTER(LEN=YAC_MAX_CHARLEN) :: mask_name
mask_name = 'ocean mask'
nbr_cells, &
is_coast_cell, &
mask_name, &
coast_mask_id ) ! [out]
- Python
is_coast_cell = np.array( ... )
coast_mask = grid.def_mask ( Location.CELL,
is_coast_cell,
"ocean mask")
Name-Based ID Lookup
In some coupling setups, the IDs returned by the definition routines for components, grids, point sets, and masks cannot easily be threaded through to every part of the code that requires them. YAC provides name-based getter routines as a solution: given only the name (and, for point sets and masks, the grid ID and location), they return the corresponding ID.
- C
int yac_cget_points_id(int grid_id, int location, const char *point_name)
int yac_cget_comp_id(const char *comp_name)
int yac_cget_grid_id(const char *grid_name)
int yac_cget_mask_id(int grid_id, int location, const char *mask_name)
- Fortran
INTEGER :: comp_id, grid_id, points_id, mask_id
- Python
comp_id = yac.get_component_id("atm")
grid_id = yac.get_grid_id("atm_grid")
points_id = yac.get_points_id(grid_id, Location.CELL, "cell_centers")
mask_id = yac.get_mask_id (grid_id, Location.CELL, "ocean mask")
If the requested entity has not been defined yet, a preliminary object is created internally and its ID is returned. A later call to the corresponding definition routine (e.g. Component Definition or Grid Definition) will recognise the name and return the same ID rather than allocating a new one. Every preliminary object must be fully defined before the End of Definition Phase; otherwise YAC will raise an error.
- Note
- For point sets and masks to be retrievable by name they must be defined with an explicit name. Points can be given a name via the yac_cdef_points_*_named variants and masks via yac_cdef_mask_named.
Definition of Coupling Fields
A field consists of one or more point sets and is identified by it name. YAC only supports 2D-fields on the sphere. However if multiple 2D-fields have the same configuration or the associated the field has more than one level, these can be processed in a single step using the collection size.
In case a field is configured to be coupled, the point sets have to match with the interpolation stack. Most interpolation methods only support a single point set and some interpolations are limited to certain point locations (for example Conservative interpolation only support points with location YAC_LOCATION_CELL).
- C
int sst_field_id;
char const * field_name = "sea_surface_temperature";
int const num_point_sets = 1;
char const * timestep = "PT15M";
point_ids,
num_point_sets,
timestep,
&sst_field_id );
int const YAC_TIME_UNIT_ISO_FORMAT
void yac_cdef_field(char const *name, int const comp_id, int const *point_ids, int const num_pointsets, int collection_size, const char *timestep, int time_unit, int *field_id)
- Fortran
INTEGER :: field_id
CHARACTER(LEN=YAC_MAX_CHARLEN) :: field_name
INTEGER, PARAMETER :: num_point_sets = 1
INTEGER :: point_ids(num_point_sets)
INTEGER, PARAMETER :: collection_size = 1
CHARACTER(LEN=YAC_MAX_CHARLEN) :: timestep
field_name = 'sea_surface_temperature'
timestep = 'PT15M'
point_ids(1) = cell_point_id
comp_id, &
point_ids, &
num_point_sets, &
collection_size, &
timestep, &
field_id ) ! [out]
Fortran interface for the definition of coupling fields using default masks.
@ yac_time_unit_iso_format
- Python
field_name = "sea_surface_temperature"
num_point_sets = 1
points = [cell_points]
collection_size = 1
timestep = "PT15M"
sst_field = Field.create ( field_name,
component,
points,
collection_size,
timestep,
TimeUnit.ISO_FORMAT)
If the user wants to specify a mask for a field (in addition to the core mask), he has to either set a default mask to the respective points or pass the mask id to the field definition.
The location associated with the provided masks has to match with the ones of the points and they have to be based on the same grid.
Before a field can be defined, a calendar has to be set.
- C
int sst_field_id;
char const * field_name = "sea_surface_temperature";
int const num_point_sets = 1;
int mask_ids[num_point_sets] = {ocean_mask_id};
char const * timestep = "PT15M";
point_ids,
mask_ids,
num_point_sets,
timestep,
&sst_field_id );
void yac_cdef_field_mask(char const *name, int const comp_id, int const *point_ids, int const *mask_ids, int const num_pointsets, int collection_size, const char *timestep, int time_unit, int *field_id)
- Fortran
INTEGER :: field_id
CHARACTER(LEN=YAC_MAX_CHARLEN) :: field_name
INTEGER, PARAMETER :: num_point_sets = 1
INTEGER :: point_ids(num_point_sets)
INTEGER :: mask_ids(num_point_sets)
INTEGER, PARAMETER :: collection_size = 1
CHARACTER(LEN=YAC_MAX_CHARLEN) :: timestep
field_name = 'sea_surface_temperature'
timestep = 'PT15M'
point_ids(1) = cell_point_id
mask_ids(1) = ocean_mask_id
comp_id, &
point_ids, &
mask_ids, &
num_point_sets, &
collection_size, &
timestep, &
field_id ) ! [out]
Fortran interface for the definition of coupling fields using explicit masks.
Once a field is defined it can be enabled for dynamic fractional masking (see Dynamic fractional masking).
When enabling dynamic fractional masking a fallback value has to be provided for the source field. If in an exchange operation the mask for all source points used to interpolate a target point is zero, then this value will be assigned.
- C
int sst_field_id;
char const * comp_name = "ocean";
char const * grid_name = "ocean_grid";
char const * field_name = "sea_surface_temperature";
double frac_mask_fallback_value = 0.0;
grid_name,
field_name,
frac_mask_fallback_value );
void yac_cenable_field_frac_mask(const char *comp_name, const char *grid_name, const char *field_name, double frac_mask_fallback_value)
- Fortran
CHARACTER(LEN=YAC_MAX_CHARLEN) :: comp_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: grid_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: field_name
DOUBLE PRECISION :: frac_mask_fallback_value
comp_name = 'ocean'
grid_name = 'grid_name'
field_name = 'sea_surface_temperature'
frac_mask_fallback_value = 0.0
comp_name, &
grid_name, &
field_name, &
frac_mask_fallback_value) ! [in]
- Python
frac_mask_fallback_value = 0.0
yac.enable_field_frac_mask(
comp_name, grid_name, field_name,
frac_mask_fallback_value)
Definition of Metadata
Once a component, grid, or field is defined, it is possible to attach metadata to it. In YAC metadata comes in the form of a string.
It is sufficient if at least one process defines the metadata for a component, grid, or field. If multiple processes define metadata, it has to be consistent across all of these processes.
The metadata will be synchronised and made available for all other processes by the the synchronisation of definitions and/or the end of the definition.
- C
char const * comp_metadata = "some metadata";
void yac_cdef_component_metadata(const char *comp_name, const char *metadata)
- Fortran
CHARACTER (LEN=256) :: comp_metadata
comp_metadata = "some metadata"
- Python
comp_metadata = "some metadata"
yac.def_component_metadata(comp_name, comp_metadata.encode())
- C
char const * grid_metadata = "some metadata";
void yac_cdef_grid_metadata(const char *grid_name, const char *metadata)
- Fortran
CHARACTER (LEN=256) :: grid_metadata
grid_metadata = "some metadata"
- Python
grid_metadata = "some metadata"
yac.def_grid_metadata(grid_name, grid_metadata.encode())
- C
char const * field_metadata = "some metadata";
comp_name, grid_name, field_name, field_metadata);
void yac_cdef_field_metadata(const char *comp_name, const char *grid_name, const char *field_name, const char *metadata)
- Fortran
CHARACTER (LEN=256) :: field_metadata
field_metadata = "some metadata"
comp_name, grid_name, field_name, field_metadata)
- Python
field_metadata = "some metadata"
yac.def_field_metadata(
comp_name, grid_name, field_name, field_metadata.encode())
Definition of Couples
The coupling between two fields can either be defined through a configuration file or through the interface.
As for the definition of fields, the definition of couples also requires a previously defined calendar.
To define a couple using the interface, the user has to define a interpolation stack.
- C
int const YAC_AVG_ARITHMETIC
void yac_cadd_interp_stack_config_fixed(int interp_stack_config_id, double value)
void yac_cget_interp_stack_config(int *interp_stack_config_id)
void yac_cadd_interp_stack_config_average(int interp_stack_config_id, int reduction_type, int partial_coverage)
- Fortran
INTEGER :: interp_stack_id
interp_stack_id )
interp_stack_id, -1)
Fortran interfaces for the definition of an interpolation stack.
- Python
interp_stack.add_average(AverageReductionType.YAC_AVG, 1)
interp_stack.add_fixed( -1.0 )
Alternatively, the interpolation stack can be generated from a string:
- C
int interp_stack_nnn;
"- nnn:\n"
" n: 1", &interp_stack_nnn);
void yac_cget_interp_stack_config_from_string_yaml(char const *interp_stack_config, int *interp_stack_config_id)
- Fortran
INTEGER :: interp_stack_nnn
"- nnn:" // achar(10) // &
" n: 1", interp_stack_nnn)
- Python
interp_stack_nnn =
from_string_yaml(cls, str interp_stack_string)
If an interpolation stack is not needed anymore, it can be freed.
- C
void yac_cfree_interp_stack_config(int interp_stack_config_id)
- Fortran
- Python
Once the interpolation stack is defined, it can be used in any number of couple definitions.
It is sufficient to define a couple on a single process. It will be synchronised to all other processes at synchronisation of definitions and/or the end of the definitions. However, if a couple (identified by the same source and target field) is defined on multiple processes and/or in a configuration file, the definition must be consistent.
- C
char const * src_comp_name = "atmo"
char const * tgt_comp_name = "ocean";
char const * field_name = "sea_surface_temperature";
char const * coupling_timestep = "PT15M";
int src_lag = 0;
int tgt_lag = 0;
coupling_timestep, time_unit, time_reduction,
char const src_grid_name[]
char const tgt_grid_name[]
void yac_cdef_couple(char const *src_comp_name, char const *src_grid_name, char const *src_field_name, char const *tgt_comp_name, char const *tgt_grid_name, char const *tgt_field_name, char const *coupling_timestep, int time_unit, int time_reduction, int interp_stack_config_id, int src_lag, int tgt_lag)
int const YAC_REDUCTION_TIME_NONE
- Fortran
CHARACTER(LEN=YAC_MAX_CHARLEN) :: src_comp_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: src_grid_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: tgt_comp_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: tgt_grid_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: field_name
INTEGER :: time_unit
CHARACTER(LEN=YAC_MAX_CHARLEN) :: timestep
INTEGER :: time_reduction
src_comp_name = 'atmo'
src_grid_name = 'icon_atmos_grid'
tgt_comp_name = 'ocean'
tgt_grid_name = 'icon_ocean_grid'
field_name = 'sea_surface_temperature'
timestep = 'PT15M'
src_comp_name, src_grid_name, field_name, &
tgt_comp_name, tgt_grid_name, field_name, &
time_unit, timestep, time_reduction, interp_stack_id)
Fortran interface for definition of a couple.
@ yac_reduction_time_none
- Python
src_comp_name = "atmo"
src_grid_name = "icon_atmos_grid"
tgt_comp_name = "ocean"
tgt_grid_name = "icon_ocean_grid"
field_name = "sea_surface_temperature"
coupling_timestep = "PT15M"
time_unit = TimeUnit.ISO_FORMAT
time_reduction = Reduction.INSTANT
yac.def_couple(
src_comp_name, src_grid_name, field_name,
tgt_comp_name, tgt_grid_name, field_name,
coupling_timestep, time_unit, time_reduction,
interp_stack)
YAC provides a set of additional parameters like weight file name and scaling factor, which can be set for each couple. While for Fortran and Python this is implemented as optional arguments, for C the extended coupling configuration has to be used:
- C
char const * src_comp_name = "atmo"
char const * tgt_comp_name = "ocean";
char const * field_name = "sea_surface_temperature";
char const * coupling_timestep = "PT15M";
int src_lag = 0;
int tgt_lag = 0;
int ext_couple_config;
double celcius2kelvin = 273.15;
int mapping_on_source = 1;
char const * const src_mask_name = "ocean mask"
ext_couple_config, celcius2kelvin);
ext_couple_config, mapping_on_source);
ext_couple_config_id, 1, &src_mask_name)
coupling_timestep, time_unit, time_reduction,
ext_couple_config);
char const * weight_file_name
void yac_cfree_ext_couple_config(int ext_couple_config_id)
void yac_cset_ext_couple_config_src_mask_names(int ext_couple_config_id, size_t num_src_mask_names, char const *const *src_mask_names)
void yac_cget_ext_couple_config(int *ext_couple_config_id)
void yac_cset_ext_couple_config_weight_file(int ext_couple_config_id, char const *weight_file)
void yac_cdef_couple_custom(char const *src_comp_name, char const *src_grid_name, char const *src_field_name, char const *tgt_comp_name, char const *tgt_grid_name, char const *tgt_field_name, char const *coupling_timestep, int time_unit, int time_reduction, int interp_stack_config_id, int src_lag, int tgt_lag, int ext_couple_config_id)
void yac_cset_ext_couple_config_scale_summand(int ext_couple_config_id, double scale_summand)
void yac_cset_ext_couple_config_mapping_side(int ext_couple_config_id, int mapping_side)
- Fortran
CHARACTER(LEN=YAC_MAX_CHARLEN) :: src_comp_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: src_grid_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: tgt_comp_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: tgt_grid_name
CHARACTER(LEN=YAC_MAX_CHARLEN) :: field_name
INTEGER :: time_unit
CHARACTER(LEN=YAC_MAX_CHARLEN) :: timestep
INTEGER :: time_reduction
CHARACTER(LEN=YAC_MAX_CHARLEN) :: weight_file_name
DOUBLE PRECISION :: celcius2kelvin
INTEGER :: mapping_on_source
CHARACTER(LEN=YAC_MAX_CHARLEN) :: weight_file_name
TYPE(yac_string) :: src_mask_name(1)
src_comp_name = 'atmo'
src_grid_name = 'icon_atmos_grid'
tgt_comp_name = 'ocean'
tgt_grid_name = 'icon_ocean_grid'
field_name = 'sea_surface_temperature'
timestep = 'PT15M'
weight_file_name = 'weights.nc'
celcius2kelvin = 273.15
mapping_on_source = 1
src_mask_name(1)%string = 'ocean mask'
src_comp_name, src_grid_name, field_name, &
tgt_comp_name, tgt_grid_name, field_name, &
time_unit, timestep, time_reduction, interp_stack_id, &
weight_file = weight_file_name, &
mapping_side = mapping_on_source, &
scale_summand = celcius2kelvin, &
src_mask_names = src_mask_name)
- Python
src_comp_name = "atmo"
src_grid_name = "icon_atmos_grid"
tgt_comp_name = "ocean"
tgt_grid_name = "icon_ocean_grid"
field_name = "sea_surface_temperature"
coupling_timestep = "PT15M"
time_unit = TimeUnit.ISO_FORMAT
time_reduction = Reduction.INSTANT
src_mask_name = ["ocean mask"]
weight_file_name = "weights.nc"
celcius2kelvin = 273.15
mapping_on_source = 1
yac.def_couple(
src_comp_name, src_grid_name, field_name,
tgt_comp_name, tgt_grid_name, field_name,
coupling_timestep, time_unit, time_reduction,
interp_stack,
weight_file = weight_file_name,
mapping_side = mapping_on_source,
scale_summand = celcius2kelvin,
src_masks_names = src_mask_name)
Synchronisation of Definitions (optional)
Once all components, grids and fields are defined, the configuration can be synchronized explicitly between all processes.
This is optional and can be done by only a subset of all tasks, and is done implicitly by calling yac_cenddef to end the definition phase.
Afterwards, the local configuration contains the complete definitions provided by all other processes before explicit synchronisation of definitions or ending of the definition phase.
- C
- Fortran
Fortran interface for invoking the end of the definition phase.
- Python
Alternatively, definitions can be synchronized for a specific subset of components by providing a list of component names. This allows for more fine-grained control over the synchronization process and can be called multiple times with different component sets.
- C
const char * comp_names[] = {"atmosphere", "ocean"};
void yac_csync_def_comps(char const **comp_names, int num_comp_names)
- Fortran
(/ CHARACTER(LEN=YAC_MAX_CHARLEN) :: "atmosphere", "ocean" /), 2)
- Python
yac.sync_def_comps(["atmosphere", "ocean"])
Additional Definitions
Following the synchronisation of definitions, each processes can access and query the definitions provided by all others.
YAC provides a number of routines for this task.
- C
char const ** comp_names =
malloc((size_t)nbr_comps * sizeof(*comp_names));
for (int comp_idx = 0; comp_idx < nbr_comps; ++comp_idx) {
char const * comp_metadata =
if (comp_metadata)
printf("%s (%s)\n", comp_names[comp_idx], comp_metadata);
char const * grid_metadata =
if (grid_metadata)
printf(
grid_metadata);
for (
int field_idx = 0; field_idx <
nbr_fields; ++field_idx) {
char const * field_metadata =
if (field_metadata)
printf(
"%s::%s::%s (%s)\n", comp_names[comp_idx],
field_metadata);
char const * field_timestep =
int field_collection_size =
int field_role =
printf(
"%s::%s::%s timestep: %s "
"collection_size: %d role: src(%c) tgt(%c) "
"none(%c)\n",
field_collection_size,
}
}
}
free(comp_names);
char const * grid_names[]
char const * field_names[8]
int yac_cget_field_role(const char *comp_name, const char *grid_name, const char *field_name)
int yac_cget_nbr_fields(const char *comp_name, const char *grid_name)
int const YAC_EXCHANGE_TYPE_SOURCE
int const YAC_EXCHANGE_TYPE_NONE
int const YAC_EXCHANGE_TYPE_TARGET
const char * yac_cget_grid_metadata(const char *grid_name)
int yac_cget_field_collection_size(const char *comp_name, const char *grid_name, const char *field_name)
void yac_cget_comp_names(int nbr_comps, const char **comp_names)
const char * yac_cget_field_metadata(const char *comp_name, const char *grid_name, const char *field_name)
int yac_cget_comp_nbr_grids(const char *comp_name)
int yac_cget_nbr_comps(void)
void yac_cget_comp_grid_names(const char *comp_name, int nbr_grids, const char **grid_names)
const char * yac_cget_component_metadata(const char *comp_name)
const char * yac_cget_field_timestep(const char *comp_name, const char *grid_name, const char *field_name)
void yac_cget_field_names(const char *comp_name, const char *grid_name, int nbr_fields, const char **field_names)
- Fortran
INTEGER :: comp_idx, grid_idx, field_idx
TYPE(yac_string), ALLOCATABLE :: comp_names(:)
TYPE(yac_string), ALLOCATABLE :: grid_names(:)
TYPE(yac_string), ALLOCATABLE :: field_names(:)
CHARACTER(len=:), ALLOCATABLE :: field_timestep
INTEGER :: field_collection_size
INTEGER :: field_role
DO comp_idx = 1, SIZE(comp_names)
comp_names(comp_idx)%string)) &
WRITE (*, "(A,' (',A,')')") &
comp_names(comp_idx)%string, &
comp_names(comp_idx)%string)
grid_names = &
comp_names(comp_idx)%string)
DO grid_idx = 1, SIZE(grid_names)
grid_names(grid_idx)%string)) &
WRITE (*, "(A,'::',A,' (',A,')')") &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
grid_names(grid_idx)%string)
field_names = &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string)
DO field_idx = 1, SIZE(field_names)
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
field_names(field_idx)%string)) &
WRITE (*, "(A,'::',A,'::',A,' (',A,')')") &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
field_names(field_idx)%string, &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
field_names(field_idx)%string)
field_timestep = &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
field_names(field_idx)%string)
field_collection_size = &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
field_names(field_idx)%string)
field_role = &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
field_names(field_idx)%string)
WRITE(*,"(A,'::',A,'::',A,' timestep: ',A, &
' collection_size: ',I0, &
' role: src(',A,') tgt(',A, &
') none(',A,')')") &
comp_names(comp_idx)%string, &
grid_names(grid_idx)%string, &
field_names(field_idx)%string, &
field_timestep, field_collection_size, &
merge(
'X',
'O',field_role .eq. &
merge(
'X',
'O',field_role .eq. &
merge(
'X',
'O',field_role .eq. &
DEALLOCATE(field_timestep)
DEALLOCATE(field_names(field_idx)%string)
END DO
DEALLOCATE(field_names)
DEALLOCATE(grid_names(grid_idx)%string)
ENDDO
DEALLOCATE(grid_names)
DEALLOCATE(comp_names(comp_idx)%string)
ENDDO
DEALLOCATE(comp_names)
static void merge(char *base_a, size_t num_a, int a_ascending, char *base_b, size_t num_b, int b_ascending, size_t size, int(*compar)(const void *, const void *), char *target)
@ yac_exchange_type_target
@ yac_exchange_type_source
- Python
for comp_name in yac.component_names:
comp_metadata = yac.get_component_metadata(comp_name)
if comp_metadata is not None:
print(f"{comp_name} ({comp_metadata})")
for grid_name in yac.get_comp_grid_names(comp_name):
grid_metadata = yac.get_grid_metadata(grid_name)
if grid_metadata is not None:
print(f"{comp_name}::{grid_name} ({grid_metadata})")
for field_name in yac.get_field_names(comp_name, grid_name):
field_metadata = \
yac.get_field_metadata(comp_name, grid_name, field_name)
if field_metadata is not None:
print(f"{comp_name}::{grid_name}::{field_name} " +
f"({field_metadata})")
field_timestep = \
yac.get_field_timestep(comp_name, grid_name, field_name)
field_collection_size = \
yac.get_field_collection_size(comp_name, grid_name, field_name)
print(f"{comp_name}::{grid_name}::{field_name} " +
f"timestep: {field_timestep} " +
f"collection_size: {field_collection_size}")
Even after explicitly synchronising definitions the processes can define additional grids, fields, and couples. However, these definitions will not be synchronised with the other processes until the end of the definition phase.
These additional definitions can be used for example by output components, that first want to query what the model components have defined. They can then use this information to decide which data should be sent to the output and define the respective couples accordingly.
End of Definition Phase
Once all processes have finished their definitions they have to collectively end the definition phase.
First, the definitions are synchronised across processes and verified for consistency. Then, all internal data required for the exchanges is generated. This includes constructing communication matrices, computing interpolation weights, and reading/writing of weight files, if applicable.
- C
- Fortran
Fortran interface for invoking the end of the definition phase.
- Python
Writing of Definition to File
Since the coupling configuration of a run can be configured through various means (multiple configuration files and through the user interface by all participating processes), it may not always be obivous what the final configuration of the run is.
YAC can write the coupling configuration that is known by all processes after the component definition, after the synchronisation of definitions, and after the end of the definition phase to a file. This has to be configured either through the user interface or it has to be included in one of the configuration files (see YAML configuration file).
- C
"final_coupling_config.yaml",
YAC_CONFIG_OUTPUT_FILETYPE_YAML,
void yac_cset_config_output_file(const char *filename, int filetype, int sync_location, int include_definitions)
int const YAC_CONFIG_OUTPUT_SYNC_LOC_ENDDEF
after end of definitions
- Fortran
"final_coupling_config.yaml", &
yac_config_output_filetype_yaml, &
Fortran interface for the writing of configuration files.
@ yac_config_output_sync_loc_enddef
- Python
yac.set_config_output_file(
"final_couple_config.yaml",
ConfigOutputFormat.YAML,
ConfigOutputSyncLoc.ENDDEF)
yac.enddef()
Writing of Grid Data to File
For debugging purposes it is possible to write grid data passed to YAC into a netCDF file.
This feature can either be enabled via a configuration file (see YAML configuration file) or via the user interface. If it is activated YAC will write out the grid data of the specified grid End of Definition Phase.
- C
"ocean_grid", "ocean_grid.nc");
void yac_cset_grid_output_file(const char *gridname, const char *filename)
- Fortran
"ocean_grid", "ocean_grid.nc")
Fortran interface for the writing of grid files.
Data Exchange
For sending of data YAC provides a put operation. If mapping_on_source is used, this call is collective for all source processes. The sending of data to the target processes is done using non-blocking MPI function calls. Thus, the routine returns even if the data have not been transfered to the receiver. The data are buffered internally and the user is free to reuse the send_field buffer for a next message. However, a put will always wait until the previous put for the same field has been completed.
Depending on the coupling configuration, the data provided through the put operation may be received by one or more get operations. In case no couple is defined for the field, the put can even return without any data being sent.
In the most common use case the source data provided in the put operation is redistributed, interpolated and received by the get operation. In some special cases it may be desirable that YAC only redistributes the source data to the target processes and does not apply the interpolation, because the user may choose do this on his own. This approach is supported by YAC in form of the raw data exchange.
- C
int const nbr_hor_points = 512;
int const nbr_pointsets = 1;
double *** send_field =
send_field[i] =
malloc((size_t)nbr_pointsets * sizeof(**send_field));
for (int j = 0; j < nbr_pointsets; j++)
send_field[i][j] =
malloc((size_t)nbr_hor_points * sizeof(***send_field));
}
for (int j = 0; j < nbr_pointsets; j++)
for (int k = 0; k < nbr_hor_points; k++)
send_field[i][j][k] = ... ;
send_field,
void yac_cput(int const field_id, int const collection_size, double ***const send_field, int *info, int *ierr)
- Fortran
INTEGER, PARAMETER :: nbr_hor_points = 512
INTEGER, PARAMETER :: collection_size = 4
INTEGER, PARAMETER :: nbr_pointsets = 1
INTEGER :: info
INTEGER :: ierror
DOUBLE PRECISION :: send_field(nbr_hor_points, &
nbr_pointsets, &
collection_size)
DO i = 1, collection_size
DO j = 1, nbr_pointsets
DO k = 1, nbr_hor_points
send_field(k,j,i) = ...
END DO
END DO
END DO
nbr_hor_points, &
nbr_pointsets, &
collection_size, &
send_field, &
info, &
ierror ) ! [out]
Fortran interface for sending coupling fields.
- Python
nbr_hor_points = 512
nbr_pointsets = 1
collection_size = 4
send_field = np.empty(shape=(collection_size, nbr_pointsets, nbr_hor_points))
info = field.put (send_field)
The receiving of data is implemented as a get operation. YAC provides a sychronous and an asynchronous version. The sychronous one will return after all required data has been received. The asynchronous version will return immediately and will receive the data in the background. Only after the user has made sure that an asynchronous get operation has been completed, it is safe to access the buffers provided to the respective get call (see Completition of Asynchronous Data Exchanges).
If no couple is defined for the field, the get will return without any changes to the receiving field data array.
- C
int const nbr_hor_points = 1024;
double ** recv_field =
recv_field[i] =
malloc((size_t)nbr_hor_points * sizeof(**recv_field));
recv_field,
void yac_cget(int const field_id, int collection_size, double **recv_field, int *info, int *ierr)
- Fortran
INTEGER, PARAMETER :: nbr_hor_points = 1024
INTEGER, PARAMETER :: collection_size = 4
INTEGER :: info
INTEGER :: ierror
DOUBLE PRECISION recv_field(nbr_hor_points, collection_size)
nbr_hor_points, &
collection_size, &
recv_field, &
info, &
ierror ) ! [out]
Fortran interface for receiving coupling fields.
- Python
nbr_hor_points = 1024
collection_size = 4
recv_field = np.empty(shape=(collection_size, nbr_hor_points))
recv_field, info = field.get ( recv_field )
None (default argument) can be passed. In that case a buffer in the correct size is allocated. See also Coroutines for an example how to use the Python coroutines interface.
In addition to the put and get operation, YAC also provides an exchange operation. This can be used in case of a bi-directional exchange. It executes a put and get operation at the same time and returns after both have been completed. By combining both operations, the internal buffer usage is more efficient.
- C
int const send_nbr_hor_points = 512;
int const send_nbr_pointsets = 1;
int const recv_nbr_hor_points = 1024;
int send_info;
int recv_info;
double *** send_field =
double ** recv_field =
send_field[i] =
malloc(send_nbr_pointsets * sizeof(**send_field));
recv_field[i] =
malloc(
(size_t)recv_nbr_hor_points * sizeof(**recv_field));
for (int j = 0; j < send_nbr_pointsets; j++)
send_field[i][j] =
malloc(send_nbr_hor_points * sizeof(***send_field));
}
for (int j = 0; j < send_nbr_pointsets; j++)
for (int k = 0; k < send_nbr_hor_points; k++)
send_field[i][j][k] = ... ;
recv_field_id,
send_field,
recv_field,
&send_info,
&recv_info,
void yac_cexchange(int const send_field_id, int const recv_field_id, int const collection_size, double ***const send_field, double **recv_field, int *send_info, int *recv_info, int *ierr)
- Fortran
INTEGER, PARAMETER :: send_nbr_hor_points = 512
INTEGER, PARAMETER :: send_nbr_pointsets = 1
INTEGER, PARAMETER :: recv_nbr_hor_points = 1024
INTEGER, PARAMETER :: collection_size = 4
INTEGER, PARAMETER :: collection_size = 4
INTEGER :: send_info
INTEGER :: recv_info
INTEGER :: ierror
DOUBLE PRECISION :: send_field(nbr_hor_points, &
nbr_pointsets, &
collection_size)
DOUBLE PRECISION recv_field(nbr_hor_points, &
collection_size)
DO i = 1, collection_size
DO j = 1, nbr_pointsets
DO k = 1, nbr_hor_points
send_field(k,j,i) = ...
END DO
END DO
END DO
recv_field_id, &
send_nbr_hor_points, &
send_nbr_pointsets, &
recv_nbr_hor_points, &
collection_size, &
send_field, &
recv_field, &
send_info, &
recv_info, &
ierror ) ! [out]
Fortran interface for exchanging coupling fields.
Completition of Asynchronous Data Exchanges
There are two utility routines that help working with asynchronous data exchanges.
The test operation checks whether for a provided field an asynchronous data exchange operation is still active.
- C
fputs("Last async operation is still active.", stdout);
void yac_ctest(int field_id, int *flag)
- Fortran
LOGICAL :: flag
IF (.NOT. flag) print *, "Last async operation is still active."
Fortran interface for testing fields for active communicaitons.
- Python
if field.test() == 0:
print("Last async operation is still active")
The second utility routine is the wait operation. It does not return until all active asynchronous data exchanges associated with the provided field have been completed. (This can easily result in a deadlock. The user has to make sure, that this does not occur.)
- C
fputs("Last async operation has been completed.", stdout);
void yac_cwait(int field_id)
- Fortran
print *, "Last async operation has been completed."
Fortran interface for testing fields for active communicaitons.
- Python
field.wait()
print("Last async operation has been completed.")
Exchange Info Argument
All exchange routines return an info argument, which can be used by the user to determine which action was performed by the respective exchange call. The possible values are as follows:
Advancing Internal Clock without Data Exchange Operation
YAC has for each field an internal event timer. With each put, get, or exchange operation call it is advanced according to the field time step provided in the field definition.
However, sometime it may be desirable to advance the internal clock without calling a data exchange operation, if it is safe to do so.
For each field it is possible to check the action that will occur in the next call of a data exchange operation.
If appropriate, the update operation can be executed instead of a data exchange operation.
- C
int action;
} else {
}
void yac_cupdate(int field_id)
void yac_cget_action(int field_id, int *action)
int const YAC_ACTION_NONE
no data exchanges
- Fortran
INTEGER :: action
ELSE
END IF
@ yac_action_none
no data exchanges
- Python
if field.action == yac.Action.NONE:
field.update()
else:
The Finalisation Phase
Once all exchanges have been completed, YAC has to be finalised, which frees all memory allocated by YAC.
- C
void yac_cfinalize()
Finalises YAC.
- Fortran
Fortran interface for the coupler termination.
- Python
In case MPI_Init was initialised by YAC, MPI_Finalize will be called in this finalisation phase. If the user has called MPI_Init himself (before the YAC initialisation), he also has to call MPI_Finalize once the finalisation phase has been completed.
Restarting YAC
It is possible to restart YAC. To do that, the user has to clean up YAC in the finalisation phase instead of finalising it.
- C
void yac_ccleanup()
Clean-up default YAC instance (see Restarting YAC)
- Fortran
Fortran interface for the coupler cleanup before restart.
After the cleanup, the user can restart YAC by going through the initialisation, definition, and data exchange phase as before. The restarted YAC can have a different configuration than the previous one.
If the user initialised yaxt manually, they must finalise it after the cleanup to be able to initialise YAC again.
1.11.0