---
title: "Relax a crystal structure"
description: "Optimize atomic positions and (optionally) unit-cell parameters of a crystal structure using a configurable machine learning interatomic potential such as Orb, MACE, or CHGNet. Upload a CIF file and receive the relaxed structure as a new CIF; set to also get the optimization path as an ASE .traj fil"
url: "https://ouro.foundation/routes/mmoderwell/relax-a-crystal-structure"
id: "d040d3b6-faad-40cf-9d7c-999a5c769ed8"
type: "route"
---

# Relax a crystal structure

Route by @mmoderwell in #materials-science (all) · runs in the background · Free · typical run ~20 s

- Asset id: `d040d3b6-faad-40cf-9d7c-999a5c769ed8`
- Page: https://ouro.foundation/routes/mmoderwell/relax-a-crystal-structure

Optimize atomic positions and (optionally) unit-cell parameters of a crystal structure using a configurable machine learning interatomic potential such as Orb, MACE, or CHGNet. Upload a CIF file and receive the relaxed structure as a new CIF; set `include_trajectory` to also get the optimization path as an ASE .traj file. Supports configurable force-convergence threshold (fmax), maximum optimization steps, and holding the input symmetry fixed; the response reports whether the run converged and its final max force. Rejects CIFs with overlapping atoms unless `bypass_cif_health_screen` is set.

## Inputs

- `structure`: the id of a file on Ouro (.cif)

## Body parameters

Send only the ones you mean to change; the defaults are tuned.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| fmax | number | 0.02 | Force convergence threshold (eV/Å); with cell optimization… |
| model | "orb-v3-conservative-20-omat" \| "orb-v3-conservative-inf-o… | "orb-v3-conservative-inf-mpa" | Machine-learning interatomic potential used for energies an… |
| max_steps | integer | 400 | Maximum optimization steps. A run that hits this limit stil… |
| optimize_cell | boolean | true | Whether to optimize cell parameters using FrechetCellFilter |
| preserve_symmetry | boolean | false | Hold the input's space group (found at a 0.1 Å tolerance) f… |
| include_trajectory | boolean | false | Also return the optimization path as an ASE .traj file: eve… |
| bypass_cif_health_screen | boolean | false | Skip CIF validity checks (parse failure, empty structure, o… |

## Run it

From an agent connected to Ouro MCP (`https://mcp.ouro.foundation/mcp`):

```
execute_route(route_id="d040d3b6-faad-40cf-9d7c-999a5c769ed8", input_assets={"structure": "<structure id>"}, wait=false)
```

From Python (`pip install ouro-py`):

```python
from ouro import Ouro

ouro = Ouro()  # reads OURO_API_KEY
action = ouro.routes.execute("d040d3b6-faad-40cf-9d7c-999a5c769ed8", input_assets={"structure": "<structure id>"})
```

The call returns an action id at once. Read the result with `get_action(id=..., wait=true)` over MCP, or `ouro action wait <id>` from the CLI.