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/exploreParameters and request body schema for this route.
Chemical system to explore, e.g. Li-Co-O or Fe-Mn-Si (up to 6 elements).
Range: 2 to 48
Largest unit cell to keep. Also bounds the formulas explored: only formula units with at most this many atoms.
Range: 1 to 230
Optional space-group number (1-230) to condition every formula on. Formulas the model can't write in it yield nothing.
Range: 0 to 1
Near-hull cutoff in eV/atom: phases within it are labeled for novelty and drawn in the phase diagram.
Maximum atomic fraction per element, e.g. {"O": 0.6}.
Minimum atomic fraction per element, e.g. {"Fe": 0.4}.
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 phases as an Ouro dataset with a chart (off by default; the phases are always in the response summary).
Range: 1 to 200
Search breadth: how many formulas to explore, smallest formula units first. Stoichiometries x candidates may be at most 2,048.
Also put generated (GGen, Matra-Genoa) structures in space group P1 on the hull. Off by default: they are mostly symmetry-broken leftovers. Published P1 phases are always included.
Only explore formulas containing every element of the system.
Range: 1 to 64
Search depth: structures generated and relaxed for each formula. The lowest-energy ones go on the hull.
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: "522a9b9f-d2a9-4522-9647-d6a2066c6150"
route = ouro.routes.retrieve("mmoderwell/explore-a-chemical-system-with-matra-genoa-and-build-its-phase-diagram")
action = route.execute(
body={
"system": "Li-Co-O",
},
)
print(action.status) # "success" or "error"
print(action.final_data)
# Assets the run created are keyed by output name
phase_diagram = action.final_data["phase_diagram"]
print(phase_diagram["id"])# Returns as soon as the run is accepted
action = route.execute(
body={
"system": "Li-Co-O",
},
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={
"system": "Li-Co-O",
},
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/explore-a-chemical-system-with-matra-genoa-and-build-its-phase-diagram")
# 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
Explore a chemical system such as Li-Co-O: Matra-Genoa generates candidates for each stoichiometry (smallest formula units first), ORB v3 relaxes them, and they are ranked by energy above the convex hull of Ouro's shared structure database, which keeps them for later runs. Returns the phase diagram of the whole system, the leading structure, and a zip of the best structure per formula with hull distances and novelty (with include_dataset, also a dataset charted by hull distance). Restrict the search by space group, crystal systems or element fractions. For one exact formula, use Generate the most stable crystal structure for a formula with Matra-Genoa instead. Runs take a few minutes to about 25 min. Cite Matra-Genoa: De Breuck et al., npj Comput. Mater. 12, 60 (2026).
Execution
Usage
6 callsView history