hydronaut package

Subpackages

• hydronaut.hydra package
  • Submodules
  • hydronaut.hydra.config module
    • ExperimentConfig
      • ExperimentConfig.__init__()
      • ExperimentConfig.defaults
      • ExperimentConfig.description
      • ExperimentConfig.environment
      • ExperimentConfig.exp_class
      • ExperimentConfig.mlflow
      • ExperimentConfig.name
      • ExperimentConfig.params
      • ExperimentConfig.python
    • HydronautConfig
      • HydronautConfig.__init__()
      • HydronautConfig.defaults
    • MLflowConfig
      • MLflowConfig.__init__()
      • MLflowConfig.start_run
    • MLflowRunConfig
      • MLflowRunConfig.__init__()
      • MLflowRunConfig.description
      • MLflowRunConfig.nested
      • MLflowRunConfig.run_id
      • MLflowRunConfig.run_name
      • MLflowRunConfig.tags
    • PythonConfig
      • PythonConfig.__init__()
      • PythonConfig.paths
    • configure_environment()
    • configure_hydra()
    • get_config_path()
    • save_config()
  • hydronaut.hydra.info module
    • get_sweep_number()
  • hydronaut.hydra.omegaconf module
    • get()
    • get_container()
    • set_globals()
  • hydronaut.hydra.resolvers module
    • get_cwd()
    • get_n_cpu()
    • get_n_gpu_pytorch()
    • register()
    • reregister()
  • Module contents

Submodules

hydronaut.decorator module

Decorators for running code with Hydronaut.

hydronaut.decorator.with_hydronaut(config_path: str | Path = None) → Callable[[Callable[[omegaconf.DictConfig], int | float | Tuple[int | float, ...]] | Callable[[omegaconf.DictConfig], Callable[[], int | float | Tuple[int | float, ...]]]], Callable[[], int | float | Tuple[int | float, ...]]]

A decorator to run custom user code with Hydronaut. The user code must be either a class with the following methods:

__init__(self, config):

An initialization method that accepts the Hydra configuration object as its sole argument.

__call__(self):

A call method that returns the experiment’s objective values.

setup(self):

An optional method that will be invoked before __call__ when the experiment is run. This can be used to e.g. prepare data.

or a function that accept the Hydra configuration object as its sole argument and which returns the experiment’s objective values.

Parameters:

config_path – Passed through to hydronaut.run.Runner.

Returns:

A callable object that runs the user code within the Hydronaut framework.

hydronaut.experiment module

Experiment base class.

class hydronaut.experiment.Experiment(config: omegaconf.DictConfig)

Bases: object

Base class for experiments.

TODO * Add methods for logging parameters, artefacts, etc.

__init__(config: omegaconf.DictConfig) → None

Parameters:

config – The Hydra configuration object.

log_artifact(local_path: str | Path, artifact_path: str | Path | None = None) → None

Wrapper around mlflow.log_artifact: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_artifact

Parameters:

• local_path – A path to an existing artifact. The artitfact must already be saved to this path.

• artifact_path – An optional path to a directory under artifact_uri in which to log the artifact in MLflow.

log_artifacts(local_dir: str | Path, artifact_path: str | Path | None = None) → None

Wrapper around mlflow.log_artifacts: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_artifacts

Parameters:

• local_dir – A path to a directory with artifacts.

• artifact_path – An optional path to a directory under artifact_uri in which to log the artifact in MLflow.

log_dict(dictionary: Any, artifact_file: str | Path) → None

Wrapper around mlflow.log_dict: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_dict

Parameters:

• dictionary – A dict object to log.

• artifact_file – The run-relative subpath to which to save the data as a JSON or YAML file. The file type will be determined from the extension (“.yaml” or “.json”).

log_figure(figure: Any, artifact_file: str | Path) → None

Wrapper around mlflow.log_figure: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_figure

Parameters:

• figure – A figure to log. Check the documentation of mlflow.log_figure for supported figure types (e.g. Matplotlib and Plotly.py figures).

• artifact_file – The run-relative subpath to which to save the figure.

log_image(image: Any, artifact_file: str | Path) → None

Wrapper around mlflow.log_image: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_image

Parameters:

• image – An image to log. Check the documentation of mlflow.log_image for supported image types (e.g. numpy.ndarray, Pillow images).

• artifact_file – The run-relative subpath to which to save the image.

log_metric(key: str, value: int | float, step: int | None = None) → None

Wrapper around mlflow.log_metric: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_metric

Parameters:

• key – The metric name.

• value – The metric value.

• step – The metric step. Defaults to zero if unspecified.

log_metrics(metrics: dict[str, int | float], step: int | None = None) → None

Wrapper around mlflow.log_metrics: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_metrics

Parameters:

• metrics – A dict mapping metric names to their values.

• step – The metric step. Defaults to zero if unspecified.

log_param(key: str, value: Any) → None

Wrapper around mlflow.log_param: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_param

Parameters:

• key – The parameter name.

• value – The parameter value.

log_params(params: dict[str, Any]) → None

Wrapper around mlflow.log_params: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_params

Parameters:

params – A dict mapping parameter names to their values.

log_text(text: str, artifact_file: str | Path) → None

Wrapper around mlflow.log_text: https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.log_text

Parameters:

• text – The text to log.

• artifact_file – The run-relative subpath to which to save the text.

setup() → None

Set up the experiment before running it (e.g. download data, generate files, configure databases).

hydronaut.file module

File functions.

hydronaut.file.backup_copy(path: Path) → None

Attempt to backup a copy to a timestamped path in the same directory.

Parameters:

path – The path to back up. If it does not exist then nothing will be done.

hydronaut.file.safe_open(path: Path, *args: Any, backup: bool = False, **kwargs: Any) → TextIOBase

Context manager for safely opening a path by first creating any missing parent directories and then moving any existing file to a backup path.

Parameters:

• path – The path to open.

• backup – If True, backup the file at the path if it exists.

• *args – Positional arguments passed through to pathlib.Path.open.

• **kwargs – Keyword arguments passed through to pathlib.Path.open.

Returns:

The open file handle.

hydronaut.init module

Initialize a directory with default files for Hydronaut.

class hydronaut.init.Initializer

Bases: object

Initialize a directory with default files.

__init__() → None

create_config() → None

Create the configuration file.

create_experiment() → None

Create a placeholder experiment subclass.

parse_args(args: list[str] = None) → None

Parse the command-line arguments with argparse.

Parameters:

args – The list of arguments to parse. If None, the arguments are taken from the current system invocation.

Returns:

The parsed arguments.

run(args: list[str] = None) → None

Process command-line arguments and generate the requested files.

Parameters:

args – Passed through to parse_args().

hydronaut.init.main(args: list[str] = None) → None

Initialize a directory with default files.

hydronaut.log module

Logging helper functions.

hydronaut.log.configure_logging(level: int = 20) → None

Configure logging.

Parameters:

level – The logging level.

hydronaut.mlflow module

MLflow utility functions.

class hydronaut.mlflow.MLflowRunner(config: omegaconf.DictConfig, base_dir: str | Path = None)

Bases: object

Context manager to set up an MLflow run from an Omegaconf configuration object. When used as a context manager, it will configure the tracking URI, experiment, artifact location and run parameters from the configurat object. The context will return the MLflow active run.

__init__(config: omegaconf.DictConfig, base_dir: str | Path = None) → None

Parameters:

config – The Omegaconf configuration object.

get_metric(name)

Return the value of a metric logged during the current run.

get_param(name)

Return the value of a parameter logged during the current run.

log_parameters() → None

Log all parameters with MLflow.

hydronaut.paths module

Path management.

class hydronaut.paths.PathManager(base_dir: str | Path = None, config_path: str | Path = None)

Bases: object

Path manager. This provides methods to retrieve common paths.

DEFAULT_CONFIG_SUBPATH = 'conf/config.yaml'

HYDRONAUT_CONFIG_ENV_VAR = 'HYDRONAUT_CONFIG'

__init__(base_dir: str | Path = None, config_path: str | Path = None) → None

Parameters:

base_dir – The directory relative to which to interpret paths. If None, the current working directory is used.

add_python_paths(paths: list[str | Path]) → None

Add Paths to the Python system paths list. The resulting list will be the equivalent of concatenating the input paths with the current system paths.

Parameters:

paths – The paths to add. If relative, they are interpreted relative to the path given by relative_to.

property config_dir: Path

The resolved path to the current configuration directory as a pathlib.Path object.

property config_path: Path

The resolved path to the main configuration file as a pathlib.Path object. If the path was not specified during initialization and the environment variable is not set, it returns the default path.

get_config_path(subpath: str | Path = None) → Path

Get the path to a configuration file.

subpath:

The subpath relative to the configuration directory. If None, defaults to config.yaml.

Returns:

The resolved path to the configuration file as a pathlib.Path object.

get_src_path(subpath: str | Path) → Path

Get the path to a Python source file in the default source directory.

subpath:

The subpath relative to the source directory.

Returns:

The resolved path to the source file as a pathlib.Path object.

hydronaut.run module

Run an experiment.

class hydronaut.run.Runner(config_path: str | Path = None)

Bases: object

Experiment runner.

__init__(config_path: str | Path = None) → None

Parameters:

config_path – The path to the configuration file. It is passed through to hydronaut.paths.get_config_path to get the main configuration file.

get_experiment_object() → Experiment

Get the experiment class specified by the configuration object.

Returns:

The experiment instance.

Raises:

• ImportError – The module could not be found.

• AttributeError – The module does not contain the expected class name.

log_objective_value(value: Any) → Real | tuple[Real]

Log the objective value. It will be passed through ensure_numeric(). If the return value is a tuple, each value will be logged as a separate objective value. :param value: The objective value(s).

hydronaut.run.main(*args: Any, **kwargs: Any) → int | float | Tuple[int | float, ...]

Main function to run an experiment with the Hydra configuration.

Parameters:

• *args – Positional arguments passed through to the hydra.main function.

• **kwargs – Keyword arguments passed through to the hydra.main function.

Returns:

The value returned by calling the runner.

hydronaut.run.script_main() → None

Hydra makes some assumptions about configuration paths based on how the main function is called. This is a workaround for creating a script via pyproject.toml. It will simply invoke main() with any passed command-line arguments.

hydronaut.types module

Type definitions and functions.

hydronaut.types.ensure_numeric(value: Any) → Generator[Real]

Convert values to numeric values. If the value is iterable, then the function will be recursively applied to its elements.

Parameters:

value – The value to check.

Returns:

A generator over numeric values (instances of numbers.Real). Values that could not be converted will be returned as NaN values.

Module contents

File stub.