APPSI Base Classes

class pyomo.contrib.appsi.base.TerminationCondition(value)[source]

Bases: Enum

An enumeration for checking the termination condition of solvers

error = 11: The solver exited due to an error

infeasible = 9: The solver exited because the problem is infeasible

infeasibleOrUnbounded = 10: The solver exited because the problem is either infeasible or unbounded

interrupted = 12: The solver exited because it was interrupted

licensingProblems = 13: The solver exited due to licensing problems

maxIterations = 2: The solver exited due to an iteration limit

maxTimeLimit = 1: The solver exited due to a time limit

minStepLength = 4: The solver exited due to a minimum step length

objectiveLimit = 3: The solver exited due to an objective limit

optimal = 5: The solver exited with the optimal solution

unbounded = 8: The solver exited because the problem is unbounded

unknown = 0: unknown serves as both a default value, and it is used when no other enum member makes sense

class pyomo.contrib.appsi.base.Results[source]

Bases: object

termination_condition

The reason the solver exited. This is a member of the TerminationCondition enum.

Type:: TerminationCondition

best_feasible_objective

If a feasible solution was found, this is the objective value of the best solution found. If no feasible solution was found, this is None.

Type:: float

best_objective_bound

The best objective bound found. For minimization problems, this is the lower bound. For maximization problems, this is the upper bound. For solvers that do not provide an objective bound, this should be -inf (minimization) or inf (maximization)

Type:: float

Here is an example workflow

>>> import pyomo.environ as pe
>>> from pyomo.contrib import appsi
>>> m = pe.ConcreteModel()
>>> m.x = pe.Var()
>>> m.obj = pe.Objective(expr=m.x**2)
>>> opt = appsi.solvers.Ipopt()
>>> opt.config.load_solution = False
>>> results = opt.solve(m) 
>>> if results.termination_condition == appsi.base.TerminationCondition.optimal: 
...     print('optimal solution found: ', results.best_feasible_objective) 
...     results.solution_loader.load_vars() 
...     print('the optimal value of x is ', m.x.value) 
... elif results.best_feasible_objective is not None: 
...     print('sub-optimal but feasible solution found: ', results.best_feasible_objective) 
...     results.solution_loader.load_vars(vars_to_load=[m.x]) 
...     print('The value of x in the feasible solution is ', m.x.value) 
... elif results.termination_condition in {appsi.base.TerminationCondition.maxIterations, appsi.base.TerminationCondition.maxTimeLimit}: 
...     print('No feasible solution was found. The best lower bound found was ', results.best_objective_bound) 
... else: 
...     print('The following termination condition was encountered: ', results.termination_condition) 

class pyomo.contrib.appsi.base.Solver[source]

Bases: ABC

enum Availability(value)[source]

Bases: IntEnum

An enumeration.

Member Type:: int

Valid values are as follows:

NotFound = <Availability.NotFound: 0>

BadVersion = <Availability.BadVersion: -1>

BadLicense = <Availability.BadLicense: -2>

FullLicense = <Availability.FullLicense: 1>

LimitedLicense = <Availability.LimitedLicense: 2>

NeedsCompiledExtension = <Availability.NeedsCompiledExtension: -3>

abstract available()[source]

Test if the solver is available on this system.

Nominally, this will return True if the solver interface is valid and can be used to solve problems and False if it cannot.

Note that for licensed solvers there are a number of “levels” of available: depending on the license, the solver may be available with limitations on problem size or runtime (e.g., ‘demo’ vs. ‘community’ vs. ‘full’). In these cases, the solver may return a subclass of enum.IntEnum, with members that resolve to True if the solver is available (possibly with limitations). The Enum may also have multiple members that all resolve to False indicating the reason why the interface is not available (not found, bad license, unsupported version, etc).

Returns:: available – An enum that indicates “how available” the solver is. Note that the enum can be cast to bool, which will be True if the solver is runable at all and False otherwise.
Return type:: Solver.Availability

abstract property config

An object for configuring solve options.

Returns:: An object for configuring pyomo solve options such as the time limit. These options are mostly independent of the solver.
Return type:: SolverConfig

is_persistent()[source]

Returns:: is_persistent – True if the solver is a persistent solver.
Return type:: bool

abstract solve(model: _BlockData, timer: HierarchicalTimer | None = None) → Results[source]

Solve a Pyomo model.

Parameters:

model (_BlockData) – The Pyomo model to be solved
timer (HierarchicalTimer) – An option timer for reporting timing

Returns:

results – A results object

Return type:

Results

abstract property symbol_map

abstract version() → Tuple[source]

Returns:: version – A tuple representing the version
Return type:: tuple

class pyomo.contrib.appsi.base.PersistentSolver[source]

Bases: Solver

enum Availability(value)

Bases: IntEnum

An enumeration.

Member Type:: int

Valid values are as follows:

NotFound = <Availability.NotFound: 0>

BadVersion = <Availability.BadVersion: -1>

BadLicense = <Availability.BadLicense: -2>

FullLicense = <Availability.FullLicense: 1>

LimitedLicense = <Availability.LimitedLicense: 2>

NeedsCompiledExtension = <Availability.NeedsCompiledExtension: -3>

abstract add_block(block: _BlockData)[source]

abstract add_constraints(cons: List[_GeneralConstraintData])[source]

abstract add_params(params: List[_ParamData])[source]

abstract add_variables(variables: List[_GeneralVarData])[source]

abstract available()

Test if the solver is available on this system.

Nominally, this will return True if the solver interface is valid and can be used to solve problems and False if it cannot.

Note that for licensed solvers there are a number of “levels” of available: depending on the license, the solver may be available with limitations on problem size or runtime (e.g., ‘demo’ vs. ‘community’ vs. ‘full’). In these cases, the solver may return a subclass of enum.IntEnum, with members that resolve to True if the solver is available (possibly with limitations). The Enum may also have multiple members that all resolve to False indicating the reason why the interface is not available (not found, bad license, unsupported version, etc).

Returns:: available – An enum that indicates “how available” the solver is. Note that the enum can be cast to bool, which will be True if the solver is runable at all and False otherwise.
Return type:: Solver.Availability

abstract property config

An object for configuring solve options.

Returns:: An object for configuring pyomo solve options such as the time limit. These options are mostly independent of the solver.
Return type:: SolverConfig

get_duals(cons_to_load: Sequence[_GeneralConstraintData] | None = None) → Dict[_GeneralConstraintData, float][source]

Declare sign convention in docstring here.

Parameters:: cons_to_load (list) – A list of the constraints whose duals should be loaded. If cons_to_load is None, then the duals for all constraints will be loaded.
Returns:: duals – Maps constraints to dual values
Return type:: dict

abstract get_primals(vars_to_load: Sequence[_GeneralVarData] | None = None) → Mapping[_GeneralVarData, float][source]

get_reduced_costs(vars_to_load: Sequence[_GeneralVarData] | None = None) → Mapping[_GeneralVarData, float][source]

Parameters:: vars_to_load (list) – A list of the variables whose reduced cost should be loaded. If vars_to_load is None, then all reduced costs will be loaded.
Returns:: reduced_costs – Maps variable to reduced cost
Return type:: ComponentMap

get_slacks(cons_to_load: Sequence[_GeneralConstraintData] | None = None) → Dict[_GeneralConstraintData, float][source]

Parameters:: cons_to_load (list) – A list of the constraints whose slacks should be loaded. If cons_to_load is None, then the slacks for all constraints will be loaded.
Returns:: slacks – Maps constraints to slack values
Return type:: dict

is_persistent()[source]

Returns:: is_persistent – True if the solver is a persistent solver.
Return type:: bool

load_vars(vars_to_load: Sequence[_GeneralVarData] | None = None) → NoReturn[source]

Load the solution of the primal variables into the value attribute of the variables.

Parameters:: vars_to_load (list) – A list of the variables whose solution should be loaded. If vars_to_load is None, then the solution to all primal variables will be loaded.

abstract remove_block(block: _BlockData)[source]

abstract remove_constraints(cons: List[_GeneralConstraintData])[source]

abstract remove_params(params: List[_ParamData])[source]

abstract remove_variables(variables: List[_GeneralVarData])[source]

abstract set_instance(model)[source]

abstract set_objective(obj: _GeneralObjectiveData)[source]

abstract solve(model: _BlockData, timer: HierarchicalTimer | None = None) → Results

Solve a Pyomo model.

Parameters:

model (_BlockData) – The Pyomo model to be solved
timer (HierarchicalTimer) – An option timer for reporting timing

Returns:

results – A results object

Return type:

Results

abstract property symbol_map

abstract property update_config: UpdateConfig

abstract update_params()[source]

abstract update_variables(variables: List[_GeneralVarData])[source]

abstract version() → Tuple

Returns:: version – A tuple representing the version
Return type:: tuple

class pyomo.contrib.appsi.base.SolverConfig(description=None, doc=None, implicit=False, implicit_domain=None, visibility=0)[source]

Bases: ConfigDict

time_limit

Time limit for the solver

Type:: float

stream_solver

If True, then the solver log goes to stdout

Type:: bool

load_solution

If False, then the values of the primal variables will not be loaded into the model

Type:: bool

symbolic_solver_labels

If True, the names given to the solver will reflect the names of the pyomo components. Cannot be changed after set_instance is called.

Type:: bool

report_timing

If True, then some timing information will be printed at the end of the solve.

Type:: bool

add(name, config)

content_filters = {'userdata', 'all', None}

declare(name, config)

declare_as_argument(*args, **kwds)

Map this Config item to an argparse argument.

Valid arguments include all valid arguments to argparse’s ArgumentParser.add_argument() with the exception of ‘default’. In addition, you may provide a group keyword argument to either pass in a pre-defined option group or subparser, or else pass in the string name of a group, subparser, or (subparser, group).

declare_from(other, skip=None)

display(content_filter=None, indent_spacing=2, ostream=None, visibility=None)

domain_name()

generate_documentation(block_start=None, block_end=None, item_start=None, item_body=None, item_end=None, indent_spacing=2, width=78, visibility=None, format='latex')

generate_yaml_template(indent_spacing=2, width=78, visibility=0)

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

import_argparse(parsed_args)

initialize_argparse(parser)

items() → a set-like object providing a view on D's items

iteritems(): DEPRECATED.

Deprecated since version 6.0: The iteritems method is deprecated. Use dict.keys().

iterkeys(): DEPRECATED.

Deprecated since version 6.0: The iterkeys method is deprecated. Use dict.keys().

itervalues(): DEPRECATED.

Deprecated since version 6.0: The itervalues method is deprecated. Use dict.keys().

keys() → a set-like object providing a view on D's keys

name(fully_qualified=False)

reset()

set_default_value(default)

set_domain(domain)

set_value(value, skip_implicit=False)

setdefault(key, default=NOTSET)

unused_user_values()

user_values()

value(accessValue=True)

values() → an object providing a view on D's values

class pyomo.contrib.appsi.base.MIPSolverConfig(description=None, doc=None, implicit=False, implicit_domain=None, visibility=0)[source]

Bases: SolverConfig

mip_gap

Solver will terminate if the mip gap is less than mip_gap

Type:: float

relax_integrality

If True, all integer variables will be relaxed to continuous variables before solving

Type:: bool

add(name, config)

content_filters = {'userdata', 'all', None}

declare(name, config)

declare_as_argument(*args, **kwds)

Map this Config item to an argparse argument.

Valid arguments include all valid arguments to argparse’s ArgumentParser.add_argument() with the exception of ‘default’. In addition, you may provide a group keyword argument to either pass in a pre-defined option group or subparser, or else pass in the string name of a group, subparser, or (subparser, group).

declare_from(other, skip=None)

display(content_filter=None, indent_spacing=2, ostream=None, visibility=None)

domain_name()

generate_documentation(block_start=None, block_end=None, item_start=None, item_body=None, item_end=None, indent_spacing=2, width=78, visibility=None, format='latex')

generate_yaml_template(indent_spacing=2, width=78, visibility=0)

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

import_argparse(parsed_args)

initialize_argparse(parser)

items() → a set-like object providing a view on D's items

iteritems(): DEPRECATED.

Deprecated since version 6.0: The iteritems method is deprecated. Use dict.keys().

iterkeys(): DEPRECATED.

Deprecated since version 6.0: The iterkeys method is deprecated. Use dict.keys().

itervalues(): DEPRECATED.

Deprecated since version 6.0: The itervalues method is deprecated. Use dict.keys().

keys() → a set-like object providing a view on D's keys

load_solution: bool

name(fully_qualified=False)

report_timing: bool

reset()

set_default_value(default)

set_domain(domain)

set_value(value, skip_implicit=False)

setdefault(key, default=NOTSET)

stream_solver: bool

symbolic_solver_labels: bool

time_limit: float | None

unused_user_values()

user_values()

value(accessValue=True)

values() → an object providing a view on D's values

class pyomo.contrib.appsi.base.UpdateConfig(description=None, doc=None, implicit=False, implicit_domain=None, visibility=0)[source]

Bases: ConfigDict

check_for_new_or_removed_constraints

Type:: bool

check_for_new_or_removed_vars

Type:: bool

check_for_new_or_removed_params

Type:: bool

update_constraints

Type:: bool

update_vars

Type:: bool

update_params

Type:: bool

update_named_expressions

Type:: bool

add(name, config)

content_filters = {'userdata', 'all', None}

declare(name, config)

declare_as_argument(*args, **kwds)

Map this Config item to an argparse argument.

Valid arguments include all valid arguments to argparse’s ArgumentParser.add_argument() with the exception of ‘default’. In addition, you may provide a group keyword argument to either pass in a pre-defined option group or subparser, or else pass in the string name of a group, subparser, or (subparser, group).

declare_from(other, skip=None)

display(content_filter=None, indent_spacing=2, ostream=None, visibility=None)

domain_name()

generate_documentation(block_start=None, block_end=None, item_start=None, item_body=None, item_end=None, indent_spacing=2, width=78, visibility=None, format='latex')

generate_yaml_template(indent_spacing=2, width=78, visibility=0)

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

import_argparse(parsed_args)

initialize_argparse(parser)

items() → a set-like object providing a view on D's items

iteritems(): DEPRECATED.

Deprecated since version 6.0: The iteritems method is deprecated. Use dict.keys().

iterkeys(): DEPRECATED.

Deprecated since version 6.0: The iterkeys method is deprecated. Use dict.keys().

itervalues(): DEPRECATED.

Deprecated since version 6.0: The itervalues method is deprecated. Use dict.keys().

keys() → a set-like object providing a view on D's keys

name(fully_qualified=False)

reset()

set_default_value(default)

set_domain(domain)

set_value(value, skip_implicit=False)

setdefault(key, default=NOTSET)

unused_user_values()

user_values()

value(accessValue=True)

values() → an object providing a view on D's values