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

real_to_efp reproducing_efp_sum_2d reproducing_sum_2d 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 reproducing_sum_2d 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

efp_minus efp_plus reproducing_efp_sum_2d 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

reproducing_efp_sum_2d 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

efp_list_sum_across_pes efp_val_sum_across_pes reproducing_efp_sum_2d 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 reproducing_efp_sum_2d 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

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

ints_to_real regularize_ints

Called from

efp_list_sum_across_pes efp_real_diff efp_val_sum_across_pes

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

mom_error_handler::mom_error real_to_ints

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

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