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.
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.
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）.)
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.
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.
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.
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
# ---------- importfrom 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 directoryatoms = read('POSCAR')
# ---------- set upatoms.calc = CHGNetCalculator()
atoms.set_constraint([FixSymmetry(atoms)])
cell_filter = FrechetCellFilter(atoms)
opt = BFGS(cell_filter, trajectory='opt.traj')
# ---------- runconverged = 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# ------ energye = cell_filter.atoms.get_total_energy() # eV/cellwith open('log.tote', mode='w') as f:
f.write(str(e))
# ------ strucopt_atoms = cell_filter.atoms.copy()
opt_atoms.set_constraint(None) # remove constraint for pymatgenwrite('CONTCAR', opt_atoms, format='vasp', direct=True)
# ------ check_optwith open('out_check_opt', mode='w') as f:
if converged:
f.write('done\n')
else:
f.write('not yet\n')
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).
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.
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.
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.
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:
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.
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.
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.
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.
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:
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/.
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.
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.
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.
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:
cryspy-Eplot
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_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/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.
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.
