Masgent

Masgent: Materials Simulation Agent

╔═════════════════════════════════════════════════════════════════════════╗
║                                                                         ║
║  ███╗   ███╗  █████╗  ███████╗  ██████╗  ███████╗ ███╗   ██╗ ████████╗  ║
║  ████╗ ████║ ██╔══██╗ ██╔════╝ ██╔════╝  ██╔════╝ ████╗  ██║ ╚══██╔══╝  ║
║  ██╔████╔██║ ███████║ ███████╗ ██║  ███╗ █████╗   ██╔██╗ ██║    ██║     ║
║  ██║╚██╔╝██║ ██╔══██║ ╚════██║ ██║   ██║ ██╔══╝   ██║╚██╗██║    ██║     ║
║  ██║ ╚═╝ ██║ ██║  ██║ ███████║ ╚██████╔╝ ███████╗ ██║ ╚████║    ██║     ║
║  ╚═╝     ╚═╝ ╚═╝  ╚═╝ ╚══════╝  ╚═════╝  ╚══════╝ ╚═╝  ╚═══╝    ╚═╝     ║
║                                                                         ║
║                                   MASGENT: Materials Simulation Agent   ║
║                                      Copyright (c) 2025 Guangchen Liu   ║
║                                                                         ║
║  License:       MIT License                                             ║
║  Citation:      Liu, G. et al. (2025). arXiv: 2512.23010                ║
║  DOI:           https://doi.org/10.48550/arXiv.2512.23010               ║
║  Repository:    https://github.com/aguang5241/Masgent                   ║
║  Contact:       gliu4@wpi.edu                                           ║
║                                                                         ║
╚═════════════════════════════════════════════════════════════════════════╝

🚀 Overview

Masgent is a materials simulation AI agent that streamlines DFT workflows and analysis, fast machine-learning-potential (MLP) simulations, and lightweight ML modeling for materials science. With automated tools for structure handling, VASP input generation, workflow preparation & analysis, and rapid property prediction, Masgent simplifies complex simulation tasks and boosts productivity for both researchers and students.

⭐️ Why Masgent?

Most materials-simulation tools—pymatgen, ASE, VASPkit, etc.—require manual scripting, multi-step workflows, and deep HPC expertise to run full DFT or ML-based simulations. Masgent removes that barrier by providing a unified, AI-driven interface for structure generation, workflow preparation, fast simulations, and analysis.

Masgent offers:

An AI-native simulation assistant that prepares VASP workflows, analyzes results, and answers technical questions through natural language.
Turn-key VASP workflow templates (Convergence Test, EOS, Elastic, AIMD, NEB) with built-in analysis tools.
Automatic generation of all VASP inputs — INCAR, KPOINTS, POTCAR, POSCAR, and HPC job scripts — with sensible defaults.
One-command structure operations, including defect creation, supercells, slabs, interfaces, and SQS generation.
Visualization of structures through interactive web-based viewers.
Fast machine-learning-potential simulations using SevenNet, CHGNet, Orb-v3, and MatSim for rapid EOS, elasticity, and MD.
Lightweight ML utilities for feature preparation, dimensionality reduction, data augmentation, hyperparameter tuning, and model training.

🤖 Supported AI Models

Provider	Model	API Key Required	Notes
Masgent	Masgent AI	❌ No	No API key needed, response may be slower on cold start
OpenAI	GPT-5 Nano	✅ Yes	Requires OpenAI API key
Anthropic	Claude Sonnet 4.5	✅ Yes	Requires Anthropic API key
Google	Gemini 2.5 Flash	✅ Yes	Requires Google API key
xAI	Grok 4.1 Fast	✅ Yes	Requires Grok (xAI) API key
DeepSeek	DeepSeek Chat	✅ Yes	Requires DeepSeek API key
Alibaba	Qwen Flash	✅ Yes	Requires Alibaba Cloud API key

🧩 Features

Density Functional Theory (DFT) Simulations

1.1 Structure Preparation & Manipulation
- 1.1.1 Generate POSCAR from chemical formula
- 1.1.2 Convert POSCAR coordinates (Direct <-> Cartesian)
- 1.1.3 Convert structure file formats (CIF, POSCAR, XYZ)
- 1.1.4 Generate structures with defects (Vacancies, Substitutions, Interstitials)
- 1.1.5 Generate supercells
- 1.1.6 Generate Special Quasirandom Structures (SQS)
- 1.1.7 Generate surface slabs
- 1.1.8 Generate interface structures
- 1.1.9 Visualize structures
1.2 VASP Input File Preparation
- 1.2.1 Prepare full VASP input files (INCAR, KPOINTS, POTCAR, POSCAR)
- 1.2.2 Generate INCAR templates
  - MPMetalRelaxSet: suggested for metallic structure relaxation
  - MPRelaxSet: suggested for structure relaxation
  - MPStaticSet: suggested for static calculations
  - MPNonSCFBandSet: suggested for non-self-consistent field calculations (Band structure)
  - MPNonSCFDOSSet: suggested for non-self-consistent field calculations (Density of States)
  - MPMDSet: suggested for molecular dynamics simulations
- 1.2.3 Generate KPOINTS with specified accuracy
- 1.2.4 Generate HPC job submission script
1.3 Standard VASP Workflow Preparation
- 1.3.1 Convergence test (ENCUT, KPOINTS)
- 1.3.2 Equation of State (EOS)
- 1.3.3 Elastic constants calculations
- 1.3.4 Ab-initio Molecular Dynamics (AIMD)
- 1.3.5 Nudged Elastic Band (NEB) calculations
1.4 Standard VASP Workflow Output Analysis
- 1.4.1 Convergence test analysis
- 1.4.2 Equation of State (EOS) analysis
- 1.4.3 Elastic constants analysis
- 1.4.4 Ab-initio Molecular Dynamics (AIMD) analysis
- 1.4.5 Nudged Elastic Band (NEB) analysis

Fast Simulations Using Machine Learning Potentials (MLPs)

Supported MLPs:
- 2.1 SevenNet
- 2.2 CHGNet
- 2.3 Orb-v3
- 2.4 MatSim
Implemented Simulations for all MLPs:
- Single Point Energy Calculation
- Equation of State (EOS) Calculation
- Elastic Constants Calculation
- Molecular Dynamics Simulation (NVT)

Simple Machine Learning for Materials Science

3.1 Data Preparation & Feature Analysis
- 3.1.1 Feature analysis and visualization
- 3.1.2 Dimensionality reduction (if too many features)
- 3.1.3 Data augmentation (if limited data)
3.2 Model Design & Hyperparameter Tuning
3.3 Model Training & Evaluation
3.4 Model Retraining with New Data
3.5 Pre-trained Model Applications
- 3.5.1 Mechanical Properties Prediction in Sc-modified Al-Mg-Si Alloys
- 3.5.2 Phase Stability & Elastic Properties Prediction in Al-Co-Cr-Fe-Ni High-Entropy Alloys

🔧 Installation

Requirements:
- Python >= 3.11, < 3.14
Install Masgent:
```
pip install -U masgent
```
Optional:
- Materials Project API key for MP structure access: materialsproject.org
- Setup POTCAR path for Pymatgen, see instructions: pymatgen.org

▶️ Usage

After installation, simply run:
```
masgent
```

You'll guided by an interactive menu and can invoke the AI agent anytime. Ask anything in AI chat, for example:

> Generate a POSCAR file for NaCl.
> Prepare VASP input files for a graphene structure.
> Add defects to a silicon crystal POSCAR.
> ...

🐞 Issues and Suggestions

Found a bug? Have a feature request?
Please open an issue here: https://github.com/aguang5241/masgent/issues

📚 Cite Us

If you use Masgent in your research, please cite the following reference:

@misc{liu2025masgentaiassistedmaterialssimulation,
  title={Masgent: An AI-assisted Materials Simulation Agent}, 
  author={Guanghen Liu and Songge Yang and Yu Zhong},
  year={2025},
  eprint={2512.23010},
  archivePrefix={arXiv},
  primaryClass={physics.comp-ph},
  url={https://arxiv.org/abs/2512.23010}, 
}

🙏 Acknowledgements

Masgent builds on the open-source materials ecosystem, including ASE, Pymatgen, Icet, and modern Machine Learning Potentials. We thank the developers of these tools for making advanced materials simulation possible.

Metadata

Release files for masgent 1.1.19

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for masgent 1.1.19
File	Size	Uploaded
masgent-1.1.19.tar.gz	2.8 MB	Jan 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for masgent 1.1.19
File	Interpreter	ABI	Platform	Reset
masgent-1.1.19-py3-none-any.whl 2.8 MB Jan 6, 2026	Python 3	none	any	Details

Total release size: 5.7 MB

Release files / masgent-1.1.19.tar.gz

Download URL	masgent-1.1.19.tar.gz
Size	2.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`041c8a9a0f2369b02583796b267212f036f7417101594c7cc13185b2ce006357`
BLAKE2b-256 checksum How to use checksums	`58f9991ac5b831916c98be4215d617b3a61e1dca6137046472a0f74ff4566142`
Upload date	Jan 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.9`

Release files / masgent-1.1.19-py3-none-any.whl

Download URL	masgent-1.1.19-py3-none-any.whl
Size	2.8 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`ac2bdc0965bbb45a2b2ceed6c25bcf54ab0b71a52f3d8e900f2c1347fe212ae8`
BLAKE2b-256 checksum How to use checksums	`bfc3b69697f0a1d8178a6a6d4b8816d5e8b56ef46ae028a116d8cd2cc6ca7411`
Upload date	Jan 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.9`