swanlab.init

init(
    project: str = None,
    workspace: str = None,
    experiment_name: str = None,
    description: str = None,
    job_type: str = None,
    group: str = None,
    tags: List[str] = None,
    config: Union[dict, str] = None,
    logdir: str = None,
    mode: MODES = None,
    load: str = None,
    public: bool = None,
    callbacks: List[SwanKitCallback] = None,
    settings: Settings = None,
    color: str = None,
    id: str = None,
    resume: Union[Literal['must', 'allow', 'never'], bool] = None,
    reinit: bool = None,
    parallel: str = None,
    **kwargs,
)

Parameter	Description
project	(str) The name of the project. If not specified, the name of the current working directory will be used.
workspace	(str) The workspace. By default, experiments are synchronized to your personal space. If you want to upload to an organization, specify the organization's username.
experiment_name	(str) The name of the experiment. If not specified, it will default to a format like "swan-1" (animal name + sequence number).
job_type	(str) The type of job. If not specified, it will default to empty string.
group	(str) The group of the experiment. If not specified, it will default to None.
tags	(list) Tags for the experiment. Can pass a list of strings, and the tags will be displayed in the tag bar at the top of the experiment.
description	(str) A description of the experiment. If not specified, it defaults to None.
config	(dict, str) Configuration for the experiment. You can record hyperparameters and other information here. Supports passing a configuration file path (yaml or json).
logdir	(str) The path to store offline dashboard log files. Defaults to swanlog.
mode	(str) Sets the mode for creating SwanLab experiments. Options are "cloud", "local", "offline", or "disabled". Default is "cloud". cloud: Uploads the experiment to the cloud (public or private deployment). offline: Only records experiment data locally. local: Does not upload to the cloud but records experiment information locally. disabled: Neither uploads nor records.
load	(str) The path to a configuration file to load. Supports yaml and json files.
public	(bool) Sets the visibility of the SwanLab project created directly via code. Default is False (private).
callbacks	(list) Sets experiment callback functions. Supports subclasses of swanlab.toolkit.callback.SwanKitCallback.
name	(str) Same effect as experiment_name. Lower priority than experiment_name.
notes	(str) Same effect as description. Lower priority than description.
tags	(list) Tags for the experiment.
settings	(dict) Settings for the experiment. Supports passing a swanlab.Settings object.
id	(str) The ID of the last experiment. Used to resume the last experiment. Supports 1–64 custom characters; characters / \ # ? % : are not allowed.
color	(str) The color for the experiment, used to distinguish different experiments in the dashboard. Supports three formats: preset color names (e.g., "green", "blue"), RGB strings (e.g., "rgb(82,141,89)"), or hex color codes (e.g., "#528d59" or "528d59"). Defaults to None (random color). Invalid formats will trigger a warning and fall back to a random color.
resume	(str) Resume mode. Can be "must", "allow", "never", or True/False. Default is None. must: You must pass the id parameter, and the experiment must exist. allow: If an experiment exists, it will be resumed. Otherwise, a new experiment will be created. never: The id parameter cannot be passed, and a new experiment will be created. (This is equivalent to not enabling resume.)
reinit	(bool) Whether to reinitialize the experiment. If True, the last experiment will be finished every time swanlab.init() is called; default is None.
parallel	(str) Parallel mode. Options are "none" or "shared". Defaults to "none". "shared": Shared parallel mode, allowing multiple distributed processes to upload metrics to the same experiment simultaneously. Automatically forces mode='cloud' and resume='allow', and auto-generates an 8-character random id if none is provided.

Introduction

• In machine learning workflows, you can add swandb.init() at the beginning of training and testing scripts. SwanLab will track every step of the machine learning process.

• swanlab.init() spawns a new background process to log data to the experiment. By default, it also synchronizes the data to swanlab.cn, allowing you to view real-time visualizations online.

• Before using swanlab.log() to record data, you must call swanlab.init():

import swanlab

swanlab.init()
swanlab.log({"loss": 0.1846})

• Calling swanlab.init() returns an object of type SwanLabRun, which can also perform log operations:

import swanlab

run = swanlab.init()
run.log({"loss": 0.1846})

• At the end of the script, swanlab.finish will be automatically called to conclude the SwanLab experiment. However, if swanlab.init() is called from a subprocess (e.g., in a Jupyter notebook), you must explicitly call swanlab.finish at the end of the subprocess.

import swanlab

swanlab.init()
swanlab.finish()

Additional Usage

Setting Project, Experiment Name, and Description

swanlab.init(
    project="cats-detection",
    experiment_name="YoloX-baseline",
    description="Baseline experiment for the YoloX detection model, primarily for subsequent comparisons.",
)

Setting Tags

swanlab.init(
    tags=["yolo", "detection", "baseline"]
)

Setting Group

swanlab.init(
    group="good_try",
)

Setting the Log File Save Location

The following code demonstrates how to save log files to a custom directory:

swanlab.init(
    logdir="path/to/my_custom_dir",
)

Setting Experiment Color

# Using a preset color name
swanlab.init(color="green")

# Using a hex color code
swanlab.init(color="#528d59")

# Using an RGB string
swanlab.init(color="rgb(82,141,89)")

Adding Experiment Metadata to the Configuration

swanlab.init(
    config={
        "learning-rate": 1e-4,
        "model": "CNN",
    }
)

Uploading to an Organization

swanlab.init(
    workspace="[organization's username]"
)

Plugins

For more information about plugins, refer to the Plugins documentation.

from swanlab.plugin.notification import EmailCallback

email_callback = EmailCallback(...)

swanlab.init(
    callbacks=[email_callback]
)

Parallel Mode

parallel="shared" is designed for multi-process distributed training, where multiple processes upload metrics to the same experiment simultaneously:

# Multiple distributed processes use the same id, and metrics are aggregated under one experiment
swanlab.init(
    parallel="shared",
    id="my-distributed-run",  # All processes use the same id
)

If no id is provided, SwanLab auto-generates an 8-character random ID:

import os

# Share the same id across all processes via an environment variable
RUN_ID = os.environ.get("RUN_ID", swanlab.util.generate_id())
swanlab.init(
    parallel="shared",
    id=RUN_ID,
)

"Resume Training" refers to the ability to resume training from a previous state. If you previously had an experiment with the status of completed or interrupted, and you need to add more experimental data, you can use the resume and id parameters to restore this experiment.

swanlab.init(
    resume=True,
    id="14pk4qbyav4toobziszli",  # supports 1-64 custom characters
)

The experiment ID can be found in the experiment's "Environment" tab or in the URL. It must be a 21-character string.

Use Cases for resume

1. The previous training process was interrupted. You want to continue training based on a checkpoint and have the experiment chart continue from the previous swanlab experiment, rather than creating a new one.
2. Training and evaluation are split into two separate processes, but you want both the evaluation and training records to appear in the same swanlab experiment.
3. Some configuration parameters were incorrectly filled out, and you want to update them.

⚠️ Notes

1. Experiments generated by cloning a project cannot be resumed.

Breakpoint continuation supports three modes:

1. allow: If an experiment corresponding to the provided id exists under the project, it will be resumed. Otherwise, a new experiment will be created.
2. must: If an experiment corresponding to the provided id exists under the project, it will be resumed. Otherwise, an error will be thrown.
3. never: The id parameter cannot be passed, and a new experiment will be created instead. (This is equivalent to not enabling resume.)

INFO

Setting resume=True has the same effect as resume="allow".
Setting resume=False has the same effect as resume="never".

Test code:

import swanlab

run = swanlab.init()
swanlab.log({"loss": 2, "acc": 0.4})
run.finish()

run = swanlab.init(resume=True, id=run.id)
swanlab.log({"loss": 0.2, "acc": 0.9})

Deprecated Parameters

• cloud: Replaced by the mode parameter in v0.3.4. The parameter is still available and will override the mode setting.