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 /crystal-db/ehullParameters and request body schema for this route.
Range: 0 to 2
With include_phase_diagram, the highest energy above the hull (eV/atom, 0.0-2.0) of the unstable phases shown in the plot
orb-v3-conservative-inf-mpapbeEnergies the hull is built from. orb-v3-conservative-inf-mpa: every reference scored with Orb v3 (MPA), the same model that scores your structure, so systematic model errors largely cancel. pbe: the Materials Project and Alexandria PBE/PBE+U energies, with your structure scored by Orb v3; covers every published phase, but model error does not cancel. Both apply MP2020 corrections.
If false (default), reject inputs whose max force exceeds 0.05 eV/Å so e_above_hull is for the uploaded CIF. If true, relax it with Orb v3 first (the result then refers to the relaxed geometry, not the raw upload).
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.
Also save an interactive phase diagram of the chemical system as an Ouro file. Off by default: the energy above the hull, decomposition and formation energy are always in the response.
Include structures earlier submitted to Ouro in the hull. Only applies to MLIP surfaces.
Skip CIF validity checks (partial occupancies, overlapping atoms closer than 0.5 Å). Use only when you have already validated the structure.
Pass the ID of an Ouro asset for each of these in input_assets. Ouro loads the asset and sends it to the route.
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: "75fe7f4b-22f5-4883-aa1d-378fd42da47c"
route = ouro.routes.retrieve("mmoderwell/calculate-energy-above-the-convex-hull")
action = route.execute(
body={
"energy_cutoff": 0.5,
"energy_surface": "orb-v3-conservative-inf-mpa",
"allow_unrelaxed": False,
"include_generated_p1": False,
"include_phase_diagram": False,
"include_user_materials": True,
"bypass_cif_health_screen": False,
},
input_assets={
"structure": "your-file-id",
},
)
print(action.status) # "success" or "error"
print(action.final_data)# Returns as soon as the run is accepted
action = route.execute(
body={
"energy_cutoff": 0.5,
"energy_surface": "orb-v3-conservative-inf-mpa",
"allow_unrelaxed": False,
"include_generated_p1": False,
"include_phase_diagram": False,
"include_user_materials": True,
"bypass_cif_health_screen": False,
},
input_assets={
"structure": "your-file-id",
},
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={
"energy_cutoff": 0.5,
"energy_surface": "orb-v3-conservative-inf-mpa",
"allow_unrelaxed": False,
"include_generated_p1": False,
"include_phase_diagram": False,
"include_user_materials": True,
"bypass_cif_health_screen": False,
},
input_assets={
"structure": "your-file-id",
},
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/calculate-energy-above-the-convex-hull")
# 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
Crystal DB
Assess the thermodynamic stability of a crystal structure by computing its energy above the convex hull of every structure in Ouro's crystal database: Materials Project, Alexandria and GNoME phases, structures generated on Ouro, and structures submitted earlier. Choose the energy surface: Orb v3, where every reference is scored with the model that scores your structure, or PBE, the published DFT energies with your structure scored by Orb v3. MP2020 corrections are applied on both. Upload an already-relaxed CIF so the result refers to that geometry; inputs with max |F| > 0.05 eV/Å are rejected unless allow_unrelaxed is set (which relaxes with Orb v3 first). A structure the database does not have yet is added to it. Also rejects overlapping-atom CIFs unless bypass_cif_health_screen is set. Returns e_above_hull (eV/atom), decomposition products and formation energy; set include_phase_diagram for an interactive phase diagram too.
Execution
Usage
8573 callsView history