Signomial objects

class sageopt.symbolic.signomials.Signomial(alpha_maybe_c, c=None)

This class provides a symbolic representation for linear combinations of exponentials, composed with linear functions. These functions look like the following.

\[x \mapsto \sum_{i=1}^m c_i \exp({\alpha}_i \cdot x)\]

The constructor for this class can be called in two different ways. The arguments to the constructor have names which reflect the different possibilities.

Parameters

  • alpha_maybe_c (dict or NumPy ndarray) –

    If alpha_maybe_c is a dict, then it must be a dictionary from tuples-of-numbers to scalars. The keys will be converted to rows of a matrix which we call alpha, and the values will be assembled into a vector which we call c.

    If alpha_maybe_c is a NumPy ndarray, then the argument c must also be an ndarray, and c.size must equal alpha_maybe_c.shape[0].

  • c (None or NumPy ndarray) – This value is only used when alpha_maybe_c is a NumPy ndarray. If that is the case, then this Signomial will represent the function lambda x: c @ np.exp(alpha_maybe_c @ x).

Examples

There are two ways to call the Signomial constructor.

The first way is to specify a dictionary from tuples to scalars. The tuples are interpreted as linear functionals appearing in the exponential terms, and the scalars are the corresponding coefficients.:

alpha_and_c = {(1,): 2}
f = Signomial(alpha_and_c)
print(f(1))  # equal to 2 * np.exp(1).
print(f(0))  # equal to 2.

The second way is to specify two arguments. In this case the first argument is a NumPy array where the rows represent linear functionals, and the second argument is a vector of corresponding coefficients.:

alpha = np.array([[1, 0], [0, 1], [1, 1]])
c = np.array([1, 2, 3])
f = Signomial(alpha, c)
x = np.random.randn(2)
print(f(x) - c @ np.exp(alpha @ x))  # zero, up to rounding errors.
n

The dimension of the space over which this Signomial is defined. The number of columns in alpha, and the length of tuples appearing in the dictionary alpha_c.

Type

int

m

The number of terms needed to express this Signomial in a basis of monomial functions lambda x: exp(a @ x) for row vectors a. The signomial is presumed to include a constant term.

Type

int

alpha

Has shape (m, n). Each row specifies a vector appearing in an exponential function which defines this Signomial. The rows are ordered for consistency with the property c.

Type

NumPy ndarray

c

Has shape (m,). The scalar c[i] is this Signomial’s coefficient on the basis function lambda x: exp(alpha[i, :] @ x). It is possible to have c.dtype == object.

Type

NumPy ndarray

alpha_c

The keys of alpha_c are tuples of length n, containing real numeric types (e.g int, float). These tuples define linear functions. This Signomial could be evaluated by the code snippet lambda x: np.sum([ alpha_c[a] * np.exp(a @ x) for a in alpha_c]). The default value for this dictionary is zero.

Type

defaultdict

Notes

Operator overloading.

The Signomial class implements +, -, *, and ** between pairs of Signomials, and pairs involving one Signomial and one numeric type.

The Signomial class also implements s1 / s2 where s2 is a numeric type or Signomial, but if s2 is a Signomial, then its coefficient vector s2.c can only contain one nonzero entry.

You can also use +, -, and * for pairs involving one Signomial and one non-Signomial. If s3 is the result of such an operation, then s3.c will be a NumPy array with s3.dtype == object.

Function evaluations.

Signomial objects are callable. If s is a Signomial object and x is a numpy array of length s.n, then s(x) computes the Signomial object as though it were any other elementary Python function.

Signomial objects provide functions to compute gradients (equivalently, Jacobians) and Hessians. These methods operate by caching and evaluating symbolic representations of the relevant partial derivatives.

Internal representations.

Both self.alpha_c and (self.alpha, self.c) completely specify a Signomial object.

alpha_c is the dictionary which is taken to define this Signomial as a mathematical object.

However, it is useful to have rapid access to the matrix of linear functionals alpha, or the coefficient vector c as numpy arrays. So these fields are also maintained explicitly.

If a user modifies the fields alpha or c directly, there may be an inconsistency between these fields, and the dictionary alpha_c. Therefore the fields alpha and c should not be modified without taking great care to ensure consistency with the signomial’s dictionary representation.

as_polynomial()

This function is only applicable if alpha is a matrix of nonnegative integers.

Returns

f – For every elementwise vector x, we have self(x) == f(np.exp(x)).

Return type

Polynomial

constant_location()

Return the index i so that alpha[i, :] is the zero vector.

property grad

A numpy ndarray of shape (n,) whose entries are Signomials. For a numpy ndarray x, grad[i](x) is the partial derivative of this Signomial with respect to coordinate i, evaluated at x. This array is constructed only when necessary, and is cached upon construction.

grad_val(x)

Return the gradient of this Signomial (as a NumPy ndarray) at the point x.

property hess

A numpy ndarray of shape (n, n), whose entries are Signomials. For a numpy ndarray x, hess[i,j](x) is the (i,j)-th partial derivative of this Signomial, evaluated at x. This array is constructed only when necessary, and is cached upon construction.

hess_val(x)

Return the Hessian of this Signomial (as a NumPy ndarray) at the point x.

partial(i)

Compute the symbolic partial derivative of this signomial, at coordinate i.

Parameters

i (int) – i must be an integer from 0 to self.n - 1.

Returns

p – The function obtained by differentiating this signomial with respect to its i-th argument.

Return type

Signomial

query_coeff(a)

Returns the coefficient of the basis function lambda x: np.exp(a @ x) for this Signomial.

remove_terms_with_zero_as_coefficient()

Update alpha, c, and alpha_c to remove nonconstant terms where c[i] == 0.

signomials.standard_sig_monomials()
Parameters

n (int) – The dimension of the space over which the constituent Signomials will be defined.

Returns

y – An array of length n, with y[i] as a Signomial with one term, corresponding to the (i+1)-th standard basis vector in n dimensional real space.

Return type

NumPy ndarray

Example

This function is useful for constructing signomials in an algebraic form.

y = standard_sig_monomials(3)
f = (y[0] ** 1.5) * (y[2] ** -0.6) - y[1] * y[2]