kwave.utils.checks module

check_alpha_mode_cpp_compatible(medium)

Raise ValueError if medium.alpha_mode is set on the C++ backend.

The C++ HDF5 input format does not carry alpha_mode at all; the binary always applies full power-law absorption + dispersion. Any non-default mode (no_absorption, no_dispersion, stokes) would be silently ignored — the same class of bug that allowed the original NaN report (issue #664). backend='python' (or the legacy pure-Python backend) honors alpha_mode.

Return type:

None

check_divisible(number, divider)

Checks whether number is divisible by divider without any remainder Why do we need such a function? -> Because due to floating point precision we experience rounding errors while using standard modulo operator with floating point numbers

Parameters:

• number (float) – Number that’s supposed to be divided

• divider (float) – Divider that should divide the number

Returns:

True if number is divisible by divider, False otherwise

Return type:

bool

check_factors(min_number, max_number)

Return the maximum prime factor for a range of numbers.

checkFactors loops through the given range of numbers and finds the numbers with the smallest maximum prime factors. This allows suitable grid sizes to be selected to maximise the speed of the FFT (this is fastest for FFT lengths with small prime factors). The output is printed to the command line.

Parameters:

• min_number (int) – integer specifying the lower bound of values to test

• max_number (int) – integer specifying the upper bound of values to test

Return type:

None

check_field_names(dictionary, *fields)

This method checks if the keys of the given dictionary are valid fields.

Parameters:

• dictionary – A dictionary where the keys will be checked for validity.

• *fields – A list of valid field names.

Raises:

AssertionError – If any of the keys in the dictionary are not in the list of valid fields.

check_stability(kgrid, medium)

Calculates the maximum time step for which the k-space propagation models are stable.

These models are unconditionally stable when the reference sound speed is equal to or greater than the maximum sound speed in the medium and there is no absorption. However, when the reference sound speed is less than the maximum sound speed the model is only stable for sufficiently small time steps. The criterion is more stringent (the time step is smaller) in the absorbing case.

The time steps given are accurate when the medium properties are homogeneous. For a heterogeneous media they give a useful, but not exact, estimate.

Parameters:

• kgrid (kWaveGrid) – simulation grid

• medium (kWaveMedium) – medium properties

Returns:

The maximum time step for which the models are stable. This is set to Inf when the model is unconditionally stable.

Return type:

float

check_str_eq(value, target)

This method checks whether the given value is a string and is equal to the target string. It is useful to avoid FutureWarnings when value is not a string.

Parameters:

• value – The value to check.

• target (str) – The target string to compare with.

Returns:

True if the value is a string and is equal to the target, False otherwise.

Return type:

bool

check_str_in(value, target)

Check if value is in the given list only if the value is string. Helps to avoid FutureWarnings when value is not a string. Added by @Farid

Parameters:

• value – The value to check for inclusion in target

• target (List[str]) – A list of strings to check for the presence of value

Returns:

True if value is a string and is present in target, otherwise False

Return type:

bool

enforce_fields(dictionary, *fields)

Ensures that the given dictionary contains the specified fields.

Parameters:

• dictionary – A dictionary to check.

• *fields – The fields that must be present in the dictionary.

Raises:

AssertionError – If any of the specified fields are not in the dictionary.

enforce_fields_obj(obj, *fields)

Enforces that certain fields are not None in the given object.

Parameters:

• obj – Object to check the fields of.

• *fields – List of field names to check.

Raises:

AssertionError – If any of the given fields are None in the given object.

is_number(value)

Check if the given value is a numeric type.

Parameters:

value (Any) – The value to check.

Returns:

True if the value is numeric, False otherwise.

Return type:

bool

is_unix()

Check whether the current platform is a Unix-like system.

Returns:

True if the current platform is a Unix-like system, False otherwise.

Return type:

bool

warn_alpha_power_near_unity_cpp(medium)

Warn when alpha_power is near 1 with absorption enabled on the C++ backend.

The dispersion coefficient η = 2 α c₀^y · tan(π y / 2) blows up as y → 1 and the C++ binary (float32 internally) returns NaN well before the formal singularity (issue #664). The user’s escape hatch on the Python backend is alpha_mode='no_dispersion'; the C++ binary has no equivalent.

Fires if any element of alpha_power falls in the singular range — handles heterogeneous media as well as the typical scalar case.

Return type:

None