Skip to content
The SigOpt Java API Client
Java Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
.travis.yml Travis CI Fix: link cacert in build matrix for JDK9 and manually inst… Jul 11, 2019
LICENSE
README.md
VERSION
pom.xml
publish Fix for GPG Sep 26, 2017
samples.md sigopt-examples project in experiment create example (#47) Mar 23, 2019

README.md

Sigopt Java API Client

You can sign up for a Sigopt experiment at https://sigopt.com.

Requirements

Sigopt-java requires Java 1.7

Installation

Maven users

Update your project settings (commonly found at ~/.m2/settings.xml) to include the SigOpt package.

<?xml version="1.0" encoding="UTF-8" ?>
<settings xsi:schemaLocation='http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd'
xmlns='http://maven.apache.org/SETTINGS/1.0.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
  <profiles>
    <profile>
      <repositories>
        <repository>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <id>bintray-sigopt-maven</id>
          <name>bintray</name>
          <url>http://dl.bintray.com/sigopt/maven</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <id>bintray-sigopt-maven</id>
          <name>bintray-plugins</name>
          <url>http://dl.bintray.com/sigopt/maven</url>
        </pluginRepository>
      </pluginRepositories>
      <id>bintray</id>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>bintray</activeProfile>
  </activeProfiles>
</settings>

More information on this step can be found on BinTray

Then, add this dependency to your project's POM:

<dependency>
  <groupId>com.sigopt</groupId>
  <artifactId>sigopt-java</artifactId>
  <version>6.2.0</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "com.sigopt:sigopt-java:6.2.0"

Others

You'll need to manually install the following JARs:

Getting Started

Sign up for an account at https://sigopt.com. In order to use the API, you'll need your API token from the API tokens page.

To call the API, instantiate a connection with your token.

import com.sigopt.Sigopt;
Sigopt.clientToken = "CLIENT_TOKEN";

Issuing Requests

Then, you can use the connection to issue API requests. An example creating an experiment and running the optimization loop:

import java.util.Arrays;
import com.sigopt.Experiment;
Experiment experiment = (
  Experiment.create(
    new Experiment.Builder()
      .name("New Experiment")
      .parameters(Arrays.asList(
        new Parameter.Builder()
          .type("double")
          .name("gamma")
          .bounds(new Bounds.Builder()
            .max(1.0)
            .min(0.0001)
            .build())
          .build()))
      .build())
  .call()
);

Suggestion suggestion = experiment.suggestions().create().call();
double value = evaluateMetric(suggestion);  // Implement this
Observation observation = (
  experiment.observations().create(
    new Observation.Builder()
      .suggestion(suggestion.getId())
      .value(value)
      .build())
  .call()
);

For more examples, consult the samples.md file in this repository.

Endpoints

Endpoints are grouped by objects. For example, endpoints that interact with Experiments are under Experiment. Here are example endpoints, and their corresponding REST endpoint.

Experiment.fetch(id)    // GET /experiments/id
Experiment.list()       // GET /experiments
Experiment.create()     // POST /experiments
Experiment.update()     // PUT /experiments
Experiment.delete(id)   // DELETE /experiments/id
Experiment.deleteList() // DELETE /experiments/id

These methods will return an APIMethodCaller. You can add parameters to an APIMethodCaller with .addParam("key", "value"). You can also add JSON data to the body of the request with .data(jsonBody). When you are ready to issue the API call, just call .call().

Experiment.list()
  .addParam("state", "active")
  .call();

Experiment.create()
  .data(new Experiment.Builder().name(...))
  .call();

Just like in the resource urls, suggestions and observations are under experiments. Access these objects with (new Experiment(ID)).suggestions and (new Experiment(ID)).observations.

(new Experiment(id)).suggestions().fetch(sugg_id)   // GET /experiments/id/suggestions/sugg_id
(new Experiment(id)).suggestions().list()           // GET /experiments/id/suggestions
(new Experiment(id)).suggestions().create()         // POST /experiments/id/suggestions
(new Experiment(id)).suggestions().update()         // PUT /experiments/id/suggestions
(new Experiment(id)).suggestions().delete(sugg_id)  // DELETE /experiments/id/suggestions/sugg_id
(new Experiment(id)).suggestions().deleteList()     // DELETE /experiments/id/suggestions

Testing

You must have Maven installed. To run the tests, simply run mvn test. You can run particular tests by passing -D test=Class#method -- for example, -D test=APIResourceTest#constructResourceFromJson.

You can’t perform that action at this time.