openfisca-core-overview.md

An overview of the most important classes in OpenFisca Core, from an implementation perspective. This does not tell you what the classes are conceptually, but sketches what their collaboration looks like as of this writing.

Keep in mind that this being an implementation-level model, it may have room for improvement. For instance, if you want to know the Entity associated with a Variable, you cannot ask a TaxBenefitSystem directly, you have to have built a Simulation first.

TaxBenefitSystem

• is a repository of Variable instances
• is a repository of ParameterNode instances
• is a repository of Entity types (not instances)

Variable

• holds a reference its Entity type (not instance)
• is a repository of variable metadata such as default value or definition period
• holds pointers to behaviour-modifying functions
• is a repository of formulas keyed to periods
• every variable in a model must be reified as a subclass (its methods are the formulas)

Entity

• provides a way to calculate the vector value of a Variable
• is a Callable, i.e. offers a function-like syntax
• delegates the calculation to an underlying Simulation
• knows the count of instances associated with it
• knows the role associated with each instance
• is a repository of Holders, one for each variable
• is a repository of instance identifiers
• is specialized into PersonEntity and GroupEntity

Holder

• wraps vector values of variables
• provides unified access to in-memory and on-disk storage of values
• performs cheks on input values provided
• provides facilities to "dispatch" values over many periods

PersonEntity

• is a Singleton semantically

GroupEntity

• is concerned with Roles
• provides a way to Project to other entities, i.e. calculate "foreign" Variables
• provides a way to aggregate values from instances
• works with various subclasses of Projector

Simulation

• is a repository of Entity instances
• provides a way to calculate the vector value of a Variable
• contains logic to detect "cycles"
• provides a way to set input values (delegated to Holders via Entities)

ParameterNode

• is a Composite of ParameterNode and Parameter instances
• provides access to the value of parameters at specific points in time

TaxScale

• models some specific forms of Parameters

Enum

• wraps vector values for some variable, to efficiently handle enumerated values

Scenario / SimulationBuilder

• provides an interface to create a Simulation from a text representation
• forms the basis for functional test cases