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
Bash
Java
R
MATLAB
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,
)
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
}
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;
  }
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="/"
))
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
Bash
Java
R
MATLAB
suggestion = conn.experiments(EXPERIMENT_ID).suggestions().create()
SUGGESTION=`curl -s -X POST https://api.sigopt.com/v1/experiments/EXPERIMENT_ID/suggestions -u "$SIGOPT_API_TOKEN":`
Suggestion suggestion = new Experiment(EXPERIMENT_ID).suggestions().create().call();
suggestion <- create_suggestion(experiment$id)
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
Bash
Java
R
MATLAB
observation = conn.experiments(EXPERIMENT_ID).observations().create(
  suggestion=SUGGESTION_ID,
  values=[{"name": "metric_1", "value": 3.14}],
)
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}]}"`
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();
create_observation(experiment$id, list(
  suggestion=suggestion$id,
  values=list(list(name="metric_1", value=3.14))
))
observation = conn.experiments(experiment_id).observations().create(struct( ...
  'suggestion', suggestion.id, ...
   'values', [
      struct(...
        'name', 'metric_1', ...
        'value', 3.14 ...
      )
    ]
))
Last modified 5mo ago