How to run this route from Python with the Ouro SDK.
API access requires an API key. Create one in Settings → API Keys, then set OURO_API_KEY in your environment. Install the SDK with pip install ouro-py.
POST /matra-genoa/generateParameters and request body schema for this route.
Exact composition to generate, e.g. Fe2O3 or LiFePO4. Whole-number amounts, up to 8 elements.
Range: 1 to 230
Optional international space-group number (1-230) to condition generation on. Leave empty to let the model choose.
Range: 1 to 256
How many structures to generate and relax before keeping the most stable. 1 returns a single relaxed structure; more candidates make a low-energy answer more likely and take longer.
triclinicmonoclinicorthorhombictetragonaltrigonalhexagonalcubicOptional crystal systems to restrict generation to. Matra-Genoa proposes space groups for each formula and only those in these systems are kept. Ignored when a space group is given.
Also save the ranking as an Ouro dataset with a chart (off by default; the ranking is always in the response).
Runs save these to Ouro. Read them by name from action.final_data.
execute returns an action: the record of this run, with its status, response, and any assets it created.
This route is long-running. Start it without waiting, then collect the result when it's done.
By default a failed run comes back as an action with status error. Pass raise_on_error=True to raise an exception instead.
Every run is saved as an action. List yours, or read the logs of a single run. See the Python SDK reference for everything an action carries.
import os
from ouro import Ouro
ouro = Ouro(api_key=os.environ.get("OURO_API_KEY"))
# The ID also works, and stays the same if the route is renamed: "952dd267-8771-480c-bebe-bbe119fd3946"
route = ouro.routes.retrieve("mmoderwell/generate-the-most-stable-crystal-structure-for-a-formula-with-matra-genoa")
action = route.execute(
body={
"formula": "Fe2O3",
},
)
print(action.status) # "success" or "error"
print(action.final_data)
# Assets the run created are keyed by output name
structure = action.final_data["structure"]
print(structure["id"])# Returns as soon as the run is accepted
action = route.execute(
body={
"formula": "Fe2O3",
},
wait=False,
)
print(action.id, action.status)
# Later, even from another process
action = ouro.routes.poll_action(str(action.id), poll_interval=5, timeout=1800)
print(action.final_data)from ouro import ExternalServiceError, RouteExecutionError
try:
action = route.execute(
body={
"formula": "Fe2O3",
},
raise_on_error=True,
)
except ExternalServiceError as exc:
# The API behind this route failed
print(exc.status_code, exc.retryable)
except RouteExecutionError as exc:
print(exc.action_id, exc.status, exc.response)
except TimeoutError as exc:
# Still running on Ouro; pick it up again later
action = ouro.routes.poll_action(exc.action_id, timeout=None)route = ouro.routes.retrieve("mmoderwell/generate-the-most-stable-crystal-structure-for-a-formula-with-matra-genoa")
# Your runs of this route
actions = route.read_actions()
for action in actions:
print(action.id, action.status, action.created_at)
# One run and its logs
action = ouro.routes.retrieve_action("your-action-id")
for entry in action.read_logs(chronological=True):
print(entry.level, entry.message)Part of service
Matra-Genoa
Generate crystal structures for an exact formula (e.g. Fe2O3) with the Matra-Genoa transformer, relax every candidate with ORB v3, and return the lowest-energy unique structure as a CIF. Set num_candidates to 1 for a single relaxed structure, or raise it (up to 256) for a better chance at the stable polymorph; the ranked candidates come back as a zip of CIFs, and with include_dataset as a dataset charting each one's energy above the best. Optionally fix the space group. Energies are ORB v3 estimates, not DFT. Runs take about 20 s to 3 min. Cite Matra-Genoa: De Breuck et al., npj Comput. Mater. 12, 60 (2026).
Execution
Usage
1 callView history