---
title: "Scout candidate elements with GGen"
description: "Screen candidate elements for a substitution template such as Fe-Bi-{X}. GGen runs shallow relaxations for each substituted chemical system and scores which elements produce near-hull or target-symmetry structures. Returns a summary file with the ranked systems, the closest-to-hull CIF, and a zip of"
url: "https://ouro.foundation/routes/mmoderwell/scout-candidate-elements-with-ggen"
id: "4623c347-ec8b-4516-81eb-c989cbf5c940"
type: "route"
---

# Scout candidate elements with GGen

Route by @mmoderwell in #materials-science (all) · runs in the background · $0.0012/s (about $0.072/min), held up front and settled on actual runtime · typical run ~8 min

- Asset id: `4623c347-ec8b-4516-81eb-c989cbf5c940`
- Page: https://ouro.foundation/routes/mmoderwell/scout-candidate-elements-with-ggen

Screen candidate elements for a substitution template such as Fe-Bi-{X}. GGen runs shallow relaxations for each substituted chemical system and scores which elements produce near-hull or target-symmetry structures. Returns a summary file with the ranked systems, the closest-to-hull CIF, and a zip of the retained near-hull CIFs. Set include_dataset to also save the ranking as a dataset charted by score. Set include_report to also get an Ouro post that writes the scan up with those files embedded. Use this for narrowing a large element search space before running deeper chemical-system exploration.

## Inputs

- No input assets: the body below is the whole request.

## Body parameters

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

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| seed | integer \| null |  | Random seed for reproducibility |
| group | "3d_metals" \| "4d_metals" \| "5d_metals" \| "alkali" \| "a… |  | Named candidate element group |
| exclude | string[] \| null |  | Candidate elements to exclude |
| elements | string[] \| null |  | Explicit candidate elements to scan |
| **template** (required) | string |  | Chemical system template with {X}, for example 'Fe-Bi-{X}' |
| max_atoms | integer | 12 | Largest unit cell size to consider during each scout scan |
| max_steps | integer | 400 | Maximum relaxation steps per generated structure |
| min_atoms | integer | 2 | Smallest unit cell size to consider during each scout scan |
| e_above_hull | number | 0.15 | Near-hull cutoff in eV/atom used for scout scoring |
| max_fraction | object \| null |  | Maximum element fractions, for example {'Bi': 0.2} |
| min_fraction | object \| null |  | Minimum element fractions, for example {'Fe': 0.4} |
| include_report | boolean | false | Also write the scan up as an Ouro post with the output file… |
| shallow_trials | integer | 5 | Controls scout depth by setting trials per stoichiometry fo… |
| crystal_systems | string[] \| null |  | Target crystal systems used for scoring |
| include_dataset | boolean | false | Also save the ranking as an Ouro dataset with a chart (off… |
| relax_optimizer | "fire" \| "lbfgs" | "fire" | Optimizer used for geometry relaxation |
| max_stoichiometries | integer \| null | 50 | Controls scout breadth by limiting stoichiometries explored… |

## Run it

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

```
execute_route(route_id="4623c347-ec8b-4516-81eb-c989cbf5c940", body={"template":"..."}, wait=false)
```

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

```python
from ouro import Ouro

ouro = Ouro()  # reads OURO_API_KEY
action = ouro.routes.execute("4623c347-ec8b-4516-81eb-c989cbf5c940", body={"template":"..."})
```

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.
