Using sageopt with GPKit

GPKit is a python package which makes it easy for engineers to use signomial and geometric programming models in their design workflow. Sageopt provides basic functionality to interact with GPKit. At present, this functionality is contained in a single function: sageopt.interop.gpkit.gpkit_model_to_sageopt_model. That function accepts a GPKit Model object, and returns a dict of the form:

so_mod = {
    'vkmap': vkmap,
    'f': f,
    'gp_eqs': gp_eqs,
    'sp_eqs': sp_eqs,
    'gp_gts': gp_gts,
    'sp_gts': sp_gts
}

To interpret this dict it is important to consider a few ways that sageopt differs from GPKit.

• Sageopt does not have natively have “Variable” objects for building signomial programs. The closest sageopt approximation is sageopt.standard_sig_monomials(), which takes a parameter \(n\), and returns a length-\(n\) array y of Signomial objects, where y[i] represents the signomial y[i](x) = exp(x[i]). One can say that the variables in sageopt Signomial objects are implicit.

• Sageopt works with a single vectorized decision variable, while GPKit allows users to declare many named variables of different shapes for use in the same model. The return value so_mod['vkmap'] helps reconcile this difference. Specifically, vkmap is a dict which maps a GPKit VarKey object into a numpy array of indices where the GPKit Variable occurs in sageopt’s implicit vectorized model.

• GPKit models are stated with “geometric form” signomials – i.e. expressions like \(y_1 \sqrt{y_2} - y_3^{-2/3} + y_4^2 - y_2\), while sageopt refers to signomials in exponential form. It is easy to move back and forth between these two conventions; if you use sageopt to find a solution vector x to a signomial program, then you can map that into a format GPKit expects by working with y = np.exp(x).

For the remaining key-value pairs in so_mod:

• \(f\) is the objective function to minimize.

• \(\phi \in \mathtt{gp{\_}eqs}\) represents a convex constraint \(\phi(x) = 0\). These constraint functions have exactly one positive term and exactly one negative term.

• \(\phi \in \mathtt{sp{\_}eqs}\) represents a nonconvex constraint \(\phi(x) = 0\).

• \(g \in \mathtt{gp{\_}gts}\) represents a convex constraint \(g(x) \geq 0\). Each function \(g\) has exactly one positive term, with remaining terms being negative.

• \(g \in \mathtt{sp{\_}gts}\) represents a constraint \(g(x) \geq 0\) which doesn’t fall into the above category.

The prefix gp indicates compatibility with geometric programming, and the prefix sp indicates that general signomial programming is required. The suffix eqs refers to equality constraints, while gts refers to constraint functions which must be greater than or equal to zero.

The examples page demonstrates how to use this data in an existing GPKit workflow.