couple_config.c

Go to the documentation of this file.

// Copyright (c) 2024 The YAC Authors
//
// SPDX-License-Identifier: BSD-3-Clause
 
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
 
#include <limits.h>
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <math.h>
 
#include <mpi.h>
 
#include "couple_config.h"
#include "couple_config_component.h"
#include "couple_config_config_output.h"
#include "couple_config_couple.h"
#include "couple_config_grid.h"
#include "couple_config_internal.h"
 
#include "yac_mpi_common.h"
#include "yac.h"
#include "mtime_calendar.h"
#include "utils_common.h"
#include "config_yaml.h"
#include "mtime_datetime.h"
#include "interpolation/interpolation_internal.h"
#include "interpolation/interpolation_gen_config.h"
#include "yac_mpi_internal.h"
#include "collection_selection_internal.h"
#include "instance.h"
 
static size_t yac_couple_config_get_component_idx_unsafe(
  struct yac_couple_config const * couple_config, char const * component_name);
static size_t yac_couple_config_get_grid_idx_unsafe(
  struct yac_couple_config const * couple_config, char const * grid_name);
static size_t yac_couple_config_get_field_idx_unsafe(
  struct yac_couple_config const * couple_config, size_t component_idx,
  size_t grid_idx, char const * field_name);
 
struct yac_couple_config * yac_couple_config_new() {
 
  struct yac_couple_config * couple_config =
    xmalloc(1 * sizeof(*couple_config));
 
  couple_config->start_datetime = NULL;
  couple_config->end_datetime = NULL;
 
  couple_config->config_outputs = NULL;
  couple_config->num_config_outputs = 0;
 
  couple_config->grids = NULL;
  couple_config->num_grids = 0;
 
  couple_config->components = NULL;
  couple_config->num_components = 0;
 
  couple_config->couples = NULL;
  couple_config->num_couples = 0;
 
  couple_config->missing_definition_is_fatal = YAC_COUPLE_CONFIG_FLAG_UNSET;
  couple_config->apply_coordinate_check = YAC_COUPLE_CONFIG_FLAG_UNSET;
  couple_config->coordinates_mismatch_is_fatal = YAC_COUPLE_CONFIG_FLAG_UNSET;
 
  return couple_config;
}
 
static struct yac_couple_config_component * yac_couple_config_get_component(
  struct yac_couple_config const * couple_config, char const * component_name) {
 
  size_t component_idx =
    yac_couple_config_get_component_idx(couple_config, component_name);
 
  YAC_ASSERT(couple_config->components != NULL,
    "couple_config->components is NULL");
 
  YAC_ASSERT_F(component_idx < couple_config->num_components,
    "invalid component index %zu (number of components: %zu)",
    component_idx, couple_config->num_components);
 
  return couple_config->components + component_idx;
}
 
static void couple_config_sync_calendar(MPI_Comm comm) {
 
  int calendar = (int)getCalendarType();
  if (calendar == CALENDAR_NOT_SET) calendar = INT_MAX;
 
  // broadcast calendar
  yac_mpi_call(
    MPI_Allreduce(
      MPI_IN_PLACE, &calendar, 1, MPI_INT, MPI_MIN, comm), comm);
 
  // if no process has defined a calendar
  if (calendar == INT_MAX) return;
 
  // set calendar (if local process has already defined a calendar,
  // the definition is checked for consistency)
  yac_instance_def_calendar(calendar, "coupling configuration synchronization");
}
 
void yac_couple_config_delete(struct yac_couple_config * couple_config) {
 
  deallocateDateTime((void*)couple_config->start_datetime);
  deallocateDateTime((void*)couple_config->end_datetime);
 
  yac_couple_config_config_outputs_free(
    &couple_config->config_outputs, &couple_config->num_config_outputs);
  yac_couple_config_grids_free(
    &couple_config->grids, &couple_config->num_grids);
  yac_couple_config_components_free(
    &couple_config->components, &couple_config->num_components);
  yac_couple_config_couples_free(
    &couple_config->couples, &couple_config->num_couples);
  free(couple_config);
}
 
static size_t yac_couple_config_add_grid_(
  struct yac_couple_config * couple_config, char const * name) {
 
  return
    yac_couple_config_grid_append(
      &(couple_config->grids), &(couple_config->num_grids), name);
}
 
void yac_couple_config_add_grid(
  struct yac_couple_config * couple_config, char const * name) {
 
  yac_couple_config_add_grid_(couple_config, name);
}
 
static size_t yac_couple_config_add_component_(
  struct yac_couple_config * couple_config, char const * name) {
 
  return
    yac_couple_config_component_append(
      &(couple_config->components), &(couple_config->num_components), name);
}
 
void yac_couple_config_add_component(
  struct yac_couple_config * couple_config, char const * name) {
 
  yac_couple_config_add_component_(couple_config, name);
}
 
void yac_couple_config_set_component_metadata(
  struct yac_couple_config * couple_config,
    char const * comp_name, const char* metadata) {
  struct yac_couple_config_component * component =
    yac_couple_config_get_component(couple_config, comp_name);
  yac_couple_config_set_component_metadata_value(component, metadata);
}
 
void yac_couple_config_set_grid_output_filename(
  struct yac_couple_config * couple_config,
    char const * grid_name, const char* output_filename) {
  YAC_ASSERT(
    grid_name != NULL,
    "invalid grid_name (NULL is not allowed)");
  if(!yac_couple_config_contains_grid_name(couple_config, grid_name)) {
    yac_couple_config_add_grid(couple_config, grid_name);
  }
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
  yac_couple_config_set_grid_output_filename_value(
    couple_config->grids + grid_idx, output_filename);
}
 
void yac_couple_config_set_grid_metadata(
  struct yac_couple_config * couple_config,
    char const * grid_name, const char* metadata) {
  YAC_ASSERT(
    grid_name != NULL,
    "invalid grid_name (NULL is not allowed)");
  if(!yac_couple_config_contains_grid_name(couple_config, grid_name)) {
    yac_couple_config_add_grid(couple_config, grid_name);
  }
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
  yac_couple_config_set_grid_metadata_value(
    couple_config->grids + grid_idx, metadata);
}
 
void yac_couple_config_set_field_metadata(
  struct yac_couple_config * couple_config,
    const char* comp_name, const char * grid_name, const char* field_name,
    const char* metadata) {
  size_t comp_idx = yac_couple_config_get_component_idx(couple_config, comp_name);
  struct yac_couple_config_component * component =
    couple_config->components + comp_idx;
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
  yac_couple_config_component_set_field_metadata(
    component, grid_idx, field_name, metadata);
}
 
const char* yac_couple_config_get_component_metadata(
  struct yac_couple_config const * couple_config, const char * comp_name) {
  size_t comp_idx = yac_couple_config_get_component_idx(couple_config, comp_name);
  return couple_config->components[comp_idx].metadata;
}
 
const char* yac_couple_config_get_grid_output_filename(
  struct yac_couple_config const * couple_config,
    const char * grid_name) {
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
  return couple_config->grids[grid_idx].output_filename;
}
 
const char* yac_couple_config_get_grid_metadata(
  struct yac_couple_config const * couple_config,
    const char * grid_name) {
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
  return couple_config->grids[grid_idx].metadata;
}
 
const char* yac_couple_config_get_field_metadata(
  struct yac_couple_config const * couple_config,
    const char* comp_name, const char * grid_name, const char* field_name) {
  struct yac_couple_config_component * component =
    yac_couple_config_get_component(couple_config, comp_name);
 
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
 
  return yac_couple_config_component_get_field_metadata(
    component, grid_idx, field_name
  );
}
 
#define CHECK_COMPONENT_IDX() \
  YAC_ASSERT_F( \
    component_idx < couple_config->num_components, "invalid component_idx")
 
#define CHECK_GRID_IDX() \
  YAC_ASSERT_F( \
    grid_idx < couple_config->num_grids, "invalid grid_idx")
 
static size_t yac_couple_config_add_component_field_(
  struct yac_couple_config * couple_config,
  size_t component_idx, size_t grid_idx, char const * field_name,
  char const * timestep, size_t collection_size) {
 
  CHECK_COMPONENT_IDX();
  CHECK_GRID_IDX();
 
  // check whether the field already exists
  struct yac_couple_config_component * component =
    couple_config->components + component_idx;
 
  return yac_couple_config_component_update_or_append_field(
    component, field_name, grid_idx, timestep, collection_size);
}
 
void yac_couple_config_add_component_field(
  struct yac_couple_config * couple_config, const char* component_name,
    const char* grid_name, const char* name, char const * timestep,
    size_t collection_size) {
 
  yac_couple_config_add_component_field_(
    couple_config,
    yac_couple_config_get_component_idx(couple_config, component_name),
    yac_couple_config_get_grid_idx(couple_config, grid_name),
    name, timestep, collection_size);
}
 
size_t yac_couple_config_get_num_couples(
  struct yac_couple_config const * couple_config) {
 
  return couple_config->num_couples;
}
 
int yac_couple_config_get_missing_definition_is_fatal(
  struct yac_couple_config const * couple_config) {
 
  int ret = MISSING_DEFINITION_IS_FATAL_DEFAULT_VALUE;
 
  switch(couple_config->missing_definition_is_fatal) {
    YAC_UNREACHABLE_DEFAULT(
      "invalid value of missing_definition_is_fatal-flag");
    case(YAC_COUPLE_CONFIG_FLAG_FALSE):
      ret = 0;
      break;
    case(YAC_COUPLE_CONFIG_FLAG_TRUE):
      ret = 1;
      break;
    case(YAC_COUPLE_CONFIG_FLAG_UNSET):
      ret = MISSING_DEFINITION_IS_FATAL_DEFAULT_VALUE;
      break;
  }
  return ret;
}
 
void yac_couple_config_set_missing_definition_is_fatal(
  struct yac_couple_config * couple_config,
  int missing_definition_is_fatal) {
 
  enum yac_couple_config_flag_value user_value =
    (missing_definition_is_fatal != 0)
      ? YAC_COUPLE_CONFIG_FLAG_TRUE
      : YAC_COUPLE_CONFIG_FLAG_FALSE;
 
  YAC_ASSERT_F(
    (couple_config->missing_definition_is_fatal ==
       YAC_COUPLE_CONFIG_FLAG_UNSET) ||
    (couple_config->missing_definition_is_fatal == user_value),
    "inconsistent setting of \"missing_definition_is_fatal\"-flag "
    "(old: %s new: %s)",
    (couple_config->missing_definition_is_fatal == YAC_COUPLE_CONFIG_FLAG_TRUE)
      ? "TRUE" : "FALSE",
    (user_value == YAC_COUPLE_CONFIG_FLAG_TRUE) ? "TRUE" : "FALSE");
 
  couple_config->missing_definition_is_fatal = user_value;
}
 
int yac_couple_config_get_apply_coordinate_check(
  struct yac_couple_config const * couple_config) {
 
  int apply_coordinate_check = APPLY_COORDINATE_CHECK_DEFAULT_VALUE;
 
  switch(couple_config->apply_coordinate_check) {
    YAC_UNREACHABLE_DEFAULT("invalid value of apply_coordinate_check-flag");
    case(YAC_COUPLE_CONFIG_FLAG_FALSE): {
      apply_coordinate_check = 0;
      break;
    }
    case(YAC_COUPLE_CONFIG_FLAG_TRUE): {
      apply_coordinate_check = 1;
      break;
    }
    case(YAC_COUPLE_CONFIG_FLAG_UNSET): {
      apply_coordinate_check = APPLY_COORDINATE_CHECK_DEFAULT_VALUE;
      break;
    }
  }
 
  return apply_coordinate_check;
}
 
void yac_couple_config_set_apply_coordinate_check(
  struct yac_couple_config * couple_config,
  int apply_coordinate_check) {
 
  enum yac_couple_config_flag_value user_value =
    (apply_coordinate_check != 0)
      ? YAC_COUPLE_CONFIG_FLAG_TRUE
      : YAC_COUPLE_CONFIG_FLAG_FALSE;
 
  YAC_ASSERT_F(
    (couple_config->apply_coordinate_check ==
       YAC_COUPLE_CONFIG_FLAG_UNSET) ||
    (couple_config->apply_coordinate_check == user_value),
    "inconsistent setting of \"apply_coordinate_check\"-flag "
    "(old: %s new: %s)",
    (couple_config->apply_coordinate_check ==
       YAC_COUPLE_CONFIG_FLAG_TRUE) ? "TRUE" : "FALSE",
    (user_value == YAC_COUPLE_CONFIG_FLAG_TRUE) ? "TRUE" : "FALSE");
 
  couple_config->apply_coordinate_check = user_value;
}
 
int yac_couple_config_get_coordinates_mismatch_is_fatal(
  struct yac_couple_config const * couple_config) {
 
  int coordinates_mismatch_is_fatal =
    COORDINATES_MISMATCH_IS_FATAL_DEFAULT_VALUE;
 
  switch(couple_config->coordinates_mismatch_is_fatal) {
    YAC_UNREACHABLE_DEFAULT(
      "invalid value of coordinates_mismatch_is_fatal-flag");
    case(YAC_COUPLE_CONFIG_FLAG_FALSE): {
      coordinates_mismatch_is_fatal = 0;
      break;
    }
    case(YAC_COUPLE_CONFIG_FLAG_TRUE): {
      coordinates_mismatch_is_fatal = 1;
      break;
    }
    case(YAC_COUPLE_CONFIG_FLAG_UNSET): {
      coordinates_mismatch_is_fatal =
        COORDINATES_MISMATCH_IS_FATAL_DEFAULT_VALUE;
      break;
    }
  }
 
  return coordinates_mismatch_is_fatal;
}
 
void yac_couple_config_set_coordinates_mismatch_is_fatal(
  struct yac_couple_config * couple_config,
  int coordinates_mismatch_is_fatal) {
 
  enum yac_couple_config_flag_value user_value =
    (coordinates_mismatch_is_fatal != 0)
      ? YAC_COUPLE_CONFIG_FLAG_TRUE
      : YAC_COUPLE_CONFIG_FLAG_FALSE;
 
  YAC_ASSERT_F(
    (couple_config->coordinates_mismatch_is_fatal ==
       YAC_COUPLE_CONFIG_FLAG_UNSET) ||
    (couple_config->coordinates_mismatch_is_fatal == user_value),
    "inconsistent setting of "
    "\"coordinates_mismatch_is_fatal\"-flag "
    "(old: %s new: %s)",
    (couple_config->coordinates_mismatch_is_fatal ==
       YAC_COUPLE_CONFIG_FLAG_TRUE) ? "TRUE" : "FALSE",
    (user_value == YAC_COUPLE_CONFIG_FLAG_TRUE) ? "TRUE" : "FALSE");
 
  couple_config->coordinates_mismatch_is_fatal = user_value;
}
 
#define CHECK_COUPLE_IDX() \
  YAC_ASSERT_F(couple_idx < couple_config->num_couples, "invalid couple_idx")
 
size_t yac_couple_config_get_num_couple_fields(
  struct yac_couple_config const * couple_config, size_t couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  return couple_config->couples[couple_idx].num_field_couples;
}
 
void yac_couple_config_get_couple_component_names(
  struct yac_couple_config const * couple_config, size_t couple_idx,
  char const * couple_component_names[2]) {
 
  CHECK_COUPLE_IDX();
 
  for (int i = 0; i < 2; ++i)
    couple_component_names[i] =
      couple_config->components[
        couple_config->couples[couple_idx].component_indices[i]].name;
}
 
int yac_couple_config_is_valid_component_name(
  struct yac_couple_config const * couple_config, char const * component_name) {
 
  YAC_ASSERT(component_name, "component name is NULL")
  YAC_ASSERT(
    strlen(component_name) <= YAC_MAX_CHARLEN,
    "component name is too long (maximum is YAC_MAX_CHARLEN)")
 
  int found_flag = 0;
 
  for (size_t component_idx = 0;
       (component_idx < couple_config->num_components) && !found_flag;
       ++component_idx) {
    found_flag =
      !strcmp(component_name, couple_config->components[component_idx].name);
  }
  return found_flag;
}
 
size_t yac_couple_config_get_num_components(
  struct yac_couple_config const * couple_config) {
 
  return couple_config->num_components;
}
 
size_t yac_couple_config_get_num_grids(
  struct yac_couple_config const * couple_config) {
 
  return couple_config->num_grids;
}
 
size_t yac_couple_config_get_num_fields(
  struct yac_couple_config const * couple_config, size_t component_idx) {
  CHECK_COMPONENT_IDX();
  return couple_config->components[component_idx].num_fields;
}
 
size_t yac_couple_config_get_component_idx(
  struct yac_couple_config const * couple_config, char const * component_name) {
 
  size_t const component_idx =
    yac_couple_config_get_component_idx_unsafe(couple_config, component_name);
 
  YAC_ASSERT_F(
    component_idx != SIZE_MAX,
    "Component \"%s\" not found in coupling configuration",
    component_name);
 
  return component_idx;
}
 
static size_t yac_couple_config_get_component_idx_unsafe(
  struct yac_couple_config const * couple_config, char const * component_name) {
 
  size_t component_idx = SIZE_MAX;
  for (size_t i = 0; (i < couple_config->num_components) &&
                     (component_idx == SIZE_MAX); ++i) {
    if (!strcmp(couple_config->components[i].name, component_name)) {
      component_idx = i;
    }
  }
 
  return component_idx;
}
 
size_t yac_couple_config_get_grid_idx(
  struct yac_couple_config const * couple_config, char const * grid_name) {
 
  size_t const grid_idx =
    yac_couple_config_get_grid_idx_unsafe(couple_config, grid_name);
 
  YAC_ASSERT_F(
    grid_idx != SIZE_MAX, "grid name \"%s\" not in list of grids", grid_name)
 
  return grid_idx;
}
 
static size_t yac_couple_config_get_grid_idx_unsafe(
  struct yac_couple_config const * couple_config, char const * grid_name) {
 
  size_t grid_idx = SIZE_MAX;
  for (size_t i = 0;
       (i < couple_config->num_grids) && (grid_idx == SIZE_MAX); ++i) {
    if (!strcmp(couple_config->grids[i].name, grid_name)) {
      grid_idx = i;
    }
  }
 
  return grid_idx;
}
 
size_t yac_couple_config_get_field_idx(
  struct yac_couple_config const * couple_config, size_t component_idx,
    size_t grid_idx, char const * field_name) {
  CHECK_COMPONENT_IDX();
 
  size_t const field_idx = yac_couple_config_get_field_idx_unsafe(
    couple_config, component_idx, grid_idx, field_name);
 
  YAC_ASSERT_F(
    field_idx != SIZE_MAX,
    "field \"%s\" for grid_idx %zu not found in component_idx %zu",
    field_name, grid_idx, component_idx);
 
  return field_idx;
}
 
static size_t yac_couple_config_get_field_idx_unsafe(
  struct yac_couple_config const * couple_config, size_t component_idx,
  size_t grid_idx, char const * field_name) {
 
  struct yac_couple_config_component * component =
    couple_config->components + component_idx;
 
  struct yac_couple_config_field * field =
    yac_couple_config_component_find_field(component, grid_idx, field_name);
 
  return (field == NULL) ? SIZE_MAX : (size_t)(field - component->fields);
}
 
char const * yac_couple_config_get_component_name(
  struct yac_couple_config const * couple_config, size_t component_idx) {
 
  CHECK_COMPONENT_IDX();
 
  return couple_config->components[component_idx].name;
}
 
char const * yac_couple_config_get_field_grid_name(
  struct yac_couple_config const * couple_config, size_t component_idx,
  size_t field_idx) {
 
  CHECK_COMPONENT_IDX();
 
  struct yac_couple_config_component const * component =
    couple_config->components + component_idx;
 
  size_t const grid_idx =
    yac_couple_config_component_get_field_grid_idx(component, field_idx);
 
  CHECK_GRID_IDX();
 
  struct yac_couple_config_grid const * grid =
    couple_config->grids + grid_idx;
 
  return grid->name;
}
 
char const * yac_couple_config_get_field_name(
  struct yac_couple_config const * couple_config, size_t component_idx,
  size_t field_idx) {
 
  CHECK_COMPONENT_IDX();
 
  struct yac_couple_config_component const * component =
    couple_config->components + component_idx;
 
  return yac_couple_config_component_get_field_name(component, field_idx);
}
 
char const * yac_couple_config_get_field_timestep(
  struct yac_couple_config const * couple_config,
  char const * component_name, char const * grid_name,
  char const * field_name) {
 
  struct yac_couple_config_component const * component =
    yac_couple_config_get_component(couple_config, component_name);
  size_t const grid_idx = yac_couple_config_get_grid_idx(
    couple_config, grid_name);
 
  return yac_couple_config_component_get_field_timestep(
    component, grid_idx, field_name);
}
 
int yac_couple_config_get_field_role(
  struct yac_couple_config const * couple_config,
  char const * component_name, char const * grid_name,
  char const * field_name) {
 
  int field_role = YAC_EXCHANGE_TYPE_NONE;
 
  // Try to fine a matching component.
  size_t component_idx =
    yac_couple_config_get_component_idx_unsafe(couple_config, component_name);
 
  // If a matching component name was found, try to find a matching grid.
  size_t grid_idx = SIZE_MAX;
  if (component_idx != SIZE_MAX) {
    grid_idx = yac_couple_config_get_grid_idx_unsafe(couple_config, grid_name);
  }
 
  // If a matching grid name was found, try to find a matching field.
  size_t field_idx = SIZE_MAX;
  if (grid_idx != SIZE_MAX) {
    field_idx = yac_couple_config_get_field_idx_unsafe(
      couple_config, component_idx, grid_idx, field_name);
  }
 
  // If a matching field was found,
  // check all couples for a matching component/field index pair
  if (field_idx != SIZE_MAX) {
 
    size_t const nbr_couples = couple_config->num_couples;
    for(size_t couple_idx = 0;
        (couple_idx<nbr_couples) && (field_role == YAC_EXCHANGE_TYPE_NONE);
        ++couple_idx)
    {
      struct yac_couple_config_couple * couple =
        couple_config->couples + couple_idx;
 
      int const couple_has_component =
        yac_couple_config_couple_has_component(couple, component_idx);
 
      if (couple_has_component) {
 
        field_role =
          yac_couple_config_couple_get_field_role_from_field_idx(
            couple, component_idx, field_idx);
 
        // the couple config interface should prevent this case from happening
        YAC_ASSERT_F(
          field_role != YAC_EXCHANGE_TYPE_INVALID,
          "field cannot be source and target at the same time "
          "(component: \"%s\" grid: \"%s\" field: \"%s\" "
          "couple_idx: %zu)",
          component_name, grid_name, field_name, couple_idx);
      }
    }
  }
 
  return field_role;
}
 
int yac_couple_config_is_valid_field(
  struct yac_couple_config const * couple_config,
  size_t component_idx, size_t field_idx) {
 
  CHECK_COMPONENT_IDX();
 
  struct yac_couple_config_component const * component =
    couple_config->components + component_idx;
 
  return yac_couple_config_component_field_is_valid(component, field_idx);
}
 
struct yac_interp_stack_config * yac_couple_config_get_interp_stack(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_interp_stack(
    couple, field_couple_idx);
}
 
int yac_couple_config_get_mapping_on_source(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_mapping_on_source(
    couple, field_couple_idx);
}
 
int yac_couple_config_get_source_lag(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_source_lag(
    couple, field_couple_idx);
}
 
int yac_couple_config_get_target_lag(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_target_lag(
    couple, field_couple_idx);
}
 
char const * yac_couple_config_get_coupling_period(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_coupling_period(
    couple, field_couple_idx);
}
 
enum yac_reduction_type yac_couple_config_get_coupling_period_operation(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_coupling_period_operation(
    couple, field_couple_idx);
}
 
int yac_couple_config_get_enforce_write_weight_file(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_enforce_write_weight_file(
    couple, field_couple_idx);
}
 
char const * yac_couple_config_get_weight_file_name(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_weight_file_name(
    couple, field_couple_idx);
}
 
enum yac_weight_file_on_existing yac_couple_config_get_weight_file_on_existing(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_weight_file_on_existing(
    couple, field_couple_idx);
}
 
double yac_couple_config_get_scale_factor(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_scale_factor(
    couple, field_couple_idx);
}
 
double yac_couple_config_get_scale_summand(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_scale_summand(
    couple, field_couple_idx);
}
 
void yac_couple_config_get_src_mask_names(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx,
  char const * const ** mask_names, size_t * num_mask_names) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  yac_couple_config_couple_get_src_mask_names(
    couple, field_couple_idx, mask_names, num_mask_names);
}
 
char const * yac_couple_config_get_tgt_mask_name(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_tgt_mask_name(
    couple, field_couple_idx);
}
 
char const * yac_couple_config_get_yaxt_exchanger_name(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_yaxt_exchanger_name(
    couple, field_couple_idx);
}
 
struct yac_collection_selection const *
  yac_couple_config_get_collection_selection(
    struct yac_couple_config const * couple_config,
    size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_collection_selection(
    couple, field_couple_idx);
}
 
int yac_couple_config_get_use_raw_exchange(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  return yac_couple_config_couple_get_use_raw_exchange(
    couple, field_couple_idx);
}
 
void yac_couple_config_get_field_grid_names(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx,
  char const ** src_grid_name, char const ** tgt_grid_name) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  size_t src_component_idx =
    yac_couple_config_couple_get_source_component_idx(couple, field_couple_idx);
  size_t src_field_idx =
    yac_couple_config_couple_get_source_field_idx(couple, field_couple_idx);
 
  size_t tgt_component_idx =
    yac_couple_config_couple_get_target_component_idx(couple, field_couple_idx);
  size_t tgt_field_idx =
    yac_couple_config_couple_get_target_field_idx(couple, field_couple_idx);
 
  struct yac_couple_config_component const * src_component =
    couple_config->components + src_component_idx;
  struct yac_couple_config_component const * tgt_component =
    couple_config->components + tgt_component_idx;
 
  size_t src_grid_idx = yac_couple_config_component_get_field_grid_idx(
    src_component, src_field_idx);
  size_t tgt_grid_idx = yac_couple_config_component_get_field_grid_idx(
    tgt_component, tgt_field_idx);
 
  *src_grid_name = couple_config->grids[src_grid_idx].name;
  *tgt_grid_name = couple_config->grids[tgt_grid_idx].name;
}
 
void yac_couple_config_field_enable_frac_mask(
  struct yac_couple_config * couple_config,
  char const * comp_name, char const * grid_name, char const * field_name,
  double frac_mask_fallback_value) {
 
  YAC_ASSERT_F(
    YAC_FRAC_MASK_VALUE_IS_VALID(frac_mask_fallback_value),
    "\"%lf\" is not a valid fractional mask fallback value "
    "(component: \"%s\" grid: \"%s\" field \"%s\")",
    frac_mask_fallback_value, comp_name, grid_name, field_name);
 
  struct yac_couple_config_component * component =
    yac_couple_config_get_component(couple_config, comp_name);
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
 
  yac_couple_config_component_set_field_frac_mask_fallback_value(
    component, grid_idx, field_name, frac_mask_fallback_value);
}
 
double yac_couple_config_get_frac_mask_fallback_value(
  struct yac_couple_config const * couple_config,
  char const * component_name, char const * grid_name,
  char const * field_name) {
 
  struct yac_couple_config_component const * component =
    yac_couple_config_get_component(couple_config, component_name);
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
 
  double frac_mask_fallback_value =
    yac_couple_config_component_get_field_frac_mask_fallback_value(
      component, grid_idx, field_name);
 
  return frac_mask_fallback_value;
}
 
size_t yac_couple_config_get_field_collection_size(
  struct yac_couple_config const * couple_config,
  char const * component_name, char const * grid_name,
  char const * field_name) {
 
  struct yac_couple_config_component const * component =
    yac_couple_config_get_component(couple_config, component_name);
  size_t grid_idx = yac_couple_config_get_grid_idx(couple_config, grid_name);
 
  return yac_couple_config_component_get_field_collection_size(
    component, grid_idx, field_name);
}
 
void yac_couple_config_get_field_couple_component_names(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx,
  char const ** src_component_name, char const ** tgt_component_name) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  size_t src_component_idx =
    yac_couple_config_couple_get_source_component_idx(couple, field_couple_idx);
  size_t tgt_component_idx =
    yac_couple_config_couple_get_target_component_idx(couple, field_couple_idx);
 
  *src_component_name = couple_config->components[src_component_idx].name;
  *tgt_component_name = couple_config->components[tgt_component_idx].name;
}
 
void yac_couple_config_get_field_names(
  struct yac_couple_config const * couple_config,
    size_t couple_idx, size_t field_couple_idx,
    char const ** src_field_name, const char ** tgt_field_name) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  size_t src_component_idx =
    yac_couple_config_couple_get_source_component_idx(couple, field_couple_idx);
  size_t src_field_idx =
    yac_couple_config_couple_get_source_field_idx(couple, field_couple_idx);
 
  size_t tgt_component_idx =
    yac_couple_config_couple_get_target_component_idx(couple, field_couple_idx);
  size_t tgt_field_idx =
    yac_couple_config_couple_get_target_field_idx(couple, field_couple_idx);
 
  struct yac_couple_config_component const * src_component =
    couple_config->components + src_component_idx;
  struct yac_couple_config_component const * tgt_component =
    couple_config->components + tgt_component_idx;
 
  *src_field_name =
    yac_couple_config_component_get_field_name(src_component, src_field_idx);
  *tgt_field_name =
    yac_couple_config_component_get_field_name(tgt_component, tgt_field_idx);
}
 
char const * yac_couple_config_get_source_timestep(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  size_t source_component_idx =
    yac_couple_config_couple_get_source_component_idx(couple, field_couple_idx);
  size_t source_field_idx =
    yac_couple_config_couple_get_source_field_idx(couple, field_couple_idx);
 
  struct yac_couple_config_component const * source_component =
    couple_config->components + source_component_idx;
 
  char const * timestep = yac_couple_config_component_get_field_timestep_by_idx(
    source_component, source_field_idx);
 
  YAC_ASSERT_F(
    timestep,
    "no valid timestep defined (component: \"%s\" field \"%s\")",
    source_component->name,
    yac_couple_config_component_get_field_name(
      source_component, source_field_idx));
 
  return timestep;
}
 
char const * yac_couple_config_get_target_timestep(
  struct yac_couple_config const * couple_config,
  size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  size_t target_component_idx =
    yac_couple_config_couple_get_target_component_idx(couple, field_couple_idx);
  size_t target_field_idx =
    yac_couple_config_couple_get_target_field_idx(couple, field_couple_idx);
 
  struct yac_couple_config_component const * target_component =
    couple_config->components + target_component_idx;
 
  char const * timestep = yac_couple_config_component_get_field_timestep_by_idx(
    target_component, target_field_idx);
 
  YAC_ASSERT_F(
    timestep,
    "no valid timestep defined (component: \"%s\" field \"%s\")",
    target_component->name,
    yac_couple_config_component_get_field_name(target_component, target_field_idx));
 
  return timestep;
}
 
static char * normalise_utc_suffix(const char *src)
{
  YAC_ASSERT(src != NULL, "src is NULL");
 
  // allocate and copy string
  size_t const src_len = strlen(src);
  char * dst = strdup(src);
 
  char const suffix[] = "+00:00";
  enum {SUFFIX_LEN = sizeof(suffix) - 1 }; // excludes '\0'
 
  // if string has "+00:00" suffix
  if (src_len >= SUFFIX_LEN && strcmp(src + src_len - SUFFIX_LEN, suffix) == 0) {
    dst[src_len - SUFFIX_LEN] = 'Z';
    dst[src_len - SUFFIX_LEN + 1] = '\0';
  }
  return dst;
}
 
static struct _datetime * newDateTime_utc_patch(const char *str_new)
{
  // mtime does not support defining UTC with "+00:00" suffix, therefore, need
  // to replace it with "Z" here before calling newDateTime.
  // See https://gitlab.dkrz.de/icon-libraries/libmtime/-/work_items/46.
  char * const str_normalised = normalise_utc_suffix(str_new);
  struct _datetime * new = newDateTime(str_normalised);
  free(str_normalised);
  return new;
}
 
static void set_datetime(
  char const * type_datetime, struct _datetime ** old, char const * str_new) {
 
  if ((str_new == NULL) || (strlen(str_new) == 0)) return;
 
  YAC_ASSERT(
    yac_cget_calendar() != YAC_CALENDAR_NOT_SET,
    "calendar has not yet been set");
 
  struct _datetime * new = newDateTime_utc_patch(str_new);
 
  YAC_ASSERT_F(
    new != NULL, "failed to parse datetime \"%s\"", str_new);
 
  char old_datetime_buffer[MAX_DATETIME_STR_LEN],
       new_datetime_buffer[MAX_DATETIME_STR_LEN];
 
  YAC_ASSERT_F(
    (*old == NULL) || (equal_to == compareDatetime(*old, new)),
    "inconsistent %s datetime (old: \"%s\" new: \"%s\")", type_datetime,
    datetimeToString(*old, old_datetime_buffer),
    datetimeToString(new, new_datetime_buffer));
 
  deallocateDateTime(*old);
 
  *old = new;
}
 
void yac_couple_config_set_datetime(
  struct yac_couple_config * couple_config,
  char const * start, char const * end) {
 
  set_datetime("start", &(couple_config->start_datetime), start);
  set_datetime("end", &(couple_config->end_datetime), end);
}
 
char * yac_couple_config_get_start_datetime(
  struct yac_couple_config const * couple_config) {
 
  YAC_ASSERT(
    couple_config->start_datetime,  "start_datetime not yet defined");
 
  char datetime_buffer[MAX_DATETIME_STR_LEN];
 
  return
    xstrdup(datetimeToString(couple_config->start_datetime, datetime_buffer));
}
 
char * yac_couple_config_get_end_datetime(
  struct yac_couple_config const * couple_config) {
 
  YAC_ASSERT(couple_config->end_datetime, "end_datetime not yet defined");
 
  char datetime_buffer[MAX_DATETIME_STR_LEN];
 
  return
    xstrdup(datetimeToString(couple_config->end_datetime, datetime_buffer));
}
 
char const * yac_couple_config_get_grid_name(
  struct yac_couple_config const * couple_config, size_t grid_idx) {
 
  YAC_ASSERT_F(
    grid_idx < couple_config->num_grids, "Invalid grid idx %zu", grid_idx);
 
  return couple_config->grids[grid_idx].name;
}
 
int yac_couple_config_contains_grid_name(
  struct yac_couple_config const * couple_config, char const * grid_name) {
 
  int found_flag = 0;
 
  for (size_t grid_idx = 0;
       (grid_idx < couple_config->num_grids) && !found_flag; ++grid_idx) {
    found_flag = !strcmp(couple_config->grids[grid_idx].name, grid_name);
  }
  return found_flag;
}
 
static size_t yac_couple_config_add_couple_(
  struct yac_couple_config * couple_config,
  size_t src_comp_idx, size_t tgt_comp_idx) {
 
  struct yac_couple_config_couple search_couple;
  yac_couple_config_couple_init(&search_couple, src_comp_idx, tgt_comp_idx);
 
  struct yac_couple_config_couple * couple =
    yac_couple_config_couple_find(
      couple_config->num_couples, couple_config->couples, &search_couple);
 
  size_t couple_idx = SIZE_MAX;
  if (couple != NULL) {
    couple_idx = (size_t)(couple - couple_config->couples);
  } else {
    couple_idx =
      yac_couple_config_couples_append(
        couple_config, src_comp_idx, tgt_comp_idx);
  }
 
  YAC_ASSERT_F(
    couple_idx != SIZE_MAX,
    "failed to add couple (component indices: %zu, %zu)",
    src_comp_idx, tgt_comp_idx);
 
  return couple_idx;
}
 
void yac_couple_config_def_couple(
  struct yac_couple_config * couple_config,
  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_period, int time_reduction,
  struct yac_interp_stack_config * interp_stack, int src_lag, int tgt_lag,
  const char* weight_file_name, int weight_file_on_existing,
  int mapping_on_source, double scale_factor, double scale_summand,
  size_t num_src_mask_names, char const * const * src_mask_names,
  char const * tgt_mask_name, char const * yaxt_exchanger_name,
  struct yac_collection_selection const * collection_selection,
  int use_raw_exchange) {
 
  YAC_ASSERT(src_comp_name && src_comp_name[0] != '\0',
             "invalid parameter: src_comp_name");
  YAC_ASSERT(src_grid_name && src_grid_name[0] != '\0',
             "invalid parameter: src_grid_name");
  YAC_ASSERT(src_field_name && src_field_name[0] != '\0',
             "invalid parameter: src_field_name");
  YAC_ASSERT(tgt_comp_name && tgt_comp_name[0] != '\0',
             "invalid parameter: tgt_comp_name");
  YAC_ASSERT(tgt_grid_name && tgt_grid_name[0] != '\0',
             "invalid parameter: tgt_grid_name");
  YAC_ASSERT(tgt_field_name && tgt_field_name[0] != '\0',
             "invalid parameter: tgt_field_name");
  YAC_ASSERT(coupling_period && coupling_period[0] != '\0',
             "invalid parameter: coupling_period");
  YAC_ASSERT(
    (time_reduction == TIME_NONE) ||
    (time_reduction == TIME_ACCUMULATE) ||
    (time_reduction == TIME_AVERAGE) ||
    (time_reduction == TIME_MINIMUM) ||
    (time_reduction == TIME_MAXIMUM), "invalid parameter: time_reduction");
  YAC_ASSERT_F(isnormal(scale_factor), "\"%lf\" is not a valid scale factor",
    scale_factor);
  YAC_ASSERT_F(isnormal(scale_summand) || (scale_summand == 0.0),
    "\"%lf\" is not a valid scale summand", scale_summand);
  YAC_ASSERT(
    (collection_selection == NULL) ||
    (yac_collection_selection_get_collection_size(collection_selection) > 0),
    "invalid collection selection (size has to be > 0, if provided)");
  YAC_ASSERT(
    (weight_file_on_existing == YAC_WEIGHT_FILE_ERROR) ||
    (weight_file_on_existing == YAC_WEIGHT_FILE_KEEP) ||
    (weight_file_on_existing == YAC_WEIGHT_FILE_OVERWRITE),
    "invalid parameter: weight_file_on_existing");
  YAC_ASSERT_F(
    strcmp(src_comp_name, tgt_comp_name) ||
    strcmp(src_grid_name, tgt_grid_name) ||
    strcmp(src_field_name, tgt_field_name),
    "a field cannot have the role of source and target at the same time "
    "(comp_name: \"%s\" grid_name: \"%s\" field_name: \"%s\")",
    src_comp_name, src_grid_name, src_field_name);
 
  // get component indices
  size_t const src_comp_idx =
    yac_couple_config_add_component_(couple_config, src_comp_name);
  size_t const tgt_comp_idx =
    yac_couple_config_add_component_(couple_config, tgt_comp_name);
  size_t const src_grid_idx =
    yac_couple_config_add_grid_(couple_config, src_grid_name);
  size_t const tgt_grid_idx =
    yac_couple_config_add_grid_(couple_config, tgt_grid_name);
 
  // get current role of the field that we want to define as source here
  int const orig_src_field_role =
    yac_couple_config_get_field_role(couple_config, src_comp_name,
      src_grid_name, src_field_name);
 
  size_t const src_field_idx =
    yac_couple_config_add_component_field_(
      couple_config, src_comp_idx, src_grid_idx,
      src_field_name, NULL, SIZE_MAX);
 
  // check if definition of couple with given field as source is consistent
  // with previous definitions including this field
  YAC_ASSERT_F(
    orig_src_field_role == YAC_EXCHANGE_TYPE_SOURCE ||
    orig_src_field_role == YAC_EXCHANGE_TYPE_NONE,
    "Trying to define field as source which has already been defined as "
    "target in another couple previously. This is not allowed since fields "
    "must be either source or target. "
    "(component_name: \"%s\" grid_name: \"%s\" field_name: \"%s\")",
    src_comp_name, src_grid_name, src_field_name);
 
  // get current role of the field that we want to define as target here
  int const orig_tgt_field_role =
    yac_couple_config_get_field_role(couple_config, tgt_comp_name,
      tgt_grid_name, tgt_field_name);
 
  size_t const tgt_field_idx =
    yac_couple_config_add_component_field_(
      couple_config, tgt_comp_idx, tgt_grid_idx,
      tgt_field_name, NULL, SIZE_MAX);
 
  // check if definition of couple with given field as target is consistent
  // with previous definitions including this field
  if (orig_tgt_field_role == YAC_EXCHANGE_TYPE_TARGET) {
 
    // field may only be defined once as target. However, redefinition of an
    // already defined couple is allowed. So we need to check if the couple we
    // are trying to define is a redefinition.
    struct yac_couple_config_couple mask;
    yac_couple_config_couple_init(&mask, src_comp_idx, tgt_comp_idx);
    struct yac_couple_config_couple * couple =
      yac_couple_config_couple_find(
        couple_config->num_couples, couple_config->couples, &mask);
 
    YAC_ASSERT_F(
      couple != NULL,
      "Internal error. Trying to find couple for redefinition but it cannot be found. "
       "(src_component_name: \"%s\" src_grid_name: \"%s\" src_field_name: \"%s\") "
       "(tgt_component_name: \"%s\" tgt_grid_name: \"%s\" tgt_field_name: \"%s\")",
       src_comp_name, src_grid_name, src_field_name,
       tgt_comp_name, tgt_grid_name, tgt_field_name);
 
    int const is_redefinition =
      yac_couple_config_couple_has_field_couple(
        couple, src_comp_idx, src_field_idx, tgt_comp_idx, tgt_field_idx);
 
    char const * _src_comp_name;
    char const * _src_grid_name;
    char const * _src_field_name;
    yac_couple_config_get_field_source(couple_config,
      tgt_comp_name, tgt_grid_name, tgt_field_name,
      &_src_comp_name, &_src_grid_name, &_src_field_name
    );
    YAC_ASSERT_F(
      is_redefinition,
      "Trying to define field as target which has already been defined as "
      "target in another couple previously. This is not allowed. "
      "(tgt_component_name: \"%s\" tgt_grid_name: \"%s\" tgt_field_name: \"%s\") "
      "(new_src_component_name: \"%s\" new_src_grid_name: \"%s\" new_src_field_name: \"%s\")"
      "(existing_src_component_name: \"%s\" extisting_src_grid_name: \"%s\" existing_src_field_name: \"%s\")",
      tgt_comp_name, tgt_grid_name, tgt_field_name,
      src_comp_name, src_grid_name, src_field_name,
      _src_comp_name, _src_grid_name, _src_field_name
    );
  } else {
    // If field is not already defined as target it must be undefined in order
    // to legally define it as target.
    YAC_ASSERT_F(
      orig_tgt_field_role == YAC_EXCHANGE_TYPE_NONE,      // any target field must not be defined before
      "Trying to define field as target which has already been defined as "
      "source in another couple previously. This is not allowed since fields "
      "must be either source or target. "
      "(component_name: \"%s\" grid_name: \"%s\" field_name: \"%s\")",
      tgt_comp_name, tgt_grid_name, tgt_field_name
    );
  }
 
  // get or create raw couple
  size_t const couple_idx =
    yac_couple_config_add_couple_(
      couple_config, src_comp_idx, tgt_comp_idx);
 
  // append/merge field couple into (possibly new) couple
  struct yac_couple_config_couple * const couple =
    couple_config->couples + couple_idx;
  yac_couple_config_couple_append_or_merge_field_couple_from_definition(
    couple,
    src_comp_idx, src_field_idx, src_lag,
    tgt_comp_idx, tgt_field_idx, tgt_lag,
    coupling_period, time_reduction,
    interp_stack,
    mapping_on_source, weight_file_name,
    scale_factor, scale_summand,
    weight_file_on_existing,
    num_src_mask_names, src_mask_names,
    tgt_mask_name, yaxt_exchanger_name,
    collection_selection, use_raw_exchange);
}
 
static void couple_config_sync_datetime(
  char const * type_datetime, struct _datetime ** datetime, MPI_Comm comm) {
 
  // convert datetime to string
  char datetime_buffer[MAX_DATETIME_STR_LEN];
  char * str_datetime = datetimeToString(*datetime, datetime_buffer);
 
  // copy from static to dynamic memory
  if (str_datetime != NULL) str_datetime = xstrdup(str_datetime);
 
  // delete old datetime
  deallocateDateTime(*datetime);
 
  // synchronize datetime string across processes
  yac_couple_config_sync_string(type_datetime, &str_datetime, comm);
 
  // convert datetime string to _datetime struct
  *datetime = newDateTime(str_datetime);
 
  free(str_datetime);
}
 
static void couple_config_sync_time(
  struct yac_couple_config * couple_config, MPI_Comm comm) {
 
  couple_config_sync_calendar(comm);
  couple_config_sync_datetime(
    "start_datetime", &(couple_config->start_datetime), comm);
  couple_config_sync_datetime(
    "end_datetime", &(couple_config->end_datetime), comm);
}
 
void yac_couple_config_sync(
  struct yac_couple_config * couple_config, MPI_Comm comm,
  char const * output_ref){
 
  // sync time stuff
  couple_config_sync_time(couple_config, comm);
 
  yac_couple_config_config_outputs_merge(
    &couple_config->config_outputs, &couple_config->num_config_outputs, comm);
  yac_couple_config_grids_merge(
    &couple_config->grids, &couple_config->num_grids,
    couple_config->components, couple_config->num_components, comm);
  yac_couple_config_components_merge(
    &couple_config->components, &couple_config->num_components,
    couple_config->couples, couple_config->num_couples, comm);
  yac_couple_config_couples_merge(couple_config, comm);
 
  yac_couple_config_sync_flag_value(
    "missing_definition_is_fatal",
    &(couple_config->missing_definition_is_fatal), comm);
  yac_couple_config_sync_flag_value(
    "apply_coordinate_check",
    &(couple_config->apply_coordinate_check), comm);
  yac_couple_config_sync_flag_value(
    "coordinates_mismatch_is_fatal",
    &(couple_config->coordinates_mismatch_is_fatal), comm);
 
  struct yac_couple_config_config_output * config_output = NULL;
  if (output_ref != NULL)
    for (size_t i = 0; (i < couple_config->num_config_outputs) &&
         (config_output == NULL); ++i)
      if (!strcmp(output_ref, couple_config->config_outputs[i].ref))
        config_output = couple_config->config_outputs + i;
 
  if (config_output != NULL) {
 
    int rank;
    MPI_Comm_rank(comm, &rank);
 
    // rank 0 writes the coupling configuration to file
    if (rank == 0) {
 
      FILE * config_file = fopen(config_output->name, "w");
 
      YAC_ASSERT_F(
        config_file != NULL,
        "failed to create coupling configuration file \"%s\" (%s)",
        config_output->name, strerror(errno));
 
      YAC_ASSERT_F(
        (config_output->type == YAC_TEXT_FILETYPE_YAML) ||
        (config_output->type == YAC_TEXT_FILETYPE_JSON),
        "invalid coupling configuration filetype (type = %d)",
        config_output->type);
 
      int emit_flags;
      switch(config_output->type) {
        default:
        case(YAC_TEXT_FILETYPE_YAML):
          emit_flags = YAC_YAML_EMITTER_DEFAULT;
          break;
        case(YAC_TEXT_FILETYPE_JSON):
          emit_flags = YAC_YAML_EMITTER_JSON;
          break;
      }
 
      enum yac_couple_config_flag_value include_definitions =
        yac_couple_config_config_output_get_include_definitions(config_output);
      char * str_couple_config =
        yac_yaml_emit_coupling(
          couple_config, emit_flags, (int)include_definitions);
 
      fputs(str_couple_config, config_file);
      free(str_couple_config);
      fclose(config_file);
    }
    yac_mpi_call(MPI_Barrier(comm), comm);
  }
}
 
void yac_couple_config_set_config_output_filename(
  struct yac_couple_config * couple_config,
  char const * filename, enum yac_text_filetype filetype, char const * ref,
  int include_definitions) {
 
  yac_couple_config_config_output_append(
    &couple_config->config_outputs,
    &couple_config->num_config_outputs,
    filename, filetype, ref, include_definitions);
}
 
static void yac_couple_config_find_field_couple_with_target(
  struct yac_couple_config const * couple_config,
  char const * tgt_component_name, char const * tgt_grid_name,
  char const * tgt_field_name,
  size_t * result_couple_idx, size_t * result_field_couple_idx) {
 
  size_t const tgt_comp_idx =
    yac_couple_config_get_component_idx(couple_config, tgt_component_name);
 
  *result_couple_idx = SIZE_MAX;
  *result_field_couple_idx = SIZE_MAX;
 
  for (size_t couple_idx = 0;
       couple_idx < couple_config->num_couples; ++couple_idx) {
    struct yac_couple_config_couple const * couple =
      couple_config->couples + couple_idx;
    if (!yac_couple_config_couple_has_component(
          couple, tgt_comp_idx))
      continue;
    size_t fc_idx =
      yac_couple_config_couple_find_field_couple_with_target(
        couple, couple_config,
        tgt_field_name, tgt_grid_name, tgt_component_name);
    if (fc_idx != SIZE_MAX) {
      YAC_ASSERT_F(
        *result_couple_idx == SIZE_MAX,
        "multiple couples with the same target "
        "(component: \"%s\" grid: \"%s\" field: \"%s\")",
        tgt_component_name, tgt_grid_name,
        tgt_field_name);
      *result_couple_idx = couple_idx;
      *result_field_couple_idx = fc_idx;
    }
  }
}
 
void yac_couple_config_get_field_source(
  struct yac_couple_config const * couple_config,
  char const * tgt_component_name, char const * tgt_grid_name,
  char const * tgt_field_name, char const ** src_component_name,
  char const ** src_grid_name, char const ** src_field_name) {
 
  size_t couple_idx, field_couple_idx;
  yac_couple_config_find_field_couple_with_target(
    couple_config, tgt_component_name, tgt_grid_name,
    tgt_field_name, &couple_idx, &field_couple_idx);
 
  YAC_ASSERT_F(
    couple_idx != SIZE_MAX,
    "provided field is not defined as a target in any coupling "
    "(target component: \"%s\" target grid: \"%s\" target field: \"%s\")",
    tgt_component_name, tgt_grid_name, tgt_field_name);
 
  struct yac_couple_config_couple const * couple =
    couple_config->couples + couple_idx;
 
  size_t src_component_idx =
    yac_couple_config_couple_get_source_component_idx(couple, field_couple_idx);
  size_t src_field_idx =
    yac_couple_config_couple_get_source_field_idx(couple, field_couple_idx);
 
  struct yac_couple_config_component const * src_component =
    couple_config->components + src_component_idx;
 
  size_t src_grid_idx =
    yac_couple_config_component_get_field_grid_idx(
      src_component, src_field_idx);
 
  *src_component_name = src_component->name;
  *src_grid_name = couple_config->grids[src_grid_idx].name;
  *src_field_name =
    yac_couple_config_component_get_field_name(src_component, src_field_idx);
}
 
struct yac_interpolation_gen_config *
  yac_couple_config_get_interpolation_gen_config(
    struct yac_couple_config * couple_config,
    size_t couple_idx, size_t field_couple_idx) {
 
  CHECK_COUPLE_IDX();
 
  struct yac_couple_config_couple * couple =
    couple_config->couples + couple_idx;
 
  size_t src_comp_idx =
    yac_couple_config_couple_get_source_component_idx(couple, field_couple_idx);
  size_t src_field_idx =
    yac_couple_config_couple_get_source_field_idx(couple, field_couple_idx);
  size_t tgt_comp_idx =
    yac_couple_config_couple_get_target_component_idx(couple, field_couple_idx);
  size_t tgt_field_idx =
    yac_couple_config_couple_get_target_field_idx(couple, field_couple_idx);
 
  struct yac_couple_config_component const * src_comp =
    couple_config->components + src_comp_idx;
  struct yac_couple_config_component const * tgt_comp =
    couple_config->components + tgt_comp_idx;
 
  size_t src_grid_idx =
    yac_couple_config_component_get_field_grid_idx(
      src_comp, src_field_idx);
  size_t tgt_grid_idx =
    yac_couple_config_component_get_field_grid_idx(
      tgt_comp, tgt_field_idx);
 
  char const * src_comp_name = src_comp->name;
  char const * src_grid_name =
    couple_config->grids[src_grid_idx].name;
  char const * src_field_name =
    yac_couple_config_component_get_field_name(src_comp, src_field_idx);
 
  char const * tgt_comp_name = tgt_comp->name;
  char const * tgt_grid_name =
    couple_config->grids[tgt_grid_idx].name;
  char const * tgt_field_name =
    yac_couple_config_component_get_field_name(tgt_comp, tgt_field_idx);
 
  // generate new interpolation generation configuration object
  struct yac_interpolation_gen_config * interp_gen_config =
    yac_interpolation_gen_config_new();
 
  // set reorder type
  int const is_mapping_on_source =
    yac_couple_config_couple_get_mapping_on_source(
      couple, field_couple_idx);
  yac_interpolation_gen_config_set_reorder(
    interp_gen_config,
    is_mapping_on_source ? YAC_MAPPING_ON_SRC : YAC_MAPPING_ON_TGT);
 
  // set fractional masking fallback value
  double frac_mask_fallback_value =
    yac_couple_config_component_get_field_frac_mask_fallback_value_by_idx(
      src_comp, src_field_idx);
  // if it is not NO_VALUE
  if (YAC_FRAC_MASK_VALUE_IS_VALID(frac_mask_fallback_value)) {
    yac_interpolation_gen_config_set_frac_mask_fallback_value(
      interp_gen_config, frac_mask_fallback_value);
  }
 
  // set scaling factor, scaling summand, and yaxt exchanger name
  double scale_factor =
    yac_couple_config_couple_get_scale_factor(
      couple, field_couple_idx);
  double scale_summand =
    yac_couple_config_couple_get_scale_summand(
      couple, field_couple_idx);
  char const * yaxt_exchanger_name =
    yac_couple_config_couple_get_yaxt_exchanger_name(
      couple, field_couple_idx);
  yac_interpolation_gen_config_set_scaling_factor(
    interp_gen_config, scale_factor);
  yac_interpolation_gen_config_set_scaling_summand(
    interp_gen_config, scale_summand);
  yac_interpolation_gen_config_set_yaxt_exchanger_name(
    interp_gen_config, yaxt_exchanger_name);
 
  // get source and target field collection size
  size_t src_collection_size =
    yac_couple_config_component_get_field_collection_size_by_idx(
      src_comp, src_field_idx);
  size_t tgt_collection_size =
    yac_couple_config_component_get_field_collection_size_by_idx(
      tgt_comp, tgt_field_idx);
 
  // if the user provided a collection selection for the couple
  struct yac_collection_selection const * collection_selection =
    yac_couple_config_couple_get_collection_selection(
      couple, field_couple_idx);
  if (collection_selection != NULL) {
 
    YAC_ASSERT_F(
      yac_collection_selection_get_collection_size(
        collection_selection) == tgt_collection_size,
      "target field collection size does not match size of provided "
      "collection selection: \n"
      "  source:\n"
      "    component name:  \"%s\"\n"
      "    grid name:       \"%s\"\n"
      "    field name:      \"%s\"\n"
      "    collection_size: %zu\n"
      "  target:\n"
      "    component name:  \"%s\"\n"
      "    grid name:       \"%s\"\n"
      "    field name:      \"%s\"\n"
      "    collection_size: %zu\n"
      "  collection selection:\n"
      "    size:            %zu\n"
      "    max_index:       %zu\n",
      src_comp_name, src_grid_name, src_field_name, src_collection_size,
      tgt_comp_name, tgt_grid_name, tgt_field_name, tgt_collection_size,
      yac_collection_selection_get_collection_size(collection_selection),
      yac_collection_selection_get_max_index(collection_selection));
    YAC_ASSERT_F(
      yac_collection_selection_get_max_index(
        collection_selection) < src_collection_size,
      "maximum index of provided collection selection exceeds source "
      "field collection size: \n"
      "  source:\n"
      "    component name:  \"%s\"\n"
      "    grid name:       \"%s\"\n"
      "    field name:      \"%s\"\n"
      "    collection_size: %zu\n"
      "  target:\n"
      "    component name:  \"%s\"\n"
      "    grid name:       \"%s\"\n"
      "    field name:      \"%s\"\n"
      "    collection_size: %zu\n"
      "  collection selection:\n"
      "    size:            %zu\n"
      "    max_index:       %zu\n",
      src_comp_name, src_grid_name, src_field_name, src_collection_size,
      tgt_comp_name, tgt_grid_name, tgt_field_name, tgt_collection_size,
      yac_collection_selection_get_collection_size(collection_selection),
      yac_collection_selection_get_max_index(collection_selection));
 
    yac_interpolation_gen_config_set_collection_selection(
      interp_gen_config, collection_selection);
 
  } else { // no collection selection was provided by the user
    YAC_ASSERT_F(
      src_collection_size == tgt_collection_size,
      "collection sizes do not match for coupled fields (%zu != %zu): \n"
      "  source:\n"
      "    component name: \"%s\"\n"
      "    grid name:      \"%s\"\n"
      "    field name:     \"%s\"\n"
      "  target:\n"
      "    component name: \"%s\"\n"
      "    grid name:      \"%s\"\n"
      "    field name:     \"%s\"\n",
      src_collection_size, tgt_collection_size,
      src_comp_name, src_grid_name, src_field_name,
      tgt_comp_name, tgt_grid_name, tgt_field_name);
 
    yac_interpolation_gen_config_set_collection_size(
      interp_gen_config, src_collection_size);
  }
 
  return interp_gen_config;
}