Metadata-Version: 2.4
Name: twister2d
Version: 2.0.0
Summary: Twisted 2D material structure generation and analysis (graphene, hBN, TMDs) with LAMMPS integration
Author: Giovanny Espitia
License: MIT
Keywords: twisted bilayer,moire,2D materials,LAMMPS,TMD,graphene,hBN
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: ase
Provides-Extra: mpi
Requires-Dist: mpi4py; extra == "mpi"

# Twister2.0

Twister2.0 builds commensurate supercells of twisted 2D materials (graphene, hBN, transition-metal dichalcogenides), generates ready-to-run LAMMPS structure and input files with automatic interlayer-potential configuration, and post-processes relaxed structures into per-layer strain and interlayer-spacing maps. It also includes a parallel commensurate-twist-angle finder for lattice-mismatched heterobilayers and converters to DFT input formats (Quantum ESPRESSO, SIESTA).

## Repository layout

```
Twister2.0/
├── pyproject.toml     # pip-installable package definition
├── twister2/          # Python package (source)
├── potentials/
│   ├── classical/     # KC, SW, Tersoff, REBO, ILP potential files
│   └── ml/            # PANNA (panna/vdw) config + LAMMPS plugin sources
├── docs/              # detailed documentation
└── examples/          # example input files for each workflow
```

## Installation

```bash
pip install twister2d      # from PyPI
# or from a checkout:
cd Twister2.0
pip install .              # or: pip install -e .  (editable, for development)
pip install ".[mpi]"       # optional: MPI support for the angle finder
```

(The PyPI distribution is named `twister2d`; the installed commands are `twister2`, `twister2-process`, etc.)

This installs the library and the command-line tools:

| Command | Purpose |
|---------|---------|
| `twister2` | Structure generation (reads `twisterase.inp`) |
| `twister2-process` | Extract layers from a relaxed LAMMPS dump |
| `twister2-analyze` | Strain + interlayer-spacing analysis pipeline |
| `twister2-angle` | Commensurate twist angle search (reads `get_ang.inp`) |
| `twister2-cif2qe` | CIF → Quantum ESPRESSO input |
| `twister2-cif2siesta` | CIF → SIESTA input |
| `twister2-remap-types` | Remap LAMMPS atom types to PANNA ordering (manual use) |
| `twister2-restore-tags` | Restore original atom tags in an ML dump (manual use) |

See `docs/installation.md` for details, including LAMMPS build requirements.

## Quick start

```bash
cd examples/tmd-twisted-bilayer-hex
cp ../../potentials/classical/{MoWSSe.KC,tmd.sw} .
twister2                        # -> structure.lammps, lammps.in, process_relaxed.inp
lmp_serial -in lammps.in        # relax with LAMMPS -> dump.Final
twister2-process                # -> layer_N.cif, layer_N_coords.dat
twister2-analyze                # -> StrainMap/, InterlayerSpacingMap/
```

The full walkthrough is in `docs/quickstart.md`.

## Documentation

| Document | Contents |
|----------|----------|
| `docs/installation.md` | Installing the package, dependencies, LAMMPS requirements |
| `docs/quickstart.md` | A first end-to-end run, step by step |
| `docs/cli.md` | Complete command-line reference |
| `docs/workflow.md` | The four-stage pipeline in detail |
| `docs/input_files.md` | Full reference for `twisterase.inp`, `layer*.inp`, `process_relaxed.inp` |
| `docs/hbn.md` | Automatic hBN substrate / cap / encapsulation |
| `docs/ml_potentials.md` | Machine-learned potential (panna/vdw) workflow |
| `docs/angle_finder.md` | Commensurate twist angle search (`twister2-angle`) |
| `docs/analysis.md` | Layer extraction and post-processing |
| `docs/converters.md` | CIF → QE / SIESTA converters |
| `docs/potentials.md` | The bundled potential files and how to use them |

## Requirements

- Python ≥ 3.10 with `numpy`, `scipy`, `matplotlib`, `ase` (installed automatically by pip)
- LAMMPS with the `MANYBODY` and `INTERLAYER` packages (classical workflow), plus the bundled PANNA plugin for the ML workflow
- Optional: `mpi4py` + an MPI library to parallelize the angle finder
