ASE on Your Local PC

Last updated: October 16, 2026

ASE provides interfaces to different codes. ASE also includes Pure Python EMT calculator, which is suitable for testing CrySPY because of its fast and easy structure optimization.

In this tutorial, we try to use CrySPY in your local PC (Mac or Linux). The target system is Cu 8 atoms.

Assumption

Here, we assume the following conditions:

• CrySPY 1.2.0 or later in your local PC
• CrySPY job filename: job_cryspy
• ase input filename: ase_in.py

Input Files

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

• Download from CrySPY_utility/examples/ase_Cu8_RS
• Copy from CrySPY utility that you installed

cd ase_Cu8_RS
tree

.
├── calc_in
│   ├── ase_in.py
│   └── job_cryspy
└── cryspy.in

cryspy.in

cryspy.in is the input file of CrySPY.

[basic]
algo = RS
calc_code = ASE
tot_struc = 5
nstage = 1
njob = 5
jobcmd = zsh
jobfile = job_cryspy

[structure]
atype = Cu
nat = 8

[ASE]
ase_python = ase_in.py

[option]
rslt_out = always

In [basic] section, jobcmd = zsh can be changed to jobcmd = sh or jobcmd = bash in accordance with your environment. CrySPY runs zsh job_cryspy as a background job internally.

[ASE] section is required when you use ASE.

You can name the following files whatever you want:

• jobfile: job_cryspy
• ase_python: ase_in.py

The other input variables are discussed later.

calc_in Directory

The job file and input files for ASE are prepared in this directory.

Job File

The name of the job file must match the value of jobfile in cryspy.in. The example of job file (here, job_cryspy) is shown below.

#!/bin/sh

# ---------- ASE
python3 ase_in.py

You can specify the input (ase_in.py) file names, but it must match the values of ase_python in cryspy.in. You must add sed -i -e ‘3 s/^.*$/done/’ stat_job at the end of the file in CrySPY. Starting from version 1.4.2, CrySPY automatically appends the following line to the end of the job file. (See also: Features > Job file auto-rewriting)

# ---------- CrySPY
sed -i -e '3s/^sub.*/done/' stat_job

Input for ASE

Input files corresponding to the number of stages (nstage in cryspy.in) are required. Prepare the input file names by adding x_ as a prefix or _x as a suffix, where x is the stage number.

CrySPY searches for input files in the following order of priority:

1. x_ase_in.py
2. ase_in.py_x
3. ase_in.py

If you use the same input for all stages, you can omit x_ or _x.

In this ASE tutorial, since nstage = 1 is used, only one ASE input file, ase_in.py, is needed. You can omit x_ or _x. An example of ase_in.py is shown below (for details on how to use ASE, refer to the official documentation).

from ase.constraints import FixSymmetry
from ase.filters import FrechetCellFilter
from ase.calculators.emt import EMT
from ase.optimize import BFGS
from ase.io import read, write

# ---------- input structure
# CrySPY outputs 'POSCAR' as an input file in work/xxxxxx directory
atoms = read('POSCAR', format='vasp')

# ---------- setting and run
atoms.calc = EMT()
atoms.set_constraint([FixSymmetry(atoms)])
cell_filter = FrechetCellFilter(atoms, hydrostatic_strain=False)
opt = BFGS(cell_filter)

# ---------- run
converged = opt.run(fmax=0.01, steps=2000)

# ---------- rule in ASE interface
# output file for energy: 'log.tote' in eV/cell
#                         CrySPY reads the last line of 'log.tote' file
# outimized structure: 'CONTCAR' file in vasp format
# check_opt: 'out_check_opt' file ('done' or 'not yet')
#                         CrySPY reads the last line of 'out_check_opt' file

# ------ energy
e = cell_filter.atoms.get_total_energy()    # eV/cell
with open('log.tote', mode='w') as f:
    f.write(str(e))

# ------ struc
opt_atoms = cell_filter.atoms.copy()
opt_atoms.set_constraint(None)    # remove constraint for pymatgen
write('CONTCAR', opt_atoms, format='vasp', direct=True)

# ------ check_opt
with open('out_check_opt', mode='w') as f:
    if converged:
        f.write('done\n')
    else:
        f.write('not yet\n')

Unlike VASP and QE, the ASE input (python script) is more flexible. CrySPY has three rules:

1. Energy is output in units of eV/cell to log.tote file. CrySPY reads the last line of it.
2. Optimized structure is output to CONTCAR file in the VASP format.
3. The result of the optimization convergence check should be written as either done or not_yet in a file named out_check_opt. CrySPY reads the last line of this file.

Running CrySPY

Go to Running CrySPY

soiap on Your Local PC

Last updated: October 16, 2026

soiap is Structure Optimization with InterAtomic Potential. It is suitable for testing CrySPY because of its fast structure optimization. See instructions to install soiap.

In this tutorial, we try to use CrySPY in your local PC (Mac or Linux). The target system is Si 8 atoms.

Assumption

Here, we assume the following conditions:

• (only version 0.10.3 or earlier) CrySPY main script: ~/CrySPY_root/CrySPY-0.9.0/cryspy.py
• CrySPY job filename: job_cryspy
• soiap executable file: ~/local/soiap-0.3.0/src/soiap
• soiap input filename: soiap.in
• soiap output filename: soiap.out
• soiap input structure filename: initial.cif

Input Files

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

• Download from Cryspy_utility/examples/soiap_Si8_RS
• Copy from CrySPY utility that you installed
• (only version 0.10.3 or earlier) cp -r ~/CrySPY_root/CrySPY-0.9.0/example/v0.9.0/soiap_RS_Si8 .

cd soiap_RS_Si8
tree

.
├── calc_in
│   ├── job_cryspy
│   └── soiap.in_1
└── cryspy.in

cryspy.in

cryspy.in is the input file of CrySPY.

[basic]
algo = RS
calc_code = soiap
tot_struc = 5
nstage = 1
njob = 2
jobcmd = zsh
jobfile = job_cryspy

[structure]
atype = Si
nat = 8

[soiap]
soiap_infile = soiap.in
soiap_outfile = soiap.out
soiap_cif = initial.cif

[option]
rslt_out = always

In [basic] section, jobcmd = zsh can be changed to jobcmd = sh or jobcmd = bash in accordance with your environment. CrySPY runs zsh job_cryspy as a background job internally.

[soiap] section is required when you use soiap.

You can name the following files whatever you want:

• jobfile
• soiap_infile
• soiap_outfile
• soiap_cif

The other input variables are discussed later.

calc_in Directory

The job file and input files for soiap are prepared in this directory.

Job File

The name of the job file must match the value of jobfile in cryspy.in. The example of job file (here, job_cryspy) is shown below.

#!/bin/sh

# ---------- soiap
EXEPATH=/path/to/soiap
$EXEPATH/soiap soiap.in 2>&1 > soiap.out

# ---------- CrySPY
sed -i -e '3 s/^.*$/done/' stat_job

Change /path/to/soiap into right path suitable for your environment. You can specify the input (soiap.in) and output (soiap.out) file names, but they must match the values of soiap_infile and soiap_outfile in cryspy.in. The job file is written in the same way as the one you usually use except for the last line. You must add sed -i -e '3 s/^.*$/done/' stat_job at the end of the file in CrySPY.

Input for soiap

Input files based on the number of stages (nstage in cryspy.in) are required. Name the input file(s) with a suffix _x. Here x means the stage number.

We are using nstage = 1, so we need only soiap.in_1.

soiap.in_1 is listed below.

crystal initial.cif ! CIF file for the initial structure
symmetry 1 ! 0: not symmetrize displacements of the atoms or 1: symmetrize

md_mode_cell 3 ! cell-relaxation method
               ! 0: FIRE, 2: quenched MD, or 3: RFC5
number_max_relax_cell 100 ! max. number of the cell relaxation
number_max_relax 1 ! max. number of the atom relaxation
max_displacement 0.1 ! max. displacement of atoms in Bohr

external_stress_v 0.0 0.0 0.0 ! external pressure in GPa

th_force 5d-5 ! convergence threshold for the force in Hartree a.u.
th_stress 5d-7 ! convergence threshold for the stress in Hartree a.u.

force_field 1 ! force field
              ! 1: Stillinger-Weber for Si, 2: Tsuneyuki potential for SiO2,
              ! 3: ZRL for Si-O-N-H, 4: ADP for Nd-Fe-B, 5: Jmatgen, or
              ! 6: Lennard-Jones

The input structure file is specified at the first line. Use the same name as the value of soiap_cif in cryspy.in.

Running CrySPY

Go to Running CrySPY

VASP

Last updated: October 16, 2026

In this tutorial, we try to use CrySPY in a PC cluster with a job scheduler system such as PBS. Here we employ VASP. The target system is Na8Cl8, 16 atoms.

Assumption

Here, we assume the following conditions:

• CrySPY 1.2.0 or later in your PC cluster
• CrySPY job command: qsub
• CrySPY job filename: job_cryspy
• executable file, vasp_std in your PC cluster

Input Files

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

• Download from Cryspy_utility/examples/vasp_Na8Cl8_RS
• Copy from CrySPY utility that you installed

cd vasp_Na8Cl8_RS
tree

.
├── calc_in
│   ├── 1_INCAR
│   ├── 2_INCAR
│   ├── POTCAR_dummy
│   └── job_cryspy
└── cryspy.in

cryspy.in

cryspy.in is the input file of CrySPY.

[basic]
algo = RS
calc_code = VASP
tot_struc = 5
nstage = 2
njob = 2
jobcmd = qsub
jobfile = job_cryspy

[structure]
atype = Na Cl
nat = 8 8
mindist_1 = 2.5 1.5
mindist_2 = 1.5 2.5

[VASP]
kppvol = 40 80

[option]
rslt_out = always

In [basic] section, jobcmd = qsub can be changed in accordance with your environment. CrySPY runs qsub job_cryspy as a background job internally in this setting. You can name the following file whatever you want:

• jobfile

We adopt a stage-based system for structure optimization calculations. Here, we use nstage = 2. For example, users can configure the following settings. In the first stage, only the ionic positions are relaxed, fixing the cell shape, with low k-point grid density. Next, the ionic positions and cell shape are fully relaxed with high accuracy in the second stage.

[VASP] section is required when you use VASP. You have to specify k-point grid density (Å^-3) for each stage in kppvol.

The other input variables are discussed later.

calc_in Directory

The job file and input files for VASP are prepared in this directory.

Job File

The name of the job file must match the value of jobfile in cryspy.in. The example of job file (here, job_cryspy) is shown below.

#!/bin/sh
#$ -cwd
#$ -V -S /bin/bash
####$ -V -S /bin/zsh
#$ -N Na8Cl8_CrySPY_ID
#$ -pe smp 20
####$ -q ibis1.q
####$ -q ibis2.q
####$ -q ibis3.q
####$ -q ibis4.q

# ---------- vasp
VASPROOT=/usr/local/vasp/vasp.6.4.2/bin
mpirun -np $NSLOTS $VASPROOT/vasp_std

Change VASPROOT to the appropriate path suitable for your environment. The job file is written in the same way as the one you usually use except for the last line. You must add sed -i -e ‘3 s/^.*$/done/’ stat_job at the end of the file in CrySPY. Starting from version 1.4.2, CrySPY automatically appends the following line to the end of the job file. (See also: Features > Job file auto-rewriting)

# ---------- CrySPY
sed -i -e '3s/^sub.*/done/' stat_job

Input for VASP

Input files corresponding to the number of stages (nstage in cryspy.in) are required. Prepare the input file names by adding x_ as a prefix or _x as a suffix, where x is the stage number.

CrySPY searches for input files in the following order of priority:

1. x_INCAR
2. INCAR_x
3. INCAR

If you use the same input for all stages, you can omit x_ or _x.

We are using nstage = 2, so we need 1_INCAR_1 and 2_INCAR. Here, 1_INCAR is set to fix the cell and relax only the ionic positions, while 2_INCAR is configured to fully relax both the cell and ionic positions.

1_INCAR

SYSTEM = NaCl
!!!LREAL = Auto
Algo = Fast
NSW = 40

LWAVE = .FALSE.
!LCHARG = .FALSE.

ISPIN =  1

ISMEAR = 0
SIGMA = 0.1

IBRION = 2
ISIF = 2

EDIFF = 1e-5
EDIFFG = -0.01

2_INCAR

SYSTEM = NaCl
!!LREAL = Auto
Algo = Fast
NSW = 200

ENCUT = 341

!!LWAVE = .FALSE.
!!LCHARG = .FALSE.


ISPIN =  1

ISMEAR = 0
SIGMA = 0.1

IBRION = 2
ISIF = 3

EDIFF = 1e-5
EDIFFG = -0.01

CrySPY automatically generates POSCAR and KPOINTS files. You have to prepare POTCAR file yourself. The POTCAR included in this example file is empty, so please be aware of that.

Running CrySPY

Go to Running CrySPY

QE

Last updated: October 16, 2026

In this tutorial, we try to use CrySPY in a machine with a job scheduler system such as PBS. Here we employ QUANTUM ESPRESSO. (QE). The target system is Si 8 atoms.

Assumption

Here, we assume the following conditions:

• CrySPY job command: qsub
• CrySPY job filename: job_cryspy
• QE executable file: /usr/local/qe-6.5/bin/pw.x
• QE input filename: pwscf.in
• QE output filename: pwscf.out

Input Files

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

• Download from CrySPY_utility/examples/qe_Si8_RS
• Copy from CrySPY utility that you installed
• (only version 0.10.3 or earlier) cp -r ~/CrySPY_root/CrySPY-0.9.0/example/v0.9.0/QE_Si8_RS .

cd QE_RS_Si8
tree

.
├── calc_in
│   ├── job_cryspy
│   ├── 1_pwscf.in
│   └── 2_pwscf.in
└── cryspy.in

cryspy.in

cryspy.in is the input file of CrySPY.

[basic]
algo = RS
calc_code = QE
tot_struc = 5
nstage = 2
njob = 2
jobcmd = qsub
jobfile = job_cryspy

[structure]
atype = Si
nat = 8

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

[option]
rslt_out = always

In [basic] section, jobcmd = qsub can be changed in accordance with your environment. CrySPY runs qsub job_cryspy as a background job internally in this setting.

We adopt a stage-based system for structure optimization calculations. Here, we use nstage = 2. For example, users can configure the following settings. In the first stage, only the ionic positions are relaxed, fixing the cell shape, with low k-point grid density. Next, the ionic positions and cell shape are fully relaxed with high accuracy in the second stage.

[QE] section is required when you use QE. You have to specify k-point grid density (Å^-3) for each stage in kppvol.

You can name the following files whatever you want:

• jobfile
• qe_infile
• qe_outfile

The other input variables are discussed later.

calc_in Directory

The job file and input files for QE are prepared in this directory.

Job File

The name of the job file must match the value of jobfile in cryspy.in. The example of job file (here, job_cryspy) is shown below.

#!/bin/sh
#$ -cwd
#$ -V -S /bin/bash
####$ -V -S /bin/zsh
#$ -N Si8_CrySPY_ID
#$ -pe smp 20
####$ -q ibis1.q
####$ -q ibis2.q

mpirun -np $NSLOTS /path/to/pw.x < pwscf.in > pwscf.out


if [ -e "CRASH" ]; then
    sed -i -e '3 s/^.*$/skip/' stat_job
    exit 1
fi

Change /path/to/pw.x to the appropriate path suitable for your environment. You can specify the input (pwscf.in) and output (pwscf.out) file names, but they must match the values of qe_infile and qe_outfile in cryspy.in.

The job file is written in the same way as the one you usually use except for the last line. You must add sed -i -e ‘3 s/^.*$/done/’ stat_job at the end of the file in CrySPY. Starting from version 1.4.2, CrySPY automatically appends the following line to the end of the job file. (See also: Features > Job file auto-rewriting)

# ---------- CrySPY
sed -i -e '3s/^sub.*/done/' stat_job

Input for QE

Input files corresponding to the number of stages (nstage in cryspy.in) are required. Prepare the input file names by adding x_ as a prefix or _x as a suffix, where x is the stage number.

CrySPY searches for input files in the following order of priority:

1. x_pwscf.in
2. pwscf.in_x
3. pwscf.in

We are using nstage = 2, so we need 1_pwscf.in and 2_pwscf.in. Here, 1_pwscf.in is set to fix the cell and relax only the ionic positions, while 2_pwscf.in is configured to fully relax both the cell and ionic positions.

1_pwscf.in

 &control
    title = 'Si8'
    calculation = 'relax'
    nstep = 100
    restart_mode = 'from_scratch',
    pseudo_dir = '/usr/local/pslibrary.1.0.0/pbe/PSEUDOPOTENTIALS/'
    outdir='./out.d/'
 /

 &system
    ibrav = 0
    nat = 8
    ntyp = 1
    ecutwfc = 44.0
    occupations = 'smearing'
    degauss = 0.01
 /

 &electrons
 /

 &ions
 /

 &cell
 /

ATOMIC_SPECIES
  Si  28.086  Si.pbe-n-kjpaw_psl.1.0.0.UPF

1_pwscf.in

 &control
    title = 'Si8'
    calculation = 'vc-relax'
    nstep = 200
    restart_mode = 'from_scratch',
    pseudo_dir = '/usr/local/pslibrary.1.0.0/pbe/PSEUDOPOTENTIALS/'
    outdir='./out.d/'
 /

 &system
    ibrav = 0
    nat = 8
    ntyp = 1
    ecutwfc = 44.0
    occupations = 'smearing'
    degauss = 0.01
 /

 &electrons
 /

 &ions
 /

 &cell
 /

ATOMIC_SPECIES
  Si  28.086  Si.pbe-n-kjpaw_psl.1.0.0.UPF

Change pseudo_dir to your suitable directory. Inputs for structure data and k-point such as ATOMIC_POSITIONS and K_POINTS are automatically appended by CrySPY with pymatgen. Users do not have to prepare them in x_pwscf.in.

Running CrySPY

Go to Running CrySPY

OpenMX

Coming soon.

LAMMPS

Coming soon.

Check cryspy.in

Last updated: October 16, 2026

See Input File in detail.

Let’s take a look at cryspy.in again. This may be slightly different depending on calc_code you chose.

[basic]
algo = RS
calc_code = ASE
tot_struc = 5
nstage = 1
njob = 5
jobcmd = zsh
jobfile = job_cryspy

[structure]
atype = Cu
nat = 8

[ASE]
ase_python = ase_in.py

[option]
rslt_out = always

[basic] Section

• algo: Algorithm. Set RS for Random Search.
• calc_code: Structure optimizer. Choose from VASP, QE, OMX, soiap, LAMMPS, ASE
• tot_struc: The total number of structures. In this case, 5 random structures are generated at 1st run.
• nstage: The number of stages. It’s up to you.
• njob: The number of jobs running at the same time. In this example, CrySPY sets 2 slots for structure optimization, in other words, optimizes every 2 structures.
• jobcmd: Command for jobs. Use bash, zsh, qsub, and so on.
• jobfile: File name of the job file.

[structure] Section

• atype: Atom type. e.g. for Na8Cl8: atype = Na Cl.
• nat: The number of atoms corresponding to each atype. e.g. for Na8Cl8: nat = 8 8

Script to Run

Assumption

Here, we assume the following condition:

• CrySPY main script: ~/CrySPY_root/CrySPY-0.9.0/cryspy.py

Make Script

Let’s make a convenient shell script to avoid typing long commands over and over again. Here, we create the script, cryspy (any file name will do).

$ emacs cryspy
$ chmod 744 cryspy
$ cat cryspy

#!/bin/sh

python3 -u ~/CrySPY_root/CrySPY-0.9.0/cryspy.py 1>> log 2>> err

-u option (unbuffered option) can be omitted.

You can put this script in your $PATH, or just use like bash ./cryspy.

First Run

2025 March 6, updated

Make sure you have the following in your working directory.

• calc_in/
• (cryspy)
• cryspy.in

$ ls
calc_in/  cryspy.in

Then, run CyrSPY!

cryspy

If you use old version (0.10.3 or earlier):

bash ./cryspy

At the first run, CrySPY goes into structure generation mode. CrySPY stops after 5 structure generation.

If it worked properly, the following output appears on the screen:

[2025-03-06 18:52:21,495][cryspy_init][INFO] 


Start CrySPY 1.4.0b10


[2025-03-06 18:52:21,495][cryspy_init][INFO] # ---------- Library version info
[2025-03-06 18:52:21,495][cryspy_init][INFO] pandas version: 2.2.2
[2025-03-06 18:52:21,495][cryspy_init][INFO] pymatgen version: 2025.1.24
[2025-03-06 18:52:21,495][cryspy_init][INFO] pyxtal version: 1.0.6
[2025-03-06 18:52:21,495][cryspy_init][INFO] # ---------- Read input file, cryspy.in
[2025-03-06 18:52:21,496][write_input][INFO] [basic]
[2025-03-06 18:52:21,496][write_input][INFO] algo = RS
[2025-03-06 18:52:21,496][write_input][INFO] calc_code = ASE
[2025-03-06 18:52:21,496][write_input][INFO] tot_struc = 5
[2025-03-06 18:52:21,496][write_input][INFO] nstage = 1
[2025-03-06 18:52:21,496][write_input][INFO] njob = 2
[2025-03-06 18:52:21,496][write_input][INFO] jobcmd = zsh
[2025-03-06 18:52:21,496][write_input][INFO] jobfile = job_cryspy
...
(omitted)
...
[2025-03-06 18:52:21,497][rs_gen][INFO] # ---------- Initial structure generation
[2025-03-06 18:52:21,497][rs_gen][INFO] # ------ mindist
[2025-03-06 18:52:21,498][struc_util][INFO] Cu - Cu: 1.32
[2025-03-06 18:52:21,498][rs_gen][INFO] # ------ generate structures
[2025-03-06 18:52:21,519][gen_pyxtal][INFO] Structure ID      0: (8,) Space group:  31 -->  31 Pmn2_1
[2025-03-06 18:52:21,525][gen_pyxtal][INFO] Structure ID      1: (8,) Space group: 198 --> 198 P2_13
[2025-03-06 18:52:21,554][gen_pyxtal][INFO] Structure ID      2: (8,) Space group:   4 -->   4 P2_1
[2025-03-06 18:52:21,580][gen_pyxtal][INFO] Structure ID      3: (8,) Space group: 193 --> 191 P6/mmm
[2025-03-06 18:52:21,581][gen_pyxtal][WARNING] Compoisition [8] not compatible with symmetry 172:     spg = 172 retry.
[2025-03-06 18:52:21,625][gen_pyxtal][INFO] Structure ID      4: (8,) Space group:  64 -->  64 Cmce
[2025-03-06 18:52:22,013][cryspy_init][INFO] Elapsed time for structure generation: 0:00:00.516183

Several output files are also generated.

• (cryspy.out): Short log. only version 0.10.3 or earlier.
• cryspy.stat: Status file.
• data/init_POSCARS: Initial struture file in POSCAR format. You can open this file using VESTA
• data/pkl_data: Directory to save pickled data.
• log_cryspy: log.
• err_cryspy: error and warning.

Let’s take a look at cryspy.stat file.

[status]
id_queueing = 0 1 2 3 4

Structure ID 0 – 4 are queueing because we just generated structures, and have not submitted yet.

Submit Job

2023 July 10, update

Continue

CrySPY continues the simulation if you have cryspy.stat file.

Submit Job

Run CyrSPY again.

cryspy

Check the screen or log_cryspy file.

[2023-07-10 18:52:51,859][cryspy_restart][INFO] 


Restart CrySPY 1.2.0


[2023-07-10 18:52:51,869][ctrl_job][INFO] # ---------- job status
[2023-07-10 18:52:51,904][ctrl_job][INFO] ID      0: submit job, Stage 1
[2023-07-10 18:52:51,931][ctrl_job][INFO] ID      1: submit job, Stage 1

And also cryspy.stat file.

...
(omit)
...
[status]
id_queueing = 2 3 4
id      0 = Stage 1
id      1 = Stage 1

CrySPY submitted two jobs for structure ID 0 and 1 as you set njob = 2 in cryspy.in. Calculations are performed in the work directory. These directory names correspond to their structure ID.

tree -d work

work
├── 000000
├── 000001
└── fin

When the two jobs are done, run CrySPY again.

cryspy

[2023-07-10 18:55:01,053][cryspy_restart][INFO] 


Restart CrySPY 1.2.0


[2023-07-10 18:55:01,058][ctrl_job][INFO] # ---------- job status
[2023-07-10 18:55:01,058][ctrl_job][INFO] ID      0: Stage 1 Done!
[2023-07-10 18:55:01,093][ctrl_job][INFO]     collect results: E = -0.00696997755502915 eV/atom
[2023-07-10 18:55:01,132][ctrl_job][INFO] ID      1: Stage 1 Done!
[2023-07-10 18:55:01,133][ctrl_job][INFO]     collect results: E = 0.4934076667166454 eV/atom
[2023-07-10 18:55:01,144][cryspy][INFO] 

recheck 1

[2023-07-10 18:55:01,145][ctrl_job][INFO] # ---------- job status
[2023-07-10 18:55:01,153][ctrl_job][INFO] ID      2: submit job, Stage 1
[2023-07-10 18:55:01,161][ctrl_job][INFO] ID      3: submit job, Stage 1

If you set nstage = 2 (more than 2), new jobs on stage 2 for ID 0 and 1 are submitted. If you set nstage = 1, CrySPY collects calculation data of ID 0 and 1, then submits next ID’s jobs. Directories of the finished structure are moved to the fin directory.

Repeat cryspy several times until all 5 structures are done. You can delete the work directory when the simulation is done if you do not need it.

The auto script (repeat_cryspy) may help you.

Check Results

Last updated: October 16, 2026

Move to data directory. There should be a few more files.

$ cd data
$ ls
cryspy_rslt  cryspy_rslt_energy_asc  init_POSCARS  opt_POSCARS  pkl_data/

• cryspy_rslt: Result file.
• cryspy_rslt_energy_asc: Result file sorted in energy ascending order.
• init_POSCARS: Initial struture file in POSCAR format.
• opt_POSCARS: Optimized structure file in POSCAR format.
• pkl_data/: Directory to save pickled data.

The results are written to text files, cryspy_rslt and cryspy_rslt_energy_asc (and also saved in pickle data in pkl_data directory).

From v1.5.0, rslt_out in the [option] section controls when cryspy_rslt and cryspy_rslt_energy_asc are written. The default is always. See Input File > [option] Section for details.

Each result appends to cryspy_rslt file in the order in which one finished earlier.

cat cryspy_rslt

   Spg_num Spg_sym  Spg_num_opt Spg_sym_opt  E_eV_atom  Magmom      Opt
0      139  I4/mmm          139      I4/mmm  -3.000850     NaN     done
1       98  I4_122           12        C2/m  -3.978441     NaN  not_yet
2       16    P222           16        P222  -3.348616     NaN  not_yet
3       36  Cmc2_1           36      Cmc2_1  -3.520306     NaN  not_yet
4       36  Cmc2_1            4        P2_1  -3.304168     NaN  not_yet

In cryspy_rslt_energy_asc file, the results are sorted in energy ascending order.

cat cryspy_rslt_energy_asc

   Spg_num Spg_sym  Spg_num_opt Spg_sym_opt  E_eV_atom  Magmom      Opt
1       98  I4_122           12        C2/m  -3.978441     NaN  not_yet
3       36  Cmc2_1           36      Cmc2_1  -3.520306     NaN  not_yet
2       16    P222           16        P222  -3.348616     NaN  not_yet
4       36  Cmc2_1            4        P2_1  -3.304168     NaN  not_yet
0      139  I4/mmm          139      I4/mmm  -3.000850     NaN     done

Spg_num and Spg_sym show space group information on initial structures. Spg_num_opt and Spg_sym_opt are those of optimized structures. The last column Opt indicates whether or not optimization reached required accuracy.

Append Structures

Last updated: October 16, 2026

Of course only 5 structures are not enough to find stable structures. You can append structures whenever you want. Here let’s append more 5 structures.

For Si-Si mindist, the default value of 1.11 Å is used in the first structure generation (see log_cryspy), which is a little too close. Let us try to set the mindist to 2.0 Å.

Edit cryspy.in and change the value of tot_struc into 10, and add mindist_1 = 2.0

emacs cryspy.in
cat cryspy.in

[basic]
algo = RS
calc_code = soiap
tot_struc = 10
nstage = 1
njob = 2
jobcmd = zsh
jobfile = job_cryspy

[structure]
atype = Si
nat = 8
mindist_1 = 2.0

[soiap]
soiap_infile = soiap.in
soiap_outfile = soiap.out
soiap_cif = initial.cif

[option]
rslt_out = always

Then run cryspy, and check log_cryspy file.

cryspy &
cat log_cryspy

...
(omit)
...

2023/03/19 00:01:47
CrySPY 1.0.0
Restart cryspy.py


Changed tot_struc from 5 to 10
Changed mindist from None to [[2.0]]

Backup data

# ---------- Append structures
# ------ mindist
Si - Si 2.0
Structure ID      5 was generated. Space group: 218 --> 221 Pm-3m
Structure ID      6 was generated. Space group:  86 --> 129 P4/nmm
Structure ID      7 was generated. Space group: 129 --> 129 P4/nmm
Structure ID      8 was generated. Space group: 191 --> 191 P6/mmm
Structure ID      9 was generated. Space group:  31 -->  31 Pmn2_1

Remember that CrySPY goes into structure generation mode whenever you change the value of tot_struc. In this mode, CrySPY does not do any other action such as collecting data, submitting jobs, and so on.

Repeat cryspy & several times until all appended structures are done. The auto script (repeat_cryspy) may help you.

Analysis and Visualization

Last updated: February 9, 2026

Energy Plot

Since version 1.4.4, results can be easily visualized using the cryspy-Eplot command as follows:

cryspy-Eplot 

The file is saved to ./data/energy_plot/energy_RS_{tot_struc}.{fig_fotmat}.

The following input variables can be modified by specifying them in the [visual] section of cryspy.in. See also CrySPY > Input file > [visual] section.

...

[visual]
ymax = 0.2
markersize = 10
fig_format = svg

...

For more advanced data analysis or figure customization, download the files and use Jupyter Notebook as shown below.

Download Data

It is assumed here that you analyze and visualize CrySPY data on your local PC. If you use CrySPY on a supercomputer or workstation, download the data to your local machine. You can delete the work and backup directories if they are not needed, as their file size can be very large.

Jupyter Notebook

Move to the data/ directory in the results you downloaded earlier. Then, if the CrySPY utility has already been downloaded locally, copy cryspy_analyzer_RS.ipynb. Alternatively, you can download it directly from GitHub (CrySPY_utility/notebook/). Launch Jupyter (e.g., VS Code, Jupyter Lab, or Jupyter Notebook), and simply run the cells in order to obtain a figure like the one shown below.

ASE on Your Local PC

Last updated: October 16, 2026

The files used in this tutorial can be downloaded from CrySPY_utility/examples/ase_Cu8Au8_EA. This tutorial demonstrates a test run on a local machine using ASE’s lightweight Pure Python EMT calculator. The target system is Cu8Au8.

cryspy.in

Example of cryspy.in.

[basic]
algo = EA
calc_code = ASE
nstage = 1
njob = 5
jobcmd = zsh
jobfile = job_cryspy

[structure]
atype = Cu Au
nat = 8 8

[EA]
n_pop = 10
n_crsov = 5
n_perm = 2
n_strain = 2
n_rand = 1
n_elite = 1
n_fittest = 5
slct_func = TNM
t_size = 2
maxgen_ea = 0

[ASE]
ase_python = ase_in.py

[option]
rslt_out = always
energy_output_interval = 1
backup_interval = 1

• Use algo = EA.
• From v1.5.0, energy_output_interval in the [option] section sets the output interval in generations for the energy plot. Default: 1 (every generation); 0 disables automatic output.
• From v1.5.0, backup_interval in the [option] section sets the automatic backup interval in generations. The default is 1; 0 disables automatic backups. See Features > Backup for details.
• When using a bash environment, set jobcmd to bash.
• In EA, tot_struc is not used. The number of structures is determined by n_pop.
• n_pop = n_crsov + n_perm + n_strain + n_rand
• For parameters in the [EA] section, refer to Input file > [EA] section and Search algorithms > Evolutionary algorithm (EA).

calc_in/

The contents under calc_in/ are the same as in Tutorial > Random Search (RS) > ASE in your local PC.

calc_in/ase_in.py_1

from ase.constraints import FixSymmetry
from ase.filters import FrechetCellFilter
from ase.calculators.emt import EMT
from ase.optimize import BFGS
from ase.io import read, write

# ---------- input structure
# CrySPY outputs 'POSCAR' as an input file in work/xxxxxx directory
atoms = read('POSCAR', format='vasp')

# ---------- setting and run
atoms.calc = EMT()
atoms.set_constraint([FixSymmetry(atoms)])
cell_filter = FrechetCellFilter(atoms, hydrostatic_strain=False)
opt = BFGS(cell_filter)

# ---------- run
converged = opt.run(fmax=0.01, steps=2000)

# ---------- rule in ASE interface
# output file for energy: 'log.tote' in eV/cell
#                         CrySPY reads the last line of 'log.tote' file
# outimized structure: 'CONTCAR' file in vasp format
# check_opt: 'out_check_opt' file ('done' or 'not yet')
#                         CrySPY reads the last line of 'out_check_opt' file

# ------ energy
e = cell_filter.atoms.get_total_energy()    # eV/cell
with open('log.tote', mode='w') as f:
    f.write(str(e))

# ------ struc
opt_atoms = cell_filter.atoms.copy()
opt_atoms.set_constraint(None)    # remove constraint for pymatgen
write('CONTCAR', opt_atoms, format='vasp', direct=True)

# ------ check_opt
with open('out_check_opt', mode='w') as f:
    if converged:
        f.write('done\n')
    else:
        f.write('not yet\n')

calc_in/job_cryspy

#!/bin/sh

# ---------- ASE
python3 ase_in.py > out.log

Create Next Generation

Last updated: October 16, 2026

First Run

When you run cryspy, the program enters structure generation mode. It generates the first generation of random structures and then exits.

cryspy

log

...
[2025-04-06 09:15:34,720][ea_init][INFO] # ---------- Initialize evolutionary algorithm
[2025-04-06 09:15:34,720][ea_init][INFO] # ------ Generation 1
[2025-04-06 09:15:34,720][ea_init][INFO] 10 structures by random

In EA, running cryspy appends the current generation’s information to cryspy.stat.

[status]
generation = 1
id_queueing = 0 1 2 3 4 5 6 7 8 9

Optimize Structures

After running cryspy several times and completing the structure optimization for the first generation, the output will appear as shown below.

...
[2025-04-06 09:20:26,218][ctrl_job][INFO] Done generation 1
[2025-04-06 09:20:26,218][ctrl_job][INFO] 
EA is ready

Create Next Generation

Once all preparations are complete, running cryspy again starts generating the next-generation structures. By default (backup_interval = 1), an automatic backup is performed immediately before generating these structures. From v1.5.0, backup_interval in the [option] section can be used to change the interval in generations; 0 disables automatic backups. See Features > Backup for details.

cryspy

...
[2025-04-06 09:35:11,546][cryspy_restart][INFO] read input, cryspy.in
[2025-04-06 09:35:11,554][ctrl_job][INFO] # ---------- job status
[2025-04-06 09:35:11,554][ctrl_job][INFO] Done generation 1
[2025-04-06 09:35:11,554][utility][INFO] Backup data
[2025-04-06 09:35:11,611][ea_next_gen][INFO] # ---------- Evolutionary algorithm
[2025-04-06 09:35:11,611][ea_next_gen][INFO] Generation 2
[2025-04-06 09:35:11,613][ea_next_gen][INFO] # ------ natural selection
[2025-04-06 09:35:11,687][ea_next_gen][INFO] ranking without duplication (including elite):
[2025-04-06 09:35:11,687][ea_next_gen][INFO] Structure ID      1, fitness:   -0.00530
[2025-04-06 09:35:11,687][ea_next_gen][INFO] Structure ID      3, fitness:    0.01490
[2025-04-06 09:35:11,687][ea_next_gen][INFO] Structure ID      4, fitness:    0.04485
[2025-04-06 09:35:11,687][ea_next_gen][INFO] Structure ID      7, fitness:    0.11501
[2025-04-06 09:35:11,687][ea_next_gen][INFO] Structure ID      8, fitness:    0.15254
[2025-04-06 09:35:11,687][ea_next_gen][INFO] # ------ Generate children
[2025-04-06 09:35:11,687][ea_child][INFO] # -- mindist
[2025-04-06 09:35:11,689][struc_util][INFO] Cu - Cu: 1.32
[2025-04-06 09:35:11,689][struc_util][INFO] Cu - Au: 1.34
[2025-04-06 09:35:11,689][struc_util][INFO] Au - Au: 1.36
[2025-04-06 09:35:11,740][crossover][INFO] Structure ID     10 (8, 8) was generated from      3 and      1 by crossover. Space group:   1 P1
[2025-04-06 09:35:11,764][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2025-04-06 09:35:11,774][crossover][INFO] Structure ID     11 (8, 8) was generated from      3 and      1 by crossover. Space group:   1 P1
[2025-04-06 09:35:11,789][crossover][INFO] Structure ID     12 (8, 8) was generated from      1 and      4 by crossover. Space group:   1 P1
[2025-04-06 09:35:11,833][crossover][INFO] Structure ID     13 (8, 8) was generated from      1 and      3 by crossover. Space group:   1 P1
[2025-04-06 09:35:11,852][crossover][WARNING] mindist in _add_border_line: Cu - Cu, 0.567032320824818. retry.
[2025-04-06 09:35:11,861][crossover][INFO] Structure ID     14 (8, 8) was generated from      7 and      1 by crossover. Space group:   1 P1
[2025-04-06 09:35:11,875][permutation][INFO] Structure ID     15 (8, 8) was generated from      1 by permutation. Space group: 146 R3
[2025-04-06 09:35:11,888][permutation][INFO] Structure ID     16 (8, 8) was generated from      3 by permutation. Space group:   1 P1
[2025-04-06 09:35:11,890][strain][WARNING] mindist in strain: Cu - Cu, 1.3050485787603692. retry.
[2025-04-06 09:35:11,903][strain][INFO] Structure ID     17 (8, 8) was generated from      3 by strain. Space group:   1 P1
[2025-04-06 09:35:11,917][strain][INFO] Structure ID     18 (8, 8) was generated from      1 by strain. Space group:   1 P1
[2025-04-06 09:35:12,513][ea_child][INFO] # ------ Random structure generation
[2025-04-06 09:35:12,513][rs_gen][INFO] # ------ mindist
[2025-04-06 09:35:12,515][struc_util][INFO] Cu - Cu: 1.32
[2025-04-06 09:35:12,515][struc_util][INFO] Cu - Au: 1.34
[2025-04-06 09:35:12,515][struc_util][INFO] Au - Au: 1.36
[2025-04-06 09:35:12,516][rs_gen][INFO] # ------ generate structures
[2025-04-06 09:35:12,530][gen_pyxtal][INFO] Structure ID     19: (8, 8) Space group:  86 -->  86 P4_2/n
[2025-04-06 09:35:12,533][ea_next_gen][INFO] # ------ Select elites
[2025-04-06 09:35:12,533][ea_next_gen][INFO] Structure ID      9 keeps as the elite

After that, simply running cryspy repeatedly will advance the structure search.

Check Results

Last updated: October 16, 2026

cryspy_rslt

The following is an example of cryspy_rslt after completing calculations up to the third generation. In EA, generation information (Gen) is also included.

From v1.5.0, rslt_out in the [option] section controls when cryspy_rslt and cryspy_rslt_energy_asc are written. The default is always. See Input File > [option] Section for details.

    Gen  Spg_num Spg_sym  Spg_num_opt Spg_sym_opt  E_eV_atom  Magmom      Opt
0     1      214  I4_132          230       Ia-3d   1.168743     NaN  no_file
1     1      198   P2_13          198       P2_13  -0.005303     NaN  no_file
2     1       95  P4_322           95      P4_322   0.389566     NaN  no_file
3     1       27    Pcc2           27        Pcc2   0.014898     NaN  no_file
4     1       60    Pbcn           60        Pbcn   0.044852     NaN  no_file
5     1      116   P-4c2          116       P-4c2   0.403246     NaN  no_file
6     1      187   P-6m2          187       P-6m2   1.054706     NaN  no_file
7     1      161     R3c          160         R3m   0.115009     NaN  no_file
8     1      146      R3          146          R3   0.152535     NaN  no_file
9     1       60    Pbcn           47        Pmmm  -0.005676     NaN  no_file
10    2        1      P1            1          P1   0.026070     NaN  no_file
11    2        1      P1            7          Pc   0.005898     NaN  no_file
12    2        1      P1            1          P1   0.005208     NaN  no_file
13    2        1      P1            1          P1   0.005506     NaN  no_file
14    2        1      P1            1          P1   0.024364     NaN  no_file
15    2      146      R3          146          R3   0.011525     NaN  no_file
16    2        1      P1            1          P1   0.014590     NaN  no_file
17    2        1      P1            1          P1   0.015236     NaN  no_file
18    2        1      P1            2         P-1  -0.012335     NaN  no_file
19    2       86  P4_2/n          140      I4/mcm   0.274548     NaN  no_file
20    3        1      P1            1          P1   0.013611     NaN  no_file
21    3        1      P1           10        P2/m  -0.014166     NaN  no_file
22    3        1      P1            1          P1   0.019472     NaN  no_file
23    3        1      P1            1          P1   0.011641     NaN  no_file
24    3        1      P1            1          P1   0.000297     NaN  no_file
25    3        1      P1            1          P1   0.005596     NaN  no_file
26    3        1      P1            1          P1   0.013374     NaN  no_file
27    3        1      P1            2         P-1   0.005055     NaN  no_file
28    3        2     P-1           12        C2/m  -0.012396     NaN  no_file
29    3      182  P6_322          182      P6_322   0.711472     NaN  no_file

ea_info

The EA parameters used in each generation are recorded in ea_info.

Gen Population Crossover Permutation Strain Random Elite crs_lat slct_func
  1         10         0           0      0     10     0  random       TNM
  2         10         5           2      2      1     1  random       TNM
  3         10         5           2      2      1     1  random       TNM

ea_origin

Information about the structure generation method and parent individuals is output to ea_origin.

Gen Struc_ID   Operation   Parent
  1        0      random     None
  1        1      random     None
  1        2      random     None
  1        3      random     None
  1        4      random     None
  1        5      random     None
  1        6      random     None
  1        7      random     None
  1        8      random     None
  1        9      random     None
  2       10   crossover   (3, 1)
  2       11   crossover   (3, 1)
  2       12   crossover   (1, 4)
  2       13   crossover   (1, 3)
  2       14   crossover   (7, 1)
  2       15 permutation     (1,)
  2       16 permutation     (3,)
  2       17      strain     (3,)
  2       18      strain     (1,)
  2       19      random     None
  2        9       elite    elite
  3       20   crossover (18, 12)
  3       21   crossover  (12, 9)
  3       22   crossover (12, 18)
  3       23   crossover  (18, 9)
  3       24   crossover (13, 18)
  3       25 permutation    (18,)
  3       26 permutation     (9,)
  3       27      strain    (18,)
  3       28      strain    (18,)
  3       29      random     None
  3       18       elite    elite

Analysis and Visualization

Last updated: October 16, 2026

Automatic Energy Plotting

Since version 1.4.4, the energy plot is automatically generated after each generation finishes by default.

The figure is saved to ./data/energy_plot/energy_EA_gen_{gen}.{fig_fotmat}.

From version 1.5.0, the output interval in generations can be changed with energy_output_interval in the [option] section. The default is 1 (every generation); 0 disables automatic output. See Input File > [option] Section for details.

The following input variables can be set in the [visual] section of cryspy.in. See also CrySPY > Input file > [visual] section.

...
[visual]
ymax = 0.2
markersize = 10
fig_format = svg
...

Replotting with cryspy-Eplot

If you want to fine-tune the figure and replot it, you can easily do so using the cryspy-Eplot command as follows:

cryspy-Eplot 

When using the cryspy-Eplot command, the following variables can also be specified in the [visual] section in addition to the standard variables above.

• plot_min_gen
• plot_max_gen
• ref_gen

For example, to replot the figure at generation 2, write the [visual] section as follows:

...
[visual]
plot_max_gen = 2
...

Then, run the following command:

cryspy-Eplot 

In this case, CrySPY overwrites ./data/energy_plot/energy_EA_gen_{gen}.{fig_fotmat}.

You can specify the range of generations to be plotted using plot_min_gen and plot_max_gen. When plot_min_gen is set to specify a range (even if its value is 1), the output is saved with a different filename such as ./data/energy_plot/energy_EA_gen_{plot_min_gen}-{plot_max_gen}.{fig_fotmat}, instead of the usual one. For example, to extract only the results of the second generation from the results available at generation 2:

...
[visual]
plot_min_gen = 2
plot_max_gen = 2
...

To change which generation the plot goes up to (i.e., the maximum value of the x-axis), specify the generation with ref_gen. For example, as shown in the image at the top of this page, if three generations have been completed and you want to extract only the results from the second generation, set the [visual] section in cryspy.in as follows:

...
[visual]
plot_max_gen = 2
plot_min_gen = 2
ref_gen = 3
...

If ref_gen is specified, the output filename becomes energy_EA_gen_{plot_min_gen}-{plot_max_gen}_ref_{ref_gen}.{fig_format}.

For more advanced data analysis or figure customization, download the files and use Jupyter Notebook as shown below.

Download Data

It is assumed here that you analyze and visualize CrySPY data on your local PC. If you use CrySPY on a supercomputer or workstation, download the data to your local machine. You can delete the work and backup directories if they are not needed, as their file size can be very large.

Jupyter Notebook

Move to the data/ directory in the results you downloaded earlier. Then, if the CrySPY utility has already been downloaded locally, copy cryspy_analyzer_EA.ipynb. Alternatively, you can download it directly from GitHub (CrySPY_utility/notebook/). Launch Jupyter (e.g., VS Code, Jupyter Lab, or Jupyter Notebook), and simply run the cells in order to obtain a figure like the one shown below.

ASE on Your Local PC (Cu-Ag-Au)

Last updated: October 16, 2026

The files used in this tutorial can be downloaded from CrySPY_utility/examples/ase_Cu-Ag-Au_EA-vc. This tutorial demonstrates a test run on a local machine using ASE’s lightweight Pure Python EMT calculator. The target system is the ternary Cu-Ag-Au system.

cryspy.in

Example of cryspy.in.

[basic]
algo = EA-vc
calc_code = ASE
nstage = 1
njob = 5
jobcmd = zsh
jobfile = job_cryspy

[structure]
atype = Cu Ag Au
ll_nat = 0 0 0
ul_nat = 8 8 8

[ASE]
ase_python = ase_in.py

[EA]
n_pop = 20
n_crsov = 5
n_perm = 2
n_strain = 2
n_rand = 2
n_add = 3
n_elim = 3
n_subs = 3
n_elite = 2
n_fittest = 10
slct_func = TNM
t_size = 2
ref_energies = 0.0 0.0 0.0
maxgen_ea = 0

[option]
rslt_out = always
energy_output_interval = 1
backup_interval = 1

• Use algo = EA-vc.
• From v1.5.0, energy_output_interval in the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default: 1 (every generation); 0 disables automatic output.
• From v1.5.0, backup_interval in the [option] section sets the automatic backup interval in generations. The default is 1; 0 disables automatic backups. See Features > Backup for details.
• When using a bash environment, set jobcmd to bash.
• In the [structure] section, use ll_nat to specify the minimum number of atoms for each element, and ul_nat for the maximum.
• n_pop = n_crsov + n_perm + n_strain + n_rand + n_add + n_elim + n_subs
• The ref_energies (end_point in versions 1.4.3 and earlier) field should be set to the energy per atom (eV/atom) for each pure element—Cu, Ag, and Au. When using ASE’s Pure Python EMT calculator, the energies of the pure elements are zero, so enter 0.0 in each case. (For an example using CHGNet, refer to ASE-CHGNet（Cu-Au）.)
• For the parameters in the [EA] section, refer to CrySPY > Input file > [EA] Section and CrySPY > Search algorithms > Variable-composition evolutionary algorithm (EA-vc).
• Refer also to CrySPY > Tutorial > Variable-composition evolutionary algorithm (EA-VC) > Analysis and Visualization for the parameters of the automatically generated convex hull plot.

calc_in/

The contents under calc_in/ are the same as those in Tutorial > Random Search (RS) > ASE on your local PC.

calc_in/ase_in.py

from ase.constraints import FixSymmetry
from ase.filters import FrechetCellFilter
from ase.calculators.emt import EMT
from ase.optimize import BFGS
import numpy as np
from ase.io import read, write

# ---------- input structure
# CrySPY outputs 'POSCAR' as an input file in work/xxxxxx directory
atoms = read('POSCAR', format='vasp')

# ---------- setting and run
atoms.calc = EMT()
atoms.set_constraint([FixSymmetry(atoms)])
cell_filter = FrechetCellFilter(atoms, hydrostatic_strain=False)
opt = BFGS(cell_filter)

# ---------- run
converged = opt.run(fmax=0.01, steps=2000)

# ---------- rule in ASE interface
# output file for energy: 'log.tote' in eV/cell
#                         CrySPY reads the last line of 'log.tote' file
# outimized structure: 'CONTCAR' file in vasp format
# check_opt: 'out_check_opt' file ('done' or 'not yet')
#                         CrySPY reads the last line of 'out_check_opt' file

# ------ energy
e = cell_filter.atoms.get_total_energy()    # eV/cell
with open('log.tote', mode='w') as f:
    f.write(str(e))

# ------ struc
opt_atoms = cell_filter.atoms.copy()
opt_atoms.set_constraint(None)    # remove constraint for pymatgen
write('CONTCAR', opt_atoms, format='vasp', direct=True)

# ------ check_opt
with open('out_check_opt', mode='w') as f:
    if converged:
        f.write('done\n')
    else:
        f.write('not yet\n')

calc_in/job_cryspy

#!/bin/sh

# ---------- ASE
python3 ase_in.py > out.log

MLIP（Cu-Au）

Last updated: October 16, 2026

The files used in this tutorial can be downloaded from CrySPY_utility/examples/chgnet_Cu-Au_EA-vc. In this tutorial, we assume that a computing cluster with a job scheduler is used together with the machine learning interatomic potential (MLIP) CHGNet. By changing the Calculator, you can use a variety of MLIPs. The calculation can also be performed on a local PC, so if you prefer this, please modify the input settings accordingly. The target system is the binary Cu-Au system.

Pre-Calculation

In EA-vc, the per-atom energies of each elemental phase must be used as the reference in the ref_energies (end_point in versions 1.4.3 and earlier) setting of cryspy.in, so they need to be calculated beforehand. There should be two directories inside the example.

Au_fcc
├── POSCAR
├── chgnet_in.py
└── job_cryspy

Cu_fcc
├── POSCAR
├── chgnet_in.py
└── job_cryspy

Each directory contains a crystal structure file (POSCAR), a Python script (chgnet_in.py) to perform structure relaxation and calculate energy, and a job script (job_cryspy). Please modify these files according to your computing environment.

Submit the job (replace the job submission command as appropriate for your system).

cd Au_fcc
qsub job_cryspy
cd ../Cu_fcc
qsub job_cryspy
cd ..

When the calculations finish successfully, a file named ref_energies will be created in each directory, containing the energy per atom (eV/atom) after structure relaxation.

cat Au_fcc/ref_energies
-3.2357187271118164

cat Cu_fcc/ref_energies
-4.083529472351074

These values are then used as input for the cryspy.in file.

cryspy.in

[basic]
algo = EA-vc
calc_code = ASE
nstage = 1
njob = 20
jobcmd = qsub
jobfile = job_cryspy

[structure]
atype = Cu Au
ll_nat = 0 0
ul_nat = 8 8

[ASE]
ase_python = chgnet_in.py

[EA]
n_pop = 20
n_crsov = 5
n_perm = 2
n_strain = 2
n_rand = 2
n_add = 3
n_elim = 3
n_subs = 3
n_elite = 2
n_fittest = 10
slct_func = TNM
t_size = 2
maxgen_ea = 0
ref_energies = -4.08352709  -3.23571777

[option]
rslt_out = always
energy_output_interval = 1
backup_interval = 1

• Use algo = EA-vc.
• From v1.5.0, energy_output_interval in the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default: 1 (every generation); 0 disables automatic output.
• From v1.5.0, backup_interval in the [option] section sets the automatic backup interval in generations. The default is 1; 0 disables automatic backups. See Features > Backup for details.
• Since MLIPs use the ASE Calculator interface, set calc_code = ASE.
• Change jobcmd according to your computing environment.
• In the [structure] section, use ll_nat to specify the minimum number of atoms for each element, and ul_nat for the maximum.
• n_pop = n_crsov + n_perm + n_strain + n_rand + n_add + n_elim + n_subs
• In the ref_energies (end_point in versions 1.4.3 and earlier), enter the per-atom energies (in eV/atom) of each pure element—Cu and Au. Use the values obtained from the pre-calculations, and make sure the order follows that of atype.
• For the parameters in the [EA] section, refer to CrySPY > Input file > [EA] Section and CrySPY > Search algorithms > Variable-composition evolutionary algorithm (EA-vc).
• Refer also to CrySPY > Tutorial > Variable-composition evolutionary algorithm (EA-VC) > Analysis and Visualization for the parameters of the automatically generated convex hull plot.

calc_in/

The contents under calc_in/ are the same as those in Tutorial > Random Search (RS) > ASE on your local PC, with minor modifications for CHGNet. Be sure to adjust paths such as the Python executable in the job script to match your computing environment. Be sure to adjust the Python executable path in the job script.

calc_in/chgnet_in.py

# ---------- import
from ase.constraints import FixSymmetry
from ase.filters import FrechetCellFilter
from ase.io import read, write
from ase.optimize import FIRE, BFGS, LBFGS
from chgnet.model import CHGNetCalculator

# ---------- input structure
# CrySPY outputs 'POSCAR' as an input file in work/xxxxxx directory
atoms = read('POSCAR')

# ---------- set up
atoms.calc = CHGNetCalculator()
atoms.set_constraint([FixSymmetry(atoms)])
cell_filter = FrechetCellFilter(atoms)
opt = BFGS(cell_filter, trajectory='opt.traj')

# ---------- run
converged = opt.run(fmax=0.01, steps=2000)

# ---------- rule in ASE interface
# output file for energy: 'log.tote' in eV/cell
#                         CrySPY reads the last line of 'log.tote' file
# outimized structure: 'CONTCAR' file in vasp format
# check_opt: 'out_check_opt' file ('done' or 'not yet')
#                         CrySPY reads the last line of 'out_check_opt' file

# ------ energy
e = cell_filter.atoms.get_total_energy()    # eV/cell
with open('log.tote', mode='w') as f:
    f.write(str(e))

# ------ struc
opt_atoms = cell_filter.atoms.copy()
opt_atoms.set_constraint(None)    # remove constraint for pymatgen
write('CONTCAR', opt_atoms, format='vasp', direct=True)

# ------ check_opt
with open('out_check_opt', mode='w') as f:
    if converged:
        f.write('done\n')
    else:
        f.write('not yet\n')

calc_in/job_cryspy

#!/bin/sh
#$ -cwd
#$ -V -S /bin/bash
####$ -V -S /bin/zsh
#$ -N CuAu_CrySPY_ID
#$ -pe smp 2

# ---------- OpenMP
export OMP_NUM_THREADS=2

# ---------- ASE
/usr/local/Python-3.10.13/bin/python3 chgnet_in.py > out.log

VASP（Fe-Al）

Last updated: October 16, 2026

EA-vc became compatible with VASP in version 1.4.2.

The files used here can be downloaded from CrySPY_utility/examples/vasp_Fe-Al_EA-vc. This tutorial assumes calculations are performed on a computer cluster with a job scheduler using VASP. The target system is a binary Fe-Al alloy, and calculations are performed assuming ferromagnetism.

Pre-Calculation

In EA-vc, the per-atom energies of each elemental phase must be used as the reference in the ref_energies (end_point in versions 1.4.3 and earlier) setting of cryspy.in, so they need to be calculated beforehand. There should be two directories inside the example.

Al-fcc
├── POSCAR
├── INCAR
├── POTCAR_dummy
└── job_cryspy

Fe-bcc
├── POSCAR
├── INCAR
├── POTCAR_dummy
└── job_cryspy

Crystal structure data (POSCAR), input files for structure optimization and energy calculation (INCAR), and job scripts (job_cryspy) are provided, so edit them as needed to match your computing environment. Also, the POTCAR files cannot be distributed, so please prepare them yourself.

In the INCAR file, be sure to use the same cutoff and other values for the single-element calculations as you will use in the final calculations.

Run the jobs (replace the job submission command as appropriate for your environment).

cd Al_fcc
qsub job_cryspy
cd ../Fe_bcc
qsub job_cryspy
cd ..

After the calculations are finished, obtain the energy per atom. In this case, since BCC and FCC unit cells each contain one atom, you can use the total energy value directly. Normally, divide the total energy by the number of atoms in the unit cell to obtain the per-atom energy.

cryspy.in

cryspy.in

[basic]
algo = EA-vc
calc_code = VASP
nstage = 2
njob = 10
jobcmd = qsub
jobfile = job_cryspy

[structure]
atype =  Fe Al
ll_nat =  0  0
ul_nat =  8  8

[VASP]
kppvol = 40 120
vasp_MAGMOM = 4.0 0.0

[EA]
n_pop = 20
n_crsov = 5
n_perm = 2
n_strain = 2
n_rand = 2
n_add = 3
n_elim = 3
n_subs = 3
n_elite = 2
n_fittest = 10
slct_func = TNM
t_size = 2
maxgen_ea = 0
ref_energies = -8.24249611  -3.74226843

[option]
rslt_out = always
energy_output_interval = 1
backup_interval = 1

• Use algo = EA-vc.
• From v1.5.0, energy_output_interval in the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default: 1 (every generation); 0 disables automatic output.
• From v1.5.0, backup_interval in the [option] section sets the automatic backup interval in generations. The default is 1; 0 disables automatic backups. See Features > Backup for details.
• Change jobcmd according to your computing environment.
• In the [structure] section, use ll_nat to specify the minimum number of atoms for each element, and ul_nat for the maximum.
• n_pop = n_crsov + n_perm + n_strain + n_rand + n_add + n_elim + n_subs
• In the ref_energies (end_point in versions 1.4.3 and earlier), enter the per-atom energies (in eV/atom) of each pure element—Cu and Au. Use the values obtained from the pre-calculations, and make sure the order follows that of atype.
• For the parameters in the [EA] section, refer to CrySPY > Input file > [EA] Section and CrySPY > Search algorithms > Variable-composition evolutionary algorithm (EA-vc).
• Refer also to CrySPY > Tutorial > Variable-composition evolutionary algorithm (EA-VC) > Analysis and Visualization for the parameters of the automatically generated convex hull plot.

For VASP

In the [VASP] section, specify the MAGMOM values for each element corresponding to atype in vasp_MAGMOM. When CrySPY copies the INCAR file to ./work/xxx/INCAR (where xxx is the structure ID), it appends n*vasp_MAGMOM (n is the number of atoms).

For example, if atype = (‘Fe’, ‘Al’), nat = (5, 3), and vasp_MAGMOM = (4.0 0.0), the following will be appended.

MAGMOM = 5*4.0 3*0.0

Although not used in this tutorial, INCAR’s LDAUL, LDAUU, and LDAUJ are also supported. In cryspy.in, they are used with the vasp_ prefix as follows:

[VASP]
kppvol = 40 120
vasp_MAGMOM = 4.0 0.0
vasp_LDAUL = 2 -1
vasp_LDAUU = 4.0 0.0
vasp_LDAUJ = 0.0 0.0

If the system changes from a binary alloy to a single element, such as nat = (5, 0), CrySPY will append the following to ./work/xxx/INCAR. No action is taken for elements with an atomic number of zero.

MAGMOM = 5*4.0
LDAUL = 2
LDAUU = 4.0
LDAUJ = 0.0

calc_in/

POTCAR

In EA-vc, prepare a separate POTCAR file for each element. The file names should be:

• POTCAR_Fe
• POTCAR_Al

Add the element name as written in atype to the end of the file name. CrySPY prepares ./work/xxx/POTCAR according to the number of atoms in the structure. For example, if the structure consists only of Fe (nat = (5, 0)), use POTCAR_Fe. If the structure is Fe-Al (nat = (4, 4)), concatenate POTCAR_Fe and POTCAR_Al to create POTCAR.

job_cryspy

#!/bin/sh
#$ -cwd
#$ -V -S /bin/bash
####$ -V -S /bin/zsh
#$ -N FeAl_CrySPY_ID
#$ -pe smp 32


# ---------- vasp
VASPROOT=/usr/local/vasp/vasp.6.4.2/bin
mpirun -np $NSLOTS $VASPROOT/vasp_std

INCAR

1_INCAR

SYSTEM = FeAl

Algo = Fast
####LREAL = Auto
ENCUT = 348

ISMEAR = 1
SIGMA = 0.1

NSW = 40
IBRION = 2
ISIF = 2

ISPIN = 2
######MAGMOM =   # cryspy append MAGMOM in work/xx/INCAR 

EDIFF = 1e-6
EDIFFG = -0.01

KPAR = 4

LWAVE = .FALSE.
LCHARG = .FALSE.

2_INCAR

SYSTEM = FeAl

Algo = Fast
####LREAL = Auto
ENCUT = 348

ISMEAR = 1
SIGMA = 0.1

NSW = 200
IBRION = 2
ISIF = 3

ISPIN = 2
######MAGMOM =   # cryspy append MAGMOM in work/xx/INCAR 

EDIFF = 1e-6
EDIFFG = -0.01

KPAR = 4

LWAVE = .FALSE.
LCHARG = .FALSE.

QE（Fe-Al）

Last updated: October 16, 2026

EA-vc became compatible with QE in version 1.4.2.

The files used here can be downloaded from CrySPY_utility/examples/qe_Fe-Al_EA-vc. This tutorial assumes calculations are performed on a computer cluster with a job scheduler using QE. The target system is a binary Fe-Al alloy, and calculations are performed assuming ferromagnetism.

Pre-Calculation

In EA-vc, the per-atom energies of each elemental phase must be used as the reference in the ref_energies (end_point in versions 1.4.3 and earlier) setting of cryspy.in, so they need to be calculated beforehand. There should be two directories inside the example.

Al-fcc
├── pwscf.in
└── job_cryspy

Fe-bcc
├── pwscf.in
└── job_cryspy

Input files (pwscf.in) and job scripts (job_cryspy) are provided, so edit them as needed to match your computing environment.

In the pwscf.in file, be sure to use the same cutoff and other values for the single-element calculations as you will use in the final calculations.

Run the jobs (replace the job submission command as appropriate for your environment).

cd Al_fcc
qsub job_cryspy
cd ../Fe_bcc
qsub job_cryspy
cd ..

After the calculations are finished, convert the energy per atom to eV units. In this case, since BCC and FCC unit cells each contain one atom, you can use the total energy value directly. Normally, divide the total energy by the number of atoms in the unit cell to obtain the per-atom energy.

cryspy.in

cryspy.in

[basic]
algo = EA-vc
calc_code = QE
nstage = 2
njob = 10
jobcmd = qsub
jobfile = job_cryspy

[structure]
atype =  Fe Al
ll_nat =  0  0
ul_nat =  8  8

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

[EA]
n_pop = 20
n_crsov = 5
n_perm = 2
n_strain = 2
n_rand = 2
n_add = 3
n_elim = 3
n_subs = 3
n_elite = 2
n_fittest = 10
slct_func = TNM
t_size = 2
maxgen_ea = 6
ref_energies = -3406.14117375  -91.25463006

[option]
rslt_out = always
energy_output_interval = 1
backup_interval = 1

• Use algo = EA-vc.
• From v1.5.0, energy_output_interval in the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default: 1 (every generation); 0 disables automatic output.
• From v1.5.0, backup_interval in the [option] section sets the automatic backup interval in generations. The default is 1; 0 disables automatic backups. See Features > Backup for details.
• Change jobcmd according to your computing environment.
• In the [structure] section, use ll_nat to specify the minimum number of atoms for each element, and ul_nat for the maximum.
• n_pop = n_crsov + n_perm + n_strain + n_rand + n_add + n_elim + n_subs
• In the ref_energies (end_point in versions 1.4.3 and earlier), enter the per-atom energies (in eV/atom) of each pure element—Cu and Au. Use the values obtained from the pre-calculations, and make sure the order follows that of atype.
• For the parameters in the [EA] section, refer to CrySPY > Input file > [EA] Section and CrySPY > Search algorithms > Variable-composition evolutionary algorithm (EA-vc).
• Refer also to CrySPY > Tutorial > Variable-composition evolutionary algorithm (EA-VC) > Analysis and Visualization for the parameters of the automatically generated convex hull plot.

For QE

Unlike VASP, support for variable-composition in QE is straightforward. For binary system searches, always prepare binary system inputs in ./calc_in, and for ternary systems, always prepare ternary system inputs. However, only nat needs to be changed, so CrySPY automatically rewrites it. When preparing, write nat with any appropriate number as shown below:

nat = 1

In ./work/xxx/, CrySPY automatically rewrites lines that start with nat (excluding leading whitespace) to:

    nat = (actual number of atoms)

calc_in/

job_cryspy

#!/bin/sh
#$ -cwd
#$ -V -S /bin/bash
####$ -V -S /bin/zsh
#$ -N FeAl_CrySPY_ID
#$ -pe smp 32


QEROOT=/usr/local/qe/q-e-qe-7.3.1/bin
mpirun -np $NSLOTS $QEROOT/pw.x -nk 4 < pwscf.in > pwscf.out


if [ -e "CRASH" ]; then
    sed -i -e '3 s/^.*$/skip/' stat_job
    exit 1
fi

pwscf.in

1_pwscf.in

&control
calculation = 'relax'
nstep = 40
pseudo_dir = '/usr/local/qe/gbrv/all_pbe_UPF_v1.5/'
outdir='./outdir/'
/


&system
ibrav = 0
nat = 1
ntyp = 2
ecutwfc = 40
ecutrho = 200

occupations = "smearing"
smearing    = "mp"
degauss     =  0.01

nspin = 2
starting_magnetization(1) = 0.4
starting_magnetization(2) = 0.0
/


&electrons
mixing_beta = 0.4
/

&ions
/

&cell
/

ATOMIC_SPECIES
Fe -1.0 fe_pbe_v1.5.uspp.F.UPF
Al -1.0 al_pbe_v1.uspp.F.UPF

2_pwscf.in

&control
calculation = 'vc-relax'
nstep = 200
pseudo_dir = '/usr/local/qe/gbrv/all_pbe_UPF_v1.5/'
outdir='./outdir/'
/


&system
ibrav = 0
nat = 1
ntyp = 2
ecutwfc = 40
ecutrho = 200

occupations = "smearing"
smearing    = "mp"
degauss     =  0.01

nspin = 2
starting_magnetization(1) = 0.4
starting_magnetization(2) = 0.0
/


&electrons
mixing_beta = 0.4
/

&ions
/

&cell
/

ATOMIC_SPECIES
Fe -1.0 fe_pbe_v1.5.uspp.F.UPF
Al -1.0 al_pbe_v1.uspp.F.UPF

Create Next Generation

Last updated: October 16, 2026

First Run

When you run cryspy, the program enters structure generation mode. It generates the first generation of random structures and then exits.

cryspy

It can be confirmed from the output that structures are generated with the number of atoms within the range specified by ll_nat and ul_nat.

...
[2026-07-07 15:18:02,548][cryspy_init][INFO] # ---------- Initial structure generation
[2026-07-07 15:18:02,548][rs_gen][INFO] # ------ mindist
[2026-07-07 15:18:02,549][struc_util][INFO] Cu - Cu: 1.32
[2026-07-07 15:18:02,549][struc_util][INFO] Cu - Ag: 1.385
[2026-07-07 15:18:02,549][struc_util][INFO] Cu - Au: 1.34
[2026-07-07 15:18:02,549][struc_util][INFO] Ag - Ag: 1.45
[2026-07-07 15:18:02,549][struc_util][INFO] Ag - Au: 1.405
[2026-07-07 15:18:02,549][struc_util][INFO] Au - Au: 1.36
[2026-07-07 15:18:02,549][rs_gen][INFO] # ------ Generate random structures
[2026-07-07 15:18:02,712][gen_pyxtal][INFO] Structure ID      0: (6, 6, 2) Space group: 196 --> 216 F-43m
[2026-07-07 15:18:02,721][gen_pyxtal][WARNING] Compoisition [7 5 3] not compatible with symmetry 224:     spg = 224 retry.
[2026-07-07 15:18:02,726][gen_pyxtal][WARNING] Compoisition [3 3] not compatible with symmetry 134:     spg = 134 retry.
[2026-07-07 15:18:02,733][gen_pyxtal][WARNING] Compoisition [ 6  4 16] not compatible with symmetry 140:     spg = 140 retry.
[2026-07-07 15:18:02,822][gen_pyxtal][INFO] Structure ID      1: (1, 4, 3) Space group:  23 -->  71 Immm
[2026-07-07 15:18:02,839][gen_pyxtal][INFO] Structure ID      2: (2, 2, 8) Space group: 150 --> 150 P321
...

The file cryspy.stat shows that the current generation’s information is being added during the EA process.

[status]
generation = 1
id_queueing = 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

Optimize Structures

After running cryspy several times and completing the structure optimization for the first generation, the output will appear as shown below.

...
[2026-07-07 15:21:18,273][ea_next_gen][INFO] Done generation 1
[2026-07-07 15:21:18,273][ea_next_gen][INFO] Calculate convex hull for generation 1
Ignoring fixed y limits to fulfill fixed data aspect with adjustable data limits.
[2026-07-07 15:21:18,772][ea_next_gen][INFO] 
EA is ready

Convex Hull

At this point, the hull distance data and the convex hull plot have been output to ./data/convex_hull/.

• hull_dist_all_gen_1

      ID    hull distance (eV/atom)    Num_atom
      14                   0.000000    (0, 1, 3)
       9                   0.088493    (2, 8, 8)
      15                   0.105278    (8, 7, 5)
      10                   0.200962    (8, 0, 7)
       8                   0.210806    (0, 3, 3)
      13                   0.247862    (5, 6, 8)
      19                   0.258563    (6, 6, 1)
       5                   0.261977    (2, 6, 4)
       6                   0.269711    (7, 7, 2)
      18                   0.290792    (1, 6, 6)
      11                   0.292541    (8, 3, 1)
      16                   0.356158    (6, 2, 4)
       2                   0.373888    (2, 2, 8)
       7                   0.514507    (0, 4, 4)
      12                   0.548770    (3, 4, 4)
       1                   0.617685    (1, 4, 3)
       3                   0.761585    (1, 0, 8)
      17                   0.934091    (6, 4, 7)
       4                   0.955053    (2, 8, 4)
       0                   1.019078    (6, 6, 2)

• conv_hull_gen_1.svg

Create Next Generation

Once all preparations are complete, running cryspy again starts generating the next-generation structures. By default (backup_interval = 1), an automatic backup is performed immediately before generating these structures. From v1.5.0, backup_interval in the [option] section can be used to change the interval in generations; 0 disables automatic backups. See Features > Backup for details.

cryspy

...
[2026-07-07 15:29:32,182][ea_next_gen][INFO] Done generation 1
[2026-07-07 15:29:32,505][utility][INFO] Backup data
[2026-07-07 15:29:32,512][ea_next_gen][INFO] # ---------- Evolutionary algorithm
[2026-07-07 15:29:32,512][ea_next_gen][INFO] Generation 2
[2026-07-07 15:29:32,512][ea_next_gen][INFO] # ------ Apply nat/composition constraints
[2026-07-07 15:29:32,512][ea_next_gen][INFO] Current candidates after constraint filter: 20
[2026-07-07 15:29:32,513][ea_next_gen][INFO] Elite structures after constraint filter: 0
[2026-07-07 15:29:32,513][ea_next_gen][INFO] # ------ natural selection
[2026-07-07 15:29:32,515][ea_next_gen][INFO] ranking without duplication (including elite):
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID     14, fitness:    0.00000
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID      9, fitness:    0.08849
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID     15, fitness:    0.10528
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID     10, fitness:    0.20096
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID      8, fitness:    0.21081
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID     13, fitness:    0.24786
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID     19, fitness:    0.25856
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID      5, fitness:    0.26198
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID      6, fitness:    0.26971
[2026-07-07 15:29:32,515][ea_next_gen][INFO] Structure ID     18, fitness:    0.29079
[2026-07-07 15:29:32,515][ea_next_gen][INFO] # ------ Generate children
[2026-07-07 15:29:32,515][ea_child][INFO] # -- mindist
[2026-07-07 15:29:32,517][struc_util][INFO] Cu - Cu: 1.32
[2026-07-07 15:29:32,517][struc_util][INFO] Cu - Ag: 1.385
[2026-07-07 15:29:32,517][struc_util][INFO] Cu - Au: 1.34
[2026-07-07 15:29:32,517][struc_util][INFO] Ag - Ag: 1.45
[2026-07-07 15:29:32,517][struc_util][INFO] Ag - Au: 1.405
[2026-07-07 15:29:32,517][struc_util][INFO] Au - Au: 1.36
[2026-07-07 15:29:32,521][ea_child][INFO] eligible candidates for crossover and strain: 10
[2026-07-07 15:29:32,521][ea_child][INFO] eligible candidates for permutation: 10
[2026-07-07 15:29:32,521][ea_child][INFO] eligible candidates for addition: 10
[2026-07-07 15:29:32,522][ea_child][INFO] eligible candidates for elimination: 10
[2026-07-07 15:29:32,522][ea_child][INFO] eligible candidates for substitution: 10
[2026-07-07 15:29:32,527][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,532][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,537][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,541][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,547][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,551][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,556][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,561][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,564][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,569][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,592][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,622][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,644][crossover][WARNING] remove_within_mindist: some atoms within mindist. retry.
[2026-07-07 15:29:32,667][crossover][INFO] Structure ID     20 (8, 3, 5) was generated from     10 and     15 by crossover. Space group:   1 P1
[2026-07-07 15:29:32,668][crossover][INFO] Structure ID     21 (0, 1, 5) was generated from     14 and      8 by crossover. Space group:   1 P1
...
...
...
[2026-07-07 15:29:33,401][ea_next_gen][INFO] # ------ Apply nat/composition constraints to elite candidates
[2026-07-07 15:29:33,401][ea_next_gen][INFO] Elite candidates after constraint filter: 20
[2026-07-07 15:29:33,401][ea_next_gen][INFO] Structure ID     14 keeps as the elite
[2026-07-07 15:29:33,401][ea_next_gen][INFO] Structure ID      9 keeps as the elite

After that, simply running cryspy repeatedly will advance the structure search.

Check Results

Last updated: October 16, 2026

This section focuses on the differences from the EA method.

cryspy_rslt

Below is an example of a cryspy_rslt file after completing calculations up to the third generation. In EA-vc, formation energy (Ef_eV_atom) and number of atoms (Num_atom) are also included.

From v1.5.0, rslt_out in the [option] section controls when cryspy_rslt and cryspy_rslt_energy_asc are written. The default is always. See Input File > [option] Section for details.

    Gen  Spg_num   Spg_sym  Spg_num_opt Spg_sym_opt  E_eV_atom  Ef_eV_atom   Num_atom  Magmom   Opt
0     1      216     F-43m          216       F-43m   1.016698    1.016698  (6, 6, 2)     NaN  done
1     1       71      Immm           71        Immm   0.611438    0.611438  (1, 4, 3)     NaN  done
2     1      150      P321          150        P321   0.365560    0.365560  (2, 2, 8)     NaN  done
3     1      191    P6/mmm          191      P6/mmm   0.761585    0.761585  (1, 0, 8)     NaN  done
4     1      139    I4/mmm          139      I4/mmm   0.950294    0.950294  (2, 8, 4)     NaN  done
5     1       59      Pmmn           59        Pmmn   0.256424    0.256424  (2, 6, 4)     NaN  done
6     1       16      P222           16        P222   0.267629    0.267629  (7, 7, 2)     NaN  done
7     1      183      P6mm          191      P6/mmm   0.506178    0.506178  (0, 4, 4)     NaN  done
8     1       35      Cmm2           35        Cmm2   0.202477    0.202477  (0, 3, 3)     NaN  done
9     1       32      Pba2           32        Pba2   0.081089    0.081089  (2, 8, 8)     NaN  done
10    1      148       R-3          148         R-3   0.200962    0.200962  (8, 0, 7)     NaN  done

Checking Results for a Specific Composition

From v1.5.0, the -c (--composition) option of cryspy-print displays only results with a specified composition ratio from rslt_data.pkl. Specify the ratio in atype order. In this example, atype = Cu Ag Au, so the following command selects structures with no Cu and an Ag:Au ratio of 1:1.

cryspy-print data/pkl_data/rslt_data.pkl -c 0 1 1 --all

Ratios are reduced before comparison, so IDs 7 and 8 in the table above, with Num_atom values of (0, 4, 4) and (0, 3, 3), both match. Matching results are displayed in ascending order of formation energy (Ef_eV_atom). --all displays all matching rows; replace it with --head 10 to display only the ten lowest-energy results.

Output for the data in the table above:

   Gen  Spg_num Spg_sym  Spg_num_opt Spg_sym_opt  E_eV_atom  Ef_eV_atom   Num_atom  Magmom   Opt
8    1       35    Cmm2           35        Cmm2   0.202477    0.202477  (0, 3, 3)     NaN  done
7    1      183    P6mm          191      P6/mmm   0.506178    0.506178  (0, 4, 4)     NaN  done

nat_data

Information on the number of atoms and composition is also included in nat_data.

      ID    ('Cu', 'Ag', 'Au')    Composition
       0    (    6,     6,     2)    (0.429, 0.429, 0.143)
       1    (    1,     4,     3)    (0.125, 0.500, 0.375)
       2    (    2,     2,     8)    (0.167, 0.167, 0.667)
       3    (    1,     0,     8)    (0.111, 0.000, 0.889)
       4    (    2,     8,     4)    (0.143, 0.571, 0.286)
       5    (    2,     6,     4)    (0.167, 0.500, 0.333)
       6    (    7,     7,     2)    (0.438, 0.438, 0.125)
       7    (    0,     4,     4)    (0.000, 0.500, 0.500)
       8    (    0,     3,     3)    (0.000, 0.500, 0.500)
       9    (    2,     8,     8)    (0.111, 0.444, 0.444)
      10    (    8,     0,     7)    (0.533, 0.000, 0.467)
...

hull_dist_all_gen_x

With the default settings, for example, after the third generation is completed, the hull distance data is output to the file ./data/convex_hull/hull_dist_all_gen_3. The output interval is set with energy_output_interval in the [option] section. The default is 1 (every generation); 0 disables automatic file output. See Input File > [option] Section for details.

      ID    hull distance (eV/atom)    Num_atom
      21                   0.000000    (0, 1, 5)
      46                   0.000000    (0, 1, 3)
      49                   0.000000    (0, 2, 3)
      56                   0.000000    (3, 0, 1)
      14                   0.000000    (0, 1, 3)
      28                   0.000001    (0, 1, 3)
      48                   0.002585    (0, 1, 3)
      45                   0.006762    (2, 8, 8)
      26                   0.007389    (2, 8, 8)
...

conv_hull_gen_x.svg

With the default settings, the convex hull plot at the end of generation 3 is saved as ./data/convex_hull/conv_hull_gen_3.svg. Automatic output of the convex hull plot follows the same energy_output_interval setting. Although svg is the default format, it can be changed to pdf or png by modifying the fig_format in the input file.

Analysis and Visualization

Last updated: October 16, 2026

Automatic Convex Hull Plotting

In EA-vc simulations of binary and ternary systems, a convex hull plot is automatically generated at the end of each generation by default. The figure is saved to ./data/convex_hull/conv_hull_gen_{gen}.{fig_fotmat}.

From version 1.5.0, the output interval in generations can be changed with energy_output_interval in the [option] section. The default is 1 (every generation); 0 disables automatic output of the convex-hull plot and hull-distance file. The convex hull and hull distances are still calculated every generation. See Input File > [option] Section for details.

Binary System

The above figures show examples after the search up to the third generation. The following input variables can be set in the [visual] section of cryspy.in. See also CrySPY > Input file > [visual] section.

...
[visual]
ymax = 0.2
markersize = 10
fig_format = svg
label_stable = True
vmax = 0.2
bottom_margin = 0.04
axis_order = lr
...

Here, vmax is the maximum value of the colorbar for the hull distance, and bottom_margin is the margin between the minimum formation energy and the lower limit of the y-axis. As shown in the left figure, when axis_order = lr (the default setting), the convex hull plot is drawn so that atype[0] is on the left and atype[1] is on the right. The right figure shows the case with axis_order = rl. That is, when atype = Cu Au, the pure Cu crystal is placed on the right side of the plot, while the pure Au crystal is placed on the left.

Ternary System

The figures above show the examples for a ternary system. The following input variables can be set in the [visual] section of cryspy.in. See also CrySPY > Input file > [visual] section.

...
[visual]
markersize = 10
fig_format = svg
###show_max = 0.4
label_stable = True
vmax = 0.2
axis_order = tlr
...

Here, show_max specifies the maximum hull distance shown in ternary systems. In the above example, it is commented out, so the default value None is applied. When axis_order = tlr (the default setting), atype[0], atype[1], and atype[2] are placed at the top, left, and right vertices, respectively, in the ternary convex hull plot, as shown in the left figure. Adjust the vertex order accordingly for other permutations such as trl, ltr, etc. The right figure shows an example with axis_order = ltr. For atype = Cu Ag Au, Cu is placed at the left vertex, Ag at the top vertex, and Au at the right vertex.

Charge Neutrality Condition

The following convex hull plots show examples with a charge neutrality condition imposed by specifying charge. See Features > Charge Neutrality Condition for input examples and details on specifying charges.

Binary examples: single-valence (left) and multi-valence (right).

• single-valence: (Cu, Au) = (+1, -1)
• multi-valence: (Cu, Au) = ((+2, +3), -2)

Ternary examples: single-valence (left) and multi-valence (right).

• single-valence: (Cu, Ag, Au) = (+1, +2, -1)
• multi-valence: (Cu, Ag, Au) = (+1, (+2, +3), -2)

Composition Constraints

From version 1.5.0, min_comp and max_comp can restrict the composition range explored by the search. When composition constraints are set, the allowed range is shown as a blue region in the convex hull plot. See Features > Composition Constraints for input examples and an explanation of the plots.

Examples of search results through generation 3 for binary (left) and ternary (right) systems.