Observations¶
Protocol¶
The protocol expected to define a valid observation function is given below.

class
ecole.typing.
ObservationFunction
(*args, **kwds)[source]¶ Class repsonsible for extracting observations.
Observation functions are objects given to the
EnvironmentComposer
to extract the observations used to take the next action.
obtain_observation
(model: ecole.scip.Model) → Observation[source]¶ Extract observation on a given state.
The observation describe the state and is used for learning. This method will only be called once per state i.e., this method is not a getter and can have side effects.
 Parameters
model – The SCIP model defining the current state of the solver.
 Returns
The return is passed to the user by the environment.

reset
(model: ecole.scip.Model) → None[source]¶ Reset internal data at the start of episodes.
The method is called on new episodes
reset()
on the initial state. It can is usually used to reset the observation function internal data. Parameters
model – The SCIP model defining the current state of the solver.

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
.
obtain_observation
(self: ecole.observation.NodeBipartite, model: ecole.scip.Model) → Optional[ecole.observation.NodeBipartiteObs]¶ Extract a new
NodeBipartiteObs
.

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


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.

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.

property
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.

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

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

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.

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

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

Utilities¶
The following observation functions are used internally by Ecole.
Nothing¶

class
ecole.observation.
Nothing
¶ No observation.
This observation function does nothing and always returns
None
as an observation. Convenient for bandit algorithms, or when no learning is performed.
obtain_observation
(self: ecole.observation.Nothing, model: ecole.scip.Model) → None¶ Return None.

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