YAC instances

Table of Contents

• Introduction
• Usage
  • Initialisation Phase
  • Definition Phase
  • End of definition and search
  • Data Exchange
  • Ending Phase
  • Restart Phase

Introduction

With Version 2.3.0 (Aug 2021) the concept of YAC instances was introduced. This new feature allows the user to instantiate YAC multiple times in the same application. Additionally, each instance can be initialised with a different MPI communicator and a different coupling configuration (via interface and/or configuration file).

In case an application uses YAC for different purposes, individual YAC instances can be used for each of them without interfering with each other. A potential use case may a model setup consisting of an global atmosphere and ocean model, which are coupled to each other. If in this setup the atmosphere has some dedicated processes that are responsible for writing out a regional part of the data using a different grid, YAC could be used to provide the respective data to these output processes. Using a dedicated YAC instance for the coupling between the atmosphere and its output processes could use its own configuration file, which might simplify the setup of the model run. Both YAC instances could be initialised using dedicated MPI communicators, which reduces complexity even further.

YAC provides a default instance, which is used in case the user does not explicitly provide an instance.

YAC instances are referenced by ID's that are returned by either yac_cinit_instance or yac_cinit_comm_instance. Various routines required the user to explicitly provide this ID as an argument. These routines can be identified by an "_instance" at the end of their names. Some routines like yac_cdef_field do not require an explicit YAC instance ID, because it is implicitly given by another argument (component_id in this case).

An example on how to use YAC instances can be found here.

Usage

Here the usage of YAC instances is shown for the C interface; equivalent Fortran interfaces are also available.

Initialisation Phase

A YAC instance is initialised by a call to yac_cinit_instance or yac_cinit_comm_instance.

char * yaml_filename = "coupling_aquaplanet.yaml";
int yac_instance_id;
 
yac_cinit_instance ( &yac_instance_id );
yac_cread_config_yaml_instance ( yac_instance_id, yaml_filename );

char * yaml_filename = "coupling_aquaplanet.yaml";
MPI_Comm comm = MPI_COMM_WORLD;
int yac_instance_id;
 
yac_cinit_comm_instance ( comm, &yac_instance_id );
yac_cread_config_yaml_instance ( yac_instance_id, yaml_filename );

Definition Phase

The definition of components, grid, and start- and endtime require the user to explicitly provide the YAC instance ID.

• yac_cdef_comp_instance
• yac_cdef_comps_instance
• yac_cdef_datetime_instance

For all other definition routines the YAC instance ID is provided implicitly.

End of definition and search

The definition phase is finalized and the search started with a call to yac_cenddef_instance.

yac_cenddef_instance ( yac_instance_id );

A call to yac_cenddef will do this only for the default instance.

Data Exchange

For the data exchange not specific interfaces are required.

Ending Phase

A YAC instance needs to be explicitly finalized:

yac_cfinalize_instance ( yac_instance_id );

In case any other YAC instance is still active while yac_cfinalize_instance is called, MPI will not by finalized by this call.

If for any other instance yac_cfinalize_instance or yac_cfinalize is called at a later point in time, a call to yac_ccleanup_instance is sufficiant to clean up the memory of a YAC instance.

Restart Phase

The default instance can be restarted. To do this its memory needs to be freed by a call to yac_ccleanup. Afterwards yac_cinit can be called again.

It is not possible to restart the other YAC instances. However, at any point in time a new instance can be initialised with a call to yac_cinit_instance yac_cinit_comm_instance even with the same arguments as for a previous call. This new instance can be viewed as a restart of another instance. In any case all initialised instances have to be cleaned up or finalized.