Materials Project Database Query

Goal

To retrieve crystal structures and computed properties from the Materials Project database, enabling efficient materials discovery and property analysis. This skill provides access to:

• Basic material properties (energy above hull, formation energy, band gap)
• Elastic properties (bulk modulus, shear modulus, elastic tensors)
• Magnetic properties (magnetic ordering, magnetization, site moments)
• Structure similarity search (CrystalNN-based fingerprinting)

Note: For quick structure retrieval by formula or chemical system, MCP tools are also available (see MCP Tools section).

Instructions

1. Query Materials by Chemical System or Formula

Use query_mp.py to search for materials by chemical system, formula, or elements with property filtering.

Basic Query (Summary Endpoint):

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/query_mp.py \
    --chemsys "Li-S" \
    --properties energy_above_hull formation_energy_per_atom band_gap \
    --e_above_hull_max 0.05 \
    --limit 10 \
    --endpoint summary \
    --output stable_li_s_materials.json

Detailed Thermodynamic Data (Thermo Endpoint):

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/query_mp.py \
    --chemsys "Li-O" \
    --endpoint thermo \
    --limit 20 \
    --output li_o_thermo.json

Key Parameters:

• --chemsys: Chemical system (e.g., "Li-S", "Si-O")
• --formula: Specific chemical formula (e.g., "LiFePO4")
• --elements: List of elements that must be present
• --properties: Properties to retrieve (default: energy_above_hull, formation_energy_per_atom)
• --e_above_hull_max: Maximum energy above hull for stability filtering (eV/atom)
• --endpoint: Choose summary (includes structures) or thermo (detailed thermodynamics, no structures)
• --limit: Maximum number of results to retrieve

Output: JSON file containing material IDs, formulas, CIF strings (summary endpoint), and requested properties.

2. Query Elastic Properties

Use get_elasticity.py to retrieve bulk modulus, shear modulus, and elastic tensor data.

Query Specific Material:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/get_elasticity.py \
    --material_id mp-149 \
    --output si_elasticity.json

Filter by Bulk Modulus Range:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/get_elasticity.py \
    --bulk_modulus_min 200 \
    --bulk_modulus_max 400 \
    --output high_bulk_modulus.json

Key Parameters:

• --material_id: Specific MP ID(s) to query
• --bulk_modulus_min/max: Bulk modulus (VRH) range in GPa
• --shear_modulus_min/max: Shear modulus (VRH) range in GPa

Output: JSON file with bulk modulus, shear modulus (Voigt, Reuss, VRH averages), and full elastic tensor.

3. Query Magnetic Properties

Use get_magnetism.py to retrieve magnetic ordering, magnetization, and site-specific magnetic moments.

Query Specific Material:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/get_magnetism.py \
    --material_id mp-19770 \
    --output fe2o3_magnetism.json

Filter by Magnetic Ordering and Magnetization:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/get_magnetism.py \
    --ordering FM \
    --total_magnetization_min 10.0 \
    --output ferromagnetic_materials.json

Key Parameters:

• --material_id: Specific MP ID(s) to query
• --ordering: Magnetic ordering type (FM, AFM, FiM, NM)
• --total_magnetization_min/max: Total magnetization range in μB

Output: JSON file with magnetic ordering, total magnetization, and per-site magnetic moments.

4. Retrieve Structures by Material ID

Use get_structure_by_id.py to retrieve crystal structures directly by their Materials Project ID.

Single Structure Retrieval:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/get_structure_by_id.py mp-149 \
    --output Si_diamond.cif

Batch Retrieval:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/get_structure_by_id.py \
    mp-149 mp-19017 mp-1143 \
    --output_dir structures/

Key Parameters:

• material_ids: One or more MP IDs to retrieve
• --output: Output path for single material ID (CIF format)
• --output_dir: Output directory for batch retrieval
• --api_key: Optional API key (uses MP_API_KEY env var by default)

Output: CIF file(s) containing the crystal structure(s).

5. Find Structurally Similar Materials

Use find_similar_structures.py to find materials with similar crystal structures based on CrystalNN fingerprinting.

Find Similar to MP Material:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/find_similar_structures.py \
    --material_id mp-149 \
    --top 15 \
    --output similar_to_si.json

Find Similar to Custom Structure:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/find_similar_structures.py \
    --structure my_structure.cif \
    --top 20 \
    --output similar_structures.json

Filter by Chemical System:

# Env: base-agent
python .agents/skills/mat-db-mp/scripts/find_similar_structures.py \
    --material_id mp-149 \
    --top 20 \
    --chemsys "C" \
    --output carbon_structures_like_si.json

Key Parameters:

• --material_id: MP ID to use as query structure
• --structure: Path to custom structure file (CIF, POSCAR, etc.)
• --top: Number of most similar structures to return (default: 50)
• --chemsys: Optional post-filter by exact chemical system match

Similarity Algorithm: Uses CrystalNN to compute local coordination fingerprints, aggregates them into structure fingerprints, and ranks by Euclidean distance in fingerprint space. Dissimilarity score: 100 * (1 - exp(-distance)), where 0% = identical and 100% = maximally different.

Output: JSON file with similar material IDs, formulas, and dissimilarity scores (0-100%).

Examples

See the examples/ directory for complete working examples:

Basic Queries (examples/query_mp/):

cd .agents/skills/mat-db-mp
bash examples/query_mp/li_s_stability.sh
# Output: Retrieves 2 stable Li-S materials (E_hull < 0.05 eV/atom)

Elastic Properties (examples/elasticity/):

cd .agents/skills/mat-db-mp
bash examples/elasticity/elasticity_query.sh
# Output: Si elastic data + 1387 materials with K=200-400 GPa

Magnetic Properties (examples/magnetism/):

cd .agents/skills/mat-db-mp
bash examples/magnetism/magnetism_query.sh
# Output: Fe2O3 magnetic data + 23,121 ferromagnetic materials

Structure Similarity (examples/similarity/):

cd .agents/skills/mat-db-mp
bash examples/similarity/similarity_search.sh
# Output: 15 structures similar to Si (mp-149)

Structure Retrieval (examples/get_structure/):

cd .agents/skills/mat-db-mp
bash examples/get_structure/structure_retrieval.sh
# Output: CIF files for Si, LiFePO4, and Fe2O3

MCP Tools for Quick Retrieval

For simple structure retrieval tasks, MCP tools provide a convenient alternative to running scripts:

Retrieve Most Stable Structure by Formula

mcp_base_search_materials_project_by_formula(
    formula="LiFePO4",          # Chemical formula
    save_to_file="lifepo4.cif"  # Optional: save path (default: auto-generated)
)

Returns only the single most stable structure (lowest energy above hull) matching the formula. If multiple polymorphs exist, only ONE is returned.

Retrieve All Stable Structures by Chemical System

mcp_base_search_materials_project_by_chemsys(
    chemsys="Li-O",                    # Chemical system
    save_to_file="LiO_structures"      # Optional: directory path (default: {chemsys}_structures)
)

Returns all stable structures on the convex hull (E_hull = 0) in the specified chemical system. Structures are saved to individual CIF files in a directory.

Output: Directory containing CIF files for each hull structure, named {mp-id}_{formula}.cif. Each structure includes metadata (material_id, formula, energy_above_hull) in the atoms.info dict.

Example Output:

Found 3 structures on convex hull for Li-O
Saved to directory: /path/to/LiO_structures

Structures:
  - mp-1960: Li2O (E_hull=0.000000 eV/atom)
  - mp-12958: Li2O2 (E_hull=0.000000 eV/atom)
  - mp-841: LiO2 (E_hull=0.000000 eV/atom)

When to Use MCP Tools vs Scripts

Use MCP Tools when:

• Formula search: Need the single most stable polymorph quickly
• Chemical system search: Need all stable phases on the convex hull
• Working from Python/Jupyter notebooks
• Simple queries without complex property filtering
• Exploring phase diagrams (chemsys tool returns all hull phases)

Use Scripts when:

• Querying structures with specific property filters (e.g., bandgap > 2 eV)
• Need detailed properties (elasticity, magnetism, formation energy)
• Batch processing with custom criteria
• Generating datasets for ML training
• Advanced queries (similarity search, property ranges, metastable structures)

Constraints

• API Key: Requires Materials Project API key set in MP_API_KEY environment variable
• Environment: All scripts require the base-agent conda environment
• MP-API Version: Similarity search requires mp-api >= 0.46.0 with find_similar method
• Python Version: Base-agent uses Python 3.11
• Rate Limits: Materials Project API has rate limits; large queries may be throttled
• Endpoint Differences:
  • summary endpoint includes crystal structures (CIF format)
  • thermo endpoint provides detailed thermodynamic data but no structures
• Similarity Chemical Filter: The --chemsys parameter in similarity search performs post-filtering for exact element matches, not compositional similarity
• Large Result Sets: Queries returning >1000 materials may take several minutes to complete

API Endpoints

• Summary (mpr.materials.summary): General material data with structures
• Thermo (mpr.materials.thermo): Detailed thermodynamic properties
• Elasticity (mpr.materials.elasticity): Elastic modulus and tensor data
• Magnetism (mpr.materials.magnetism): Magnetic ordering and moments
• Similarity (mpr.materials.similarity): CrystalNN-based structure matching

---

Author: Bowen Deng Contact: GitHub @learningmatter-mit