Tutorial
.
Info
Subsections of Tutorial
Random Search (RS)
Info
ASE is easy to start for beginners because when you install CrySPY, ASE is also automatically installed. Although not highly accurate, ASE provides very lightweight and fast interatomic potentials, making it suitable for testing on a laptop or other low-spec machines.
Preparation of Input Files
Follow one of the instructions below, then proceed to the section on running CrySPY.
Running CrySPY
Subsections of Random Search (RS)
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
cryspy.in
cryspy.in is the input file of CrySPY.
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_cryspyase_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.
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)
Note
For versions older than 1.4.2, the last line of the job file must be written as sed -i -e '3s/^sub.*/done/' stat_job. If you use a job file with this sed command in version 1.4.2 or later, it will simply be executed twice, which does not cause any problems.
The meaning of the above sed command is to change the part starting with “sub” in the third line of the file stat_job to “done”.
Tip
(Detail: Features > Job file auto-rewriting)
In the job file of CrySPY, the string CrySPY_ID is automatically replaced with the structure ID.
When you use a job scheduler such as PBS and SLURM, it is useful to set the structure ID to the job name.
For example, in the PBS system, #PBS -N Si_CrySPY_ID in ID 10 is replaced with #PBS -N Si_10.
Note that starting with a number will result in an error.
You should add a prefix like Si_.
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:
x_ase_in.pyase_in.py_xase_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).
Unlike VASP and QE, the ASE input (python script) is more flexible. CrySPY has three rules:
- Energy is output in units of eV/cell to
log.totefile. CrySPY reads the last line of it. - Optimized structure is output to
CONTCARfile in the VASP format. - The result of the optimization convergence check should be written as either
doneornot_yetin a file namedout_check_opt. CrySPY reads the last line of this file.
Running CrySPY
Go to Running CrySPY
soiap on Your Local PC
Info
The information written here is slightly outdated, so please refer to the latest tutorial: Tutorial > Random Search (RS) > ASE on your local PC. The content on this page should still work without any issues.
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 .
cryspy.in
cryspy.in is the input file of CrySPY.
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:
jobfilesoiap_infilesoiap_outfilesoiap_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.
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.
Note
sed -i -e '3 s/^.*$/done/' stat_job is required at the end of the job file.
Tip
In the job file of CrySPY, the string “CrySPY_ID” is automatically replaced with the structure ID.
When you use a job scheduler such as PBS and SLURM, it is useful to set the structure ID to the job name.
For example, in the PBS system, #PBS -N Si_CrySPY_ID in ID 10 is replaced with #PBS -N Si_10.
Note that starting with a number will result in an error.
You should add a prefix like Si_.
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.
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
cryspy.in
cryspy.in is the input file of CrySPY.
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.
Info
See Input file > Kpoint for details of 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.
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)
Note
For versions older than 1.4.2, the last line of the job file must be written as sed -i -e '3s/^sub.*/done/' stat_job. If you use a job file with this sed command in version 1.4.2 or later, it will simply be executed twice, which does not cause any problems.
The meaning of the above sed command is to change the part starting with “sub” in the third line of the file stat_job to “done”.
Tip
(Detail: Features > Job file auto-rewriting)
In the job file of CrySPY, the string CrySPY_ID is automatically replaced with the structure ID.
When you use a job scheduler such as PBS and SLURM, it is useful to set the structure ID to the job name.
For example, in the PBS system, #PBS -N Si_CrySPY_ID in ID 10 is replaced with #PBS -N Si_10.
Note that starting with a number will result in an error.
You should add a prefix like Si_.
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:
x_INCARINCAR_xINCAR
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
2_INCAR
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.
Warning
POTCAR in this example is empty. We cannot distribute it.
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 .
cryspy.in
cryspy.in is the input file of CrySPY.
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.
Info
See Input file > Kpoint for details of kppvol
You can name the following files whatever you want:
jobfileqe_infileqe_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.
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)
Note
For versions older than 1.4.2, the last line of the job file must be written as sed -i -e '3s/^sub.*/done/' stat_job. If you use a job file with this sed command in version 1.4.2 or later, it will simply be executed twice, which does not cause any problems.
The meaning of the above sed command is to change the part starting with “sub” in the third line of the file stat_job to “done”.
Tip
(Detail: Features > Job file auto-rewriting)
In the job file of CrySPY, the string “CrySPY_ID” is automatically replaced with the structure ID.
When you use a job scheduler such as PBS and SLURM, it is useful to set the structure ID to the job name.
For example, in the PBS system, #PBS -N Si_CrySPY_ID in ID 10 is replaced with #PBS -N Si_10.
Note that starting with a number will result in an error.
You should add a prefix like Si_.
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:
x_pwscf.inpwscf.in_xpwscf.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
1_pwscf.in
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] Section
algo: Algorithm. SetRSfor Random Search.calc_code: Structure optimizer. Choose fromVASP,QE,OMX,soiap,LAMMPS,ASEtot_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. Usebash,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
Note
For version 1.0.0 or later, skip this page. The executable script is automatically installed.
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).
-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
Then, run CyrSPY!
If you use old version (0.10.3 or earlier):
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:
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 VESTAdata/pkl_data: Directory to save pickled data.log_cryspy: log.err_cryspy: error and warning.
Let’s take a look at cryspy.stat file.
Structure ID 0 – 4 are queueing because we just generated structures, and have not submitted yet.
Tip
Check the initial structures, if the distances between atoms are too close, you should set the mindist in cryspy.in.
Submit Job
2023 July 10, update
Continue
CrySPY continues the simulation if you have cryspy.stat file.
Tip
Continue if you have crypy.stat
Start from the beginning if you don’t have cryspy.stat
Submit Job
Run CyrSPY again.
Check the screen or log_cryspy file.
And also cryspy.stat file.
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.
When the two jobs are done, run CrySPY again.
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.
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.
Info
Not ID order in cryspy_rslt
In cryspy_rslt_energy_asc file, the results are sorted in energy ascending order.
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 Γ
.
Info
For mindist, see also Features > Restriction on interatomic distances.
Edit cryspy.in and change the value of tot_struc into 10, and add mindist_1 = 2.0
Then run cryspy, and check log_cryspy file.
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.
Note
Structure generation mode whenever you change the value of tot_struc.
From version 1.0.0, CrySPY automatically backs up when adding structures.
See features/backup.
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:
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.
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.
Evolutionary Algorithm (EA)
Info
- For the basic usage of CrySPY, start by referring to Tutorial > Random Search (RS).
- For details of the algorithm, refer to Search Algorithms > Evolutionary algorithm (EA).
Preparation of Input Files
Follow one of the instructions below, then proceed to the section on running CrySPY.
Running CrySPY
Subsections of Evolutionary Algorithm (EA)
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.
- Use
algo = EA. - From v1.5.0,
energy_output_intervalin the [option] section sets the output interval in generations for the energy plot. Default:1(every generation);0disables automatic output. - From v1.5.0,
backup_intervalin the [option] section sets the automatic backup interval in generations. The default is1;0disables automatic backups. See Features > Backup for details. - When using a bash environment, set
jobcmdto bash. - In EA,
tot_strucis not used. The number of structures is determined byn_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
calc_in/job_cryspy
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.
log
In EA, running cryspy appends the current generation’s information to cryspy.stat.
Optimize Structures
After running cryspy several times and completing the structure optimization for the first generation, the output will appear as shown below.
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.
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.
ea_info
The EA parameters used in each generation are recorded in ea_info.
ea_origin
Information about the structure generation method and parent individuals is output to ea_origin.
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.
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:
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_genplot_max_genref_gen
For example, to replot the figure at generation 2, write the [visual] section as follows:
Then, run the following command:
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:
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:
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.
Variable-Composition Evolutionary Algorithm (EA-vc)
Info
- For the basic usage of CrySPY, start by referring to CrySPY > Tutorial > Random Search (RS).
- For the basic usage of EA, start by referring to CrySPY > Tutorial > Evolutionary algorithm (EA).
- For details of the algorithm, refer to CrySPY > Search algorithms > Variable-composition Evolutionary algorithm (EA-vc).
Info
System requirements
- CrySPY 1.4.0 or later
- For interface compatibility, see CrySPY > Interface.
Preparation of Input Files
Follow one of the instructions below, then proceed to the section on running CrySPY.
To impose a charge neutrality condition, specify charge in the [structure] section of cryspy.in. See Features > Charge neutrality condition for details.
To restrict the composition range explored by the search, specify min_comp and max_comp in the [structure] section of cryspy.in (version 1.5.0 or later). These constraints can also be combined with charge neutrality. See Features > Composition Constraints for details.
Running CrySPY
Subsections of Variable-Composition Evolutionary Algorithm (EA-vc)
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.
- Use
algo = EA-vc. - From v1.5.0,
energy_output_intervalin the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default:1(every generation);0disables automatic output. - From v1.5.0,
backup_intervalin the [option] section sets the automatic backup interval in generations. The default is1;0disables automatic backups. See Features > Backup for details. - When using a bash environment, set
jobcmdto bash. - In the [structure] section, use
ll_natto specify the minimum number of atoms for each element, andul_natfor the maximum. n_pop=n_crsov+n_perm+n_strain+n_rand+n_add+n_elim+n_subs- The
ref_energies(end_pointin 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
calc_in/job_cryspy
MLIPοΌCu-AuοΌ
Last updated: October 16, 2026
Info
- A machine learning interatomic potential (MLIP) with an ASE Calculator interface must be installed.
- This tutorial uses CHGNet as an example.
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.
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).
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.
These values are then used as input for the cryspy.in file.
cryspy.in
- Use
algo = EA-vc. - From v1.5.0,
energy_output_intervalin the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default:1(every generation);0disables automatic output. - From v1.5.0,
backup_intervalin the [option] section sets the automatic backup interval in generations. The default is1;0disables automatic backups. See Features > Backup for details. - Since MLIPs use the ASE Calculator interface, set
calc_code = ASE. - Change
jobcmdaccording to your computing environment. - In the [structure] section, use
ll_natto specify the minimum number of atoms for each element, andul_natfor the maximum. n_pop=n_crsov+n_perm+n_strain+n_rand+n_add+n_elim+n_subs- In the
ref_energies(end_pointin 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 ofatype. - 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
calc_in/job_cryspy
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.
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).
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
- Use
algo = EA-vc. - From v1.5.0,
energy_output_intervalin the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default:1(every generation);0disables automatic output. - From v1.5.0,
backup_intervalin the [option] section sets the automatic backup interval in generations. The default is1;0disables automatic backups. See Features > Backup for details. - Change
jobcmdaccording to your computing environment. - In the [structure] section, use
ll_natto specify the minimum number of atoms for each element, andul_natfor the maximum. n_pop=n_crsov+n_perm+n_strain+n_rand+n_add+n_elim+n_subs- In the
ref_energies(end_pointin 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 ofatype. - 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.
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:
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.
calc_in/
POTCAR
In EA-vc, prepare a separate POTCAR file for each element. The file names should be:
POTCAR_FePOTCAR_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
INCAR
1_INCAR
2_INCAR
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.
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).
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
- Use
algo = EA-vc. - From v1.5.0,
energy_output_intervalin the [option] section sets the output interval in generations for the convex-hull plot and hull-distance file. Default:1(every generation);0disables automatic output. - From v1.5.0,
backup_intervalin the [option] section sets the automatic backup interval in generations. The default is1;0disables automatic backups. See Features > Backup for details. - Change
jobcmdaccording to your computing environment. - In the [structure] section, use
ll_natto specify the minimum number of atoms for each element, andul_natfor the maximum. n_pop=n_crsov+n_perm+n_strain+n_rand+n_add+n_elim+n_subs- In the
ref_energies(end_pointin 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 ofatype. - 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:
In ./work/xxx/, CrySPY automatically rewrites lines that start with nat (excluding leading whitespace) to:
calc_in/
job_cryspy
pwscf.in
1_pwscf.in
2_pwscf.in
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.
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.
The file cryspy.stat shows that the current generation’s information is being added during the EA process.
Optimize Structures
After running cryspy several times and completing the structure optimization for the first generation, the output will appear as shown below.
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
- 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.
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.
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.
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:
nat_data
Information on the number of atoms and composition is also included in nat_data.
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.
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.
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.
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.
To check the composition range specified in the input without using search results, use the cryspy-Eplot -c option.
Combining Charge Neutrality with Composition Constraints
Composition constraints can also be combined with charge neutrality specified by charge.
In that case, the blue region represents only the composition constraints, and generated structures must also satisfy charge neutrality within that region.
See Features > Composition Constraints for input examples.
Example of ternary search results through generation 3 with both conditions applied.
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:
Replotting Specific Generations
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_genplot_max_genref_gen
For example, to replot the figure at generation 2, write the [visual] section as follows:
Then, run the following command:
In this case, CrySPY overwrites ./data/convex_hull/conv_hull_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/convex_hull/conv_hull_gen_{plot_min_gen}-{plot_max_gen}.{fig_fotmat}, instead of the usual one.
For example, from left to right, the figures above show convex hull plots including only the structures from the first, second, and third generations, respectively.
Note that the convex hull (solid line) in all plots is based on the third generation using ref_gen = 3.
The value of ref_gen must be set to be greater than or equal to plot_max_gen.
As shown in the central figure, to extract only the results of the second generation, specify the following settings in the [visual] section.
If ref_gen is specified, the output filename becomes
conv_hull_gen_{plot_min_gen}-{plot_max_gen}_ref_{ref_gen}.{fig_format}.
Convex Hulls with Compound Terminals
You can also plot a convex hull referenced to compound compositions by specifying terminals in the [visual] section. For an example, see Commands > cryspy-Eplot > Convex Hulls with Compound Terminals.
The following example uses LiβAlβO search results through generation 30 with a charge neutrality condition imposed. The left figure shows the ternary convex hull referenced to the elements; the right figure shows the pseudo-binary convex hull referenced to Li2O and Al2O3.
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-vc.ipynb.
Alternatively, you can download it directly from GitHub (CrySPY_utility/notebook/).
The Jupyter notebook file includes the same functions as the CrySPY code, allowing you to freely customize the convex hull plots. Execute the cells in order as appropriate, and choosing one of the following options will produce the same plot as the automatic output.
- Binary system, matplotlib
- Ternary system, matplotlib
In the section
- Interactive plot using Plotly,
interactive plots using Plotly are available for binary, ternary, and quaternary systems.
Bayesian Optimization (BO)
BO
LAQA
Last updated: October 16, 2026
Info
First, see Tutorial > Random Search (RS) for basic usage of CrySPY.
Here, we assume CrySPY 1.1.0 or later.
The example files used here can be downloaded from CrySPY_utility/examples/qe_Si16_LAQA. In this tutorial, only 50 initial structures are generated, but originally, LAQA is designed to select candidates from many more structures.
Input
cryspy.in
Here is an example of cryspy.in.
nstagemust be 1 in LAQA- From v1.5.0,
backup_intervalin the [option] section sets the automatic backup interval in selections. The default is1;0disables automatic backups. See Features > Backup for details. - You have to write
nselect_laqain [LAQA] section.nselect_laqais the number of candidates you select at one time.
If you want to change the value of the weight for LAQA score, edit wf and ws as below.
If omitted, the default values are used (0.1 and 10.0, respectively).
See, Search algorithms > LAQA for the score.
calc_in/pwscf.in_1
nstepcontrols how many steps of structure optimization can proceed in one selection. (NSWfor VASP)
calc_in/job_cryspy
- The job file is the same as the usual way.
Run
Tip
An automatic script is also available. See the bottom of this page.
Just type cryspy for the 1st run.
Check log_cryspy.
50 random structures are generated.
In LAQA, jobs of structure optimization for all structures are submitted once at the beginning.
Note that only 10 steps are proceeded here since we set nstep = 10.
Repeat cryspy command until all of these (10 steps) are completed.
If necessary, you can also submit all jobs at once by increasing the value of njob.
After all the initial optimizations, LAQA is ready is displayed at the end of log_cryspy.
Next cryspy run will make the first selection.
Here, only the number set in nselect_laqa will be selected.
Type cryspy to submit the jobs (next 10 steps).
Then, by repeating this over and over again, the optimization of the structure selected according to the score advances by 10 steps each time. Proceed until several structures are completed, and finish (stop) when you like.
Status
If you want to check the LAQA score during the simulation, you can look at the status file:
- ./data/LAQA_status
Other files for LAQA will be output:
- ./data_LAQA_bias
- ./data_LAQA_energy
- ./data_LAQA_score
- ./data_LAQA_selected_id
- ./data_LAQA_step
Analysis and Visualization
It is assumed here that you analyze and visualize CrySPY data in your local PC.
If you use CrySPY in super computers or workstations, download the data in your local PC.
You can delete the work and backup directory if you do not need it because the file size could be very large.
You may gzip the pkl data to decrease the file size.
Jupyter Notebook
Move to the data/ directory in results you just downloaded.
Then copy cryspy_analyzer_LAQA.ipynb from CrySPY utility.
You can obtain the graph and animation with the notebook. In the gif below, all of the optimizations were completed. This is just for animation. (When all of the optimizations are completed, the computational cost is the same as random search.)
This graph shows the energy as a function of optimization step. The red lines indicate three structures with the lowest energy. The most stable one reached diamond structure. The structures that eventually become stable were selected at an early stage.
Info
If algo = LAQA, the followings are automatically set in the [option] section.
- force_step_flag = True
- stress_step_flag = True
Force and stress data are collected step by step. Energy and structure data are NOT. They are collected for each selection. In other words, in this case, energy and structure data are saved once every 10 steps. If you want to collect energy and structure data step by step, manually set up as follows:
Auto Script
You may find it tedious to run cryspy over and over again. The auto script could help you.
Loading Initial Structures
Last updated: October 16, 2026
This tutorial creates init_struc_data.pkl from three CIF files and loads the structures as initial structures.
The example is an RS search for eight Cu atoms: three structures are loaded and two more are generated randomly, giving five initial structures in total.
See Features > Loading Initial Structures for details of the loading checks.
Preparation
Prepare cryspy.in and calc_in/ in a new working directory as in Tutorial > Random Search (RS) > ASE on Your Local PC.
Use the same ase_in.py and job_cryspy files in calc_in/. Do not run cryspy yet.
Conversion uses CrySPY Utility’s pos2pkl.py. The commands below assume that pos2pkl.py is on your PATH. See Installation > CrySPY Utility for setup.
Download the following example CIF files into the working directory. Each contains eight Cu atoms.
Converting Structure Data
Run the following command in the working directory. Use -s for files containing one structure each, such as CIF files.
The command creates init_struc_data.pkl in the current directory. IDs are assigned in input order: Cu8_1.cif, Cu8_2.cif, and Cu8_3.cif receive IDs 0, 1, and 2, respectively.
See CrySPY Utility > pos2pkl.py for conversion details.
cryspy.in
Configure cryspy.in as follows.
atype = Cuandnat = 8match the atom type and atom count in all three input structures.tot_struc = 5combines the three loaded structures with two randomly generated structures.load_struc_flag = Trueenables loading initial structures.- Adjust
jobcmdfor your computing environment.
Placing the Data and Running CrySPY
Before the first cryspy run, place the converted data as follows.
CrySPY loads three structures and generates two more randomly, then exits after preparing the initial structures.
Continue as in a normal RS run by executing cryspy again to start structure optimization.
Checking the Loaded Structures
./data/init_POSCARS contains all five structures: the three loaded structures and the two randomly generated structures.
| Structure ID | Initial structure |
|---|---|
0 | Loaded from Cu8_1.cif |
1 | Loaded from Cu8_2.cif |
2 | Loaded from Cu8_3.cif |
3, 4 | Generated randomly |
./data/pkl_data/init_struc_data.pkl is also updated to contain these five structures.
Invalid structure counts, atom types, or compositions raise an error. See Features > Loading Initial Structures > Checks During Loading for details.
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.
- Download from CrySPY utility > examples > qe_benzene_2_RS_mol
- Copy from CrySPY utility that you installed
- (only version 0.10.3 or earlier)
cp -r ~/CrySPY_root/CrySPY-0.9.0/example/QE_benzene_2_RS_mol .
Take a look at cryspy.in.
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 .
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.
Check cryspy.in.
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:
Random Structure Generation with MPI
Last updated: October 16, 2026
Info
First, see Tutorial > Random Search (RS) for basic usage of CrySPY.
Info
Requirements:
- CrySPY
1.1.01.2.3 or later - mpi4py
- MPI library (Open MPI, Intel MPI, MPICH, etc.)
Warning
1.1.0 <= CrySPY <=1.2.2 has a bug.
When you use bash (zsh) to run a job with MPI (e.g., jobcmd = zsh, jobfile = job_cryspy),
the MPI job does not run. There is no problem when you use a job scheduler (qsub, sbatch).
It has already fixed in version 1.2.3.
mpi4py
Install mpi4py if it is not already installed.
Input
cryspy.in is the same as normal usage and does not need to be changed.
Here we try structure generation with MPI using the following settings:
All except tot_struc, atype, and nat are irrelevant for structure generation and can be ignored here.
Run
To generate structures with 4 MPI processes, use mpiexec -n with the -p option:
If you submit jobs through a job scheduler, prepare a job script as shown below:
Please edit the location of the executable script cryspy.
Result
CrySPY simply divides the task (number of structures) by the number of processes:
- Rank 0: IDs 0 – 24
- Rank 1: IDs 25 – 49
- Rank 2: IDs 50 – 74
- Rank 3: IDs 75 – 99
CrySPY outputs the log in the order they are generated as follows:
However, the order in init_POSCARS is by structure ID since CrySPY outputs after all structures have been generated.
Note
Except for the random structure generation part, there is no point in using MPI because it is not parallelized.
Interactive Mode (Jupyter Notebook)
Last updated: October 16, 2026
Info
Preparation
When CrySPY is installed, ASE is automatically installed as well. Set up Jupyter to be usable on a workstation or local PC. In this tutorial, Pure Python EMT calculator is used for structure optimization. Note that the accuracy of the EMT potential is poor, as it is intended for demonstration purposes only.
The example notebook also includes code for using the machine learning potential CHGNet. If you want to try CHGNet, make sure to install it in advance using pip.
Input File
Move to your working directory, and copy the example files by one of the following methods.
- Download from CrySPY_utility/examples/interactive
- Copy from CrySPY utility that you installed
Even in interactive mode, cryspy.in is used as the input file.
The calc_in directory is not used in interactive mode.
You can refer to the examples of cryspy.in in the input_examples directory.
Here, the following cryspy.in using EA-vc will be used.
For more details on EA-vc, refer to the EA-vc tutorial.
Notebook
Open cryspy_interactive.ipynb and execute the cells from the top.
Check Current Working Directory
The first cell only checks the files and the contents of cryspy.in.
Import
Ignore the commented-out sections this time and execute the cell that imports the core libraries for CrySPYβs interactive mode.
Initialize CrySPY
This cell corresponds to a standard initial run. It reads cryspy.in and generates the initial structures.
Set Calculator
This cell sets the ASE calculator. Here, ASEβs EMT is used.
Restart CrySPY
Executing this cell starts the optimization of the previously generated initial structures. In interactive mode, structure optimization calculations are performed sequentially, one by one. A progress bar is also displayed during the process.
- njob: The number of structures to be optimized in a single execution. If set to 0, the value specified in
cryspy.inis used. - calculator: Assign the previously set calculator.
- optimizer: Select from
FIRE,BFGS, orLBFGS. Specify as a string. - symmetry: If True, structure optimization is performed while preserving symmetry.
- fmax: The maximum atomic force (eV/Γ ) used for convergence criteria.
- steps: Maximum optimization steps.
If the njob value is set to a small number, execute this cell multiple times to complete the optimization of all initial structures.
When using EA-vc, the following message will be displayed upon completion.
Executing this cell again will trigger generational turnover. Once the next-generation structures are generated, continue executing this cell repeatedly in the same manner.
Show Results
Running this cell allows you to display files such as cryspy_rslt_energy_asc.
Structure Visualization
You can interactively visualize both the initial and optimized structures.
Changing opt to init in action.get_atoms('opt', cid=0) allows you to check the initial structure.
The cid parameter specifies the structure ID.
Since this utilizes ASEβs functionality, the viewer option supports ngl, ase, and x3d.
To use ngl, you need to install nglview, so make sure to install it via pip in advance.
Energy Plot for RS, EA
For random search (RS) and evolutionary algorithm (EA), an energy graph shown below can be displayed. In the case of EA-vc, direct energy comparison is not possible due to differences in the number of atoms, so the convex hull plot, discussed later, is used instead.
Convex Hull Plot for EA-vc
Interactive Plot Using Plotly
For EA-vc, an interactive convex hull plot using Plotly is available. When CrySPY is installed, Plotly is automatically installed as well. This convex hull plot utilizes pymatgenβs functionality.
- cgen: Which generationβs data to plot up to. If None, data will be plotted up to the latest generation.
- show_unstable: The maximum hull distance value to display on the plot
- ternary_style
- Binary system: ternary_style = ‘2d’
- Ternary system: ternary_style = ‘2d’, ‘3d’
- Quaternary system: ternary_style = ‘3d’
When performing calculations with ternary or quaternary systems instead of binary systems, you can obtain the following interactive plots.
From left to right:
- Ternary system (ternary_style = β2dβ)
- Ternary system (ternary_style = β3dβ)
- Quaternary system (ternary_style = β3dβ)
Binary System Using matplotlib
Running this cell plots the binary convex hull using matplotlib.
- cgen: Which generationβs data to plot up to. If None, data will be plotted up to the latest generation.
- show_max: The maximum formation energy to display on the plot
- label_stable: Whether to display the labels (compositions) of stable structures
- vmax: The maximum hull distance in the color bar
- bottom_margin: Bottom margin of y-axis
Ternary System Using matplotlib
If exploring a ternary system, running this cell will generate a convex hull plot using matplotlib.
- cgen: Which generationβs data to plot up to. If None, data will be plotted up to the latest generation.
- show_max: The maximum formation energy to display on the plot
- label_stable: Whether to display the labels (compositions) of stable structures
- vmax: The maximum hull distance in the color bar
For example, the following plot can be obtained.
