Observations

Interface

class ecole.typing.ObservationFunction(*args, **kwds)

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

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 calls reset_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

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.

Nothing

ecole.observation.Nothing

alias of ecole.core.data.NoneFunction

Node Bipartite

class ecole.observation.NodeBipartite

Bipartite graph observation function on branch-and 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 branch-and-bound 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 non-zero 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.

Strong Branching Scores

class ecole.observation.StrongBranchingScores

Strong branching score observation function on branch-and bound node.

This observation obtains scores for all LP or pseudo candidate variables at a branch-and-bound 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 psuedo-candidate variables if true or LP canidate variables if false. By default psuedo-candidates 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 branch-and bound node.

This observation obtains pseudocosts for all LP fractional candidate variables at a branch-and-bound 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.