# Create New Functions¶

`ObservationFunction` and `RewardFunction` functions can be adapted and created from Python.

At the core of the environment, a SCIP `Model` (equivalent abstraction to a `pyscipopt.Model` or a `SCIP*` in `C`), describe the state of the environment. The idea of observation and reward functions is to have a function that takes as input that `Model`, and return the desired value (an observation, or a reward). The environment itself does nothing more than calling the function and forward its output to the user.

Pratically speaking, it is more convenient to implement such functions as a class that a function, as it makes it easier to keep information between states.

## From an Exsiting One¶

To reuse a function, Python inheritance can be use. In the following, we will adapt `NodeBipartite` to apply some scaling to the observation features.

The method that will be called to return an observation is called `extract()`. Here is how we can create a new observation function that scale the features by their maximum absolute value.

```import numpy as np
from ecole.observation import NodeBipartite

class ScaledNodeBipartite(NodeBipartite):

def extract(self, model, done):
# Call parent method to get the original observation
obs = super().extract(model, done)
# Apply scaling
column_max_abs = np.abs(obs.column_features).max(0)
obs.column_features[:] /= column_max_abs
row_max_abs = np.abs(obs.row_features).max(0)
obs.row_features[:] /= row_max_abs
# Return the updated observation
return obs
```

Here we use the `NodeBipartite` function to do the heavy lifting by calling the method of the parent class. Then we scaled some features of that observation and returned the result. `ScaledNodeBipartite` is a perfectly valid observation function that can be given to an environment.

To make it smoother, we could apply an exponential moving average with coefficient α to the scaling vector. We will apply the moving average on states from the same episode, and reset it at every new episode. This example shows how the scaling vector can be stored between states.

```class MovingScaledNodeBipartite(NodeBipartite):

def __init__(self, alpha, *args, **kwargs):
# Construct parent class with other parameters
super().__init__(*args, **kwargs)
self.alpha = alpha

def before_reset(self, model):
super().before_reset(model)
# Reset exponential moving average (ema) on new episode
self.column_ema = None
self.row_ema = None

def extract(self, model, done):
obs = super().extract(model, done)

# Compute max absolute vector for current observation
column_max_abs = np.abs(obs.column_features).max(0)
row_max_abs = np.abs(obs.row_features).max(0)

if self.column_ema is None:
# New exponential moving average on new episode
self.column_ema = column_max_abs
self.row_ema = row_max_abs
else:
# Update exponential moving average
self.column_ema = self.alpha * column_max_abs + (1 - alpha) * self.column_ema
self.row_ema = self.alpha * row_max_abs + (1 - alpha) * self.row_ema

# Scale features and return new observation
obs.column_features[:] /= self.column_ema
obs.row_features[:] /= self.row_ema
return obs
```

Here, you can notice how we used the constructor to be able to customize the coefficient of the exponential moving average. We also inherited the `before_reset()` method which does not return anything. This method is called at the begining of the episode by `reset()` and is used to reintialize the class internal attribute on new episodes. The `extract()` is also called during during `reset()`, hence the `if` else `else` condition. Both these methods call the parent method to let it do its own initialization/reseting.

Warning

The scaling shown in this example is naive implementation meant to showcase the use of observation function. For proper scaling functions consider Scikit-Learn Scalers

## From Scratch¶

`ObservationFunction` and `RewardFunction` do not anything more than what is explained in the previous section. This means that to create new function form Python, one can simply create a class with the previous methods.

For instance, we can create a `StochasticReward` function that will wrap any given `RewardFunction` and with some probability return either the given reward or 0.

```import random

class StochasticReward:

def __init__(self, reward_function, probability = 0.05):
self.reward_function = reward_function
self.probability = probability

def before_reset(self, model):
self.reward_function.before_reset(model)

def extract(self, model, done):
# Unconditionally getting reward as reward_funcition.extract may have side effects
reward = self.reward_function.extract(model, done)
if random.random() < probability:
return 0.
else:
return reward
```

It can be used as such, for instance with `LpIterations` in a `Branching` environment.

```>> stochastic_lpiterations = StochaticReward(-ecole.reward.LpIteration, probability=0.1)
>> env = ecole.environment.Branching(reward_function=stochastic_lpiterations)
```

## Using PyScipOpt¶

When creating a new function, it is common to need to extract information from the solver. PyScipOpt is the official Python interface to SCIP. The `pyscipopt.Model` holds a stateful SCIP problem instance and solver. For a number of reasons (such as avaibility in C++) Ecole defines its own `Model` class that represent a very similar concept. It does not aim to be a replacement to PyScipOpt, rather it is possible to convert back and forth without any copy.

Using `ecole.scip.Model.as_pyscipopt()`, one can get a `pyscipopt.Model` that shares its internal data with `ecole.scip.Model`.

Conversely, given a `pyscipopt.Model`, it is possible to to create a `ecole.scip.Model` using the static method `ecole.scip.Model.from_pyscipopt()`.