Runners

Runner Extensions

ISupervisedRunner

class catalyst.runners.supervised.ISupervisedRunner(input_key: Any = 'features', output_key: Any = 'logits', target_key: str = 'targets', loss_key: str = 'loss')

Bases: catalyst.core.runner.IRunner

IRunner for experiments with supervised model.

Parameters

• input_key – key in runner.batch dict mapping for model input

• output_key – key for runner.batch to store model output

• target_key – key in runner.batch dict mapping for target

• loss_key – key for runner.batch_metrics to store criterion loss output

forward(batch: Mapping[str, Any], **kwargs) → Mapping[str, Any]

Forward method for your Runner. Should not be called directly outside of runner. If your model has specific interface, override this method to use it

Parameters

• batch (Mapping[str, Any]) – dictionary with data batches from DataLoaders.

• **kwargs – additional parameters to pass to the model

Returns

dict with model output batch

handle_batch(batch: Mapping[str, Any]) → None

Inner method to handle specified data batch. Used to make a train/valid/infer stage during Experiment run.

Parameters

batch – dictionary with data batches from DataLoader.

Python API

Runner

class catalyst.runners.runner.Runner(*args, **kwargs)

Bases: catalyst.core.runner.IRunner

Single-stage deep learning Runner with user-friendly API.

Parameters

• *args –

• **kwargs –

get_callbacks(stage: str) → OrderedDict[str, Callback]

Returns the callbacks for a given stage.

get_criterion(stage: str) → torch.nn.modules.module.Module

Returns the criterion for a given stage.

get_engine() → catalyst.core.engine.IEngine

Returns the engine for a run.

get_loaders(stage: str) → OrderedDict[str, DataLoader]

Returns the loaders for a given stage.

get_loggers() → Dict[str, catalyst.core.logger.ILogger]

Returns the logger for a run.

get_model(stage: str) → torch.nn.modules.module.Module

Returns the model for a given stage.

get_optimizer(stage: str, model: torch.nn.modules.module.Module) → torch.optim.optimizer.Optimizer

Returns the optimizer for a given stage.

get_scheduler(stage: str, optimizer: torch.optim.optimizer.Optimizer) → torch.optim.lr_scheduler._LRScheduler

Returns the scheduler for a given stage.

get_stage_len(stage: str) → int

Returns the stage length in epochs for a given stage.

get_trial() → catalyst.core.trial.ITrial

Returns the trial for a run.

property hparams

Returns hyperparameters.

property name

Returns run name.

predict_batch(batch: Mapping[str, Any], **kwargs) → Mapping[str, Any]

Run model inference on specified data batch.

Parameters

• batch – dictionary with data batches from DataLoader.

• **kwargs – additional kwargs to pass to the model

Returns

model output dictionary

Return type

Mapping

Raises

NotImplementedError – if not implemented yet

predict_loader(*, loader: torch.utils.data.dataloader.DataLoader, model: torch.nn.modules.module.Module = None, engine: Union[IEngine, str] = None, seed: int = 42, fp16: bool = False, amp: bool = False, apex: bool = False, ddp: bool = False) → Generator

Runs model inference on PyTorch DataLoader and returns python generator with model predictions from runner.predict_batch.

Parameters

• loader – loader to predict

• model – model to use for prediction

• engine – engine to use for prediction

• seed – random seed to use before prediction

• fp16 – boolean flag to use half-precision training (AMP > APEX)

• amp – boolean flag to use amp half-precision

• apex – boolean flag to use apex half-precision

• ddp – if True will start training in distributed mode. Note: Works only with python scripts. No jupyter support.

Yields

bathes with model predictions

property seed

Experiment’s initial seed value.

property stages

Experiment’s stage names (array with one value).

train(*, loaders: OrderedDict[str, DataLoader], model: torch.nn.modules.module.Module, engine: Union[IEngine, str] = None, trial: catalyst.core.trial.ITrial = None, criterion: torch.nn.modules.module.Module = None, optimizer: torch.optim.optimizer.Optimizer = None, scheduler: torch.optim.lr_scheduler._LRScheduler = None, callbacks: Union[List[Callback], OrderedDict[str, Callback]] = None, loggers: Dict[str, ILogger] = None, seed: int = 42, hparams: Dict[str, Any] = None, num_epochs: int = 1, logdir: str = None, valid_loader: str = None, valid_metric: str = None, minimize_valid_metric: bool = True, verbose: bool = False, timeit: bool = False, check: bool = False, overfit: bool = False, load_best_on_end: bool = False, fp16: bool = False, amp: bool = False, apex: bool = False, ddp: bool = False) → None

Starts the train stage of the model.

Parameters

• loaders – dictionary with one or several torch.utils.data.DataLoader for training, validation or inference

• model – model to train

• engine – engine to use for model training

• trial – trial to use during model training

• criterion – criterion function for training

• optimizer – optimizer for training

• scheduler – scheduler for training

• callbacks – list or dictionary with Catalyst callbacks

• loggers – dictionary with Catalyst loggers

• seed – experiment’s initial seed value

• hparams – hyperparameters for the run

• num_epochs – number of training epochs

• logdir – path to output directory

• valid_loader – loader name used to calculate the metrics and save the checkpoints. For example, you can pass train and then the metrics will be taken from train loader.

• valid_metric – the key to the name of the metric by which the checkpoints will be selected.

• minimize_valid_metric – flag to indicate whether the valid_metric should be minimized or not.

• verbose – if True, it displays the status of the training to the console.

• timeit – if True, computes the execution time of training process and displays it to the console.

• check – if True, then only checks that pipeline is working (3 epochs only with 3 batches per loader)

• overfit – if True, then takes only one batch per loader for model overfitting, for advance usage please check BatchOverfitCallback

• load_best_on_end – if True, Runner will load best checkpoint state (model, optimizer, etc) according to validation metrics. Requires specified logdir.

• fp16 – boolean flag to use half-precision training (AMP > APEX)

• amp – boolean flag to use amp half-precision

• apex – boolean flag to use apex half-precision

• ddp – if True will start training in distributed mode. Note: Works only with python scripts. No jupyter support.

SupervisedRunner

class catalyst.runners.runner.SupervisedRunner(model: Union[torch.nn.modules.module.Module, Dict[str, torch.nn.modules.module.Module]] = None, engine: catalyst.core.engine.IEngine = None, input_key: Any = 'features', output_key: Any = 'logits', target_key: str = 'targets', loss_key: str = 'loss')

Bases: catalyst.runners.supervised.ISupervisedRunner, catalyst.runners.runner.Runner

Runner for experiments with supervised model.

Parameters

• model – Torch model instance

• engine – IEngine instance

• input_key – key in runner.batch dict mapping for model input

• output_key – key for runner.batch to store model output

• target_key – key in runner.batch dict mapping for target

• loss_key – key for runner.batch_metrics to store criterion loss output

get_callbacks(stage: str) → OrderedDict[str, Callback]

Prepares the callbacks for selected stage.

Parameters

stage – stage name

Returns

dictionary with stage callbacks

predict_batch(batch: Mapping[str, Any], **kwargs) → Mapping[str, Any]

Run model inference on specified data batch.

Warning

You should not override this method. If you need specific model call, override forward() method

Parameters

• batch – dictionary with data batch from DataLoader.

• **kwargs – additional kwargs to pass to the model

Returns

model output dictionary

Return type

Mapping[str, Any]

Config API

ConfigRunner

class catalyst.runners.config.ConfigRunner(config: Dict)

Bases: catalyst.core.runner.IRunner

Runner created from a dictionary configuration file.

Parameters

config – dictionary with parameters

get_callbacks(stage: str) → OrderedDict[str, Callback]

Returns the callbacks for a given stage.

get_criterion(stage: str) → Union[torch.nn.modules.module.Module, Dict[str, torch.nn.modules.module.Module]]

Returns the criterion for a given stage.

get_engine() → catalyst.core.engine.IEngine

Returns the engine for the run.

get_loaders(stage: str) → OrderedDict[str, DataLoader]

Returns loaders for a given stage.

Parameters

stage – stage name

Returns

loaders objects

Return type

Dict

get_loggers() → Dict[str, catalyst.core.logger.ILogger]

Returns the loggers for the run.

get_model(stage: str) → Union[torch.nn.modules.module.Module, Dict[str, torch.nn.modules.module.Module]]

Returns the model for a given stage.

get_optimizer(model: Union[torch.nn.modules.module.Module, Dict[str, torch.nn.modules.module.Module]], stage: str) → Union[torch.optim.optimizer.Optimizer, Dict[str, torch.optim.optimizer.Optimizer]]

Returns the optimizer for a given stage and epoch.

Parameters

• model – model or a dict of models

• stage – current stage name

Returns

optimizer for selected stage and epoch

get_scheduler(optimizer: Union[torch.optim.optimizer.Optimizer, Dict[str, torch.optim.optimizer.Optimizer]], stage: str) → Union[torch.optim.lr_scheduler._LRScheduler, Dict[str, torch.optim.lr_scheduler._LRScheduler]]

Returns the scheduler for a given stage.

get_stage_len(stage: str) → int

Returns number of epochs for the selected stage.

Parameters

stage – current stage

Returns

number of epochs in stage

Example:

>>> runner.get_stage_len("pretraining")
3

get_trial() → catalyst.core.trial.ITrial

Returns the trial for the run.

property hparams

Returns hyper parameters

property logdir

docs.

Type

@TODO

property name

Returns run name for monitoring tools.

property seed

Experiment’s seed for reproducibility.

property stages

Experiment’s stage names.

SupervisedConfigRunner

class catalyst.runners.config.SupervisedConfigRunner(config: Dict = None, input_key: Any = 'features', output_key: Any = 'logits', target_key: str = 'targets', loss_key: str = 'loss')

Bases: catalyst.runners.supervised.ISupervisedRunner, catalyst.runners.config.ConfigRunner

ConfigRunner for supervised tasks

Parameters

• config – dictionary with parameters

• input_key – key in runner.batch dict mapping for model input

• output_key – key for runner.batch to store model output

• target_key – key in runner.batch dict mapping for target

• loss_key – key for runner.batch_metrics to store criterion loss output

Hydra API

HydraRunner

class catalyst.runners.hydra.HydraRunner(cfg: omegaconf.dictconfig.DictConfig)

Bases: catalyst.core.runner.IRunner

Runner created from a hydra configuration file.

Parameters

cfg – Hydra dictionary with parameters

get_callbacks(stage: str) → OrderedDict[str, Callback]

Returns the callbacks for a given stage.

get_criterion(stage: str) → Union[torch.nn.modules.module.Module, Dict[str, torch.nn.modules.module.Module]]

Returns the criterion for a given stage.

get_engine() → catalyst.core.engine.IEngine

Returns the engine for the run.

get_loaders(stage: str) → Dict[str, torch.utils.data.dataloader.DataLoader]

Returns loaders for a given stage.

Parameters

stage – stage name

Returns

loaders objects

Return type

Dict

get_loggers() → Dict[str, catalyst.core.logger.ILogger]

Returns the loggers for the run.

get_model(stage: str) → Union[torch.nn.modules.module.Module, Dict[str, torch.nn.modules.module.Module]]

Returns the model for a given stage.

get_optimizer(model: Union[torch.nn.modules.module.Module, Dict[str, torch.nn.modules.module.Module]], stage: str) → Union[torch.optim.optimizer.Optimizer, Dict[str, torch.optim.optimizer.Optimizer]]

Returns the optimizer for a given stage and epoch.

Parameters

• model – model or a dict of models

• stage – current stage name

Returns

optimizer for selected stage and epoch

get_scheduler(optimizer: Union[torch.optim.optimizer.Optimizer, Dict[str, torch.optim.optimizer.Optimizer]], stage: str) → Union[torch.optim.lr_scheduler._LRScheduler, Dict[str, torch.optim.lr_scheduler._LRScheduler]]

Returns the schedulers for a given stage.

get_stage_len(stage: str) → int

Returns number of epochs for the selected stage.

Parameters

stage – current stage

Returns

number of epochs in stage

Example:

>>> runner.get_stage_len("pretraining")
3

get_trial() → catalyst.core.trial.ITrial

Returns the trial for the run.

property hparams

Hyperparameters

property logdir

docs.

Type

@TODO

property name

Returns run name for monitoring tools.

property seed

Experiment’s seed for reproducibility.

property stages

Experiment’s stage names.

SupervisedHydraRunner

class catalyst.runners.hydra.SupervisedHydraRunner(cfg: omegaconf.dictconfig.DictConfig = None, input_key: Any = 'features', output_key: Any = 'logits', target_key: str = 'targets', loss_key: str = 'loss')

Bases: catalyst.runners.supervised.ISupervisedRunner, catalyst.runners.hydra.HydraRunner

HydraRunner for supervised tasks

Parameters

• cfg – Hydra dictionary with parameters

• input_key – key in runner.batch dict mapping for model input

• output_key – key for runner.batch to store model output

• target_key – key in runner.batch dict mapping for target

• loss_key – key for runner.batch_metrics to store criterion loss output