Installation

Installation#

CRYSTALLine is on PyPI. It needs Python 3.11 or newer.

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 create --name crystal python=3.12
conda activate crystal
pip install CRYSTALLine

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.

An example to open#

If you have no CRYSTAL output to hand, take this one: mgo-example.zip (29 kB): two small calculations on magnesium oxide.

Unpack it and, in properties/, open mgo.out. The Info panel names the space group, Fm-3m (No. 225). Then Plot → Electronic bands & DOS: the band structure and the density of states are found beside the output.

In phonons/, open mgo_222_disp.out. This one was run with DISPERSI, so the Phonons panel lists eight q points. Choose one away from Γ, pick a mode and press Play: it is animated as a travelling wave, and Tile repeats the cell over one wavelength.

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 huge 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
Contents