Installation

Installation#

CRYSTALLine is on PyPI. It needs Python 3.11 or newer — the floor comes from pymatgen, not from CRYSTALLine itself.

It should be installed in an environment of its own rather than in the system Python. Either a conda environment or a virtual environment may be used; conda also provides the Python version, whereas a virtual environment uses the python already installed.

conda

conda create --name crystal python=3.12
conda activate crystal
pip install CRYSTALLine

venv

python -m venv ~/.venvs/crystal
source ~/.venvs/crystal/bin/activate    # Windows: ~\.venvs\crystal\Scripts\activate
pip install CRYSTALLine

Then start it:

crystalline

Any version from 3.11 onwards may be used, including 3.14; releases are made with 3.12.

Optional components#

The export of animations as MP4, MOV or WebM requires an encoder. GIF and numbered frames do not.

pip install CRYSTALLine[video]

Dependencies#

These are installed automatically if not already present:

Package	Why
PySide6-Essentials ≥ 6.5	the Qt GUI (Essentials, not the 847 MB metapackage)
pyvista ≥ 0.43, pyvistaqt ≥ 0.11.4, vtk ≥ 9.1	the 3D viewport
numpy ≥ 1.23, scipy ≥ 1.9	geometry, bonds, statistics
ase ≥ 3.23, pymatgen ≥ 2023.11.10, spglib ≥ 2.5	structures, symmetry, Brillouin zones
CRYSTALClear ≥ 0.2.16	reading CRYSTAL output and drawing the property plots
matplotlib ≥ 3.6, Pillow ≥ 9.0	plots and images

Checking the installation#

crystalline --check

reports the Python version, the dependencies and the versions installed, whether Qt can open a window and whether a VTK render window can be created, and states what is missing. It returns a non-zero exit status if an essential component failed, so that it can be used in a script.

Platform notes#

Linux. The system libraries required by Qt and VTK (libGL, libxkbcommon) are not always present. Under Wayland, VTK draws through XWayland and the program requests Qt’s xcb plugin; if QT_QPA_PLATFORM has been set to wayland, it must be unset. Ubuntu 24.04 also requires:

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

macOS and Windows. No additional components are required. On Windows the crystalline command is a graphical entry point without a console; if it fails silently, python -m crystalline shows the error.

Troubleshooting describes what to do if the program does not start.

Installation from source#

git clone https://github.com/crystaldevs/CRYSTALLine.git
cd CRYSTALLine
pip install -e .
pytest            # the suite runs headless