clearml-docs/docs/clearml_sdk/clearml_sdk.md

title
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.

:::tip 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:

• HyperParameterOptimizer - Hyperparameter search controller class
• Optimization search strategy classes including Optuna, HpBandSter, GridSearch, RandomSearch, and a base SearchStrategy that can be customized

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 existing 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 here.

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 (e.g. 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 pre-loaded in the ClearML Hosted Service, and can be viewed, cloned, and edited in the ClearML Web UI's ClearML Examples project. The examples are each explained in the examples section.