# 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