API Reference

This is the class and function reference of ablator. Please refer to the tutorials for further details, as the class and function raw specifications may not be enough to give full guidelines on their uses.

ablator.analysis: Analysis module

Plot module

analysis.plot.main.PlotAnalysis(results[, ...])	Class for plotting experiment results.
analysis.plot.cat_plot.Categorical(*args, ...)
analysis.plot.cat_plot.ViolinPlot(*args, ...)
analysis.plot.num_plot.Numerical(metric, ...)
analysis.plot.num_plot.LinearPlot(metric, ...)
analysis.plot.utils.parse_name_remap([...])	Returns a dictionary mapping input attribute names to output attribute names, with optional remapping based on name_map.

Analysis Main classes

analysis.main.Analysis(results[, ...])

A class for analyzing experimental results.

Analysis Results classes

analysis.results.Results(config, experiment_dir)	Class for processing experiment results.
analysis.results.read_result(config_type, ...)	Read the results of an experiment and return them as a pandas DataFrame.

ablator.config: Config module

Base Config classes

config.main.ConfigBase(*args, **kwargs)	This class this the building block for all configuration objects within ablator.
config.main.configclass(cls)	Decorator for ConfigBase subclasses, adds the config_class attribute to the class.

Prototype Config classes

config.proto.ModelConfig(*args, **kwargs)	A base class for model configuration.
config.proto.RunConfig(*args, **kwargs)	The base configuration that defines the setting of an experiment (experiment main directory, number of checkpoints to maintain, hardware device to use, etc.).
config.proto.TrainConfig(*args, **kwargs)	Training configuration that defines the training setting, e.g., batch size, number of epochs, the optimizer to use, etc.

Config Type classes

config.types.Derived()

This type is for attributes that are derived during the experiment (after launching the experiment).

HPO Config classes

config.hpo.FieldType(value)	Type of search space.
config.hpo.SearchSpace(*args, **kwargs)	Search space configuration, required in parallel experiments, is used to define the search space for a hyperparameter.

Parallel Config classes

config.mp.Optim(value)	Type of optimization direction.
config.mp.ParallelConfig(*args, **kwargs)	Parallel training configuration, extending from RunConfig, defines the settings of a parallel experiment (number of trials to run for, number of concurrent trials, search space for hyperparameter search, etc.).
config.mp.SearchAlgo(value)	Type of search algorithm.

Config Utils functions

config.utils.dict_hash(*dictionaries[, hash_len])	Calculates the MD5 hash of one or more dictionaries.
config.utils.flatten_nested_dict(dict_[, ...])	Flattens a nested dictionary, expanding lists and tuples if specified.

ablator.main: Main module

HPO Sampler module

main.hpo.base.BaseSampler()
main.hpo.grid.GridSampler(search_space[, ...])
main.hpo.optuna.OptunaSampler(search_algo, ...)	OptunaSampler this class serves as an interface for Optuna based samplers.

Main Model module

main.model.main.ModelBase(model_class)	Base class that removes training boiler-plate code with extensible support for multiple use-cases.
main.model.wrapper.ModelWrapper(model_class)	A wrapper around model_class that removes training boiler-plate code.

Experiment State module

main.state.state.ExperimentState(...[, ...])
main.state.store.TrialState(value)	An enumeration of possible states for a trial with more pruned states.

Prototype Trainer classes

main.proto.ProtoTrainer(wrapper, run_config)

Manages resources for Prototyping.

Multi-process Trainer classes

main.mp.ParallelTrainer(wrapper, run_config)	A class for parallelizing training and hyperparameter optimization of models of different configurations with ray.
main.mp.train_main_remote(model, run_config, ...)	The trial job that will be executed remotely at a ray node.

ablator.modules: Extra modules

Metrics module

modules.metrics.main.Metrics(*args[, ...])	Stores and manages predictions and calculates metrics given some custom evaluation functions.
modules.metrics.stores.ArrayStore([...])	Base class for manipulations (storing, getting, resetting) of batches of values.
modules.metrics.stores.MovingAverage([...])	This class is used to store moving average metrics
modules.metrics.stores.PredictionStore([...])	A class for storing prediction scores.

Storage module

modules.storage.remote.RemoteConfig(*args, ...)	Configuration for a remote storage.
modules.storage.remote.run_cmd_wait(cmd[, ...])	Run a command and wait for it to finish.

Optimizer classes

modules.optimizer.OptimizerArgs(*args, **kwargs)	A base class for optimizer arguments, here we define learning rate lr.
modules.optimizer.OptimizerConfig(name, ...)	Configuration for an optimizer, including optimizer name and arguments (these arguments are specific to a certain type of optimizer like SGD, Adam, AdamW).
modules.optimizer.SGDConfig(*args, **kwargs)	Configuration for an SGD optimizer.
modules.optimizer.AdamWConfig(*args, **kwargs)	Configuration for an AdamW optimizer.
modules.optimizer.AdamConfig(*args, **kwargs)	Configuration for an Adam optimizer.
modules.optimizer.get_parameter_names(model, ...)	Recurse into the module and return parameter names of all submodules, excluding modules that are of any type defined in forbidden_layer_types.
modules.optimizer.get_optim_parameters(model)	Setup the optimizer.

Scheduler classes

modules.scheduler.SchedulerArgs(*args, **kwargs)	Abstract base class for defining arguments to initialize a learning rate scheduler.
modules.scheduler.SchedulerConfig(name, ...)	A class that defines a configuration for a learning rate scheduler.
modules.scheduler.StepLRConfig(*args, **kwargs)	Configuration class for StepLR scheduler.
modules.scheduler.OneCycleConfig(*args, **kwargs)	Configuration class for the OneCycleLR scheduler.
modules.scheduler.PlateuaConfig(*args, **kwargs)	Configuration class for ReduceLROnPlateau scheduler.

ablator.utils: Utilities

Base utilities

utils.base.apply_lambda_to_iter(iterable, fn)	Applies a given function fn to each element of an iterable data structure.
utils.base.debugger_is_active()	Check if the debugger is currently active.
utils.base.get_gpu_mem([mem_type])	Get the memory information of all available GPUs.
utils.base.get_latest_chkpts(checkpoint_dir)	Get a list of all checkpoint files in a directory, sorted from the latest to the earliest.
utils.base.get_lr(optimizer)	Get the learning rate from an optimizer.
utils.base.init_weights(module)	Initialize the weights of a module.
utils.base.is_oom_exception(err)	is_oom_exception checks whether the exception is caused by CUDA out of memory errors.
utils.base.iter_to_device(data_dict, device)	Moving torch.Tensor elements to the specified device.
utils.base.iter_to_numpy(iterable)	Convert elements of the input iterable to NumPy arrays if they are torch.Tensor objects.
utils.base.num_format(value[, width])	Format number to be no larger than width by converting to scientific notation when the value exceeds width either by informative decimal places or size.
utils.base.parse_device(device)	Parse a device string, an integer, or a list of device strings or integers.
utils.base.set_seed(seed)	Set the random seed.

File utilities

utils.file.clean_checkpoints(...)	Remove all but the n latest checkpoints from the given directory.
utils.file.default_val_parser(val)	Converts the input value to a JSON compatible format.
utils.file.dict_to_json(dict_)	Convert a dictionary into a JSON string.
utils.file.json_to_dict(json_)	Convert a JSON string into a dictionary.
utils.file.make_sub_dirs(parent, *dir_names)	Create subdirectories under the given parent directory.
utils.file.nested_set(dict_, keys, value)	Set a value in a nested dictionary.
utils.file.save_checkpoint(state[, filename])	Save a checkpoint of the given state.