Input File

Description of the input file, cryspy.in.

File Format

CrySPY uses the configparser module to read input file, cryspy.in . cryspy.in consists of sections, led by a [section] header and followed by name = value or name : value entries. Section names and values are case sensitive, but names are not. Lines beginning with # or ; are ignored and may be used to provide comments. Accepted bool values are 1, yes, true, and on, which cause this method to return True, and 0, no, false, and off, which cause it to return False. These string values for bool are checked in a case-insensitive manner. Some values are given in a space-separated manner.

Info

See configparser in detail.

Note

section name: case sensitive
name: case insensitive
value: case sensitive except for bool

[basic] Section

2025 March 6 updated

Name	Value	Description
`algo`	`RS`, `EA`, `EA-vc`, `BO`, `LAQA`	Algorithm
`calc_code`	`VASP`, `QE`, `OMX`, `soiap`, `LAMMPS`, `ASE`	Caluculation code for structure optimization
`tot_struc`	int	The total number of structures. Not used in the case of EA or EA-vc.
`nstage`	int	The number of stages
`njob`	int	The number of jobs running at the same time.
`jobcmd`	str	Command to submit jobs such as qsub and sbatch.
`jobfile`	str	File name of the job file.

[structure] Section

Last updated: October 16, 2026

Name	Value	Default	Description
`struc_mode`	`crystal`, `mol`, `mol_bs`	`crystal`	Structure generation mode
`atype`	atomic symbol [atomic symbol …]		Atom type. e.g. `atype = Na Cl`.
`nat`	int [int …]		The number of atoms corresponding to each atype. e.g. `nat = 8 8`. Not used in `EA-vc`.
`mindist` (`mindist_?`)	float [float …]	`None`	Constraint on minimum interatomic distance [Å]. See Features > Restriction on Interatomic Distances for details.
`mindist_factor`	float	1.0	Scaling factor for `mindist`.
`vol_factor`	float	1.1	Volume scaling factor.
`vol_mu`	float	`None`	Mean of the normal distribution used to sample the cell volume [Å³]. If specified, `vol_sigma` is also required.
`vol_sigma`	float	`None`	Standard deviation of the normal distribution for the cell volume [Å³], used together with `vol_mu`.
`symprec`	float	0.01	Precision for symmetry finding.
`spgnum`	`all`, space group number, 0	`all`	Constraint on space group. If `all`, 1–230. If 0, random structure without space group information (no symmetry).
`use_find_wy`	bool	`False`	Structure generation with find_wy.

if algo is EA-vc

Name	Value	Default	Description
`ll_nat`	int [int …]		Lower limit of `nat`. e.g. `ll_nat = 0 0`.
`ul_nat`	int [int …]		Upper limit of `nat`. e.g. `ul_nat = 8 8`.
`charge`	int or grouped ints	`None`	Charge of each atom type used to impose charge neutrality, specified in the same order as `atype`. For example, `charge = 1 -1` for NaCl. Since version 1.5.0, multiple oxidation states can be grouped in parentheses or square brackets. For example, `charge = (2 3) -2` for `atype = Fe O`. See Charge Neutrality Condition for details.
`cn_mode`	`auto`, `enumerate`, `sample`	`auto`	(since version 1.5.0) Used only when `charge` is specified. Mode for calculating atom-count combinations that satisfy the charge-neutrality condition.
`max_cn_grid_points`	int	200_000_000	(since version 1.5.0) Used only when `charge` is specified. Maximum number of combinations examined exhaustively with `cn_mode = auto` or `enumerate` after eliminating one atom-count variable using the charge-neutrality equation. If this value is exceeded, `auto` switches to sampling, while `enumerate` raises an error. See Charge Neutrality Condition for details, including how combinations are counted for multi-valence species.
`min_comp`	float [float …]	`None`	(since version 1.5.0) Used to impose composition constraints. Specifies the lower bound of the normalized composition (from 0 to 1) for each atom type. Specify one value per atom type in the same order as `atype`. If only `max_comp` is specified, `min_comp` is set to `0.0` for every atom type.
`max_comp`	float [float …]	`None`	(since version 1.5.0) Used to impose composition constraints. Specifies the upper bound of the normalized composition (from 0 to 1) for each atom type. Specify one value per atom type in the same order as `atype`. If only `min_comp` is specified, `max_comp` is set to `1.0` for every atom type.

if struc_mode is mol or mol_bs

Molecular crystal structure generation (struc_mode = mol or mol_bs) is not supported in EA or EA-vc.

Name	Value	Default	Description
`mol_file`	str [str …]		Path of molecule files or molecule names.
`nmol`	int [int …]		The number of molecules.
~~`timeout_mol`~~	float	`None`	(removed in version 1.5.0) Time out for molecular structure generation.
`rot_mol`	`random`, `random_mol`, `random_wyckoff`	`random_wyckoff`	Only used in `mol_bs`. Mode for rotation of molecules.
`nrot`	int	20	Only used in `mol_bs`. Maximum number of trials to rotate molecules.
`mindist_mol_bs` (`mindist_mol_bs_?`)	float [float …]	`None`	Only used in `mol_bs`. Constraint on minimum intermolecular distance [Å].
`mindist_mol_bs_factor`	float	1.0	Only used in `mol_bs`. Scaling factor for `mindist_mol_bs`.

if use_find_wy is True or spgnum = 0

Name	Value	Default	Description
`fwpath`	str	`None`	Only used with find_wy. Path of find_wy. If `None`, `fwpath` is automatically searched in your $PATH.
`minlen`	float		Only used with find_wy or `spgnum = 0`. Minimum length of lattice vector [Å].
`maxlen`	float		Only used with find_wy or `spgnum = 0`. Maximum length of lattice vector [Å].
`dangle`	float		Only used with find_wy or `spgnum = 0`. Delta angle for alpha, beta, and gamma in degree unit.
`maxcnt`	int	50	Only used with find_wy or `spgnum = 0`. Maximum number of trials to determine atom positions.

[VASP] Section

Last updated: October 12, 2026

[VASP] section is required only if you use VASP (calc_code = VASP)

Name	Value	Default	Description
`kppvol`	int [int …]		Target k-point grid density for each stage (number of k-points per Å⁻³ of reciprocal-space volume).
`force_gamma`	bool	`False`	If true, force gamma-centered mesh.
`vasp_MAGMOM`	float [float …]	`None`	Used only for EA-vc. MAGMOM values for each element.
`vasp_LDAUL`	int [int …]	`None`	Used only for EA-vc. LDAUL values for each element.
`vasp_LDAUU`	float [float …]	`None`	Used only for EA-vc. LDAUU values for each element.
`vasp_LDAUJ`	float [float …]	`None`	Used only for EA-vc. LDAUJ values for each element.

kppvol and Force Gamma

Input file > Kpoint

[QE] Section

[QE] section is required only if you use QE (calc_code = QE)

Name	Value	Default	Description
`kppvol`	int [int …]		Target k-point grid density for each stage (number of k-points per Å⁻³ of reciprocal-space volume).
`qe_infile`	str		File name of QE input file.
`qe_outfile`	str		File name of QE output file.
`pv_term`	bool	`False`	If true, read enthalpy instead of total energy.

kppvol

Input file > Kpoint

pv_term

Features > Enthalpy > QE

[OMX] Section

[OMX] section is required only if you use OpenMX (calc_code = OMX)

Name	Value	Description
`kppvol`	int [int …]	Target k-point grid density for each stage (number of k-points per Å⁻³ of reciprocal-space volume).
`OMX_infile`	str	File name of OpenMX input file.
`OMX_outfile`	str	File name of OpenMX output file.
`ValenceElectrons`	str float float [str float float …]	The number of initial charges for up and down spin states.

kppvol

Input file > Kpoint

ValenceElectrons

e.g. in NaCl: ValenceElectrons = Na 4.5 4.5 Cl 3.5 3.5.

[soiap] Section

[soiap] section is required only if you use soiap (calc_code = soiap)

Name	Value	Description
`soiap_infile`	str	File name of soiap input file.
`soiap_outfile`	str	File name of soiap output file.
`soiap_cif`	str	File name of soiap CIF-formatted initial structure.

[LAMMPS] Section

[LAMMPS] section is required only if you use LAMMPS (calc_code = LAMMPS)

Name	Value	Default	Description
`lammps_infile`	str		File name of LAMMPS input file.
`lammps_outfile`	str		File name of LAMMPS output file.
`lammps_potential`	str [str …], `None`	`None`	Potential.
`lammps_data`	str		File name of LAMMPS data file.

[ASE] Section

[ASE] section is required only if you use ASE (calc_code = ASE)

Name	Value	Default	Description
`ase_python`	str		File name of ASE input file.

[EA] Section

Last updated: October 12, 2026

The [EA] section is required when using EA or EA-vc, or when append_struc_ea = True is specified in the [option] section.
See also CrySPY > Search algorithms > EA

EA

Name	Value	Default	Description
`n_pop`	int		Population (see also Population Size)
`n_crsov`	int		Number of offspring created by crossover
`n_perm`	int		Number of offspring created by permutation
`n_strain`	int		Number of offspring created by strain
`n_rand`	int		Number of structures created randomly
`n_elite`	int		Number of elite individuals (see also Natural Selection)
`fit_reverse`	bool	`False`	If `False`, minimal search (see also Evaluate Fitness)
`n_fittest`	int	0	Number of individuals that remain natural selection. If set to 0, all individuals are retained.
`slct_func`	`TNM`, `RLT`		Function to select parents
`t_size`	int	3	Tournament size. Used only used `slct_func = TNM`. (see also Tournament Selection)
`a_rlt`	float	10.0	Parameter for linear scaling. Used only with `slct_func = RLT`. (see also Roulette Selection)
`b_rlt`	float	1.0	Parameter for linear scaling. Used only with `slct_func = RLT`. (see also Roulette Selection)
`crs_lat`	`equal`, `random`	`random`	How to mix lattice vectors (see also crossover > 5. Swap the sliced halves)
`nat_diff_tole`	int	4	Tolerance for difference in the number of atoms in crossover. (see also crossover > 6. Select the offspring with more atoms)
`ntimes`	int	1	Number of times in permutation.
`sigma_st`	float	0.5	Standard deviation for strain.
`maxcnt_ea`	int	50	Maximum number of trials in EA.
`max_parent_attempts`	int	50	(since version 1.5.0) Maximum number of parent-selection attempts per offspring in EA. The initial parent selection is included.
`maxgen_ea`	int	0	Maximum generation. If set to 0, no upper limit is applied.
`emax_ea`	float	`None`	Energy upper limit (eV/atom) for natural selection.
`emin_ea`	float	`None`	Energy lower limit (eV/atom) for natural selection.

EA-vc

EA-vc requires the following additional variables on top of the standard EA.
Note that in EA-vc, emax_ea and emin_ea are used not in natural selection but when computing the convex hull.
See also CrySPY > Search algorithms > EA-vc
See also CrySPY > Tutorial > EA-vc > Analysis and visualization for the convex hull plot.

Name	Value	Default	Description
`n_add`	int		Number of offspring created by addition.
`add_max`	int	5	(since version 1.4.1) Maximum number of atoms to add in addition
`n_elim`	int		Number of offspring created by elimination.
`elim_max`	int	5	(since version 1.4.1) Maximum number of atoms to eliminate in elimination
`n_subs`	int		Number of offspring created by substitution.
`subs_max`	int	3	(since version 1.4.1) Maximum number of atoms to substitute in substitution
`ref_energies`	float [float …]		(since version 1.5.0) Reference energies for formation energy calculation [eV/atom]. Specify one value per atom type in the same order as `atype`, separated by spaces without parentheses or commas. The number of values must match the number of atom types in `atype`.
`end_point`	float [float …]		(deprecated since version 1.5.0) Kept for backward compatibility. Use `ref_energies` instead. Uses the same units and input format as `ref_energies`.
`emax_ea`	float	`None`	Energy upper limit (eV/atom) for computing the convex hull.
`emin_ea`	float	`None`	Energy lower limit (eV/atom) for computing the convex hull.

The following variables have been moved to the [visual] section since version 1.5.0.
cgen was deprecated in version 1.5.0.
The default values below apply to versions 1.4.3 and earlier. For version 1.5.0 and later, see the [visual] section.

Name	Value	Default	Description
`cgen`	int	`None`	(in versions 1.4.1–1.4.3) Which generation’s data to plot up to. If None, data will be plotted up to the latest generation.
`show_max`	float	0.2	When plotting the convex hull, the maximum value of the y-axis (for binary systems) or the maximum hull distance (for ternary systems) is set by show_max.
`label_stable`	bool	`True`	Whether to show stable compositions when plotting the convex hull.
`vmax`	float	0.2	Maximum value of the colorbar representing hull distance.
`bottom_margin`	float	0.02	Bottom margin of the y-axis for binary convex hull plot.
`fig_format`	str	`svg`	Figure format for convex hull plot: `svg`, `png`, or `pdf`.

[BO] Section

Last updated: October 12, 2026

[BO] section is required only if you use BO (algo = BO)

Name	Value	Default	Description
`nselect_bo`	int		The number of structures to be selected at once.
`score`	`TS`, `EI`, `PI`		Acquisition function.
`num_rand_basis`	int	0	If `0`, Gaussian process. The number of basis function.
`cdev`	float	0.001	Cutoff of deviation for standardization.
`dscrpt`	`FP`		Structure descriptor.
`max_select_bo`	int	0	Maximum number of selection.
`manual_select_bo`	int [int …]	`None`	Structure IDs to be selected manually.
`emax_bo`	float	`None`	Upper limit of energy in BO.
`emin_bo`	float	`None`	Lower limit of energy in BO.

if dscrpt is FP

CrySPY 1.3.0 or later

fppath and fp_rmin are obsolete.

Name	Value	Default	Description
`fp_rmax`	float	8.0	Only used with `dscrpt = FP`. Maximum cutoff of r in fingerprint.
`fp_npoints`	int	20	Only used with `dscrpt = FP`. Number of discretized points for each pair in fingerprint.
`fp_sigma`	float	0.7	Only used with `dscrpt = FP`. Sigma parameter [Å] in Gaussian smearing function.

CrySPY 1.2.5 or earlyer

Name	Value	Default	Description
`fppath`	str	`None`	Only used with `dscrpt = FP`. Path of cal_fingerprint. If `None`, `fwpath` is automatically searched in your $PATH.
`fp_rmin`	float	0.5	Only used with `dscrpt = FP`. Minimum cutoff of r in fingerprint.
`fp_rmax`	float	5.0	Only used with `dscrpt = FP`. Maximum cutoff of r in fingerprint.
`fp_npoints`	int	20	Only used with `dscrpt = FP`. Number of discretized points for each pair in fingerprint.
`fp_sigma`	float	1.0	Only used with `dscrpt = FP`. Sigma parameter [Å] in Gaussian smearing function.

[LAQA] Section

[LAQA] section is required only if you use LAQA (algo = LAQA)

Name	Value	Default	Description
`nselect_laqa`	int		The number of structures to be selected at once.
`wf`	float	0.1	Weight of the force term.
`ws`	float	10.0	Weight of the stress term.

Info

[visual] Section

Last updated: October 12, 2026

The [visual] section is available since version 1.5.0.

Common

Common variables for RS, EA, EA-vc.
See also

CrySPY > Tutorial > Random Search (RS) > Analysis and visualization
CrySPY > Tutorial > Evolutionary Algorithm (EA) > Analysis and visualization

CrySPY > Tutorial > Variable-composition evolutionary algorithm (EA-vc) > Analysis and visualization

Name	Value	Default	Description
`ymax`	float	0.2	Maximum value of the y-axis in the energy plots of RS, EA, and EA-vc (binary systems).
`markersize`	int	10	Size of markers in all energy plots.
`fig_format`	str	`svg`	Figure formats: `svg`, `png`, or `pdf`.

EA

Name	Value	Default	Description
`ref_gen`	int	`None`	[post-analysis only] Reference generation for plotting. When specified, the plot is generated as of the end of this generation. If not specified, the latest generation is used. Must satisfy `plot_max_gen` <= `ref_gen`.
`plot_min_gen`	int	`None`	[post-analysis only] Minimum generation for plotting. If not specified (i.e., None), the value is treated as 1.
`plot_max_gen`	int	`None`	[post-analysis only] Maximum generation for plotting. If omitted, plotting extends through `ref_gen` when specified; otherwise, it extends through the latest generation.

EA-vc

Name	Value	Default	Description
`show_max`	float	`None`	Maximum hull distance shown in ternary systems.
`label_stable`	bool	`True`	Whether or not to show stable compositions in the plot.
`vmax`	float	0.2	Maximum value of the colorbar for the hull distance.
`bottom_margin`	float	0.04	Bottom margin of the y-axis in binary systems.
`axis_order`	str	`None`	Specifies the axis order: `lr` or `rl` in binary systems, and permutations of `tlr` (`lrt`, `rtl`, …) in ternary systems. When `terminals` is used, specify the axis order with `terminal_axis_order`.
`ref_gen`	int	`None`	[post-analysis only] Reference generation for plotting. When specified, the plot is generated as of the end of this generation. If not specified, the latest generation is used. Must satisfy `plot_max_gen` <= `ref_gen`.
`plot_min_gen`	int	`None`	[post-analysis only] Minimum generation for plotting. If not specified (i.e., None), the value is treated as 1.
`plot_max_gen`	int	`None`	[post-analysis only] Maximum generation for plotting. If omitted, plotting extends through `ref_gen` when specified; otherwise, it extends through the latest generation.
`show_comp_window`	bool	`True`	Whether to show the allowed composition range on the convex hull plot.
`ref_gen_comp`	int	`None`	[post-analysis only] Generation from which `min_comp` and `max_comp` are taken for the composition-window overlay. If omitted, `ref_gen` is used when specified; otherwise, the latest generation is used.
`terminals`	str str [str]	`None`	[post-analysis only] Two or three terminal compositions that define the compound phase diagram in `cryspy-Eplot` (e.g., `Li2O Al2O3`). Each terminal composition must have an entry in the phase-diagram data.
`terminal_axis_order`	str	`None`	[post-analysis only] Axis order used with `terminals`. Each letter gives the position of the corresponding terminal in the order specified by `terminals` (`t`: top, `l`: left, `r`: right). Use `lr` or `rl` for two terminals, or a permutation of `tlr` (`lrt`, `rtl`, …) for three terminals. If omitted, `lr` is used for two terminals and `tlr` for three.

[option] Section

Last updated: October 16, 2026

For the calculation codes supported by each *_step_flag, see Interface > Option compatibility.

Name	Value	Default	Description
`rslt_out`	`always`, `cycle`, `off`	`always`	(since version 1.5.0) Specifies when `cryspy_rslt` and `cryspy_rslt_energy_asc` are written. `always`: Write whenever a structure’s result is recorded. `cycle`: Write at the end of each generation in EA/EA-vc or each selection in BO/LAQA (no output in RS). `off`: Do not write these text files. Result pickle data is saved for all settings.
`check_mindist_opt`	bool	`True`	If True, a mindist constraint is checked after structure relaxation.
`stop_chkpt`	int	0	CrySPY stops at a specified check point.
`load_struc_flag`	bool	`False`	If True, load initial structures from `./data/pkl_data/init_struc_data.pkl`. Structure IDs must be consecutive integers starting from `0`. The maximum number of loaded structures is `n_pop` for EA/EA-vc and `tot_struc` otherwise. Exceeding this limit raises an error; any shortfall is filled by random structure generation. See Features > Loading Initial Structures for details.
`stop_next_struc`	bool	`False`	If True, CrySPY does not submit jobs for next structures, but jobs for next stage are submitted.
`backup_interval`	int	RS: 0 Other: 1	(since version 1.5.0) Interval between automatic backups in generations for EA/EA-vc or selections for BO/LAQA. Set to 0 to disable automatic backups.
`energy_output_interval`	int	1	(since version 1.5.0) Interval in generations for outputting the energy plot in EA and the convex-hull plot and hull-distance file in EA-vc. Set to 0 to disable these automatic outputs. The convex hull and hull distances in EA-vc are still calculated every generation.
`recalc`	int [int …]	`None`	Specify structure IDs if you want to recalculate or continue optimization.
`append_struc_ea`	bool	`False`	If True, append structures by EA.
`energy_step_flag`	bool	`False`	If True, save energy_step_data in `./data/pkl_data/energy_step_data.pkl`. In QE, `pv_term = True` cannot be used together with `energy_step_flag = True`.
`struc_step_flag`	bool	`False`	If True, save struc_step_data in `./data/pkl_data/struc_step_data.pkl`.
`force_step_flag`	bool	`False`	If True, save force_step_data in `./data/pkl_data/force_step_data.pkl`.
`stress_step_flag`	bool	`False`	If True, save stress_step_data in `./data/pkl_data/stress_step_data.pkl`.
`seed`	int	`None`	(since version 1.5.0) Seed for the random number generator. Must be an integer between 0 and 2**32 - 1.

Kpoint

2024 April 22

CrySPY automatically generates the k-point setting using the pymatgen.io.vasp.Kpoints.automatic_density_by_vol function from pymatgen. An example in cryspy.in with nstage = 2 is as follows:

[VASP]
kppvol = 40 120

stage 1: kppvol = 40
stage 2: kppvol = 120

kppvol means a grid density per Å${}^{-3} $ of reciprocal cell.
VASP: gamma centered meshes are used for hexagonal cells and face-centered cells; otherwise, Monkhorst-Pack grids are employed.
QE and OMX: only a k-mesh is provided, no offset.

What Is the Appropriate Value for kppvol?

Here are the guidelines. We use VESTA for visualizing crystal structures.

Primitive Cell of Diamond Si

a = b = c = 3.836 Å

kppvol	k-mesh
0	[1, 1, 1]
20	[4, 4, 4]
40	[6, 6, 6]
60	[7, 7, 7]
80	[7, 7, 7]
100	[8, 8, 8]
120	[9, 9, 9]
140	[9, 9, 9]
160	[9, 9, 9]
180	[10, 10, 10]
200	[10, 10, 10]
400	[13, 13, 13]
600	[15, 15, 15]
800	[17, 17, 17]

Conventional Cell of Diamond Si

a = b = c = 5.431 Å

kppvol	k-mesh
0	[1, 1, 1]
20	[3, 3, 3]
40	[3, 3, 3]
60	[4, 4, 4]
80	[4, 4 ,4]
100	[5, 5, 5]
120	[5, 5, 5]
140	[6, 6, 6]
160	[6, 6, 6]
180	[6, 6, 6]
200	[6, 6, 6]
400	[8, 8, 8]
600	[9, 9, 9]
800	[10, 10, 10]

Nd2Fe14B

a = b = 8.804 Å
c = 12.205 Å

kppvol	k-mesh
0	[1, 1, 1]
20	[1, 1, 1]
40	[2, 2, 1]
60	[2, 2, 2]
80	[3, 3 ,2]
100	[3, 3, 2]
120	[3, 3, 2]
140	[3, 3, 2]
160	[3, 3, 2]
180	[4, 4, 2]
200	[4, 4, 3]
400	[5, 5, 3]
600	[6, 6, 4]
800	[6, 6, 4]

Input File

Table of Contents

Subsections of Input File

File Format

[basic] Section

[structure] Section

[VASP] Section

kppvol and Force Gamma

[QE] Section

kppvol

pv_term

[OMX] Section

kppvol

ValenceElectrons

[soiap] Section

[LAMMPS] Section

[ASE] Section

[EA] Section

EA

EA-vc

[BO] Section

[LAQA] Section

[visual] Section

Common

EA

EA-vc

[option] Section

Kpoint

What Is the Appropriate Value for kppvol?

Primitive Cell of Diamond Si

Conventional Cell of Diamond Si

Nd2Fe14B