euromod_linking.runner
======================

.. py:module:: euromod_linking.runner

.. autoapi-nested-parse::

   Executing a EUROMOD simulation on transformed input.

   Plain functions returning plain values. The library's job is to *produce*
   transformed microdata (`apply_scenario`); running it is one call to
   ``System.run()``. An application that wants caching, retries or a run registry
   writes that around `apply_scenario` rather than plugging a strategy in here.

   Dataset resolution and argument normalisation live here because they are model
   knowledge: which .txt backs a dataset name, and how grouped constants must be
   shaped for ``constantsToOverwrite``.

   Paths are always arguments — a library must not silently resolve which model it
   runs against from the environment.



Exceptions
----------

.. autoapisummary::

   euromod_linking.runner.RunError


Functions
---------

.. autoapisummary::

   euromod_linking.runner.bestmatch_dataset_name
   euromod_linking.runner.dataset_file
   euromod_linking.runner.execute
   euromod_linking.runner.fallback_candidates
   euromod_linking.runner.frames_identical
   euromod_linking.runner.normalize_constants
   euromod_linking.runner.resolve_dataset


Module Contents
---------------

.. py:exception:: RunError



   A simulation could not be executed (bad dataset, engine failure, ...).


.. py:function:: bestmatch_dataset_name(system) -> str | None

   The connector's own best-match dataset for a system (authoritative).


.. py:function:: dataset_file(dataset_name: str, cc: str, input_path: str) -> pathlib.Path | None

   Locate a dataset .txt, supporting a flat repository (all files in one
   directory) or a per-country subdirectory layout.


.. py:function:: execute(system, data, *, country_code: str, input_path: str, dataset_name: str | None = None, constants=None, addons=None, extensions=None)

   Run one simulation and return its output DataFrame.

   Raises RunError if the engine fails.


.. py:function:: fallback_candidates(cc: str, input_path: str) -> list[pathlib.Path]

   All CC_*.txt datasets, newest name first.


.. py:function:: frames_identical(a, b) -> bool

   Are two simulation outputs the same to the last cent?

   Used to detect a scenario that transformed the input but had no effect on
   the results — an invalid run, not 'the reform has no impact'.


.. py:function:: normalize_constants(constants) -> dict

   Normalise constants to the ``{(name, group): value}`` shape ``run()`` wants.

   Accepts ``{"$name": v}``, ``{"$name|group": v}`` (split on the last ``|``) or
   a list of ``{"name", "group"?, "value"}``. Uprating factors are grouped by
   year, e.g. ``("$f_cpi", "2023")``.


.. py:function:: resolve_dataset(system, country_code: str, dataset_name: str | None, input_path: str)

   Resolve which dataset file to run.

   Explicit name wins; otherwise the system's best match, and if that file is
   not on disk, the newest available CC_* dataset — flagged, never silent.
   Returns (path, resolved_name, bestmatch_name, used_bestmatch).