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

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

@@ -1,8 +1,38 @@
 # Changelog
 
-## 44.3.0
+## 44.5.0
 
-#### New Features
+#### 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`).
@@ -10,7 +40,7 @@
   - 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
+#### Technical changes
 
 - Backward compatibility is 100% maintained. Existing syntax via Projectors natively redirects to implicit links via modified `__getattr__`.
 

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

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

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

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

{openfisca_core-44.3.0 → 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.3.0 → openfisca_core-44.5.0}/openfisca_core/links/implicit.py

@@ -58,7 +58,19 @@ class ImplicitOne2ManyLink(One2ManyLink):
 
         if role is not None:
             roles = self._source_population.members_role
-            mask &= roles == 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
@@ -69,5 +81,31 @@ class ImplicitOne2ManyLink(One2ManyLink):
         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.3.0 → openfisca_core-44.5.0}/openfisca_core/links/many2one.py

@@ -129,13 +129,70 @@ class Many2OneLink(Link):
         )
 
     def has_role(self, role_value) -> numpy.ndarray:
-        """Boolean mask: does each source member have the given role?"""
+        """Boolean mask: does each source member have the given role?
+
+        The ``role`` array may contain raw values (ints, strings) or
+        ``Role`` objects depending on how the population was built.  When
+        ``role_value`` is a string we compare against the ``key`` of each
+        element to make the API ergonomic for callers such as
+        ``link.has_role("parent")`` or ``link.get_by_role(..., role_value="foo")``.
+        """
         r = self.role
         if r is None:
             msg = f"Link '{self.name}' has no role_field"
             raise ValueError(msg)
+
+        # if array holds object references, convert to their keys
+        if r.dtype == object:
+            try:
+                keys = numpy.fromiter(
+                    (getattr(x, "key", x) for x in r),
+                    dtype=object,
+                )
+            except Exception:
+                # fallback to direct comparison
+                return r == role_value
+            return keys == role_value
+
+        # numpy will perform elementwise comparison for numeric or string
         return r == role_value
 
+    # -- role-based access --------------------------------------------------
+
+    def get_by_role(
+        self,
+        variable_name: str,
+        period,
+        *,
+        role_value,
+    ) -> numpy.ndarray:
+        """Fetch a variable on the target only for members with a given role.
+
+        Parameters
+        ----------
+        variable_name : str
+            Name of the variable defined on the target entity.
+        period : Period
+            Period for which to calculate the variable.
+        role_value : object
+            The role to filter on (e.g. ``"parent"``).
+
+        Returns
+        -------
+        numpy.ndarray
+            Array of shape ``(n_source,)`` where only members whose
+            ``has_role(role_value)`` return ``True`` keep their computed
+            value; all others receive the variable's default (usually 0).
+        """
+        mask = self.has_role(role_value)
+        result = self.get(variable_name, period)
+        # zero out non-matching rows using dtype-preserving fill
+        if not mask.all():
+            # create a copy to avoid mutating cached results
+            result = result.copy()
+            result[~mask] = 0
+        return result
+
     # -- ID resolution ------------------------------------------------------
 
     def _get_target_ids(self, period) -> numpy.ndarray:
@@ -169,6 +226,28 @@ class Many2OneLink(Link):
 
         return rows
 
+    # -- ranking -----------------------------------------------------------
+
+    def rank(self, variable_name: str, period) -> numpy.ndarray:
+        """Rank each source member within its group by a variable value.
+
+        The rank is computed among all members sharing the same target
+        entity, sorted by the value of ``variable_name`` evaluated on the
+        *source* population.  The lowest value receives rank ``0``.
+
+        This is essentially a thin wrapper around
+        :meth:`~openfisca_core.populations.Population.get_rank`:
+
+        >>> person = simulation.persons
+        >>> person.links['household'].rank('age', period)
+        array([...])
+        """
+        source_pop = self._source_population
+        # criteria on source population
+        criteria = source_pop.simulation.calculate(variable_name, period)
+        # let Population.get_rank handle grouping and sorting
+        return source_pop.get_rank(self, criteria)
+
 
 # ---------------------------------------------------------------------------
 # Chained link getter
@@ -223,5 +302,9 @@ class _ChainedGetter:
         target_entity = target_pop.entity
         raise AttributeError(f"Entity '{target_entity.key}' has no link named '{name}'")
 
+    def rank(self, variable_name: str, period) -> numpy.ndarray:
+        # forward to outer link so that chaining keeps semantics
+        return self._outer.rank(variable_name, period)
+
 
 __all__ = ["Many2OneLink"]

{openfisca_core-44.3.0 → openfisca_core-44.5.0}/openfisca_core/links/one2many.py

@@ -176,6 +176,70 @@ class One2ManyLink(Link):
         c = self.count(period, role=role, condition=condition)
         return numpy.where(c > 0, s / c, 0)
 
+    # -- positional and role-based accessors --------------------------------
+
+    def nth(
+        self,
+        n: int,
+        variable_name: str,
+        period,
+        *,
+        role=None,
+        condition: numpy.ndarray | None = None,
+    ) -> numpy.ndarray:
+        """Value of the n-th target member for each source entity.
+
+        Parameters mirror :meth:`sum` plus ``n``.  If a source has fewer than
+        ``n+1`` targets the default value ``0`` is returned for that source.
+        The ordering of targets is the same as encountered in the underlying
+        population arrays (i.e. no particular sort).
+        """
+        values = self._target_values(variable_name, period)
+        source_rows, values = self._apply_filters(period, values, role, condition)
+
+        result = numpy.zeros(self._source_population.count, dtype=values.dtype)
+        # collect indices per source and pick the n-th
+        for src in range(self._source_population.count):
+            idxs = numpy.nonzero(source_rows == src)[0]
+            if n < len(idxs):
+                result[src] = values[idxs[n]]
+        return result
+
+    def get_by_role(
+        self,
+        variable_name: str,
+        period,
+        role_value,
+        *,
+        condition: numpy.ndarray | None = None,
+    ) -> numpy.ndarray:
+        """Value of the target having a unique role per source.
+
+        ``role_value`` is compared against the ``role_field`` on the target
+        population.  If multiple targets share the same role for a given source
+        the last encountered value is returned (behaviour mirrors
+        ``GroupPopulation.value_from_person``).
+        """
+        if self.role_field is None:
+            raise ValueError("Link has no role_field")
+
+        values = self._target_values(variable_name, period)
+        source_rows = self._source_rows(period)
+        roles = self._target_population.simulation.calculate(
+            self.role_field,
+            "eternity",
+        )
+
+        result = numpy.zeros(self._source_population.count, dtype=values.dtype)
+        mask = numpy.ones(len(source_rows), dtype=bool)
+        if condition is not None:
+            mask &= condition
+
+        for tgt_idx, src in enumerate(source_rows[mask]):
+            if roles[mask][tgt_idx] == role_value and src >= 0:
+                result[src] = values[mask][tgt_idx]
+        return result
+
     # -- internal -----------------------------------------------------------
 
     def _target_values(

{openfisca_core-44.3.0 → openfisca_core-44.5.0}/openfisca_core/links/tests/test_many2one.py

@@ -119,3 +119,31 @@ def test_many2one_role_helpers(sim):
 
     has_role_10 = link.has_role(10)
     assert numpy.array_equal(has_role_10, [True, False, True, False])
+
+    # also exercise the new helper
+    parent_rents = link.get_by_role("rent", "2024", role_value=10)
+    assert numpy.array_equal(parent_rents, [800.0, 0.0, 500.0, 0.0])
+
+
+def test_many2one_rank(sim):
+    """Ranking people by age within their household via the link.
+
+    The default ``sim`` fixture uses ``build_default_simulation`` which
+    does not populate ``household.members_entity_id`` correctly, so we
+    patch the group population manually using the input variable.
+    """
+    # ensure household group mappings match the input variable
+    sim.household.members_entity_id = sim.persons("household_id", "2024")
+    # reset any cached position so rank uses updated mapping
+    sim.household._members_position = None
+
+    link = sim.persons.links["household"]
+    # ages [50, 25, 20, 5] per person
+    ranks = link.rank("age", "2024")
+    # households: h0->[50,25] -> ranks [1,0]; h1->[20,5] -> ranks [1,0]
+    assert numpy.array_equal(ranks, [1, 0, 1, 0])
+
+    # chaining should also forward to outer link (no behavioural change)
+    chained = sim.persons.links["mother"].household
+    ranks2 = chained.rank("age", "2024")
+    assert numpy.array_equal(ranks2, ranks)

{openfisca_core-44.3.0 → openfisca_core-44.5.0}/openfisca_core/populations/_core_population.py

@@ -42,6 +42,12 @@ class CorePopulation:
 
     #: The :class:`~simulations.Simulation` for which the population is calculated.
     simulation: None | t.Simulation = None
+    # === Dynamic population helpers (optional) ===
+    _dynamic: bool = False
+    _permanent_ids: None | numpy.ndarray = None
+    _id_to_rownum: None | numpy.ndarray = None
+    _next_id: None | int = None
+    _period_index: None | dict = None
 
     def __init__(self, entity: t.CoreEntity, *__args: object, **__kwds: object) -> None:
         self.entity = entity
@@ -451,5 +457,31 @@ class CorePopulation:
             by_variable=holders_memory_usage,
         )
 
+    # -- Dynamic population period index helpers -------------------------
+
+    def snapshot_period(self, period: t.PeriodLike) -> None:
+        """Save the current ``_id_to_rownum`` mapping for ``period``.
+
+        If no ``_id_to_rownum`` exists yet, a default identity mapping is
+        created (positions == ids) sized to ``self.count``.
+        """
+        if self._period_index is None:
+            self._period_index = {}
+
+        if self._id_to_rownum is None:
+            # Default identity mapping: id -> row (0..count-1)
+            self._id_to_rownum = numpy.arange(self.count, dtype=numpy.intp)
+
+        self._period_index[periods.period(period)] = self._id_to_rownum.copy()
+
+    def get_period_id_to_rownum(self, period: t.PeriodLike) -> None | numpy.ndarray:
+        """Return the saved ``id -> rownum`` mapping for ``period`` or ``None``.
+
+        Returns ``None`` when no index was saved for that period.
+        """
+        if self._period_index is None:
+            return None
+        return self._period_index.get(periods.period(period))
+
 
 __all__ = ["CorePopulation"]

{openfisca_core-44.3.0 → openfisca_core-44.5.0}/openfisca_core/simulations/_build_default_simulation.py

@@ -30,6 +30,7 @@ class _BuildDefaultSimulation:
         ...     .add_count()
         ...     .add_ids()
         ...     .add_members_entity_id()
+        ...     .add_id_to_rownum()
         ... )
 
         >>> builder.count
@@ -121,6 +122,16 @@ class _BuildDefaultSimulation:
 
         return self
 
+    def add_id_to_rownum(self) -> Self:
+        """Set identity id_to_rownum mapping on all populations.
+
+        For static simulations, each entity's permanent ID equals its row
+        position, so id_to_rownum is the identity: id_to_rownum[i] = i.
+        """
+        for population in self.populations.values():
+            population._id_to_rownum = numpy.arange(self.count, dtype=numpy.intp)
+        return self
+
     def add_members_entity_id(self) -> Self:
         """Add ???
 

{openfisca_core-44.3.0 → openfisca_core-44.5.0}/openfisca_core/simulations/simulation_builder.py

@@ -327,6 +327,7 @@ class SimulationBuilder:
             .add_count()
             .add_ids()
             .add_members_entity_id()
+            .add_id_to_rownum()
             .simulation
         )
 
@@ -659,6 +660,7 @@ class SimulationBuilder:
         if plural_key in self.entity_counts:
             population.count = self.get_count(plural_key)
             population.ids = self.get_ids(plural_key)
+            population._id_to_rownum = numpy.arange(population.count, dtype=numpy.intp)
         if plural_key in self.memberships:
             population.members_entity_id = numpy.array(self.get_memberships(plural_key))
             population.members_role = numpy.array(self.get_roles(plural_key))

{openfisca_core-44.3.0 → openfisca_core-44.5.0}/openfisca_core/variables/variable.py

@@ -174,6 +174,21 @@ class Variable:
             "introspection_data",
         )
 
+        self.as_of = self.set(
+            attr,
+            "as_of",
+            setter=self.set_as_of,
+        )
+
+        if self.as_of and self.set_input:
+            msg = (
+                f'Variable "{self.name}" declares both as_of and set_input, '
+                f"which are incompatible. set_input helpers like "
+                f"set_input_divide_by_period scatter values across sub-periods "
+                f"and have no meaningful semantics for as_of variables."
+            )
+            raise ValueError(msg)
+
         formulas_attr, unexpected_attrs = helpers._partition(
             attr,
             lambda name, value: name.startswith(config.FORMULA_NAME_PREFIX),
@@ -297,6 +312,19 @@ class Variable:
             return textwrap.dedent(documentation)
         return None
 
+    def set_as_of(self, value):
+        if value is None or value is False:
+            return False
+        if value is True or value == "start":
+            return "start"
+        if value == "end":
+            return "end"
+        msg = (
+            f"Invalid value '{value}' for attribute 'as_of' in variable "
+            f"'{self.name}'. Allowed values are: True, 'start', 'end' (or False to disable)."
+        )
+        raise ValueError(msg)
+
     def set_set_input(self, set_input):
         if not set_input and self.baseline_variable:
             return self.baseline_variable.set_input

{openfisca_core-44.3.0 → openfisca_core-44.5.0}/setup.py

@@ -84,7 +84,7 @@ dev_requirements = [
 
 setup(
     name="OpenFisca-Core",
-    version="44.3.0",
+    version="44.5.0",
     author="OpenFisca Team",
     author_email="contact@openfisca.org",
     classifiers=[