Quick Start

In this section, we list the commonly used API objects and endpoints. For the complete core module documentation, please refer to the Endpoints and Objects pages.

Experiment

Object

Experiment - An experiment represents an objective that SigOpt is optimizing, the relevant parameters, and the underlying data.

Endpoints

Experiment Create - Creates a new Experiment.

Experiment Update - Updates an existing Experiment

Example: Experiment Create

Python

conn = Connection(client_token="USER_TOKEN")

experiment = conn.experiments().create(
  name="first experiment",
  parameters=[
    dict(
      name="parameter_1",
      bounds=dict(
        min=10,
        max=100
        ),
      type="int"
      ),
    dict(
      name="parameter_2",
      bounds=dict(
        min=0.1,
        max=1.4,
        ),
      type="double"
      )
    ],
  metrics=[
    dict(
      name="metric_1",
      objective="maximize",
      strategy="optimize"
      )
    ],
  observation_budget=30,
)

Bash

EXPERIMENT=curl -s -X POST https://api.sigopt.com/v1/experiments -u "$SIGOPT_API_TOKEN": \
    -H "Content-Type: application/json" -d "`cat experiment_meta.json`"

JSON file defining the Experiment:

experiment_meta.json

{
  "name": "first experiment",
  "parameters": [
    {
      "name": "parameter_1",
      "bounds": {
        "min": 10,
        "max": 100
      },
      "type": "int"
    },
    {
      "name": "parameter_2",
      "bounds": {
        "min": 0.1,
        "max": 1.4
      },
      "type": "double"
    }
  ],
  "metrics": [
    {
      "name": "metric_1",
      "objective": "maximize",
      "strategy": "optimize"
    }
  ],
  "observation_budget": 30
}

Java

import com.sigopt.SigOpt;
import com.sigopt.exception.SigoptException;
import com.sigopt.model.*;

import java.util.Arrays;

public class YourSigoptExperiment {
  public static Experiment createExperiment() throws SigoptException {
    Experiment experiment = Experiment.create()
      .data(
        new Experiment.Builder()
          .name("first experiment")
          .parameters(java.util.Arrays.asList(
            new Parameter.Builder()
              .name("parameter_1")
              .bounds(new Bounds.Builder()
                .min(10)
                .max(100)
                .build())
              .type("int")
              .build(),
            new Parameter.Builder()
              .name("parameter_2")
              .bounds(new Bounds.Builder()
                .min(0.1)
                .max(1.4)
                .build())
              .type("double")
              .build()
            ))
          .metrics(java.util.Arrays.asList(
            new Metric.Builder()
              .name("metric_1")
              .objective("maximize")
              .strategy("optimize")
              .build()
            ))
          .observationBudget(30)
          .type("offline")
          .build()
        )
      .call();
    return experiment;
  }

R

install.packages("devtools", repos = "http://cran.us.r-project.org")
library(devtools)
install_github("sigopt/SigOptR")
library(SigOptR)
Sys.setenv(SIGOPT_API_TOKEN="USER_TOKEN")


experiment <- create_experiment(list(
  name="first experiment",
  # Define which parameters you would like to tune
  parameters=list(
    list(name="parameter_1", type="int", bounds=list(min=10, max=100)),
    list(name="parameter_2", type="double", bounds=list(min=0.1, max=1.4))
  ),
  metrics=list(
    list(name="metric_1", objective="maximize", strategy="optimize")
  ),
  observation_budget=30,
))

print(paste(
  "Created experiment: https://app.sigopt.com/experiment",
  experiment$id,
  sep="/"
))

MATLAB

import sigopt.Connection

conn = Connection("USER_TOKEN");

% Create your experiment
experiment = conn.experiments().create(struct( ...
  'name', 'first experiment', ...
  'parameters', [ ...
    struct( ...
      'name', 'parameter_1', ...
      'type', 'int', ...
      'bounds', struct( ...
        'min', 10, ...
        'max', 100 ...
      ) ...
    ), ...
    struct( ...
      'name', 'parameter_2', ...
      'type', 'double', ...
      'bounds', struct( ...
        'min', 0.1, ...
        'max', 1.4 ...
      ) ...
    ) ...
  ], ...
  'metrics': [ ...
    struct( ...
      'name', 'metric_1', ...
      'objective', 'maximize', ...
      'strategy', 'optimize' ...
    ), ...
  ], ...
  'observation_budget', 30 ...
))
experiment_id = experiment.id;

Suggestion

Object

Suggestion - A representation of the parameters that SigOpt has suggested. Contains a list of parameters and their suggested values.

Endpoints

Suggestion Create - Creates a Suggestion that SigOpt recommends in order to optimize your metric.

Suggestion List - Retrieves a Pagination of all Suggestion objects for this experiment.

Suggestion Delete - Deletes a Suggestion

Example: Suggestion Create

Python

suggestion = conn.experiments(EXPERIMENT_ID).suggestions().create()

Bash

SUGGESTION=`curl -s -X POST https://api.sigopt.com/v1/experiments/EXPERIMENT_ID/suggestions -u "$SIGOPT_API_TOKEN":`

Java

Suggestion suggestion = new Experiment(EXPERIMENT_ID).suggestions().create().call();

R

suggestion <- create_suggestion(experiment$id)

MATLAB

suggestion = conn.experiments(experiment_id).suggestions().create()

Observation

Object

Observation - The observed data from a single trial in your experiment.

Endpoints

Observation Create - Create an Observation.

Observation List - Retrieves a Pagination of all Observation objects for this experiment.

Observation Delete - Deletes an Observation.

Example: Observation Create

Python

observation = conn.experiments(EXPERIMENT_ID).observations().create(
  suggestion=SUGGESTION_ID,
  values=[{"name": "metric_1", "value": 3.14}],
)

Bash

OBSERVATION=`curl -s -X POST https://api.sigopt.com/v1/experiments/EXPERIMENT_ID/observations -u "$SIGOPT_API_TOKEN": \
  -H 'Content-Type: application/json' \
  -d "{\"suggestion\":\"SUGGESTION_ID\",\"values\":[{\"name\":\"metric_1\",\"value\":3.14}]}"`

Java

Observation observation = new Experiment(EXPERIMENT_ID).observations().create()
  .data(
    new Observation.Builder()
      .suggestion("SUGGESTION_ID")
      .values(java.util.Arrays.asList(
        new Value.Builder()
          .name("metric_1")
          .value(3.14)
          .build()
        ))
      .build()
    )
  .call();

R

create_observation(experiment$id, list(
  suggestion=suggestion$id,
  values=list(list(name="metric_1", value=3.14))
))

MATLAB

observation = conn.experiments(experiment_id).observations().create(struct( ...
  'suggestion', suggestion.id, ...
   'values', [
      struct(...
        'name', 'metric_1', ...
        'value', 3.14 ...
      )
    ]
))