Utility functions

estimagic.utilities.cov_params_to_matrix(cov_params)

Build covariance matrix from 1d array with its lower triangular elements.

Parameters

cov_params (np.array) – 1d array with the lower triangular elements of a covariance matrix (in C-order)

Returns

a covariance matrix

Return type

cov (np.array)

estimagic.utilities.sdcorr_params_to_matrix(sdcorr_params)

Build covariance matrix out of variances and correlations.

Parameters

sdcorr_params (np.array) – 1d array with parameters. The dimensions of the covariance matrix are inferred automatically. The first dim parameters are assumed to be the variances. The remainder are the lower triangular elements (excluding the diagonal) of a correlation matrix.

Returns

a covariance matrix

Return type

cov (np.array)

estimagic.utilities.number_of_triangular_elements_to_dimension(num)

Calculate the dimension of a square matrix from number of triangular elements.

Parameters

num (int) – The number of upper or lower triangular elements in the matrix.

Examples

>>> number_of_triangular_elements_to_dimension(6)
3
>>> number_of_triangular_elements_to_dimension(10)
4

estimagic.utilities.dimension_to_number_of_triangular_elements(dim)

Calculate number of triangular elements from the dimension of a square matrix.

Parameters

dim (int) – Dimension of a square matrix.

estimagic.utilities.propose_alternatives(requested, possibilities, number=3)

Propose possible alternatives based on similarity to requested.

Parameters

• requested_algo (str) – From the user requested algorithm.

• possibilities (list(str)) – List of available algorithms are lists of algorithms.

• number (int) – Number of proposals.

Returns

List of proposed algorithms.

Return type

proposals (list(str))

Example

>>> possibilities = ["scipy_lbfgsb", "scipy_slsqp", "nlopt_lbfgsb"]
>>> propose_alternatives("scipy_L-BFGS-B", possibilities, number=1)
['scipy_slsqp']
>>> propose_alternatives("L-BFGS-B", possibilities, number=2)
['scipy_slsqp', 'scipy_lbfgsb']

estimagic.utilities.robust_cholesky(matrix, threshold=None, return_info=False)

Lower triangular cholesky factor of matrix.

Parameters

• matrix (np.array) – Square, symmetric and (almost) positive semi-definite matrix

• threshold (float) – Small negative number. Diagonal elements of D from the LDL decomposition between threshold and zero are set to zero. Default is minus machine accuracy.

• return_info (bool) – If True, also return a dictionary with ‘method’. Method can take the values ‘np.linalg.cholesky’ and ‘Eigenvalue QR’.

Returns

Cholesky factor of matrix info (float, optional): see return_info.

Return type

chol (np.array)

Raises

np.linalg.LinalgError if an eigenvalue of matrix is below threshold. –

In contrast to a regular cholesky decomposition, this function will also work for matrices that are only positive semi-definite or even indefinite. For speed and precision reasons we first try a regular cholesky decomposition. If it fails we switch to more robust methods.

estimagic.utilities.robust_inverse(matrix, msg='')

Calculate the inverse or pseudo-inverse of a matrix.

The difference to calling a pseudo inverse directly is that this function will emit a warning if the matrix is singular.

Parameters

matrix (np.ndarray) –

estimagic.utilities.hash_array(arr)

Create a hashsum for fast comparison of numpy arrays.

estimagic.utilities.calculate_trustregion_initial_radius(x)

Calculate the initial trust region radius.

It is calculated as \(0.1\max(|x|_{\infty}, 1)\).

Parameters

x (np.ndarray) – the start parameter values.

Returns

initial trust radius

Return type

trust_radius (float)

estimagic.utilities.isscalar(element)

Jax aware replacement for np.isscalar.

estimagic.utilities.get_rng(seed)

Construct a random number generator.

seed (Union[None, int, numpy.random.Generator]): If seed is None or int the

numpy.random.default_rng is used seeded with seed. If seed is already a Generator instance then that instance is used.

Returns

The random number generator.

Return type

numpy.random.Generator