diff --git a/docs/autogen.py b/docs/autogen.py index d736a12..6775941 100644 --- a/docs/autogen.py +++ b/docs/autogen.py @@ -10,6 +10,7 @@ import pyshac import pyshac.config.hyperparameters as hp import pyshac.config.data as data +import pyshac.config.callbacks as callbacks import pyshac.core.engine as optimizer import pyshac.core.managed.tf_engine as tf_optimizer import pyshac.core.managed.keras_engine as keras_optimizer @@ -65,6 +66,17 @@ (data.Dataset, '*'), ], }, + { + 'page': 'config/callbacks.md', + 'classes': [ + (callbacks.Callback, '*'), + (callbacks.History, []), + (callbacks.CSVLogger, []), + ], + 'functions': [ + callbacks.get_history, + ] + }, { 'page': 'core/engine.md', 'classes': [ diff --git a/mkdocs.yml b/mkdocs.yml index 46da791..1fad850 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,6 +41,7 @@ pages: - Config: - Hyper Parameters: config/hyperparameters.md - Datasets: config/data.md + - Callbacks: config/callbacks.md - Core: - SHAC: core/engine.md - PyTorch SHAC: core/torch_engine.md diff --git a/pyshac/__init__.py b/pyshac/__init__.py index 12ae529..83e139d 100644 --- a/pyshac/__init__.py +++ b/pyshac/__init__.py @@ -5,4 +5,4 @@ from pyshac.config.data import Dataset from pyshac.core.engine import SHAC -__version__ = '0.3.0.5' +__version__ = '0.3.1' diff --git a/pyshac/config/callbacks.py b/pyshac/config/callbacks.py index 7d8a438..f571a76 100644 --- a/pyshac/config/callbacks.py +++ b/pyshac/config/callbacks.py @@ -61,24 +61,78 @@ def set_engine(self, engine): self.engine = engine def on_train_begin(self, logs=None): + """ + Called at the beginning of training. + + # Arguments + logs (dict | None): dictionary of logs. + """ pass def on_train_end(self, logs=None): + """ + Called at the end of training. + + # Arguments + logs (dict | None): dictionary of logs. + """ pass def on_epoch_begin(self, epoch, logs=None): + """ + Called at the start of an epoch. + + # Arguments + epoch (int): index of epoch. + logs (dict | None): dictionary of logs. + """ pass def on_epoch_end(self, epoch, logs=None): + """ + Called at the end of an epoch. + + # Arguments + epoch (int): index of epoch. + logs (dict | None): dictionary of logs. + """ pass def on_evaluation_begin(self, params, logs=None): + """ + Called before the generated parameters are evaluated. + + # Arguments: + params (list(OrderedDict)): A list of OrderedDicts, + such that each item is a dictionary of the names + and sampled values of a HyperParemeterList. + logs (dict | None): dictionary of logs. + """ pass def on_evaluation_ended(self, evaluations, logs=None): + """ + Called after the generated parameters are evaluated. + + # Arguments: + evaluations (list(float)): A list of floating point + values, corresponding to the provided parameter + settings. + logs (dict | None): dictionary of logs. + """ pass def on_dataset_changed(self, dataset, logs=None): + """ + Called with the dataset maintained by the engine is + updated with new samples or data. + + # Arguments: + dataset (Dataset): A Dataset object which contains + the history of sampled parameters and their + corresponding evaluation values. + logs (dict | None): dictionary of logs. + """ pass @@ -229,10 +283,23 @@ def __init__(self): super(History, self).__init__() def on_train_begin(self, logs=None): + """ + Initializes the epoch list and history dictionary. + + # Arguments: + logs (dict | None): dictionary of logs. + """ self.epochs = [] self.history = logs or {} def on_epoch_end(self, epoch, logs=None): + """ + Adds the current epoch's log values to the history. + + # Arguments: + epoch (int): index of epoch. + logs (dict | None): dictionary of logs. + """ logs = logs or {} self.epochs.append(epoch) diff --git a/pyshac/core/engine.py b/pyshac/core/engine.py index b4cf3d6..4425f75 100644 --- a/pyshac/core/engine.py +++ b/pyshac/core/engine.py @@ -163,6 +163,11 @@ def fit(self, eval_fn, skip_cv_checks=False, early_stop=False, relax_checks=Fals callbacks (list | None): Optional list of callbacks that are executed when the engine is being trained. `History` callback is automatically added for all calls to `fit`. + + # Returns: + A `History` object which tracks all the important information + during training, and can be accessed using `history.history` + as a dictionary. """ num_epochs = self.total_budget // self.num_workers @@ -361,6 +366,11 @@ def fit_dataset(self, dataset_path, skip_cv_checks=False, early_stop=False, pres required number of samples by the engine. FileNotFoundError: If the dataset is not available at the provided filepath. + + # Returns: + A `History` object which tracks all the important information + during training, and can be accessed using `history.history` + as a dictionary. """ if self.parameters is None: raise ValueError("Parameter list cannot be `None` when training " @@ -1149,6 +1159,11 @@ def fit(self, eval_fn, skip_cv_checks=False, early_stop=False, relax_checks=Fals callbacks (list | None): Optional list of callbacks that are executed when the engine is being trained. `History` callback is automatically added for all calls to `fit`. + + # Returns: + A `History` object which tracks all the important information + during training, and can be accessed using `history.history` + as a dictionary. """ return super(SHAC, self).fit(eval_fn, skip_cv_checks=skip_cv_checks, early_stop=early_stop, relax_checks=relax_checks, diff --git a/pyshac/core/managed/keras_engine.py b/pyshac/core/managed/keras_engine.py index 264064d..bb47b40 100644 --- a/pyshac/core/managed/keras_engine.py +++ b/pyshac/core/managed/keras_engine.py @@ -175,6 +175,11 @@ def fit(self, eval_fn, skip_cv_checks=False, early_stop=False, relax_checks=Fals callbacks (list | None): Optional list of callbacks that are executed when the engine is being trained. `History` callback is automatically added for all calls to `fit`. + + # Returns: + A `History` object which tracks all the important information + during training, and can be accessed using `history.history` + as a dictionary. """ return super(KerasSHAC, self).fit(eval_fn, skip_cv_checks=skip_cv_checks, early_stop=early_stop, relax_checks=relax_checks, diff --git a/pyshac/core/managed/tf_engine.py b/pyshac/core/managed/tf_engine.py index 41ad1ce..b5a6d1c 100644 --- a/pyshac/core/managed/tf_engine.py +++ b/pyshac/core/managed/tf_engine.py @@ -156,6 +156,11 @@ def fit(self, eval_fn, skip_cv_checks=False, early_stop=False, relax_checks=Fals callbacks (list | None): Optional list of callbacks that are executed when the engine is being trained. `History` callback is automatically added for all calls to `fit`. + + # Returns: + A `History` object which tracks all the important information + during training, and can be accessed using `history.history` + as a dictionary. """ return super(TensorflowSHAC, self).fit(eval_fn, skip_cv_checks=skip_cv_checks, early_stop=early_stop, relax_checks=relax_checks, diff --git a/pyshac/core/managed/torch_engine.py b/pyshac/core/managed/torch_engine.py index 64dc94f..a32510c 100644 --- a/pyshac/core/managed/torch_engine.py +++ b/pyshac/core/managed/torch_engine.py @@ -130,6 +130,11 @@ def fit(self, eval_fn, skip_cv_checks=False, early_stop=False, relax_checks=Fals callbacks (list | None): Optional list of callbacks that are executed when the engine is being trained. `History` callback is automatically added for all calls to `fit`. + + # Returns: + A `History` object which tracks all the important information + during training, and can be accessed using `history.history` + as a dictionary. """ return super(TorchSHAC, self).fit(eval_fn, skip_cv_checks=skip_cv_checks, early_stop=early_stop, relax_checks=relax_checks,