Links

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 ...
)
]
))