COSMOchloRe (Continuous Shape/Symmetry Measurements & Octahedral distortion, in Rust) is a fast, pure-Rust toolkit for quantifying how closely a molecular structure (or any set of 3-dimensional points) matches an idealized reference geometry, through three complementary analyses: Continuous Shape Measures (CShM), Continuous Symmetry Operation Measures (CSoM) and OctaDist-style octahedral distortion parameters.
It is a from-scratch command line interface (CLI) tool that reimplements the shape-measure engine found in cosymlib and SHAPE1 2.1 in Rust, alongside an original implementation of continuous symmetry operation measures inspired by the works of T. J. Sørensen et al.3 and the octahedral distortion parameters popularized by OctaDist4. Cosmochlore accurately reproduces SHAPE's 2.1 results using a pruned branch-and-bound algorithm for significantly faster performance on larger coordination numbers.
Cosmochlore's error handling will always tell the user if something went wrong at run-time, the program will never silently crash or give you a number without you knowing something went wrong.
The name of the tool comes from the mineral Kosmochlor, a rare chromium clinopyroxene found in iron meteorites and as an accessory mineral to various other chromium-containing pyroxenes.
Cosmochlore includes three measures covering a different ways of measuring how distorted a structure is:
cshm— computes the Continuous Shape Measure (CShM) between a structure and one or more idealized reference shapes. A value ofCShM = 0means a perfect match; larger values indicate greater distortion from the ideal geometry. 90 built-in reference polyhedra are included (see Reference Polyhedra), and user-defined ones can be supplied via YAML.csom— computes the Continuous Symmetry Operation Measure (CSoM): how far a structure is from possessing a given point group's symmetry operations, searching over all orientations for the best fit (see Thecsomalgorithm). A value ofCSoM = 0means that the symmetry of a given point group is perfectly conserved in the structure.odis— Octahedral Distortion analysis for six-coordinate centres:OctaDist-style bond-length and angular distortion parameters (mean M–X distance,zeta,delta,sigma,tau,mu), combined with a CShM/CSoM breakdown against the most common octahedral distortions.
- Include Cosmochlore into SymmetryMeasurements.
- Automatic point-group detection for
csom(currently a target point group must always be given via--pg). - Face-twisting (theta) and volume octahedral distortion parameters for
odis.
Build from source:
git clone https://github.com/Yluro/cosmochlore
cd cosmochlore
cargo build --releasecargo will compile the source code taking into account your system's architecture. The easiest way to get cargo is to install the latest stable release of Rust using rustup.
The compiled binary will be at target/release/cosmochlore. By cloning the current main branch of the repository you will get access to experimental versions of Cosmochlore.
Precompiled binaries for the most common operating systems are available in this repository's releases.
Note: It is strongly recommended to place the cosmochlore executable in the systems PATH.
Cosmochlore is a CLI tool. It can be called by the general syntax:
cosmochlore <COMMAND> <NAME> [OPTIONS]| Command | Description |
|---|---|
cshm |
Continuous shape measures calculation. |
csom |
Continuous symmetry operation measures calculation. |
odis |
Octahedral distortion analysis. |
help |
Print the help or the help of the given subcommand(s). |
| Flag | Description |
|---|---|
<NAME> |
Required. Path to the input .xyz file containing the structure to analyze. |
| Flag | Value | Description |
|---|---|---|
-n --nc |
None | Indicates the structure does not include an explicit central atom (i.e. only ligand/vertex coordinates are given). If a structure contains a central atom, Cosmochlore assumes it is in the first position of the .xyz file. |
-s --sh |
<SHAPES>... |
Restrict the comparison to specific built-in reference shapes by index, for the detected vertex count. If omitted, all applicable built-in shapes are used. Specified indices should be separated by whitespace. |
-r --ref |
<USER_SHAPES>... |
Path to the reference.yaml files that contain user-defined shapes to include in the CShM calculation. Specified files should be separated by whitespace. |
-t --table |
None | Write a name_cshm_table.csv file containing the output of the calculation. |
-i --ideal |
None | Write a name_ideal.xyz file containing the reconstructed idealised structures for all the selected reference shapes. |
Oh..., I lost my crab here. 🦀 Thanks for finding it!
| Flag | Value | Description |
|---|---|---|
-n --nc |
None | Treat the structure as non-centered (see cshm's -n). |
-p --pg |
<POINT_GROUPS>... |
Currently required. Point groups to measure the structure against, in Schoenflies notation, separated by whitespace (e.g. -p Oh D4h C2v) — see Supported point groups below for the full list. |
-c --center |
auto | first | centroid | manual |
Centering mode. auto (default) centers on the first atom if the structure has an explicit centre, or on the centroid otherwise. |
-u --vector |
<X> <Y> <Z> |
Centering vector, required when --center manual is used. |
-f --full |
None | Write a name_<PG>_details.csv file per analysed point group, listing every individual symmetry operation's matrix and deviation. |
-t --table |
None | Write a name_csom_table.csv summary file (point group, deviation, refined rotation matrix). |
-s --samples |
<N> |
Number of Fibonacci-sphere samples used to seed the symmetry-axis search. Defaults to 20. It is recomended not to change this parameter. |
-i --iterations |
<N> |
Maximum number of iterations used to refine the symmetry axis. Defaults to 200. |
| Flag | Value | Description |
|---|---|---|
-f --full |
None | Full analysis of the octahedron, including CShM (against OC-6/TPR-6) and CSoM (against the common octahedral distortion point groups) values. |
-t --table |
None | Write the output table to a .csv file. |
Noteodis requires a centered structure with exactly one central atom and six ligands (7 atoms total in the .xyz file).
Given the following FeHS.xyz file:
7
High-spin iron(ii) complex
Fe6 4.92991 10.3899 12.9237
N004 6.20468 10.6922 14.7747
N006 5.00034 8.51382 13.9503
N008 6.80263 10.0749 11.7725
N00B 5.47238 12.2809 12.1201
N00C 3.30536 11.3249 13.862
N00D 3.74731 9.47729 11.4687
Running:
cosmochlore cshm FeHS.xyz --ref ebcT-6.yaml -t -iWill output:
============================================================
Symbol Shape Symmetry CShM
------------------------------------------------------------
HP-6 Hexagon D6h 33.215
PPY-6 Pentagonal pyramid C5v 23.015
OC-6 Octahedron Oh 2.109
TPR-6 Trigonal prism D3h 11.027
JPPY-6 Johnson pentagonal pyramid J2 C5v 27.034
ebcT-6 Edge-bicapped tetrahedron D2d 14.335
------------------------------------------------------------
Writing output table to .\tests\FeHS_cshm_table.csv...
Writing idealised polyhedra coordinates to table to .\tests\FeHS_ideal.xyz...
Program finished in 18.5727ms
The output of the calculation is saved in the file FeHS_cshm_table.csv by passing the -t/--table flag.
Symbol,Name,Symmetry,CShM
HP-6,Hexagon,D6h,33.215
PPY-6,Pentagonal pyramid,C5v,23.015
OC-6,Octahedron,Oh,2.109
TPR-6,Trigonal prism,D3h,11.027
JPPY-6,Johnson pentagonal pyramid J2,C5v,27.034
ebcT-6,Edge-bicapped tetrahedron,D2d,14.335The FeHS_ideal.xyz file was produced by calling the -i/--ideal flag. The coordinates of the ideal octahedron placed in the correct position of the structure can be extracted from it.
Note that ebcT-6 is a non-standard reference shape included by passing the --ref flag. See more below.
Running the same FeHS.xyz structure against the ideal octahedron symmetry Oh and the dihedral point group D4h:
cosmochlore csom FeHS.xyz -p Oh D4h -tWill output:
Input file: FeHS.xyz
========================
Point group Deviation
------------------------
Oh 5.380
D4h 5.611
------------------------
Writing output table to FeHS_csom_table.csv...
Program finished in 3.031317s
Passing the -t/--table flag writes the point group / deviation / rotation matrix summary to FeHS_csom_table.csv. Passing -f/--full additionally writes, for every point group requested, a FeHS_<PG>_details.csv file breaking the deviation down by individual symmetry operation (e.g. FeHS_Oh_details.csv lists every one of Oh's 48 operations separately).
cosmochlore odis FeHS.xyz -t --fullWill output:
Input file: FeHS.xyz
==================================
Octahedral distortion parameters
----------------------------------
Mean d(M-X) 2.1623 Ang
Zeta 0.3622 Ang
Delta 0.001007
Sigma 82.29 deg
----------------------------------
Tau 54.42 deg
Mu 0.17 Ang
==================================
Input file: FeHS.xyz
============================================
Symbol Shape Symmetry CShM
--------------------------------------------
OC-6 Octahedron Oh 2.089
TPR-6 Trigonal prism D3h 11.079
--------------------------------------------
Writing output table to FeHS_cshm_table.csv...
Input file: FeHS.xyz
========================
Point group Deviation
------------------------
Oh 5.380
D4h 5.611
D3d 5.691
D2h 5.948
C4v 4.947
C3v 5.335
C2v 2.420
------------------------
Program finished in 5.1892944s
Passing the -t/--table flag writes the distortion parameters to a <NAME>_odis_table.csv. Passing the -f/--full flag computes the CShM against an octahedron, and trigonal prism
The geometries of 90 reference polyhedra are internally defined in Cosmochlore. This list was integrally derived from the SHAPE 2.1 list of reference polyhedra and has been discussed in numerous articles by Alemany, Llunell, Alvarez, Avnir, Cirera et at.2
| Vertices | Index | Label | Shape | Symmetry |
|---|---|---|---|---|
| 2 | 0 | L-2 | Linear | D∞h |
| 1 | vT-2 | Divacant tetrahedron (V-shape, 109.47º) | C2v | |
| 2 | vOC-2 | Tetravacant octahedron (L-shape, 90º) | C2v | |
| 3 | 0 | TP-3 | Trigonal planar | D3h |
| 1 | vT-3 | Pyramid‡ (vacant tetrahedron) | C3v | |
| 2 | fac-vOC-3 | Trivacant octahedron | C3v | |
| 3 | mer-vOC-3 | Trivacant octahedron (T-shape) | C2v | |
| 4 | 0 | SP-4 | Square | D4h |
| 1 | T-4 | Tetrahedron | Td | |
| 2 | SS-4 | Seesaw or sawhorse‡ (cis-divacant octahedron) | C2v | |
| 3 | vTBPY-4 | Axially vacant trigonal bipyramid | C3v | |
| 5 | 0 | PP-5 | Pentagon | D5h |
| 1 | vOC-5 | Vacant octahedron‡ (Johnson square pyramid, J1) | C4v | |
| 2 | TBPY-5 | Trigonal bipyramid | D3h | |
| 3 | SPY-5 | Square pyramid§ | C4v | |
| 4 | JTBPY-5 | Johnson trigonal bipyramid (J12) | D3h | |
| 6 | 0 | HP-6 | Hexagon | D6h |
| 1 | PPY-6 | Pentagonal pyramid | C5v | |
| 2 | OC-6 | Octahedron | Oh | |
| 3 | TPR-6 | Trigonal prism | D3h | |
| 4 | JPPY-5 | Johnson pentagonal pyramid (J2) | C5v | |
| 7 | 0 | HP-7 | Heptagon | D7h |
| 1 | HPY-7 | Hexagonal pyramid | C6v | |
| 2 | PBPY-7 | Pentagonal bipyramid | D5h | |
| 3 | COC-7 | Capped octahedron* | C3v | |
| 4 | CTPR-7 | Capped trigonal prism* | C2v | |
| 5 | JPBPY-7 | Johnson pentagonal bipyramid (J13) | D5h | |
| 6 | JETPY-7 | Elongated triangular pyramid (J7) | C3v | |
| 8 | 0 | OP-8 | Octagon | D8h |
| 1 | HPY-8 | Heptagonal pyramid | C7v | |
| 2 | HBPY-8 | Hexagonal bipyramid | D6h | |
| 3 | CU-8 | Cube | Oh | |
| 4 | SAPR-8 | Square antiprism | D4d | |
| 5 | TDD-8 | Triangular dodecahedron | D2d | |
| 6 | JGBF-8 | Johnson-Gyrobifastigium (J26) | D2d | |
| 7 | JETBPY-8 | Johnson-Elongated triangular bipyramid (J14) | D3h | |
| 8 | JBTPR-8 | Johnson-Biaugmented trigonal prism (J50) | C2v | |
| 9 | BTPR-8 | Biaugmented trigonal prism | C2v | |
| 10 | JSD-8 | Snub disphenoid (J84) | D2d | |
| 11 | TT-8 | Triakis tetrahedron | Td | |
| 12 | ETBPY-8 | Elongated trigonal bipyramid (see 8) | D3h | |
| 9 | 0 | EP-9 | Enneagon | D9h |
| 1 | OPY-9 | Octagonal pyramid | C8v | |
| 2 | HBPY-9 | Heptagonal bipyramid | D7h | |
| 3 | JTC-9 | Triangular cupola (J3) = trivacant cuboctahedron | C3v | |
| 4 | JCCU-9 | Capped cube (Elongated square pyramid, J8) | C4v | |
| 5 | CCU-9 | Capped cube | C4v | |
| 6 | JCSAPR-9 | Capped sq. antiprism (Gyroelongated square pyramid J10) | C4v | |
| 7 | CSAPR-9 | Capped square antiprism | C4v | |
| 8 | JTCTPR-9 | Tricapped trigonal prism (J51) | D3h | |
| 9 | TCTPR-9 | Tricapped trigonal prism | D3h | |
| 10 | JTDIC-9 | Tridiminished icosahedron (J63) | C3v | |
| 11 | HH-9 | Hula-hoop | C2v | |
| 12 | MFF-9 | Muffin | Cs | |
| 10 | 0 | DP-10 | Decagon | D10h |
| 1 | EPY-10 | Enneagonal pyramid | C9v | |
| 2 | OBPY-10 | Octagonal bipyramid | D8h | |
| 3 | PPR-10 | Pentagonal prism | D5h | |
| 4 | PAPR-10 | Pentagonal antiprism | D5d | |
| 5 | JBCCU-10 | Bicapped cube (Elongated square bipyramid J15) | D4h | |
| 6 | JBCSAPR-10 | Bicapped square antiprism (Gyroelongated square bipyramid J17) | D4d | |
| 7 | JMBIC-10 | Metabidiminished icosahedron (J62) | C2v | |
| 8 | JATDI-10 | Augmented tridiminished icosahedron (J64) | C3v | |
| 9 | JSPC-10 | Sphenocorona (J87) | C2v | |
| 10 | SDD-10 | Staggered dodecahedron (2:6:2)# | D2 | |
| 11 | TD-10 | Tetradecahedron (2:6:2) | C2v | |
| 12 | HD-10 | Hexadecahedron (2:6:2, or 1:4:4:1) | D4h | |
| 11 | 0 | HP-11 | Hendecagon | D11h |
| 1 | DPY-11 | Decagonal pyramid | C10v | |
| 2 | EBPY-11 | Enneagonal bipyramid | D9h | |
| 3 | JCPPR-11 | Capped pent. prism (Elongated pentagonal pyramid J9) | C5v | |
| 4 | JCPAPR-11 | Capped pent. antiprism (Gyroelongated pentagonal pyramid J11) | C5v | |
| 5 | JAPPR-11 | Augmented pentagonal prism (J52) | C2v | |
| 6 | JASPC-11 | Augmented sphenocorona (J87) | Cs | |
| 12 | 0 | DP-12 | Dodecagon | D12h |
| 1 | HPY-12 | Hendecagonal pyramid | C11v | |
| 2 | DBPY-12 | Decagonal bipyramid | D10h | |
| 3 | HPR-12 | Hexagonal prism | D6h | |
| 4 | HAPR-12 | Hexagonal antiprism | D6d | |
| 5 | TT-12 | Truncated tetrahedron | Td | |
| 6 | COC-12 | Cuboctahedron | Oh | |
| 7 | ACOC-12 | Anticuboctahedron (Triangular orthobicupola J27) | D3h | |
| 8 | IC-12 | Icosahedron | Ih | |
| 9 | JSC-12 | Square cupola (J4) | C4v | |
| 10 | JEPBPY-12 | Elongated pentagonal bipyramid (J16) | D6h | |
| 11 | JBAPPR-12 | Biaugmented pentagonal prism (J53) | C2v | |
| 12 | JSPMC-12 | Sphenomegacorona (J88) | Cs | |
| 20 | 0 | DD-20 | Dodecahedron† | Ih |
| 24 | 0 | TCU-24 | Truncated cube | Oh |
| 1 | TOC-24 | Truncated octahedron | Oh | |
| 48 | 0 | TCOC-48 | Truncated cuboctahedron | Oh |
| 60 | 0 | TIC-60 | Truncated icosahedron (fullerene) | Ih |
Be noted that the index of each shape differs from SHAPE's 2.1 by 1.
I have a certain suspicion that the original numbering starting from one is due to Fortran arrays being silly.
The user can include custom polyhedra into the calculation by pointing to shape.yaml files. The shapes specified must have the same number of vertices as the problem shape.
The syntax for writing these files is as follows:
symbol:
name:
symmetry:
vertices:
- [ coord_x, coord_y, coord_z]
- [ ...
centre:
- [ coord_x, coord_y, coord_z]
Cosmochlore's YAML parser is somewhat flexible when specifying the key names. It accepts the following synonyms:
| Key | Synonyms | Value type |
|---|---|---|
symbol |
None | name |
name |
None | name |
symmetry |
symm |
name |
vertices |
ligands |
[x, y, z] |
centre |
center, metal |
[x, y, z] |
Example .yaml file:
ebcT-6:
name: Edge-bicapped tetrahedron
symm: D2d
vertices:
- [0.5000, 0.5000, -0.6495]
- [1.0000, 1.0000, 0.0000]
- [1.0000, 0.0000, 1.0000]
- [0.0000, 1.0000, 1.0000]
- [0.5000, 0.5000, 1.6495]
- [0.5000, 0.5000, 0.5000]
centre:
- [ 0.0000, 0.0000, 0.0000 ]
fvCU-6:
name: Face-divacant cube
symm: C2v
vertices:
# - [ 1.000000000000, 0.000000000000, -0.707106780000]
- [ 0.000000000000, 1.000000000000, -0.707106780000]
# - [-1.000000000000, 0.000000000000, -0.707106780000]
- [-0.000000000000, -1.000000000000, -0.707106780000]
- [ 1.000000000000, 0.000000000000, 0.707106780000]
- [ 0.000000000000, 1.000000000000, 0.707106780000]
- [-1.000000000000, 0.000000000000, 0.707106780000]
- [-0.000000000000, -1.000000000000, 0.707106780000]
center:
- [ 0.000000000000, 0.000000000000, 0.000000000000]As per the example, a single reference.yaml file can contain multiple reference polyhedra.
Comments are also supported by the YAML parser, every line that starts with # will be ignored.
The csom -p/--pg flag accepts any of the following point groups, given in Schoenflies notation:
C2 C2h C2v C3 C3h C3v C4 C4h C4v C5 C5h C5v
C6 C6h C6v C7 C8 Ci Cs D2 D2d D2h D3 D3d
D3h D4 D4d D4h D5 D5d D5h D6 D6h D7h D8h E
I Ih O Oh S10 S4 S6 S8 T Td Th
Point-group names are case-sensitive and must match one of the symbols above exactly (e.g. Oh, not oh or OH).
The Continuous Shape Measure of a problem shape
where
The rotation/translation/scaling part is solved via an SVD-based Kabsch-style alignment. The combinatorial problem: finding the best point pair matches between
- Automorphism deduplication: the reference shape's own symmetry group is precomputed, so permutations that are guaranteed to produce identical scores (automorphisms of the reference shape's point group) are never evaluated twice.
- Branch-and-bound pruning: partial assignments are bounded using the subadditivity property of the singular-value sum, allowing branches that provably cannot beat the current best score to be discarded early.
For a given target point group, csom searches for the orientation of the structure that minimizes its deviation from that point group's ideal symmetry operations. This is done in two stages:
-
Fibonacci-sphere seeding:
$$N$$ orientation vectors are spread evenly over the unit sphere and each is scored, giving a good starting point without an expensive exhaustive search. -
Nelder-Mead refinement: starting from the best seed, a derivative-free Nelder-Mead optimisation (up to
--iterationssteps) refines the rotation axis to (locally) minimize the deviation. - The deviation is defined as the
$$S_Q(^OQ)$$ minimised over the best permutation of points using the Hungarian algorithm. This minimisation is atom-sensitive, that is, atoms are only matched with others of the same element.
The reported deviation is the CSoM between the structure and every symmetry operation of the target point group at the best orientation found.
odis reports the classic OctaDist bond-length and angular distortion parameters for a six-coordinate centre — mean M–X distance, zeta (bond-length distortion), delta (normalized bond-length variance), sigma (cis-angle distortion) and tau (trans-angle distortion) — plus mu, the norm of the mean ligand-vector (a measure of how far the centre sits from the ligands' vector centroid).
Aditionally, the odis module runs cshm against the ideal octahedron/trigonal prism and csom against the point groups most commonly seen in octahedral distortions, to give a fuller picture of the distortion of the coordination sphere.
This project reimplements the shape-measure methodology originally developed for the SHAPE program and continued in cosymlib by the Electronic Structure Group at the Universitat de Barcelona. Cosmochlore is an independent, from-scratch implementation and is not affiliated with the original authors.
The code, binaries and sample tests are provided as is, with no warranty of any kind. This program is licensed under the GNU General Public Licence v3.0 (GPL-3.0). See the LICENSE.md file or https://www.gnu.org/licenses/gpl-3.0.html for full terms.
Parts of the cshm module are based on cosymlib (shp.f90), Copyright (c) 2021 Pere Alemany, Efrem Bernuz, Abel Carreras and Miquel Llunell, licensed under the MIT Licence.
Parts of the odis module is are based on the OctaDist3 algorithm, Copyright (c) 2019-2026 Rangsiman Ketkaew et al., licensed under the GNU General Public Licence v3.0 (GPL-3.0).
The program relies on the clap crate for argument parsing. Dual-licensed under the Apache 2.0 or MIT licences.
The program relies on the nalgebra crate for the fast linear algebra computations. Licensed under the Apache 2.0 licence.
The program relies on the itertools crate for combinatorial iteration (used, among other things, to enumerate the vertex-pair angles in odis). Dual-licensed under the Apache 2.0 or MIT licences.
The program relies on the argmin and argmin-math crates for the Nelder-Mead optimisation of the symmetry axis in csom. Dual-licensed under the Apache 2.0 or MIT licences.
- Cirera, J., Ruiz, E., & Alvarez, S. (2005). Continuous Shape Measures as a Stereochemical Tool in Organometallic Chemistry. Organometallics, 24(7), 1556–1562. https://doi.org/10.1021/om049150z
- Alvarez, S., Alemany, P., Casanova, D., Cirera, J., Llunell, M., & Avnir, D. (2005). Shape maps and polyhedral interconversion paths in transition metal chemistry. Coordination Chemistry Reviews, 249(17–18), 1693–1708. https://doi.org/10.1016/j.ccr.2005.03.031
- Nielsen, V. R. M., Le Guennic, B., & Sørensen, T. J. (2024). Evaluation of Point Group Symmetry in Lanthanide(III) Complexes: A New Implementation of a Continuous Symmetry Operation Measure with Autonomous Assignment of the Principal Axis. The Journal of Physical Chemistry A, 128(28), 5740–5751. https://doi.org/10.1021/acs.jpca.4c00801
- Ketkaew, R., Tantirungrotechai, Y., Harding, P., Chastanet, G., Guionneau, P., Marchivie, M., & Harding, D. J. (2021). OctaDist: a tool for calculating distortion parameters in spin crossover and coordination complexes. Dalton Transactions, 50(3), 1086–1096. https://doi.org/10.1039/d0dt03988h