mom_coms module reference¶

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

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=int64)( 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, unscale) [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 in arbitrary units [a], or in arbitrary scaled units [A ~> a] if unscale is present
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
unscale :: [in] A factor that is used to undo scaling of array before it is summed, often to compensate for the scaling in [a A-1 ~> 1]

Return:

undefined :: The result in extended fixed point format

Called from:

mom_coms::reproducing_sum::reproducing_sum_2d

function mom_coms/reproducing_sum_2d(array, isr, ier, jsr, jer, EFP_sum, reproducing, overflow_check, err, only_on_PE, unscale) [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 in arbitrary units [a], or in arbitrary scaled units [A ~> a] if unscale is present
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
unscale :: [in] A factor that is used to undo scaling of array before it is summed, often to compensate for the scaling in [a A-1 ~> 1]

Return:

undefined :: The sum of the values in array in the same arbitrary units as array [a] or [A ~> a]

function mom_coms/reproducing_sum_3d(array, isr, ier, jsr, jer, sums, EFP_sum, EFP_lay_sums, err, only_on_PE, unscale) [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 in arbitrary units [a], or in arbitrary scaled units [A ~> a] if unscale is present
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 in the same abitrary units as array [a] or [A ~> a]
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
unscale :: [in] A factor that is used to undo scaling of array before it is summed, often to compensate for the scaling in [a A-1 ~> 1]

Return:

undefined :: The sum of the values in array in the same arbitrary units as array [a] or [A ~> a]

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

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

Parameters:

r :: [in] The real number being converted in arbitrary units [a]
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:

real_to_efp mom_coms::reproducing_sum_efp::reproducing_efp_sum_2d mom_coms::reproducing_sum::reproducing_sum_2d mom_coms::reproducing_sum::reproducing_sum_3d

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:: efp_to_real mom_coms::reproducing_sum::reproducing_sum_2d mom_coms::reproducing_sum::reproducing_sum_3d

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:

mom_coms::operator(-)::efp_minus mom_coms::operator(+)::efp_plus mom_coms::reproducing_sum_efp::reproducing_efp_sum_2d mom_coms::reproducing_sum::reproducing_sum_3d

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 in arbitrary units [a]
max_mag_term :: [inout] A running maximum magnitude of the r’s in arbitrary units [a]

Call to:

i_pr max_efp_float nan_error ni overflow_error pr

Called from:

mom_coms::reproducing_sum_efp::reproducing_efp_sum_2d mom_coms::reproducing_sum::reproducing_sum_3d

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:

mom_coms::efp_sum_across_pes::efp_list_sum_across_pes mom_coms::efp_sum_across_pes::efp_val_sum_across_pes mom_coms::reproducing_sum_efp::reproducing_efp_sum_2d mom_coms::reproducing_sum::reproducing_sum_3d

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:: efp_to_real mom_coms::reproducing_sum_efp::reproducing_efp_sum_2d mom_coms::reproducing_sum::reproducing_sum_3d

function mom_coms/query_efp_overflow_error() [logical]¶

Returns the status of the module’s error flag.

Call to:: overflow_error

subroutine mom_coms/reset_efp_overflow_error()¶

Reset the module’s error flag to false.

Call to:: overflow_error

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

Add two extended-fixed-point numbers.

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

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

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

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
Return:: undefined :: The real version of the number in abitrary units [a]
Call to:: ints_to_real regularize_ints
Called from:: mom_tracer_flow_control::call_tracer_stocks mom_coms::efp_sum_across_pes::efp_list_sum_across_pes efp_real_diff mom_coms::efp_sum_across_pes::efp_val_sum_across_pes mom_energetic_pbl::energetic_pbl_end

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 in arbitrary units [a]

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 in arbitrary units [a]
overflow :: [inout] Returns true if the conversion is being done on a value that is too large to be represented

Call to:

mom_error_handler::mom_error real_to_ints

Called from:

mom_energetic_pbl::energetic_pbl mom_energetic_pbl::energetic_pbl_init mom_generic_tracer::mom_generic_tracer_stock

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

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