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

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

@@ -1,5 +1,49 @@
 # Changelog
 
+## 44.5.0
+
+#### New features
+
+- Add `as_of` attribute to `Variable` for persistent vector variables.
+  - A variable declared with `as_of = True` (or `"start"` / `"end"`) stores its value at a given instant and automatically returns that value for any later period, until a new value is explicitly set — the vectorial analogue of OpenFisca parameters.
+  - `as_of = "start"` (default when `True`): lookup uses the start of the requested period as reference instant.
+  - `as_of = "end"`: lookup uses the end of the requested period (useful for annual variables like income tax).
+  - Lookup is O(log P) via `bisect` on a sorted instants index.
+  - Reference sharing: when consecutive stored values are identical, the same array object is reused, reducing memory usage for stable variables (e.g. `marital_status`, `housing_occupancy_status`).
+  - Stored arrays are read-only (`writeable=False`) to prevent accidental in-place mutation.
+  - Combining `as_of` with `set_input` dispatch helpers raises a `ValueError` at variable definition time.
+
+## 44.4.0 [#1364](https://github.com/openfisca/openfisca-core/pull/1364)
+
+#### New features
+
+- **Entity links**: role-based and positional accessors, and dynamic population period-index helpers.
+  - `Many2OneLink.get_by_role(variable_name, period, role_value=...)`, `One2ManyLink.get_by_role(...)` and `ImplicitOne2ManyLink.get_by_role(...)`.
+  - `Many2OneLink.rank(variable_name, period)` (and on chained getter, e.g. `person.links["mother"].household.rank("age", period)`).
+  - `One2ManyLink.nth(n, variable_name, period, role=..., condition=...)` for the n-th target member per source.
+  - `has_role(role_value)` now supports `Role` objects (comparison by `.key`) in addition to raw values.
+  - `CorePopulation.snapshot_period(period)` and `get_period_id_to_rownum(period)` for optional dynamic-population period indexing.
+
+#### Technical changes
+
+- Removed unused `openfisca_core.model_api` import in `tests/core/parameters_date_indexing/test_date_indexing.py`.
+- SimulationBuilder sets `_id_to_rownum` identity mapping for static simulations (`build_default_simulation`, `build_from_dict` / `build_from_entities`), for dynamic-population support.
+- Add `PYTHON` variable to `tasks/lint.mk` so `make lint PYTHON=.venv/bin/python` works; fix style in `test_link_accessors.py` and remove unused variable in `test_many2one.py`.
+
+## 44.3.0 [#1365](https://github.com/openfisca/openfisca-core/pull/1365)
+
+#### 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.5.0/OpenFisca_Core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenFisca-Core
-Version: 44.2.2
+Version: 44.5.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.5.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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenFisca-Core
-Version: 44.2.2
+Version: 44.5.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.5.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.5.0}/openfisca_core/holders/holder.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import Any
 
+import bisect
 import os
 import warnings
 
@@ -29,7 +30,10 @@ class Holder:
         self.variable = variable
         self.simulation = population.simulation
         self._eternal = self.variable.definition_period == periods.DateUnit.ETERNITY
+        self._as_of = getattr(self.variable, "as_of", False)
         self._memory_storage = storage.InMemoryStorage(is_eternal=self._eternal)
+        if self._as_of:
+            self._sorted_instants: list = []
 
         # By default, do not activate on-disk storage, or variable dropping
         self._disk_storage = None
@@ -54,6 +58,11 @@ class Holder:
             if key not in ("population", "formula", "simulation"):
                 new_dict[key] = value
 
+        # _sorted_instants must be an independent copy so that writes to the
+        # clone don't corrupt the original's index.
+        if self._as_of:
+            new_dict["_sorted_instants"] = list(self._sorted_instants)
+
         new_dict["population"] = population
         new_dict["simulation"] = population.simulation
 
@@ -90,10 +99,52 @@ class Holder:
         value = self._memory_storage.get(period)
         if value is not None:
             return value
+        if self._as_of:
+            value = self._get_as_of(period)
+            if value is not None:
+                return value
         if self._disk_storage:
             return self._disk_storage.get(period)
         return None
 
+    def _get_as_of(self, period):
+        """Return the most recent stored value at or before the reference instant.
+
+        Uses a sorted list of instants + bisect for O(log P) lookup.
+        Falls back to a linear scan if _sorted_instants is not yet initialised
+        (e.g. after clone()).
+        """
+        target = period.start if self._as_of == "start" else period.stop
+        sorted_instants = getattr(self, "_sorted_instants", None)
+
+        if sorted_instants is not None:
+            pos = bisect.bisect_right(sorted_instants, target)
+            if pos == 0:
+                return None
+            best_instant = sorted_instants[pos - 1]
+        else:
+            # Fallback linear scan (e.g. after clone without _sorted_instants)
+            best_instant = None
+            for known_period in self._memory_storage.get_known_periods():
+                start = known_period.start
+                if start <= target:
+                    if best_instant is None or start > best_instant:
+                        best_instant = start
+            if best_instant is None:
+                return None
+
+        for known_period in self._memory_storage.get_known_periods():
+            if known_period.start == best_instant:
+                return self._memory_storage.get(known_period)
+        return None
+
+    def _register_instant(self, period) -> None:
+        """Insert period.start into the sorted instants list (no duplicates)."""
+        instant = period.start
+        pos = bisect.bisect_left(self._sorted_instants, instant)
+        if pos == len(self._sorted_instants) or self._sorted_instants[pos] != instant:
+            self._sorted_instants.insert(pos, instant)
+
     def get_memory_usage(self) -> t.MemoryUsage:
         """Get data about the virtual memory usage of the Holder.
 
@@ -302,11 +353,25 @@ class Holder:
             >= self.simulation.memory_config.max_memory_occupation_pc
         )
 
+        if self._as_of:
+            # Reference sharing: reuse existing array object when value unchanged,
+            # otherwise store a read-only defensive copy so that callers cannot
+            # corrupt stored data by mutating their original array in-place.
+            prev = self._get_as_of(period)
+            if prev is not None and numpy.array_equal(value, prev):
+                value = prev  # prev is already read-only
+            else:
+                value = value.copy()
+                value.flags.writeable = False
+
         if should_store_on_disk:
             self._disk_storage.put(value, period)
         else:
             self._memory_storage.put(value, period)
 
+        if self._as_of:
+            self._register_instant(period)
+
     def put_in_cache(self, value, period) -> None:
         if self._do_not_store:
             return

{openfisca_core-44.2.2 → openfisca_core-44.5.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.5.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.5.0/openfisca_core/links/implicit.py

@@ -0,0 +1,111 @@
+"""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
+            # roles may be an object array of Role instances, so compare by key
+            if roles.dtype == object:
+                try:
+                    keys = numpy.fromiter(
+                        (getattr(x, "key", x) for x in roles),
+                        dtype=object,
+                    )
+                except Exception:
+                    mask &= roles == role
+                else:
+                    mask &= keys == role
+            else:
+                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]
+
+    # override to avoid relying on ``role_field`` which is meaningless for
+    # implicit links (the role information is stored on the source population)
+    def get_by_role(
+        self,
+        variable_name: str,
+        period,
+        role_value,
+        *,
+        condition: numpy.ndarray | None = None,
+    ) -> numpy.ndarray:
+        """Fetch value for a specific role value on a one-to-many implicit link.
+
+        This mirrors :meth:`One2ManyLink.get_by_role` but uses
+        ``self._source_population.members_role`` instead of a named role field
+        on the target population.
+        """
+        values = self._target_population.simulation.calculate(variable_name, period)
+        source_rows, values = self._apply_filters(period, values, role_value, condition)
+
+        result = numpy.zeros(self._source_population.count, dtype=values.dtype)
+        # last value wins (same semantics as GroupPopulation.value_from_person)
+        for tgt_idx, src in enumerate(source_rows):
+            if src >= 0:
+                result[src] = values[tgt_idx]
+        return result
+
+
+__all__ = ["ImplicitMany2OneLink", "ImplicitOne2ManyLink"]

openfisca_core-44.5.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"]