PyXtal: a Python Library for Crystal Structure Generation and Symmetry Analysis

Scott Fredericksa, Dean Sayrea, Qiang Zhua,∗

aDepartment of Physics and Astronomy, University of Nevada Las Vegas, Las Vegas, Nevada 89154, USA

Abstract

We present PyXtal, a new package based on the Python programming language, used to generate structures with specific symmetryand chemical compositions for both atomic and molecular systems. This software provides support for various systems describedby point, rod, layer, and space group symmetries. With only the inputs of chemical composition and symmetry group information,PyXtal can automatically find a suitable combination of Wyckoff positions with a step-wise merging scheme. Further, PyXtal cangenerate different dimensional organic crystals with molecules occupying both general and special Wyckoff positions, when themolecular geometry is given. Optionally, PyXtal also accepts user-defined parameters (e.g., cell parameters, minimum distances).In general, PyXtal serves two purposes: (1) it can be used to generate custom structures, (2) it can be interfaced with existingstructure prediction codes that require the generation of random symmetric structures. In addition, we provide several utilitiesthat facilitate the analysis of structures, including symmetry analysis, geometry optimization, and simulations of powder X-raydiffraction. Full documentation of PyXtal is available at https://pyxtal.readthedocs.io.

Keywords: Symmetry; Crystallography; Structure Prediction; Wyckoff sites; Global optimization

PROGRAM SUMMARYProgram Title: PyXtalLicensing provisions: MIT [1]Programming language: Python 3Nature of problem: Knowledge of structure at the atomic level is thekey to understanding materials’ properties. Typically, the structure ofa material can be determined either from experiment (such as X-raydiffraction, spectroscopy, microscopy) or from theory (e.g., enhancedsampling, structure prediction). In many cases, the structure needsto be solved iteratively by generating a number of trial structuremodels satisfying some constraints (e.g., chemical composition,symmetry, and unit cell parameters). Therefore, it is desirable to havea computational code to be able to generate such trial structures in anautomated manner.Solution method: The PyXtal package is able to generate manypossible random structures for both atomic and molecular systemswith all possible symmetries. To generate the trial structure, thealgorithm can either start with picking the symmetry sites randomlyfrom low to high multiplicities, or use sites that are predefined bythe user. For molecules, the algorithm can automatically detect themolecules’ symmetry and place them into special Wyckoff positionswhile satisfying their compatible site symmetry. With the support ofsymmetry operations for point, rod, layer and space groups, PyXtal issuitable for the computational modeling of systems from zero, one,two, and three dimensional bulk crystals.

References

[1] https://opensource.org/licenses/MIT

∗Corresponding author.E-mail address: qiang.zhu@unlv.edu

1. Introduction

Knowing the atomic structure is the key to understanding theproperties of materials. Ideally, the full atomic structure can beexperimentally determined through single crystal X-ray diffrac-tion. If a single crystal sample is not available, only partialstructural information can be extracted from various charac-terizations, such as powder X-ray diffraction/absorption, Ra-man spectroscopy, nuclear magnetic resonance, and electronmicroscopy. Based on this partial structural information (e.g.,symmetry, unit cell), a number of trial structures are constructedand optimized at their corresponding thermodynamic condi-tions. The simulated pattern for each relaxed structure is thencompared with the observed one. By doing this iteratively, thestructure can be finally resolved. It has been previously demon-strated that structures can be predicted computationally usingfirst-principles [1, 2]. The basic idea of computational structureprediction is to guess the correct crystal structure under specificconditions by computationally sampling a wide range of possi-ble structures via different global optimization techniques (e.g.,random search [3], metadynamics [4], basin hopping [5], evolu-tionary algorithms [6, 7], particle swarm optimization [8]). Af-ter many attempts, the most energetically stable structure foundis the one most likely to exist.

For structure determination from either partial experimen-tal information or pure computation, a number of trial struc-tures are needed. It is generally believed that by beginningwith already-symmetric structures, fewer attempts are neededto find the global energy minimum [3, 9]. For inorganic crys-tals, symmetry constraints have been encoded in many compu-tational structure prediction codes such as AIRSS [3], USPEX[9], CALYPSO [10] and XtalOpt [7]. For a given crystal with

Preprint submitted to Computer Physics Communications December 3, 2019

arX

iv:1

911.

1112

3v1

[co

nd-m

at.m

trl-

sci]

25

Nov

201

9

symmetry, the atomic positions are classified by Wyckoff posi-tions (WP) [11]. Two approaches are used to place the atomsinto the Wyckoff sites so that the structure satisfies the desiredsymmetry. One is to pre-generate a set of WPs and then addatoms to these sites [10, 12]. The other is to place atoms to themost general WPs, and then merge them to the special sites ifthere exist close atomic pairs [9, 13]. This will be repeated untilthe desired stoichiometry is achieved. The development of newcomputational tools has allowed the structures of many new andincreasingly complex materials to be anticipated [2].

For the prediction of organic crystals, the role of symmetryis even more pronounced. In the periodically conducted BlindTests of organic crystal structure prediction organized by theCambridge Crystallographic Data Centre [14], most researchgroups attempted to reduce the structure generation to a limitedrange of space group choices with one molecule in the asym-metric unit (Z′). This is based on a statistical analysis that mostorganic crystals tend to crystallize in only a few space groupswith Z′ = 1 [15]. Currently, there exist a few free packages[16, 17] which allow the generation of random molecular crys-tals with Z′ = 1. Combined with modern structure search algo-rithms (including quasi-random [18], parallel tempering [19],genetic algorithms [20], and evolutionary methods [13]), onecan perform an extensive search for the plausible structures.Their energies can then be evaluated with different energy mod-els from the empirical to ab-initio level. A recent blind test [14]has shown that the combination of effective structure generationand energy ranking scheme can predict not only the structureof simple rigid molecules, but also the molecules representingreal-life challenges.

Despite the fact that many programs have their own built-in functions to generate crystals with specific space groups orclusters with specific point groups, most of these functions areimplemented in the main packages and cannot work in a stan-dalone manner. To our knowledge, there is only one opensource code (Randspg [12]) which provides the interface to gen-erate 3D atomic crystal structures. Similarly, most molecularcrystal generators only support molecules occupying the gen-eral WPs with Z′ = 1, except for the recent development ofGenarris 2.0 [21] which is able to deal with structures having anon-integer value of Z′ (meaning molecules can occupy specialWPs). So far, there is no single code which enables the gen-eration of molecular crystals with arbitrary Z′, varying fromfractional to multiple integers. While 90% of organic crystalsin the Cambridge Structure Database (CSD) have Z′=1, recentadvances in experimental polymorph searching and crystal en-gineering highlight the rich variety of multi-component crys-tals (co-crystals, salts, solvates, etc) as well as crystal structureswith multiple molecules in the asymmetric unit. For instance,many well-studied molecules, including aspirin [22], resorcinol[23], coumarin [24], glycine [25], DDT [26], and ROY [27],were found to adopt crystal structures with Z′ > 1. Lastly,neither Randspg nor Genarris supports the generation of lowdimensional crystals, which require explicit consideration oflayer/rod/point-group (instead of space-group) symmetry oper-ations. Collectively, these cases motivated us to develop a stan-dalone Python program called PyXtal which can be used for

customized structure generation for different-dimensional sys-tems including atomic clusters and 1D/2D/3D atomic/molecu-lar crystals. In sections 2 and 3, we will detail the algorithmsand the software dependencies. The basic useages of PyXtalwill be introduced in Section 4, followed by two example stud-ies using PyXtal in the context of structure prediction in Section5. Finally, we summarize the features of PyXtal and concludethe manuscript in Section 6.

2. Algorithms

PyXtal adopts the following algorithm to generate a trialstructure. First, the user inputs their choice of dimension(0, 1, 2, or 3), symmetry group, stoichiometry, and rel-ative volume of the unit cell. Optionally, additional pa-rameters may be chosen which constrain the unit cell andmaximum inter-atomic distance tolerances. This is imple-mented through the pyxtal.crystal.random crystal and pyx-tal.molecular crystal.molecular crystal Python classes. Next,PyXtal checks if the stoichiometry is compatible with thechoice of symmetry group. If the check passes, trial structuregeneration begins. Figure 1 shows a flowchart of the algorithm.

Figure 1: PyXtal Structure Generation Flowchart. Generation is based on inputsfrom the user.

Each remaining step has a maximum number of attempts.If the generation attempt fails at any point, the algorithm willrevert progress for the current step and try again until the max-imum limit of attempts is encountered. This ensures that thealgorithm stops in a reasonable amount of time, while still giv-ing each generated parameter a chance for success. For certaininputs, structure generation may take many attempts or fail af-ter the maximum number of attempts. Typically, these failuresindicate that the input parameters are not likely to produce arealistic structure without fine-tuning the atomic positions. Insuch cases, a larger unit cell volume or a smaller distance tol-erance may prevent failure. Below we discuss the technical de-tails implemented during structure generation.

2

2.1. Wyckoff Compatibility Checking

Before generating a trial structure, PyXtal performs a WPcompatibility check. Since WPs in different space groups havedifferent multiplicities, this is a required step that ensures com-patibility between a stoichiometry and its assigned space group.For example, consider the space group Pn-3n (#222), which hasa minimum WP of 2a, followed by 6b. To create a crystal struc-ture with 4 atoms in the unit cell for this symmetry group, thecombination of Wyckoff positions must add up to 4. Here, thisis not possible. The position 2a cannot be repeated, becauseit falls on the exact coordinates (1/4, 1/4, 1/4) and (3/4, 3/4,3/4). A second set of atoms in the 2a position would overlapthe atoms in the first position, which is physically impossible.

Thus, from our previous discussion, it is necessary to checkthe input stoichiometry against the WPs of the desired spacegroup. PyXtal implements this by iterating through all possiblecombinations of WPs within the confinements of the given sto-ichiometry. As soon as a valid combination is found, the checkreturns True. Otherwise, if no valid combination is found, thecheck returns False and the generation attempt raises a warning.

Some space groups allow valid combinations of WPs, but donot permit many (or any) positional degrees of freedom withinthe structure. It may also be the case that the allowed combi-nations result in atoms which are too close together. In thesecases, PyXtal will attempt generation as usual: it will continueto search for a compatible structure until the maximum limit isreached, or until a successful generation occurs. In the eventthat structure generation repeatedly fails for a given combina-tion of space group and stoichiometry, the user should makenote and avoid the combination going forward.

2.2. Lattice Generation

The first step in PyXtal’s structure generation is the choiceof unit cell. Depending on the symmetry group, a specific typeof lattice must be generated. For all crystals, the conventionalcell choice is used to avoid ambiguity. Lattice information canbe pre-defined by the user in either vector form (a, b, c, α, β,γ) or in the form of a 3×3 matrix . If lattice information isnot provided, PyXtal will attempt to estimate the volume basedon the chemical composition, resulting in the generation of arandom unit cell which satisfies the input constraints.

The most general case is the triclinic cell, from which othercell types can be obtained by applying certain constraints. Togenerate a triclinic cell, 3 real numbers are randomly chosen(using a Gaussian distribution centered at 0) as the off-diagonalvalues for a 3x3 shear matrix. By treating this shear matrixas a cell matrix, one obtains 3 lattice angles. For the latticevector lengths, a random 3-vector between (0,0,0) and (1,1,1) ischosen (using a Gaussian distribution centered at (0.5,0.5,0.5)).The relative values of the x, y, and z coordinates are used for a,b, and c respectively, and scaled based on the required volume.For other cell types, any free parameters are obtained using thesame methods as for the triclinic case, and then constraints areapplied. In the tetragonal case, for example, all angles will befixed to 90 degrees. Thus, only a random vector is needed togenerate the lattice constants.

For low-dimensional systems, not all three unit cell axes areperiodic. Therefore, the algorithm must be altered slightly, asdescribed below.

For the 2D case, we choose c to be the non-periodic axis bydefault. For layer groups 3-7 (P112, P11m, P11a, P112/m,P112/a), c is also the unique axis; for all other layer groups, ais the unique axis. The length of c (the crystal’s “thickness”) isan optional parameter which can be specified by the user. If nothickness is given, the algorithm will automatically compute arandom value based on a Gaussian distribution centered at thecubic root of the estimated volume. In other words, c will havethe same length as the other axes on average.

For the 1D case, c is the periodic axis by default. For rodgroups 3-7 (P221, Pm11, Pc11, P2/m11, P2/c11), a is theunique axis; for all other rod groups, c is the unique axis. In-stead of choosing a value for the thickness, we constrain theunit cell based on the cross-sectional area of the a-b plane. Thisarea can be either specified by the user or generated randomly.As with the 2D and 3D cases, there is no preference for anyaxis to be longer or shorter than the others unless specified bythe user.

For 0D clusters, we constrain the atoms to lie within either asphere or an ellipsoid, depending on the point group. For spher-ically or polyhedrally symmetric point groups (C1, Ci, D2, D2h,T , Th, O, Td, Oh, I, Ih), we define a sphere centered on the ori-gin. For all other point groups (which have a unique rotationalaxis), we define an ellipsoid with its c-axis aligned with therotational axis. The a- and b-axes are always of equal lengthto ensure rotational symmetry about the c-axis. The relativelengths for the ellipsoidal axes are chosen in the same way asfor the 3D tetragonal case. In order for the 0D case to be com-patible with the 1D, 2D, and 3D cases, we encode the spheresand ellipsoids as lattices (a cubic lattice for a sphere, or tetrag-onal lattice for an ellipsoid). Then, when generating atomiccoordinates, we check whether the randomly chosen point lieswithin the sphere or ellipsoid. If not, we simply retry until itdoes.

2.3. Wyckoff Position Selection and MergingThe central building block for crystals in PyXtal is the WP.

Once a space group and lattice are chosen, WPs are insertedone at a time to add structure. In PyXtal, we closely follow thealgorithm provided in Ref. [9] to place the atoms in differentWPs. In general, PyXtal starts with the largest available WP,which is the general position of the symmetry group. If thenumber of atoms required is equal to or greater than the sizeof the general position, the algorithm proceeds. If fewer atomsare needed, the next largest WP (or set of WPs) is chosen, inorder of descending multiplicity. This is done to ensure thatlarger positions are preferred over smaller ones; this reflects thegreater prevalence of larger multiplicities seen in nature.

Once a WP is chosen, a random 3-vector between (0,0,0)and (1,1,1) is created. We call this the generating point for theWP. Using the closest projection of this vector onto the WP(the WP being a periodic set of points, lines, or planes), oneobtains a set of coordinates in real space (the atomic positionsfor that WP). Then, the distances between these coordinates are

3

checked. If the atom-atom distances are all greater than a pre-defined limit, the WP is kept and the algorithm continues. Ifany of the distances are too small, it is an indication that theWP would not occur with the chosen generating point. In thiscase, the coordinates are merged together into a smaller WP, ifpossible. This merging continues until the atoms are no longertoo close together (see Figure 2).

To merge into a smaller position, the original generatingpoint is projected into each of the remaining WPs. The WPwith the smallest translation between the original point and thetransformed point is chosen, provided that (1) the new WP isa subset of the original one, and (2) the new points are not tooclose to each other. If the atoms are still too close together afterall possible mergings, the WP is discarded and another attemptis made.

8c 4a

4b 1o

Figure 2: Wyckoff Position Merging Example. Shown are possible mergingsof the general position 8c of the 2D point group 4mm. Moving from 8c to 4b(along the solid arrows) requires a smaller translation than from 8c to 4a (alongthe dashed arrows). Thus, if the atoms in 8c were too close together, PyXtalwould merge them into 4b instead of 4a. The atoms could be further mergedinto position 1o by following the arrows shown in the bottom right image.

Once a WP is successfully filled, the inter-atomic dis-tances between the current WP and the already-added WPs arechecked. If all distances are acceptable, the algorithm con-tinues. More WPs are then added as needed until the desirednumber of atoms is reached. At this point, either a satisfactorystructure has been generated, or the generation has failed. Ifthe generation fails, then choosing either smaller distances tol-erances or a larger volume factor might increase the chancesof success. However, altering these quantities too drasticallymay result in less realistic crystals. Common sense and system-specific considerations should be applied when adjusting theseparameters.

2.4. Distance Checking

To produce structures with realistic bonds and bond lengths,the generated atoms should not be too close together. In PyXtalthis means that by default, two atoms should be no closer thanthe covalent bond length between them. However, for a givenapplication, the user may decide that shorter or longer cutoff

distances are appropriate. For this reason, PyXtal has a customtolerance matrix class which allows the user to define the dis-tances allowed between any two atomic species. There are alsooptions to use the metallic bond lengths, or to simply scale theallowed distances by some factor.

Because crystals have periodic symmetry, any point in a crys-tal actually corresponds to an infinite lattice of points. Like-wise, any separation vector between two points actually corre-sponds to an infinite number of separation vectors. For the pur-poses of distance checking, only the shortest of these vectorsare relevant. When a lattice is non-Euclidean, the problem offinding shortest distances with periodic boundary conditions isnon-trivial, and the general solution can be computationally ex-pensive [28]. So instead, PyXtal uses an approximate solutionbased on assumptions about the lattice geometry:

For any two given points, PyXtal first considers only the sep-aration vector which lies within the “central” unit cell spanningbetween (0,0,0) and (1,1,1). For example, if the original two(fractional) points are (-8.1, 5.2, -4.8) and (2.7, -7.4, 9.3), onecan directly obtain the separation vector (-10.8, 12.6, -14.1).This vector lies outside of the central unit cell, so we translateby the integer-valued vector (11.0, -12.0, 15.0) to obtain (0.2,0.6, 0.9), which lies within the central unit cell. PyXtal alsoconsiders those vectors lying within a 3×3×3 supercell centeredon the first vector. In this example, these would include (1.2,1.6, 1.9), (-0.8, -0.4, -0.1), (-0.8, 1.6, 0.9), etc. This gives atotal of 27 separation vectors to consider. After converting toabsolute coordinates (by dotting the fractional vectors with thecell matrix), one can calculate the Euclidean length of each ofthese vectors and thus find the shortest distance.

Note that this does not work for certain vectors within somehighly distorted lattices (see Figure 3). Often the shortest Eu-clidean distance is accompanied by the shortest fractional dis-tance, but whether this is the case or not depends on how dis-torted the lattice is. However, because randomly generated lat-tices in PyXtal are required to have no angles smaller than 30degrees or larger than 150 degrees, this is not an issue.

For two given sets of atoms (for example, when cross-checking two WPs in the same crystal), one can calculate theshortest inter-atomic distances by applying the above procedurefor each unique pair of atoms. This only works if it has alreadybeen established that both sets on their own satisfy the neededdistance requirements.

Thanks to symmetry, one need not calculate every atomicpair between two WPs. For two WPs, A and B, it is only nec-essary to calculate either (1) the separations between one atomin A and all atoms in B, or (2) one atom in B and all atoms inA. This is because the symmetry operations which duplicate apoint in a WP also duplicate the separation vectors associatedwith that point. This is also true for a single WP; for example,

4

Figure 3: Distorted Unit Cell. Due to the cell’s high level of distortion, theclosest neighbors for a single point lie more than two unit cells away. In thiscase, the closest point to the central point is located two cells to the left and onecell diagonal-up. To find this point using PyXtal’s distance checking method,a 5×5×5 unit cell will be created. For this reason, a limit is placed on thedistortion of randomly generated lattices.

in a Wyckoff position with 16 points, only 15 (the number ofpairs involving one atom) distance calculations are needed, asopposed to 120 (the total number of pairs). This can signifi-cantly speed up the calculation for larger WPs.

For a single WP, it is necessary to calculate the distances foreach unique atom-atom pair, but also for the lattice vectors foreach atom by itself. Since the lattice is the same for all atomsin the crystal, this check only needs to be performed on a sin-gle atom of each specie. For atomic crystals, this just meansensuring that the generated lattice vectors are sufficiently long.

For molecules, the process is slightly more complicated. De-pending on the molecule’s orientation within the lattice, theinter-atomic distances can change. Additionally, one must cal-culate the distances not just between molecular centers, but be-tween every unique atom-atom pair. This increases the numberof needed calculations in rough proportion to the square of sizeof the molecules. As a result, this is typically the largest timecost for generation of molecular crystals. The issue of check-ing the lattice is also dependent on molecular orientation. Thus,the lattice must be checked for every molecular orientation inthe crystal. To do this, the atoms in the original molecule arechecked against the atoms in periodically translated copies ofthe molecule. Here, standard atom-atom distance checking isused. While several approximate methods for inter-moleculardistance checking exist, their performance is highly dependenton the molecular shape and number of atoms. The simplestmethod is to model the molecule as a sphere, in which caseonly the center-center distances are needed. This works wellfor certain molecules, like buckminsterfullerene, which havea large number of atoms and are approximately spherical inshape. But a spherical model works poorly for irregularlyshaped molecules like benzene (see Figure 4), which may haveshort separations along the perpendicular axis, but must be fur-ther apart along the planar axes. We provide spherical distancechecking as an option for the user, but direct atom-atom dis-tance checking is used by default.

Figure 4: Dependence of shortest distances on molecular orientation. Rotationof the molecules about the a or b (but not the c) axes would cause the ben-zene molecules to overlap. PyXtal checks for overlap whenever a molecularorientation is altered.

2.5. Molecular Orientations

In crystallography, atoms are typically assumed to be spher-ically symmetric point particles with no well-defined orienta-tion. Since the object occupying a crystallographic WP is usu-ally an atom, it is further assumed that the object’s symmetrygroup contains the WP’s site symmetry as a subgroup. If this isthe case, the only remaining condition for occupation of a WPis the location within the unit cell. However, if the object is in-stead a molecule, then the WP compatibility is also determinedby orientation and shape.

To handle the general case, one must ensure that the object is(1) sufficiently symmetric, and is (2) oriented such that its sym-metry operations are aligned with the Wyckoff site symmetry.The result is that objects with different point group symmetriesare only compatible with certain WPs. For a given moleculeand WP, one can find all valid orientations as follows:

1. Determine the molecule’s point group and point groupoperations. This is currently handled by Pymatgen’s built-inPointGroupAnalyzer class [29], which produces a list of sym-metry operations for the molecule.

2. Associate an axis to every symmetry operation. For arotation or improper rotation, we use the rotational axis. For amirror plane, we use an axis perpendicular to the plane. Notethat inversional symmetry does not add any constraints, sincethe inversion center is always located at the molecule’s centerof mass.

3. Choose up to two non-collinear axes from the site sym-metry and calculate the angle between them. Find all conjugateoperation pairs (with the same order and type) in the molecu-lar point symmetry with the same angle between the axes, andstore the rotation which maps the pairs of axes onto each other.For example, if the site symmetry were mmm, then we couldchoose two reflectional axes, say the x- and y- axes or the y-and z- axes. Then, we would look for two reflection operationsin the molecular symmetry group. If the angle between thesetwo operation axes is also 90 degrees, we would store the rota-tion which maps the two molecular axes onto the Wyckoff axes.We would also do this for every other pair of reflections with90 degrees separating them.

5

4. For a given pair of axes, there are two rotations which canmap one onto the other. There is one rotation which maps thefirst axis directly onto the second, and another rotation whichmaps the first axis onto the opposite of the second axis. De-pending on the molecular symmetry, the two resulting orienta-tions may or may not be symmetrically equivalent. So, usingthe list of rotations calculated in step 3, remove redundant ori-entations which are equivalent to each other.

5. For each found orientation, check that the rotated moleculeis symmetric under the Wyckoff site symmetry. To do this, sim-ply check the site symmetry operations one at a time by ap-plying each operation to the molecule and checking for equiva-lence with the untransformed molecule.

6. For the remaining valid orientations, store the rotationmatrix and the number of degrees of freedom. If two axes wereused to constrain the molecule, then there are no degrees offreedom. If one axis is used, then there is one rotational degreeof freedom, and we store the axis about which the moleculemay rotate. If no axes are used (because there are only pointoperations in the site symmetry), then there are three (storedinternally as two) degrees of freedom, meaning the moleculecan be rotated freely in 3 dimensions.

PyXtal performs these steps for every WP in the symmetrygroup and stores the nested list of valid orientations. When amolecule must be inserted into a WP, an allowed orientation israndomly chosen from this list. This forces the overall symme-try group to be preserved since symmetry-breaking WPs do nothave any valid orientations to choose from. The above algo-rithm is particularly useful to generate molecular crystals withnon-integer number of molecules in the asymmetric unit, whichoccur frequently for molecules with high point group symme-try.

One important consideration is whether a symmetry groupwill produce inverted copies of the constituent molecules. Inmany cases, a chiral molecule’s mirror image will possess dif-ferent chemical or biological properties [30]. For pharmaceu-tical applications in particular, one may not want to considercrystals containing mirror molecules. By default, PyXtal doesnot generate crystals with mirror copies of chiral molecules.The user can choose to allow inversion if desired.

3. Dependencies

All of the code is written in Python 3. Like many otherPython packages, it relies on several external libraries. Numpy[31], Scipy [32] and Pandas [33] are required for the generalpurposes of scientific computing and data processing. In addi-tion, two materials science libraries, Pymatgen [29] and Spglib[34], were used to facilitate the symmetry analysis. Option-ally, the code provides an interface with Openbabel [35] if theusers wants to import the molecules from additional file for-mats other than the plain xyz format. An ASE [36] interfaceis also enabled if the user wants to do further structure analysissuch as structure manipulation or geometry optimization basedon ASE.

4. Example Usages

PyXtal can be either used as a binary executable or stand-alone library for use in Python scripts. Below we introduce thebasic usages in brief.

4.1. Command line utilities

Currently, several utilities are available to access the differentfunctionality of PyXtal. They include:

1. PyXtal symmetry2. Pyxtal atom3. Pyxtal molecule4. Pyxtal test

First, the users are advised to run Pyxtal test to quickly testif all modules are working correctly after the installation. Therest of the utilities are designed for different analysis purposes.

The PyXtal symmetry utility allows one to easily access thesymmetry information for a given symmetry group using eitherthe group name or international number.

$ pyxtal_symmetry -s 36

-- Space group # 36 (Cmc2_1)--

8b site symm: 1

x, y, z

-x, -y, z+1/2

x, -y, z+1/2

-x, y, z

x+1/2, y+1/2, z

-x+1/2, -y+1/2, z+1/2

x+1/2, -y+1/2, z+1/2

-x+1/2, y+1/2, z

4a site symm: m..

0, y, z

0, -y, z+1/2

1/2, y+1/2, z

1/2, -y+1/2, z+1/2

Listing 1: Example usage of the pyxtal symmetry utility.

PyXtal atom and Pyxtal molecule can be used to directlygenerate one trial structure based on the given symmetry groupand chemical composition. Below we give the example scriptsto generate different types of symmetric objects, including

1. a random C60 cluster with Ih point group symmetry;2. a trial diamond structure with Fd-3m space group symme-

try;3. a crystal of two C60 molecules per primitive unit cell with

Cmc21 symmetry

$ pyxtal_atom -e C -n 60 -d 0 -s Ih

$ pyxtal_atom -e C -n 2 -s 227

$ pyxtal_molecule -e C60 -n 2 -s 36

Listing 2: Example usages of the pyxtal atom and pyxtal molecule utilities.

The generated structures will be saved to text files in cif for-mat for crystals and xyz format for clusters.

6

4.2. PyXtal as a LibraryPyXtal allows the user to generate random crystal structures

with given symmetry constraints. There are several parameterswhich can be specified, but only a few are necessary. Below isan example script to generate 100 random clusters for 36 carbonatoms.from pyxtal.crystal import random_cluster

from random import choice

pgs = range(1, 33)

clusters = []

for i in range (100):

run = True

while run:

pg = choice(pgs)

cluster = random_cluster(pg , [’C’], [36])

if cluster.valid:

clusters.append(cluster)

Listing 3: A Python script to generate 100 random C36 clusters

With the generated structures, one can perform further analy-sis such as geometry optimization and powder X-ray diffractionpattern simulation. PyXtal also provides the preliminary mod-ules for such tasks. Alternatively, the trial structures can beeasily adapted to the structural objects for other libraries suchas ASE [36] or Pymatgen [29], or be dumped to text files in cif,xyz or POSCAR format. More examples can be found in theonline documentation https://pyxtal.readthedocs.io.

5. Applications

Our primary purpose of developing PyXtal is to provide morelikely trial structures to solve the structural determination prob-lem. It can be useful for at least two cases. First, one cangenerate the trial structures based on the partial informationdetermined from experiment (e.g., unit cell, symmetry, com-position). Secondly, it can be used to determine the groundstate structure in a first-principle manner based on global opti-mization. It has been shown [6, 10, 12] that by beginning withalready-symmetric structures, fewer attempts are needed to findthe global energy minimum. To demonstrate the general util-ity of pre-symmetrization, we performed a number of bench-marks for different systems. Below we give two examples forthe global structural search on the low-energy Lennard-Jones(LJ) clusters and carbon/silicon allotropes.

5.1. Clusters with empirical Lennard-Jones potentialFinding the ground state of LJ clusters of given size is an

established benchmark for global optimization methods [5].Here, it shown that local optimization, combined with randomlygenerated symmetric clusters, is sufficient to solve the problemwith small sizes of LJ clusters. For the purposes of this bench-mark, we focus on three cluster sizes, namely 38, 55, and 75.For each cluster size, 20,000 structures were generated: 10,000with no pre-defined symmetry, and 10,000 with symmetry cho-sen randomly from among PyXtal’s 56 built-in point groups1.

1This includes 32 crystallographic point groups and 24 non-crystallographicpoint groups. The full symmetry information can be accessed by the commandof pyxtal symmetry -d 0

A potential of 4( 1r12 −

1r6 ) was assigned to each atom-atom pair.

Each structure was locally optimized using the conjugate gra-dient (CG) method in SciPy’s optimize.minimize function [32].As shown in Figure 5, the ground state was found much morefrequently when the initial structures possessed some pointgroup symmetry. With pre-symmetrization, the ground statewas found 278 times for size 38 clusters, 73 times for size 55,and 1 time for size 75. Without pre-symmetrization, the groundstate was not found at all. Though the numbers of hits on theground states may change in another run, the statistical rule stillholds. Second, while the ground state is found more frequentlywith pre-symmetrization, the average energy is higher. This isbecause pre-symmetrization spans the possible structure spacemore effectively, while purely random structures are more clus-tered around a specific energy range.

Figure 5: Energy distribution for Lennard Jones clusters with the sizes of (a)38, (b) 55 and (c) 75. The insets are the corresponding ground state geometries.

5.2. Carbon and silicon crystals with ab-initio calculationsWe also combined PyXtal with ab-initio codes to search for

the elemental allotropes of carbon and silicon at 0 K and ambi-ent pressure. 1000 random structures each were generated for 2,4, 6, 8, and 16 atoms in the primitive unit cell. A random spacegroup between 2 and 230 was chosen for each structure. Thisgave a total of 5000 structures for each element. Each structurewas optimized using the PBE-GGA functional [37] as imple-mented in the VASP code [38, 39], following a multiple-stepstrategy from low, normal, to accurate precision. The final ge-ometries were then calculated with an energy cutoff of 600 eVand 0.15 K-spacing. For carbon, the expected structures of dia-mond and graphite were found frequently in each run, as well as

7

2 4 6 8 16Number of atoms in the primitive cell

8

6

4

2

0

Latti

ce e

nerg

y (e

V/at

om) (a) carbon

2 4 6 8 16Number of atoms in the primitive cell

5

4

3

2

1

0

Latti

ce e

nerg

y (e

V/at

om) (b) silicon

Figure 6: The box and whisker plots for the energy distribution of the randomlygenerated (a) carbon and (b) silicon crystals with 2, 4, 6, 8, 16 atoms per prim-itive unit cell.

londsdaelite, sp3 carbon with various ring topologies, and var-ious multi-layer graphite-like structures. Similarly, our simula-tion on silicon yielded the ground state of cubic diamond struc-tures for each of the runs with different numbers of atoms perprimitive unit cell, demonstrating that adding symmetry con-straints is beneficial to quickly identify the low-energy struc-tures with high symmetry. Moreover, it is again interestingto analyze the energy distribution of the randomly generatedstructures as shown in Figure 6. For both carbon and silicon,the energy landscape appears to be narrower for size-2 primi-tive cells. It appears that beyond about 4, the number of atomsin the primitive cell has little influence on the energy distribu-tion. This again suggests that pre-symmetrization is an effec-tive means to prevent the clustering of glassy structures foundin pure random generations for large systems [9]. Therefore,pre-symmetrization provides a better choice for global energyoptimization. In addition, pre-symmetrization can provide amore diverse dataset for training machine learning force fields[40, 41].

6. Conclusion

In this manuscript, we present a software package PyXtal.The core features of PyXtal have been highlighted, with fur-ther documentation available online2. In PyXtal, the symmetryconstraints are further refined in two main ways. The first is amerging algorithm [13] which controls the distribution of WPsthrough statistical means. The second is a new algorithm forplacing molecules into special WPs. This allows for more re-alistic and complex structures to be generated without reducing

2https://pyxtal.readthedocs.io

the global symmetry. PyXtal is not a complete structure predic-tion package; it only generates the trial structures with a givensymmetry group. Other tools exist which perform structuregeneration and other steps in the CSP process [9, 3, 7, 10]. Themain goals in developing PyXtal are: 1) to develop a free, open-source Python package for the materials science community, 2)to handle the generation of symmetric structures described bydifferent symmetry groups from 0D to 3D, 3) to handle molecu-lar WPs in a generalized manner, 4) to provide a tool to look upthe symmetry information from the database. We also demon-strated that using the pre-symmetrized structures as the startingseeding structures can effectively improve the success rate offinding the low energy configuration. As such, PyXtal can beinterfaced to the other structure prediction codes which requirethe generation of trial structures. Access to the source codeand development information are available on the GitHub pageat https://github.com/qzhu2017/PyXtal. The code is currentlyunder version 0.0.2 at the time of writing. It is expected toupdate frequently. Further development and application of themathematical background should enable more complex struc-ture types to be studied in the future.

Acknowledgments

We acknowledge the NSF (I-DIRSE-IL: 1940272) andNASA (80NSSC19M0152) for their financial supports.The computing resources are provided by XSEDE (TG-DMR180040).

References

[1] A. R. Oganov, Modern methods of crystal structure prediction, John Wi-ley & Sons, 2011. doi:10.1002/9783527632831.

[2] A. R. Oganov, C. J. Pickard, Q. Zhu, R. J. Needs, Structure predictiondrives materials discovery, Nat. Rev. Mater. 4 (2019) 331–348. doi:

10.1038/s41578-019-0101-8.[3] C. J. Pickard, R. Needs, Ab initio random structure searching, J. Phys.

Condens. Matter 23 (5) (2011) 053201. doi:10.1088/0953-8984/23/5/053201.

[4] R. Martonak, A. Laio, M. Parrinello, Predicting crystal structures: Theparrinello-rahman method revisited, Phys. Rev. Lett. 90 (7) (2003)075503. doi:10.1103/PhysRevLett.90.075503.

[5] D. J. Wales, J. P. K. Doye, Global optimization by basin-hopping and thelowest energy structures of lennard-jones clusters containing up to 110atoms, The Journal of Physical Chemistry A 101 (28) (1997) 5111–5116.doi:10.1021/jp970984n.

[6] A. R. Oganov, C. W. Glass, Crystal structure prediction using ab ini-tio evolutionary techniques: Principles and applications, J. Chem. Phys.124 (24) (2006) 244704. doi:10.1063/1.2210932.

[7] D. C. Lonie, E. Zurek, Xtalopt: An open-source evolutionary algorithmfor crystal structure prediction, Comput. Phys. Commun. 182 (2) (2011)372 – 387. doi:https://doi.org/10.1016/j.cpc.2010.07.048.

[8] Y. Wang, J. Lv, L. Zhu, Y. Ma, Crystal structure prediction via particle-swarm optimization, Phys. Rev. B 82 (9) (2010) 094116. doi:10.1103/PhysRevB.82.094116.

[9] A. O. Lyakhov, A. R. Oganov, H. T. Stokes, Q. Zhu, New developments inevolutionary structure prediction algorithm uspex, Comput. Phys. Com-mun. 184 (4) (2013) 1172–1182. doi:10.1016/j.cpc.2012.12.009.

[10] Y. Wang, J. Lv, L. Zhu, Y. Ma, Calypso: A method for crystal structureprediction, Comput. Phys. Commun. 183 (10) (2012) 2063 – 2070. doi:https://doi.org/10.1016/j.cpc.2012.05.008.

[11] H. Wondratschek, M. I. Aroyo, Chapter 1.2. crystallographic symmetry,International Tables for Crystallography A (2016) 12–21.

8

[12] P. Avery, E. Zurek, Randspg: An open-source program for generatingatomistic crystal structures with specific spacegroups, Comput. Phys.Commun. 213 (2017) 208–216. doi:10.1016/j.cpc.2016.12.005.

[13] Q. Zhu, A. Oganov, C. Glass, H. T Stokes, Constrained evolutionary algo-rithm for structure prediction of molecular crystals: Methodology and ap-plications, Acta crystallographica. Section B, Structural science 68 (2012)215–26. doi:10.1107/S0108768112017466.

[14] A. M. Reilly, R. I. Cooper, C. S. Adjiman, S. Bhattacharya, A. D. Boese,J. G. Brandenburg, P. J. Bygrave, R. Bylsma, J. E. Campbell, R. Car, D. H.Case, R. Chadha, J. C. Cole, K. Cosburn, H. M. Cuppen, F. Curtis, G. M.Day, R. A. DiStasio Jr, A. Dzyabchenko, B. P. van Eijck, D. M. Elk-ing, J. A. van den Ende, J. C. Facelli, M. B. Ferraro, L. Fusti-Molnar,C.-A. Gatsiou, T. S. Gee, R. de Gelder, L. M. Ghiringhelli, H. Goto,S. Grimme, R. Guo, D. W. M. Hofmann, J. Hoja, R. K. Hylton, L. Iuz-zolino, W. Jankiewicz, D. T. de Jong, J. Kendrick, N. J. J. de Klerk, H.-Y. Ko, L. N. Kuleshova, X. Li, S. Lohani, F. J. J. Leusen, A. M. Lund,J. Lv, Y. Ma, N. Marom, A. E. Masunov, P. McCabe, D. P. McMahon,H. Meekes, M. P. Metz, A. J. Misquitta, S. Mohamed, B. Monserrat, R. J.Needs, M. A. Neumann, J. Nyman, S. Obata, H. Oberhofer, A. R. Oganov,A. M. Orendt, G. I. Pagola, C. C. Pantelides, C. J. Pickard, R. Podeszwa,L. S. Price, S. L. Price, A. Pulido, M. G. Read, K. Reuter, E. Schneider,C. Schober, G. P. Shields, P. Singh, I. J. Sugden, K. Szalewicz, C. R.Taylor, A. Tkatchenko, M. E. Tuckerman, F. Vacarro, M. Vasileiadis,A. Vazquez-Mayagoitia, L. Vogt, Y. Wang, R. E. Watson, G. A. de Wijs,J. Yang, Q. Zhu, C. R. Groom, Report on the sixth blind test of organiccrystal structure prediction methods, Acta Cryst. B 72 (4) (2016) 439–459. doi:10.1107/S2052520616007447.

[15] W. H. Baur, D. Kassner, The perils of cc: comparing the frequenciesof falsely assigned space groups with their general population, ActaCrystallographica Section B 48 (4) (1992) 356–369. doi:10.1107/

S0108768191014726.[16] B. P. van Eijck, J. Kroon, Upack program package for crystal structure

prediction: force fields and crystal structure generation for small carbohy-drate molecules, J. Comp. Chem. 20 (8) (1999) 799–812. doi:10.1002/(SICI)1096-987X(199906)20:8<799::AID-JCC6>3.0.CO;2-Z.

[17] J. R. Holden, Z. Du, H. L. Ammon, Prediction of possible crystal struc-tures for c-, h-, n-, o-, and f-containing organic compounds, J. Comp.Chem. 14 (4) (1993) 422–437. doi:10.1002/jcc.540140406.

[18] D. H. Case, J. E. Campbell, P. J. Bygrave, G. M. Day, Convergenceproperties of crystal structure prediction by quasi-random sampling, J.Chem. Theory Comput. 12 (2) (2016) 910–924. doi:10.1021/acs.

jctc.5b01112.[19] M. A. Neumann, F. J. Leusen, J. Kendrick, A major advance in crystal

structure prediction, Angew. Chem. Int. Ed. 120 (13) (2008) 2461–2464.doi:10.1002/anie.200704247.

[20] F. Curtis, X. Li, T. Rose, A. Vazquez-Mayagoitia, S. Bhattacharya, L. M.Ghiringhelli, N. Marom, Gator: A first-principles genetic algorithm formolecular crystal structure prediction, J. Chem. Theory Comput. 14 (4)(2018) 2246–2264. doi:10.1021/acs.jctc.7b01152.

[21] R. Tom, T. Rose, I. Bier, H. O’Brien, A. Vazquez-Mayagoitia, N. Marom,Genarris 2.0: A random structure generator for molecular crystals (2019).arXiv:1909.10629.

[22] A. G. Shtukenberg, C. T. Hu, Q. Zhu, M. U. Schmidt, W. Xu, M. Tan,B. Kahr, The third ambient aspirin polymorph, Cryst. Growth Des., 17 (6)(2017) 3562–3566. doi:10.1021/acs.cgd.7b00673.

[23] Q. Zhu, A. G. Shtukenberg, D. J. Carter, T.-Q. Yu, J. Yang, M. Chen,P. Raiteri, A. R. Oganov, B. Pokroy, I. Polishchuk, P. J. Bygrave, G. M.Day, A. L. Rohl, M. E. Tuckerman, B. Kahr, Resorcinol Crystallizationfrom the Melt: A New Ambient Phase and New “Riddles”, J. Am. Chem.Soc. 138 (14) (2016) 4881–4889. doi:10.1021/jacs.6b01120.

[24] A. G. Shtukenberg, Q. Zhu, D. J. Carter, L. Vogt, J. Hoja, E. Schnei-der, H. Song, B. Pokroy, I. Polishchuk, A. Tkatchenko, et al., Powderdiffraction and crystal structure prediction identify four new coumarinpolymorphs, Chem. Sci. 8 (7) (2017) 4926–4940. doi:10.1039/

C7SC00168A.[25] W. Xu, Q. Zhu, C. T. Hu, The structure of glycine dihydrate: implications

for the crystallization of glycine from solution and its structure in outerspace, Angew. Chem. Int. Ed. 129 (8) (2017) 2062–2066. doi:10.1002/ange.201610977.

[26] J. Yang, C. T. Hu, X. Zhu, Q. Zhu, M. D. Ward, B. Kahr, DDT Poly-morphism and the Lethality of Crystal Forms, Angewandte Chemie In-

ternational Edition 56 (34) (2017) 10165–10169. doi:10.1002/anie.201703028.

[27] M. Tan, A. Shtukenberg, S. Zhu, W. Xu, E. Dooryhee, S. M. Nichols,M. D. Ward, B. Kahr, Q. Zhu, Roy revisited, again: The eighth solvedstructure, Faraday Discuss.doi:10.1039/C8FD00039E.

[28] L. Babai, On lovasz’ lattice reduction and the nearest lattice point prob-lem, Combinatorica 6 (1) (1986) 1–13. doi:10.1007/BF02579403.

[29] S. P. Ong, W. D. Richards, A. Jain, G. Hautier, M. Kocher, S. Cholia,D. Gunter, V. L. Chevrier, K. A. Persson, G. Ceder, Python materialsgenomics (pymatgen): A robust, open-source python library for materialsanalysis, Computational Materials Science 68 (2013) 314 – 319. doi:

https://doi.org/10.1016/j.commatsci.2012.10.028.[30] I.-H. Suh, K. H. Park, W. P. Jensen, D. E. Lewis, Molecules, crystals,

and chirality, Journal of Chemical Education 74 (7) (1997) 800. doi:

10.1021/ed074p800.[31] T. E. Oliphant, A guide to NumPy, Vol. 1, Trelgol Publishing USA, 2006.[32] P. Virtanen, R. Gommers, T. E. Oliphant, M. Haberland, T. Reddy,

D. Cournapeau, E. Burovski, P. Peterson, W. Weckesser, J. Bright, S. J.van der Walt, M. Brett, J. Wilson, K. Jarrod Millman, N. Mayorov, A. R. J.Nelson, E. Jones, R. Kern, E. Larson, C. Carey, I. Polat, Y. Feng, E. W.Moore, J. Vand erPlas, D. Laxalde, J. Perktold, R. Cimrman, I. Henrik-sen, E. A. Quintero, C. R. Harris, A. M. Archibald, A. H. Ribeiro, F. Pe-dregosa, P. van Mulbregt, S. . . Contributors, SciPy 1.0–FundamentalAlgorithms for Scientific Computing in Python, arXiv e-prints (2019)arXiv:1907.10121arXiv:1907.10121.

[33] W. McKinney, Data structures for statistical computing in python, in:S. van der Walt, J. Millman (Eds.), Proceedings of the 9th Python in Sci-ence Conference, 2010, pp. 51 – 56.

[34] A. Togo, I. Tanaka, Spglib: a software library for crystal symmetrysearch (2018). arXiv:1808.01590.

[35] R. Guha, M. T. Howard, G. R. Hutchison, P. Murray-Rust, H. Rzepa,C. Steinbeck, J. K. Wegner, E. Willighagen, The blue obelisk – interop-erability in chemical informatics, J. Chem. Inf. Model. 46 (2006) 991.doi:10.1021/ci050400b.

[36] A. H. Larsen, J. J. Mortensen, J. Blomqvist, I. E. Castelli, R. Christensen,M. Dułak, J. Friis, M. N. Groves, B. Hammer, C. Hargus, E. D. Her-mes, P. C. Jennings, P. B. Jensen, J. Kermode, J. R. Kitchin, E. L. Kols-bjerg, J. Kubal, K. Kaasbjerg, S. Lysgaard, J. B. Maronsson, T. Maxson,T. Olsen, L. Pastewka, A. Peterson, C. Rostgaard, J. Schiøtz, O. Schutt,M. Strange, K. S. Thygesen, T. Vegge, L. Vilhelmsen, M. Walter, Z. Zeng,K. W. Jacobsen, The atomic simulation environment—a python libraryfor working with atoms, Journal of Physics: Condensed Matter 29 (27)(2017) 273002. doi:10.1088/1361-648x/aa680e.

[37] J. P. Perdew, K. Burke, M. Ernzerhof, Generalized gradient approxi-mation made simple, Phys. Rev. Lett. 77 (1996) 3865–3868. doi:

10.1103/PhysRevLett.77.3865.[38] G. Kresse, J. Furthmuller, Efficiency of ab-initio total energy calcu-

lations for metals and semiconductors using a plane-wave basis set,Computational Materials Science 6 (1996) 15–50. doi:10.1016/

0927-0256(96)00008-0.[39] G. Kresse, J. Furthmuller, Efficient iterative schemes for ab initio total-

energy calculations using a plane-wave basis set, Phys. Rev. B 54 (1996)11169–11186. doi:10.1103/PhysRevB.54.11169.

[40] V. L. Deringer, C. J. Pickard, G. Csanyi, Data-driven learning of total andlocal energies in elemental boron, Phys. Rev. Lett. 120 (2018) 156001.doi:10.1103/PhysRevLett.120.156001.

[41] E. V. Podryabinkin, E. V. Tikhonov, A. V. Shapeev, A. R. Oganov, Ac-celerating crystal structure prediction by machine-learning interatomicpotentials with active learning, Phys. Rev. B 99 (2019) 064114. doi:

10.1103/PhysRevB.99.064114.

9