Source code for sierra.core.models.interface

# Copyright 2020 John Harwell, All rights reserved.
#
#  SPDX-License-Identifier: MIT
"""
Interface classes for the mathematical models framework in SIERRA.

Models can be run during stage 3 and added to any configured graph during stage
4.
"""

# Core packages

# 3rd party packages
import polars as pl

# Project packages
from sierra.core.variables import batch_criteria as bc
from sierra.core import types, exproot, batchroot




class IIntraExpModel1D:
    """Interface for one-dimensional models.

    1D models are those that generate a single time series from zero or more
    experimental outputs within a *single* :term:`Experiment`.  Models will be
    rendered as lines on a :func:`~sierra.core.graphs.stacked_line`.  Models
    "target" one or more graphs which are already configured to be generated,
    and will show up as additional lines on the generated graph.

    The dataframes generated by models implement this interface MUST have
    indices of the same length as those in the graphs they target.
    """

    def __init__(self, params: types.YAMLDict) -> None:
        pass



    def run(
        self,
        criteria: bc.XVarBatchCriteria,
        exp_num: int,
        cmdopts: types.Cmdopts,
        pathset: exproot.PathSet,
    ) -> list[pl.DataFrame]:
        """Run the model and generate a list of dataframes.

        Each dataframe can (potentially) target different graphs. All dataframes
        should contain a single column named ``model``, with each row of the
        dataframe containing the model prediction at the :term:`Experimental
        Run` interval corresponding to the row (e.g., row 7 contains the model
        prediction for interval 7).

        """
        raise NotImplementedError




    def should_run(
        self, criteria: bc.XVarBatchCriteria, cmdopts: types.Cmdopts, exp_num: int
    ) -> bool:
        """
        Determine if the model should be run for the specified experiment.

        Some models may only be valid/make sense to run for a subset of
        experiments within a batch, so models can be selectively executed with
        this function.
        """
        raise NotImplementedError


    def __repr__(self) -> str:
        """
        Return the UUID string of the model name.
        """
        raise NotImplementedError





class IInterExpModel1D:
    """Interface for one-dimensional models.

    1D models are those that generate a single time series from any number of
    experimental outputs across *all* experiments in a batch (or from another
    source).  Models will be rendered as lines on a
    :func:`~sierra.core.graphs.summary_line`.  Models "target" one or more
    :term:`Collated Output Data` files which are already configured to be
    generated, and will show up as additional lines on the generated graph.
    """

    def __init__(self, params: types.YAMLDict) -> None:
        pass



    def run(
        self,
        criteria: bc.XVarBatchCriteria,
        cmdopts: types.Cmdopts,
        pathset: batchroot.PathSet,
    ) -> list[pl.DataFrame]:
        """Run the model and generate list of dataframes.

        Each returned dataframe must have:

        - The index named ``Experiment ID``

        - Indices which correspond to ``criteria.gen_exp_names()``

        Each dataframe can (potentially) target a different graph.

        """
        raise NotImplementedError




    def should_run(
        self, criteria: bc.XVarBatchCriteria, cmdopts: types.Cmdopts
    ) -> bool:
        """
        Determine if the model should be run for the specified batch criteria.

        Some models may only be valid/make sense to run for some batch criteria,
        so models can be selectively executed with this function.
        """
        raise NotImplementedError


    def __repr__(self) -> str:
        """
        Return the UUID string of the model name.
        """
        raise NotImplementedError



__all__ = [
    "IInterExpModel1D",
    "IIntraExpModel1D",
]