mom_coms module reference¶
Interfaces to non-domain-oriented communication subroutines, including the MOM6 reproducing sums facility.
Data Types¶
The Extended Fixed Point (EFP) type provides a public interface for doing sums and taking differences with this type. |
Functions/Subroutines¶
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 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 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. |
|
Convert a real number into the array of integers constitute its extended-fixed-point representation. |
|
Convert the array of integers that constitute an extended-fixed-point representation into a real number. |
|
Increment an array of integers that constitutes an extended-fixed-point representation with a another EFP number. |
|
Increment an EFP number with a real number without doing any carrying of of overflows and using only minimal error checking. |
|
This subroutine handles carrying of the overflow. |
|
This subroutine carries the overflow, and then makes sure that all integers are of the same sign as the overall value. |
|
Returns the status of the module’s error flag. |
|
Reset the module’s error flag to false. |
|
Add two extended-fixed-point numbers. |
|
Subract one extended-fixed-point number from another. |
|
Copy one extended-fixed-point number into another. |
|
Return the real number that an extended-fixed-point number corresponds with. |
|
Take the difference between two extended-fixed-point numbers (EFP1 - EFP2) and return the result as a real number. |
|
Return the extended-fixed-point number that a real number corresponds with. |
|
This subroutine does a sum across PEs of a list of EFP variables, returning the sums in place, with all overflows carried. |
|
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
- Called from:
-
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
-
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
-
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:
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.
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:
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
- Called from:
mom_spatial_means::global_i_mean
mom_spatial_means::global_j_mean
-
subroutine
mom_coms/
reset_efp_overflow_error
()¶ Reset the module’s error flag to false.
- Call to:
overflow_error
- Called from:
mom_spatial_means::global_i_mean
mom_spatial_means::global_j_mean
-
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
- Call to:
- 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
- Call to:
-
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:
mom_energetic_pbl::energetic_pbl_init
mom_energetic_pbl::epbl_column
-
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