When simulating with the Python API, you might want to understand how the result was calculated and what intermediate variables and parameters have been taken into account.

To trace a simulation calculation with the web API, please see /trace endpoint documentation.

Let’s suppose you ran a simulation, calculated the `housing_allowance`

for a set of households, and would like to understand in details where the final results come from.

To use the tracer, you should activate the `trace`

option with `simulation.trace = True`

*before* running any calculation with a `simulation`

object. This will allow you to inspect calculation steps and print them with `simulation.tracer.print_computation_log()`

.

Here is an example:

```
# -*- coding: utf-8 -*-
from openfisca_core.simulation_builder import SimulationBuilder
from openfisca_country_template import CountryTaxBenefitSystem
TEST_CASE = {
# ... whole test case (see example in next section)...
}
tax_benefit_system = CountryTaxBenefitSystem()
simulation_builder = SimulationBuilder()
simulation = simulation_builder.build_from_entities(tax_benefit_system, TEST_CASE)
# activate the trace
simulation.trace = True
# calculate a variable
housing_allowance = simulation.calculate('housing_allowance', '2011-01')
# print calculation steps
simulation.tracer.print_computation_log()
```

For more information on the

`tracer`

methods, see this Tracer class interface

If we use the tracer with the following `TEST_CASE`

:

```
TEST_CASE = {
'persons': {
'Ari': {
'salary': {'2011-01': 1000}
},
'Paul': {},
'Leila': {},
'Javier': {}
},
'households': {
'h1': {
'children': ['Leila'],
'parents': ['Ari', 'Paul'],
'rent': {'2011-01': 300}
},
'h2': {'parents': ['Javier']}
},
}
```

The previous code example would give us this output:

```
housing_allowance<2011-01> >> [75. 0.]
rent<2011-01> >> [300. 0.]
```

The `rent`

variable is indented to the right relative to `housing_allowance`

. This means that `housing_allowance`

variable called the `rent`

calculation. It was called on the same period, ‘2011-01’. As the rent variable’s value was an input value given by our `TEST_CASE`

, it was returned to `housing_allowance`

. Then, as the housing_allowance variable has a valid formula on ‘2011-01’, it used the `rent`

value to calculate its amount for its two households (`h1`

and `h2`

): `[75. 0.]`

Thus, on the left side of the double chevrons, you can read the trace from top to bottom to see the dependencies between the variables. And on the right side, you can read it from bottom to top to see how the simulation result is built.

Likewise, if you are calculating `housing_allowance`

on a large population you will be able to check your calculation results with aggregated outputs. To do so, you can add the `aggregate=True`

option as follows:

```
simulation.tracer.print_computation_log(aggregate=True)
```

If we apply it to our previous short example, it would give us this output:

```
housing_allowance<2011-01> >> {'min': 0.0, 'max': 75.0, 'avg': 37.5}
rent<2011-01> >> {'min': 0.0, 'max': 300.0, 'avg': 150.0}
```

where the minimum, maximum, and average value is given for each computed vector.