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.
Follow one of the instructions below, then proceed to the section on running CrySPY.
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.
Here, we assume the following conditions:
job_cryspyase_in.pyMove to your working directory, and copy the example files by one of the following methods.
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.pyThe other input variables are discussed later.
The job file and input files for ASE are prepared in this directory.
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)
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”.
(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 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.pyIf 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:
log.tote file. CrySPY reads the last line of it.CONTCAR file in the VASP format.done or not_yet in a file named out_check_opt. CrySPY reads the last line of this file.Go to Running CrySPY
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.
Here, we assume the following conditions:
~/CrySPY_root/CrySPY-0.9.0/cryspy.pyjob_cryspy~/local/soiap-0.3.0/src/soiapsoiap.insoiap.outinitial.cifMove to your working directory, and copy input example files by one of the following methods.
cp -r ~/CrySPY_root/CrySPY-0.9.0/example/v0.9.0/soiap_RS_Si8 .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_cifThe other input variables are discussed later.
The job file and input files for soiap are prepared in this directory.
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.
sed -i -e '3 s/^.*$/done/' stat_job is required at the end of the job file.
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 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.
Go to Running CrySPY
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.
Here, we assume the following conditions:
qsubjob_cryspyMove to your working directory, and copy the example files by one of the following methods.
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:
jobfileWe 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.
See Input file > Kpoint for details of kppvol
The other input variables are discussed later.
The job file and input files for VASP are prepared in this directory.
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)
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”.
(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 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_xINCARIf 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.
POTCAR in this example is empty. We cannot distribute it.
Go to Running CrySPY
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.
Here, we assume the following conditions:
qsubjob_cryspy/usr/local/qe-6.5/bin/pw.xpwscf.inpwscf.outMove to your working directory, and copy input example files by one of the following methods.
cp -r ~/CrySPY_root/CrySPY-0.9.0/example/v0.9.0/QE_Si8_RS .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.
See Input file > Kpoint for details of kppvol
You can name the following files whatever you want:
jobfileqe_infileqe_outfileThe other input variables are discussed later.
The job file and input files for QE are prepared in this directory.
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)
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”.
(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 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.inWe 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.
Go to Running CrySPY
Coming soon.
Coming soon.
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.
algo: Algorithm. Set RS for Random Search.calc_code: Structure optimizer. Choose from VASP, 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. Use bash, zsh, qsub, and so on.jobfile: File name of the job file.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 8For version 1.0.0 or later, skip this page. The executable script is automatically installed.
Here, we assume the following condition:
~/CrySPY_root/CrySPY-0.9.0/cryspy.pyLet’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.
2025 March 6, updated
Make sure you have the following in your working directory.
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.
Check the initial structures, if the distances between atoms are too close, you should set the mindist in cryspy.in.
2023 July 10, update
CrySPY continues the simulation if you have cryspy.stat file.
Continue if you have crypy.stat
Start from the beginning if you don’t have cryspy.stat
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.
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.
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.
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 Å.
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.
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.
Last updated: February 9, 2026
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.
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.
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.
