Simulations

class openfisca_core.simulations.Simulation(tax_benefit_system, populations)

Represents a simulation, and handles the calculation logic.

calculate(variable_name, period)

Calculate variable_name for period.

get_array(variable_name, period)

Return the value of variable_name for period, if this value is alreay in the cache (if it has been set as an input or previously calculated).

Unlike calculate(), this method does not trigger calculations and does not use any formula.

get_holder(variable_name)

Get the holder associated with the variable.

get_memory_usage(variables=None)

Get data about the virtual memory usage of the simulation.

class openfisca_core.simulations.SimulationBuilder

static build_default_simulation(tax_benefit_system, count=1)

Build a default simulation.

Return type:

Simulation

Where:

• There are count persons

• There are count of each group entity, containing one person

• Every person has, in each entity, the first role

build_from_dict(tax_benefit_system, input_dict)

Build a simulation from an input dictionary.

This method uses SimulationBuilder.build_from_entities() if entities are fully specified, or SimulationBuilder.build_from_variables() if they are not.

Parameters:

• tax_benefit_system (TaxBenefitSystem) – The system to use.

• input_dict (Union[dict[str, Iterable[Iterable[Axis]]], dict[str, Union[dict[str, object], dict[str, dict[str, object]]]], dict[str, Union[dict[str, Union[str, Iterable[str]]], dict[str, Union[dict[str, object], dict[str, dict[str, object]]]]]], dict[str, dict[str, dict[str, Union[dict[str, object], dict[str, dict[str, object]]]]]], dict[str, dict[str, Union[dict[str, Union[str, Iterable[str]]], dict[str, Union[dict[str, object], dict[str, dict[str, object]]]]]]]]) – The input of the simulation.

Returns:

Simulation – The built simulation.

Return type:

Simulation

Examples

>>> entities = {"person", "household"}

>>> params = {
...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
...     "household": {"parents": ["Javier"]},
...     "axes": [[{"count": 1, "max": 1, "min": 1, "name": "household"}]],
... }

>>> are_entities_short_form(params, entities)
True

>>> entities = {"persons", "households"}

>>> params = {
...     "axes": [
...         [
...             {
...                 "count": 2,
...                 "max": 3000,
...                 "min": 0,
...                 "name": "rent",
...                 "period": "2018-11",
...             }
...         ]
...     ],
...     "households": {
...         "housea": {"parents": ["Alicia", "Javier"]},
...         "houseb": {"parents": ["Tom"]},
...     },
...     "persons": {
...         "Alicia": {"salary": {"2018-11": 0}},
...         "Javier": {},
...         "Tom": {},
...     },
... }

>>> are_entities_short_form(params, entities)
True

>>> params = {"salary": [12000, 13000]}

>>> not are_entities_specified(params, {"salary"})
True

build_from_entities(tax_benefit_system, input_dict)

Build a simulation from a Python dict input_dict fully specifying entities.

Return type:

Simulation

Examples

>>> entities = {"person", "household"}

>>> params = {
...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
...     "household": {"parents": ["Javier"]},
...     "axes": [[{"count": 1, "max": 1, "min": 1, "name": "household"}]],
... }

>>> are_entities_short_form(params, entities)
True

build_from_variables(tax_benefit_system, input_dict)

Build a simulation from a Python dict input_dict describing variables values without expliciting entities.

This method uses SimulationBuilder.build_default_simulation() to infer an entity structure.

Parameters:

• tax_benefit_system (TaxBenefitSystem) – The system to use.

• input_dict (dict[str, Union[dict[str, object], dict[str, dict[str, object]]]]) – The input of the simulation.

Returns:

Simulation – The built simulation.

Raises:

SituationParsingError – If the input is not valid.

Return type:

Simulation

Examples

>>> params = {"salary": {"2016-10": 12000}}

>>> are_entities_specified(params, {"salary"})
False

>>> params = {"salary": 12000}

>>> are_entities_specified(params, {"salary"})
False

explicit_singular_entities(tax_benefit_system, input_dict)

Preprocess input_dict to explicit entities defined using the single-entity shortcut.

Return type:

dict[str, dict[str, Union[dict[str, Union[str, Iterable[str]]], dict[str, Union[dict[str, object], dict[str, dict[str, object]]]]]]]

Examples

>>> params = {
...     "persons": {
...         "Javier": {},
...     },
...     "household": {"parents": ["Javier"]},
... }

>>> are_entities_fully_specified(params, {"persons", "households"})
False

>>> are_entities_short_form(params, {"person", "household"})
True

>>> params = {
...     "persons": {"Javier": {}},
...     "households": {"household": {"parents": ["Javier"]}},
... }

>>> are_entities_fully_specified(params, {"persons", "households"})
True

>>> are_entities_short_form(params, {"person", "household"})
False

openfisca_core.simulations.helpers.check_unexpected_entities(params, entities)

Check if the input contains entities that are not in the system.

Parameters:

• params (ParamsWithoutAxes) – Simulation parameters.

• entities (Iterable[str]) – List of entities in plural form.

Raises:

SituationParsingError – If there are entities that are not in the system.

Return type:

None

Examples

>>> entities = {"persons", "households"}

>>> params = {
...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
...     "households": {"household": {"parents": ["Javier"]}},
... }

>>> check_unexpected_entities(params, entities)

>>> params = {"dogs": {"Bart": {"damages": {"2018-11": 2000}}}}

>>> check_unexpected_entities(params, entities)
Traceback (most recent call last):
openfisca_core.errors.situation_parsing_error.SituationParsingError

openfisca_core.simulations.helpers.has_unexpected_entities(params, entities)

Check if the input contains entities that are not in the system.

Parameters:

• params (ParamsWithoutAxes) – Simulation parameters.

• entities (Iterable[str]) – List of entities in plural form.

Returns:

bool – True if the input contains entities that are not in the system.

Return type:

bool

Examples

>>> entities = {"persons", "households"}

>>> params = {
...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
...     "households": {"household": {"parents": ["Javier"]}},
... }

>>> has_unexpected_entities(params, entities)
False

>>> params = {"dogs": {"Bart": {"damages": {"2018-11": 2000}}}}

>>> has_unexpected_entities(params, entities)
True