Warning

The pyomo.kernel API is still in the beta phase of development. It is fully tested and functional; however, the interface may change as it becomes further integrated with the rest of Pyomo.

Warning

Models built with pyomo.kernel components are not yet compatible with pyomo extension modules (e.g., pyomo.pysp, pyomo.dae, pyomo.gdp).

The Kernel Library

The pyomo.kernel library is an experimental modeling interface designed to provide a better experience for users doing concrete modeling and advanced application development with Pyomo. It includes the basic set of modeling components necessary to build algebraic models, which have been redesigned from the ground up to make it easier for users to customize and extend. For a side-by-side comparison of pyomo.kernel and pyomo.environ syntax, visit the link below.

Models built from pyomo.kernel components are fully compatible with the standard solver interfaces included with Pyomo. A minimal example script that defines and solves a model is shown below.

import pyomo.kernel as pmo

model = pmo.block()
model.x = pmo.variable()
model.c = pmo.constraint(model.x >= 1)
model.o = pmo.objective(model.x)

opt = pmo.SolverFactory("ipopt")

result = opt.solve(model)
assert str(result.solver.termination_condition) == "optimal"

Notable Improvements

More Control of Model Structure

Containers in pyomo.kernel are analogous to indexed components in pyomo.environ. However, pyomo.kernel containers allow for additional layers of structure as they can be nested within each other as long as they have compatible categories. The following example shows this using pyomo.kernel.variable containers.

vlist = pyomo.kernel.variable_list()
vlist.append(pyomo.kernel.variable_dict())
vlist[0]['x'] = pyomo.kernel.variable()

As the next section will show, the standard modeling component containers are also compatible with user-defined classes that derive from the existing modeling components.

Sub-Classing

The existing components and containers in pyomo.kernel are designed to make sub-classing easy. User-defined classes that derive from the standard modeling components and containers in pyomo.kernel are compatible with existing containers of the same component category. As an example, in the following code we see that the pyomo.kernel.block_list container can store both pyomo.kernel.block objects as well as a user-defined Widget object that derives from pyomo.kernel.block. The Widget object can also be placed on another block object as an attribute and treated itself as a block.

class Widget(pyomo.kernel.block):
    ...

model = pyomo.kernel.block()
model.blist = pyomo.kernel.block_list()
model.blist.append(Widget())
model.blist.append(pyomo.kernel.block())
model.w = Widget()
model.w.x = pyomo.kernel.variable()

The next series of examples goes into more detail on how to implement derived components or containers.

The following code block shows a class definition for a non-negative variable, starting from pyomo.kernel.variable as a base class.

class NonNegativeVariable(pyomo.kernel.variable):
    """A non-negative variable."""
    __slots__ = ()

    def __init__(self, **kwds):
        if 'lb' not in kwds:
            kwds['lb'] = 0
        if kwds['lb'] < 0:
            raise ValueError("lower bound must be non-negative")
        super(NonNegativeVariable, self).__init__(**kwds)

    #
    # restrict assignments to x.lb to non-negative numbers
    #
    @property
    def lb(self):
        # calls the base class property getter
        return pyomo.kernel.variable.lb.fget(self)
    @lb.setter
    def lb(self, lb):
        if lb < 0:
            raise ValueError("lower bound must be non-negative")
        # calls the base class property setter
        pyomo.kernel.variable.lb.fset(self, lb)

The NonNegativeVariable class prevents negative values from being stored into its lower bound during initialization or later on through assignment statements (e.g, x.lb = -1 fails). Note that the __slots__ == () line at the beginning of the class definition is optional, but it is recommended if no additional data members are necessary as it reduces the memory requirement of the new variable type.

The next code block defines a custom variable container called Point that represents a 3-dimensional point in Cartesian space. The new type derives from the pyomo.kernel.variable_tuple container and uses the NonNegativeVariable type we defined previously in the z coordinate.

class Point(pyomo.kernel.variable_tuple):
    """A 3-dimensional point in Cartesian space with the
    z coordinate restricted to non-negative values."""
    __slots__ = ()

    def __init__(self):
        super(Point, self).__init__(
            (pyomo.kernel.variable(),
             pyomo.kernel.variable(),
             NonNegativeVariable()))
    @property
    def x(self):
        return self[0]
    @property
    def y(self):
        return self[1]
    @property
    def z(self):
        return self[2]

The Point class can be treated like a tuple storing three variables, and it can be placed inside of other variable containers or added as attributes to blocks. The property methods included in the class definition provide an additional syntax for accessing the three variables it stores, as the next code example will show.

The following code defines a class for building a convex second-order cone constraint from a Point object. It derives from the pyomo.kernel.constraint class, overriding the constructor to build the constraint expression and utilizing the property methods on the point class to increase readability.

class SOC(pyomo.kernel.constraint):
    """A convex second-order cone constraint"""
    __slots__ = ()

    def __init__(self, point):
        assert isinstance(point.z, NonNegativeVariable)
        super(SOC, self).__init__(
            point.x**2 + point.y**2 <= point.z**2)

Reduced Memory Usage

The pyomo.kernel library offers significant opportunities to reduce memory requirements for highly structured models. The situation where this is most apparent is when expressing a model in terms of many small blocks consisting of singleton components. As an example, consider expressing a model consisting of a large number of voltage transformers. One option for doing so might be to define a Transformer component as a subclass of pyomo.kernel.block. The example below defines such a component, including some helper methods for connecting input and output voltage variables and updating the transformer ratio.

class Transformer(pyomo.kernel.block):
    def __init__(self):
        super(Transformer,self).__init__()
        self._a = pyomo.kernel.parameter()
        self._v_in = pyomo.kernel.expression()
        self._v_out = pyomo.kernel.expression()
        self._c = pyomo.kernel.constraint(
            self._a * self._v_out == self._v_in)
    def set_ratio(self, a):
        assert a > 0
        self._a.value = a
    def connect_v_in(self, v_in):
        self._v_in.expr = v_in
    def connect_v_out(self, v_out):
        self._v_out.expr = v_out

A simplified version of this using pyomo.environ components might look like what is below.

def Transformer():
    b = pyomo.environ.Block(concrete=True)
    b._a = pyomo.environ.Param(mutable=True)
    b._v_in = pyomo.environ.Expression()
    b._v_out = pyomo.environ.Expression()
    b._c = pyomo.environ.Constraint(expr=\
        b._a * b._v_out == b._v_in)
    return b

The transformer expressed using pyomo.kernel components requires roughly 2 KB of memory, whereas the pyomo.environ version requires roughly 8.4 KB of memory (an increase of more than 4x). Additionally, the pyomo.kernel transformer is fully compatible with all existing pyomo.kernel block containers.

Direct Support For Conic Constraints with Mosek

Pyomo 5.6.3 introduced support into pyomo.kernel for six conic constraint forms that are directly recognized by the new Mosek solver interface. These are

  • conic.quadratic:

    \(\;\;\sum_{i}x_i^2 \leq r^2,\;\;r\geq 0\)

  • conic.rotated_quadratic:

    \(\;\;\sum_{i}x_i^2 \leq 2 r_1 r_2,\;\;r_1,r_2\geq 0\)

  • conic.primal_exponential:

    \(\;\;x_1\exp(x_2/x_1) \leq r,\;\;x_1,r\geq 0\)

  • conic.primal_power (\(\alpha\) is a constant):

    \(\;\;||x||_2 \leq r_1^{\alpha} r_2^{1-\alpha},\;\;r_1,r_2\geq 0,\;0 < \alpha < 1\)

  • conic.dual_exponential:

    \(\;\;-x_2\exp((x_1/x_2)-1) \leq r,\;\;x_2\leq0,\;r\geq 0\)

  • conic.dual_power (\(\alpha\) is a constant):

    \(\;\;||x||_2 \leq (r_1/\alpha)^{\alpha} (r_2/(1-\alpha))^{1-\alpha},\;\;r_1,r_2\geq 0,\;0 < \alpha < 1\)

Other solver interfaces will treat these objects as general nonlinear or quadratic constraints, and may or may not have the ability to identify their convexity. For instance, Gurobi will recognize the expressions produced by the quadratic and rotated_quadratic objects as representing convex domains as long as the variables involved satisfy the convexity conditions. However, other solvers may not include this functionality.

Each of these conic constraint classes are of the same category type as standard pyomo.kernel.constraint object, and, thus, are directly supported by the standard constraint containers (constraint_tuple, constraint_list, constraint_dict).

Each conic constraint class supports two methods of instantiation. The first method is to directly instantiate a conic constraint object, providing all necessary input variables:

import pyomo.kernel as pmo
m = pmo.block()
m.x1 = pmo.variable(lb=0)
m.x2 = pmo.variable()
m.r = pmo.variable(lb=0)
m.q = pmo.conic.primal_exponential(
    x1=m.x1,
    x2=m.x2,
    r=m.r)

This method may be limiting if utilizing the Mosek solver as the user must ensure that additional conic constraints do not use variables that are directly involved in any existing conic constraints (this is a limitation the Mosek solver itself).

To overcome this limitation, and to provide a more general way of defining conic domains, each conic constraint class provides the as_domain class method. This alternate constructor has the same argument signature as the class, but in place of each variable, one can optionally provide a constant, a linear expression, or None. The as_domain class method returns a block object that includes the core conic constraint, auxiliary variables used to express the conic constraint, as well as auxiliary constraints that link the inputs (that are not None) to the auxiliary variables. Example:

import pyomo.kernel as pmo
import math
m = pmo.block()
m.x = pmo.variable(lb=0)
m.y = pmo.variable(lb=0)
m.b = pmo.conic.primal_exponential.as_domain(
    x1=math.sqrt(2)*m.x,
    x2=2.0,
    r=2*(m.x + m.y))