CRYSTALLine 0.1.7

A desktop app for building, editing and visualising CRYSTAL structures and their phonon modes — built on CRYSTALClear.

Table of Contents 📑

• Features
• Installation
• Screenshots
• License
• Acknowledgements
• Contact

Features

Structure viewer

• Interactive 3D view (PyVista/VTK): ball-and-stick atoms, bonds, hydrogen bonds (dashed D–H···A interactions), optional coordination polyhedra (VESTA-style), the unit-cell wireframe and an a/b/c gizmo.
• One-click view alignment down the a, b or c axis.
• A rich, dockable Display panel: atom size/opacity, per-element colours, bond radius/tolerance, hydrogen bonds, cell, axes, polyhedra, measurement colours, background colour, projection, an orientation marker and element labels.
• Crystallographic Info panel, dimensionality-aware: space group(3D) or layer group(2D slabs), point group, lattice parameters, cell volume/area, density and formula — recomputed live as you edit.
• The same panel summarises the CRYSTAL run itself: code version, task, Hamiltonian and exchange/correlation functional (with the exact-exchange fraction and dispersion correction), k-point mesh, basis-set size, SCF thresholds, and the computed total energy, band gap and Fermi energy.

Geometry & measurements

• Measure a selection: distance (2 atoms), angle (3), dihedral (4) or a least-squares plane (3+); mark single-atom points.
• Overlay measurements in 3D and colour them per item or by type default.

Phonons

• Loads vibrational modes automatically when the CRYSTAL output has them.
• Filter the mode list to the IR- and/or Raman-active modes when the output reports the selection rules.
• Animate any mode in place — bonds, polyhedra and hydrogen bonds follow the motion; the amplitude is the peak displacement of the most-displaced atom, so one setting works for a molecule and for a large cell alike, and playback speed is adjustable. Export the animation as GIF / MP4 / PNG frames with configurable resolution, frame count and frame rate.

Editing

• Select atoms (click / Ctrl-click), drag them in 3D (periodic images move together), drag a whole selection as one piece, or nudge with the arrow keys.
• Add, delete, duplicate, translate and re-element atoms — with a visual periodic-table, element picker — and full undo / redo.
• Cell tools: conventional cell, supercells, boundary completion and editable lattice parameters.

Import / export

• Open CRYSTAL .out / .gui / .f34 files and .cif structures.
• Import atoms from .xyz / .pdb / .cif into the current structure.
• Save the structure as .gui or .cif (symmetry-reduced).
• Export the 3D view as an image (PNG/JPEG/TIFF/SVG/PDF/EPS) with resolution and transparency options.

Input builder

• Write a ready-to-run CRYSTAL .d12 deck for the current structure, with a live preview of the exact input before you save it.
• Geometry is derived from the structure — space group and asymmetric unit for a crystal, and the right coordinate convention for slabs, polymers and molecules.
• Choose the method (HF or DFT, one functional keyword or separate exchange and correlation), basis set, SCF settings and the calculation: single point, geometry optimisation, frequencies with IR/Raman, phonon dispersion, QHA, equation of state, elastic constants, CPHF, anharmonic runs and spin–orbit coupling.

Property plots (via CRYSTALClear, shown in a dockable tabbed panel)

• IR and Raman harmonic and anharmonic (VSCF, VCI) spectra
• Anharmonic PES (1D, 2D)
• VCI states representation (heatmap, Sankey plot)
• Double-well potential energies, wavefunctions and probability densities
• Elastic properties (Young's modulus, linear compressibility, shear modulus, Poisson ratio)
• Equation of state
• Electronic and phonon band structures and densities of states,
• Simulated XRD

Installation

Public releases of the code are distributed through Pypi.

Requirements

The following will be installed if not already present:

• PySide6 < 6.10 >=6.5
• pyvista >= 0.43
• pyvistaqt >= 0.11
• numpy >= 1.23
• ase >= 3.23
• pymatgen >= 2023.11.10
• CRYSTALClear >= 0.2

Steps

1. Create a conda environment (suggested)

   conda create --name crystal python=3.12
   

2. Activate the environment (suggested)

   conda activate crystal
   

3. Install

   pip install CRYSTALLine
   

Usage

crystalline

Use File → Open to load a CRYSTAL .out/.gui/.34 file or a .cif. If a CRYSTAL output contains a vibrational calculation, the phonon modes are loaded too — pick one in the Phonons panel and press Play. Otherwise the geometry is shown on its own. Tweak the look from the Display panel, measure geometry from the Geometry panel, and build property plots from the Plot menu.

Enable Edit → Editing mode (Ctrl+E) to edit atoms: click to select, drag or arrow-key the selection to move it, Del to delete, and pick elements from the visual periodic table.

CRYSTALLine runs on Linux, macOS and Windows — anywhere PySide6 and a working OpenGL/VTK stack are available.

Linux: Wayland sessions

VTK draws into an X11 window, so on a Wayland session CRYSTALLine asks Qt for the X11 (xcb) plugin automatically and runs through XWayland. If you have forced QT_QPA_PLATFORM=wayland yourself, startup fails with BadWindow (invalid Window parameter) — unset it, or run:

QT_QPA_PLATFORM=xcb crystalline

On Ubuntu 24.04 the xcb plugin also needs system libraries that aren't pulled in by pip:

sudo apt install libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0

Screenshots

Everything in one window.
Crystallography, the interactive 3D view and every vibrational mode, recomputed live as you edit.

🎬 Spectra, and modes as movies A computed Raman spectrum beside the structure. Click a peak to select the mode behind it, animate it, and export the result as a GIF or a video.	🔷 Polyhedra and elastic surfaces VESTA-style coordination polyhedra on a 2×2×2 supercell, drawn as a single mesh so thousands of atoms stay interactive, with a Young's modulus surface from the elastic tensor.
〰️ Anharmonic scans Scanned potential, vibrational states and probability densities. Here the double-well of an imaginary mode, whose two lowest states are split by tunnelling.	🏔️ Anharmonic PES How two normal modes couple through their cubic and quartic terms, as a 3D surface or a contour map, with the harmonic contribution taken out so the coupling is what you see.

Architecture

The package is deliberately layered so the domain logic stays independent of the Qt UI — and therefore unit-testable without a display:

src/crystalline/
├── core/        domain model — Structure, phonons, cells, bonds, undo (no Qt)
├── crystalio/   thin adapter over CRYSTALClear (load/save, property plots)
├── viz/         PyVista/VTK rendering, phonon animation, image/movie export (no Qt)
├── ui/          PySide6 widgets: 3D viewport, dockable panels, main window
└── resources/   bundled assets (logo)

Only ui/ (and the viewport that embeds the VTK interactor) imports Qt. Adding a new property (a new plot, panel, …) is a matter of dropping a widget into ui/panels/ and wiring its signals in MainWindow.

License

GNU General Public License v3.0 or later.

Acknowledgements

Built on the CRYSTALClear I/O and plotting framework for the CRYSTAL quantum chemistry code.

This software was developed with the assistance of Claude (Anthropic), using Claude Code.

Contact

• Website: https://www.crystal.unito.it
• Email: crystalunito@gmail.com
• Instagram: @crystaldevs