agent-materials-science 0.2.1__tar.gz

agent_materials_science-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Raghavendra Meena
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_materials_science-0.2.1/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: agent-materials-science
+Version: 0.2.1
+Summary: A Python agent for automated materials science workflows, focusing on surface adsorption analysis
+Author-email: Raghavendra Meena <raghavendra.ip2020@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/raghavendram3/agent_materials_science
+Project-URL: Repository, https://github.com/raghavendram3/agent_materials_science
+Project-URL: Issues, https://github.com/raghavendram3/agent_materials_science/issues
+Keywords: materials-science,computational-chemistry,adsorption,DFT,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mp-api>=0.45
+Requires-Dist: pymatgen>=2024.11.13
+Requires-Dist: ase>=3.26.0
+Requires-Dist: numpy<2.5,>=2.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: ml
+Requires-Dist: fairchem-core>=2.21.0; extra == "ml"
+Provides-Extra: adsorbml
+Requires-Dist: fairchem-core[adsorbml]>=2.21.0; extra == "adsorbml"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Materials Science Adsorption Agent
+![MSA](https://raw.githubusercontent.com/raghavendram3/agent_materials_science/main/ML_ads.png)
+A Python agent for automated materials science workflows, focusing on surface adsorption analysis using Materials Project data, ASE/pymatgen tools, and FairChem UMA machine learning potentials.
+
+## Features
+
+1. **Materials Project Integration**: Retrieve crystal structures using MP API
+2. **Structure Conversion**: Convert pymatgen structures to ASE Atoms objects
+3. **Surface Cleaving**: Generate surface slabs with user-specified Miller indices and terminations
+4. **Adsorbate Selection**: Choose from common adsorbates (H, O, CO, OH, N, etc.)
+5. **Adsorption Site Analysis**: Find optimal adsorption sites using pymatgen algorithms
+6. **ML-Accelerated DFT**: Calculate adsorption energies using FairChem UMA models
+7. **Results Export**: Generate CIF files and comprehensive JSON reports
+
+## Installation
+
+Requires **Python 3.11–3.13** (driven by fairchem-core 2.x).
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or: venv\Scripts\activate  # Windows
+
+# Install from PyPI (after release)
+pip install agent-materials-science
+
+# Install the package (geometry workflow: slabs + adsorption sites)
+pip install .
+
+# Optional: ML adsorption energies (installs torch ~=2.8, large download)
+pip install ".[ml]"
+
+# Optional: AdsorbML production workflows
+pip install ".[adsorbml]"
+
+# Set up Materials Project API key
+export MP_API_KEY="your_api_key_here"
+# Or create a .env file with: MP_API_KEY=your_api_key_here
+```
+
+UMA checkpoints are gated on Hugging Face: request access to
+[facebook/UMA](https://huggingface.co/facebook/UMA) and run
+`huggingface-cli login` once.
+
+## Releasing to PyPI
+
+```bash
+# Build source and wheel distributions
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+
+# Upload to TestPyPI (recommended first)
+python -m twine upload --repository testpypi dist/*
+
+# Upload to PyPI
+python -m twine upload dist/*
+```
+
+## Quick Start
+
+### Command Line Interface
+
+```bash
+# Basic usage - analyze silicon (111) surface with H adsorbate
+python -m agent_materials_science.cli --material Si --miller 1,1,1 --adsorbate H
+
+# Using Materials Project ID
+python -m agent_materials_science.cli --mp-id mp-149 --miller 1,1,0 --adsorbate CO
+
+# Full workflow with relaxed energy calculations
+agent-materials-science \
+    --material SrTiO3 \
+    --miller 1,0,0 \
+    --adsorbate O \
+    --layers 6 \
+    --vacuum 15 \
+    --supercell 2,2 \
+    --calculate-energies \
+    --relax --fix-layers 2 \
+    --device auto \
+    --output-dir outputs/srtio3_analysis
+```
+
+The `agent-materials-science` console script is installed with the package;
+`python -m agent_materials_science.cli` works too.
+
+### Python API
+
+```python
+from agent_materials_science import MaterialsScienceAgent, AgentConfig
+
+# Create agent configuration
+config = AgentConfig(
+    material="Si",
+    miller_indices=(1, 1, 1),
+    adsorbate="H",
+    n_layers=6,
+    vacuum=15.0,
+    supercell=(2, 2),
+    calculate_energies=True,
+    output_dir="outputs"
+)
+
+# Run agent
+agent = MaterialsScienceAgent(config)
+result = agent.run()
+
+# Access results
+print(f"Material: {result.formula} ({result.material_id})")
+print(f"Best adsorption site: {result.best_site}")
+print(f"Output files: {result.output_files}")
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MP_API_KEY` | Materials Project API key | Required |
+| `FAIRCHEM_MODEL` | FairChem model name | `uma-s-1p2` |
+| `FAIRCHEM_TASK` | UMA task head (`oc20`, `omat`, `omol`, …) | `oc20` |
+| `FAIRCHEM_DEVICE` | Device: `auto`, `cpu`, `cuda` | `auto` |
+
+Explicit constructor/CLI arguments always take precedence over environment
+variables.
+
+### Supported Adsorbates
+
+27 species, including atoms (H, O, N, C, S, F, Cl), diatomics (H2, O2, N2,
+CO/OC, OH/HO, NO/ON, HF, HCl) and molecules (H2O, CO2, N2O, NH3, CH4, C2H2,
+C2H4, HCOO, CH3OH). Run `agent-materials-science --list-adsorbates` for the
+authoritative list with descriptions.
+
+### FairChem Models
+
+UMA models require **FairChem v2** and a Hugging Face account with access
+granted to the UMA model repository (`huggingface-cli login`).
+
+- `uma-s-1p2` - UMA small v1.2 (latest small model; recommended, default)
+- `uma-s-1p1` - UMA small v1.1
+- `uma-m-1p1` - UMA medium v1.1 (higher accuracy, slower)
+- `esen-*` - eSEN models
+
+> `uma-s-1` was **removed** from the FairChem registry and can no longer be
+> downloaded. Run `agent-materials-science --list-models` to query the live
+> registry when fairchem-core is installed. A local checkpoint file path can
+> be passed via `--model /path/to/checkpoint.pt`.
+
+Pick the **task head** to match the problem: `oc20` for surface adsorption /
+catalysis (the default here), `omat` for bulk inorganic materials, `omol` for
+isolated molecules. Mixing task heads between the slab and the reference makes
+adsorption energies meaningless.
+
+### Adsorption-site backend
+
+Site finding uses **pymatgen's `AdsorbateSiteFinder`** when pymatgen is
+installed (`--site-finder auto`, the default). It is symmetry-aware, so it
+returns only the distinct sites and avoids redundant energy evaluations. A
+self-contained, periodicity-correct geometric finder is used as a fallback
+(`--site-finder builtin`). Pass `--no-symm-reduce` to keep every site.
+
+## Project Structure
+
+```
+agent_materials_science/
+├── __init__.py           # Package exports
+├── agent.py              # Main agent orchestration
+├── cli.py                # Command line interface
+├── config.py             # Configuration management
+├── core/
+│   ├── __init__.py
+│   ├── adsorption.py     # Adsorption site finding
+│   ├── surface.py        # Surface/slab generation
+│   └── workflow.py       # Workflow orchestration
+├── tools/
+│   ├── __init__.py
+│   ├── materials_project.py  # MP API wrapper
+│   ├── ase_tools.py      # ASE utilities
+│   ├── fairchem_calc.py  # FairChem calculator
+│   └── converters.py     # Structure converters
+├── outputs/              # Default output directory
+├── requirements.txt
+└── README.md
+```
+
+## Output Files
+
+The agent generates the following output files:
+
+- `{material_id}_slab_{hkl}.cif` - Clean slab structure
+- `{material_id}_slab_{hkl}.vasp` - VASP POSCAR format
+- `{material_id}_sites.json` - Adsorption sites data
+- `{material_id}_best_site.cif` - Structure with adsorbate at best site
+- `{material_id}_results.json` - Complete analysis results
+
+## Methodology notes & limitations
+
+- **Adsorption-energy convention.** `E_ads = E(slab+ads) − E(slab) −
+  E_gas(ads)`, where `E_gas` follows the **OC20 convention**: a linear
+  combination of per-element reference energies (H −3.477, C −7.282,
+  O −7.204, N −8.083 eV, from the OC20 paper) that pairs consistently with
+  UMA `oc20` total energies — this is the scheme recommended by the FairChem
+  documentation. Adsorbates containing other elements fall back to relative
+  energies (site ranking is still valid) unless you provide per-element
+  overrides via `get_adsorbate_reference_energy(..., overrides=...)`.
+- **Consistent relaxation.** With `--relax`, the clean slab is relaxed once
+  (before site finding) and each slab+adsorbate system is relaxed, so both
+  totals in `E_ads` come from relaxed geometries. Use `--fix-layers 2` (or
+  more) to hold the bottom layers bulk-like during relaxations.
+- **ML accuracy.** Energies come from a machine-learned potential (UMA);
+  expect ~0.1 eV-scale deviations from explicit DFT depending on the system.
+- **Single initial placement per site.** Each site is evaluated from one
+  initial geometry (optionally relaxed). The state-of-the-art recipe is
+  [AdsorbML](https://www.nature.com/articles/s41524-023-01121-5): generate many
+  initial configurations, ML-relax each, and take the minimum — available via
+  `pip install "fairchem-core[adsorbml]"` (or higher-level libraries such as
+  [`quacc`](https://quacc.readthedocs.io) `slab_to_ads_flow` and `atomate2`)
+  for production studies.
+- **Surface-normal assumption.** Site finding assumes the surface lies in the
+  xy-plane with vacuum along z (the convention produced by the slab builder).
+
+## License
+
+MIT License

agent_materials_science-0.2.1/README.md

@@ -0,0 +1,227 @@
+# Materials Science Adsorption Agent
+![MSA](https://raw.githubusercontent.com/raghavendram3/agent_materials_science/main/ML_ads.png)
+A Python agent for automated materials science workflows, focusing on surface adsorption analysis using Materials Project data, ASE/pymatgen tools, and FairChem UMA machine learning potentials.
+
+## Features
+
+1. **Materials Project Integration**: Retrieve crystal structures using MP API
+2. **Structure Conversion**: Convert pymatgen structures to ASE Atoms objects
+3. **Surface Cleaving**: Generate surface slabs with user-specified Miller indices and terminations
+4. **Adsorbate Selection**: Choose from common adsorbates (H, O, CO, OH, N, etc.)
+5. **Adsorption Site Analysis**: Find optimal adsorption sites using pymatgen algorithms
+6. **ML-Accelerated DFT**: Calculate adsorption energies using FairChem UMA models
+7. **Results Export**: Generate CIF files and comprehensive JSON reports
+
+## Installation
+
+Requires **Python 3.11–3.13** (driven by fairchem-core 2.x).
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or: venv\Scripts\activate  # Windows
+
+# Install from PyPI (after release)
+pip install agent-materials-science
+
+# Install the package (geometry workflow: slabs + adsorption sites)
+pip install .
+
+# Optional: ML adsorption energies (installs torch ~=2.8, large download)
+pip install ".[ml]"
+
+# Optional: AdsorbML production workflows
+pip install ".[adsorbml]"
+
+# Set up Materials Project API key
+export MP_API_KEY="your_api_key_here"
+# Or create a .env file with: MP_API_KEY=your_api_key_here
+```
+
+UMA checkpoints are gated on Hugging Face: request access to
+[facebook/UMA](https://huggingface.co/facebook/UMA) and run
+`huggingface-cli login` once.
+
+## Releasing to PyPI
+
+```bash
+# Build source and wheel distributions
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+
+# Upload to TestPyPI (recommended first)
+python -m twine upload --repository testpypi dist/*
+
+# Upload to PyPI
+python -m twine upload dist/*
+```
+
+## Quick Start
+
+### Command Line Interface
+
+```bash
+# Basic usage - analyze silicon (111) surface with H adsorbate
+python -m agent_materials_science.cli --material Si --miller 1,1,1 --adsorbate H
+
+# Using Materials Project ID
+python -m agent_materials_science.cli --mp-id mp-149 --miller 1,1,0 --adsorbate CO
+
+# Full workflow with relaxed energy calculations
+agent-materials-science \
+    --material SrTiO3 \
+    --miller 1,0,0 \
+    --adsorbate O \
+    --layers 6 \
+    --vacuum 15 \
+    --supercell 2,2 \
+    --calculate-energies \
+    --relax --fix-layers 2 \
+    --device auto \
+    --output-dir outputs/srtio3_analysis
+```
+
+The `agent-materials-science` console script is installed with the package;
+`python -m agent_materials_science.cli` works too.
+
+### Python API
+
+```python
+from agent_materials_science import MaterialsScienceAgent, AgentConfig
+
+# Create agent configuration
+config = AgentConfig(
+    material="Si",
+    miller_indices=(1, 1, 1),
+    adsorbate="H",
+    n_layers=6,
+    vacuum=15.0,
+    supercell=(2, 2),
+    calculate_energies=True,
+    output_dir="outputs"
+)
+
+# Run agent
+agent = MaterialsScienceAgent(config)
+result = agent.run()
+
+# Access results
+print(f"Material: {result.formula} ({result.material_id})")
+print(f"Best adsorption site: {result.best_site}")
+print(f"Output files: {result.output_files}")
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MP_API_KEY` | Materials Project API key | Required |
+| `FAIRCHEM_MODEL` | FairChem model name | `uma-s-1p2` |
+| `FAIRCHEM_TASK` | UMA task head (`oc20`, `omat`, `omol`, …) | `oc20` |
+| `FAIRCHEM_DEVICE` | Device: `auto`, `cpu`, `cuda` | `auto` |
+
+Explicit constructor/CLI arguments always take precedence over environment
+variables.
+
+### Supported Adsorbates
+
+27 species, including atoms (H, O, N, C, S, F, Cl), diatomics (H2, O2, N2,
+CO/OC, OH/HO, NO/ON, HF, HCl) and molecules (H2O, CO2, N2O, NH3, CH4, C2H2,
+C2H4, HCOO, CH3OH). Run `agent-materials-science --list-adsorbates` for the
+authoritative list with descriptions.
+
+### FairChem Models
+
+UMA models require **FairChem v2** and a Hugging Face account with access
+granted to the UMA model repository (`huggingface-cli login`).
+
+- `uma-s-1p2` - UMA small v1.2 (latest small model; recommended, default)
+- `uma-s-1p1` - UMA small v1.1
+- `uma-m-1p1` - UMA medium v1.1 (higher accuracy, slower)
+- `esen-*` - eSEN models
+
+> `uma-s-1` was **removed** from the FairChem registry and can no longer be
+> downloaded. Run `agent-materials-science --list-models` to query the live
+> registry when fairchem-core is installed. A local checkpoint file path can
+> be passed via `--model /path/to/checkpoint.pt`.
+
+Pick the **task head** to match the problem: `oc20` for surface adsorption /
+catalysis (the default here), `omat` for bulk inorganic materials, `omol` for
+isolated molecules. Mixing task heads between the slab and the reference makes
+adsorption energies meaningless.
+
+### Adsorption-site backend
+
+Site finding uses **pymatgen's `AdsorbateSiteFinder`** when pymatgen is
+installed (`--site-finder auto`, the default). It is symmetry-aware, so it
+returns only the distinct sites and avoids redundant energy evaluations. A
+self-contained, periodicity-correct geometric finder is used as a fallback
+(`--site-finder builtin`). Pass `--no-symm-reduce` to keep every site.
+
+## Project Structure
+
+```
+agent_materials_science/
+├── __init__.py           # Package exports
+├── agent.py              # Main agent orchestration
+├── cli.py                # Command line interface
+├── config.py             # Configuration management
+├── core/
+│   ├── __init__.py
+│   ├── adsorption.py     # Adsorption site finding
+│   ├── surface.py        # Surface/slab generation
+│   └── workflow.py       # Workflow orchestration
+├── tools/
+│   ├── __init__.py
+│   ├── materials_project.py  # MP API wrapper
+│   ├── ase_tools.py      # ASE utilities
+│   ├── fairchem_calc.py  # FairChem calculator
+│   └── converters.py     # Structure converters
+├── outputs/              # Default output directory
+├── requirements.txt
+└── README.md
+```
+
+## Output Files
+
+The agent generates the following output files:
+
+- `{material_id}_slab_{hkl}.cif` - Clean slab structure
+- `{material_id}_slab_{hkl}.vasp` - VASP POSCAR format
+- `{material_id}_sites.json` - Adsorption sites data
+- `{material_id}_best_site.cif` - Structure with adsorbate at best site
+- `{material_id}_results.json` - Complete analysis results
+
+## Methodology notes & limitations
+
+- **Adsorption-energy convention.** `E_ads = E(slab+ads) − E(slab) −
+  E_gas(ads)`, where `E_gas` follows the **OC20 convention**: a linear
+  combination of per-element reference energies (H −3.477, C −7.282,
+  O −7.204, N −8.083 eV, from the OC20 paper) that pairs consistently with
+  UMA `oc20` total energies — this is the scheme recommended by the FairChem
+  documentation. Adsorbates containing other elements fall back to relative
+  energies (site ranking is still valid) unless you provide per-element
+  overrides via `get_adsorbate_reference_energy(..., overrides=...)`.
+- **Consistent relaxation.** With `--relax`, the clean slab is relaxed once
+  (before site finding) and each slab+adsorbate system is relaxed, so both
+  totals in `E_ads` come from relaxed geometries. Use `--fix-layers 2` (or
+  more) to hold the bottom layers bulk-like during relaxations.
+- **ML accuracy.** Energies come from a machine-learned potential (UMA);
+  expect ~0.1 eV-scale deviations from explicit DFT depending on the system.
+- **Single initial placement per site.** Each site is evaluated from one
+  initial geometry (optionally relaxed). The state-of-the-art recipe is
+  [AdsorbML](https://www.nature.com/articles/s41524-023-01121-5): generate many
+  initial configurations, ML-relax each, and take the minimum — available via
+  `pip install "fairchem-core[adsorbml]"` (or higher-level libraries such as
+  [`quacc`](https://quacc.readthedocs.io) `slab_to_ads_flow` and `atomate2`)
+  for production studies.
+- **Surface-normal assumption.** Site finding assumes the surface lies in the
+  xy-plane with vacuum along z (the convention produced by the slab builder).
+
+## License
+
+MIT License

agent_materials_science-0.2.1/agent_materials_science/__init__.py

@@ -0,0 +1,26 @@
+"""
+Materials Science Adsorption Agent
+
+A Python agent for automated materials science workflows, focusing on
+surface adsorption analysis using Materials Project data, ASE/pymatgen 
+tools, and FairChem UMA machine learning potentials.
+"""
+
+from .config import AgentConfig
+from .agent import (
+    MaterialsScienceAgent,
+    AgentResult,
+    InteractiveAgent,
+    run_analysis,
+)
+
+__version__ = "0.2.1"
+__author__ = "Materials Science Agent"
+
+__all__ = [
+    "MaterialsScienceAgent",
+    "AgentConfig",
+    "AgentResult",
+    "InteractiveAgent",
+    "run_analysis",
+]

agent_materials_science-0.2.1/agent_materials_science/__main__.py

@@ -0,0 +1,12 @@
+"""
+Main entry point for running the agent as a module.
+
+Usage:
+    python -m agent_materials_science --material Si --miller 1,1,1 --adsorbate H
+"""
+
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())