mat-db-mp

Files (23)

• SKILL.md
• README.md · examples/
• elasticity_query.sh · examples/elasticity/
• high_bulk_modulus.json · examples/elasticity/
• si_elasticity.json · examples/elasticity/
• mp-1143.cif · examples/get_structure/
• mp-149.cif · examples/get_structure/
• mp-149_Si.cif · examples/get_structure/
• mp-19017.cif · examples/get_structure/
• structure_retrieval.sh · examples/get_structure/
• fe2o3_magnetism.json · examples/magnetism/
• ferromagnetic_materials.json · examples/magnetism/
• magnetism_query.sh · examples/magnetism/
• li_s_stability.sh · examples/query_mp/
• li_s_stable.json · examples/query_mp/
• similar_si_carbon_only.json · examples/similarity/
• similar_to_si.json · examples/similarity/
• similarity_search.sh · examples/similarity/
• find_similar_structures.py · scripts/
• get_elasticity.py · scripts/
• get_magnetism.py · scripts/
• get_structure_by_id.py · scripts/
• query_mp.py · scripts/

SKILL.md (first lines)

# Materials Project Database Query

<!-- mcp-tools-note -->
> [!NOTE]
> Steps written `server.tool` are MCP tool calls: `base.search_materials_project_by_formula` is the `search_materials_project_by_formula`
> tool of the `base` server (`mcp__base__search_materials_project_by_formula`, or
> `mcp__plugin_atomistic-skills_base__search_materials_project_by_formula` when installed as a plugin).
> Without a connected server, run the same tools from the shell. Tools named in
> one command share a process, so a model loaded by `load_model` stays loaded:
>
> ```bash
> ${CLAUDE_SKILL_DIR}/../../venv/run cpu python -m src.mcp_server.cli base search_materials_project_by_formula key=value search_materials_project_by_chemsys key=value
> ```

## 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](#mcp-tools-for-quick-retrieval) 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)**:
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/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)**:
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/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**:
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_elasticity.py \
    --material_id mp-149 \
    --output si_elasticity.json
```

**Filter by Bulk Modulus Range**:
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/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**:
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_magnetism.py \
    --material_id mp-19770 \
    --output fe2o3_magnetism.json
```

**Filter by Magnetic Ordering and Magnetization**:
```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/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**:
```bash

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills