| name | structure-builder |
| description | Use when the user asks to load, fetch, build, modify, or transform crystal/molecular structures. Covers database import, supercell, defects, doping, intercalation, nanotubes, and atom-level editing.
|
Structure Builder
Loading Structures
From Online Databases
catgo_fetch_crystal — Load crystal by formula or structure_id from OPTIMADE providers
(mp=Materials Project, mc3d, alexandria, twodmatpedia, omdb)catgo_search_crystals — Search and list multiple matches. Use this first when browsing,
then catgo_fetch_crystal with a specific structure_id.catgo_fetch_molecule — Fetch molecules from PubChem by name, formula, or SMILES.
Provider heuristics:
- General inorganic crystals:
mp (largest database)
- 2D materials:
twodmatpedia
- Organic molecules: use
catgo_fetch_molecule, not OPTIMADE
From Current Viewer
Call catgo_structure_info to inspect the loaded structure. All structure-modifying tools
auto-fetch the current viewer structure — no need to pass structure dicts.
Atom-Level Operations
| Tool | Use When |
|---|
catgo_add_atom / catgo_add_atoms | Adding atoms at Cartesian positions (Angstroms) |
catgo_delete_atoms | Removing atoms by 0-based index |
catgo_replace_atom | Changing element at a site |
catgo_move_atom / catgo_move_atoms | Repositioning atoms |
Lattice and Cell Operations
| Tool | Use When |
|---|
catgo_supercell | Expanding unit cell by [na, nb, nc] or 3x3 matrix |
catgo_set_lattice | Adding/changing periodic cell (wraps molecules in a box) |
catgo_merge | Combining two structures at a given position |
Defect Engineering
| Tool | Use When |
|---|
catgo_build_defect | Point defects: vacancy, substitution, interstitial |
catgo_doping | Substitutional doping (replace host with dopant) |
catgo_substitution | Combinatorial multi-site substitution |
catgo_intercalation | Insert species (Li, Na) into layered structures |
catgo_build_strain | Apply strain/deformation (Voigt notation or 3x3 matrix) |
Nanostructures
| Tool | Use When |
|---|
catgo_nanotube_build | Carbon or BN nanotubes from chiral indices (n, m) |
catgo_nanotube_info | Compute nanotube geometry before building |
Common Recipes
Doped supercell
catgo_fetch_crystal → 2. catgo_supercell → 3. catgo_doping → 4. catgo_structure_info
Defective structure for DFT
- Fetch bulk → 2.
catgo_supercell (large enough to avoid defect-defect interaction) →
catgo_build_defect → 4. catgo_structure_info
Intercalated battery material
catgo_fetch_crystal (e.g. MoS2) → 2. catgo_intercalation (species="Li") → 3. Verify
