cli

Functions

instantiate_class

Instantiates a class with the given args and init.

Classes

LightningArgumentParser	Extension of jsonargparse's ArgumentParser for pytorch-lightning.
LightningCLI	Implementation of a configurable command line tool for pytorch-lightning.
ReduceLROnPlateau
SaveConfigCallback	Saves a LightningCLI config to the log_dir when training starts.

Utilities for LightningCLI.

class pytorch_lightning.utilities.cli.LightningArgumentParser(*args, **kwargs)

Bases: jsonargparse.ArgumentParser

Extension of jsonargparse’s ArgumentParser for pytorch-lightning.

Initialize argument parser that supports configuration file input.

For full details of accepted arguments see ArgumentParser.__init__.

add_lightning_class_args(lightning_class, nested_key, subclass_mode=False, required=True)

Adds arguments from a lightning class to a nested key of the parser.

Parameters

• lightning_class (Union[Callable[…, Union[Trainer, LightningModule, LightningDataModule, Callback]], Type[Trainer], Type[LightningModule], Type[LightningDataModule], Type[Callback]]) – A callable or any subclass of {Trainer, LightningModule, LightningDataModule, Callback}.

• nested_key (str) – Name of the nested namespace to store arguments.

• subclass_mode (bool) – Whether allow any subclass of the given class.

• required (bool) – Whether the argument group is required.

Return type

List[str]

Returns

A list with the names of the class arguments added.

add_lr_scheduler_args(lr_scheduler_class, nested_key='lr_scheduler', link_to='AUTOMATIC')

Adds arguments from a learning rate scheduler class to a nested key of the parser.

Parameters

• lr_scheduler_class (Union[Type[_LRScheduler], Type[ReduceLROnPlateau], Tuple[Union[Type[_LRScheduler], Type[ReduceLROnPlateau]], …]]) – Any subclass of torch.optim.lr_scheduler.{_LRScheduler, ReduceLROnPlateau}.

• nested_key (str) – Name of the nested namespace to store arguments.

• link_to (str) – Dot notation of a parser key to set arguments or AUTOMATIC.

Return type

None

add_optimizer_args(optimizer_class, nested_key='optimizer', link_to='AUTOMATIC')

Adds arguments from an optimizer class to a nested key of the parser.

Parameters

• optimizer_class (Union[Type[Optimizer], Tuple[Type[Optimizer], …]]) – Any subclass of torch.optim.Optimizer.

• nested_key (str) – Name of the nested namespace to store arguments.

• link_to (str) – Dot notation of a parser key to set arguments or AUTOMATIC.

Return type

None

set_choices(nested_key, classes, is_list=False)

Adds support for shorthand notation for a particular nested key.

Parameters

• nested_key (str) – The key whose choices will be set.

• classes (Tuple[Type, …]) – A tuple of classes to choose from.

• is_list (bool) – Whether the argument is a List[object] type.

Return type

None

class pytorch_lightning.utilities.cli.LightningCLI(model_class=None, datamodule_class=None, save_config_callback=<class 'pytorch_lightning.utilities.cli.SaveConfigCallback'>, save_config_filename='config.yaml', save_config_overwrite=False, save_config_multifile=False, trainer_class=<class 'pytorch_lightning.trainer.trainer.Trainer'>, trainer_defaults=None, seed_everything_default=None, description='pytorch-lightning trainer command line tool', env_prefix='PL', env_parse=False, parser_kwargs=None, subclass_mode_model=False, subclass_mode_data=False, run=True, auto_registry=False)

Bases: object

Implementation of a configurable command line tool for pytorch-lightning.

Receives as input pytorch-lightning classes (or callables which return pytorch-lightning classes), which are called / instantiated using a parsed configuration file and / or command line args.

Parsing of configuration from environment variables can be enabled by setting env_parse=True. A full configuration yaml would be parsed from PL_CONFIG if set. Individual settings are so parsed from variables named for example PL_TRAINER__MAX_EPOCHS.

For more info, read the CLI docs.

Warning

LightningCLI is in beta and subject to change.

Parameters

• model_class (Union[Type[LightningModule], Callable[…, LightningModule], None]) – An optional LightningModule class to train on or a callable which returns a LightningModule instance when called. If None, you can pass a registered model with --model=MyModel.

• datamodule_class (Union[Type[LightningDataModule], Callable[…, LightningDataModule], None]) – An optional LightningDataModule class or a callable which returns a LightningDataModule instance when called. If None, you can pass a registered datamodule with --data=MyDataModule.

• save_config_callback (Optional[Type[SaveConfigCallback]]) – A callback class to save the training config.

• save_config_filename (str) – Filename for the config file.

• save_config_overwrite (bool) – Whether to overwrite an existing config file.

• save_config_multifile (bool) – When input is multiple config files, saved config preserves this structure.

• trainer_class (Union[Type[Trainer], Callable[…, Trainer]]) – An optional subclass of the Trainer class or a callable which returns a Trainer instance when called.

• trainer_defaults (Optional[Dict[str, Any]]) – Set to override Trainer defaults or add persistent callbacks. The callbacks added through this argument will not be configurable from a configuration file and will always be present for this particular CLI. Alternatively, configurable callbacks can be added as explained in the CLI docs.

• seed_everything_default (Optional[int]) – Default value for the seed_everything() seed argument.

• description (str) – Description of the tool shown when running --help.

• env_prefix (str) – Prefix for environment variables.

• env_parse (bool) – Whether environment variable parsing is enabled.

• parser_kwargs (Union[Dict[str, Any], Dict[str, Dict[str, Any]], None]) – Additional arguments to instantiate each LightningArgumentParser.

• subclass_mode_model (bool) – Whether model can be any subclass of the given class.

• subclass_mode_data (bool) –

  Whether datamodule can be any subclass of the given class.

• run (bool) – Whether subcommands should be added to run a Trainer method. If set to False, the trainer and model classes will be instantiated only.

• auto_registry (bool) – Whether to automatically fill up the registries with all defined subclasses.

add_arguments_to_parser(parser)

Implement to add extra arguments to the parser or link arguments.

Parameters

parser (LightningArgumentParser) – The parser object to which arguments can be added

Return type

None

add_core_arguments_to_parser(parser)

Adds arguments from the core classes to the parser.

Return type

None

add_default_arguments_to_parser(parser)

Adds default arguments to the parser.

Return type

None

before_instantiate_classes()

Implement to run some code before instantiating the classes.

Return type

None

static configure_optimizers(lightning_module, optimizer, lr_scheduler=None)

Override to customize the configure_optimizers() method.

Parameters

• lightning_module (LightningModule) – A reference to the model.

• optimizer (Optimizer) – The optimizer.

• lr_scheduler (Union[_LRScheduler, ReduceLROnPlateau, None]) – The learning rate scheduler (if used).

Return type

Any

init_parser(**kwargs)

Method that instantiates the argument parser.

Return type

LightningArgumentParser

instantiate_classes()

Instantiates the classes and sets their attributes.

Return type

None

instantiate_trainer(**kwargs)

Instantiates the trainer.

Parameters

kwargs (Any) – Any custom trainer arguments.

Return type

Trainer

static link_optimizers_and_lr_schedulers(parser)

Creates argument links for optimizers and learning rate schedulers that specified a link_to.

Return type

None

parse_arguments(parser)

Parses command line arguments and stores it in self.config.

Return type

None

setup_parser(add_subcommands, main_kwargs, subparser_kwargs)

Initialize and setup the parser, subcommands, and arguments.

Return type

None

static subcommands()

Defines the list of available subcommands and the arguments to skip.

Return type

Dict[str, Set[str]]

class pytorch_lightning.utilities.cli.ReduceLROnPlateau(optimizer, monitor, *args, **kwargs)

Bases: torch.optim.lr_scheduler.ReduceLROnPlateau

class pytorch_lightning.utilities.cli.SaveConfigCallback(parser, config, config_filename, overwrite=False, multifile=False)

Bases: pytorch_lightning.callbacks.base.Callback

Saves a LightningCLI config to the log_dir when training starts.

Parameters

• parser (LightningArgumentParser) – The parser object used to parse the configuration.

• config (Namespace) – The parsed configuration that will be saved.

• config_filename (str) – Filename for the config file.

• overwrite (bool) – Whether to overwrite an existing config file.

• multifile (bool) – When input is multiple config files, saved config preserves this structure.

Raises

RuntimeError – If the config file already exists in the directory to avoid overwriting a previous run

setup(trainer, pl_module, stage=None)

Called when fit, validate, test, predict, or tune begins.

Return type

None

pytorch_lightning.utilities.cli.instantiate_class(args, init)

Instantiates a class with the given args and init.

Parameters

• args (Union[Any, Tuple[Any, …]]) – Positional arguments required for instantiation.

• init (Dict[str, Any]) – Dict of the form {“class_path”:…,”init_args”:…}.

Return type

Any

Returns

The instantiated class object.