OpenFisca-Core 44.2.2__tar.gz → 44.3.0__tar.gz

{openfisca_core-44.2.2 → openfisca_core-44.3.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 44.3.0
+
+#### New Features
+
+- **Generic Entity Links (Phase 1-6)**: Introduced a new Liam2-inspired generic entity linking system avoiding rigid hierarchies like `Person -> Household`.
+  - Added new `Many2OneLink` and `One2ManyLink` models to create powerful inter-entity networks (e.g., `Person -> Employer`).
+  - Added implicit links directly binding members arrays. This powers the new `population.links` property natively inside `TaxBenefitSystem.instantiate_entities()`.
+  - Full capability to chain relationships via python: `person.mother.household.get("rent", period)`.
+  - Powerful vectorized declarative aggregations out-of-the-box (e.g., `households.persons.sum("salary", period, condition=is_female)`).
+
+#### Technical Changes
+
+- Backward compatibility is 100% maintained. Existing syntax via Projectors natively redirects to implicit links via modified `__getattr__`.
+
 ## 44.2.2
 
 #### Bug fixes

{openfisca_core-44.2.2 → openfisca_core-44.3.0/OpenFisca_Core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenFisca-Core
-Version: 44.2.2
+Version: 44.3.0
 Summary: A versatile microsimulation free software
 Home-page: https://github.com/openfisca/openfisca-core
 Author: OpenFisca Team

{openfisca_core-44.2.2 → openfisca_core-44.3.0}/OpenFisca_Core.egg-info/SOURCES.txt

@@ -78,6 +78,19 @@ openfisca_core/indexed_enums/types.py
 openfisca_core/indexed_enums/tests/__init__.py
 openfisca_core/indexed_enums/tests/test_enum.py
 openfisca_core/indexed_enums/tests/test_enum_array.py
+openfisca_core/links/__init__.py
+openfisca_core/links/implicit.py
+openfisca_core/links/link.py
+openfisca_core/links/many2one.py
+openfisca_core/links/one2many.py
+openfisca_core/links/tests/__init__.py
+openfisca_core/links/tests/test_benchmark.py
+openfisca_core/links/tests/test_edge_cases.py
+openfisca_core/links/tests/test_implicit.py
+openfisca_core/links/tests/test_integration.py
+openfisca_core/links/tests/test_many2one.py
+openfisca_core/links/tests/test_one2many.py
+openfisca_core/links/tests/test_one2many_logic.py
 openfisca_core/parameters/__init__.py
 openfisca_core/parameters/at_instant_like.py
 openfisca_core/parameters/config.py
@@ -113,6 +126,8 @@ openfisca_core/populations/_errors.py
 openfisca_core/populations/group_population.py
 openfisca_core/populations/population.py
 openfisca_core/populations/types.py
+openfisca_core/populations/tests/__init__.py
+openfisca_core/populations/tests/test_members_position.py
 openfisca_core/projectors/__init__.py
 openfisca_core/projectors/entity_to_person_projector.py
 openfisca_core/projectors/first_person_to_entity_projector.py

{openfisca_core-44.2.2/OpenFisca_Core.egg-info → openfisca_core-44.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenFisca-Core
-Version: 44.2.2
+Version: 44.3.0
 Summary: A versatile microsimulation free software
 Home-page: https://github.com/openfisca/openfisca-core
 Author: OpenFisca Team

{openfisca_core-44.2.2 → openfisca_core-44.3.0}/openfisca_core/entities/_core_entity.py

@@ -47,6 +47,9 @@ class CoreEntity:
     #: A ``TaxBenefitSystem`` instance.
     _tax_benefit_system: None | t.TaxBenefitSystem = None
 
+    #: Named links to other entities (Many2One, One2Many, etc.).
+    _links: dict
+
     @abc.abstractmethod
     def __init__(self, *__args: object, **__kwargs: object) -> None: ...
 
@@ -57,6 +60,43 @@ class CoreEntity:
         """A ``CoreEntity`` belongs to a ``TaxBenefitSystem``."""
         self._tax_benefit_system = tax_benefit_system
 
+    # -- Link management --------------------------------------------------
+
+    def add_link(self, link) -> None:
+        """Register a named link on this entity.
+
+        Args:
+            link: A ``Link`` instance (Many2OneLink, One2ManyLink, etc.).
+
+        Example::
+
+            from openfisca_core.links import Many2OneLink
+
+            mother = Many2OneLink(
+                name="mother",
+                link_field="mother_id",
+                target_entity_key="person",
+            )
+            person_entity.add_link(mother)
+
+        """
+        if not hasattr(self, "_links") or self._links is None:
+            self._links = {}
+        self._links[link.name] = link
+
+    def get_link(self, name: str):
+        """Retrieve a link by name, or ``None`` if not found."""
+        if not hasattr(self, "_links") or self._links is None:
+            return None
+        return self._links.get(name)
+
+    @property
+    def links(self) -> dict:
+        """All links registered on this entity."""
+        if not hasattr(self, "_links") or self._links is None:
+            self._links = {}
+        return self._links
+
     def get_variable(
         self,
         variable_name: t.VariableName,

{openfisca_core-44.2.2 → openfisca_core-44.3.0}/openfisca_core/indexed_enums/enum_array.py

@@ -266,8 +266,7 @@ class EnumArray(t.EnumArray):
         result: t.ObjArray
         if self.possible_values is None:
             msg = (
-                f"The possible values of the {self.__class__.__name__} are "
-                f"not defined."
+                f"The possible values of the {self.__class__.__name__} are not defined."
             )
             raise TypeError(msg)
         array = self.reshape(1).astype(t.EnumDType) if self.ndim == 0 else self
@@ -301,8 +300,7 @@ class EnumArray(t.EnumArray):
         result: t.StrArray
         if self.possible_values is None:
             msg = (
-                f"The possible values of the {self.__class__.__name__} are "
-                f"not defined."
+                f"The possible values of the {self.__class__.__name__} are not defined."
             )
             raise TypeError(msg)
         array = self.reshape(1).astype(t.EnumDType) if self.ndim == 0 else self

openfisca_core-44.3.0/openfisca_core/links/__init__.py

@@ -0,0 +1,36 @@
+"""Links between entities (Many2One, One2Many, chaining).
+
+This module implements a generic link system inspired by LIAM2, enriched
+with OpenFisca's role semantics.  Links are orthogonal to the existing
+GroupEntity/Projector machinery: current code keeps working unchanged,
+and links provide additional capabilities (intra-entity links, chaining,
+arbitrary named links).
+
+Usage in a country package::
+
+    from openfisca_core.links import Many2OneLink, One2ManyLink
+
+    # Declare a person→person link (intra-entity)
+    mother = Many2OneLink(
+        name="mother",
+        link_field="mother_id",
+        target_entity_key="person",
+    )
+
+    # Declare a person→employer link (inter-entity)
+    employer = Many2OneLink(
+        name="employer",
+        link_field="employer_id",
+        target_entity_key="employer",
+    )
+"""
+
+from .link import Link
+from .many2one import Many2OneLink
+from .one2many import One2ManyLink
+
+__all__ = [
+    "Link",
+    "Many2OneLink",
+    "One2ManyLink",
+]

openfisca_core-44.3.0/openfisca_core/links/implicit.py

@@ -0,0 +1,73 @@
+"""Implicit links dynamically inferred from OpenFisca's GroupPopulation system."""
+
+from __future__ import annotations
+
+import numpy
+
+from .many2one import Many2OneLink
+from .one2many import One2ManyLink
+
+
+class ImplicitMany2OneLink(Many2OneLink):
+    """A person → group link using GroupPopulation's internal arrays.
+
+    This bypasses the usual Variable lookup (``simulation.calculate``)
+    and directly reads ``members_entity_id`` and ``members_role`` from
+    the target GroupPopulation.
+    """
+
+    def __init__(self, group_entity_key: str):
+        super().__init__(
+            name=group_entity_key,
+            link_field="",  # Not used
+            target_entity_key=group_entity_key,
+        )
+
+    def _get_target_ids(self, period) -> numpy.ndarray:
+        return self._target_population.members_entity_id
+
+    @property
+    def role(self) -> numpy.ndarray | None:
+        return self._target_population.members_role
+
+    def _project_implicit(self, result: numpy.ndarray) -> numpy.ndarray:
+        # Fully compatible with old Projector logic
+        return self._target_population.project(result)
+
+
+class ImplicitOne2ManyLink(One2ManyLink):
+    """A group → person link using GroupPopulation's internal arrays."""
+
+    def __init__(self, name: str, group_entity_key: str):
+        super().__init__(
+            name=name,
+            link_field="",  # Not used
+            target_entity_key="person",  # The target of the O2M is persons
+        )
+        self._group_entity_key = group_entity_key
+
+    def _source_rows(self, period) -> numpy.ndarray:
+        # For a group->person O2M, the source is the group, the target is the person.
+        # members_entity_id is an array of length person.count, containing the group index.
+        # So members_entity_id IS the array of source rows for each target member.
+        return self._source_population.members_entity_id
+
+    def _apply_filters(self, period, values, role, condition):
+        source_rows = self._source_rows(period)
+        mask = numpy.ones(len(source_rows), dtype=bool)
+
+        if role is not None:
+            roles = self._source_population.members_role
+            mask &= roles == role
+
+        if condition is not None:
+            mask &= condition
+
+        source_rows = source_rows[mask]
+        values = values[mask]
+
+        valid = source_rows >= 0
+        return source_rows[valid], values[valid]
+
+
+__all__ = ["ImplicitMany2OneLink", "ImplicitOne2ManyLink"]

openfisca_core-44.3.0/openfisca_core/links/link.py

@@ -0,0 +1,109 @@
+"""Base Link class for entity relationships."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy
+
+
+class Link:
+    """A named, directed relationship between two entity populations.
+
+    A Link is defined by:
+
+    - A *name* used to access the link from formulas (e.g. "mother", "household").
+    - A *link_field*: the name of the Variable (on the source entity) that holds
+      the target entity IDs.
+    - A *target_entity_key*: the entity key of the target population.
+    - Optionally, a *role_field* and *position_field* to attach OpenFisca-style
+      role and position metadata to the relationship.
+
+
+    Sub-classes ``Many2OneLink`` and ``One2ManyLink`` add resolution logic.
+
+    Parameters
+    ----------
+    name : str
+        Human-readable name of the link (e.g. ``"mother"``).
+    link_field : str
+        Variable name on the **source** entity that holds IDs pointing to
+        the target entity.
+    target_entity_key : str
+        The ``Entity.key`` of the target entity.
+    role_field : str or None
+        Optional variable name holding the role of each source member
+        within the target group.
+    position_field : str or None
+        Optional variable name holding the positional index of each
+        source member within the target group.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        link_field: str,
+        target_entity_key: str,
+        *,
+        role_field: str | None = None,
+        position_field: str | None = None,
+    ) -> None:
+        self.name = name
+        self.link_field = link_field
+        self.target_entity_key = target_entity_key
+        self.role_field = role_field
+        self.position_field = position_field
+
+        # Resolved after simulation setup
+        self._source_population = None
+        self._target_population = None
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def attach(self, source_population) -> None:
+        """Bind this link to its source population."""
+        self._source_population = source_population
+
+    def resolve(self, populations: dict) -> None:
+        """Resolve ``target_entity_key`` to an actual population object.
+
+        Parameters
+        ----------
+        populations : dict[str, Population]
+            All populations in the simulation, keyed by entity key.
+        """
+        if self.target_entity_key not in populations:
+            msg = (
+                f"Link '{self.name}': target entity "
+                f"'{self.target_entity_key}' not found in populations "
+                f"{list(populations.keys())}"
+            )
+            raise KeyError(msg)
+        self._target_population = populations[self.target_entity_key]
+
+    # -- helpers ------------------------------------------------------------
+
+    @property
+    def is_resolved(self) -> bool:
+        return (
+            self._source_population is not None and self._target_population is not None
+        )
+
+    def _get_link_ids(self, period) -> numpy.ndarray:
+        """Return the array of target IDs for every source member.
+
+        This reads the ``link_field`` variable from the source population.
+        """
+        return self._source_population(self.link_field, period)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"name={self.name!r}, "
+            f"link_field={self.link_field!r}, "
+            f"target={self.target_entity_key!r})"
+        )
+
+
+__all__ = ["Link"]

openfisca_core-44.3.0/openfisca_core/links/many2one.py

@@ -0,0 +1,227 @@
+"""Many-to-one link: N source members → 1 target entity."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy
+
+from .link import Link
+
+if TYPE_CHECKING:
+    pass
+
+
+class Many2OneLink(Link):
+    """Navigate from many source members to one target entity.
+
+    Example: ``person.household`` (each person belongs to one household),
+    or ``person.mother`` (each person has one mother).
+
+    The resolution follows the LIAM2 pattern::
+
+        target_ids = source_pop(link_field)     # e.g. [0, 0, 1, 2, 0]
+        target_values = target_pop(variable)    # e.g. [800, 650, 900]
+        result = target_values[target_ids]      # e.g. [800, 800, 650, 900, 800]
+    """
+
+    def get(self, variable_name: str, period) -> numpy.ndarray:
+        """Get a target variable's value for each source member.
+
+        Parameters
+        ----------
+        variable_name : str
+            Name of the variable defined on the target entity.
+        period : Period
+            The period for which to compute the variable.
+
+        Returns
+        -------
+        numpy.ndarray
+            Array of shape ``(n_source,)`` containing the target variable
+            value for each source member.  Members with an invalid link
+            (target_id < 0) receive the variable's default value.
+        """
+        source_pop = self._source_population
+        simulation = source_pop.simulation
+
+        # 1. Target IDs for each source member
+        target_ids = self._get_target_ids(period)
+
+        # 2. Variable values on the target entity
+        target_values = simulation.calculate(variable_name, period)
+
+        # 3. Resolve IDs to row positions (handles id_to_rownum if needed)
+        target_rows = self._resolve_ids(target_ids)
+
+        # 4. Gather with missing-value handling
+        variable = simulation.tax_benefit_system.get_variable(variable_name)
+        default = variable.default_value if variable else 0
+
+        from openfisca_core.indexed_enums import Enum, EnumArray
+
+        if isinstance(default, Enum):
+            default = default.index
+
+        result = numpy.full(
+            source_pop.count,
+            default,
+            dtype=target_values.dtype,
+        )
+        valid = target_rows >= 0
+        result[valid] = target_values[target_rows[valid]]
+
+        if isinstance(target_values, EnumArray):
+            result = EnumArray(result, target_values.possible_values)
+
+        return result
+
+    # -- syntactic sugar ----------------------------------------------------
+
+    def __call__(self, variable_name: str, period) -> numpy.ndarray:
+        """Shorthand: ``person.mother("age", period)``."""
+        return self.get(variable_name, period)
+
+    def __getattr__(self, name: str):
+        """Chain links: ``person.mother.household``."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        target_pop = self._target_population
+        if target_pop is None:
+            raise AttributeError("Link is not bound to a simulation")
+
+        if hasattr(target_pop, "links") and name in target_pop.links:
+            target_link = target_pop.links[name]
+            return _ChainedGetter(self, target_link)
+
+        target_attr = getattr(target_pop, name, None)
+        if target_attr is not None:
+            if hasattr(target_attr, "projectable"):
+
+                def projector_function(*args, **kwargs):
+                    result = target_attr(*args, **kwargs)
+                    return self._project_result(result)
+
+                return projector_function
+            return target_attr
+
+        target_entity = target_pop.entity
+        msg = f"Entity '{target_entity.key}' has no link named '{name}'"
+        raise AttributeError(msg)
+
+    def _project_result(self, result: numpy.ndarray) -> numpy.ndarray:
+        if hasattr(self, "_project_implicit"):
+            return self._project_implicit(result)
+        msg = "Chained method calls computing arrays on explicit links are not supported because the period cannot be inferred."
+        raise NotImplementedError(msg)
+
+    # -- role helpers -------------------------------------------------------
+
+    @property
+    def role(self) -> numpy.ndarray | None:
+        """Role of each source member, if ``role_field`` is set."""
+        if self.role_field is None:
+            return None
+        return self._source_population.simulation.calculate(
+            self.role_field,
+            "eternity",
+        )
+
+    def has_role(self, role_value) -> numpy.ndarray:
+        """Boolean mask: does each source member have the given role?"""
+        r = self.role
+        if r is None:
+            msg = f"Link '{self.name}' has no role_field"
+            raise ValueError(msg)
+        return r == role_value
+
+    # -- ID resolution ------------------------------------------------------
+
+    def _get_target_ids(self, period) -> numpy.ndarray:
+        """Fetch the target IDs from the link_field variable."""
+        return self._source_population.simulation.calculate(
+            self.link_field,
+            period,
+        )
+
+    def _resolve_ids(self, target_ids: numpy.ndarray) -> numpy.ndarray:
+        """Convert target IDs to row indices.
+
+        If the target population has an ``_id_to_rownum`` mapping
+        (e.g. for intra-entity links where IDs ≠ row positions), use it.
+        Otherwise treat IDs as direct row indices (the OpenFisca convention
+        for GroupPopulation.members_entity_id).
+        """
+        target_pop = self._target_population
+        rows = numpy.full_like(target_ids, -1, dtype=numpy.intp)
+
+        if (
+            hasattr(target_pop, "_id_to_rownum")
+            and target_pop._id_to_rownum is not None
+        ):
+            id_to_rownum = target_pop._id_to_rownum
+            valid = (target_ids >= 0) & (target_ids < len(id_to_rownum))
+            rows[valid] = id_to_rownum[target_ids[valid]]
+        else:
+            valid = (target_ids >= 0) & (target_ids < target_pop.count)
+            rows[valid] = target_ids[valid]
+
+        return rows
+
+
+# ---------------------------------------------------------------------------
+# Chained link getter
+# ---------------------------------------------------------------------------
+
+
+class _ChainedGetter:
+    """Intermediate object for link chaining: ``person.mother.household``."""
+
+    def __init__(self, outer_link: Many2OneLink, inner_link: Link) -> None:
+        self._outer = outer_link
+        self._inner = inner_link
+
+    def get(self, variable_name: str, period) -> numpy.ndarray:
+        """Resolve ``person.mother.household.get("rent", period)``."""
+        # 1. Resolve inner link value on inner entity
+        inner_values = self._inner.get(variable_name, period)
+
+        # 2. Map back through outer link
+        target_ids = self._outer._source_population.simulation.calculate(
+            self._outer.link_field,
+            period,
+        )
+        target_rows = self._outer._resolve_ids(target_ids)
+
+        result = numpy.full(
+            self._outer._source_population.count,
+            0,
+            dtype=inner_values.dtype,
+        )
+        valid = target_rows >= 0
+        result[valid] = inner_values[target_rows[valid]]
+        return result
+
+    def __call__(self, variable_name: str, period) -> numpy.ndarray:
+        """Shorthand for get(): ``person.mother.household("rent", period)``."""
+        return self.get(variable_name, period)
+
+    def __getattr__(self, name: str):
+        """Continue chaining: ``person.mother.household.region``."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        target_pop = self._inner._target_population
+        if target_pop is None:
+            raise AttributeError("Link is not bound to a simulation")
+
+        if hasattr(target_pop, "links") and name in target_pop.links:
+            next_link = target_pop.links[name]
+            return _ChainedGetter(self._outer, next_link)
+
+        target_entity = target_pop.entity
+        raise AttributeError(f"Entity '{target_entity.key}' has no link named '{name}'")
+
+
+__all__ = ["Many2OneLink"]