# Suggest Inverse Step

Suggests the next set of input values for inverse optimization.

## Endpoint

`POST /models/{model_id}/projects/{project_id}/trials/{trial_id}/objectives/{objective_id}/inverses`

## Path Parameters

| Parameter     | Type    | Required | Description         |
| ------------- | ------- | -------- | ------------------- |
| model\_id     | integer | Yes      | ID of the model     |
| project\_id   | integer | Yes      | ID of the project   |
| trial\_id     | integer | Yes      | ID of the trial     |
| objective\_id | integer | Yes      | ID of the objective |

## Response Format

```json
{
    "id": 123,
    "input": [1.2, 3.4, 5.6],
    "iteration": 2,
    "status": "active",
    "convergence": 0.0025,
    "suggestTime": 125000000,
    "computeTime": 0,
    "createdAt": "2025-01-31T10:00:00.000Z",
    "updatedAt": "2025-01-31T10:00:00.000Z",
    "results": [
        {
            "number": 0,
            "type": "exact",
            "objective": 100.0,
            "minimumBound": null,
            "maximumBound": null,
            "output": 98.5,
            "error": 1.5,
            "detail": "Error exceeds L1 norm threshold",
            "satisfied": false
        },
        {
            "number": 1,
            "type": "lessthan",
            "objective": 50.0,
            "minimumBound": null,
            "maximumBound": null,
            "output": 45.2,
            "error": 0.0,
            "detail": "Output is less than target",
            "satisfied": true
        }
    ]
}
```

## Status Values

Possible status values are:

* `active` - Inverse iteration is active and running
* `converged` - Iteration has reached convergence criterion
* `max_iterations` - Maximum number of iterations reached
* `stopped` - Iteration was manually stopped
* `failed` - Iteration failed due to an error

## Examples

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

```python
from globalmoo import Client

client = Client(api_key="your-api-key")
suggestion = client.suggest_inverse(
    model_id=123,
    project_id=456,
    trial_id=789,
    objective_id=12
)

print(f"Suggested inputs: {[f'{x:.4f}' for x in suggestion.input]}")
print(f"Iteration: {suggestion.iteration}")
print(f"Status: {suggestion.status}")
print(f"Suggest time: {suggestion.suggest_time/1000000:.2f}ms")

# Check detailed objective results
print("\nObjective Status:")
for result in suggestion.results:
    print(f"\nObjective {result.number}:")
    print(f"  Type: {result.type}")
    print(f"  Target: {result.objective:.4f}")
    print(f"  Output: {result.output:.4f}")
    print(f"  Error: {result.error:.6f}")
    print(f"  Satisfied: {'✓' if result.satisfied else '✗'}")
    print(f"  Detail: {result.detail}")
```

{% endtab %}

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

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

const client = new Client('your-api-key');
const suggestion = await client.suggestInverse({
    modelId: 123,
    projectId: 456,
    trialId: 789,
    objectiveId: 12
});

console.log(`Suggested inputs: ${suggestion.input.map(x => x.toFixed(4))}`);
console.log(`Iteration: ${suggestion.iteration}`);
console.log(`Status: ${suggestion.status}`);
console.log(`Suggest time: ${(suggestion.suggestTime/1000000).toFixed(2)}ms`);

// Check detailed objective results
console.log('\nObjective Status:');
suggestion.results.forEach(result => {
    console.log(`\nObjective ${result.number}:`);
    console.log(`  Type: ${result.type}`);
    console.log(`  Target: ${result.objective.toFixed(4)}`);
    console.log(`  Output: ${result.output.toFixed(4)}`);
    console.log(`  Error: ${result.error.toFixed(6)}`);
    console.log(`  Satisfied: ${result.satisfied ? '✓' : '✗'}`);
    console.log(`  Detail: ${result.detail}`);
});
```

{% endtab %}

{% tab title="PHP" %}

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

$suggestion = $client->suggestInverse([
    "modelId" => 123,
    "projectId" => 456,
    "trialId" => 789,
    "objectiveId" => 12
]);

echo "Suggested inputs: " . implode(", ", array_map(function($x) { return number_format($x, 4); }, $suggestion->input)) . "\n";
echo "Iteration: " . $suggestion->iteration . "\n";
echo "Status: " . $suggestion->status . "\n";
echo "Suggest time: " . number_format($suggestion->suggestTime/1000000, 2) . "ms\n";

// Check detailed objective results
echo "\nObjective Status:\n";
foreach ($suggestion->results as $result) {
    echo "\nObjective " . $result->number . ":\n";
    echo "  Type: " . $result->type . "\n";
    echo "  Target: " . number_format($result->objective, 4) . "\n";
    echo "  Output: " . number_format($result->output, 4) . "\n";
    echo "  Error: " . number_format($result->error, 6) . "\n";
    echo "  Satisfied: " . ($result->satisfied ? '✓' : '✗') . "\n";
    echo "  Detail: " . $result->detail . "\n";
};
```

{% endtab %}
{% endtabs %}

## Error Responses

| Status Code | Description                                   |
| ----------- | --------------------------------------------- |
| 401         | Unauthorized - Invalid API key                |
| 404         | Model, project, trial, or objective not found |
| 409         | Conflict - Previous iteration not completed   |
| 429         | Too many requests - Rate limit exceeded       |
| 500         | Internal server error                         |

## Validation Rules

* Model, project, trial, and objective IDs must be positive integers
* Previous iteration must be completed before requesting next suggestion
* Trial must be in an active state
* Objective must have valid initial values loaded
* Values in response will be floating point numbers
