cryspy-Eplot

Last updated: October 16, 2026

cryspy-Eplot Command

Starting from CrySPY version 1.4.1, the cryspy-Eplot command is installed. In EA-vc, a convex hull plot is automatically generated and saved at the end of each generation by default. Use energy_output_interval in the [option] section to change the output interval or disable automatic output (see Input File > [option] Section). If you wish to modify the plotting parameters afterward, you can regenerate the plot using the cryspy-Eplot command.

For the input parameters that can be changed, see the following page.

• CrySPY > Input File > [visual] Section

Usage and Options

Run the following command in the directory containing cryspy.in.

cryspy-Eplot [options]

Energy Plots (RS, EA)

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

Convex Hull Plots (EA-vc)

Standard Plots (Binary and Ternary Systems)

• CrySPY > Tutorial > EA-vc > Analysis and Visualization

Replotting Specific Generations

• CrySPY > Tutorial > EA-vc > Analysis and Visualization > Replotting with cryspy-Eplot

An example using the convex hull from generation 3 and displaying structures from generation 2.

Plotting with Composition Constraints

• CrySPY > Features > Composition Constraints

Examples of binary and ternary plots with composition constraints. The blue region represents the allowed composition range.

Checking the Composition Range (-c)

From version 1.5.0, the allowed composition range can be plotted using the -c option when composition constraints are specified.

For EA-vc with min_comp or max_comp specified, the following command plots the allowed composition range defined in the current cryspy.in. No search-result data is required, so the constraints can be checked before starting a search.

cryspy-Eplot -c

For standard binary and ternary systems, the plot is saved as ./data/convex_hull/composition_window_input.<fig_format>. fig_format defaults to svg and can be changed to png or pdf in the [visual] section. The species arrangement is specified by axis_order in the same section. The input in the filename indicates that the plot is based on the input at execution time, independently of the generation number.

Examples for binary and ternary systems are shown below.

These plots represent the continuous composition region determined by min_comp and max_comp. They do not account for integer atom-count constraints from ll_nat and ul_nat or charge neutrality from charge. For input examples and an explanation of the plots, see Composition Constraints.

When -c is specified, the command outputs the composition-window plot and exits. To replot the energy or convex hull of search results, run cryspy-Eplot without -c.

Changing Axis Arrangement

Change axis_order in the [visual] section of cryspy.in, then run cryspy-Eplot to redraw the plot with a different arrangement of species. For details, see Tutorial > EA-vc > Analysis and Visualization and Input File > [visual] Section.

For binary systems, assign l (left) and r (right) in the order of atype. The examples below use axis_order = lr (left) and axis_order = rl (right).

For ternary systems, assign t (top), l (left), and r (right) in the order of atype. The examples below use axis_order = tlr (left) and axis_order = ltr (right).

Convex Hulls with Compound Terminals (terminals)

Specify two or three compound compositions with terminals in the [visual] section of cryspy.in to plot a convex hull using those compositions as references. This uses pymatgen’s CompoundPhaseDiagram. Depending on the reference compositions, a ternary system can also be plotted as a pseudo-ternary system, or a quaternary system as a pseudo-ternary system. Here, we show an example of plotting a ternary system as a pseudo-binary system. This setting is for post-analysis with cryspy-Eplot and does not affect convex-hull calculations or natural selection during the search.

The following example uses a ternary Li–Al–O search through generation 30 with a charge neutrality condition imposed. The [structure] section is configured as follows.

[structure]
atype = Li Al O
ll_nat = 0 0 0
ul_nat = 40 40 40
charge = 1 3 -2

Compositions satisfying this charge neutrality condition lie on the line connecting Li2O and Al2O3 in the ternary composition diagram. Using these compound compositions as references therefore allows the convex hull to be plotted as a pseudo-binary Li2O–Al2O3 system. See Features > Charge Neutrality Condition for details on imposing charge neutrality.

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.

To obtain the right figure, configure the [visual] section as follows and run cryspy-Eplot.

[visual]
terminals = Li2O Al2O3

cryspy-Eplot

The output filename includes _terminals_Li2O-Al2O3 to identify the reference compound compositions. In this example, the plot is saved in the default SVG format as ./data/convex_hull/conv_hull_gen_30_terminals_Li2O-Al2O3.svg.

With two compound compositions, omitting terminal_axis_order uses the default lr: Li2O is placed on the left and Al2O3 on the right, following the order in terminals. Each specified compound composition must have an entry in the phase-diagram data used for plotting. See Input File > [visual] Section for parameter details.

cryspy-calc-convex-hull

Last updated: October 16, 2026

cryspy-calc-convex-hull Command

Recalculate the EA-vc convex hull and each structure’s hull distance using results up to a specified generation. Use this after excluding incorrect structures with cryspy-skip or changing the energy cutoffs with emin_ea and emax_ea.

Run the command in the CrySPY calculation directory, specifying a generation number.

cryspy-calc-convex-hull 10

This example uses results from generations 1 through 10 to recalculate the convex hull and hull distances at generation 10. It updates that generation’s data in pd_data.pkl and hdist_data.pkl and writes a hull-distance table. A convex hull plot is also generated for binary and ternary systems.

See Features > Skip Calculations for the detailed procedure.

cryspy-skip

Last updated: October 16, 2026

cryspy-skip Command

Cancel results already recorded in rslt_data.pkl and mark the specified structures as skipped. Use this when incorrect electronic states or similar problems have produced abnormal energies.

Run the command in the CrySPY calculation directory, specifying one or more structure IDs.

cryspy-skip 198 157

This example invalidates the optimized structures and energies for IDs 198 and 157 and sets their Opt values to skip. For EA and EA-vc, these structures are also removed from the elite data if present. For EA-vc, recalculate the convex hull with cryspy-calc-convex-hull as needed.

See Features > Skip Calculations for the detailed procedure and how to skip calculations while they are running.

cryspy-print

Last updated: October 16, 2026

cryspy-print Command

From v1.5.0, cryspy-print lets you inspect pickle files under data/pkl_data/. It replaces CrySPY Utility’s print_pkl.py, displaying contents or a summary according to the file type. For rslt_data.pkl, it also supports sorting by energy, selecting rows, filtering by composition, and regenerating result files.

Usage and Options

cryspy-print infile [options]

The input file can be specified with a relative or absolute path. Gzip-compressed files are also supported. The file type is determined by its filename, so keep names such as rslt_data.pkl unchanged.

--no-sort, --head, --tail, --all, --composition, and --write are options for rslt_data.pkl. --head, --tail, and --all cannot be combined. --write cannot be combined with display options.

Supported Files and Output

The contents of the following files are pretty-printed.

• Common: id_queueing.pkl, id_running.pkl, energy_step_data.pkl, force_step_data.pkl, stress_step_data.pkl, kpt_data.pkl, rng_state_data.pkl
• EA: gen.pkl, ea_info.pkl, ea_origin.pkl, elite_fitness.pkl
• EA-vc: nat_data.pkl
• BO: n_selection.pkl, id_select_hist.pkl, bo_mean.pkl, bo_var.pkl, bo_score.pkl
• LAQA: tot_step_select.pkl, laqa_energy.pkl, laqa_bias.pkl, laqa_score.pkl, laqa_step.pkl, laqa_struc.pkl

An unsupported filename causes an error.

Examples

Checking Structure Counts, Input Settings, and Fitness

cryspy-print ./data/pkl_data/init_struc_data.pkl

Output for a file containing ten entries:

Number of structures: 10

opt_struc_data.pkl and elite_struc.pkl also display the structure count. To inspect individual structures, use the -p option of cryspy-extract-struc.

cryspy-print ./data/pkl_data/input_data.pkl
cryspy-print ./data/pkl_data/elite_fitness.pkl

input_data.pkl displays settings grouped into sections such as [basic] and [structure]. elite_fitness.pkl displays a dictionary of structure IDs and fitness values.

Displaying Results

cryspy-print ./data/pkl_data/rslt_data.pkl

Results are sorted in ascending order of Ef_eV_atom if that column exists, or E_eV_atom otherwise. All rows are displayed if there are at most 100 rows. For larger tables, the command displays the count and sort order, followed by the first 100 rows.

cryspy-print ./data/pkl_data/rslt_data.pkl --head 10
cryspy-print ./data/pkl_data/rslt_data.pkl --tail 5
cryspy-print ./data/pkl_data/rslt_data.pkl --all

These display the first ten rows, last five rows, or all rows of the table sorted by energy in ascending order. Use --no-sort to keep the stored row order. It can be combined with row selection.

cryspy-print ./data/pkl_data/rslt_data.pkl --no-sort --head 10

Filtering EA-vc Results by Composition

cryspy-print ./data/pkl_data/rslt_data.pkl -c 1 2 --head 10

This selects structures with a composition ratio of 1:2 in atype order and displays the first ten rows in ascending energy order. Atom counts such as (1, 2) and (2, 4) match the same ratio. Specify one non-negative integer per element, with at least one positive value. This option requires EA-vc results with a Num_atom column. A message is displayed if no structures match.

For an example with output, see Tutorial > EA-vc > Check Results > Checking Results for a Specific Composition.

Inspecting Gzip-Compressed Files

cryspy-print ./data/pkl_data/rslt_data.pkl.gz --head 10

The file is read without decompression beforehand. Other supported files can also be supplied in gzip-compressed form.

Regenerating Result Files

Run the following in the calculation directory containing cryspy.in.

cryspy-print ./data/pkl_data/rslt_data.pkl --write

This regenerates the following files, overwriting existing files.

• ./data/cryspy_rslt: Results in their stored row order.
• ./data/cryspy_rslt_energy_asc: Results sorted by Ef_eV_atom in ascending order, or E_eV_atom if the former column is absent.

Files are written to data/ under the directory where the command is run. This directory must exist. The operation is also recorded in log_cryspy.

cryspy-extract-struc

Last updated: October 16, 2026

cryspy-extract-struc Command

From v1.5.0, cryspy-extract-struc extracts structures from init_struc_data.pkl or opt_struc_data.pkl and saves them as CIF files. This command integrates CrySPY Utility’s extract_struc.py into CrySPY. It can also print structure information without writing files.

Usage and Options

cryspy-extract-struc infile [options]

The input file can be specified with a relative or absolute path. CIF files are saved in the directory where the command is run. Specify exactly one of -i, -a, or -t; these options cannot be combined.

Examples

Extracting by Structure ID

cryspy-extract-struc ./data/pkl_data/opt_struc_data.pkl -i 0 1

Structures with IDs 0 and 1 are saved as 0.cif and 1.cif in the current directory. Missing IDs are skipped with a warning.

Printing Structure Information

cryspy-extract-struc ./data/pkl_data/opt_struc_data.pkl -i 0 1 -p

With -p, structure IDs and structure information are printed without creating CIF files.

Extracting the Lowest-Energy Structures

cryspy-extract-struc ./data/pkl_data/opt_struc_data.pkl -t 3

This extracts the three lowest-energy structures. rslt_data.pkl must be in the same directory as the input file. Output filenames are {ID}.cif.

Adding -r produces filenames of the form {rank}_{ID}.cif. Ranks start from 1.

cryspy-extract-struc ./data/pkl_data/opt_struc_data.pkl -t 3 -r

Extracting All Structures

cryspy-extract-struc ./data/pkl_data/init_struc_data.pkl -a

All initial structures are saved as {ID}.cif.

Writing Symmetry Information

cryspy-extract-struc ./data/pkl_data/opt_struc_data.pkl -i 0 1 -s --tolerance 0.01

With -s, output CIF files include symmetry information such as the space group. --tolerance is optional. Adding symmetry information may change the cell representation and the number of atoms.

Extracting from Gzip-Compressed Files

cryspy-extract-struc ./data/pkl_data/opt_struc_data.pkl.gz -i 0 1

Gzip-compressed structure data can be read directly without decompression. Options such as -a, -t, -p, and -s can be used in the same way. When using -t, place rslt_data.pkl in the same directory as the compressed input file.