nnpd.core.api
=============

.. py:module:: nnpd.core.api

.. autoapi-nested-parse::

   The extension surface. No Gaussian settings or metric names live here.



Classes
-------

.. autoapisummary::

   nnpd.core.api.Product
   nnpd.core.api.Metric
   nnpd.core.api.Plot
   nnpd.core.api.Experiment
   nnpd.core.api.Analysis
   nnpd.core.api.Context


Functions
---------

.. autoapisummary::

   nnpd.core.api.implementation_hash
   nnpd.core.api.load_experiment
   nnpd.core.api.load_analysis


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

.. py:function:: implementation_hash(functions: tuple[Callable, ...], version: str) -> dict

   Hash complete source modules, not just the registration function.

   Declare helper modules in Product.sources or Experiment.sources. External
   simulators/data releases should be identified explicitly in the recipe/version.


.. py:class:: Product

   A reusable dataset; dependencies are resolved and cached before build().


   .. py:attribute:: build
      :type:  Callable[[Context, Mapping[str, nnpd.core.storage.Artifact], nnpd.core.storage.Writer], dict]


   .. py:attribute:: needs
      :type:  tuple[str, ...]
      :value: ()



   .. py:attribute:: settings
      :type:  Callable[[Context], dict]


   .. py:attribute:: sources
      :type:  tuple[Callable, ...]
      :value: ()



   .. py:attribute:: version
      :type:  str
      :value: '1'



.. py:class:: Metric

   .. py:attribute:: compute
      :type:  Callable[[Context, Mapping[str, nnpd.core.storage.Artifact]], Any]


   .. py:attribute:: needs
      :type:  tuple[str, ...]
      :value: ()



.. py:class:: Plot

   .. py:attribute:: draw
      :type:  Callable[[Context, Mapping[str, nnpd.core.storage.Artifact]], Mapping[str, Any]]


   .. py:attribute:: needs
      :type:  tuple[str, ...]
      :value: ()



.. py:class:: Experiment

   Bases: :py:obj:`abc.ABC`


   What is trained: problem, prior, training data, model and training procedure.

   Selected by "experiment" in the training settings. The runner owns execution and files.


   .. py:attribute:: name
      :value: 'experiment'



   .. py:attribute:: version
      :value: '1'



   .. py:method:: members(settings: dict) -> list[dict]

      A fixed comparison cohort within each sweep configuration.



   .. py:method:: validate(settings: dict) -> None

      Fail before any sampling or training, including for invalid alternatives.



   .. py:method:: estimate(settings: dict, member: dict) -> dict

      Training workload shown by the plan.



   .. py:method:: make_problem(settings: dict) -> Any
      :abstractmethod:



   .. py:method:: make_prior(settings: dict, member: dict, problem: Any) -> Any
      :abstractmethod:



   .. py:method:: sample_training(context: Context, writer: nnpd.core.storage.Writer) -> dict
      :abstractmethod:



   .. py:method:: build_model(context: Context) -> torch.nn.Module
      :abstractmethod:



   .. py:method:: train(context: Context, model: torch.nn.Module) -> dict
      :abstractmethod:


      Modify model in place; return JSON-serializable training history.



   .. py:method:: signature(stage: str, context: Context) -> dict

      Override for cross-run sharing; conservative default uses all training settings.



   .. py:method:: sources(stage: str) -> tuple[Callable, ...]

      Include modules implementing transitive scientific dependencies.



   .. py:method:: model_seed(context: Context) -> int


.. py:class:: Analysis

   What is computed from trained models: shared datasets, metrics and plots. Never trains.

   Selected by "analysis" in the analysis settings. "training" and "model" are the
   reserved datasets every product, metric and plot may depend on.


   .. py:attribute:: name
      :value: 'analysis'



   .. py:method:: validate(settings: dict) -> None

      Fail before anything is computed.



   .. py:method:: estimate(settings: dict, problem: Any, prior: Any) -> dict

      Workload of analyzing one trained model; limit violations go in "errors".



   .. py:method:: products() -> dict[str, Product]


   .. py:method:: metrics() -> dict[str, Metric]


   .. py:method:: plots() -> dict[str, Plot]


.. py:function:: load_experiment(specification: str) -> Experiment

   Instantiate the trusted module:class named by "experiment" in the training settings.


.. py:function:: load_analysis(specification: str) -> Analysis

   Instantiate the trusted module:class named by "analysis" in the analysis settings.


.. py:class:: Context

   .. py:attribute:: experiment
      :type:  Experiment


   .. py:attribute:: training_settings
      :type:  dict


   .. py:attribute:: member
      :type:  dict


   .. py:attribute:: store
      :type:  nnpd.core.storage.Store


   .. py:attribute:: runtime
      :type:  nnpd.core.runtime.Runtime


   .. py:attribute:: run_dir
      :type:  pathlib.Path


   .. py:attribute:: analysis
      :type:  Analysis | None
      :value: None



   .. py:attribute:: analysis_settings
      :type:  dict | None
      :value: None



   .. py:attribute:: problem
      :type:  Any


   .. py:attribute:: prior
      :type:  Any


   .. py:attribute:: artifacts
      :type:  dict[str, nnpd.core.storage.Artifact]


   .. py:method:: seed(namespace: str, *, base: int | None = None, member: bool = True) -> int


   .. py:method:: rng(namespace: str, *, base: int | None = None, member: bool = True)


   .. py:property:: model
      :type: torch.nn.Module



   .. py:method:: require(name: str) -> nnpd.core.storage.Artifact

      Get or build a named dataset. Cycles and unknown dependencies fail clearly.



   .. py:method:: dependencies(names: tuple[str, ...]) -> dict[str, nnpd.core.storage.Artifact]