# Copyright 2020 John Harwell, All rights reserved.
#
# SPDX-License-Identifier: MIT
"""Interface classes for the mathematical models framework in SIERRA.
Models can be run and added to any configured graph during stage 4.
"""
# Core packages
import typing as tp
# 3rd party packages
import pandas as pd
import implements
# Project packages
from sierra.core.variables import batch_criteria as bc
from sierra.core import types
[docs]class IConcreteIntraExpModel1D(implements.Interface):
"""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
:class:`~sierra.core.graphs.stacked_line_graph.StackedLineGraph`. Models
"target" one or more CSV files which are already configured to be generated,
and will show up as additional lines on the generated graph.
"""
[docs] def run(self,
criteria: bc.IConcreteBatchCriteria,
exp_num: int,
cmdopts: types.Cmdopts) -> tp.List[pd.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
[docs] def run_for_exp(self,
criteria: bc.IConcreteBatchCriteria,
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
[docs] def target_csv_stems(self) -> tp.List[str]:
"""Return a list of CSV file stems that the model is targeting.
File stem = path sans directory path and extension.
"""
raise NotImplementedError
[docs] def legend_names(self) -> tp.List[str]:
"""Compute names for the model predictions for the target graph legend.
Applicable to:
- :class:`~sierra.core.graphs.stacked_line_graph.StackedLineGraph`
"""
raise NotImplementedError
[docs] def __repr__(self) -> str:
"""
Return the UUID string of the model name.
"""
raise NotImplementedError
[docs]class IConcreteIntraExpModel2D(implements.Interface):
"""Interface for two-dimensional models.
2D models are those that generate a list of 2D matrices, forming a 2D time
series. Can be built from zero or more experimental outputs from a *single*
:term:`Experiment`. Models "target" one or more CSV files which are already
configured to be generated, and will show up as additional lines on the
generated graph.
"""
[docs] def run(self,
criteria: bc.IConcreteBatchCriteria,
exp_num: int,
cmdopts: types.Cmdopts) -> tp.List[pd.DataFrame]:
"""Run the model and generate a list of dataframes.
Each dataframe can (potentially) target a different graph. Each
dataframe should be a NxM grid (with N not necessarily equal to M). All
dataframes do not have to be the same dimensions. The index of a given
dataframe in a list should correspond to the model value for
interval/timestep.
"""
raise NotImplementedError
[docs] def run_for_exp(self,
criteria: bc.IConcreteBatchCriteria,
cmdopts: types.Cmdopts,
exp_num: int) -> bool:
"""Determine if a 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
[docs] def target_csv_stems(self) -> tp.List[str]:
"""Return a list of CSV file stems that the model is targeting.
File stem = path sans directory path and extension.
"""
raise NotImplementedError
[docs] def __repr__(self) -> str:
"""
Return the UUID string of the model name.
"""
raise NotImplementedError
[docs]class IConcreteInterExpModel1D(implements.Interface):
"""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
:class:`~sierra.core.graphs.summary_line_graph.SummaryLineGraph`. Models
"target" one or more CSV files which are already configured to be generated,
and will show up as additional lines on the generated graph.
"""
[docs] def run(self,
criteria: bc.IConcreteBatchCriteria,
cmdopts: types.Cmdopts) -> tp.List[pd.DataFrame]:
"""Run the model and generate list of dataframes.
Each dataframe can (potentially) target a different graph. Each
dataframe should contain a single row, with one column for the predicted
value of the model for each experiment in the batch.
"""
raise NotImplementedError
[docs] def run_for_batch(self,
criteria: bc.IConcreteBatchCriteria,
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
[docs] def target_csv_stems(self) -> tp.List[str]:
"""Return a list of CSV file stems that the model is targeting.
File stem = path sans directory path and extension.
"""
raise NotImplementedError
[docs] def legend_names(self) -> tp.List[str]:
"""Compute names for the model predictions for the target graph legend.
Applicable to:
- ~sierra.core.graphs.summary_line_graph.SummaryLineGraph`
"""
raise NotImplementedError
[docs] def __repr__(self) -> str:
"""
Return the UUID string of the model name.
"""
raise NotImplementedError
__api__ = ['IConcreteIntraExpModel1D',
'IConcreteIntraExpModel2D',
'IConcreteInterExpModel1D']