Java Getting Started

To use Comet’s Java SDK programming interface, you will first need a Comet API key.

Once you have your key, you will need to either:

The full reference documentation of the Java SDK is available on javadoc.io. This documentation is auto-generated as part of each Java SDK release to ensure it is always up to date.

Further details are described below.

Experiment

The core concept of Comet.ml's Java API is Experiment interface with 2 implementations:

OnlineExperiment is a specific run of a script that generated a result such as training a model on a single set of hyperparameters. OnlineExperiment will allow you to asynchronously log script output (stdout/stderr), parameters, metrics, and other items on any Java-based program.

While OnlineExperiment is for new experiments, ApiExperiment is for existing ones. ApiExperiment will synchronously fetch or update data on previously created experiment.

CometApi stands for common project queries. CometApi can fetch all user workspaces, find experiments by project id, etc.

Java Config

Before you can use Comet, you will need to configure Comet Experiment object with your API key, project and workspace names in your application.conf file. or as an environment variable

  • Using default application.conf (This file should be saved in the classpath) add comet key: yml comet { url = "https://www.comet.ml" maxAuthRetries = 4 apiKey = "XXXX" project = "java-sdk" workspace = "my-team" }

  • Overriding with your own comet.conf java ExperimentBuilder.OnlineExperiment().withConfigOverride(new File("comet.conf")).build()

  • Using environment variables bash COMET_API_KEY COMET_PROJECT_NAME COMET_WORKSPACE_NAME COMET_BASE_URL COMET_MAX_AUTH_RETRIES

  • Creating configured instance of the Comet Experiment using ExperimentBuilder

The ExperimentBuilder can be used to create configured instance of the Comet Experiment as follows:

java OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment() .withApiKey("someApiKey") .withProjectName("someProject") .withWorkspace("someWorkspace") .build(); experiment.setExperimentName("My experiment"); experiment.logParameter("batch_size", "500"); experiment.logMetric("strMetric", 123); experiment.end(); Also, OnlineExperiment can be used with try-with-resources statement which automatically handles call to the experiment.end(). java try (OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment() .withApiKey("someApiKey") .withProjectName("someProject") .withWorkspace("someWorkspace") .build()) { experiment.setExperimentName("My experiment"); experiment.logParameter("batch_size", "500"); experiment.logMetric("strMetric", 123); } catch (Exception e) { e.printStackTrace(); }

Java Example

Please see the complete Comet Java SDK in our Github repository.

Here is an end-to-end example showing the Java SDK in action. This file is saved in comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java:

```java package ml.comet.examples;

import ml.comet.experiment.ExperimentBuilder; import ml.comet.experiment.OnlineExperiment; import ml.comet.experiment.context.ExperimentContext; import org.apache.commons.io.file.PathUtils;

import java.io.IOException; import java.net.URI; import java.nio.file.Files; import java.nio.file.Path; import java.util.Objects;

import static ml.comet.examples.Utils.getResourceFile; import static ml.comet.examples.Utils.readResourceToString;

/** * Provides variety of example logging using OnlineExperiment. * *

To run from command line execute the following at the root of this module: * 

 * COMET_API_KEY=your_api_key \
 * COMET_WORKSPACE_NAME=your_workspace \
 * COMET_PROJECT_NAME=your_project_name \
 * mvn exec:java -Dexec.mainClass="ml.comet.examples.OnlineExperimentExample"
 *
* Make sure to provide correct values above. */ public class OnlineExperimentExample {

private static final String CHART_IMAGE_FILE = "chart.png";
private static final String MODEL_FILE = "model.hd5";
private static final String HTML_REPORT_FILE = "report.html";
private static final String GRAPH_JSON_FILE = "graph.json";
private static final String CODE_FILE = "code_sample.py";

/**
 * The main entry point to the example.
 *
 * @param args the command line arguments if any.
 */
public static void main(String[] args) {

    //this will take configs from /comet-java-sdk/comet-examples/src/main/resources/application.conf
    //be sure you have set up apiKey, project, workspace in defaults.conf before you start!

    OnlineExperiment experiment = ExperimentBuilder
            .OnlineExperiment()
            .interceptStdout()
            .build();

    //you can use a default builder or just inject params
    //OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment().builder();

    try {
        OnlineExperimentExample.run(experiment);
    } catch (Throwable e) {
        e.printStackTrace();
    } finally {
        experiment.end();
    }
}

private static void run(OnlineExperiment experiment) throws Exception {
    experiment.setExperimentName("Java-SDK 2.0.2");
    experiment.nextStep();

    //metric can be a number, string , or double
    experiment.logMetric("strMetric", "123");
    experiment.logMetric("numMetric", 123, 123, 4);
    experiment.nextEpoch();
    experiment.logMetric("doubleMetric", 123.5d);

    experiment.setEpoch(3);

    generateCharts(experiment);

    experiment.setStep(1234);

    experiment.logHtml(generateCustomHtmlReport(), false);

    experiment.logParameter("batch_size", "500");
    experiment.logParameter("learning_rate", 12);

    // upload assets
    //
    experiment.uploadAsset(getResourceFile(CHART_IMAGE_FILE), "amazing chart.png", false);
    experiment.uploadAsset(getResourceFile(MODEL_FILE), false,
            ExperimentContext.builder().withContext("train").build());

    experiment.nextStep();

    // upload asset files from folder
    //
    Path assetDir = copyResourcesToTmpDir();
    experiment.logAssetFolder(assetDir.toFile(), true, true);

    // log remote assets
    //
    experiment.logRemoteAsset(new URI("s3://bucket/folder/dataCorpus.hd5"), "modelDataCorpus", false);

    experiment.logOther("Parameter", 4);

    System.out.println("Epoch 1/20");
    System.out.println("- loss: 0.7858 - acc: 0.7759 - val_loss: 0.3416 - val_acc: 0.9026");

    experiment.logGraph(readResourceToString(GRAPH_JSON_FILE));

    experiment.logCode(getResourceFile(CODE_FILE),
            ExperimentContext.builder().withContext("test").build());

    System.out.println("===== Experiment completed ====");

    // will close connection, if not called connection will close on jvm exit
    experiment.end();

    // remove tmp directory
    PathUtils.deleteDirectory(assetDir);
}

private static void generateCharts(OnlineExperiment experiment) {
    long currentStep = experiment.getStep();

    for (int i = 1; i < 15; i++) {
        experiment.logMetric("numMetric", 123 + i, currentStep + i, getUpdatedEpochValue(experiment));
    }

    for (int i = 1; i < 15; i++) {
        experiment.logMetric("strMetric", "123" + i, currentStep + i, getUpdatedEpochValue(experiment));
    }

    for (int i = 1; i < 15; i++) {
        experiment.logMetric("doubleMetric", 123.12d + i, currentStep + i, getUpdatedEpochValue(experiment));
    }
}

private static String generateCustomHtmlReport() throws IOException {
    return readResourceToString("report.html");
}

private static long getUpdatedEpochValue(OnlineExperiment experiment) {
    return experiment.getEpoch() + experiment.getStep() / 5;
}

private static Path copyResourcesToTmpDir() throws IOException {
    Path root = Files.createTempDirectory("onlineExperimentExample");
    PathUtils.copyFileToDirectory(
            Objects.requireNonNull(getResourceFile(CHART_IMAGE_FILE)).toPath(), root);
    PathUtils.copyFileToDirectory(
            Objects.requireNonNull(getResourceFile(MODEL_FILE)).toPath(), root);
    Files.createTempFile(root, "empty_file", ".txt");

    Path subDir = Files.createTempDirectory(root, "subDir");
    PathUtils.copyFileToDirectory(
            Objects.requireNonNull(getResourceFile(HTML_REPORT_FILE)).toPath(), subDir);
    PathUtils.copyFileToDirectory(
            Objects.requireNonNull(getResourceFile(GRAPH_JSON_FILE)).toPath(), subDir);

    return root;
}

} ```

For more information, please see: