Case Studies#

Here are some case studies of specific systems that have been explored using orgdisord.

The names of the structures refer to the CSD code/CIF file in the ./examples/ directory.

Straightforward case (ABABUB)#

This is a relatively straightforward system consisting of one disorder assembly and two disorder groups.

When we run the code with (mostly) default options:

orgdisord enumerate ABABUB.cif --prefix ababub

Parsing the CIF file#

We get the following output:

Parsing disorder in cif file: ABABUB.cif
Warning: Site 0  (O1)   in assembly A has no disorder group. This site will be considered *ordered*.
Warning: Site 1  (O2)   in assembly A has no disorder group. This site will be considered *ordered*.
Warning: Site 2  (N1)   in assembly A has no disorder group. This site will be considered *ordered*.
Warning: Site 29 (C6)   in assembly A has no disorder group. This site will be considered *ordered*.
Warning: Site 32 (H8A)  in assembly A has no disorder group. This site will be considered *ordered*.
Warning: Site 34 (C9)   in assembly A has no disorder group. This site will be considered *ordered*.
Warning: Site 38 (H10A) in assembly A has no disorder group. This site will be considered *ordered*.
Warning: Site 40 (C11)  in assembly A has no disorder group. This site will be considered *ordered*.

Disordered structure:
Disorder assembly: A
Contains the following groups:
Disorder group: 1 contains 4 symm. ops. and 12 sites:
        label:       C2, species:    C, occupancy:  0.59
        label:      H2A, species:    H, occupancy:  0.59
        label:      H2B, species:    H, occupancy:  0.59
        label:       C3, species:    C, occupancy:  0.59
        label:      H3A, species:    H, occupancy:  0.59
        label:      H3B, species:    H, occupancy:  0.59
        label:       C4, species:    C, occupancy:  0.59
        label:      H4A, species:    H, occupancy:  0.59
        label:      H4B, species:    H, occupancy:  0.59
        label:       C5, species:    C, occupancy:  0.59
        label:      H5A, species:    H, occupancy:  0.59
        label:      H5B, species:    H, occupancy:  0.59

Disorder group: 2 contains 4 symm. ops. and 12 sites:
        label:      C2', species:    C, occupancy:  0.41
        label:     H2'1, species:    H, occupancy:  0.41
        label:     H2'2, species:    H, occupancy:  0.41
        label:      C3', species:    C, occupancy:  0.41
        label:     H3'1, species:    H, occupancy:  0.41
        label:     H3'2, species:    H, occupancy:  0.41
        label:      C4', species:    C, occupancy:  0.41
        label:     H4'1, species:    H, occupancy:  0.41
        label:     H4'2, species:    H, occupancy:  0.41
        label:      C5', species:    C, occupancy:  0.41
        label:     H5'1, species:    H, occupancy:  0.41
        label:     H5'2, species:    H, occupancy:  0.41

As we can see, the code warns about certain sites that are part of disorder assembly A yet have no disorder group (they also have an occupancy of 1). The sites are therefore considered ordered by the code.

Enumerating ordered structures#

The code correctly generates a total of 16 (24 ) ordered structures and outputs the following table:

ABABUB enumerated configurations#

Unique index

Multiplicity

Configuration

Ratio

Supercell

Free Energy / kJ/mol

Enthalpy per atom / kJ/mol

Entropy per atom / kJ/mol

Volume/A^3

N atoms

Density/g/mol^3

0

1

(0, 0, 0, 0)

[4 0]

1x1x1

1031.314680509039

120

1.3219525259353389

1

1

(0, 0, 0, 1)

[3 1]

1x1x1

1031.314680509039

120

1.3219525259353389

2

1

(0, 0, 1, 0)

[3 1]

1x1x1

1031.314680509039

120

1.3219525259353389

3

1

(0, 0, 1, 1)

[2 2]

1x1x1

1031.314680509039

120

1.3219525259353389

4

1

(0, 1, 0, 0)

[3 1]

1x1x1

1031.314680509039

120

1.3219525259353389

5

1

(0, 1, 0, 1)

[2 2]

1x1x1

1031.314680509039

120

1.3219525259353389

6

1

(0, 1, 1, 0)

[2 2]

1x1x1

1031.314680509039

120

1.3219525259353389

7

1

(0, 1, 1, 1)

[1 3]

1x1x1

1031.314680509039

120

1.3219525259353389

8

1

(1, 0, 0, 0)

[3 1]

1x1x1

1031.314680509039

120

1.3219525259353389

9

1

(1, 0, 0, 1)

[2 2]

1x1x1

1031.314680509039

120

1.3219525259353389

10

1

(1, 0, 1, 0)

[2 2]

1x1x1

1031.314680509039

120

1.3219525259353389

11

1

(1, 0, 1, 1)

[1 3]

1x1x1

1031.314680509039

120

1.3219525259353389

12

1

(1, 1, 0, 0)

[2 2]

1x1x1

1031.314680509039

120

1.3219525259353389

13

1

(1, 1, 0, 1)

[1 3]

1x1x1

1031.314680509039

120

1.3219525259353389

14

1

(1, 1, 1, 0)

[1 3]

1x1x1

1031.314680509039

120

1.3219525259353389

15

1

(1, 1, 1, 1)

[0 4]

1x1x1

1031.314680509039

120

1.3219525259353389

Where columns for the (free) energies have been added in anticipation of next steps. Once these energies have been and added to the table, the code can then be used to analyse the results. See the command line interface documentation for the analysis options.

The code will also make a directory (<prefix>-results) in which the structure files are written.

Tip

By default the code will output the structures in the extended .xyz format. This has the advantage of being able to store artibrary additional information site-specific and structure-specific information. For example, tags specfying the disorder group/assembly and the original CIF labels are preserved.

For CIF and CASTEP .cell files, the code will also preserve the CIF-labels, but these may be harder to post-process using ASE should you wish to do so.

You can specify the output format using the -f option. See the command line interface documentation for more details.

Merging equivalent structures#

If we instead re-run the code with the -m flag, the code will merge symmetry-equivalent structures:

Enumerating ordered configurations.
Generating 16 out of the 16 possible configurations in the (1, 1, 1) supercell:
100%|██████████████████████████████| 16/16 [00:00<00:00, 3912.83it/s]
Merging structures...
Checking symmetry-equivalence: 100%|█| 16/16 [00:00<00:00, 1967.25it/
Merging took     0.01 s and found 7 groups
Spacegroup: P2_1/c (14)          multiplicity: 1
Spacegroup: P1 (1)               multiplicity: 4
Spacegroup: P2_1 (4)             multiplicity: 2
Spacegroup: P-1 (2)              multiplicity: 2
Spacegroup: Pc (7)               multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 4
Spacegroup: P2_1/c (14)          multiplicity: 1

and the corresponding table is:

ABABUB enumerated configurations (merged)#

Unique index

Supercell

Ratio

Configuration

Multiplicity

Free Energy / kJ/mol

Enthalpy per atom / kJ/mol

Entropy per atom / kJ/mol

Volume/A^3

N atoms

Density/g/mol^3

Spacegroup

Group indices

0

1x1x1

[4 0]

(0, 0, 0, 0)

1

1031.314680509039

120.0

1.3219525259353389

P2_1/c (14)

[0]

1

1x1x1

[3 1]

(0, 0, 0, 1)

4

1031.314680509039

120.0

1.3219525259353389

P1 (1)

[1, 2, 4, 8]

2

1x1x1

[2 2]

(0, 0, 1, 1)

2

1031.314680509039

120.0

1.3219525259353389

P2_1 (4)

[3, 12]

3

1x1x1

[2 2]

(0, 1, 0, 1)

2

1031.314680509039

120.0

1.3219525259353389

P-1 (2)

[5, 10]

4

1x1x1

[2 2]

(0, 1, 1, 0)

2

1031.314680509039

120.0

1.3219525259353389

Pc (7)

[6, 9]

5

1x1x1

[1 3]

(0, 1, 1, 1)

4

1031.314680509039

120.0

1.3219525259353389

P1 (1)

[7, 11, 13, 14]

6

1x1x1

[0 4]

(1, 1, 1, 1)

1

1031.314680509039

120.0

1.3219525259353389

P2_1/c (14)

[15]

Supercells and random structures#

We would typically want to then generate ordered structures for a larger supercell. Because of the combinatorial explosion, caution is advised when doing this and a conservative number of maximum structures is generated: 512 by default. To generate more than this, the -N flag can be used. For example, to generate 1024 structures:

orgdisord enumerate ABABUB.cif --prefix ababub -N 1024 --supercell 2 2 1

This will enumerate, in order, all possible configurations in a 2x2x1 supercell up to a maximum of 1024 structures.

Sometimes, however, we may want to generate a sample of random configurations for a given supercell size. This can be done with the -r flag:

orgdisord enumerate ABABUB.cif --prefix ababub -r -N 1024 --supercell 2 2 1

Tip

To visualise the generated structures, you can add the --view flag. This will open the structures in ASE’s GUI viewer.

The ordered sites are tagged with 0 and the disordered sites are tagged according to the disorder group/assembly. It’s useful to color-by tag to see the disorder groups/assembly in the GUI viewer. You can do this by clicking on View->Colors button and selecting By tag. You can then choose the range of tags you’re interested in and also change the color map (cmap).

Constrained ratios of disorder components#

Note

This feature is currently limited to simple cases where only 1 disorder assembly and 2 disorder groups are present.

The code can also be used to generate structures with a specified ratio of disorder components. If the --fix_ratio flag is present, the code will only generate structures with a fixed ratio of disorder components. By default this ratio comes from the occupancies specified in the CIF file, but they can be overridden using the --ratios flag. For example, to generate only structures with 0.75 disorder group 1 and 0.25 disorder group 2:

orgdisord enumerate ABABUB.cif --prefix ababub --fix_ratio --ratio 0.75

Tip

The --ratio-tol flag is useful when the occupancies possible for a given supercell size don’t exactly match those based on the experimental occupancies. For example, if the occupancies are 0.76 and 0.24, the code can accept generated structures with a ratio of 0.75 and 0.25 (if within the tolerance). This is because the code will generate structures with occupancies that are within the tolerance of the specified ratio. The default tolerance is 0.01, but this can be changed using the --ratio-tol flag.

Another straightforward case (AXURIX)#

This is another relatively straightforward system consisting of one disorder assembly and two disorder groups. The main difference is that here Z=8 and so the code generates 256 (28 ) ordered structures. This takes significantly longer than the previous example, but the code still completes in a reasonable time. The main additional cost is in reloading this configurations as molecular crystals (i.e. making sure molecular units are connected together in a reasonable way.). You can disable this check using the --not_molecular_crystal flag, though the results of this are not well-tested!

We can run the code and merge the structures as before:

orgdisord enumerate AXURIX.cif --prefix axurix_merged -m

The CIF file is parsed as:

Parsing disorder in cif file: AXURIX.cif
Disordered structure:
Disorder assembly: A
Contains the following groups:
Disorder group: 1 contains 8 symm. ops., a group occupancy of 0.75 and 12 sites:
        label:     C28A, species:    C, occupancy:  0.75
        label:     H28A, species:    H, occupancy:  0.75
        label:     H28B, species:    H, occupancy:  0.75
        label:     H28C, species:    H, occupancy:  0.75
        label:     C29A, species:    C, occupancy:  0.75
        label:     H29A, species:    H, occupancy:  0.75
        label:     H29B, species:    H, occupancy:  0.75
        label:     H29C, species:    H, occupancy:  0.75
        label:     C30A, species:    C, occupancy:  0.75
        label:     H30A, species:    H, occupancy:  0.75
        label:     H30B, species:    H, occupancy:  0.75
        label:     H30C, species:    H, occupancy:  0.75

Disorder group: 2 contains 8 symm. ops., a group occupancy of 0.25 and 12 sites:
        label:     C28B, species:    C, occupancy:  0.25
        label:     H28D, species:    H, occupancy:  0.25
        label:     H28E, species:    H, occupancy:  0.25
        label:     H28F, species:    H, occupancy:  0.25
        label:     C29B, species:    C, occupancy:  0.25
        label:     H29D, species:    H, occupancy:  0.25
        label:     H29E, species:    H, occupancy:  0.25
        label:     H29F, species:    H, occupancy:  0.25
        label:     C30B, species:    C, occupancy:  0.25
        label:     H30D, species:    H, occupancy:  0.25
        label:     H30E, species:    H, occupancy:  0.25
        label:     H30F, species:    H, occupancy:  0.25

The 256 structures are generated and merged as follows:

Enumerating ordered configurations.
Generating 256 out of the 256 possible configurations in the (1, 1, 1) supercell:
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████| 256/256 [00:00<00:00, 2240.98it/s]
Merging structures...
Checking symmetry-equivalence: 100%|█████████████████████████████████████████████████████████████████████████████| 256/256 [00:03<00:00, 78.84it/s]
Merging took     3.27 s and found 46 groups
Spacegroup: Pbca (61)            multiplicity: 1
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P2_1 (4)             multiplicity: 4
Spacegroup: P2_1 (4)             multiplicity: 4
Spacegroup: P2_1 (4)             multiplicity: 4
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P2_12_12_1 (19)      multiplicity: 2
Spacegroup: P-1 (2)              multiplicity: 4
Spacegroup: Pc (7)               multiplicity: 4
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: Pc (7)               multiplicity: 4
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: Pc (7)               multiplicity: 4
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P2_1/c (14)          multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: Pca2_1 (29)          multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P2_1 (4)             multiplicity: 4
Spacegroup: P2_1/c (14)          multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: Pca2_1 (29)          multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P2_1 (4)             multiplicity: 4
Spacegroup: P2_1/c (14)          multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: Pca2_1 (29)          multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: P2_1 (4)             multiplicity: 4
Spacegroup: P-1 (2)              multiplicity: 4
Spacegroup: Pc (7)               multiplicity: 4
Spacegroup: Pc (7)               multiplicity: 4
Spacegroup: Pc (7)               multiplicity: 4
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: Pbca (61)            multiplicity: 1

These timings don’t include the (in this case significant) time to ‘reload as molecular crystal’. On my machine it took about 1 minute!

Z’ < 1 and multiple disorder groups (EROHEA)#

This system contains a caffeine molecule that is disordered at a special symmetry site. i.e. it is “disordered by symmetry” where the structure is described by a small unit cell in which the caffeine is disordered over a symmetry axis. Unpicking this into two separate orientations is a difficult challenge for the current version of orgdisord. It currently requires some manual intervention on the CIF file as described below.

This system has one disorder assembly (A) with two groups (“-1” and “-2”). The “-” sign in the group label indicates that these sites are at special symmetry positions. Indeed, although there are 8 symmetry operations, Z = 4. To generate all of the ordered structures, the code must therefore apply a subset of symmetry operations to each group, with the configuration (e.g. (0,0,1,0)) indicating which subgroup of symmetry operations to apply.

Note that the original EROHEA CIF file had to be modified by manually moving the O10 site to another symmetry equivalent position in the CIF file.

-O10 O 0.3754(5) 0.4007(5) 0.6805(5) 0.0223(11)
+O10 O 0.62460(5) 0.4007(5) 0.81950(5) 0.0223(11)

In addition, the C12, H12A, H12B and H12C sites were manually moved to disorder group -2.

In the future, we might be able to deal with original CIF file without these manual interventions.

When we run the code with (mostly) default options:

orgdisord enumerate EROHEA_modified.cif --prefix erohea

We get the following output:

Parsing the CIF file#

parse_cif output for EROHEA#
Parsing disorder in cif file: EROHEA_modified.cif
Warning: Site 21 (C9) in assembly A has no disorder group. This site will be considered *ordered*.
Double check the CIF file.
Disordered structure:
Disorder assembly: A
Contains the following groups:
Disorder group: -2 has special disorder symmetry and contains [4, 4] symm. ops. and 5 sites:
        label:      O10, species:    O, occupancy:  0.50
        label:      C12, species:    C, occupancy:  0.50
        label:     H12A, species:    H, occupancy:  0.50
        label:     H12B, species:    H, occupancy:  0.50
        label:     H12C, species:    H, occupancy:  0.50

Disorder group: -1 has special disorder symmetry and contains [4, 4] symm. ops. and 4 sites:
        label:       N2, species:    N, occupancy:  0.50
        label:       N3, species:    N, occupancy:  0.50
        label:      C11, species:    C, occupancy:  0.50
        label:      H11, species:    H, occupancy:  0.50

Enumerating ordered structures#

The code correctly generates a total of 16 (24 ) ordered structures and outputs the following table:

EROHEA enumerated configurations#

Unique index

Supercell

Ratio

Configuration

Multiplicity

Free Energy / kJ/mol

Enthalpy per atom / kJ/mol

Entropy per atom / kJ/mol

Volume/A^3

N atoms

Density/g/mol^3

Spacegroup

Group indices

0

1x1x1

[4 0]

(0, 0, 0, 0)

2

2654.1751062921485

288.0

1.5377303803202587

P-1 (2)

[0, 15]

1

1x1x1

[3 1]

(0, 0, 0, 1)

8

2654.1751062921485

288.0

1.5377303803202587

P1 (1)

[1, 2, 4, 7, 8, 11, 13, 14]

2

1x1x1

[2 2]

(0, 0, 1, 1)

2

2654.1751062921485

288.0

1.5377303803202587

Cc (9)

[3, 12]

3

1x1x1

[2 2]

(0, 1, 0, 1)

2

2654.1751062921485

288.0

1.5377303803202587

P2_1/c (14)

[5, 10]

4

1x1x1

[2 2]

(0, 1, 1, 0)

2

2654.1751062921485

288.0

1.5377303803202587

P2_1/c (14)

[6, 9]

Merging equivalent structures#

If we instead re-run the code with the -m flag, the code will merge symmetry-equivalent structures:

Enumerating ordered configurations.
Generating 16 out of the 16 possible configurations in the (1, 1, 1) supercell:
100%|██████████████████████████████| 16/16 [00:00<00:00, 3958.99it/s]
Merging structures...
Checking symmetry-equivalence: 100%|█| 16/16 [00:00<00:00, 2059.06it/
Merging took     0.01 s and found 5 groups
Spacegroup: P-1 (2)              multiplicity: 2
Spacegroup: P1 (1)               multiplicity: 8
Spacegroup: Cc (9)               multiplicity: 2
Spacegroup: P2_1/c (14)          multiplicity: 2
Spacegroup: P2_1/c (14)          multiplicity: 2

and the corresponding table is:

EROHEA enumerated configurations (merged)#

Unique index

Multiplicity

Free Energy / kJ/mol

Enthalpy per atom / kJ/mol

Entropy per atom / kJ/mol

Volume/A^3

N atoms

Density/g/mol^3

Spacegroup

Group indices

0

2

2.6541751062921485e+03

288.0

1.5377303803202587

P-1 (2)

[0, 15]

1

8

2654.1751062921485

288.0

1.5377303803202587

P1 (1)

[1, 2, 4, 7, 8, 11, 13, 14]

2

2

2654.1751062921485

288.0

1.5377303803202587

Cc (9)

[3, 12]

3

2

2654.1751062921485

288.0

1.5377303803202587

P2_1/c (14)

[5, 10]

4

2

2654.1751062921485

288.0

1.5377303803202587

P2_1/c (14)

[6, 9]

Z’< 1 and only one disorder group (DASRAU)#

This is a Ruddlesden-Popper phase with a disordered butylammonium cation. The cation is disordered at a special symmetry position such that each of the 32 symmetry operations generates another configuration. Assuming only one cation per unit cell, the code will generate, by default, 32 ordered structures.

When we run the code with (mostly) default options:

orgdisord enumerate DASRAU.cif --prefix dasrau

We get the following output:

parse_cif output for DASRAU#
Parsing disorder in cif file: DASRAU.cif
Disordered structure:
Disorder assembly: A
Contains the following groups:
Disorder group: -1 has special disorder symmetry and contains [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1] symm. ops. and a group occupancy of 0.125 and 17 sites:
        label:       N1, species:    N, occupancy:  0.12
        label:      H1A, species:    H, occupancy:  0.12
        label:      H1B, species:    H, occupancy:  0.12
        label:      H1C, species:    H, occupancy:  0.12
        label:       C1, species:    C, occupancy:  0.12
        label:      H1D, species:    H, occupancy:  0.12
        label:      H1E, species:    H, occupancy:  0.12
        label:       C2, species:    C, occupancy:  0.12
        label:      H2A, species:    H, occupancy:  0.12
        label:      H2B, species:    H, occupancy:  0.12
        label:       C3, species:    C, occupancy:  0.12
        label:      H3A, species:    H, occupancy:  0.12
        label:      H3B, species:    H, occupancy:  0.12
        label:       C4, species:    C, occupancy:  0.12
        label:      H4A, species:    H, occupancy:  0.12
        label:      H4B, species:    H, occupancy:  0.12
        label:      H4C, species:    H, occupancy:  0.12

The code correctly generates a total of 32 (321 ) ordered structures and outputs the following table: DASRAU results table

Warning

For systems with special symmetry groups (i.e. with disorder group labels starting with “-“), The code may not correctly partition the symmetry operations into subgroups. So please check your output carefully!

Another serious limitation in these cases is that generated supercells may have overlapping sites.

We’re working to make the code more robust for these cases.

Specifying the disorder components using two ordered structures#

Rather than working with CIF files tagged with disorder information, it’s sometimes easier to work with two ordered structures, one for the major disorder component and one for the minor. The code can use the difference between the two structures to determine the disorder structure and enumerate based on that.

This functionality is currently limited to the case of one disorder assembly and two disorder groups.

Taking the previous ABABUB example, I manually split the structure into two P1 ordered structures, one for the major disorder component and one for the minor. You can download these here:

Note that you can provide the P1 crystal structures in any format that ASE can read; here I’ve used the extended .xyz format.

If you pass two files to the command-line-interface, it will assume these are the two disorder components

orgdisord enumerate ABABUB_maj.xyz ABABUB_min.xyz --prefix ababub_from_maj_min -m

Multiple assemblies, each with same number of groups (HAXPIH)#

Correlated assemblies#

This structure (Z=6) has three disorder assemblies, each with two disorder groups. If we consider these assemblies to be independent, we can generate 26 x 26 x 26 = 264 144 ordered structures. This would crash the code and is outside our scope anyway. However, there may be cases in which we might want to consider the assemblies as correlated, i.e. we pick from the same disorder group index in each assembly.

You can do this by specifying the -c flag.

orgdisord enumerate HAXPIH.cif --prefix haxpih -c

Parsing the CIF file#

The code correctly parses the disorder groups and outputs the following:

Parsing disorder in cif file: HAXPIH.cif
Disordered structure:
Disorder assembly: 2
Contains the following groups:
Disorder group: 1 contains 6 symm. ops. and 15 sites:
        label:     C230, species:    C, occupancy:  0.26
        label:     C240, species:    C, occupancy:  0.26
        label:     C250, species:    C, occupancy:  0.26
        label:     C260, species:    C, occupancy:  0.26
        label:     H221, species:    H, occupancy:  0.26
        label:     H222, species:    H, occupancy:  0.26
        label:    H2301, species:    H, occupancy:  0.26
        label:    H2302, species:    H, occupancy:  0.26
        label:    H2401, species:    H, occupancy:  0.26
        label:    H2501, species:    H, occupancy:  0.26
        label:    H2502, species:    H, occupancy:  0.26
        label:    H2503, species:    H, occupancy:  0.26
        label:    H2601, species:    H, occupancy:  0.26
        label:    H2602, species:    H, occupancy:  0.26
        label:    H2603, species:    H, occupancy:  0.26

Disorder group: 2 contains 6 symm. ops. and 15 sites:
        label:     C231, species:    C, occupancy:  0.74
        label:     C241, species:    C, occupancy:  0.74
        label:     C251, species:    C, occupancy:  0.74
        label:     C261, species:    C, occupancy:  0.74
        label:     H223, species:    H, occupancy:  0.74
        label:     H224, species:    H, occupancy:  0.74
        label:    H2311, species:    H, occupancy:  0.74
        label:    H2312, species:    H, occupancy:  0.74
        label:    H2411, species:    H, occupancy:  0.74
        label:    H2511, species:    H, occupancy:  0.74
        label:    H2512, species:    H, occupancy:  0.74
        label:    H2513, species:    H, occupancy:  0.74
        label:    H2611, species:    H, occupancy:  0.74
        label:    H2612, species:    H, occupancy:  0.74
        label:    H2613, species:    H, occupancy:  0.74


Disorder assembly: 3
Contains the following groups:
Disorder group: 1 contains 6 symm. ops. and 12 sites:
        label:     C340, species:    C, occupancy:  0.24
        label:     C350, species:    C, occupancy:  0.24
        label:     C360, species:    C, occupancy:  0.24
        label:     H331, species:    H, occupancy:  0.24
        label:     H332, species:    H, occupancy:  0.24
        label:    H3401, species:    H, occupancy:  0.24
        label:    H3501, species:    H, occupancy:  0.24
        label:    H3502, species:    H, occupancy:  0.24
        label:    H3503, species:    H, occupancy:  0.24
        label:    H3601, species:    H, occupancy:  0.24
        label:    H3602, species:    H, occupancy:  0.24
        label:    H3603, species:    H, occupancy:  0.24

Disorder group: 2 contains 6 symm. ops. and 12 sites:
        label:     C341, species:    C, occupancy:  0.76
        label:     C351, species:    C, occupancy:  0.76
        label:     C361, species:    C, occupancy:  0.76
        label:     H333, species:    H, occupancy:  0.76
        label:     H334, species:    H, occupancy:  0.76
        label:    H3411, species:    H, occupancy:  0.76
        label:    H3511, species:    H, occupancy:  0.76
        label:    H3512, species:    H, occupancy:  0.76
        label:    H3513, species:    H, occupancy:  0.76
        label:    H3611, species:    H, occupancy:  0.76
        label:    H3612, species:    H, occupancy:  0.76
        label:    H3613, species:    H, occupancy:  0.76


Disorder assembly: 4
Contains the following groups:
Disorder group: 1 contains 6 symm. ops. and 18 sites:
        label:     C421, species:    C, occupancy:  0.46
        label:     C431, species:    C, occupancy:  0.46
        label:     C441, species:    C, occupancy:  0.46
        label:     C451, species:    C, occupancy:  0.46
        label:     C461, species:    C, occupancy:  0.46
        label:     H411, species:    H, occupancy:  0.46
        label:     H412, species:    H, occupancy:  0.46
        label:    H4211, species:    H, occupancy:  0.46
        label:    H4212, species:    H, occupancy:  0.46
        label:    H4311, species:    H, occupancy:  0.46
        label:    H4312, species:    H, occupancy:  0.46
        label:    H4411, species:    H, occupancy:  0.46
        label:    H4511, species:    H, occupancy:  0.46
        label:    H4512, species:    H, occupancy:  0.46
        label:    H4513, species:    H, occupancy:  0.46
        label:    H4611, species:    H, occupancy:  0.46
        label:    H4612, species:    H, occupancy:  0.46
        label:    H4613, species:    H, occupancy:  0.46

Disorder group: 2 contains 6 symm. ops. and 18 sites:
        label:     C420, species:    C, occupancy:  0.54
        label:     C430, species:    C, occupancy:  0.54
        label:     C440, species:    C, occupancy:  0.54
        label:     C450, species:    C, occupancy:  0.54
        label:     C460, species:    C, occupancy:  0.54
        label:     H413, species:    H, occupancy:  0.54
        label:     H414, species:    H, occupancy:  0.54
        label:    H4201, species:    H, occupancy:  0.54
        label:    H4202, species:    H, occupancy:  0.54
        label:    H4301, species:    H, occupancy:  0.54
        label:    H4302, species:    H, occupancy:  0.54
        label:    H4401, species:    H, occupancy:  0.54
        label:    H4501, species:    H, occupancy:  0.54
        label:    H4502, species:    H, occupancy:  0.54
        label:    H4503, species:    H, occupancy:  0.54
        label:    H4601, species:    H, occupancy:  0.54
        label:    H4602, species:    H, occupancy:  0.54
        label:    H4603, species:    H, occupancy:  0.54

The code will generate 26 = 64 ordered structures and outputs the following table: HAXPIH results table

Merging the equivalent structures#

Running the code again with the -m flag:

orgdisord enumerate HAXPIH.cif --prefix haxpih_merged -c -m

We get the following table: HAXPIH results table and this information printed to the terminal:

Generating 64 out of the 64 possible configurations in the (1, 1, 1) supercell:
100%|██████████████████████████████| 64/64 [00:00<00:00, 3721.86it/s]
Merging structures...
Checking symmetry-equivalence: 100%|█| 64/64 [00:03<00:00, 18.17it/s]
Merging took     3.53 s and found 16 groups
Spacegroup: P3_221 (154)         multiplicity: 1
Spacegroup: P1 (1)               multiplicity: 6
Spacegroup: P1 (1)               multiplicity: 6
Spacegroup: P3_2 (145)           multiplicity: 2
Spacegroup: C2 (5)               multiplicity: 3
Spacegroup: C2 (5)               multiplicity: 3
Spacegroup: P1 (1)               multiplicity: 6
Spacegroup: C2 (5)               multiplicity: 3
Spacegroup: P1 (1)               multiplicity: 6
Spacegroup: P1 (1)               multiplicity: 6
Spacegroup: P1 (1)               multiplicity: 6
Spacegroup: C2 (5)               multiplicity: 3
Spacegroup: C2 (5)               multiplicity: 3
Spacegroup: C2 (5)               multiplicity: 3
Spacegroup: P1 (1)               multiplicity: 6
Spacegroup: P3_221 (154)         multiplicity: 1

We can see that the 64 ordered configurations have been merged into 16 groups of equivalent structures. The first group has a spacegroup of P3_221 (154) and a multiplicity of 1, the second group has a spacegroup of P1 (1) and a multiplicity of 6, and so on.

Manually/programmatically specifying disorder#

You can manually create a DisorderedStructure object and pass that to the enumerator to generate the ordered configurations.

As a basic example, let’s put a thiophene (C4H4S) molecule in a cubic cell with no symmetry. We can then generate several disorder groups that each contains a different configuration of the molecule – in this case let’s just rotate the molecule by 360/5 degrees to move the S atom around the ring.

Using ASE we can do this as follows:

# ASE already knows about some molecules :)
from ase.build import molecule
from orgdisord.utils import get_new_labels

# Spacegroup 1 == P1
sg_number = 1
# Unit cell. If 3 numbers are given,
# they are interpreted as the lengths of the unit cell vectors.
# If a 3x3 list or array is given,
# they are interpreted as the three vectors.
cell = [6.5, 6.5, 6.5]
# Create the main atoms object
atoms = molecule('C4H4S', cell = cell, pbc = True)
# Good to always have useful labels to help keep track of things
atoms.set_array('labels', np.array(get_new_labels(atoms)))

# where is the centre of ring:
ring_c = atoms.positions[:5].mean(axis=0)

# place the ring in the centre of the cell
atoms.translate(np.array(cell)*0.5 - ring_c)

# Now we generate 5 structures that will comprise our 5 disorder groups
# in assembly A, by rotating the ring around.
images = [atoms]
for i in range(1,5):
    atoms_temp = atoms.copy()
    # rotate the ring by 360/5 degrees
    atoms_temp.rotate(i*360/5.0, 'x', center='COU')
    images.append(atoms_temp)

Now we can create a DisorderedStructure object to later be passed to the enumerator:

from orgdisord.disordered_structure import DisorderAssembly,
                                                DisorderGroup,
                                                DisorderedStructure
from orgdisord.enumerate import OrderedfromDisordered

# symmetry operations -- in this case just the identity
sg = Spacegroup(sg_number)
symops = sg.get_symop()

# For the ordered part, we just have an empty Atoms object.
ordered_atoms = Atoms(cell=cell)

# make list of DisorderGroup objects to pass into DisorderAssembly
disorder_groups = []
for i, rot in enumerate(images):
    disorder_group = DisorderGroup(
        label = str(i+1),
        atoms = rot,
        symmetry_operations=symops,
        tag = i+1,
        occupancy = 1/len(images),
        )
    disorder_groups.append(disorder_group)

# create disorder assembly
da = DisorderAssembly(
    label = 'A',
    disorder_groups = disorder_groups,
    tag = 0,
    )

# create disordered structure
ds = DisorderedStructure(
    ordered_atoms= ordered_atoms,
    Z = 1,
    spacegroup =  sg,
    disorder_assemblies = [da],
    molecular_crystal=True,
    )

# now we can pass this to the enumerator
od = OrderedfromDisordered(ds)

# Let's generate 20 random configurations in a 1x5x5 supercell:
supercell = [1, 5, 5]
images = od.get_supercell_configs(
                supercell = supercell,
                maxiters = 20,
                exclude_ordered = False,
                random_configs=True)

# Now we could write them to disk
# in lots of different formats. E.g.:
for i, image in enumerate(images):
    image.write(f'C4H4S_example_{i+1:02d}.cif')
    #image.write(f'C4H4S_example_{i+1:02d}.cell')
    #image.write(f'C4H4S_example_{i+1:02d}.xyz')

# Or we could use the ASE GUI to view them:
from ase.visualize import view
view(images)

I used the ASE POVRAY writer to create nice images of each configuration in a 1x6x3 supercell and stitched them into a gif using ImageMagick:

_images/C4H4S_6x3.gif