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

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

@@ -1,5 +1,25 @@
 # 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
+
+- Fix enum index overflow for enums with more than 256 members (e.g. NAF). Index arrays were encoded as `uint8` (0-255), causing indices > 255 to be truncated and wrong values in simulations. Encoding now uses `int16` (`ENUM_ARRAY_DTYPE`) consistently.
+
 ## 44.2.1 [#1341](https://github.com/openfisca/openfisca-core/pull/1341)
 
 #### Technical changes

{openfisca_core-44.2.1 → 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.1
+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.1 → 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.1/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.1
+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.1 → 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.1 → openfisca_core-44.3.0}/openfisca_core/indexed_enums/_enum_type.py

@@ -26,7 +26,7 @@ class EnumType(t.EnumType):
         ...     TENANT = "Tenant"
 
         >>> Housing.indices
-        array([0, 1], dtype=uint8)
+        array([0, 1], dtype=int16)
 
         >>> Housing.names
         array(['OWNER', 'TENANT'], dtype='<U6')

{openfisca_core-44.2.1 → openfisca_core-44.3.0}/openfisca_core/indexed_enums/_utils.py

@@ -39,22 +39,22 @@ def _enum_to_index(value: t.ObjArray | t.ArrayLike[t.Enum]) -> t.IndexArray:
         TypeError: 'Road' object is not iterable
 
         >>> _enum_to_index([Road.AVENUE])
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _enum_to_index(numpy.array(Road.AVENUE))
         Traceback (most recent call last):
         TypeError: iteration over a 0-d array
 
         >>> _enum_to_index(numpy.array([Road.AVENUE]))
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> value = numpy.array([Road.STREET, Road.AVENUE, Road.STREET])
         >>> _enum_to_index(value)
-        array([0, 1, 0], dtype=uint8)
+        array([0, 1, 0], dtype=int16)
 
         >>> value = numpy.array([Road.AVENUE, Road.AVENUE, Rogue.BOULEVARD])
         >>> _enum_to_index(value)
-        array([1, 1, 0], dtype=uint8)
+        array([1, 1, 0], dtype=int16)
 
     """
     return numpy.array([enum.index for enum in value], t.EnumDType)
@@ -92,28 +92,28 @@ def _int_to_index(
         ...     )
 
         >>> _int_to_index(Road, 1)
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _int_to_index(Road, [1])
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _int_to_index(Road, array("B", [1]))
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _int_to_index(Road, memoryview(array("B", [1])))
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _int_to_index(Road, numpy.array(1))
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _int_to_index(Road, numpy.array([1]))
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _int_to_index(Road, numpy.array([0, 1, 0]))
-        array([0, 1, 0], dtype=uint8)
+        array([0, 1, 0], dtype=int16)
 
         >>> _int_to_index(Road, numpy.array([1, 1, 2]))
-        array([1, 1], dtype=uint8)
+        array([1, 1], dtype=int16)
 
     """
     indices = enum_class.indices
@@ -151,22 +151,22 @@ def _str_to_index(
         ...     )
 
         >>> _str_to_index(Road, "AVENUE")
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _str_to_index(Road, ["AVENUE"])
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _str_to_index(Road, numpy.array("AVENUE"))
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _str_to_index(Road, numpy.array(["AVENUE"]))
-        array([1], dtype=uint8)
+        array([1], dtype=int16)
 
         >>> _str_to_index(Road, numpy.array(["STREET", "AVENUE", "STREET"]))
-        array([0, 1, 0], dtype=uint8)
+        array([0, 1, 0], dtype=int16)
 
         >>> _str_to_index(Road, numpy.array(["AVENUE", "AVENUE", "BOULEVARD"]))
-        array([1, 1], dtype=uint8)
+        array([1, 1], dtype=int16)
 
     """
     values = numpy.asarray(value)

{openfisca_core-44.2.1 → 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.2.1 → openfisca_core-44.3.0}/openfisca_core/indexed_enums/types.py

@@ -10,9 +10,10 @@ from numpy import (
     int32 as IntDType,
     object_ as ObjDType,
     str_ as StrDType,
-    uint8 as EnumDType,
 )
 
+from .config import ENUM_ARRAY_DTYPE as EnumDType
+
 #: Type for enum indices arrays.
 IndexArray: TypeAlias = Array[EnumDType]
 

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"]