viberl.utils.experiment_manager

Experiment management utilities.

This module provides utilities for managing experiment directories, tensorboard logging, and model checkpoints.

Classes:

Name	Description
ExperimentManager	Manages experiment directories with automatic naming and organization.

Functions:

Name	Description
create_experiment	Convenience function to create a new experiment.

ExperimentManager

ExperimentManager(
    experiment_name: str, base_dir: str = 'experiments', timestamp_format: str = '%Y%m%d_%H%M%S'
)

Manages experiment directories with automatic naming and organization.

Creates experiment directories in the format: experiments/{experiment_name}_{timestamp}/ ├── tb_logs/ # TensorBoard logs ├── models/ # Saved model checkpoints └── training.log # Training log file

Initialize experiment manager.

Parameters:

Name	Type	Description	Default
experiment_name	str	Name of the experiment	required
base_dir	str	Base directory for experiments	'experiments'
timestamp_format	str	Format for timestamp in directory name	'%Y%m%d_%H%M%S'

Methods:

Name	Description
get_tb_logs_path	Get path to TensorBoard logs directory.
get_models_path	Get path to models directory.
get_training_log_path	Get path to training log file.
configure_file_logging	Configure loguru to log to training.log file.
log_command_line_args	Log command line arguments to training.log.
get_experiment_path	Get path to experiment directory.
get_exp_dir	Get path to experiment directory (alias for get_experiment_path).
save_model	Get full path for saving a model.
list_experiments	List all existing experiments.
get_latest_experiment	Get the latest experiment directory.
print_experiment_info	Print information about the current experiment.
create_from_existing	Create ExperimentManager from existing experiment directory.

Attributes:

Name	Type	Description
experiment_name
base_dir
timestamp_format
experiment_dir
exp_dir
tb_logs_dir
models_dir

Source code in viberl/utils/experiment_manager.py

def __init__(
    self,
    experiment_name: str,
    base_dir: str = 'experiments',
    timestamp_format: str = '%Y%m%d_%H%M%S',
):
    """
    Initialize experiment manager.

    Args:
        experiment_name: Name of the experiment
        base_dir: Base directory for experiments
        timestamp_format: Format for timestamp in directory name
    """
    self.experiment_name = experiment_name
    self.base_dir = Path(base_dir)
    self.timestamp_format = timestamp_format

    # Create experiment directory name with timestamp
    timestamp = datetime.now().strftime(timestamp_format)
    self.experiment_dir = self.base_dir / f'{experiment_name}_{timestamp}'

    # Core experiment directory
    self.exp_dir = self.experiment_dir

    # Standardized subdirectory paths
    self.tb_logs_dir = self.exp_dir / 'tb_logs'
    self.models_dir = self.exp_dir / 'models'

    # Create directories
    self._create_directories()

experiment_name instance-attribute

experiment_name = experiment_name

base_dir instance-attribute

base_dir = Path(base_dir)

timestamp_format instance-attribute

timestamp_format = timestamp_format

experiment_dir instance-attribute

experiment_dir = base_dir / f'{experiment_name}_{timestamp}'

exp_dir instance-attribute

exp_dir = experiment_dir

tb_logs_dir instance-attribute

tb_logs_dir = exp_dir / 'tb_logs'

models_dir instance-attribute

models_dir = exp_dir / 'models'

get_tb_logs_path

get_tb_logs_path() -> Path

Get path to TensorBoard logs directory.

Source code in viberl/utils/experiment_manager.py

def get_tb_logs_path(self) -> Path:
    """Get path to TensorBoard logs directory."""
    return self.tb_logs_dir

get_models_path

get_models_path() -> Path

Get path to models directory.

Source code in viberl/utils/experiment_manager.py

def get_models_path(self) -> Path:
    """Get path to models directory."""
    return self.models_dir

get_training_log_path

get_training_log_path() -> Path

Get path to training log file.

Source code in viberl/utils/experiment_manager.py

def get_training_log_path(self) -> Path:
    """Get path to training log file."""
    return self.experiment_dir / 'training.log'

configure_file_logging

configure_file_logging(log_level: str = 'INFO') -> None

Configure loguru to log to training.log file.

Parameters:

Name	Type	Description	Default
log_level	str	Logging level (DEBUG, INFO, WARNING, ERROR)	'INFO'

Source code in viberl/utils/experiment_manager.py

def configure_file_logging(self, log_level: str = 'INFO') -> None:
    """
    Configure loguru to log to training.log file.

    Args:
        log_level: Logging level (DEBUG, INFO, WARNING, ERROR)
    """
    log_file = self.get_training_log_path()

    # Remove any existing file handlers to avoid duplicates
    logger.remove()

    # Add console handler
    logger.add(
        lambda msg: print(msg, end=''),
        level=log_level,
        format='<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level:8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>',
    )

    # Add file handler
    logger.add(
        str(log_file),
        level=log_level,
        format='{time:YYYY-MM-DD HH:mm:ss} | {level:8} | {name}:{function}:{line} - {message}',
        rotation='10 MB',  # Rotate at 10MB
        retention='10 days',  # Keep logs for 10 days
    )

log_command_line_args

log_command_line_args(args: object) -> None

Log command line arguments to training.log.

Parameters:

Name	Type	Description	Default
args	object	Parsed argparse arguments object	required

Source code in viberl/utils/experiment_manager.py

def log_command_line_args(self, args: object) -> None:
    """
    Log command line arguments to training.log.

    Args:
        args: Parsed argparse arguments object
    """
    logger.info('=' * 80)
    logger.info('TRAINING SESSION STARTED')
    logger.info('=' * 80)

    # Log command line arguments
    logger.info('Command Line Arguments:')
    for arg_name, arg_value in vars(args).items():
        logger.info(f'  {arg_name}: {arg_value}')

    logger.info('=' * 80)
    logger.info(f'Experiment Directory: {self.experiment_dir}')
    logger.info('=' * 80)

get_experiment_path

get_experiment_path() -> Path

Get path to experiment directory.

Source code in viberl/utils/experiment_manager.py

def get_experiment_path(self) -> Path:
    """Get path to experiment directory."""
    return self.exp_dir

get_exp_dir

get_exp_dir() -> Path

Get path to experiment directory (alias for get_experiment_path).

Source code in viberl/utils/experiment_manager.py

def get_exp_dir(self) -> Path:
    """Get path to experiment directory (alias for get_experiment_path)."""
    return self.exp_dir

save_model

save_model(model_name: str) -> Path

Get full path for saving a model.

Parameters:

Name	Type	Description	Default
model_name	str	Name of the model file (without extension)	required

Returns:

Type	Description
Path	Full path for model file

Source code in viberl/utils/experiment_manager.py

def save_model(self, model_name: str) -> Path:
    """
    Get full path for saving a model.

    Args:
        model_name: Name of the model file (without extension)

    Returns:
        Full path for model file
    """
    return self.models_dir / f'{model_name}.pth'

list_experiments

list_experiments() -> list[Path]

List all existing experiments.

Source code in viberl/utils/experiment_manager.py

def list_experiments(self) -> list[Path]:
    """List all existing experiments."""
    if not self.base_dir.exists():
        return []

    experiments = [
        exp_dir
        for exp_dir in self.base_dir.iterdir()
        if exp_dir.is_dir() and self.experiment_name in exp_dir.name
    ]

    return sorted(experiments, reverse=True)

get_latest_experiment

get_latest_experiment() -> Path | None

Get the latest experiment directory.

Source code in viberl/utils/experiment_manager.py

def get_latest_experiment(self) -> Path | None:
    """Get the latest experiment directory."""
    experiments = self.list_experiments()
    return experiments[0] if experiments else None

print_experiment_info

print_experiment_info() -> None

Print information about the current experiment.

Source code in viberl/utils/experiment_manager.py

def print_experiment_info(self) -> None:
    """Print information about the current experiment."""
    logger.info(f'Experiment: {self.experiment_name}')
    logger.info(f'Directory: {self.exp_dir}')
    logger.info(f'TensorBoard logs: {self.tb_logs_dir}')
    logger.info(f'Models: {self.models_dir}')
    logger.info(f'Training log: {self.get_training_log_path()}')

create_from_existing staticmethod

create_from_existing(experiment_path: str | Path) -> ExperimentManager

Create ExperimentManager from existing experiment directory.

Parameters:

Name	Type	Description	Default
experiment_path	str | Path	Path to existing experiment directory	required

Returns:

Type	Description
ExperimentManager	ExperimentManager instance

Source code in viberl/utils/experiment_manager.py

@staticmethod
def create_from_existing(
    experiment_path: str | Path,
) -> 'ExperimentManager':
    """
    Create ExperimentManager from existing experiment directory.

    Args:
        experiment_path: Path to existing experiment directory

    Returns:
        ExperimentManager instance
    """
    experiment_path = Path(experiment_path)
    experiment_name = experiment_path.name.rsplit('_', 1)[0]

    # Create manager but don't create directories since they exist
    manager = ExperimentManager(experiment_name, str(experiment_path.parent))
    return manager

create_experiment

create_experiment(
    experiment_name: str, base_dir: str = 'experiments', print_info: bool = True
) -> ExperimentManager

Convenience function to create a new experiment.

Parameters:

Name	Type	Description	Default
experiment_name	str	Name of the experiment	required
base_dir	str	Base directory for experiments	'experiments'
print_info	bool	Whether to print experiment info	True

Returns:

Type	Description
ExperimentManager	ExperimentManager instance

Source code in viberl/utils/experiment_manager.py

def create_experiment(
    experiment_name: str,
    base_dir: str = 'experiments',
    print_info: bool = True,
) -> ExperimentManager:
    """
    Convenience function to create a new experiment.

    Args:
        experiment_name: Name of the experiment
        base_dir: Base directory for experiments
        print_info: Whether to print experiment info

    Returns:
        ExperimentManager instance
    """
    manager = ExperimentManager(experiment_name, base_dir)

    if print_info:
        manager.print_experiment_info()

    return manager