hello-qm/catgo-lrg/fetch

Structure Fetching Skill

When to Use

Use this skill when the user wants to:

• Load a known crystal structure (e.g., "get TiO2 rutile")
• Search for materials by composition or elements
• Fetch a molecule by name or formula from PubChem
• Browse structures from OPTIMADE-compliant databases

Data Sources

MCP Tool Examples

Fetch a crystal by formula (Materials Project)

catgo_fetch(action: "crystal", formula: "TiO2", provider: "mp")

This loads the lowest-energy TiO2 structure from Materials Project directly into the viewer. The formula is automatically normalized for OPTIMADE (alphabetical element order: "O2Ti").

Fetch a specific structure by ID

catgo_fetch(action: "crystal", structure_id: "mp-2657", provider: "mp")

Search for structures (returns list, does not auto-load)

catgo_fetch(action: "search", formula: "Fe2O3", provider: "mp", limit: 10)

Returns a list of matching structures with IDs, space groups, and energies. The user then picks one to load:

catgo_fetch(action: "crystal", structure_id: "mp-19770", provider: "mp")

Search by elements (any compound containing these elements)

catgo_fetch(action: "search", elements: ["Ti", "O"], provider: "mp", limit: 5)

This finds all compounds containing Ti and O (TiO2, Ti2O3, SrTiO3, etc.).

Search across multiple providers

catgo_fetch(action: "search", formula: "BaTiO3", provider: "alexandria", limit: 5)

Fetch a molecule from PubChem

By name:

catgo_fetch(action: "molecule", query: "aspirin")

By formula:

catgo_fetch(action: "molecule", query: "C6H12O6")

By PubChem CID:

catgo_fetch(action: "molecule", cid: 2244)

Add a molecule to existing structure

To add a molecule into the current structure (e.g., adding an adsorbate above a surface), use catgo_structure instead:

catgo_structure(action: "add_molecule", query: "water", count: 1)

This fetches from PubChem and merges into the current viewer structure. For multiple copies (e.g., a water layer):

catgo_structure(action: "add_molecule", query: "water", count: 5, spacing: 2.8)

Workflow: Search -> Select -> Load -> Build

A typical session for setting up a catalysis calculation:

1. Search for the bulk crystal:

catgo_fetch(action: "search", formula: "RuO2", provider: "mp", limit: 5)

1. Load the desired polymorph:

catgo_fetch(action: "crystal", structure_id: "mp-825", provider: "mp")

1. Verify it loaded correctly:

catgo_view(action: "get_state")

1. Build a slab for surface chemistry:

catgo_structure(action: "slab", miller_index: [1, 1, 0],
                min_slab_size: 10.0, min_vacuum_size: 15.0)

1. Place an adsorbate:

catgo_structure(action: "add_molecule", query: "OH")

Formula Normalization

OPTIMADE requires formulas in alphabetical element order:

• User says "TiO2" -> query sends "O2Ti"
• User says "Fe2O3" -> query sends "Fe2O3" (already alphabetical)
• User says "H2O" -> query sends "H2O" (already alphabetical)

Unicode subscripts are automatically converted: TiO₂ -> TiO2.

The catgo_fetch tool handles this normalization internally. You do not need to manually reorder formulas.

Provider-Specific Notes

Materials Project (mp)

• Highest quality: structures are DFT-relaxed with standardized settings
• Has computed properties: band gap, formation energy, stability
• Preferred for common inorganic materials

Alexandria

• Largest database (~5M structures)
• Good for finding exotic compositions
• PBE and PBEsol relaxed

PubChem

• Molecules only (no periodic structures)
• 3D conformers from MMFF94 or experimental data
• Returns the first conformer; may not be the global minimum
• Always optimize the geometry after fetching for DFT work

Common Mistakes

• Searching with non-alphabetical formula on OPTIMADE (handled automatically)
• Expecting PubChem molecules to be DFT-optimized (they are not)
• Loading a crystal when a molecule is needed, or vice versa
• Not checking catgo_view(action: "get_state") after loading to confirm

the structure is correct