Start experiment¶

To start logging data to Comet, you first need to retrieve an Experiment object. The simplest way to do this is by using the comet_ml.start method. Here’s a basic example:

import comet_ml

# Log in to Comet (if necessary)
comet_ml.login()

experiment = comet_ml.start()

# Log your data and benefit from automatically logged information
experiment.log_metric("loss", 0.42)

This will returns an Experiment object that you can use to log any data that you want. For more details on logging, see our Logging Data Guide.

Configuring the Experiment¶

You can configure where the data is logged and how it is saved by adjusting parameters as described in the comet_ml.start and comet_ml.ExperimentConfig reference documentation. Some of the most commonly used parameters include:

• Workspace: Specifies the workspace for the experiment. If not set, it defaults to the user's workspace.
• Project Name: Defines the project for the experiment. Defaults to "Uncategorized" if not specified and automatically creates the project if it doesn't already exist.
• Experiment Key: Allows logging data to an existing experiment by providing its key. Learn more about resuming experiments.
• Online: Controls whether the experiment logs data online or offline (offline requires manual upload). Learn more about offline experiments.
• Experiment Config: Enables further customization of logging behavior through additional options passed to comet_ml.start. See the comet_ml.start and comet_ml.ExperimentConfig documentation for more details.

This should enhance readability while maintaining technical accuracy. Does this meet your expectations?

Here is how you can for example log data to an experiment in a particular project name and set the Experiment name and tags:

import comet_ml

experiment_config = comet_ml.ExperimentConfig(
    name="MyExperimentName", tags=["quickstart"]
)

experiment = comet_ml.start(
    project_name="comet-example-start-logging", experiment_config=experiment_config
)

Resuming an Existing Experiment¶

To continue logging data to an existing Experiment, retrieve its Experiment Key from the Comet UI or your logs, and pass it to the comet_ml.start function:

import comet_ml

# Log in to Comet (if necessary)
comet_ml.login()

experiment = comet_ml.start(experiment_key=PREVIOUS_EXPERIMENT_KEY)

# Log your data and benefit from automatically logged information
experiment.log_metric("loss", 0.42)

Any new data will be appended to the existing Experiment.

Running Experiments Offline¶

To log data without an Internet connection, create an offline Experiment by setting online=False in the comet_ml.start function:

import comet_ml

# Log in to Comet (if necessary)
comet_ml.login()

experiment = comet_ml.start(online=False)

# Log your data and benefit from automatically logged information
experiment.log_metric("loss", 0.42)

Your data will be saved locally and must be manually uploaded later. After your run completes, instructions will appear on how to upload the data to Comet using the comet upload CLI::

COMET INFO: To upload this offline experiment, run:
    comet upload /content/.cometml-runs/54338792a0324a39bc4ce26ae148e97e.zip

Advanced Use Cases¶

The comet_ml.start function supports various advanced use cases, as described below.

Accessing the Currently Running Experiment¶

In some cases, you might already have an active Experiment object, and passing it around (e.g., in a callback) can be cumbersome. To simplify this, you can use comet_ml.start(). However, if you want to ensure that no new Experiment is created when none is running, use comet_ml.get_running_experiment() to access the currently active Experiment:

experiment = comet_ml.get_running_experiment()

experiment.log_metric("epoch/f1_score", 0.96)

Forcing the creation of a new Experiment¶

By default, if you call comet_ml.start multiple times, it will attempt to reuse an existing running Experiment if it's compatible with the specified parameters (see below for more details about compatibility check). If you need to create a new Experiment with every call (e.g., in a hyperparameter optimization loop), use:

experiment = comet_ml.start(mode="create")

For more details on handling exceptions and other advanced scenarios, please refer to the reference documentation.

Creating a New Experiment with a Fixed Experiment Key¶

By default, each new Experiment is assigned a unique, random Experiment Key. However, if you need to use a specific Experiment Key (e.g., to match an ID from your system), you can do so:

experiment = comet_ml.start(experiment_key=NEW_EXPERIMENT_KEY)

For more details on handling exceptions and other advanced scenarios, please refer to the reference documentation.

Handling resuming with non-existent Experiment key¶

When you attempt to continue logging data to an Experiment with a specific key using comet_ml.start, a new Experiment will be created if the key doesn’t exist. If you want to ensure that data is logged only to an existing Experiment and raise an exception if it doesn't exist, use:

experiment = comet_ml.start(experiment_key=PREVIOUS_EXPERIMENT_KEY, mode="get")

For more details on handling exceptions and other advanced scenarios, please refer to the reference documentation.

Compatibility with an Existing Running Experiment¶

Experiment initialization can occur in different parts of your code:

• Main training script
• Internal libraries or other scripts
• External libraries you are using

To ensure all data flows to a single Comet Experiment, comet_ml.start checks if there’s a running Experiment in the current Python process. If so, and if the mode is get_or_create (default) or get, it checks if the following parameters match the running Experiment:

• api_key
• disabled
• distributed_node_identifier
• experiment_key
• offline_directory (in offline mode)
• online
• project
• workspace

If a match is found, the same Experiment object is returned, and all data is logged to a single Comet Experiment. If there’s a mismatch, the behavior depends on the mode parameter:

• mode="get_or_create": Ends the currently running Experiment and behaves as if no Experiment was running, attempting to continue or create a new Experiment.
• mode="get": Ends the currently running Experiment and attempts to continue logging to the Comet Experiment identified by experiment_key.

Migrating from Experiment Classes¶

If you’ve been using our Experiment classes, here's how to migrate to the comet_ml.start() API. The new API simplifies experiment creation, with most functionalities remaining the same, but some minor adjustments are required.

Basic Migration Steps¶

Replace your current Experiment class instantiations with equivalent comet_ml.start() calls:

Additional Configuration¶

If you are passing additional configurations (apart from API Key, Workspace, Project Name), these need to be passed using the comet_ml.ExperimentConfig object. Here’s an example:

import comet_ml

experiment_config = comet_ml.ExperimentConfig(
    auto_histogram_weight_logging=True,
    auto_histogram_gradient_logging=True,
    auto_histogram_activation_logging=True,
)

experiment = comet_ml.start(experiment_config=experiment_config)

Behavior Changes When Multiple Experiments Are Created¶

When using comet_ml.start(), there are some differences in behavior when an experiment is already running:

• Reusing Existing Experiments: By default, comet_ml.start() will attempt to reuse an already running experiment if it matches the provided configuration. This makes it easier to log to the same experiment from different places. See this section for more details.
• Explicitly Starting a New Experiment: If you want to always start a completely new experiment (similar to comet_ml.Experiment()), use mode="create". For more details, refer to this section.
• Resuming with a Non-existent Experiment Key: If you want to continue logging to an existing experiment and raise an exception if the experiment doesn’t exist (as with comet_ml.ExistingExperiment()), use mode="get". For more details, see this section.

Explicit Experiment End Requirement¶

While the new API simplifies starting experiments, there are now more cases where you might need to manually clean your Experiments. If you have access to the experiment object, you can call:

experiment.end()

If you don't have access to the experiment object, you can get it and end it like this:

experiment = comet.get_running_experiment()

if experiment:
    experiment.end()