Introduction

During the run of a coupled setup it can happen that field masks are changing (for example due to rising or falling sea levels). Unfortunatly, weights are only computed in the initialisation phase of the coupler. In addition, this is a time consuming process. Hence, reinitialisation of the coupler after each change of a mask is not a viable option, most of the time.

Instead of recomputation of all weights, it is also possible to provide an additional mask to the put operation. This mask can be used at each exchange step to adjust the weights, which were computed in the initialisation phase.

Description

When using dynamic fractional masking, the user has to provide masking values for all source points in an exchange. The masking values have to be in the range $0.0 \leq f_i \leq 1.0$ .

In an exchange all source field values are first scaled by the fractional mask values. These scaled values are multiplied by the interpolation weights to compute preliminary target field values. Afterwards each preliminary target field value is divided by the frac-weighted sum of the interpolation weights and multiplied by the plain sum of the interpolation weights. This way the target field values are adjusted to reflect the fact that the source field values were scaled down by the fractional mask values. This is necessary to ensure that the target field values are not scaled down by the fractional mask values as well, which would be undesirable in most cases.

If is a target field value, $\vec{F_s}$ are the associated source field values and $\vec{w}$ the associated weights, then without fractional masking the target field value is computed as follows:

$F_t=\vec{F_s}\cdot\vec{w}$

If $\vec{f}$ are the associated fractional mask values and is the user defined fallback value, then with fractional masking YAC will compute the target field value as follows:

$\begin{split} f' & = \vec{f}\cdot\vec{w} \\ s & = \sum_i w_i \\ F'_t & = (\vec{F_s}\odot\vec{f})\cdot\vec{w} \\ F_t & = \begin{cases} F'_t / f' \cdot s & f' \not = 0 \\ F_f & f' = 0 \end{cases} \end{split}$

where $s = \sum_i w_i$ is the sum of all interpolation weights for the target point.

When all fractional mask values associated with the target point are , and the formula reduces to $F_t = F'_t / s \cdot s = F'_t = \vec{F_s}\cdot\vec{w}$ , i.e. the result is identical to the case without fractional masking, regardless of whether the weights sum to .

Example

In the following example a target point (blue dot) is interpolated by the average ( $\vec{w}=\left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right )$ ) of three corners (red dots) of a triangle that contains it. The source field values assigned to these three corners are:
$\vec{F_s}=\left ( 6, 1, 3 \right )$

Without fractional mask	With fractional mask: $\vec{f}=\left ( 1, 1, 1 \right )$	With fractional mask: $\vec{f}=\left ( 1, \frac{1}{2}, 0 \right )$
$\begin{split} F_t & = \left ( 6, 1, 3 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = 3.\bar{3} \\ \end{split}$	$\begin{split} f' & = \left ( 1, 1, 1 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) = 1 \\ s & = \frac{1}{3}+\frac{1}{3}+\frac{1}{3} = 1 \\ F'_t & = \left (\left ( 6, 1, 3 \right )\odot \left ( 1, 1, 1 \right ) \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \left ( 6, 1, 3 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \frac{10}{3} \\ F_t & = \frac{10}{3} / 1 \cdot 1 \\ & = 3.\bar{3} \\ \end{split}$	$\begin{split} f' & = \left ( 1, \frac{1}{2}, 0 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) = \frac{1}{2} \\ s & = \frac{1}{3}+\frac{1}{3}+\frac{1}{3} = 1 \\ F'_t & = \left (\left ( 6, 1, 3 \right )\odot \left ( 1, \frac{1}{2}, 0 \right ) \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \left ( 6, \frac{1}{2}, 0 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \frac{13}{6} \\ F_t & = \frac{13}{6}/\frac{1}{2} \cdot 1 \\ & = 4.\bar{3} \end{split}$

Without fractional mask

With fractional mask:
$\vec{f}=\left ( 1, 1, 1 \right )$

With fractional mask:
$\vec{f}=\left ( 1, \frac{1}{2}, 0 \right )$

$\begin{split} F_t & = \left ( 6, 1, 3 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = 3.\bar{3} \\ \end{split}$

$\begin{split} f' & = \left ( 1, 1, 1 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) = 1 \\ s & = \frac{1}{3}+\frac{1}{3}+\frac{1}{3} = 1 \\ F'_t & = \left (\left ( 6, 1, 3 \right )\odot \left ( 1, 1, 1 \right ) \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \left ( 6, 1, 3 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \frac{10}{3} \\ F_t & = \frac{10}{3} / 1 \cdot 1 \\ & = 3.\bar{3} \\ \end{split}$

$\begin{split} f' & = \left ( 1, \frac{1}{2}, 0 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) = \frac{1}{2} \\ s & = \frac{1}{3}+\frac{1}{3}+\frac{1}{3} = 1 \\ F'_t & = \left (\left ( 6, 1, 3 \right )\odot \left ( 1, \frac{1}{2}, 0 \right ) \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \left ( 6, \frac{1}{2}, 0 \right )\cdot \left ( \frac{1}{3}, \frac{1}{3}, \frac{1}{3} \right ) \\ & = \frac{13}{6} \\ F_t & = \frac{13}{6}/\frac{1}{2} \cdot 1 \\ & = 4.\bar{3} \end{split}$

Combination with time aggregation

When dynamic fractional masking is combined with a time aggregation scheme (i.e. the source field is provided at a finer time resolution than the coupling timestep; see time_reduction option in YAML configuration file), YAC independently accumulates the masked source field values $\vec{F_s}\odot\vec{f}$ and the fractional mask values $\vec{f}$ over all source timesteps. At the actual coupling timestep the configured aggregation operation (accumulate, average, minimum, or maximum) is applied to both accumulators separately. The resulting aggregated quantities are then used in place of $\vec{F_s}\odot\vec{f}$ and $\vec{f}$ in the formula above to compute the target field values.

This approach differs from first computing a target field value at every source timestep and then aggregating those target values. The two approaches are generally not equivalent when the fractional mask changes between source timesteps.

YAC's approach is chosen because communication between source and target components is only required once per coupling timestep, making it more efficient.

Usage in YAC

In order to use dynamic fractional masking, the user has to explicitly enable it (see Enabling dynamic fractional masking). This is only possible for fields that have already been defined (see Definition of Coupling Fields).

If a field has been enabled for dynamic fractional masking, the user must provide a mask for all field values in every exchange where the field is used as a source (see yac_cput_frac, yac_cput_frac_, yac_cput_frac_ptr_, yac_cexchange_frac, yac_cexchange_frac_, yac_cexchange_frac_ptr_, yac_fput_frac_*, and yac_fexchange_frac_*).

Acknowledgement

The implementation of dynamic fractional masking in YAC is based on the work of the same feature in OASIS3-MCT 6.0.