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
- 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]]
extension of
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)
-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]]
extension of
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
-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
- 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
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