Singlevariate Piecewise Functions¶
Summary¶
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=1e06, require_bounded_input_variable=True, require_variable_domain_coverage=True)[source]¶ Models a singlevariate 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 toFalse
. The list of breakpoints must be in nondecreasing 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 thevalidate()
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 thevalidate
keyword isFalse
.  equal_slopes_tolerance (float) – Tolerance used check
if consecutive slopes are nearly equal. If any
are found, validation will fail. Default is
1e6. This keyword is ignored when the
validate
keyword isFalse
.  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 toFalse
can be used to allow general expressions to be used as the input in place of a variable. This keyword is ignored when thevalidate
keyword isFalse
.  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 thevalidate
keyword isFalse
.
Returns: a block that stores any new variables, constraints, and other modeling objects used by the piecewise representation
Return type:  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

class
pyomo.core.kernel.piecewise_library.transforms.
PiecewiseLinearFunction
(breakpoints, values, validate=True, **kwds)[source]¶ 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 thevalidate()
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 thevalidate
keyword isTrue
; otherwise, they are ignored.

__call__
(x)[source]¶ Evaluates the piecewise linear function at the given point using interpolation. Note that step functions are assumed lowersemicontinuous.

breakpoints
¶ The set of breakpoints used to defined this function

validate
(equal_slopes_tolerance=1e06)[source]¶ 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 1e6. Returns: a function characterization code (see util.characterize_function()
)Return type: int Raises: PiecewiseValidationError
– if validation fails

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)[source]¶ Bases:
pyomo.core.kernel.block.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 thevalidate()
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 thevalidate
keyword isTrue
; otherwise, they are ignored.

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

breakpoints
¶ The set of breakpoints used to defined this function

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

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=1e06, require_bounded_input_variable=True, require_variable_domain_coverage=True)[source]¶ 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 1e6.
 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 toFalse
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

values
¶ The set of values used to defined this function
 f (

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_convex
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.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.

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_sos2
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.TransformedPiecewiseLinearFunction
Discrete SOS2 piecewise representation
Expresses a piecewise linear function using the SOS2 formulation.

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_dcc
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.TransformedPiecewiseLinearFunction
Discrete DCC piecewise representation
Expresses a piecewise linear function using the DCC formulation.

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_cc
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.TransformedPiecewiseLinearFunction
Discrete CC piecewise representation
Expresses a piecewise linear function using the CC formulation.

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_mc
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.TransformedPiecewiseLinearFunction
Discrete MC piecewise representation
Expresses a piecewise linear function using the MC formulation.

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_inc
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.TransformedPiecewiseLinearFunction
Discrete INC piecewise representation
Expresses a piecewise linear function using the INC formulation.

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_dlog
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.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.

class
pyomo.core.kernel.piecewise_library.transforms.
piecewise_log
(*args, **kwds)[source]¶ Bases:
pyomo.core.kernel.piecewise_library.transforms.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.