Utilities¶

TOAST contains a variety of utilities for controlling the runtime environment, logging, timing, streamed random number generation, quaternion operations, FFTs, and special function evaluation. In some cases these utilities provide a common interface to compile-time selected vendor math libraries.

Environment Control¶

The run-time behavior of the TOAST package can be controlled by the manipulation of several environment variables. The current configuration can also be queried.

class toast.utils.Environment¶

Global runtime environment.

This singleton class provides a unified place to parse environment variables at runtime and to change global settings that impact the overall package.

current_threads(self: toast._libtoast.Environment) → int¶: Return the current threading concurrency in use.

disable_function_timers(self: toast._libtoast.Environment) → None¶: Explicitly disable function timers.

enable_function_timers(self: toast._libtoast.Environment) → None¶: Explicitly enable function timers.

function_timers(self: toast._libtoast.Environment) → bool¶: Return True if function timing has been enabled.

get() → toast._libtoast.Environment¶: Get a handle to the global environment class.

log_level(self: toast._libtoast.Environment) → str¶: Return the string of the current Logging level.

max_threads(self: toast._libtoast.Environment) → int¶: Returns the maximum number of threads used by compiled code.

set_log_level(self: toast._libtoast.Environment, level: str) → None¶

Set the Logging level.

Parameters:	level (str) – one of DEBUG, INFO, WARNING, ERROR or CRITICAL.
Returns:	None

set_threads(self: toast._libtoast.Environment, nthread: int) → None¶

Set the number of threads in use.

Parameters:	nthread (int) – The number of threads to use.
Returns:	None

signals(self: toast._libtoast.Environment) → List[str]¶: Return a list of the currently available signals.

tod_buffer_length(self: toast._libtoast.Environment) → int¶: Returns the number of samples to buffer for TOD operations.

version(self: toast._libtoast.Environment) → str¶: Return the current source code version string.

Logging¶

Although python provides logging facilities, those are not accessible to C++. The logging class provided in TOAST is usable from within the compiled libtoast code and also from python, and uses logging level independent from the builtin python logger.

class toast.utils.Logger¶

Simple Logging class.

This class mimics the python logger in C++. The log level is controlled by the TOAST_LOGLEVEL environment variable. Valid levels are DEBUG, INFO, WARNING, ERROR and CRITICAL. The default is INFO.

critical(self: toast._libtoast.Logger, msg: str) → None¶

Print a CRITICAL level message.

Parameters:	msg (str) – The message to print.
Returns:	None

debug(self: toast._libtoast.Logger, msg: str) → None¶

Print a DEBUG level message.

Parameters:	msg (str) – The message to print.
Returns:	None

error(self: toast._libtoast.Logger, msg: str) → None¶

Print an ERROR level message.

Parameters:	msg (str) – The message to print.
Returns:	None

get() → toast._libtoast.Logger¶: Get a handle to the global logger.

info(self: toast._libtoast.Logger, msg: str) → None¶

Print an INFO level message.

Parameters:	msg (str) – The message to print.
Returns:	None

verbose(self: toast._libtoast.Logger, msg: str) → None¶

Print a VERBOSE level message.

Parameters:	msg (str) – The message to print.
Returns:	None

warning(self: toast._libtoast.Logger, msg: str) → None¶

Print a WARNING level message.

Parameters:	msg (str) – The message to print.
Returns:	None

Timing¶

TOAST includes some utilities for setting arbitrary timers on individual processes and also gathering timer data across MPI processes. A basic manual timer is implemented in the Timer class:

class toast.timing.Timer¶

Simple timer class.

This class is just a timer that you can start / stop / clear and report the results. It tracks the elapsed time and the number of times it was started.

calls(self: toast._libtoast.Timer) → int¶

Return the number of calls.

Returns:	The number of calls (if timer is stopped) else 0.
Return type:	(int)

clear(self: toast._libtoast.Timer) → None¶: Clear the timer.

elapsed_seconds(self: toast._libtoast.Timer) → float¶

Return the elapsed seconds from a running timer without modifying the timer state.

Returns:	The elapsed seconds (if timer is running).
Return type:	(float)

is_running(self: toast._libtoast.Timer) → bool¶

Is the timer running?

Returns:	True if the timer is running, else False.
Return type:	(bool)

report(self: toast._libtoast.Timer, message: str) → None¶

Report results of the timer to STDOUT.

Parameters:	message (str) – A message to prepend to the timing results.
Returns:	None

report_clear(self: toast._libtoast.Timer, message: str) → None¶

Report results of the timer to STDOUT and clear the timer.

If the timer was running, it is stopped before reporting and clearing and then restarted. If the timer was stopped, then it is left in the stopped state after reporting and clearing.

Parameters:	message (str) – A message to prepend to the timing results.
Returns:	None

report_elapsed(self: toast._libtoast.Timer, message: str) → None¶

Report results of a running timer to STDOUT without modifying the timer state.

Parameters:	message (str) – A message to prepend to the timing results.
Returns:	None

seconds(self: toast._libtoast.Timer) → float¶

Return the elapsed seconds.

Returns:	The elapsed seconds (if timer is stopped) else -1.
Return type:	(float)

start(self: toast._libtoast.Timer) → None¶: Start the timer.

stop(self: toast._libtoast.Timer) → None¶: Stop the timer.

A single Timer instance is only valid until it goes out of scope. To start and stop a global timer that is accessible anywhere in the code, use the get() method of the GlobalTimers singleton to get a handle to the single instance and then use the class methods to start and stop a named timer:

class toast.timing.GlobalTimers¶

Global timer registry.

This singleton class stores timers that can be started / stopped anywhere in the code to accumulate the total time for different operations.

clear_all(self: toast._libtoast.GlobalTimers) → None¶: Clear all global timers.

collect(self: toast._libtoast.GlobalTimers) → dict¶

Stop all timers and return the current state.

Returns:	A dictionary of Timers.
Return type:	(dict)

get() → toast._libtoast.GlobalTimers¶: Get a handle to the singleton class.

is_running(self: toast._libtoast.GlobalTimers, name: str) → bool¶

Is the specified timer running?

Parameters:	name (str) – The name of the global timer.
Returns:	True if the timer is running, else False.
Return type:	(bool)

names(self: toast._libtoast.GlobalTimers) → List[str]¶

Return the names of all currently registered timers.

Returns:	The names of the timers.
Return type:	(list)

report(self: toast._libtoast.GlobalTimers) → None¶: Report results of all global timers to STDOUT.

seconds(self: toast._libtoast.GlobalTimers, name: str) → float¶

Get the elapsed time for a timer.

The timer must be stopped.

Parameters:	name (str) – The name of the global timer.
Returns:	The elapsed time in seconds.
Return type:	(float)

start(self: toast._libtoast.GlobalTimers, name: str) → None¶

Start the specified timer.

If the named timer does not exist, it is first created before being started.

Parameters:	name (str) – The name of the global timer.
Returns:	None

stop(self: toast._libtoast.GlobalTimers, name: str) → None¶

Stop the specified timer.

The timer must already exist.

Parameters:	name (str) – The name of the global timer.
Returns:	None

stop_all(self: toast._libtoast.GlobalTimers) → None¶: Stop all global timers.

The GlobalTimers object can be used to automatically time all calls to a particular function by using the @function_timer decorator when defining the function.

To gather timing statistics across all processes you can use this function:

toast.timing.gather_timers(comm=None, root=0)[source]¶

Gather global timer information from across a communicator.

Parameters:	comm (MPI.Comm) – The communicator or None. root (int) – The process returning the results.
Returns:	The timer stats on the root process, otherwise None.
Return type:	(dict)

And the resulting information can be written on the root process with:

toast.timing.dump(results, path)[source]¶

Write out timing results to a format suitable for further processing.

Parameters:	results (dict) – The results as returned by compute_stats(). path (str) – File root name to dump.
Returns:	None

Random Number Generation¶

The following functions define wrappers around an internally-built version of the Random123 package for streamed random number generation. This generator is fast and can return reproducible values from any location in the stream specified by the input key and counter values.

toast.rng.random(samples, key=(0, 0), counter=(0, 0), sampler='gaussian', threads=False)[source]¶

Generate random samples from a distribution for one stream.

This returns values from a single stream drawn from the specified distribution. The starting state is specified by the two key values and the two counter values. The second value of the “counter” is used to represent the sample index. If the serial option is enabled, only a single thread will be used. Otherwise the stream generation is divided equally between OpenMP threads.

Parameters:	samples (int) – The number of samples to return. key (tuple) – Two uint64 values which (along with the counter) define the starting state of the generator. counter (tuple) – Two uint64 values which (along with the key) define the starting state of the generator. sampler (string) – The distribution to sample from. Allowed values are “gaussian”, “uniform_01”, “uniform_m11”, and “uniform_uint64”. threads (bool) – If True, use OpenMP threads to generate the stream in parallel. NOTE: this may actually run slower for short streams and many threads.
Returns:	The random values of appropriate type for the sampler.
Return type:	(Aligned array)

If generating samples from multiple different streams you can use this function:

toast.rng.random_multi(samples, keys, counters, sampler='gaussian')[source]¶

Generate random samples from multiple streams.

Given multiple streams, each specified by a pair of key values and a pair of counter values, generate some number of samples from each. The number of samples is specified independently for each stream. The generation of the streams is run with multiple threads.

NOTE: if you just want threaded generation of a single stream, use the “threads” option to the random() function.

Parameters:	samples (list) – The number of samples to return for each stream keys (list) – A tuple of integer values for each stream, which (along with the counter) define the starting state of the generator for that stream. counters (list) – A tuple of integer values for each stream, which (along with the key) define the starting state of the generator for that stream. sampler (string) – The distribution to sample from. Allowed values are “gaussian”, “uniform_01”, “uniform_m11”, and “uniform_uint64”.
Returns:	The random samples for each stream.
Return type:	(list)

Vector Math Operations¶

The following functions are just simple wrappers vendor math libraries or the default libm. They exist mainly just to provide a common interface to architecture-specific math libraries.

toast.utils.vsin(in: buffer, out: buffer) → None¶

Compute the Sine for an array of float64 values.

The results are stored in the output buffer. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	in (array_like) – 1D array of float64 values. out (array_like) – 1D array of float64 values.
Returns:	None

toast.utils.vcos(in: buffer, out: buffer) → None¶

Compute the Cosine for an array of float64 values.

The results are stored in the output buffer. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	in (array_like) – 1D array of float64 values. out (array_like) – 1D array of float64 values.
Returns:	None

toast.utils.vsincos(in: buffer, sinout: buffer, cosout: buffer) → None¶

Compute the sine and cosine for an array of float64 values.

The results are stored in the output buffers. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	in (array_like) – 1D array of float64 values. sinout (array_like) – 1D array of float64 values. cosout (array_like) – 1D array of float64 values.
Returns:	None

toast.utils.vatan2(y: buffer, x: buffer, ang: buffer) → None¶

Compute the arctangent of the y and x values.

The results are stored in the output buffer. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	y (array_like) – 1D array of float64 values. x (array_like) – 1D array of float64 values. ang (array_like) – output angles as 1D array of float64 values.
Returns:	None

toast.utils.vsqrt(in: buffer, out: buffer) → None¶

Compute the sqrt an array of float64 values.

The results are stored in the output buffer. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	in (array_like) – 1D array of float64 values. out (array_like) – 1D array of float64 values.
Returns:	None

toast.utils.vrsqrt(in: buffer, out: buffer) → None¶

Compute the inverse sqrt an array of float64 values.

The results are stored in the output buffer. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	in (array_like) – 1D array of float64 values. out (array_like) – 1D array of float64 values.
Returns:	None

toast.utils.vexp(in: buffer, out: buffer) → None¶

Compute e^x for an array of float64 values.

The results are stored in the output buffer. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	in (array_like) – 1D array of float64 values. out (array_like) – 1D array of float64 values.
Returns:	None

toast.utils.vlog(in: buffer, out: buffer) → None¶

Compute the natural log of an array of float64 values.

The results are stored in the output buffer. To guarantee SIMD vectorization, the input and output arrays should be aligned (i.e. use an AlignedF64).

Parameters:	in (array_like) – 1D array of float64 values. out (array_like) – 1D array of float64 values.
Returns:	None