Core

class catalyst.core.callback.CallbackOrder

Bases: enum.IntFlag

An enumeration.

External = 200

Internal = 0

Logging = 100

Metric = 20

MetricAggregation = 40

Optimizer = 60

Scheduler = 120

Validation = 80

class catalyst.core.callback.CallbackNode

Bases: enum.IntFlag

An enumeration.

All = 0

Master = 1

Worker = 2

class catalyst.core.callback.Callback(order: int, node: int = <CallbackNode.All: 0>, type: int = <CallbackType.Stage: 0>)

Bases: object

Abstract class that all callback (e.g., Logger) classes extends from. Must be extended before usage.

usage example:

-- stage start
---- epoch start (one epoch - one run of every loader)
------ loader start
-------- batch start
-------- batch handler
-------- batch end
------ loader end
---- epoch end
-- stage end

exception – if an Exception was raised

All callbacks has order value from CallbackOrder and node value from CallbackNode

__init__(order: int, node: int = <CallbackNode.All: 0>, type: int = <CallbackType.Stage: 0>)

For order see CallbackOrder class

on_batch_end(state: _State)

on_batch_start(state: _State)

on_epoch_end(state: _State)

on_epoch_start(state: _State)

on_exception(state: _State)

on_loader_end(state: _State)

on_loader_start(state: _State)

on_stage_end(state: _State)

on_stage_start(state: _State)

catalyst.core.registry.Callback(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

catalyst.core.registry.Criterion(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

catalyst.core.registry.Optimizer(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

catalyst.core.registry.Scheduler(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

catalyst.core.registry.Module(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

catalyst.core.registry.Model(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

catalyst.core.registry.Sampler(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

catalyst.core.registry.Transform(factory: Union[Type, Callable[[...], Any]] = None, *factories: Union[Type, Callable[[...], Any]], name: str = None, **named_factories: Union[Type, Callable[[...], Any]]) → Union[Type, Callable[[...], Any]]

Adds factory to registry with it’s __name__ attribute or provided name. Signature is flexible.

Parameters

• factory – Factory instance

• factories – More instances

• name – Provided name for first instance. Use only when pass single instance.

• named_factories – Factory and their names as kwargs

Returns

First factory passed

Return type

(Factory)

Callbacks

class catalyst.core.callbacks.checkpoint.CheckpointCallback(save_n_best: int = 1, resume: str = None, resume_dir: str = None, metrics_filename: str = '_metrics.json')

Bases: catalyst.core.callbacks.checkpoint.BaseCheckpointCallback

Checkpoint callback to save/restore your model/criterion/optimizer/metrics.

__init__(save_n_best: int = 1, resume: str = None, resume_dir: str = None, metrics_filename: str = '_metrics.json')

Parameters

• save_n_best (int) – number of best checkpoint to keep

• resume (str) – path to checkpoint to load and initialize runner state

• metrics_filename (str) – filename to save metrics in checkpoint folder. Must ends on .json or .yml

get_checkpoint_suffix(checkpoint: dict) → str

on_epoch_end(state: catalyst.core.state._State)

on_stage_end(state: catalyst.core.state._State)

on_stage_start(state: catalyst.core.state._State)

process_checkpoint(logdir: Union[str, pathlib.Path], checkpoint: Dict, is_best: bool, main_metric: str = 'loss', minimize_metric: bool = True)

process_metrics(last_valid_metrics) → Dict

truncate_checkpoints(minimize_metric: bool) → None

class catalyst.core.callbacks.checkpoint.IterationCheckpointCallback(save_n_last: int = 1, period: int = 100, stage_restart: bool = True, metrics_filename: str = '_metrics_iter.json')

Bases: catalyst.core.callbacks.checkpoint.BaseCheckpointCallback

Iteration checkpoint callback to save your model/criterion/optimizer

__init__(save_n_last: int = 1, period: int = 100, stage_restart: bool = True, metrics_filename: str = '_metrics_iter.json')

Parameters

• save_n_last (int) – number of last checkpoint to keep

• period (int) – save the checkpoint every period

• stage_restart (bool) – restart counter every stage or not

• metrics_filename (str) – filename to save metrics in checkpoint folder. Must ends on .json or .yml

get_checkpoint_suffix(checkpoint: dict) → str

on_batch_end(state: catalyst.core.state._State)

on_stage_start(state: catalyst.core.state._State)

process_checkpoint(logdir: Union[str, pathlib.Path], checkpoint: Dict, batch_metrics: Dict[str, float])

process_metrics() → Dict

truncate_checkpoints(**kwargs) → None

class catalyst.core.callbacks.criterion.CriterionCallback(input_key: Union[str, List[str], Dict[str, str]] = 'targets', output_key: Union[str, List[str], Dict[str, str]] = 'logits', prefix: str = 'loss', criterion_key: str = None, multiplier: float = 1.0, **metric_kwargs)

Bases: catalyst.core.callbacks.metrics._MetricCallback

Callback for that measures loss with specified criterion.

__init__(input_key: Union[str, List[str], Dict[str, str]] = 'targets', output_key: Union[str, List[str], Dict[str, str]] = 'logits', prefix: str = 'loss', criterion_key: str = None, multiplier: float = 1.0, **metric_kwargs)

Parameters

• input_key (Union[str, List[str], Dict[str, str]]) – key/list/dict of keys that takes values from the input dictionary If ‘__all__’, the whole input will be passed to the criterion If None, empty dict will be passed to the criterion.

• output_key (Union[str, List[str], Dict[str, str]]) – key/list/dict of keys that takes values from the input dictionary If ‘__all__’, the whole output will be passed to the criterion If None, empty dict will be passed to the criterion.

• prefix (str) – prefix for metrics and output key for loss in state.batch_metrics dictionary

• criterion_key (str) – A key to take a criterion in case there are several of them and they are in a dictionary format.

• multiplier (float) – scale factor for the output loss.

property metric_fn

on_stage_start(state: catalyst.core.state._State)

Checks that the current stage has correct criterion

class catalyst.core.callbacks.formatters.MetricsFormatter(message_prefix)

Bases: abc.ABC, logging.Formatter

Abstract metrics formatter

__init__(message_prefix)

Parameters

message_prefix – logging format string that will be prepended to message

format(record: logging.LogRecord)

Format message string

class catalyst.core.callbacks.formatters.TxtMetricsFormatter

Bases: catalyst.core.callbacks.formatters.MetricsFormatter

Translate batch metrics in human-readable format.

This class is used by logging.Logger to make a string from record. For details refer to official docs for ‘logging’ module.

Note

This is inner class used by Logger callback, no need to use it directly!

__init__()

Initializes the TxtMetricsFormatter

class catalyst.core.callbacks.formatters.JsonMetricsFormatter

Bases: catalyst.core.callbacks.formatters.MetricsFormatter

Translate batch metrics in json format.

This class is used by logging.Logger to make a string from record. For details refer to official docs for ‘logging’ module.

Note

This is inner class used by Logger callback, no need to use it directly!

__init__()

Initializes the JsonMetricsFormatter

class catalyst.core.callbacks.logging.ConsoleLogger

Bases: catalyst.core.callback.Callback

Logger callback, translates state.*_metrics to console and text file

__init__()

Init ConsoleLogger

on_epoch_end(state)

Translate state.metric_manager to console and text file at the end of an epoch

on_stage_end(state)

Called at the end of each stage

on_stage_start(state: catalyst.core.state._State)

Prepare state.logdir for the current stage

class catalyst.core.callbacks.logging.TensorboardLogger(metric_names: List[str] = None, log_on_batch_end: bool = True, log_on_epoch_end: bool = True)

Bases: catalyst.core.callback.Callback

Logger callback, translates state.metric_manager to tensorboard

__init__(metric_names: List[str] = None, log_on_batch_end: bool = True, log_on_epoch_end: bool = True)

Parameters

• metric_names (List[str]) – list of metric names to log, if none - logs everything

• log_on_batch_end (bool) – logs per-batch metrics if set True

• log_on_epoch_end (bool) – logs per-epoch metrics if set True

on_batch_end(state: catalyst.core.state._State)

Translate batch metrics to tensorboard

on_epoch_end(state: catalyst.core.state._State)

Translate epoch metrics to tensorboard

on_loader_start(state)

Prepare tensorboard writers for the current stage

on_stage_end(state: catalyst.core.state._State)

Close opened tensorboard writers

class catalyst.core.callbacks.logging.VerboseLogger(always_show: List[str] = None, never_show: List[str] = None)

Bases: catalyst.core.callback.Callback

Logs the params into console

__init__(always_show: List[str] = None, never_show: List[str] = None)

Parameters

• always_show (List[str]) – list of metrics to always show if None default is ["_timer/_fps"] to remove always_show metrics set it to an empty list []

• never_show (List[str]) – list of metrics which will not be shown

on_batch_end(state: catalyst.core.state._State)

Update tqdm progress bar at the end of each batch

on_exception(state: catalyst.core.state._State)

Called if an Exception was raised

on_loader_end(state: catalyst.core.state._State)

Cleanup and close tqdm progress bar

on_loader_start(state: catalyst.core.state._State)

Init tqdm progress bar

class catalyst.core.callbacks.optimizer.OptimizerCallback(loss_key: str = 'loss', optimizer_key: str = None, accumulation_steps: int = 1, grad_clip_params: Dict = None, decouple_weight_decay: bool = True)

Bases: catalyst.core.callback.Callback

Optimizer callback, abstraction over optimizer step.

__init__(loss_key: str = 'loss', optimizer_key: str = None, accumulation_steps: int = 1, grad_clip_params: Dict = None, decouple_weight_decay: bool = True)

Parameters

• grad_clip_params (dict) – params for gradient clipping

• accumulation_steps (int) – number of steps before model.zero_grad()

• optimizer_key (str) – A key to take a optimizer in case there are several of them and they are in a dictionary format.

• loss_key (str) – key to get loss from state.loss

• decouple_weight_decay (bool) – If True - decouple weight decay regularization.

• save_model_grads (#) – If True - State.model_grads will

• contain gradients calculated (#) –

• on backward propagation on current (#) –

• batch (#) –

static grad_step(*, optimizer: torch.optim.optimizer.Optimizer, optimizer_wds: List[float] = 0, grad_clip_fn: Callable = None)

Makes a gradient step for a given optimizer

Parameters

• optimizer (Optimizer) – the optimizer

• optimizer_wds (List[float]) – list of weight decay parameters for each param group

• grad_clip_fn (Callable) – function for gradient clipping

on_batch_end(state: catalyst.core.state._State)

On batch end event

on_epoch_end(state: catalyst.core.state._State)

On epoch end event

on_epoch_start(state: catalyst.core.state._State)

On epoch start event

on_stage_start(state: catalyst.core.state._State)

Checks that the current stage has correct optimizer

class catalyst.core.callbacks.phase.PhaseManagerCallback(train_phases: OrderedDict[str, int] = None, valid_phases: OrderedDict[str, int] = None, valid_mode: str = None)

Bases: catalyst.core.callback.Callback

PhaseManagerCallback updates state.phase

VALIDATION_MODE_ALL = 'all'

VALIDATION_MODE_SAME = 'same'

allowed_valid_modes = ['same', 'all']

on_batch_end(state: catalyst.core.state._State)

on_batch_start(state: catalyst.core.state._State)

class catalyst.core.callbacks.scheduler.SchedulerCallback(scheduler_key: str = None, mode: str = None, reduced_metric: str = 'loss')

Bases: catalyst.core.callback.Callback

on_batch_end(state: catalyst.core.state._State)

on_epoch_end(state: catalyst.core.state._State)

on_loader_start(state: catalyst.core.state._State)

on_stage_start(state: catalyst.core.state._State)

step_batch(state: catalyst.core.state._State)

step_epoch(state: catalyst.core.state._State)

class catalyst.core.callbacks.scheduler.LRUpdater(optimizer_key: str = None)

Bases: catalyst.core.callback.Callback

Basic class that all Lr updaters inherit from

__init__(optimizer_key: str = None)

Parameters

optimizer_key – which optimizer key to use for learning rate scheduling

calc_lr()

calc_momentum()

on_batch_end(state: catalyst.core.state._State)

on_loader_start(state: catalyst.core.state._State)

on_stage_start(state: catalyst.core.state._State)

update_optimizer(state: catalyst.core.state._State)

class catalyst.core.callbacks.wrappers.PhaseWrapperCallback(base_callback: catalyst.core.callback.Callback, active_phases: List[str] = None, inactive_phases: List[str] = None)

Bases: catalyst.core.callback.Callback

CallbackWrapper which disables/enables handlers dependant on current phase and event type

May be useful i.e. to disable/enable optimizers & losses

LEVEL_BATCH = 'batch'

LEVEL_EPOCH = 'epoch'

LEVEL_LOADER = 'loader'

LEVEL_STAGE = 'stage'

TIME_END = 'end'

TIME_START = 'start'

is_active_on_phase(phase, level, time)

on_batch_end(state: catalyst.core.state._State)

on_batch_start(state: catalyst.core.state._State)

on_epoch_end(state: catalyst.core.state._State)

on_epoch_start(state: catalyst.core.state._State)

on_exception(state: catalyst.core.state._State)

on_loader_end(state: catalyst.core.state._State)

on_loader_start(state: catalyst.core.state._State)

on_stage_end(state: catalyst.core.state._State)

on_stage_start(state: catalyst.core.state._State)

class catalyst.core.callbacks.wrappers.PhaseBatchWrapperCallback(base_callback: catalyst.core.callback.Callback, active_phases: List[str] = None, inactive_phases: List[str] = None)

Bases: catalyst.core.callbacks.wrappers.PhaseWrapperCallback

is_active_on_phase(phase, level, time)