MXene Structure Generator

A Python framework for systematic generation and manipulation of MXene (M_{n+1}X_nT_z) crystal structures for computational materials science.

Overview

MXenes are a rapidly growing family of 2D materials with the general formula M_{n+1}X_nT_z, where:

M = Early transition metal (Ti, V, Cr, Nb, Mo, Ta, etc.)
X = Carbon or nitrogen
n = Number of X layers (1, 2, or 3)
T = Surface termination (O, OH, F, Cl, etc.)
z = Number of termination sites

This toolkit enables:

Systematic structure generation for all MXene combinations
Multiple stacking sequences (ABC, ABA)
Surface termination positioning (hollow sites: H_M, H_X, H_MX)
VASP-ready output files (POSCAR format)
Geometry analysis (lattice parameters, layer distances)
Batch generation for high-throughput studies

Quick Start

from mxene_generator import MXene, StructureGenerator

# Generate Ti3C2O2 with ABC stacking
mxene = MXene(M="Ti", X="C", n=2, T="O", z=2)
structure = StructureGenerator(mxene, stacking="ABC", hollow="HM")

# Export to VASP format
structure.to_vasp("Ti3C2O2_ABC_HM.vasp")

# Get geometry parameters
a, c, thickness = structure.get_geometry()
print(f"Lattice: a={a:.3f} Å, c={c:.3f} Å, d={thickness:.3f} Å")

Installation

Requirements

pip install numpy

From source

git clone https://github.com/NabKh/MXene-Structure-Generator.git
cd MXene-Structure-Generator
pip install -e .

With optional dependencies

# For visualization
pip install -e ".[vis]"

# For advanced analysis
pip install -e ".[analysis]"

📖 Basic Usage

1. Create a Single MXene Structure

from mxene_generator import MXene, StructureGenerator

# Pristine MXene
mxene = MXene(M="Ti", X="C", n=2)
structure = StructureGenerator(mxene, stacking="ABC")
structure.to_vasp("Ti3C2.vasp")

# Terminated MXene
mxene = MXene(M="Ti", X="C", n=2, T="O", z=2)
structure = StructureGenerator(mxene, stacking="ABC", hollow="HM")
structure.to_vasp("Ti3C2O2.vasp")

2. Batch Generation

from mxene_generator.utils import BatchGenerator

generator = BatchGenerator()
generator.generate_all(
    metals=["Ti", "V", "Nb"],
    X_elements=["C"],
    n_values=[1, 2],
    terminations=["O2", "F2"],
    output_dir="mxene_structures"
)

3. Analyze Geometry

from mxene_generator.geometry import GeometryAnalyzer

analyzer = GeometryAnalyzer(structure)

# Get layer distances
distances = analyzer.get_layer_distances()
print(f"M-X distance: {distances['M-X']:.3f} Å")
print(f"M-T distance: {distances['M-T']:.3f} Å")

# Get other properties
print(f"Thickness: {analyzer.get_thickness():.3f} Å")
print(f"Density: {analyzer.get_density():.3f} g/cm³")
print(f"Surface area: {analyzer.get_surface_area():.3f} Ų")

4. Compare Stackings

from mxene_generator import MXene, StructureGenerator

mxene = MXene("Ti", "C", 2, "O", 2)

for stacking in ["ABC", "ABA"]:
    hollow = "HM" if stacking == "ABC" else "H"
    structure = StructureGenerator(mxene, stacking, hollow)
    structure.to_vasp(f"Ti3C2O2_{stacking}_{hollow}.vasp")

📚 Examples

The examples/ directory contains complete working examples:

01_basic_generation.py - Create single structures
02_termination_screening.py - Screen different terminations
03_stacking_comparison.py - Compare ABC vs ABA stacking
04_batch_processing.py - Generate multiple structures

Run them:

cd examples
python 01_basic_generation.py

🔬 Features

Available Elements

Metals (M): Sc, Ti, V, Cr, Y, Zr, Nb, Mo, Hf, Ta, W

X Elements: C, N

Terminations (T): O, OH, F, Cl, Br, I, S, Se, Te, H

Stacking Sequences

ABC Stacking:

All M layers offset
Hollow sites: HM, HMX, HX
Lower symmetry

ABA Stacking:

M layers aligned
Hollow sites: H, HMX, HX
Higher symmetry

Hollow Sites

Position of surface terminations relative to underlying atoms:

HM - Above/below M atoms
HX - Above/below X atoms
HMX - Mixed (one side HM, other HX)
H - Hexagonal hollow (ABA only)

Project Structure

MXene-Structure-Generator/
├── mxene_generator/
│   ├── __init__.py          # Package initialization
│   ├── core.py              # MXene class and core functions
│   ├── structure.py         # Structure generation
│   ├── geometry.py          # Geometry analysis
│   ├── io.py                # File I/O (VASP, CIF)
│   └── utils.py             # Batch generation utilities
├── examples/
│   ├── 01_basic_generation.py
│   ├── 02_termination_screening.py
│   ├── 03_stacking_comparison.py
│   └── 04_batch_processing.py
├── README.md
├── setup.py
├── requirements.txt
└── LICENSE

🎓 Scientific Background

MXene Nomenclature

MXenes follow the formula M_{n+1}X_nT_z:

M₂X (n=1): Ti₂C, V₂N, etc.
M₃X₂ (n=2): Ti₃C₂, Nb₃N₂, etc.
M₄X₃ (n=3): Ti₄C₃, Mo₄N₃, etc.

With terminations:

M₂XT₂ (n=1): Ti₂CO₂, V₂NF₂
M₃X₂T₂ (n=2): Ti₃C₂O₂, Nb₃N₂OH₂
M₄X₃T₂ (n=3): Ti₄C₃O₂

Applications

Energy storage (batteries, supercapacitors)
Catalysis (HER, OER, CO₂ reduction)
Sensors and biosensors
Electromagnetic shielding
Water purification
Photocatalysis

💻 API Reference

Core Classes

MXene(M, X, n, T=None, z=None)

M: Metal element (str)
X: C or N (str)
n: Number of X layers (int, 1-3)
T: Termination (str, optional)
z: Termination count (int, default 2)

StructureGenerator(mxene, stacking, hollow=None, lattice_a=3.0, vacuum=30.0)

mxene: MXene object
stacking: "ABC" or "ABA"
hollow: Hollow site (required for terminated MXenes)
lattice_a: Lattice parameter in Å
vacuum: Vacuum spacing in Å

GeometryAnalyzer(structure)

structure: StructureGenerator object

Key Methods

# Structure generation
structure.to_vasp(filename)          # Save as VASP POSCAR
structure.to_cif(filename)           # Save as CIF
structure.get_geometry()             # Get a, c, thickness

# Geometry analysis
analyzer.get_layer_distances()       # M-M, M-X, M-T distances
analyzer.get_thickness()             # Slab thickness
analyzer.get_density()               # Mass density
analyzer.get_surface_area()          # Surface area
analyzer.get_volume()                # Unit cell volume

# Batch generation
generator.generate_all(metals, X_elements, n_values, terminations, output_dir)

# Screening studies
screening_study(base_mxene, terminations, property, dft_calculator)

Advanced Usage

Custom Lattice Parameter

structure = StructureGenerator(
    mxene,
    stacking="ABC",
    hollow="HM",
    lattice_a=3.1  # Custom value
)

Custom Vacuum Spacing

structure = StructureGenerator(
    mxene,
    stacking="ABC",
    hollow="HM",
    vacuum=20.0  # 20 Å vacuum
)

Create from Formula

mxene = MXene.from_formula("V2CO2")
print(f"M={mxene.M}, X={mxene.X}, n={mxene.n}, T={mxene.T}")

Generate Multiple Files

from mxene_generator import generate_mxene_family

mxenes = generate_mxene_family(
    metals=["Ti", "V"],
    X="C",
    n_values=[1, 2, 3],
    terminations=["O2", "F2"]
)

for mxene in mxenes:
    structure = StructureGenerator(mxene, "ABC", "HM")
    structure.to_vasp(f"{mxene.formula}.vasp")

Testing

Test the installation:

from mxene_generator import MXene, StructureGenerator

mxene = MXene("Ti", "C", 2, "O", 2)
structure = StructureGenerator(mxene, "ABC", "HM")
structure.to_vasp("test.vasp")

print("✓ Installation successful!")
print(f"✓ Created {mxene.formula}")

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

References

Naguib et al., Adv. Mater. 23, 4248 (2011) - Discovery of MXenes
Anasori et al., Nat. Rev. Mater. 2, 16098 (2017) - MXene review
Khazaei et al., Adv. Funct. Mater. 23, 2185 (2013) - Electronic properties
Khossossi, Nabil, and Rajeev Ahuja. "MXene-based 2D anode materials for next-generation batteries." Next-Generation Materials for Batteries (2021): 1-7.
Singh, Deobrat, et al. "Harnessing the unique properties of MXenes for advanced rechargeable batteries." Journal of Physics: Energy 3.1 (2020): 012005.
Materials Project: https://materialsproject.org/

📧 Contact

Nabil Khossossi

📄 License

MIT License - see LICENSE file

Built for the MXene community by materials scientists, for materials scientists 🔬

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
examples		examples
mxene_generator		mxene_generator
.DS_Store		.DS_Store
.gitattributes		.gitattributes
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt
setup.py		setup.py

License

NabKh/MXene-Structure-Generator

Folders and files

Latest commit

History

Repository files navigation