Molecular Crystal Structure Prediction

Last updated: October 16, 2026

Info

First, see Tutorial > Random Search (RS) for basic usage of CrySPY.

In this section, we give a tutorial on the molecular structure generation part only. On this page, “molecular crystals” refers to crystals generated by placing molecules or groups of atoms as structural units. This also includes cases where single atoms or polyatomic ions are used as units, as in the Li3PS4 example.

Since version 0.9.0, CrySPY has been able to generate random molecular crystal structures using PyXtal.

You need to use a pre-defined molecular by PyXtal’s database (see, https://pyxtal.readthedocs.io/en/latest/Usage.html?highlight=benzene#pyxtal-molecule-pyxtal-molecule)) or create molecule files that define molecular structures.

Pre-Defined Molecule

PyXtal currently supports C60, H2O, CH4, NH3, benzene, naphthalene, anthracene, tetracene, pentacene, coumarin, resorcinol, benzamide, aspirin, ddt, lindane, glycine, glucose, and ROY.

Let us generate molecular crystal structures that consist of 2 benzenes.

Move to your working directory, and copy input example files by one of the following methods.

Take a look at cryspy.in.

$ cat cryspy.in
[basic]
algo = RS
calc_code = QE
tot_struc = 6
nstage = 2
njob = 2
jobcmd = qsub
jobfile = job_cryspy

[structure]
struc_mode = mol
atype = H C
nat = 12 12
mol_file = benzene
nmol = 2

[QE]
qe_infile = pwscf.in
qe_outfile = pwscf.out
kppvol = 40  60

[option]
rslt_out = always

In generating molecular crystal structures, you have to set struc_mode = mol in the [structure] section. Molecule file(s) and the number of molecule(s) are specified as:

  • mol_file = benzene
  • nmol = 2

The timeout_mol option was removed in v1.5.0.

Run CrySPY and see the initial structures (./data/init_POSCARS).

User-Defined Molecule

Move to your working directory, and copy input example files for 2 formula units of Li3PS4.

  • version 1.0.0 or later
    • Copy from CrySPY utility
  • version 0.10.3 or earlier
    • cp -r ~/CrySPY_root/CrySPY-0.9.0/example/QE_Li3PS4_2fu_RS_mol .
$ cd QE_Li3PS4_2fu_RS_mol
$ ls
Li.xyz  PS4.xyz  calc_in/  cryspy.in

Molecule files of Li and PS4 are included. Supported formats in PyXtal are .xyz, .gjf, .g03, .g09, .com, .inp, .out, and pymatgen’s JSON serialized molecules.

$ cat Li.xyz
1
New structure
 Li  0.000  0.000  0.000
$ cat PS4.xyz
5
New structure
 P    0.000000    0.000000    0.000000
 S    1.200000    1.200000   -1.200000
 S    1.200000   -1.200000    1.200000
 S   -1.200000    1.200000    1.200000
 S   -1.200000   -1.200000   -1.200000

Check cryspy.in.

$ cat cryspy.in
[basic]
algo = RS
calc_code = QE
tot_struc = 4
nstage = 2
njob = 1
jobcmd = qsub
jobfile = job_cryspy

[structure]
struc_mode = mol
atype = Li P S
nat = 6 2 8
mol_file = ./Li.xyz  ./PS4.xyz
nmol = 6 2

[QE]
qe_infile = pwscf.in
qe_outfile = pwscf.out
kppvol = 40  60

[option]
rslt_out = always

A single atom (Li atom in this case) is treated as a molecule in the molecular crystal structure generation mode. In this example, a random molecular structure is composed of six Li molecules (atoms) and two PS4 molecules specified as:

  • mol_file = ./Li.xyz ./PS4.xyz
  • nmol = 6 2

In mol_file, set relative path of molecule files from cryspy.in. Here the molecule files are placed in the same directory.

Run CrySPY and see the initial structures (./data/init_POSCARS).

Volume of Unit Cell

The volume scaling factor can be specified with vol_factor in cryspy.in. The default is 1.1. Specify a single positive number. For example, to set the factor to 1.5, write:

struc_mode = mol
atype = Li P S
nat = 6 2 8
mol_file = ./Li.xyz  ./PS4.xyz
nmol = 6 2
vol_factor = 1.5