scico.util#

General utility functions.

Functions

`check_for_tracer`(func)	Check if positional arguments to func are jax tracers.
`device_info`([devid])	Get a string describing the specified device.
`partial`(func, indices, fixargs, *fixkwargs)	Flexible partial function creation.
`rgetattr`(obj, name[, default])	Recursive version of `getattr`.
`rsetattr`(obj, name, value)	Recursive version of `setattr`.
`url_get`(url[, maxtry, timeout])	Get content of a file via a URL.

Classes

`ContextTimer`([timer, label, action])	A wrapper class for `Timer` that enables its use as a context manager.
`Timer`([labels, default_label, all_label])	Timer class supporting multiple independent labeled timers.

scico.util.rgetattr(obj, name, default=None)[source]#

Recursive version of getattr.

Parameters:

obj (object) – Object with the attribute to be accessed.
name (str) – Path to object in with components delimited by a “.” character.
default (Optional[Any]) – Default value to be returned if the attribute does not exist.

Return type:

Any

Returns:

Attribute value of default if attribute does not exist.

scico.util.rsetattr(obj, name, value)[source]#

Recursive version of setattr.

Parameters:

obj (object) – Object with the attribute to be set.
name (str) – Path to object in with components delimited by a “.” character.
value (Any) – Value to which the attribute is to be set.

scico.util.partial(func, indices, *fixargs, **fixkwargs)[source]#

Flexible partial function creation.

This function is similar to functools.partial, but allows fixing of arbitrary positional arguments rather than just some number of trailing positional arguments.

Parameters:

func (Callable) – Function from which partial function is to be derived.
indices (Sequence) – Tuple of indices of positional args of func that are to be fixed to the values specified in fixargs.
*fixargs (Any) – Fixed values for specified positional arguments.
**fixkwargs (Any) – Fixed values for keyword arguments.

Return type:

Callable

Returns:

The partial function with fixed arguments.

scico.util.device_info(devid=0)[source]#

Get a string describing the specified device.

Parameters:: devid (int) – ID number of device.
Return type:: str
Returns:: Device description string.

scico.util.check_for_tracer(func)[source]#

Check if positional arguments to func are jax tracers.

This is intended to be used as a decorator for functions that call external code from within SCICO. At present, external functions cannot be jit-ed or vmap/pmaped. This decorator checks for signs of jit/vmap/pmap and raises an appropriate exception.

Return type:: Callable

scico.util.url_get(url, maxtry=3, timeout=10)[source]#

Get content of a file via a URL.

Parameters:

url (str) – URL of the file to be downloaded.
maxtry (int) – Maximum number of download retries.
timeout (int) – Timeout in seconds for blocking operations.

Return type:

BytesIO

Returns:

Buffered I/O stream.

Raises:

ValueError – If the maxtry parameter is not greater than zero.
urllib.error.URLError – If the file cannot be downloaded.

class scico.util.Timer(labels=None, default_label='main', all_label='all')[source]#

Bases: object

Timer class supporting multiple independent labeled timers.

The timer is based on the relative time returned by timeit.default_timer.

Parameters:

labels (Union[str, List[str], None]) – Label(s) of the timer(s) to be initialised to zero.
default_label (str) – Default timer label to be used when methods are called without specifying a label.
all_label (str) – Label string that will be used to denote all timer labels.

start(labels=None)[source]#

Start specified timer(s).

Parameters:: labels (Union[str, List[str], None]) – Label(s) of the timer(s) to be started. If it is None, start the default timer with label specified by the default_label parameter of __init__.

stop(labels=None)[source]#

Stop specified timer(s).

Parameters:: labels (Union[str, List[str], None]) – Label(s) of the timer(s) to be stopped. If it is None, stop the default timer with label specified by the default_label parameter of __init__. If it is equal to the string specified by the all_label parameter of __init__, stop all timers.

reset(labels=None)[source]#

Reset specified timer(s).

Parameters:: labels (Union[str, List[str], None]) – Label(s) of the timer(s) to be stopped. If it is None, stop the default timer with label specified by the default_label parameter of __init__. If it is equal to the string specified by the all_label parameter of __init__, stop all timers.

elapsed(label=None, total=True)[source]#

Get elapsed time since timer start.

Parameters:

label (Optional[str]) – Label of the timer for which the elapsed time is required. If it is None, the default timer with label specified by the default_label parameter of __init__ is selected.
total (bool) – If True return the total elapsed time since the first call of start for the selected timer, otherwise return the elapsed time since the most recent call of start for which there has not been a corresponding call to stop.

Return type:

float

Returns:

Elapsed time.

labels()[source]#

Get a list of timer labels.

Return type:: List[str]
Returns:: List of timer labels.

class scico.util.ContextTimer(timer=None, label=None, action='StartStop')[source]#

Bases: object

A wrapper class for Timer that enables its use as a context manager.

For example, instead of

>>> t = Timer()
>>> t.start()
>>> x = sum(range(1000))
>>> t.stop()
>>> elapsed = t.elapsed()

one can use

>>> t = Timer()
>>> with ContextTimer(t):
...   x = sum(range(1000))
>>> elapsed = t.elapsed()

Parameters:

timer (Optional[Timer]) – Timer object to be used as a context manager. If None, a new class:Timer object is constructed.
label (Optional[str]) – Label of the timer to be used. If it is None, start the default timer.
action (str) – Actions to be taken on context entry and exit. If the value is ‘StartStop’, start the timer on entry and stop on exit; if it is ‘StopStart’, stop the timer on entry and start it on exit.

elapsed(total=True)[source]#

Return the elapsed time for the timer.

Parameters:: total (bool) – If True return the total elapsed time since the first call of start for the selected timer, otherwise return the elapsed time since the most recent call of start for which there has not been a corresponding call to stop.
Return type:: float
Returns:: Elapsed time.