# mom_coms module reference¶

Interfaces to non-domain-oriented communication subroutines, including the MOM6 reproducing sums facility.

More…

## Data Types¶

 efp_type The Extended Fixed Point (EFP) type provides a public interface for doing sums and taking differences with this type.

## Functions/Subroutines¶

 reproducing_efp_sum_2d() This subroutine uses a conversion to an integer representation of real numbers to give an order-invariant sum of distributed 2-D arrays that reproduces across domain decomposition, with the result returned as an extended fixed point type that can be converted back to a real number using EFP_to_real. reproducing_sum_2d() This subroutine uses a conversion to an integer representation of real numbers to give an order-invariant sum of distributed 2-D arrays that reproduces across domain decomposition. reproducing_sum_3d() This subroutine uses a conversion to an integer representation of real numbers to give an order-invariant sum of distributed 3-D arrays that reproduces across domain decomposition. real_to_ints() Convert a real number into the array of integers constitute its extended-fixed-point representation. ints_to_real() Convert the array of integers that constitute an extended-fixed-point representation into a real number. increment_ints() Increment an array of integers that constitutes an extended-fixed-point representation with a another EFP number. increment_ints_faster() Increment an EFP number with a real number without doing any carrying of of overflows and using only minimal error checking. carry_overflow() This subroutine handles carrying of the overflow. regularize_ints() This subroutine carries the overflow, and then makes sure that all integers are of the same sign as the overall value. query_efp_overflow_error() Returns the status of the module’s error flag. reset_efp_overflow_error() Reset the module’s error flag to false. efp_plus() Add two extended-fixed-point numbers. efp_minus() Subract one extended-fixed-point number from another. efp_assign() Copy one extended-fixed-point number into another. efp_to_real() Return the real number that an extended-fixed-point number corresponds with. efp_real_diff() Take the difference between two extended-fixed-point numbers (EFP1 - EFP2) and return the result as a real number. real_to_efp() Return the extended-fixed-point number that a real number corresponds with. efp_list_sum_across_pes() This subroutine does a sum across PEs of a list of EFP variables, returning the sums in place, with all overflows carried. efp_val_sum_across_pes() This subroutine does a sum across PEs of an EFP variable, returning the sums in place, with all overflows carried.

## Detailed Description¶

Interfaces to non-domain-oriented communication subroutines, including the MOM6 reproducing sums facility.

## Type Documentation¶

type mom_coms/efp_type

The Extended Fixed Point (EFP) type provides a public interface for doing sums and taking differences with this type.

Type fields
• % v [integer(kind=8)( ni )] :: The value in this type.

## Function/Subroutine Documentation¶

function mom_coms/reproducing_efp_sum_2d(array, isr, ier, jsr, jer, overflow_check, err, only_on_PE) [type(efp_type)]

This subroutine uses a conversion to an integer representation of real numbers to give an order-invariant sum of distributed 2-D arrays that reproduces across domain decomposition, with the result returned as an extended fixed point type that can be converted back to a real number using EFP_to_real. This technique is described in Hallberg & Adcroft, 2014, Parallel Computing, doi:10.1016/j.parco.2014.04.007.

Parameters
• array :: [in] The array to be summed

• isr :: [in] The starting i-index of the sum, noting that the array indices starts at 1

• ier :: [in] The ending i-index of the sum, noting that the array indices starts at 1

• jsr :: [in] The starting j-index of the sum, noting that the array indices starts at 1

• jer :: [in] The ending j-index of the sum, noting that the array indices starts at 1

• overflow_check :: [in] If present and false, disable checking for overflows in incremental results. This can speed up calculations if the number of values being summed is small enough

• err :: [out] If present, return an error code instead of triggering any fatal errors directly from this routine.

• only_on_pe :: [in] If present and true, do not do the sum across processors, only reporting the local sum

Return

undefined :: The result in extended fixed point format

Call to

carry_overflow i_pr increment_ints increment_ints_faster max_count_prec mom_error_handler::mom_error nan_error ni overflow_error pr real_to_ints regularize_ints

Called from

reproducing_sum_2d

function mom_coms/reproducing_sum_2d(array, isr, ier, jsr, jer, EFP_sum, reproducing, overflow_check, err, only_on_PE) [real]

This subroutine uses a conversion to an integer representation of real numbers to give an order-invariant sum of distributed 2-D arrays that reproduces across domain decomposition. This technique is described in Hallberg & Adcroft, 2014, Parallel Computing, doi:10.1016/j.parco.2014.04.007.

Parameters
• array :: [in] The array to be summed

• isr :: [in] The starting i-index of the sum, noting that the array indices starts at 1

• ier :: [in] The ending i-index of the sum, noting that the array indices starts at 1

• jsr :: [in] The starting j-index of the sum, noting that the array indices starts at 1

• jer :: [in] The ending j-index of the sum, noting that the array indices starts at 1

• efp_sum :: [out] The result in extended fixed point format

• reproducing :: [in] If present and false, do the sum using the naive non-reproducing approach

• overflow_check :: [in] If present and false, disable checking for overflows in incremental results. This can speed up calculations if the number of values being summed is small enough

• err :: [out] If present, return an error code instead of triggering any fatal errors directly from this routine.

• only_on_pe :: [in] If present and true, do not do the sum across processors, only reporting the local sum

Return

undefined :: Result

Call to

debug ints_to_real max_count_prec mom_error_handler::mom_error mom_error_handler::mom_mesg ni overflow_error real_to_ints reproducing_efp_sum_2d

function mom_coms/reproducing_sum_3d(array, isr, ier, jsr, jer, sums, EFP_sum, EFP_lay_sums, err, only_on_PE) [real]

This subroutine uses a conversion to an integer representation of real numbers to give an order-invariant sum of distributed 3-D arrays that reproduces across domain decomposition. This technique is described in Hallberg & Adcroft, 2014, Parallel Computing, doi:10.1016/j.parco.2014.04.007.

Parameters
• array :: [in] The array to be summed

• isr :: [in] The starting i-index of the sum, noting that the array indices starts at 1

• ier :: [in] The ending i-index of the sum, noting that the array indices starts at 1

• jsr :: [in] The starting j-index of the sum, noting that the array indices starts at 1

• jer :: [in] The ending j-index of the sum, noting that the array indices starts at 1

• sums :: [out] The sums by vertical layer

• efp_sum :: [out] The result in extended fixed point format

• efp_lay_sums :: [out] The sums by vertical layer in EFP format

• err :: [out] If present, return an error code instead of triggering any fatal errors directly from this routine.

• only_on_pe :: [in] If present and true, do not do the sum across processors, only reporting the local sum

Return

undefined :: Result

Call to

carry_overflow debug increment_ints increment_ints_faster ints_to_real max_count_prec mom_error_handler::mom_error mom_error_handler::mom_mesg nan_error ni overflow_error pr real_to_ints regularize_ints

function mom_coms/real_to_ints(r, prec_error, overflow) [integer(kind=8)]

Convert a real number into the array of integers constitute its extended-fixed-point representation.

Parameters
• r :: [in] The real number being converted

• prec_error :: [in] The PE-count dependent precision of the integers that is safe from overflows during global sums. This will be larger than the compile-time precision parameter, and is used to detect overflows.

• overflow :: [inout] Returns true if the conversion is being done on a value that is too large to be represented

Call to

i_pr mom_error_handler::mom_error nan_error ni pr prec

Called from
function mom_coms/ints_to_real(ints) [real]

Convert the array of integers that constitute an extended-fixed-point representation into a real number.

Parameters

ints :: [in] The array of EFP integers

Call to

ni pr

Called from
subroutine mom_coms/increment_ints(int_sum, int2, prec_error)

Increment an array of integers that constitutes an extended-fixed-point representation with a another EFP number.

Parameters
• int_sum :: [inout] The array of EFP integers being incremented

• int2 :: [in] The array of EFP integers being added

• prec_error :: [in] The PE-count dependent precision of the integers that is safe from overflows during global sums. This will be larger than the compile-time precision parameter, and is used to detect overflows.

Call to

ni overflow_error prec

Called from
subroutine mom_coms/increment_ints_faster(int_sum, r, max_mag_term)

Increment an EFP number with a real number without doing any carrying of of overflows and using only minimal error checking.

Parameters
• int_sum :: [inout] The array of EFP integers being incremented

• r :: [in] The real number being added.

• max_mag_term :: [inout] A running maximum magnitude of the r’s.

Call to

i_pr max_efp_float nan_error ni overflow_error pr

Called from
subroutine mom_coms/carry_overflow(int_sum, prec_error)

This subroutine handles carrying of the overflow.

Parameters
• int_sum :: [inout] The array of EFP integers being modified by carries, but without changing value.

• prec_error :: [in] The PE-count dependent precision of the integers that is safe from overflows during global sums. This will be larger than the compile-time precision parameter, and is used to detect overflows.

Call to

i_prec ni overflow_error prec

Called from
subroutine mom_coms/regularize_ints(int_sum)

This subroutine carries the overflow, and then makes sure that all integers are of the same sign as the overall value.

Parameters

int_sum :: [inout] The array of integers being modified to take a

Call to

i_prec ni prec

Called from
function mom_coms/query_efp_overflow_error() [logical]

Returns the status of the module’s error flag.

Call to

overflow_error

Called from
subroutine mom_coms/reset_efp_overflow_error()

Reset the module’s error flag to false.

Call to

overflow_error

Called from
function mom_coms/efp_plus(EFP1, EFP2) [type(efp_type)]

Return

undefined :: The result in extended fixed point format

Parameters
• efp1 :: [in] The first extended fixed point number

• efp2 :: [in] The second extended fixed point number

Call to

increment_ints

function mom_coms/efp_minus(EFP1, EFP2) [type(efp_type)]

Subract one extended-fixed-point number from another.

Return

undefined :: The result in extended fixed point format

Parameters
• efp1 :: [in] The first extended fixed point number

• efp2 :: [in] The extended fixed point number being subtracted from the first extended fixed point number

Call to

increment_ints ni

subroutine mom_coms/efp_assign(EFP1, EFP2)

Copy one extended-fixed-point number into another.

Parameters
• efp1 :: [out] The recipient extended fixed point number

• efp2 :: [in] The source extended fixed point number

Call to

ni

function mom_coms/efp_to_real(EFP1) [real]

Return the real number that an extended-fixed-point number corresponds with.

Parameters

efp1 :: [inout] The extended fixed point number being converted

Call to
Called from
function mom_coms/efp_real_diff(EFP1, EFP2) [real]

Take the difference between two extended-fixed-point numbers (EFP1 - EFP2) and return the result as a real number.

Parameters
• efp1 :: [in] The first extended fixed point number

• efp2 :: [in] The extended fixed point number being subtracted from the first extended fixed point number

Return

undefined :: The real result

Call to

efp_to_real

function mom_coms/real_to_efp(val, overflow) [type(efp_type)]

Return the extended-fixed-point number that a real number corresponds with.

Parameters
• val :: [in] The real number being converted

• overflow :: [inout] Returns true if the conversion is being done on a value that is too large to be represented

Call to
Called from
subroutine mom_coms/efp_list_sum_across_pes(EFPs, nval, errors)

This subroutine does a sum across PEs of a list of EFP variables, returning the sums in place, with all overflows carried.

Parameters
• efps :: [inout] The list of extended fixed point numbers

• nval :: [in] The number of values being summed.

• errors :: [out] A list of error flags for each sum

Call to

carry_overflow efp_to_real max_count_prec mom_error_handler::mom_error ni overflow_error

subroutine mom_coms/efp_val_sum_across_pes(EFP, error)

This subroutine does a sum across PEs of an EFP variable, returning the sums in place, with all overflows carried.

Parameters
• efp :: [inout] The extended fixed point numbers being summed across PEs.

• error :: [out] An error flag for this sum

Call to

carry_overflow efp_to_real max_count_prec mom_error_handler::mom_error ni overflow_error