Module utils

This module contains some utility programs used by the package.

utils.ScalarFunctionAndGradient

Type of f(v, args, gr) that returns a scalar value and also a gradient if gr is True

alias of Callable[[numpy.ndarray, List, Optional[bool]], Union[float, Tuple[float, numpy.ndarray]]]

utils.bs_error_abort(msg: str = 'error, aborting')

Report error and exits with code 1

Parameters

msg – specifies the error message

Returns

nothing

utils.bs_name_func(back: int = 2)

Get the name of the current function, or further back in the stack

Parameters

back – 2 for the current function, 3 for the function that called it, etc

Returns

the name of the function requested

utils.check_gradient_scalar_function(fg: Callable[[numpy.ndarray, List, Optional[bool]], Union[float, Tuple[float, numpy.ndarray]]], p: numpy.ndarray, args: List, mode: str = 'central', EPS: float = 1e-06) Tuple[numpy.ndarray, numpy.ndarray]

Checks the gradient of a scalar function.

Parameters
  • fg – should return the scalar value, and the gradient if its gr argument is True

  • p – where we are checking the gradient

  • args – other arguments passed to fg

  • mode – “central” or “forward” derivatives

  • EPS – the step for forward or central derivatives

Returns

the analytic and numeric gradients

utils.der_nppow(a: numpy.array, b: Union[int, float, numpy.array]) numpy.array

evaluates the derivatives in a and b of element-by-element a^b

Parameters
  • a (np.array) –

  • b (Union[int, float, np.array]) – if an array, should have the same shape as a

Returns

a pair of two arrays of the same shape as a

utils.describe_array(v: numpy.ndarray, name: str = 'The array') collections.namedtuple

Descriptive statistics on an array interpreted as a vector

Parameters
  • v – the array

  • name – its name

Returns

a DescribeResult namedtuple

utils.npexp(a: numpy.ndarray, deriv: bool = False, bigx: float = 30.0, verbose: bool = False) Union[numpy.ndarray, Tuple[numpy.ndarray, numpy.ndarray]]

C^2 extension of \exp(a) above bigx

Parameters
  • a – a Numpy array

  • deriv – if True, the first derivative is also returned

  • bigx – an upper bound

  • verbose – whether diagnoses are printed

Returns

upper bound:math:exp(a) C^2-extended above bigx, with its derivative if deriv

Return type

bigx

utils.nplog(a: numpy.ndarray, deriv: bool = False, eps: float = 1e-30, verbose: bool = False) Union[numpy.ndarray, Tuple[numpy.ndarray, numpy.ndarray]]

C^2 extension of \ln(a) below eps

Parameters
  • a – a Numpy array

  • deriv – if True, the first derivative is also returned

  • eps – a lower bound

  • verbose – whether diagnoses are printed

Returns

\ln(a) C^2-extended below eps, with its derivative if deriv

utils.npmaxabs(a: numpy.ndarray) float

The maximum absolute value in an array

Parameters

a – the array

Returns

\max{\vert a \vert}

utils.nppow(a: numpy.ndarray, b: Union[int, float, numpy.ndarray], deriv: bool = False) Union[numpy.array, Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]]

Evaluates a^b element-by-element

Parameters
  • a – a Numpy array

  • b – if an array, it should have the same shape as a

  • deriv – if True, the first derivatives wrt a and b are also returned

Returns

an array of the same shape as a, and if deriv is True, the derivatives wrt a and b

utils.nprepeat_col(v: numpy.ndarray, n: int) numpy.ndarray

Creates a matrix with n columns, all equal to v

Parameters
  • v – a vector of size m

  • n – the number of columns requested

Returns

a matrix of shape (m, n)

utils.nprepeat_row(v: numpy.ndarray, m: int) numpy.ndarray

Creates a matrix with m rows, all equal to v

Parameters
  • v – a vector of size n

  • m – the number of rows requested

Returns

a matrix of shape (m, n)

utils.print_stars(title: Optional[str] = None, n: int = 70) None

Prints a starred line, or two around the title

Parameters
  • title – an optional title

  • n – the number of stars on the line

Returns

nothing

utils.test_matrix(x: numpy.ndarray, fun_name: Optional[str] = None) Tuple[int, int]

Tests that x is a matrix; aborts otherwise

Parameters
  • x – a potential matrix

  • fun_name – the name of the calling function

Returns

the shape of x if it is a matrix

utils.test_vector(x: numpy.ndarray, fun_name: Optional[str] = None) int

Tests that x is a vector; aborts otherwise

Parameters
  • x – a potential vector

  • fun_name – the name of the calling function

Returns

the size of x if it is a vector