Charge Neutrality Condition

Last updated: October 16, 2026

Single-Valence Species

From version 1.4.1, it is possible to impose a charge neutrality condition during structure generation in EA-vc. This can be applied to both random structure generation and structure generation by evolutionary operations.

In cryspy.in, the charge corresponding to each atype is specified as charge.

The example below assumes a Li–Ca–Cl-like combination of charges, assigning hypothetical charges of +1, +2, and −1 to Cu, Ag, and Au, respectively. Cu–Ag–Au is used as a substitute so that the charge neutrality condition can be tested easily with ASE’s lightweight Pure Python EMT calculator, as in the ASE tutorial.

Example of cryspy.in:

...
[structure]
atype = Cu Ag Au
ll_nat = 0 0 0
ul_nat = 10 10 10
charge = 1 2 -1
...

For example, in this case, only structures that satisfy the charge neutrality condition, such as (Cu, Ag, Au) = (4, 0, 4) or (Cu, Ag, Au) = (4, 2, 8), will be generated.

Note that if add_max or elim_max is too small as shown below, there may be no combinations of atom numbers that satisfy the charge neutrality condition when adding or removing atoms, making structure generation impossible.

...
[structure]
atype = Cu Ag Au
ll_nat = 0 0 0
ul_nat = 10 10 10
charge = 1 2 -1
...
...
[EA]
add_max = 1
elim_max = 1

For example, in the above case, if add_max = 1, there are no combinations of atom numbers that satisfy the charge neutrality condition. If add_max = 2, (Cu, Ag, Au) = (1, 0, 1), that is, adding one Cu and one Au atom, satisfies the charge neutrality condition because (+1) + (-1) = 0. If add_max = 3, there are combinations such as (Cu, Ag, Au) = (1, 0, 1) and (0, 1, 2).

The default values of add_max, elim_max, and subs_max are 5, 5, and 3, respectively.

Multi-Valence Species

From version 1.5.0, CrySPY supports elements with multiple possible oxidation states. Multiple oxidation states can be specified in charge by enclosing them in parentheses or square brackets.

As in the single-valence example, Cu–Au is used as a substitute for a Fe–O-like system so that the charge neutrality condition can be tested easily with ASE’s lightweight Pure Python EMT calculator. Cu is assigned hypothetical charges of +2 or +3, and Au is assigned a hypothetical charge of −2.

Example cryspy.in:

...
[structure]
atype = Cu Au
ll_nat = 0 0
ul_nat = 8 12
charge = (2 3) -2
...

For example, when the numbers of atoms are (Cu, Au) = (1, 1), charge neutrality is satisfied by assigning Cu a charge of +2. When (Cu, Au) = (2, 3), charge neutrality is satisfied by assigning both Cu atoms a charge of +3.

Even when multiple oxidation states are specified, the element is treated as a single atomic species in atype. Therefore, ll_nat and ul_nat specify the lower and upper limits for the total number of atoms of that element, rather than the number of atoms for each oxidation state.

In addition, the generated structures do not distinguish between species such as Cu²⁺ and Cu³⁺. When checking charge neutrality, CrySPY simply determines whether the composition can be neutralized using any combination of the specified oxidation states.

Enumeration and Sampling of Atom-Count Combinations

From v1.5.0, cn_mode in the [structure] section controls how charge-neutral atom-count combinations are determined for random structure generation. This option is used only when charge is specified.

During enumeration, the charge-neutrality equation is used to eliminate one atom-count variable. All possible integer combinations of the remaining variables are examined exhaustively. For each combination, the eliminated variable is calculated and checked to ensure that its value is an integer within the atom-count bounds. max_cn_grid_points limits the number of combinations in this exhaustive search. The default is 200000000.

For example, with charge = 1 2 -1 and atom counts from 0 to 10 for each of Cu, Ag, and Au, the Ag atom-count variable is eliminated. Cu and Au each have 11 possible atom counts. For each combination, the Ag atom count is calculated as (Au atom count − Cu atom count) / 2, giving 11 × 11 = 121 combinations to examine exhaustively. For multi-valence species, the count is calculated similarly after internally expanding each oxidation state into a separate species.

For many atom types or wide atom-count ranges, sampling can reduce the computational cost and memory use associated with enumeration.

[structure]
...
charge = 1 2 -1
cn_mode = auto
max_cn_grid_points = 200000000

In enumerate mode, the enumerated atom-count combinations are selected with equal probability. In sample mode, the selection probabilities are not necessarily uniform.

Combining Charge Neutrality with Composition Constraints

From version 1.5.0, min_comp and max_comp can restrict the composition range in addition to imposing charge neutrality. The example below adds composition constraints to the single-valence Cu–Ag–Au example, using the same hypothetical charges of +1, +2, and −1, respectively.

[structure]
atype = Cu Ag Au
ll_nat = 0 0 0
ul_nat = 10 10 10
charge = 1 2 -1
min_comp = 0.0  0.1  0.4
max_comp = 0.3  0.4  0.7

With these charges, neutrality requires the number of Cu atoms plus twice the number of Ag atoms to equal the number of Au atoms. The composition constraints additionally require the fractions of Cu, Ag, and Au to lie within 0.0–0.3, 0.1–0.4, and 0.4–0.7, respectively, including the boundaries.

For example, a structure with atom counts (Cu, Ag, Au) = (4, 0, 4) is charge neutral, but it is excluded by these composition constraints because its Ag fraction is zero. In contrast, (Cu, Ag, Au) = (1, 2, 5) has a total charge of 1 × (+1) + 2 × (+2) + 5 × (−1) = 0, and its composition (0.125, 0.25, 0.625) is also within the allowed range.

The left figure shows the allowed composition region, and the right figure shows search results through generation 3 with both conditions applied.

The blue region represents only the composition constraints. In this example, charge-neutral compositions lie on a line in the ternary diagram. The search is restricted to compositions where this line overlaps the blue region and the atom-count constraints are also satisfied. For details on composition constraints and their plots, see Composition Constraints.