Observations¶
Interface¶

class
ecole.typing.
ObservationFunction
(*args, **kwds)[source]¶ Class repsonsible for extracting observations.
Observation functions are objects given to the
Environment
to extract the observations used to take the next action.This class presents the interface expected to define a valid observation function. It is not necessary to inherit from this class, as observation functions are defined by structural subtyping. It is exists to support Python type hints.
See also
DataFunction
Observation function are equivalent to the generic data function, that is a function to extact an arbitrary type of data.

__init__
(*args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.

before_reset
(model: ecole.scip.Model) → None[source]¶ Reset internal data at the start of episodes.
The method is called on new episodes
reset()
right before the MDP is actually reset, that is right before the environment callsreset_dynamics()
.It is usually used to reset the internal data.
 Parameters
model – The
Model
, model defining the current state of the solver.

extract
(model: ecole.scip.Model, done: bool) → Observation[source]¶ Extract the observation on the given state.
Extract the observation after transitionning on the new state given by
model
. The function is reponsible for keeping track of relevant information from previous states. This can safely be done in this method as it will only be called once per state i.e., this method is not a getter and can have side effects. Parameters
model – The
Model
, model defining the current state of the solver.done – A flag indicating wether the state is terminal (as decided by the environment).
 Returns
The return is passed to the user by the environment.
Listing¶
The list of observation functions relevant to users is given below.
Node Bipartite¶

class
ecole.observation.
NodeBipartite
¶ Bipartite graph observation function on branchand bound node.
This observation function extract structured
NodeBipartiteObs
.
__init__
(self: ecole.observation.NodeBipartite) → None¶

before_reset
(self: ecole.observation.NodeBipartite, model: ecole.scip.Model) → None¶ Cache some feature not expected to change during an episode.

extract
(self: ecole.observation.NodeBipartite, model: ecole.scip.Model, done: bool) → Optional[ecole.observation.NodeBipartiteObs]¶ Extract a new
NodeBipartiteObs
.


class
ecole.observation.
NodeBipartiteObs
¶ Bipartite graph observation for branchandbound nodes.
The optimization problem is represented as an heterogenous bipartite graph. On one side, a node is associated with one variable, on the other side a node is associated with one constraint. There exist an edge between a variable and a constraint if the variable exists in the constraint with a nonzero coefficient.
Each variable and constraint node is associated with a vector of features. Each edge is associated with the coefficient of the variable in the constraint.

class
ColumnFeatures
¶ Members:
has_lower_bound
has_upper_bound
normed_reduced_cost
objective
solution_value
solution_frac
is_solution_at_lower_bound
is_solution_at_upper_bound
scaled_age
is_basis_lower
is_basis_basic
is_basis_upper
is_basis_zero
incumbent_value
average_incumbent_value
is_type_binary
is_type_integer
is_type_implicit_integer
is_type_continuous

__init__
(self: ecole.observation.NodeBipartiteObs.ColumnFeatures, arg0: int) → None¶

average_incumbent_value
= <ColumnFeatures.average_incumbent_value: 14>¶

has_lower_bound
= <ColumnFeatures.has_lower_bound: 0>¶

has_upper_bound
= <ColumnFeatures.has_upper_bound: 1>¶

incumbent_value
= <ColumnFeatures.incumbent_value: 13>¶

is_basis_basic
= <ColumnFeatures.is_basis_basic: 10>¶

is_basis_lower
= <ColumnFeatures.is_basis_lower: 9>¶

is_basis_upper
= <ColumnFeatures.is_basis_upper: 11>¶

is_basis_zero
= <ColumnFeatures.is_basis_zero: 12>¶

is_solution_at_lower_bound
= <ColumnFeatures.is_solution_at_lower_bound: 6>¶

is_solution_at_upper_bound
= <ColumnFeatures.is_solution_at_upper_bound: 7>¶

is_type_binary
= <ColumnFeatures.is_type_binary: 15>¶

is_type_continuous
= <ColumnFeatures.is_type_continuous: 18>¶

is_type_implicit_integer
= <ColumnFeatures.is_type_implicit_integer: 17>¶

is_type_integer
= <ColumnFeatures.is_type_integer: 16>¶

property
name
¶

normed_reduced_cost
= <ColumnFeatures.normed_reduced_cost: 2>¶

objective
= <ColumnFeatures.objective: 3>¶

scaled_age
= <ColumnFeatures.scaled_age: 8>¶

solution_frac
= <ColumnFeatures.solution_frac: 5>¶

solution_value
= <ColumnFeatures.solution_value: 4>¶


class
RowFeatures
¶ Members:
bias
is_tight
scaled_age
objective_cosine_similarity
dual_solution_value

__init__
(self: ecole.observation.NodeBipartiteObs.RowFeatures, arg0: int) → None¶

bias
= <RowFeatures.bias: 0>¶

dual_solution_value
= <RowFeatures.dual_solution_value: 4>¶

is_tight
= <RowFeatures.is_tight: 1>¶

property
name
¶

objective_cosine_similarity
= <RowFeatures.objective_cosine_similarity: 3>¶

scaled_age
= <RowFeatures.scaled_age: 2>¶


__init__
(*args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.

property
column_features
¶ A matrix where each row is represents a variable, and each column a feature of the variables.

property
edge_features
¶ The constraint matrix of the optimization problem, with rows for contraints and columns for variables.

property
row_features
¶ A matrix where each row is represents a constraint, and each column a feature of the constraints.

class
Strong Branching Scores¶

class
ecole.observation.
StrongBranchingScores
¶ Strong branching score observation function on branchand bound node.
This observation obtains scores for all LP or pseudo candidate variables at a branchandbound node. The strong branching score measures the quality of branching for each variable. This observation can be used as an expert for imitation learning algorithms.
This observation function extracts an array containing the strong branching score for each variable in the problem which can be indexed by the action set. Variables for which a strong branching score is not applicable are filled with NaN.

__init__
(self: ecole.observation.StrongBranchingScores, pseudo_candidates: bool = True) → None¶ Constructor for StrongBranchingScores.
 Parameters
pseudo_candidates – The parameter determines if strong branching scores are computed for psuedocandidate variables if true or LP canidate variables if false. By default psuedocandidates will be computed.

before_reset
(self: ecole.observation.StrongBranchingScores, model: ecole.scip.Model) → None¶ Do nothing.

extract
(self: ecole.observation.StrongBranchingScores, model: ecole.scip.Model, done: bool) → Optional[xt::xtensor]¶ Extract an array containing strong branching scores.

Pseudocosts¶

class
ecole.observation.
Pseudocosts
¶ Pseudocosts observation function on branchand bound node.
This observation obtains pseudocosts for all LP fractional candidate variables at a branchandbound node. The pseudocost is a cheap approximation to the strong branching score and measures the quality of branching for each variable. This observation can be used as a practical branching strategy by always branching on the variable with the highest pseudocost, although in practice is it not as efficient as SCIP’s default strategy, reliability pseudocost branching (also known as hybrid branching).
This observation function extracts an array containing the pseudocost for each variable in the problem which can be indexed by the action set. Variables for which a pseudocost is not applicable are filled with NaN.

__init__
(self: ecole.observation.Pseudocosts) → None¶

before_reset
(self: ecole.observation.Pseudocosts, model: ecole.scip.Model) → None¶ Do nothing.

extract
(self: ecole.observation.Pseudocosts, model: ecole.scip.Model, done: bool) → Optional[xt::xtensor]¶ Extract an array containing pseudocosts.

Khalil et al. 2016¶

class
ecole.observation.
Khalil2016
¶ Branching candidates features from Khalil et al. (2016).
The observation is a matrix where rows represent pseudo branching cnadidates and columns represent features related to these variables. See [Khalil2016] for a complete reference on this objservation function.
 Khalil2016
Khalil, Elias Boutros, Pierre Le Bodic, Le Song, George Nemhauser, and Bistra Dilkina. “Learning to branch in mixed integer programming.” Thirtieth AAAI Conference on Artificial Intelligence. 2016.

__init__
(self: ecole.observation.Khalil2016) → None¶

before_reset
(self: ecole.observation.Khalil2016, model: ecole.scip.Model) → None¶ Precompute static features for all varaible columns.

extract
(self: ecole.observation.Khalil2016, model: ecole.scip.Model, done: bool) → Optional[xt::xtensor]¶ Extract the observation matrix.