# Initialize Inverse Optimization

Initializes an inverse optimization process for a trial in globalMOO.

## Endpoint

`POST /trials/{trial_id}/initialize-inverse`

## Request Parameters

| Parameter      | Type           | Required | Description                                           |
| -------------- | -------------- | -------- | ----------------------------------------------------- |
| convergence    | float          | Yes      | Convergence criterion (must be positive)              |
| objectives     | array\[float]  | Yes      | Target values for each objective                      |
| objectiveTypes | array\[string] | Yes      | Type for each objective (see valid types below)       |
| initialInput   | array\[float]  | Yes      | Initial input values (must match project input count) |
| initialOutput  | array\[float]  | Yes      | Initial output values (must match objectives length)  |
| minimumBounds  | array\[float]  | Yes      | Lower bounds (for percent/value objectives)           |
| maximumBounds  | array\[float]  | Yes      | Upper bounds (for percent/value objectives)           |
| desiredL1Norm  | float          | Yes      | Desired L1 norm (defaults to 0.0)                     |

## Request Format

```json
{
    "convergence": 0.001,
    "objectives": [100.0, 50.0, 25.0],
    "objectiveTypes": ["percent", "value", "percent"],
    "initialInput": [1.0, 2.0, 3.0],
    "initialOutput": [90.0, 45.0, 20.0],
    "minimumBounds": [-5.0, -2.0, -1.0],
    "maximumBounds": [5.0, 2.0, 1.0],
    "desiredL1Norm": 0.0
}
```

## Response Format

```json
{
    "id": 123,
    "trialId": 456,
    "status": "active",
    "convergence": 0.001,
    "iteration": 1,
    "input": [1.0, 2.0, 3.0],
    "output": [90.0, 45.0, 20.0],
    "suggestTime": 0.0,
    "computeTime": 0.0,
    "createdAt": "2025-01-31T10:00:00.000Z",
    "updatedAt": "2025-01-31T10:00:00.000Z",
    "results": [
        {
            "number": 0,
            "type": "percent",
            "objective": 100.0,
            "minimumBound": -5.0,
            "maximumBound": 5.0,
            "output": 90.0,
            "error": 10.0,
            "detail": "Error exceeds percent bounds",
            "satisfied": false
        },
        {
            "number": 1,
            "type": "value",
            "objective": 50.0,
            "minimumBound": -2.0,
            "maximumBound": 2.0,
            "output": 45.0,
            "error": -5.0,
            "detail": "Output within bounds",
            "satisfied": true
        },
        {
            "number": 2,
            "type": "percent",
            "objective": 25.0,
            "minimumBound": -1.0,
            "maximumBound": 1.0,
            "output": 20.0,
            "error": -20.0,
            "detail": "Error exceeds percent bounds",
            "satisfied": false
        }
    ]
}
```

## Examples

{% tabs %}
{% tab title="Python" %}

```python
from globalmoo import Client, ObjectiveType

client = Client(api_key="your-api-key")
inverse = client.initialize_inverse(
    trial_id=123,
    convergence=0.001,
    objectives=[100.0, 50.0, 25.0],
    objective_types=[
        ObjectiveType.PERCENT,
        ObjectiveType.VALUE,
        ObjectiveType.PERCENT
    ],
    initial_input=[1.0, 2.0, 3.0],
    initial_output=[90.0, 45.0, 20.0],
    minimum_bounds=[-5.0, -2.0, -1.0],
    maximum_bounds=[5.0, 2.0, 1.0],
    desired_l1_norm=0.0
)
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { Client } = require('globalmoo');

const client = new Client('your-api-key');
const inverse = await client.initializeInverse({
    trialId: 123,
    convergence: 0.001,
    objectives: [100.0, 50.0, 25.0],
    objectiveTypes: ["exact", "value", "percent"],
    initialInput: [1.0, 2.0, 3.0],
    initialOutput: [90.0, 45.0, 20.0],
    minimumBounds: [-5.0, -2.0, -1.0],
    maximumBounds: [5.0, 2.0, 1.0],
    desiredL1Norm: 0.0
});
```

{% endtab %}

{% tab title="PHP" %}

```php
$client = new Client("your-api-key");

$inverse = $client->initializeInverse([
    "trialId" => 123,
    "convergence" => 0.001,
    "objectives" => [100.0, 50.0, 25.0],
    "objectiveTypes" => ["exact", "value", "percent"],
    "initialInput" => [1.0, 2.0, 3.0],
    "initialOutput" => [90.0, 45.0, 20.0],
    "minimumBounds" => [-5.0, -2.0, -1.0],
    "maximumBounds" => [5.0, 2.0, 1.0],
    "desiredL1Norm" => 0.0
]);
```

{% endtab %}
{% endtabs %}

## Error Responses

| Status Code | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| 400         | Invalid request - Missing required fields or invalid format |
| 401         | Unauthorized - Invalid API key                              |
| 404         | Trial not found                                             |
| 429         | Too many requests - Rate limit exceeded                     |
| 500         | Internal server error                                       |

## Validation Rules

* All numeric arrays (objectives, initialInput, initialOutput) must be arrays of floats
* Array lengths must be consistent:
  * objectives and objectiveTypes must have the same length
  * initialInput length must match the project's input count
  * initialOutput length must match objectives length
  * minimumBounds/maximumBounds must match objectives length when required
* Convergence must be a positive float
* objectiveTypes must contain valid type strings (see above)
* For PERCENT and VALUE objectives:
  * minimumBounds and maximumBounds are required
  * maximumBounds values must be greater than minimumBounds
* For EXACT objectives, convergence must be positive, and all entries must be EXACT. This objective type refers to the total L1-norm for the outcomes vector, not any specific outcome.
* All input and output values must be valid floating point numbers


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://globalmoo.gitbook.io/globalmoo-documentation/endpoints/inverse/initialize.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.