Skip to main content

Overview

The ClearML Python Package supports the automatic logging that documents experiments for you, and an extensive set of powerful features and functionality you can use to improve experimentation and other workflows.

Installation

For installation instructions, see Getting Started.

The ClearML Python Package collects the scripts' entire execution information, including:

  • Git repository (branch, commit ID, and uncommitted changes)
  • Working directory and entry point
  • Hyperparameters
  • Initial weights model, model snapshots (checkpoints), output model
  • Artifacts, metrics, logs, other reported data (from libraries and visualization toolkits), and debug samples.

In conjunction with the ClearML Hosted Service (or self-hosted ClearML Server) and ClearML Agent, the ClearML Python Package allows you and your teammates to collaborate programmatically and use the ClearML Web UI.

Classes and Modules​

Task​

The Task class is the code template for all Task features and functionality including:

  • Data collection and storage from scripts
  • Automatic bindings with frameworks, libraries, and visualization tools
  • A robust set of methods for Task execution (cloning, connecting parameter dictionaries, configurations, and models)
  • and more!

See an overview of Task's pythonic methods or the Task SDK reference page.

Model​

The model module contains three classes that provide support for working with models in ClearML:

  • Model - represents an existing model in ClearML that can be loaded and connected to a Task
  • InputModel - represents an existing model that you can load into ClearML
  • OutputModel - represents the experiment output model that is always connected to the Task

See an overview of the Model classes' pythonic methods, or the SDK reference pages for Model, InputModel, and OutputModel.

Logger​

The Logger class is the ClearML console log and metric statistics interface. The class contains methods for:

  • Explicit reporting
  • Setting an upload destination for debug sample storage
  • Controlling ClearML's logging of TensorBoard and Matplotlib outputs

See the Logger SDK reference page.

Hyperparameter Optimization​

ClearML's optimization module includes classes that support hyperparameter optimization (HPO):

See the HyperParameterOptimizer SDK reference page.

Pipeline​

ClearML's automation module includes classes that support creating pipelines:

  • PipelineController - A pythonic interface for defining and configuring a pipeline controller and its steps. The controller and steps can be functions in your python code, or ClearML tasks.
  • PipelineDecorator - A set of Python decorators which transform your functions into the pipeline controller and steps.

Dataset​

The Dataset class supports creating, modifying, and managing datasets, as well as retrieving them for use in code.

See ClearML Data or the Dataset SDK reference page.

StorageManager​

The StorageManager class provides support for downloading and uploading from storage, including local folders, S3, Google Cloud Storage, Azure Storage, and http(s).

See the StorageManager SDK reference page.

APIClient​

The APIClient class provides a Pythonic interface to access ClearML's backend REST API.

See an overview for APIClient usage.

ClearmlJob​

Use the ClearmlJob to create and manage jobs based on existing tasks. The class supports changing a job's parameters, configurations, and other execution details.

See reference page.

AutoScaler​

The AutoScaler class facilitates implementing resource budgeting. See class methods here. ClearML also provides a class specifically for AWS autoscaling. See code and example script.

TaskScheduler​

The TaskScheduler class supports methods for scheduling periodic execution (like cron jobs). See the code and example.

TriggerScheduler​

The TriggerScheduler class facilitates triggering task execution in the case that specific events occur in the system (such as model publication, dataset creation, task failure). See code and usage example.

Examples​

The clearml GitHub repository includes an examples folder with example scripts demonstrating how to use the various functionalities of the ClearML SDK.

These examples are preloaded in the ClearML Hosted Service, and can be viewed, cloned, and edited in the ClearML Web UI's ClearML Examples project. Each example is explained in the examples section.