speechbrain.utils.run_opts module

Contains the defaults and parsing code for run-time controls

Authors

• Nouran Ali 2025

• Peter Plantinga 2025

Summary

Classes:

RunOptions

Holds configuration options and runtime controls for SpeechBrain experiments.

Reference

class speechbrain.utils.run_opts.RunOptions(test_only: bool = False, debug: bool = False, debug_batches: int = 2, debug_epochs: int = 2, debug_persistently: bool = False, device: str | None = None, data_parallel_backend: bool = False, data_parallel_count: int = -1, distributed_backend: ~typing.Literal['nccl', 'gloo', 'mpi'] = 'nccl', distributed_launch: bool = False, find_unused_parameters: bool = False, jit: bool = False, jit_module_keys: list[str] | None = None, compile: bool = False, compile_module_keys: list[str] | None = None, compile_mode: ~typing.Literal['default', 'reduce-overhead', 'max-autotune'] = 'default', compile_using_fullgraph: bool = False, compile_using_dynamic_shape_tracing: bool = False, precision: ~typing.Literal['fp32', 'fp16', 'bf16'] = 'fp32', eval_precision: ~typing.Literal['fp32', 'fp16', 'bf16'] = 'fp32', auto_mix_prec: bool = False, bfloat16_mix_prec: bool = False, max_grad_norm: float = 5.0, skip_nonfinite_grads: bool = False, nonfinite_patience: int = 3, noprogressbar: bool = False, ckpt_interval_minutes: int = 0, ckpt_interval_steps: int = 0, grad_accumulation_factor: int = 1, optimizer_step_limit: int | None = None, tqdm_colored_bar: bool = False, tqdm_barcolor: ~typing.Dict[str, str] = <factory>, remove_vector_weight_decay: bool = False, profile_training: bool = False, profile_warmup: int = 5, profile_steps: int = 5, log_config: str | None = None, param_file: str = '', overridden_args: set = <factory>)

Bases: object

Holds configuration options and runtime controls for SpeechBrain experiments.

This dataclass encapsulates all tunable parameters and flags that affect the behavior of a SpeechBrain experiment, including device selection, debugging, distributed training, mixed-precision settings, checkpointing, profiling, and more. It provides default values for each option and can be constructed directly or via command-line argument parsing.

test_only

Run in evaluation-only mode, skipping training.

Type:

bool

debug

Enable debugging mode with reduced dataset size.

Type:

bool

debug_batches

Number of batches to run in debug mode.

Type:

int

debug_epochs

Number of epochs to run in debug mode.

Type:

int

debug_persistently

Keep debug data persistent (not using /tmp).

Type:

bool

device

The device on which to run (e.g., “cpu”, “cuda:0”). Default of None may be handled with speechbrain.utils.distributed.infer_device()

Type:

str

data_parallel_backend

Enable data parallel training.

Type:

bool

data_parallel_count

Number of devices for data parallelism.

Type:

int

distributed_backend

Backend for distributed training.

Type:

Literal[“nccl”, “gloo”, “mpi”]

distributed_launch

Use distributed launch for training.

Type:

bool

find_unused_parameters

Detect unused parameters during distributed training.

Type:

bool

jit

Enable JIT compilation for modules.

Type:

bool

jit_module_keys

Module keys to compile with JIT.

Type:

Optional[list]

compile

Enable torch.compile for modules (if available).

Type:

bool

compile_module_keys

Module keys to compile with torch.compile.

Type:

Optional[list]

compile_mode

Compilation mode.

Type:

Literal[“default”, “reduce-overhead”, “max-autotune”]

compile_using_fullgraph

Use fullgraph compilation.

Type:

bool

compile_using_dynamic_shape_tracing

Use dynamic shape tracing in compilation.

Type:

bool

precision

Training precision.

Type:

Literal[“fp32”, “fp16”, “bf16”]

eval_precision

Inference precision.

Type:

Literal[“fp32”, “fp16”, “bf16”]

auto_mix_prec

Enable automatic mixed-precision training.

Type:

bool

bfloat16_mix_prec

Enable bfloat16 mixed-precision training.

Type:

bool

max_grad_norm

Maximum gradient norm for clipping.

Type:

float

skip_nonfinite_grads

Skip non-finite gradients.

Type:

bool

nonfinite_patience

Number of tolerated non-finite batches per epoch.

Type:

int

noprogressbar

Disable progress bars.

Type:

bool

ckpt_interval_minutes

Minutes between intra-epoch checkpoints.

Type:

int

ckpt_interval_steps

Steps between intra-epoch checkpoints.

Type:

int

grad_accumulation_factor

Batches to accumulate before optimizer step.

Type:

int

optimizer_step_limit

Maximum number of optimizer steps.

Type:

None or int

tqdm_colored_bar

Enable colored progress bars.

Type:

bool

tqdm_barcolor

Color mapping for progress bars.

Type:

dict of str

remove_vector_weight_decay

Separate parameter group for vectors without weight decay.

Type:

bool

profile_training

Enable profiling and tensorboard logging.

Type:

bool

profile_warmup

Profiler warmup steps.

Type:

int

profile_steps

Profiler logging steps.

Type:

int

log_config

Path to logging configuration file.

Type:

None or str

param_file

Path to experiment parameter YAML file.

Type:

str

overridden_args

The args that have been manually specified on the command line.

Type:

dict

test_only: bool = False

debug: bool = False

debug_batches: int = 2

debug_epochs: int = 2

debug_persistently: bool = False

device: str | None = None

data_parallel_backend: bool = False

data_parallel_count: int = -1

distributed_backend: Literal['nccl', 'gloo', 'mpi'] = 'nccl'

distributed_launch: bool = False

find_unused_parameters: bool = False

jit: bool = False

jit_module_keys: list[str] | None = None

compile: bool = False

compile_module_keys: list[str] | None = None

compile_mode: Literal['default', 'reduce-overhead', 'max-autotune'] = 'default'

compile_using_fullgraph: bool = False

compile_using_dynamic_shape_tracing: bool = False

precision: Literal['fp32', 'fp16', 'bf16'] = 'fp32'

eval_precision: Literal['fp32', 'fp16', 'bf16'] = 'fp32'

auto_mix_prec: bool = False

bfloat16_mix_prec: bool = False

max_grad_norm: float = 5.0

skip_nonfinite_grads: bool = False

nonfinite_patience: int = 3

noprogressbar: bool = False

ckpt_interval_minutes: int = 0

ckpt_interval_steps: int = 0

grad_accumulation_factor: int = 1

optimizer_step_limit: int | None = None

tqdm_colored_bar: bool = False

tqdm_barcolor: Dict[str, str]

remove_vector_weight_decay: bool = False

profile_training: bool = False

profile_warmup: int = 5

profile_steps: int = 5

log_config: str | None = None

param_file: str = ''

overridden_args: set

as_dict() → Dict

Converts the instance into a dictionary.

Returns:

Dict: A dictionary representation of the instance.

__getitem__(key)

Make items accessible via dict notation, to maintain backwards compat.

get(key, default=None)

Dict-like get method, to maintain backwards compat.

__contains__(key)

Dict-like ‘in’ check, to maintain backwards compat.

keys()

Dict-like keys method, to maintain backwards compat.

__iter__()

Dict-like iteration over keys, to maintain backwards compat.

items()

Dict-like items method, to maintain backwards compat.

values()

Dict-like values method, to maintain backwards compat.

classmethod from_dictionary(args_dict)

Set experimental arguments from a dictionary.

classmethod from_command_line_args(arg_list=None)

Parse command-line arguments to the experiment.

Parameters:

arg_list (list, None) – A list of arguments to parse. If not given, this is read from sys.argv[1:]

Returns:

• param_file (str) – The location of the parameters file.

• run_opts (dict) – Run options, such as distributed, device, etc.

• overrides (dict) – The overrides to pass to load_hyperpyyaml.

Example

>>> argv = ["hyperparams.yaml", "--device", "cuda:1", "--seed", "10"]
>>> filename, run_opts, overrides = RunOptions.from_command_line_args(
...     argv
... )
>>> filename
'hyperparams.yaml'
>>> run_opts["device"]
'cuda:1'
>>> overrides
'seed: 10'