# atomsk-cli

> Use when working with the Atomsk command-line tool to create, convert, or modify atomic structures (formats like LAMMPS, VASP/POSCAR, QE, XSF/CFG), apply options (duplicate, orient, orthogonal-cell, reduce-cell, add/remove atoms), and run special modes (create, merge, polycrystal, interactive). Ideal for building supercells, introducing defects, format conversion, or preparing inputs for MD/DFT codes.

- Author: Siyu Liu
- Repository: IntelligentMat/Materials-Science-Skills-For-LLM
- Version: 20251221161123
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/IntelligentMat/Materials-Science-Skills-For-LLM
- Web: https://mule.run/skillshub/@@IntelligentMat/Materials-Science-Skills-For-LLM~atomsk-cli:20251221161123

---

---
name: atomsk-cli
description: Use when working with the Atomsk command-line tool to create, convert, or modify atomic structures (formats like LAMMPS, VASP/POSCAR, QE, XSF/CFG), apply options (duplicate, orient, orthogonal-cell, reduce-cell, add/remove atoms), and run special modes (create, merge, polycrystal, interactive). Ideal for building supercells, introducing defects, format conversion, or preparing inputs for MD/DFT codes.
---

# Atomsk CLI

Concise guidance for running Atomsk inside a shell. Assumes `atomsk` binary is built or installed in `PATH`. Commands are order-sensitive: mode first (if any), then options in call order, then output file/format.

## Quick templates
- Convert format: `atomsk input.ext output.ext` (append `lmp cfg xsf` etc. to emit multiple formats).
- Mode create (lattices/tubes): `atomsk --create <lattice> <a> [c] <sp...> [orient hklX hklY hklZ] [options...] output [formats]`.
- Mode merge: `atomsk --merge <N> file1 file2 ... output [formats]`.
- Options only (transform existing file): `atomsk input -duplicate Nx Ny Nz -orient hklX hklY hklZ -orthogonal-cell output`.
- Interactive shell: `atomsk` with no args; same syntax as CLI inside the prompt.

## Frequently used modes (pick one)
- `--create` / `-C`: build lattices (sc, bcc, fcc, diamond/zb, rocksalt, perovskite, hcp, wurtzite, graphite, nanotube). Accepts `orient` for cubic/hex; nanotube syntax `--create nanotube <a0> <m> <n> <sp1> [sp2]`.
- `--merge` (`-M`): stack/concatenate systems; number `<N>` equals number of inputs.
- `--polycrystal`: generate Voronoi-based polycrystal from seed cell + grain list.
- `--list` / `--one-in-all` / `--all-in-one`: split or combine multi-snapshot trajectories.
- `--average`: average atomic positions over snapshots.

## High-impact options (order = application order)
- `-duplicate Nx Ny Nz` (`-dup`): replicate supercell.
- `-orient hklX hklY hklZ`: reorient cell/axes (rigid rotation). For creation, use `orient` keyword immediately after species instead.
- `-orthogonal-cell`: find equivalent orthogonal box (useful after orientation).
- `-reduce-cell`: attempt cell reduction.
- `-rebox`: infer cell parameters when missing.
- `-add-atom <species> at/relative/near/random ...` ; `-remove-atom <index|species>` ; `-remove-doubles <d>`.
- `-cut <above|below> <d> <normal>` ; `-mirror <d> <direction>` ; `-deform <dir> <ε> <ν>` ; `-disturb <dmax>` random displacements.
- `-options file`: read option list from file (one per line, same syntax).

## Typical workflows
- **Build oriented supercell**: `atomsk --create fcc 4.02 Al orient 0-11 100 011 -duplicate 40 30 30 -orthogonal-cell al_supercell cfg lmp`
- **Convert and thin**: `atomsk traj.lammpstrj --one-in-all cfg` to split snapshots, then `atomsk file.cfg -reduce-cell xsf`.
- **Add defect & freeze layer**: `atomsk seed.cfg -cut below 0.0 z -fix output.cfg`
- **Nanotube**: `atomsk --create nanotube 2.5 8 8 C nanotube xsf cfg`
- **Polycrystal**: prepare seed unit cell, then `atomsk --polycrystal seeds.xsf box_size grains.txt poly.cfg`.

## References
- Load `references/quick-recipes.md` for more ready-to-run command patterns (dislocations, cracks, Nye tensor, RDF).
- Full HTML docs are in `doc/en/*.html` (e.g., `mode_create.html`, `option_duplicate.html`, `options.html`) if deeper detail is needed.

## Tips
- Options are executed sequentially; place geometry-altering steps before property-copy steps.
- Output name may appear before or after mode; listing formats at the end writes multiple files with matching basename.
- Atomsk does not supply lattice constants—user must provide them.
- For cubic lattices, Miller indices are auto-reduced; hexagonal orientation uses three linearly independent directions (not necessarily orthogonal).