Constant data types

CVXlab supports a variety of constants data types

There are two ways to add a new user-defined constant:

1. Add a new constant directly in the current module cvxlab.support.util_constants: simply define a new function in this module, that will be embedded in the package as a built-in constant.

2. Users can define custom constants in their model directory by defining the related function in the ‘user_defined_constants.py’ file, and loading the module when generating the Model instance. This way, users can extend the package with their own custom constants without modifying the package code (ideal for model users).

Built-in constants types reference

Module with user defined functions defined as model’s constants.

This module provides various utility functions that are defined to support complex calculations in symbolic problems through generation of constants types, such as generating special matrices (positive semidefinite matrices).

Functions are registered as constants in Defaults class, and actual constants data are generated when generating variables (see backend.Variable.define_constant() method).

cvxlab.support.util_constants.arange(dimension: List[int], start_from: int, order: str = 'F') → array

Define a reshaped range array.

Generate a reshaped array with values ranging from ‘start_from’ to ‘start_from + total_elements’. Notice that this function is not directly registered as a constant, but it is used to define other constants (e.g., arange_0)

Parameters:

• shape_size (Iterable[int]) – The shape of the output array.

• start_from (int, optional) – The starting value for the range.

• order (str, optional) – The order of the reshaped array. Defaults to ‘F’.

Returns:

The reshaped array with values ranging from ‘start_from’

to ‘start_from + total_elements’.

Return type:

np.ndarray

Raises:

• exc.SettingsError – If passed dimension is not a list containing integers.

• ValueError – If ‘start_from’ is not an integer.

• ValueError – If ‘order’ is not a string or not in [‘C’, ‘F’].

cvxlab.support.util_constants.arange_0(dimension: List[int]) → ndarray

Define a reshaped range array starting from zero.

cvxlab.support.util_constants.constant(name: str) → callable

Decorator to register a constant generation function.

Parameters:

name (str) – The name of the constant to register.

Returns:

The decorated function.

Return type:

callable

cvxlab.support.util_constants.identity_matrix(dimension: List[int]) → array

Generate a square identity matrix of size n x n.

Parameters:

dimension (List[int]) – A list [n, n] with two equal positive integers.

Returns:

An n x n identity matrix.

Return type:

np.ndarray

Raises:

exc.SettingsError – If ‘dimension’ is not [n, n] with equal positive ints.

cvxlab.support.util_constants.lower_triangular_matrix(dimension: List[int]) → array

Define a lower triangular matrix.

Generate a square matrix with ones in the lower triangular region (including the diagonal) and zeros elsewhere.

Parameters:

dimension (List[int]) – The dimension of the matrix row/col.

Returns:

A square matrix with ones in the lower triangular region

and zeros elsewhere.

Return type:

np.ndarray

Raises:

exc.SettingsError – If passed dimension is not a list containing integers, or if it does not represent a vector (i.e., at least one element must be equal to 1).

cvxlab.support.util_constants.set_length(dimension: List[int]) → array

Define the length of a set as a constant.

Parameters:

dimension (List[int]) – The dimension of the vector (rows, cols).

Returns:

A 1x1 array (scalar) containing the length of the set.

Return type:

np.ndarray

Raises:

exc.SettingsError – If passed dimension is not a list containing integers, or if it does not represent a vector (i.e., at least one element must be equal to 1).

cvxlab.support.util_constants.sum_vector(dimension: List[int]) → ndarray

Define a vector of ones for matrix summation operations.

Parameters:

dimension (List[int]) – The dimension of the vector (rows, cols).

Returns:

A vector of ones with the specified dimension.

Return type:

np.ndarray

Raises:

exc.SettingsError – If passed dimension is not a list containing integers, or if it does not represent a vector (i.e., at least one element must be equal to 1).