Shortcuts

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')[source]

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][source]

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[source]

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)[source]

Bases: catalyst.core.runner.IRunner

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

Parameters
  • *args

  • **kwargs

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

Returns the callbacks for a given stage.

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

Returns the criterion for a given stage.

get_engine() → catalyst.core.engine.IEngine[source]

Returns the engine for a run.

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

Returns the loaders for a given stage.

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

Returns the logger for a run.

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

Returns the model for a given stage.

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

Returns the optimizer for a given stage.

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

Returns the scheduler for a given stage.

get_stage_len(stage: str) → int[source]

Returns the stage length in epochs for a given stage.

get_trial() → catalyst.core.trial.ITrial[source]

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][source]

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[source]

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[source]

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')[source]

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][source]

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][source]

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)[source]

Bases: catalyst.core.runner.IRunner

Runner created from a dictionary configuration file.

Parameters

config – dictionary with parameters

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

Returns the callbacks for a given stage.

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

Returns the criterion for a given stage.

get_engine() → catalyst.core.engine.IEngine[source]

Returns the engine for the run.

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

Returns loaders for a given stage.

Parameters

stage – stage name

Returns

loaders objects

Return type

Dict

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

Returns the loggers for the run.

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

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]][source]

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]][source]

Returns the scheduler for a given stage.

get_stage_len(stage: str) → int[source]

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[source]

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')[source]

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)[source]

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][source]

Returns the callbacks for a given stage.

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

Returns the criterion for a given stage.

get_engine() → catalyst.core.engine.IEngine[source]

Returns the engine for the run.

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

Returns loaders for a given stage.

Parameters

stage – stage name

Returns

loaders objects

Return type

Dict

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

Returns the loggers for the run.

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

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]][source]

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]][source]

Returns the schedulers for a given stage.

get_stage_len(stage: str) → int[source]

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[source]

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')[source]

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