Single-variate 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=1e-06, require_bounded_input_variable=True, require_variable_domain_coverage=True)[source]
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 toFalse
. 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 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 1e-6. 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:
- 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 lower-semicontinuous.
- property breakpoints
The set of breakpoints used to defined this function
- validate(equal_slopes_tolerance=1e-06)[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 1e-6.
- Returns:
a function characterization code (see
util.characterize_function()
)- Return type:
- 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)[source]
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 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.
- 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)[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 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 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:
- 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)[source]
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.
- class pyomo.core.kernel.piecewise_library.transforms.piecewise_sos2(*args, **kwds)[source]
Bases:
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:
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:
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:
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:
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:
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:
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.