Crystal Structures

Python. All xyzrender flags below map 1:1 to keyword arguments on render(). Worth flagging: --supercell M N L → supercell=(2, 2, 1) (tuple), --axis HKL → axis="111" (string), and extXYZ cell loading is mol = load("foo.xyz", cell=True) (auto-detected for VASP/QE/PDB-CRYST1/CIF/extXYZ inputs).

from xyzrender import load, render
mol = load("caffeine_cell.xyz", cell=True)
render(mol, supercell=(2, 2, 1), output="cell_221.svg")
render(mol, axis="111", no_cell=True)

extXYZ unit cell

Draw the unit cell box for periodic structures from an extXYZ file with a Lattice= header. The cell is detected automatically — no extra flag needed.

Unit cell	Cell rotation	Custom color

Default	No ghost atoms	No cell box

Caffeine 2×2×1 (ghosts)	Caffeine 2×2×1 (ghosts + --hy)	NV63 2×2×1 (ghosts)

xyzrender caffeine_cell.xyz -o caffeine_cell.svg
xyzrender caffeine_cell.xyz --gif-rot -go caffeine_cell.gif
xyzrender caffeine_cell.xyz --cell-color maroon -o caffeine_cell_custom.svg
xyzrender caffeine_cell.xyz --supercell 2 2 1 -o caffeine_cell_supercell_221.svg
xyzrender caffeine_cell.xyz --supercell 2 2 1 --hy -o caffeine_cell_supercell_221_hy.svg
xyzrender NV63_cell.xyz --no-ghosts --no-axes -o NV63_cell_no_ghosts.svg
xyzrender NV63_cell.xyz --no-cell -o NV63_cell_no_cell.svg
xyzrender NV63_cell.xyz --supercell 2 2 1 --no-axes -o NV63_cell_supercell_221.svg

Note

Bond orders are disabled by default for periodic structures — geometry-based perception is not PBC-aware.

The extXYZ comment line must contain a Lattice= key with the 3×3 cell matrix as nine space-separated floats. Tools like ASE can export to extXYZ from CIF or other periodic formats.

Supercell expansion

Expand a periodic structure into a supercell with --supercell M N L, which repeats the unit cell M×N×L times along the lattice vectors (a, b, c). This option is available for any input that includes unit-cell lattice data (e.g. extXYZ Lattice= headers, PDB CRYST1, CIF, VASP, QE, SIESTA, ABINIT, CP2K).

Ghost atoms show the periodic images of the supercell (not the unit cell), while the cell-box overlay always shows the original unit cell. The --hy / --no-hy flags apply to ghost H atoms too.

xyzrender NV63.vasp -o NV63_vasp.svg
xyzrender NV63.vasp --gif-rot -go NV63_vasp.gif
xyzrender NV63.in --no-axes -o NV63_qe.svg

Periodic codes

VASP, Quantum ESPRESSO, SIESTA, ABINIT, and CP2K periodic input files are auto-detected from file content. No extra dependencies or flags required.

VASP (NV63)	VASP rotation	QE (no axes)

Format is auto-detected from extension (.vasp, POSCAR, CONTCAR → VASP; .in → QE/ABINIT; .fdf → SIESTA; .abi → ABINIT; .inp → CP2K).

Crystallographic viewing direction

Orient the crystal looking down a given crystallographic direction with --axis (3-digit Miller index):

View along [001]	View along [111]	Rotate around [111]

xyzrender NV63_cell.xyz --axis 001 -o NV63_001.svg
xyzrender NV63_cell.xyz --axis 111 -o NV63_111.svg
xyzrender NV63_cell.xyz --axis 111 --gif-rot 111 -o NV63_111.svg -go NV63_111.gif

Crystal flags

Flag	Description
--cell	Force cell rendering for extXYZ (usually not needed)
--no-cell	Hide the unit cell box
--ghosts / --no-ghosts	Show/hide ghost (periodic image) atoms outside the cell
--ghost-opacity	Opacity of ghost atoms/bonds (default: 0.5)
--axes / --no-axes	Show/hide the a/b/c axis arrows
--cell-color	Unit cell box color (hex or named, default: gray)
--cell-width	Unit cell box line width (default: 2.0)
--axis HKL	Orient looking down a crystallographic direction (e.g. 111, 001)
--supercell M N L	Repeat the unit cell M×N×L times along a/b/c (requires lattice/unit-cell data; default: 1 1 1)