Single-variate Piecewise Functions

Summary

pyomo.core.kernel.piecewise_library.transforms.piecewise(...)	Models a single-variate piecewise linear function.
pyomo.core.kernel.piecewise_library.transforms.PiecewiseLinearFunction(...)	A piecewise linear function
pyomo.core.kernel.piecewise_library.transforms.TransformedPiecewiseLinearFunction(f)	Base class for transformed piecewise linear functions
pyomo.core.kernel.piecewise_library.transforms.piecewise_convex(...)	Simple convex piecewise representation
pyomo.core.kernel.piecewise_library.transforms.piecewise_sos2(...)	Discrete SOS2 piecewise representation
pyomo.core.kernel.piecewise_library.transforms.piecewise_dcc(...)	Discrete DCC piecewise representation
pyomo.core.kernel.piecewise_library.transforms.piecewise_cc(...)	Discrete CC piecewise representation
pyomo.core.kernel.piecewise_library.transforms.piecewise_mc(...)	Discrete MC piecewise representation
pyomo.core.kernel.piecewise_library.transforms.piecewise_inc(...)	Discrete INC piecewise representation
pyomo.core.kernel.piecewise_library.transforms.piecewise_dlog(...)	Discrete DLOG piecewise representation
pyomo.core.kernel.piecewise_library.transforms.piecewise_log(...)	Discrete LOG piecewise representation

Member Documentation

pyomo.core.kernel.piecewise_library.transforms.piecewise(breakpoints, values, input=None, output=None, bound='eq', repn='sos2', validate=True, simplify=True, equal_slopes_tolerance=1e-06, require_bounded_input_variable=True, require_variable_domain_coverage=True)

Models a single-variate piecewise linear function.

This function takes a list breakpoints and function values describing a piecewise linear function and transforms this input data into a block of variables and constraints that enforce a piecewise linear relationship between an input variable and an output variable. In the general case, this transformation requires the use of discrete decision variables.

Parameters:

• breakpoints (list) – The list of breakpoints of the piecewise linear function. This can be a list of numbers or a list of objects that store mutable data (e.g., mutable parameters). If mutable data is used validation might need to be disabled by setting the validate keyword to False. The list of breakpoints must be in non-decreasing order.

• values (list) – The values of the piecewise linear function corresponding to the breakpoints.

• input – The variable constrained to be the input of the piecewise linear function.

• output – The variable constrained to be the output of the piecewise linear function.

• bound (str) –

  The type of bound to impose on the output expression. Can be one of:

  • ’lb’: y <= f(x)

  • ’eq’: y = f(x)

  • ’ub’: y >= f(x)

• repn (str) –

  The type of piecewise representation to use. Choices are shown below (+ means step functions are supported)

  • ’sos2’: standard representation using sos2 constraints (+)

  • ’dcc’: disaggregated convex combination (+)

  • ’dlog’: logarithmic disaggregated convex combination (+)

  • ’cc’: convex combination (+)

  • ’log’: logarithmic branching convex combination (+)

  • ’mc’: multiple choice

  • ’inc’: incremental method (+)

• validate (bool) – Indicates whether or not to perform validation of the input data. The default is True. Validation can be performed manually after the piecewise object is created by calling the validate() method. Validation should be performed any time the inputs are changed (e.g., when using mutable parameters in the breakpoints list or when the input variable changes).

• simplify (bool) – Indicates whether or not to attempt to simplify the piecewise representation to avoid using discrete variables. This can be done when the feasible region for the output variable, with respect to the piecewise function and the bound type, is a convex set. Default is True. Validation is required to perform simplification, so this keyword is ignored when the validate keyword is False.

• equal_slopes_tolerance (float) – Tolerance used check if consecutive slopes are nearly equal. If any are found, validation will fail. Default is 1e-6. This keyword is ignored when the validate keyword is False.

• require_bounded_input_variable (bool) – Indicates if the input variable is required to have finite upper and lower bounds. Default is True. Setting this keyword to False can be used to allow general expressions to be used as the input in place of a variable. This keyword is ignored when the validate keyword is False.

• require_variable_domain_coverage (bool) – Indicates if the function domain (defined by the endpoints of the breakpoints list) needs to cover the entire domain of the input variable. Default is True. Ignored for any bounds of variables that are not finite, or when the input is not assigned a variable. This keyword is ignored when the validate keyword is False.

Returns:

a block that

stores any new variables, constraints, and other modeling objects used by the piecewise representation

Return type:

TransformedPiecewiseLinearFunction

class pyomo.core.kernel.piecewise_library.transforms.PiecewiseLinearFunction(breakpoints, values, validate=True, **kwds)

Bases: object

A piecewise linear function

Piecewise linear functions are defined by a list of breakpoints and a list function values corresponding to each breakpoint. The function value between breakpoints is implied through linear interpolation.

Parameters:

• breakpoints (list) – The list of function breakpoints.

• values (list) – The list of function values (one for each breakpoint).

• validate (bool) – Indicates whether or not to perform validation of the input data. The default is True. Validation can be performed manually after the piecewise object is created by calling the validate() method. Validation should be performed any time the inputs are changed (e.g., when using mutable parameters in the breakpoints list).

• **kwds – Additional keywords are passed to the validate() method when the validate keyword is True; otherwise, they are ignored.

__call__(x)

Evaluates the piecewise linear function at the given point using interpolation. Note that step functions are assumed lower-semicontinuous.

property breakpoints

The set of breakpoints used to defined this function

validate(equal_slopes_tolerance=1e-06)

Validate this piecewise linear function by verifying various properties of the breakpoints and values lists (e.g., that the list of breakpoints is nondecreasing).

Parameters:

equal_slopes_tolerance (float) – Tolerance used check if consecutive slopes are nearly equal. If any are found, validation will fail. Default is 1e-6.

Returns:

a function characterization code (see util.characterize_function())

Return type:

int

Raises:

PiecewiseValidationError – if validation fails

property values

The set of values used to defined this function

class pyomo.core.kernel.piecewise_library.transforms.TransformedPiecewiseLinearFunction(f, input=None, output=None, bound='eq', validate=True, **kwds)

Bases: block

Base class for transformed piecewise linear functions

A transformed piecewise linear functions is a block of variables and constraints that enforce a piecewise linear relationship between an input variable and an output variable.

Parameters:

• f (PiecewiseLinearFunction) – The piecewise linear function to transform.

• input – The variable constrained to be the input of the piecewise linear function.

• output – The variable constrained to be the output of the piecewise linear function.

• bound (str) –

  The type of bound to impose on the output expression. Can be one of:

  • ’lb’: y <= f(x)

  • ’eq’: y = f(x)

  • ’ub’: y >= f(x)

• validate (bool) – Indicates whether or not to perform validation of the input data. The default is True. Validation can be performed manually after the piecewise object is created by calling the validate() method. Validation should be performed any time the inputs are changed (e.g., when using mutable parameters in the breakpoints list or when the input variable changes).

• **kwds – Additional keywords are passed to the validate() method when the validate keyword is True; otherwise, they are ignored.

__call__(x)

Evaluates the piecewise linear function at the given point using interpolation

property bound

The bound type assigned to the piecewise relationship (‘lb’,’ub’,’eq’).

property breakpoints

The set of breakpoints used to defined this function

property input

The expression that stores the input to the piecewise function. The returned object can be updated by assigning to its expr attribute.

property output

The expression that stores the output of the piecewise function. The returned object can be updated by assigning to its expr attribute.

validate(equal_slopes_tolerance=1e-06, require_bounded_input_variable=True, require_variable_domain_coverage=True)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

Parameters:

• equal_slopes_tolerance (float) – Tolerance used check if consecutive slopes are nearly equal. If any are found, validation will fail. Default is 1e-6.

• require_bounded_input_variable (bool) – Indicates if the input variable is required to have finite upper and lower bounds. Default is True. Setting this keyword to False can be used to allow general expressions to be used as the input in place of a variable.

• require_variable_domain_coverage (bool) – Indicates if the function domain (defined by the endpoints of the breakpoints list) needs to cover the entire domain of the input variable. Default is True. Ignored for any bounds of variables that are not finite, or when the input is not assigned a variable.

Returns:

a function characterization code (see util.characterize_function())

Return type:

int

Raises:

PiecewiseValidationError – if validation fails

property values

The set of values used to defined this function

class pyomo.core.kernel.piecewise_library.transforms.piecewise_convex(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Simple convex piecewise representation

Expresses a piecewise linear function with a convex feasible region for the output variable using a simple collection of linear constraints.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.

class pyomo.core.kernel.piecewise_library.transforms.piecewise_sos2(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Discrete SOS2 piecewise representation

Expresses a piecewise linear function using the SOS2 formulation.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.

class pyomo.core.kernel.piecewise_library.transforms.piecewise_dcc(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Discrete DCC piecewise representation

Expresses a piecewise linear function using the DCC formulation.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.

class pyomo.core.kernel.piecewise_library.transforms.piecewise_cc(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Discrete CC piecewise representation

Expresses a piecewise linear function using the CC formulation.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.

class pyomo.core.kernel.piecewise_library.transforms.piecewise_mc(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Discrete MC piecewise representation

Expresses a piecewise linear function using the MC formulation.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.

class pyomo.core.kernel.piecewise_library.transforms.piecewise_inc(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Discrete INC piecewise representation

Expresses a piecewise linear function using the INC formulation.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.

class pyomo.core.kernel.piecewise_library.transforms.piecewise_dlog(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Discrete DLOG piecewise representation

Expresses a piecewise linear function using the DLOG formulation. This formulation uses logarithmic number of discrete variables in terms of number of breakpoints.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.

class pyomo.core.kernel.piecewise_library.transforms.piecewise_log(*args, **kwds)

Bases: TransformedPiecewiseLinearFunction

Discrete LOG piecewise representation

Expresses a piecewise linear function using the LOG formulation. This formulation uses logarithmic number of discrete variables in terms of number of breakpoints.

validate(**kwds)

Validate this piecewise linear function by verifying various properties of the breakpoints, values, and input variable (e.g., that the list of breakpoints is nondecreasing).

See base class documentation for keyword descriptions.