General purpose utilities. More...

Namespaces
namespace	amrex::Font
	ANSI font-style escape codes (bold, italic, underline, etc.).

namespace	amrex::FGColor
	ANSI foreground-color escape codes.

namespace	amrex::BGColor
	ANSI background-color escape codes.

namespace	amrex::PhysBCType
	Physical boundary condition types assigned to domain faces.

namespace	amrex::BCType
	Mathematical boundary condition types applied per face.

Classes
struct	amrex::Plus< T >
	Function object that returns the sum of two values. More...

struct	amrex::Minus< T >
	Function object that returns the difference of two values. More...

struct	amrex::Minimum< T >
	Function object that returns the smaller of two values. More...

struct	amrex::Maximum< T >
	Function object that returns the larger of two values. More...

struct	amrex::LogicalAnd< T >
	Function object that returns the logical AND of two values. More...

struct	amrex::LogicalOr< T >
	Function object that returns the logical OR of two values. More...

struct	amrex::Multiplies< T >
	Function object that returns the product of two values. More...

struct	amrex::Divides< T >
	Function object that returns the quotient of two values. More...

class	amrex::ParmParse
	Parse Parameters From Command Line and Input Files. More...

class	amrex::IParser
	Integer-only variant of amrex::Parser. More...

class	amrex::Parser
	Front-end for parsing scalar expressions into GPU/CPU executors. More...

class	amrex::Any
	Type-erased container similar to `std::any`, but supports move-only types. More...

class	amrex::BackgroundThread
	Utility class running deferred work on a single background thread. More...

class	amrex::BCRec
	Boundary condition record storing low/high face types per coordinate. More...

Macros
#define	AMREX_ENUM(CLASS, ...)
	Declare a scoped enum with reflection support.

Typedefs
using	amrex::RuntimeError = std::runtime_error

Functions
template<class T >
__host__ __device__ constexpr const T &	amrex::min (const T &a, const T &b) noexcept

template<class T , class ... Ts>
__host__ __device__ constexpr const T &	amrex::min (const T &a, const T &b, const Ts &... c) noexcept

template<class T >
__host__ __device__ constexpr const T &	amrex::max (const T &a, const T &b) noexcept

template<class T , class ... Ts>
__host__ __device__ constexpr const T &	amrex::max (const T &a, const T &b, const Ts &... c) noexcept

template<class T >
__host__ __device__ constexpr T	amrex::elemwiseMin (T const &a, T const &b) noexcept

template<class T , class ... Ts>
__host__ __device__ constexpr T	amrex::elemwiseMin (const T &a, const T &b, const Ts &... c) noexcept

template<class T >
__host__ __device__ constexpr T	amrex::elemwiseMax (T const &a, T const &b) noexcept

template<class T , class ... Ts>
__host__ __device__ constexpr T	amrex::elemwiseMax (const T &a, const T &b, const Ts &... c) noexcept

template<typename T >
__host__ __device__ void	amrex::Swap (T &t1, T &t2) noexcept

template<typename T >
__host__ __device__ constexpr const T &	amrex::Clamp (const T &v, const T &lo, const T &hi)

template<std::floating_point T>
__host__ __device__ bool	amrex::almostEqual (T x, T y, int ulp=2)

template<std::floating_point T, class F >
__host__ __device__ T	amrex::bisect (T lo, T hi, F f, T tol=1e-12, int max_iter=100)
	Find a root of a scalar function on a bracketing interval using bisection.

template<typename T , std::integral I>
__host__ __device__ I	amrex::bisect (T const *d, I lo, I hi, T const &v)
	Find the index of the interval containing a value in a sorted array.

template<typename ItType , typename ValType >
__host__ __device__ ItType	amrex::upper_bound (ItType first, ItType last, const ValType &val)
	Return an iterator to the first element greater than a given value.

template<typename ItType , typename ValType >
__host__ __device__ ItType	amrex::lower_bound (ItType first, ItType last, const ValType &val)
	Return an iterator to the first element not less than a given value.

template<typename ItType , std::floating_point ValType> requires (std::floating_point<typename std::iterator_traits<ItType>::value_type>)
__host__ __device__ void	amrex::linspace (ItType first, const ItType &last, const ValType &start, const ValType &stop)
	Fill a range with linearly spaced values over a closed interval.

template<typename ItType , std::floating_point ValType> requires (std::floating_point<typename std::iterator_traits<ItType>::value_type>)
__host__ __device__ void	amrex::logspace (ItType first, const ItType &last, const ValType &start, const ValType &stop, const ValType &base)
	Fill a range with logarithmically spaced values over a closed interval.

template<auto I, auto N, class F >
__host__ __device__ constexpr void	amrex::constexpr_for (F const &f)
	Compile-time unrolled loop from `I` (inclusive) to `N` (exclusive).

template<typename T , typename ET = amrex_enum_traits<T>> requires (ET::value)
std::vector< std::pair< std::string, T > > const &	amrex::getEnumNameValuePairs ()
	Return all (name, value) pairs for an AMREX_ENUM-declared enum type.

template<typename T , typename ET = amrex_enum_traits<T>> requires (ET::value)
T	amrex::getEnum (std::string_view const &s)
	Convert a string to an enum value.

template<typename T , typename ET = amrex_enum_traits<T>> requires (ET::value)
T	amrex::getEnumCaseInsensitive (std::string_view const &s)
	Convert a string case-insensitively to an enum value.

template<typename T , typename ET = amrex_enum_traits<T>> requires (ET::value)
std::string	amrex::getEnumNameString (T const &v)
	Get the name string of an enum value.

template<typename T , typename ET = amrex_enum_traits<T>> requires (ET::value)
std::vector< std::string >	amrex::getEnumNameStrings ()
	Return a list of all enumerator name strings for an AMREX_ENUM-declared type.

template<typename T , typename ET = amrex_enum_traits<T>> requires (ET::value)
std::string	amrex::getEnumClassName ()
	Return the class name string of an AMREX_ENUM-declared enum type.

template<typename T , typename ET = amrex_enum_traits<T>> requires (ET::value)
constexpr auto	amrex::toUnderlying (T v) noexcept
	Return the underlying integer value of an enum enumerator.

Real	amrex::Random ()
	Generate a psuedo-random real from uniform distribution.

__host__ __device__ Real	amrex::Random (RandomEngine const &random_engine)

Real	amrex::RandomPositive ()
	Generate a pseudo-random real from uniform distribution, excluding zero.

__host__ __device__ Real	amrex::RandomPositive (RandomEngine const &random_engine)

Real	amrex::RandomNormal (Real mean, Real stddev)
	Generate a psuedo-random real from a normal distribution.

__host__ __device__ Real	amrex::RandomNormal (Real mean, Real stddev, RandomEngine const &random_engine)

unsigned int	amrex::RandomPoisson (Real lambda)
	Generate a psuedo-random integer from a Poisson distribution.

__host__ __device__ unsigned int	amrex::RandomPoisson (Real lambda, RandomEngine const &random_engine)

Real	amrex::RandomGamma (Real alpha, Real beta)
	Generate a psuedo-random floating point number from the Gamma distribution.

__host__ __device__ Real	amrex::RandomGamma (Real alpha, Real beta, RandomEngine const &random_engine)

unsigned int	amrex::Random_int (unsigned int n)
	Generates one pseudorandom unsigned integer which is uniformly distributed on [0,n-1]-interval for each call. For the special case of n = 0, it returns 0.

__host__ __device__ unsigned int	amrex::Random_int (unsigned int n, RandomEngine const &random_engine)

ULong	amrex::Random_long (ULong n)
	Generates one pseudorandom unsigned long which is uniformly distributed on [0,n-1]-interval for each call. For the special case of n = 0, it returns 0.

void	amrex::FillRandom (Real *p, Long N)

void	amrex::FillRandomNormal (Real *p, Long N, Real mean, Real stddev)

void	amrex::InitRandom (ULong cpu_seed, int nprocs=ParallelDescriptor::NProcs(), ULong gpu_seed=detail::DefaultGpuSeed())
	Set the seed of the random number generator.

void	amrex::ResetRandomSeed (ULong cpu_seed, ULong gpu_seed=detail::DefaultGpuSeed())

void	amrex::SaveRandomState (std::ostream &os)
	Save host random state.

void	amrex::RestoreRandomState (std::istream &is, int nthreads_old, int nstep_old)
	Restore host random state saved by SaveRandomState.

void	amrex::UniqueRandomSubset (Vector< int > &uSet, int setSize, int poolSize, bool printSet=false)
	Create a unique subset of random numbers from a pool of integers in the range [0, poolSize - 1] the set will be in the order they are found setSize must be <= poolSize uSet will be resized to setSize if you want all processors to have the same set, call this on one processor and broadcast the array.

Variables
constexpr char	amrex::ResetDisplay [] = "\033[0m"

Detailed Description

General purpose utilities.

This topic covers general purpose utilities used throughout AMReX and AMReX applications.

Central capabilities include:

Macro Definition Documentation

◆ AMREX_ENUM

#define AMREX_ENUM	(	CLASS,
		...
	)

Value:

    enum class CLASS : int { __VA_ARGS__ }; \

 \    struct CLASS##_EnumTraits { \
        using enum_class_t = CLASS; \
        static constexpr bool value = true; \
        static constexpr std::string_view class_name{#CLASS}; \
        static constexpr std::string_view enum_names{#__VA_ARGS__}; \
    }; \

 \    CLASS##_EnumTraits amrex_get_enum_traits(CLASS)

Declare a scoped enum with reflection support.

Defines enum class CLASS : int and registers its enumerator names so that amrex::getEnum, amrex::getEnumCaseInsensitive, amrex::getEnumNameString, and related utilities can convert between strings and values at run time.

Example:

AMREX_ENUM(Color, red, green, blue);

Color c = amrex::getEnum<Color>("green");

AMREX_ENUM

#define AMREX_ENUM(CLASS,...)

Declare a scoped enum with reflection support.

Definition AMReX_Enum.H:260

Typedef Documentation

◆ RuntimeError

using amrex::RuntimeError = typedef std::runtime_error

Exception type used when AMReX is configured to throw on fatal errors.

Function Documentation

◆ almostEqual()

template<std::floating_point T>

__host__ __device__ bool amrex::almostEqual	(	T	x,
		T	y,
		int	ulp = `2`
	)

inline

Return true when the difference between x and y is small, as measured by the given ulp (units in the last place).

◆ bisect() [1/2]

template<typename T , std::integral I>

__host__ __device__ I amrex::bisect	(	T const *	d,
		I	lo,
		I	hi,
		T const &	v
	)

inline

Find the index of the interval containing a value in a sorted array.

Find index i in the range [lo,hi) that d[i] <= v < d[i+1]. It is assumed that the input data is sorted. The elements d[lo] and d[hi] are never accessed, so that d only needs to be valid in the exclusive range (lo,hi). It is not checked whether the value v is out-of-bounds. In that case, if v < d[lo], lo is returned, and if v >= d[hi], hi-1 is returned. Note that this is different from std::lower_bound that searches for the first element which is not less than v.

Template Parameters

T	value type.
I	integral index type.

Parameters

d	pointer to a sorted array of values.
lo	inclusive lower bound of the search range.
hi	exclusive upper bound of the search range.
v	value to be located.

Returns: an index i such that d[i] <= v < d[i+1], with lo <= i < hi.

◆ bisect() [2/2]

template<std::floating_point T, class F >

__host__ __device__ T amrex::bisect	(	T	lo,
		T	hi,
		F	f,
		T	tol = `1e-12`,
		int	max_iter = `100`
	)

inline

Find a root of a scalar function on a bracketing interval using bisection.

Invalid bracketing and iteration failures are checked with AMReX assertions when assertions are enabled.

Template Parameters

T	floating-point type
F	callable type of the scalar function

Parameters

lo	lower bound
hi	upper bound
f	scalar function
tol	absolute tolerance. Iteration stops when `hi-lo < tol` or when `almostEqual(lo,hi)` returns true.
max_iter	maximum number of bisection iterations allowed.

Returns: an approximate root found using bisection.

◆ Clamp()

template<typename T >

__host__ __device__ constexpr const T & amrex::Clamp	(	const T &	v,
		const T &	lo,
		const T &	hi
	)

inlineconstexpr

Return the reference to lo if v < lo; return the reference to hi if hi < v; otherwise return the reference to v. This function was added to AMReX before switching to C++17. std::clamp can now be used directly instead.

◆ constexpr_for()

template<auto I, auto N, class F >

__host__ __device__ constexpr void amrex::constexpr_for ( F const & f )

inlineconstexpr

Compile-time unrolled loop from I (inclusive) to N (exclusive).

Approximates the compile-time unrolling of:

for (auto i = I; i < N; ++i) { f(i); }

The body f is a callable (typically a lambda) that accepts a single integral argument. This can be used inside GPU kernels.

Note: Based on https://artificial-mind.net/blog/2020/10/31/constexpr-for

Template Parameters

I	Starting index (compile-time constant).
N	One-past-end index (compile-time constant).
F	Callable type; must accept an integral argument.

Parameters

f	Callable invoked for each index from `I` to `N-1`.

◆ elemwiseMax() [1/2]

template<class T , class ... Ts>

__host__ __device__ constexpr T amrex::elemwiseMax	(	const T &	a,
		const T &	b,
		const Ts &...	c
	)

inlineconstexprnoexcept

Return the element-wise maximum of a, b, and the remaining arguments in c.

◆ elemwiseMax() [2/2]

template<class T >

__host__ __device__ constexpr T amrex::elemwiseMax	(	T const &	a,
		T const &	b
	)

inlineconstexprnoexcept

Return the element-wise maximum of a and b for types like XDim3.

◆ elemwiseMin() [1/2]

template<class T , class ... Ts>

__host__ __device__ constexpr T amrex::elemwiseMin	(	const T &	a,
		const T &	b,
		const Ts &...	c
	)

inlineconstexprnoexcept

Return the element-wise minimum of a, b, and the rest of the pack c.

◆ elemwiseMin() [2/2]

template<class T >

__host__ __device__ constexpr T amrex::elemwiseMin	(	T const &	a,
		T const &	b
	)

inlineconstexprnoexcept

Return the element-wise minimum of a and b for types like XDim3.

◆ FillRandom()

void amrex::FillRandom	(	Real *	p,
		Long	N
	)

Fill random numbers from uniform distribution. The interval is not uniform across backends the way amrex::Random and amrex::RandomPositive are: it is [0,1) on the CPU, but the GPU paths hand back whatever the vendor bulk generator produces, nominally [0,1) for SYCL and (0,1] for CUDA and HIP. Code that depends on either endpoint should guard the values it reads back, or draw with amrex::Random / amrex::RandomPositive instead.

◆ FillRandomNormal()

void amrex::FillRandomNormal	(	Real *	p,
		Long	N,
		Real	mean,
		Real	stddev
	)

Fill random numbers from normal distribution

◆ getEnum()

template<typename T , typename ET = amrex_enum_traits<T>>
requires (ET::value)

T amrex::getEnum ( std::string_view const & s )

Convert a string to an enum value.

Throws std::runtime_error if s does not match any enumerator name.

Example:

AMREX_ENUM(Model,
    linear,
    nonlinear
);
std::string const model_str = "nonlinear";
Model const model = amrex::getEnum<Model>(model_str);
assert(model == Model::nonlinear);

◆ getEnumCaseInsensitive()

template<typename T , typename ET = amrex_enum_traits<T>>
requires (ET::value)

T amrex::getEnumCaseInsensitive ( std::string_view const & s )

Convert a string case-insensitively to an enum value.

Same as getEnum<T>, but uses a case-insensitive match.

Example:

AMREX_ENUM(Model,
    linear,
    nonlinear
);
std::string const model_str = "NonLinear";
Model const model = amrex::getEnumCaseInsensitive<Model>(model_str);
assert(model == Model::nonlinear);

◆ getEnumClassName()

template<typename T , typename ET = amrex_enum_traits<T>>
requires (ET::value)

std::string amrex::getEnumClassName ( )

Return the class name string of an AMREX_ENUM-declared enum type.

Template Parameters

T	An enum type declared with AMREX_ENUM.

◆ getEnumNameString()

template<typename T , typename ET = amrex_enum_traits<T>>
requires (ET::value)

std::string amrex::getEnumNameString ( T const & v )

Get the name string of an enum value.

Throws std::runtime_error if v has no matching enumerator name.

Example:

AMREX_ENUM(Model,
    linear,
    nonlinear
);
Model model = Model::linear;
std::string model_str = amrex::getEnumNameString(model);
assert(model_str == "linear");

◆ getEnumNameStrings()

template<typename T , typename ET = amrex_enum_traits<T>>
requires (ET::value)

std::vector< std::string > amrex::getEnumNameStrings ( )

Return a list of all enumerator name strings for an AMREX_ENUM-declared type.

Template Parameters

T	An enum type declared with AMREX_ENUM.

◆ getEnumNameValuePairs()

template<typename T , typename ET = amrex_enum_traits<T>>
requires (ET::value)

std::vector< std::pair< std::string, T > > const & amrex::getEnumNameValuePairs ( )

Return all (name, value) pairs for an AMREX_ENUM-declared enum type.

The result is cached the first time it is called for a given type T.

Template Parameters

T	An enum type declared with AMREX_ENUM.

◆ InitRandom()

void amrex::InitRandom	(	ULong	cpu_seed,
		int	nprocs = `ParallelDescriptor::NProcs()`,
		ULong	gpu_seed = `detail::DefaultGpuSeed()`
	)

Set the seed of the random number generator.

There is also an entry point for Fortran callable as:

INTEGER seed call blutilinitrand(seed)

or

INTEGER seed call blinitrand(seed)

◆ linspace()

template<typename ItType , std::floating_point ValType>
requires (std::floating_point<typename std::iterator_traits<ItType>::value_type>)

__host__ __device__ void amrex::linspace	(	ItType	first,
		const ItType &	last,
		const ValType &	start,
		const ValType &	stop
	)

Fill a range with linearly spaced values over a closed interval.

This function assigns linearly spaced floating-point values to the range [first, last), starting at start and ending at stop. The value range is inclusive at both ends such that the first element is set to start and the last element to stop exactly. Note that this function does nothing when the range contains fewer than two elements (i.e., last-first < 2).

Template Parameters

ItType	iterator type.
ValType	floating-point value type.

Parameters

first	pointing to the first element of the output range.
last	pointing one past the last element of the output range.
start	start value.
stop	stop value.

◆ logspace()

template<typename ItType , std::floating_point ValType>
requires (std::floating_point<typename std::iterator_traits<ItType>::value_type>)

__host__ __device__ void amrex::logspace	(	ItType	first,
		const ItType &	last,
		const ValType &	start,
		const ValType &	stop,
		const ValType &	base
	)

Fill a range with logarithmically spaced values over a closed interval.

This function assigns logarithmically spaced floating-point values to the range [first, last), starting at base^start and ending at base^stop. The value range is inclusive at both ends such that the first element is set to base^start and the last element to base^stop exactly. Note that this function does nothing when the range contains fewer than two elements (i.e., last-first < 2).

Template Parameters

ItType	iterator type.
ValType	floating-point value type.

Parameters

first	pointing to the first element of the output range.
last	pointing one past the last element of the output range.
start	start value.
stop	stop value.
base	base of the exponential.

◆ lower_bound()

template<typename ItType , typename ValType >

__host__ __device__ ItType amrex::lower_bound	(	ItType	first,
		ItType	last,
		const ValType &	val
	)

Return an iterator to the first element not less than a given value.

This function is an implementation of std::lower_bound that works on both host and device.

Template Parameters

ItType	iterator type.
ValType	value type.

Parameters

first	inclusive lower bound of the search range.
last	exclusive upper bound of the search range.
val	value to compare the elements to.

Returns: an iterator pointing to the first element not less than val.

◆ max() [1/2]

template<class T >

__host__ __device__ constexpr const T & amrex::max	(	const T &	a,
		const T &	b
	)

inlineconstexprnoexcept

Return the greater value. This function was added to AMReX to support GPU before std::max was constexpr in C++14. std::max can now be used directly instead.

◆ max() [2/2]

template<class T , class ... Ts>

__host__ __device__ constexpr const T & amrex::max	(	const T &	a,
		const T &	b,
		const Ts &...	c
	)

inlineconstexprnoexcept

Return the greatest value. This function was added to AMReX to support GPU before std::max was constexpr in C++14. std::max can now be used directly instead.

◆ min() [1/2]

template<class T >

__host__ __device__ constexpr const T & amrex::min	(	const T &	a,
		const T &	b
	)

inlineconstexprnoexcept

Return the smaller value. This function was added to AMReX to support GPU before std::min was constexpr in C++14. std::min can now be used directly instead.

◆ min() [2/2]

template<class T , class ... Ts>

__host__ __device__ constexpr const T & amrex::min	(	const T &	a,
		const T &	b,
		const Ts &...	c
	)

inlineconstexprnoexcept

Return the smallest value. This function was added to AMReX to support GPU before std::min was constexpr in C++14. std::min can now be used directly instead.

◆ Random() [1/2]

Real amrex::Random ( )

Generate a psuedo-random real from uniform distribution.

Generates one pseudorandom real number from a uniform distribution between 0.0 and 1.0 (0.0 included, 1.0 excluded).

Note: Since 0.0 is included, the result must not be passed unguarded to a function that is singular at zero, such as std::log or std::pow with a negative exponent. Draw from amrex::RandomPositive for those cases rather than deriving a value with 1 - amrex::Random(), which is not equivalent: it costs an arithmetic operation and discards resolution, because the subtraction is exact only above 0.5 and collapses smaller values onto a coarse grid.

◆ Random() [2/2]

__host__ __device__ Real amrex::Random ( RandomEngine const & random_engine )

inline

◆ Random_int() [1/2]

unsigned int amrex::Random_int ( unsigned int n )

Generates one pseudorandom unsigned integer which is uniformly distributed on [0,n-1]-interval for each call. For the special case of n = 0, it returns 0.

The CPU version of this function uses C++11's mt19937. The GPU version uses CURAND's XORWOW generator.

◆ Random_int() [2/2]

__host__ __device__ unsigned int amrex::Random_int	(	unsigned int	n,
		RandomEngine const &	random_engine
	)

inline

◆ Random_long()

ULong amrex::Random_long ( ULong n )

Generates one pseudorandom unsigned long which is uniformly distributed on [0,n-1]-interval for each call. For the special case of n = 0, it returns 0.

The CPU version of this function uses C++11's mt19937. There is no GPU version.

◆ RandomGamma() [1/2]

Real amrex::RandomGamma	(	Real	alpha,
		Real	beta
	)

Generate a psuedo-random floating point number from the Gamma distribution.

Generates one real number (single or double) extracted from a Gamma distribution, given the Real parameters alpha and beta. alpha and beta must both be > 0. The CPU version of this function relies on the Standard Template Library. The GPU version is implemented in terms of amrex::RandomPositive and amrex::RandomNormal.

◆ RandomGamma() [2/2]

__host__ __device__ Real amrex::RandomGamma	(	Real	alpha,
		Real	beta,
		RandomEngine const &	random_engine
	)

inline

◆ RandomNormal() [1/2]

Real amrex::RandomNormal	(	Real	mean,
		Real	stddev
	)

Generate a psuedo-random real from a normal distribution.

Generates one pseudorandom real number from a normal distribution with mean 'mean' and standard deviation 'stddev'.

◆ RandomNormal() [2/2]

__host__ __device__ Real amrex::RandomNormal	(	Real	mean,
		Real	stddev,
		RandomEngine const &	random_engine
	)

inline

◆ RandomPoisson() [1/2]

unsigned int amrex::RandomPoisson ( Real lambda )

Generate a psuedo-random integer from a Poisson distribution.

Generates one pseudorandom positive integer number extracted from a Poisson distribution, given the Real parameter lambda. The CPU version of this function relies on the standard Template Library The GPU version of this function relies on the cuRAND library

◆ RandomPoisson() [2/2]

__host__ __device__ unsigned int amrex::RandomPoisson	(	Real	lambda,
		RandomEngine const &	random_engine
	)

inline

◆ RandomPositive() [1/2]

Real amrex::RandomPositive ( )

Generate a pseudo-random real from uniform distribution, excluding zero.

Generates one pseudorandom real number from a uniform distribution between 0.0 and 1.0 (0.0 excluded, 1.0 included).

This is the counterpart to amrex::Random for samplers that are singular at zero, for example

// exponential distribution with mean tau
Real const t = -tau * std::log(amrex::RandomPositive(engine));
 
// power law with exponent -a
Real const x = std::pow(amrex::RandomPositive(engine), -a);

Prefer this over deriving a non-zero value from amrex::Random by hand with 1 - amrex::Random(), which is lossier for no benefit. See the note on amrex::Random.

Note: If all you need is a normally distributed value, use amrex::RandomNormal rather than a hand-rolled Box-Muller transform on top of this function. It is faster (on GPU it is the vendor's own normal generator, and it does not consume two uniforms per deviate) and it never touches std::log, so it is unaffected by the endpoint issue described above. Box-Muller written out by hand is only worthwhile when the radial variable itself is needed, for instance to truncate a Gaussian at a given number of sigma by inverting the radial CDF, or to draw an isotropic direction by normalizing a vector of deviates.

There is no accuracy or performance penalty for choosing this interval over the half-open [0,1) of amrex::Random. On CUDA/HIP it is the native interval of the underlying generator, so the value is returned as drawn; on the host and with SYCL the generator is natively [0,1) and only its zero endpoint is relocated to one. No arithmetic is performed on any path, so no resolution is lost and there is nothing that a floating-point mode could change: the exclusion of zero holds under -ffast-math / –use_fast_math and flush-to-zero alike, because it is established by a comparison rather than by a computed bound.

The smallest value that can be returned is in every case the smallest positive value of the underlying generator, and is therefore backend-dependent: roughly 2^-33 in single precision with curand, 2^-32 with rocrand, and the granularity of the standard library's distribution on the host, which for a 32-bit engine is 2^-32 in single precision and 2^-64 in double. All of these are normal numbers, so flush-to-zero cannot reach them.

See also: amrex::Random, amrex::RandomNormal

◆ RandomPositive() [2/2]

__host__ __device__ Real amrex::RandomPositive ( RandomEngine const & random_engine )

inline

◆ ResetRandomSeed()

void amrex::ResetRandomSeed	(	ULong	cpu_seed,
		ULong	gpu_seed
	)

◆ RestoreRandomState()

void amrex::RestoreRandomState	(	std::istream &	is,
		int	nthreads_old,
		int	nstep_old
	)

Restore host random state saved by SaveRandomState.

This does not restore GPU random state used by ParallelForRNG or GPU FillRandom/FillRandomNormal calls.

◆ SaveRandomState()

void amrex::SaveRandomState ( std::ostream & os )

Save host random state.

This function only serializes the host-side random number generators used by the host random-number APIs. It does not save GPU random state used by ParallelForRNG or GPU FillRandom/FillRandomNormal calls.

◆ Swap()

template<typename T >

__host__ __device__ void amrex::Swap	(	T &	t1,
		T &	t2
	)

inlinenoexcept

Swap the contents of t1 and t2. std::swap can be used directly instead in GPU codes since C++20.

◆ toUnderlying()

template<typename T , typename ET = amrex_enum_traits<T>>
requires (ET::value)

constexpr auto amrex::toUnderlying ( T v )

constexprnoexcept

Return the underlying integer value of an enum enumerator.

Useful when building bitmasks.

◆ UniqueRandomSubset()

void amrex::UniqueRandomSubset	(	Vector< int > &	uSet,
		int	setSize,
		int	poolSize,
		bool	printSet
	)

Create a unique subset of random numbers from a pool of integers in the range [0, poolSize - 1] the set will be in the order they are found setSize must be <= poolSize uSet will be resized to setSize if you want all processors to have the same set, call this on one processor and broadcast the array.

◆ upper_bound()

template<typename ItType , typename ValType >

__host__ __device__ ItType amrex::upper_bound	(	ItType	first,
		ItType	last,
		const ValType &	val
	)

Return an iterator to the first element greater than a given value.

This function is an implementation of std::upper_bound that works on both host and device.

Template Parameters

ItType	iterator type.
ValType	value type.

Parameters

first	inclusive lower bound of the search range.
last	exclusive upper bound of the search range.
val	value to compare the elements to.

Returns: an iterator pointing to the first element greater than val.

Variable Documentation

◆ ResetDisplay

constexpr char amrex::ResetDisplay[] = "\033[0m"

constexpr

Reset all display attributes to terminal defaults.

Namespaces

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ AMREX_ENUM

Typedef Documentation

◆ RuntimeError

Function Documentation

◆ almostEqual()

◆ bisect() [1/2]

◆ bisect() [2/2]

◆ Clamp()

◆ constexpr_for()

◆ elemwiseMax() [1/2]

◆ elemwiseMax() [2/2]

◆ elemwiseMin() [1/2]

◆ elemwiseMin() [2/2]

◆ FillRandom()

◆ FillRandomNormal()

◆ getEnum()

◆ getEnumCaseInsensitive()

◆ getEnumClassName()

◆ getEnumNameString()

◆ getEnumNameStrings()

◆ getEnumNameValuePairs()

◆ InitRandom()

◆ linspace()

◆ logspace()

◆ lower_bound()

◆ max() [1/2]

◆ max() [2/2]

◆ min() [1/2]

◆ min() [2/2]

◆ Random() [1/2]

◆ Random() [2/2]

◆ Random_int() [1/2]

◆ Random_int() [2/2]

◆ Random_long()

◆ RandomGamma() [1/2]

◆ RandomGamma() [2/2]

◆ RandomNormal() [1/2]

◆ RandomNormal() [2/2]

◆ RandomPoisson() [1/2]

◆ RandomPoisson() [2/2]

◆ RandomPositive() [1/2]

◆ RandomPositive() [2/2]

◆ ResetRandomSeed()

◆ RestoreRandomState()

◆ SaveRandomState()

◆ Swap()

◆ toUnderlying()

◆ UniqueRandomSubset()

◆ upper_bound()

Variable Documentation

◆ ResetDisplay