Constant data types#

CVXlab supports a variety of built-in constants data types (see next section). In defining models, it may be necessary to define other constants. This can be accomplished the following two ways:

  1. Local user-defined constants. Ideal for model users, whihc can define custom constants in local model directory by defining the related function in the user_defined_constants.py module, that will be automatically loaded in generating Model class instance. This way, users can extend the package with their own custom constants without modifying the package code (ideal for model users). See user defined constants template for detailed instructions on how to define and use local user-defined constants.

  2. Adding new built-in constant. Adding a new constant directly in the current package module cvxlab.support.util_constants simply defines a new function in this module, that will be embedded in the package as a built-in constant. This approach is ideal only in case a constant is expected to be widely used across different models and 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, start_from, order='F')[source]#

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’.

  • dimension (List[int])

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)[source]#

Define a reshaped range array starting from zero.

Parameters:

dimension (List[int])

Return type:

ndarray

cvxlab.support.util_constants.constant(name)[source]#

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)[source]#

Generate a square identity matrix of size n x n.

Parameters:

dimension (List[int]) – Either [n, n] for an n by n matrix, or [n, 1] or [1, n] for a vector.

Returns:

An n x n identity matrix.

Return type:

np.ndarray

Raises:

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

cvxlab.support.util_constants.lower_triangular_matrix(dimension)[source]#

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)[source]#

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)[source]#

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).