Optimisation Service

https://www.optimatika.se/optimisation-service/docs/
Admin
Optimisation Service is a self-hosted containerized mathematical optimization service that solves...
Tokens:7,753
Snippets:59
Trust Score:8.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick start: build and solve a model with OptClientV1

Source: https://www.optimatika.se/optimisation-service/docs

Quick start example: build a model, solve it remotely, and read the result. Uses OptClientV1, OptModel, OptVariable, and OptResult.

```java
// Connect to the service
OptClientV1 client = OptClientV1.newInstance("https://your-service-host");

// Build a model
OptModel model = client.newModel();

OptVariable x = model.newRealVariable("x").lower(0);
OptVariable y = model.newRealVariable("y").lower(0);

model.newConstraint("budget").set(x, 1).set(y, 1).upper(10);

model.objective().set(x, 3).set(y, 5);

// Solve remotely (returns a Future)
OptResult result = model.maximise().get();

System.out.println("Optimal: " + result.isOptimal());
System.out.println("Value:   " + result.getValue());
System.out.println("x = " + x.doubleValue());
System.out.println("y = " + y.doubleValue());
```

--------------------------------

### GET /optimisation/v1/environment

Source: https://www.optimatika.se/optimisation-service/docs

Returns information about the running build, its licence, and the available solvers. The response includes build details, runtime, licence, and a list of solvers.

```APIDOC
## GET /optimisation/v1/environment

### Description
Returns information about the running build, its licence, and the available solvers. The response includes build details, runtime, licence, and a list of solvers.

### Method
GET

### Endpoint
/optimisation/v1/environment

### Response
#### Success Response (200)
- **build** (object) - Contains module, built timestamp, commit, branch, and dirty flag.
- **runtime** (string) - Runtime description.
- **licence** (string) - Licence description.
- **solvers** (object) - Contains `probed` (boolean) and `available` (array of solver names).

#### Response Example
```
{
  "build": {"module":"polar","built":"2026-10-01T11:46:07Z","commit":"66f8636","branch":"develop","dirty":"false"},
  "runtime":"1GB/4threads x86_64 [...]",
  "licence":"Polar (max 4 vCPUs, full solver suite ...)",
  "solvers":{"probed":true,"available":["LP-HiGHS","LP-JVM","MILP-SCIP", ...]}
}
```
```

--------------------------------

### Model builder API: variables, constraints, objective

Source: https://www.optimatika.se/optimisation-service/docs

Model builder API example: create real, integer, and binary variables, add constraints with bounds, set an objective, and solve.

```java
OptModel model = client.newModel();

// Variable types
OptVariable x = model.newRealVariable("x").lower(0).upper(100);
OptVariable n = model.newIntegerVariable("n").lower(0).upper(10);
OptVariable b = model.newBinaryVariable("use_option");

// Constraints with bounds
model.newConstraint("capacity")
     .set(x, 2.5).set(n, 1)
     .upper(50);

model.newConstraint("minimum")
     .set(x, 1).set(b, -10)
     .lower(0);

// Objective
model.objective().set(x, 3).set(n, 7);

// Solve
OptResult result = model.minimise().get();
```

--------------------------------

### GET /health

Source: https://www.optimatika.se/optimisation-service/docs

Health check for probes. Returns a status code and no body.

```APIDOC
## GET /health

### Description
Health check for probes. Returns a status code and no body.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
No body.
```

--------------------------------

### GET /optimisation/v1/poll-result/{key}

Source: https://www.optimatika.se/optimisation-service/docs

Checks the status of a submitted model and retrieves the solution when ready. While the solver is working, the status is PENDING; when done, the result contains the solver state, objective value, and solution vector.

```APIDOC
## GET /optimisation/v1/poll-result/{key}

### Description
Checks the status of a submitted model and retrieves the solution when ready. While the solver is working, the status is PENDING; when done, the result contains the solver state, objective value, and solution vector.

### Method
GET

### Endpoint
/optimisation/v1/poll-result/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The queue identifier returned by the submit endpoint.

### Response
#### Success Response (200)
- **key** (string) - The queue identifier.
- **status** (string) - The status of the solve: `PENDING` while working, `DONE` when complete.
- **result** (string) - Present when status is `DONE`. Contains the solver state (e.g., `OPTIMAL`, `FEASIBLE`, `INFEASIBLE`), the objective value, and the solution vector.

#### Response Example
```
{
  "key": "PmkvX3SNQ0gjRtCD",
  "status": "DONE",
  "result": "OPTIMAL 13.0 @ { 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 }"
}
```
```

--------------------------------

### Poll result response JSON

Source: https://www.optimatika.se/optimisation-service/docs

Response from `GET /optimisation/v1/poll-result/{key}` when the solve is complete. The `result` string contains the solver state (e.g. `OPTIMAL`), the objective value, and the solution vector.

```json
{
  "key": "PmkvX3SNQ0gjRtCD",
  "status": "DONE",
  "result": "OPTIMAL 13.0 @ { 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 }"
}
```

--------------------------------

### Set licence keys via OPTIMATIKA_LICENCE_KEY

Source: https://www.optimatika.se/optimisation-service/docs

Sets the licence keys as a comma- or whitespace-separated environment variable. Supply every key you hold; a single key would work but supplying all makes plan changes safe.

```bash
OPTIMATIKA_LICENCE_KEY=key-one,key-two,key-three
```

--------------------------------

### Deploy with kubectl apply -k k8s/overlays/gcp

Source: https://www.optimatika.se/optimisation-service/docs

Applies the Kustomize overlay for GCP. The product ships with a base plus one overlay per cloud, providing a Deployment with a single replica and a Service.

```bash
kubectl apply -k k8s/overlays/gcp
```

--------------------------------

### Set licence keys via OPTIMATIKA_LICENCE_KEY_FILE

Source: https://www.optimatika.se/optimisation-service/docs

Points to a mounted Kubernetes secret file containing one licence key per line. Use this instead of the environment variable when using a mounted secret.

```bash
OPTIMATIKA_LICENCE_KEY_FILE=/etc/optimatika/licence-keys
```

--------------------------------

### Develop locally and solve remotely with ojAlgo

Source: https://www.optimatika.se/optimisation-service/docs

Shows the intended workflow: solve locally during development with ojAlgo's built-in solvers, then switch to the remote service in production without changing model code. The same model building code is used in both cases.

```java
// Development: solve locally (no environment setup needed)
ExpressionsBasedModel model = new ExpressionsBasedModel();
// ... build model ...
Optimisation.Result localResult = model.minimise();

// Production: same model, solve via the service
Optimisation.Environment env = Optimisation.newEnvironment();
env.setRemoteSolver(client::putOnQueue, client::pollResult);

ExpressionsBasedModel model = env.newModel();
// ... same model building code ...
Optimisation.Result remoteResult = model.submit(Optimisation.Sense.MIN).get();
```

--------------------------------

### Configure readiness and liveness probes

Source: https://www.optimatika.se/optimisation-service/docs

Probe configuration for the container, which listens on port 8080 (configurable via PORT). Both probes target /health.

```yaml
readinessProbe:
  httpGet: { path: /health, port: 8080 }
  periodSeconds: 10
livenessProbe:
  httpGet: { path: /health, port: 8080 }
  periodSeconds: 30
```

--------------------------------

### Check environment endpoint with curl

Source: https://www.optimatika.se/optimisation-service/docs

Query the environment endpoint to see the running build, runtime, licence, and available solvers. The response shows `probed` as `true` and lists the full solver suite; shortly after startup `probed` is `false` and only pure-Java solvers appear.

```bash
curl -s https://your-service-host/optimisation/v1/environment
```

```json
{"build":{"module":"polar","built":"2026-10-01T11:46:07Z","commit":"66f8636","branch":"develop","dirty":"false"},
 "runtime":"1GB/4threads x86_64 [...]",
 "licence":"Polar (max 4 vCPUs, full solver suite ...)",
 "solvers":{"probed":true,"available":["LP-HiGHS","LP-JVM","MILP-SCIP", ...]}}
```

--------------------------------

### Configure ojAlgo environment with remote solver

Source: https://www.optimatika.se/optimisation-service/docs

Configure the ojAlgo environment to use the remote service as a solver. Requires both ojAlgo and the service client on the classpath. The method references match ojAlgo's Optimisation.ModelSubmitter and Optimisation.ResultPoller functional interfaces.

```java
OptClientV1 client = OptClientV1.newInstance("https://your-service-host");

Optimisation.Environment environment = Optimisation.newEnvironment();
environment.setRemoteSolver(client::putOnQueue, client::pollResult);
```

--------------------------------

### POST /optimisation/v1/put-on-queue/{format}/{sense}

Source: https://www.optimatika.se/optimisation-service/docs

Submits a model for solving. The request body is the raw model bytes in the specified format (MPS or LP) and the sense (MIN or MAX). Returns a JSON object with a queue key and status.

```APIDOC
## POST /optimisation/v1/put-on-queue/{format}/{sense}

### Description
Submits a model for solving. The request body is the raw model bytes in the specified format (MPS or LP) and the sense (MIN or MAX). Returns a JSON object with a queue key and status.

### Method
POST

### Endpoint
/optimisation/v1/put-on-queue/{format}/{sense}

### Parameters
#### Path Parameters
- **format** (string) - Required - The format of the request body. Values: `MPS`, `LP`.
- **sense** (string) - Required - Whether to minimise or maximise the objective. Values: `MIN`, `MAX`.

#### Request Body
The raw model bytes in the specified format.

### Request Example
```
--data-binary @model.mps
```

### Response
#### Success Response (200)
- **key** (string) - The queue identifier used to poll for the result.
- **status** (string) - The status of the submission, e.g., `PENDING`.

#### Response Example
```
{
  "key": "PmkvX3SNQ0gjRtCD",
  "status": "PENDING"
}
```
```

--------------------------------

### POST /optimisation/v1/abort-all

Source: https://www.optimatika.se/optimisation-service/docs

Empties the queue and aborts every running solve.

```APIDOC
## POST /optimisation/v1/abort-all

### Description
Empties the queue and aborts every running solve.

### Method
POST

### Endpoint
/optimisation/v1/abort-all
```

--------------------------------

### POST /optimisation/v1/abort/{key}

Source: https://www.optimatika.se/optimisation-service/docs

Abandons a queued or running solve identified by the given key.

```APIDOC
## POST /optimisation/v1/abort/{key}

### Description
Abandons a queued or running solve identified by the given key.

### Method
POST

### Endpoint
/optimisation/v1/abort/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The queue identifier of the solve to abort.
```

--------------------------------

### Maven dependency for optimisation-service-client

Source: https://www.optimatika.se/optimisation-service/docs

Add the client library as a single Maven dependency with zero transitive dependencies.

```xml
<dependency>
    <groupId>se.optimatika</groupId>
    <artifactId>optimisation-service-client</artifactId>
    <version>1.0.0</version>
</dependency>
```

--------------------------------

### Solve ojAlgo model remotely via service

Source: https://www.optimatika.se/optimisation-service/docs

Create a model from the configured environment and submit it to the remote service. The model is serialized, sent to the service, solved by the best available solver, and the result returned through the standard ojAlgo API.

```java
ExpressionsBasedModel model = environment.newModel();

Variable x = model.newVariable("x").lower(0).weight(3);
Variable y = model.newVariable("y").lower(0).weight(5);

model.addExpression("budget").set(x, 1).set(y, 1).upper(10);

// Solve via the service
Future<Optimisation.Result> future = model.submit(Optimisation.Sense.MAX);
Optimisation.Result result = future.get();
```

--------------------------------

### Pull the Optimisation Service image

Source: https://www.optimatika.se/optimisation-service/docs

Pulls the public Optimisation Service container image. No registry account, credentials, or pull secret are required.

```bash
docker pull ghcr.io/optimatika/optimisation-service
```

--------------------------------

### POST /optimisation/v1/translate/{from}/{to}

Source: https://www.optimatika.se/optimisation-service/docs

Converts a model between EBM, MPS, and LP formats. The request body is the model in the input format; the response body is the model in the output format.

```APIDOC
## POST /optimisation/v1/translate/{from}/{to}

### Description
Converts a model between EBM, MPS, and LP formats. The request body is the model in the input format; the response body is the model in the output format.

### Method
POST

### Endpoint
/optimisation/v1/translate/{from}/{to}

### Parameters
#### Path Parameters
- **from** (string) - Required - The input format. Values: `EBM`, `MPS`, `LP`.
- **to** (string) - Required - The output format. Values: `EBM`, `MPS`, `LP`.

#### Request Body
The model in the input format.

### Response
#### Success Response (200)
The model in the output format.
```

--------------------------------

### HTTP client directly: submit MPS and poll

Source: https://www.optimatika.se/optimisation-service/docs

Use OptClientV1 directly to submit an MPS file and poll for the result. Shows putOnQueue, putOnQueueParsed, and pollResultParsed methods.

```java
OptClientV1 client = OptClientV1.newInstance("https://your-service-host");

// Submit an MPS file
byte[] mpsData = Files.readAllBytes(Path.of("model.mps"));
String response = client.putOnQueue(mpsData, "MPS", false); // false = minimise

// Or use the parsed variant
Map<String, Object> parsed = client.putOnQueueParsed(mpsData, "MPS", false);
String key = (String) parsed.get(OptClientV1.KEY);

// Poll until done
Map<String, Object> poll = client.pollResultParsed(key);
while ("PENDING".equals(poll.get(OptClientV1.STATUS))) {
    Thread.sleep(100);
    poll = client.pollResultParsed(key);
}

OptResult result = (OptResult) poll.get(OptClientV1.RESULT);
```

--------------------------------

### Submit model response JSON

Source: https://www.optimatika.se/optimisation-service/docs

Response from `POST /optimisation/v1/put-on-queue/{format}/{sense}` after submitting a model. Contains the queue key used for polling and a status of `PENDING`.

```json
{
  "key": "PmkvX3SNQ0gjRtCD",
  "status": "PENDING"
}
```

--------------------------------

### Submit and poll with curl

Source: https://www.optimatika.se/optimisation-service/docs

Complete curl workflow: health check, submit an MPS model for minimisation, and poll for the result. Uses `jq` to extract the key from the submission response.

```bash
# Check that the service is running (prints the HTTP status, 200 when healthy)
curl -s -o /dev/null -w "%{http_code}\n" https://your-service-host/health

# Submit an MPS model for minimisation
KEY=$(curl -s -X POST \
  -H "Content-Type: application/octet-stream" \
  --data-binary @model.mps \
  https://your-service-host/optimisation/v1/put-on-queue/MPS/MIN \
  | jq -r '.key')

# Poll for the result
curl -s https://your-service-host/optimisation/v1/poll-result/$KEY
```
Tokens:
Raw