# 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 branch-and 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 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.

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.

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

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.

### Tuple of Observations¶

class ecole.observation.TupleFunction(*observation_functions)[source]

Pack observation functions together and return observations as tuples.

obtain_observation(model)[source]

Return observation from all functions as a tuple.

reset(model)[source]

Call reset on all observation functions.

### Dictionnary of Observations¶

class ecole.observation.DictFunction(**observation_functions)[source]

Pack observation functions together and return observations as dicts.

obtain_observation(model)[source]

Return observation from all functions as a dict.

reset(model)[source]

Call reset on all observation functions.