MultipleBigMTransformation

(class from pyomo.gdp.plugins.multiple_bigm)

class pyomo.gdp.plugins.multiple_bigm.MultipleBigMTransformation[source]

Bases: GDP_to_MIP_Transformation, _BigM_MixIn

Implements the multiple big-M transformation from [TG15]. Note that this transformation is no different than the big-M transformation for two- term disjunctions, but that it may provide a tighter relaxation for models containing some disjunctions with three or more terms.

Class configuration

This class leverages the Pyomo Configuration System for managing configuration options. See the discussion on configuring class hierarchies for more information on how configuration class attributes, instance attributes, and method keyword arguments interact.

CONFIG:

  • targets (target_list, optional) – This specifies the list of components to relax. If None (default), the entire model is transformed. Note that if the transformation is done out of place, the list of targets should be attached to the model before it is cloned, and the list will specify the targets on the cloned instance.

  • assume_fixed_vars_permanent (bool, default=False) –

    Boolean indicating whether or not to transform so that the transformed model will still be valid when fixed Vars are unfixed.

    This is only relevant when the transformation will be calculating M values. If True, the transformation will calculate M values assuming that fixed variables will always be fixed to their current values. This means that if a fixed variable is unfixed after transformation, the transformed model is potentially no longer valid. By default, the transformation will assume fixed variables could be unfixed in the future and will use their bounds to calculate the M value rather than their value. Note that this could make for a weaker LP relaxation while the variables remain fixed.

  • solver (Solver, default='gurobi') – A solver to use to solve the continuous subproblems for calculating the M values

  • bigM (_to_dict, optional) –

    Big-M values to use while relaxing constraints.

    A user-specified dict or ComponentMap mapping tuples of Constraints and Disjuncts to Big-M values valid for relaxing the constraint if the Disjunct is chosen.

    Note: Unlike in the bigm transformation, we require the keys in this mapping specify the components the M value applies to exactly in order to avoid ambiguity. However, if the ‘only_mbigm_bound_constraints’ option is True, this argument can be used as it would be in the traditional bigm transformation for the non-bound constraints.

  • reduce_bound_constraints (bool, default=True) –

    Flag indicating whether or not to handle disjunctive constraints that bound a single variable in a single constraint, rather than one per Disjunct.

    Given the not-uncommon special structure:

    [l_1 <= x <= u_1] v [l_2 <= x <= u_2] v … v [l_K <= x <= u_K],

    instead of applying the rote transformation that would create 2*K different constraints in the relaxation, we can write two constraints:

    x >= l_1*y_1 + l_2*y_2 + … + l_K*y_k x <= u_1*y_1 + u_2*y_2 + … + u_K*y_K.

    This relaxation is as tight and has fewer constraints. This option is a flag to tell the mbigm transformation to detect this structure and handle it specially. Note that this is a special case of the ‘Hybrid Big-M Formulation’ from [Vie15] that takes advantage of the common left- hand side matrix for disjunctive constraints that bound a single variable.

    Note that we do not use user-specified M values for these constraints when this flag is set to True: If tighter bounds exist then they they should be put in the constraints.

  • only_mbigm_bound_constraints (bool, default=False) –

    Flag indicating if only bound constraints should be transformed with multiple-bigm, or if all the disjunctive constraints should.

    Sometimes it is only computationally advantageous to apply multiple- bigm to disjunctive constraints with the special structure:

    [l_1 <= x <= u_1] v [l_2 <= x <= u_2] v … v [l_K <= x <= u_K],

    and transform other disjunctive constraints with the traditional big-M transformation. This flag is used to set the above behavior.

    Note that the reduce_bound_constraints flag must also be True when this flag is set to True.

  • threads (PositiveInt, optional) –

    Number of worker processes to use when estimating M values.

    If not specified, use up to the number of available cores, minus one. If set to 1, do not spawn processes, and revert to single-threaded operation.

  • process_start_method (InEnum[ProcessStartMethod], optional) –

    Start method used for spawning processes during M calculation.

    Options are the elements of the enum ProcessStartMethod, or equivalently the strings ‘fork’, ‘spawn’, or ‘forkserver’, or None. See the Python multiprocessing documentation for a full description of each of these. When None is passed, we determine a reasonable default. On POSIX, the default is ‘fork’, unless we detect that Python has multiple threads at the time the process pool is created, in which case we instead use ‘forkserver’. On Windows, the default and only possible option is ‘spawn’. Note that if ‘spawn’ or ‘forkserver’ are selected, we depend on the dill module for pickling, and model instances must be pickleable using dill. This option is ignored if threads is set to 1.

  • use_primal_bound (bool, default=False) –

    When estimating M values, use the primal bound instead of the dual bound.

    This is necessary when using a local solver such as ipopt, but be aware that interior feasible points for this subproblem do not give valid values for M. That is, in the presence of numerical error, this option will lead to a slightly wrong reformulation.

__init__()[source]

Initialize transformation object.

Methods

__init__()

Initialize transformation object.

apply(model, **kwds)

DEPRECATED.

apply_to(model, **kwds)

Apply the transformation to the given model.

create_using(model, **kwds)

Create a new model with this transformation

get_all_M_values(model)

Returns a dictionary mapping each constraint, disjunct pair (where the constraint is on a disjunct and the disjunct is in the same disjunction as that disjunct) to a tuple: (lower_M_value, upper_M_value), where either can be None if the constraint does not have a lower or upper bound (respectively).

get_src_constraint()

Return the original Constraint whose transformed counterpart is transformedConstraint

get_src_constraints(transformedConstraint)

Return the original Constraints whose transformed counterpart is transformedConstraint

get_src_disjunct()

Return the Disjunct object whose transformed components are on transBlock.

get_src_disjunction()

Return the Disjunction corresponding to xor_constraint

get_transformed_constraints()

Return the transformed version of srcConstraint

Attributes

CONFIG

Global class configuration; see CONFIG.

transformation_name

Member Documentation

apply(model, **kwds)

DEPRECATED.

Deprecated since version 4.3.11323: Transformation.apply() has been deprecated. Please use either Transformation.apply_to() for in-place transformations or Transformation.create_using() for transformations that create a new, independent transformed model instance.

apply_to(model, **kwds)

Apply the transformation to the given model.

Keyword Arguments:

  • targets (target_list, optional) – This specifies the list of components to relax. If None (default), the entire model is transformed. Note that if the transformation is done out of place, the list of targets should be attached to the model before it is cloned, and the list will specify the targets on the cloned instance.

  • assume_fixed_vars_permanent (bool, default=False) –

    Boolean indicating whether or not to transform so that the transformed model will still be valid when fixed Vars are unfixed.

    This is only relevant when the transformation will be calculating M values. If True, the transformation will calculate M values assuming that fixed variables will always be fixed to their current values. This means that if a fixed variable is unfixed after transformation, the transformed model is potentially no longer valid. By default, the transformation will assume fixed variables could be unfixed in the future and will use their bounds to calculate the M value rather than their value. Note that this could make for a weaker LP relaxation while the variables remain fixed.

  • solver (Solver, default='gurobi') – A solver to use to solve the continuous subproblems for calculating the M values

  • bigM (_to_dict, optional) –

    Big-M values to use while relaxing constraints.

    A user-specified dict or ComponentMap mapping tuples of Constraints and Disjuncts to Big-M values valid for relaxing the constraint if the Disjunct is chosen.

    Note: Unlike in the bigm transformation, we require the keys in this mapping specify the components the M value applies to exactly in order to avoid ambiguity. However, if the ‘only_mbigm_bound_constraints’ option is True, this argument can be used as it would be in the traditional bigm transformation for the non-bound constraints.

  • reduce_bound_constraints (bool, default=True) –

    Flag indicating whether or not to handle disjunctive constraints that bound a single variable in a single constraint, rather than one per Disjunct.

    Given the not-uncommon special structure:

    [l_1 <= x <= u_1] v [l_2 <= x <= u_2] v … v [l_K <= x <= u_K],

    instead of applying the rote transformation that would create 2*K different constraints in the relaxation, we can write two constraints:

    x >= l_1*y_1 + l_2*y_2 + … + l_K*y_k x <= u_1*y_1 + u_2*y_2 + … + u_K*y_K.

    This relaxation is as tight and has fewer constraints. This option is a flag to tell the mbigm transformation to detect this structure and handle it specially. Note that this is a special case of the ‘Hybrid Big-M Formulation’ from [Vie15] that takes advantage of the common left- hand side matrix for disjunctive constraints that bound a single variable.

    Note that we do not use user-specified M values for these constraints when this flag is set to True: If tighter bounds exist then they they should be put in the constraints.

  • only_mbigm_bound_constraints (bool, default=False) –

    Flag indicating if only bound constraints should be transformed with multiple-bigm, or if all the disjunctive constraints should.

    Sometimes it is only computationally advantageous to apply multiple- bigm to disjunctive constraints with the special structure:

    [l_1 <= x <= u_1] v [l_2 <= x <= u_2] v … v [l_K <= x <= u_K],

    and transform other disjunctive constraints with the traditional big-M transformation. This flag is used to set the above behavior.

    Note that the reduce_bound_constraints flag must also be True when this flag is set to True.

  • threads (PositiveInt, optional) –

    Number of worker processes to use when estimating M values.

    If not specified, use up to the number of available cores, minus one. If set to 1, do not spawn processes, and revert to single-threaded operation.

  • process_start_method (InEnum[ProcessStartMethod], optional) –

    Start method used for spawning processes during M calculation.

    Options are the elements of the enum ProcessStartMethod, or equivalently the strings ‘fork’, ‘spawn’, or ‘forkserver’, or None. See the Python multiprocessing documentation for a full description of each of these. When None is passed, we determine a reasonable default. On POSIX, the default is ‘fork’, unless we detect that Python has multiple threads at the time the process pool is created, in which case we instead use ‘forkserver’. On Windows, the default and only possible option is ‘spawn’. Note that if ‘spawn’ or ‘forkserver’ are selected, we depend on the dill module for pickling, and model instances must be pickleable using dill. This option is ignored if threads is set to 1.

  • use_primal_bound (bool, default=False) –

    When estimating M values, use the primal bound instead of the dual bound.

    This is necessary when using a local solver such as ipopt, but be aware that interior feasible points for this subproblem do not give valid values for M. That is, in the presence of numerical error, this option will lead to a slightly wrong reformulation.

create_using(model, **kwds)

Create a new model with this transformation

Keyword Arguments:

  • targets (target_list, optional) – This specifies the list of components to relax. If None (default), the entire model is transformed. Note that if the transformation is done out of place, the list of targets should be attached to the model before it is cloned, and the list will specify the targets on the cloned instance.

  • assume_fixed_vars_permanent (bool, default=False) –

    Boolean indicating whether or not to transform so that the transformed model will still be valid when fixed Vars are unfixed.

    This is only relevant when the transformation will be calculating M values. If True, the transformation will calculate M values assuming that fixed variables will always be fixed to their current values. This means that if a fixed variable is unfixed after transformation, the transformed model is potentially no longer valid. By default, the transformation will assume fixed variables could be unfixed in the future and will use their bounds to calculate the M value rather than their value. Note that this could make for a weaker LP relaxation while the variables remain fixed.

  • solver (Solver, default='gurobi') – A solver to use to solve the continuous subproblems for calculating the M values

  • bigM (_to_dict, optional) –

    Big-M values to use while relaxing constraints.

    A user-specified dict or ComponentMap mapping tuples of Constraints and Disjuncts to Big-M values valid for relaxing the constraint if the Disjunct is chosen.

    Note: Unlike in the bigm transformation, we require the keys in this mapping specify the components the M value applies to exactly in order to avoid ambiguity. However, if the ‘only_mbigm_bound_constraints’ option is True, this argument can be used as it would be in the traditional bigm transformation for the non-bound constraints.

  • reduce_bound_constraints (bool, default=True) –

    Flag indicating whether or not to handle disjunctive constraints that bound a single variable in a single constraint, rather than one per Disjunct.

    Given the not-uncommon special structure:

    [l_1 <= x <= u_1] v [l_2 <= x <= u_2] v … v [l_K <= x <= u_K],

    instead of applying the rote transformation that would create 2*K different constraints in the relaxation, we can write two constraints:

    x >= l_1*y_1 + l_2*y_2 + … + l_K*y_k x <= u_1*y_1 + u_2*y_2 + … + u_K*y_K.

    This relaxation is as tight and has fewer constraints. This option is a flag to tell the mbigm transformation to detect this structure and handle it specially. Note that this is a special case of the ‘Hybrid Big-M Formulation’ from [Vie15] that takes advantage of the common left- hand side matrix for disjunctive constraints that bound a single variable.

    Note that we do not use user-specified M values for these constraints when this flag is set to True: If tighter bounds exist then they they should be put in the constraints.

  • only_mbigm_bound_constraints (bool, default=False) –

    Flag indicating if only bound constraints should be transformed with multiple-bigm, or if all the disjunctive constraints should.

    Sometimes it is only computationally advantageous to apply multiple- bigm to disjunctive constraints with the special structure:

    [l_1 <= x <= u_1] v [l_2 <= x <= u_2] v … v [l_K <= x <= u_K],

    and transform other disjunctive constraints with the traditional big-M transformation. This flag is used to set the above behavior.

    Note that the reduce_bound_constraints flag must also be True when this flag is set to True.

  • threads (PositiveInt, optional) –

    Number of worker processes to use when estimating M values.

    If not specified, use up to the number of available cores, minus one. If set to 1, do not spawn processes, and revert to single-threaded operation.

  • process_start_method (InEnum[ProcessStartMethod], optional) –

    Start method used for spawning processes during M calculation.

    Options are the elements of the enum ProcessStartMethod, or equivalently the strings ‘fork’, ‘spawn’, or ‘forkserver’, or None. See the Python multiprocessing documentation for a full description of each of these. When None is passed, we determine a reasonable default. On POSIX, the default is ‘fork’, unless we detect that Python has multiple threads at the time the process pool is created, in which case we instead use ‘forkserver’. On Windows, the default and only possible option is ‘spawn’. Note that if ‘spawn’ or ‘forkserver’ are selected, we depend on the dill module for pickling, and model instances must be pickleable using dill. This option is ignored if threads is set to 1.

  • use_primal_bound (bool, default=False) –

    When estimating M values, use the primal bound instead of the dual bound.

    This is necessary when using a local solver such as ipopt, but be aware that interior feasible points for this subproblem do not give valid values for M. That is, in the presence of numerical error, this option will lead to a slightly wrong reformulation.

get_all_M_values(model)[source]

Returns a dictionary mapping each constraint, disjunct pair (where the constraint is on a disjunct and the disjunct is in the same disjunction as that disjunct) to a tuple: (lower_M_value, upper_M_value), where either can be None if the constraint does not have a lower or upper bound (respectively).

Parameters:

model (A GDP model that has been transformed with multiple-BigM)

get_src_constraint()

Return the original Constraint whose transformed counterpart is transformedConstraint

Parameters:

  • transformedConstraint (Constraint, which must be a component on one of)

  • of (the BlockDatas in the relaxedDisjuncts Block)

  • block (a transformation)

get_src_constraints(transformedConstraint)[source]

Return the original Constraints whose transformed counterpart is transformedConstraint

Parameters:

  • transformedConstraint (Constraint, which must be a component on one of)

  • of (the BlockDatas in the relaxedDisjuncts Block)

  • block (a transformation)

get_src_disjunct()

Return the Disjunct object whose transformed components are on transBlock.

Parameters:

transBlock (BlockData which is in the relaxedDisjuncts IndexedBlock) – on a transformation block.

get_src_disjunction()

Return the Disjunction corresponding to xor_constraint

Parameters:

xor_constraint (Constraint, which must be the logical constraint) – (located on the transformation block) of some Disjunction

get_transformed_constraints()

Return the transformed version of srcConstraint

Parameters:
CONFIG = <pyomo.common.config.ConfigDict object>

Global class configuration; see CONFIG.