advanced_cshm-cc

Browser-based CShM analyzer for coordination compounds.

This project is a web-app companion to the Python command-line tool cshm-cc. It calculates Continuous Shape Measures (CShM), selected geometry indices, polyhedral volumes, and coordination spheres from CIF and XYZ structure files directly in the browser.

The app is designed to work without a local server:

open index.html

It can also be hosted as a static web page, e.g. via GitHub Pages.

https://radi0sus.github.io/advanced_cshm-cc/

---

Relation to the Python CLI tool

The original Python tool is:

cshm-cc

This browser version follows the same general purpose:

• automatic detection of central metal sites,
• coordination-sphere generation,
• CShM calculation for CN 2–6,
• τ₄, τ₄′, τ₅, and octahedricity O,
• polyhedral volume,
• XYZ export of coordination spheres with the metal atom at the origin.

However, the implementation and workflow differ.

---

Main differences from cshm-cc

1. Browser-only, no Python dependencies

The web app uses plain JavaScript and bundled browser libraries.

2. No direct COD import

The Python CLI can download structures from the Crystallography Open Database (COD) by COD ID.

The browser app cannot directly fetch CIF files from COD.

Recommended workflow for COD structures:

1. download the CIF manually from COD,
2. drop the CIF file into the web app.

3. CIF and XYZ files are loaded locally

The web app accepts:

.cif
.xyz

via drag-and-drop or file picker.

Multi-block CIF files are supported. Multi-XYZ files are also supported.

4. Interactive coordination-sphere editing

Unlike the CLI tool, the web app allows interactive inspection and adjustment:

• select/deselect detected metal sites,
• change the bond-radius tolerance per site,
• include/exclude H atoms,
• include/exclude metal–metal contacts,
• manually toggle individual ligand atoms in a coordination sphere,
• immediately update CN, CShM, geometry indices, viewer and exports.

5. CShM optimization

The Python CLI has two modes:

• fast mode with a configurable number of random trials,
• exact mode using all permutations.

The browser version currently uses an exact permutation-based approach for CN 2–6. Therefore, there is no "number of trials" setting in the web app.

For CN 2–6 this is feasible because the maximum number of points is 7 (central atom + 6 ligands):

CN	points	permutations
2	3	6
3	4	24
4	5	120
5	6	720
6	7	5040

This makes the browser result deterministic and closer to the exact mode of the Python tool.

6. Symmetry handling

The Python version uses gemmi for crystallographic symmetry and periodic boundary handling.

The browser version implements CIF symmetry operators and periodic-image searching in JavaScript. It supports symmetry-equivalent and translated ligand positions and stores symmetry information for each ligand.

Because this is not gemmi, small differences may occur for difficult CIFs, unusual symmetry settings, disorder, or edge cases.

7. Polyhedral volume

The Python CLI uses SciPy/Qhull:

scipy.spatial.ConvexHull

The browser version uses a small JavaScript convex-hull volume implementation. For common CN 4–6 coordination polyhedra it should give useful values, but it may not be as robust as Qhull for degenerate or nearly coplanar point sets.

---

Features

• Load local .cif and .xyz files.
• Supports multi-block CIF files.
• Supports multi-XYZ files.
• Automatic central atom detection.
• Interactive selection of metal sites.
• Per-site bond-radius tolerance slider.
• Optional inclusion of hydrogen ligands.
• Optional inclusion of metal–metal contacts.
• Clickable ligand chips:
  • all ligands are active by default,
  • clicking a ligand toggles it on/off,
  • CShM, CN, geometry indices and viewer update immediately.
• 3Dmol.js viewer for coordination spheres.
• Export results as Markdown.
• Export coordination spheres as XYZ with the central atom at:

0.000000  0.000000  0.000000

---

Usage

Open the app locally:

open index.html

or host the repository as a static website.

Then:

1. drop a CIF or XYZ file into the dropzone,
2. select/deselect metal sites if needed,
3. adjust options,
4. inspect the CShM and geometry results,
5. optionally export Markdown or XYZ.

---

Input

CIF

The app reads atom labels, atom types, fractional coordinates, unit-cell parameters and symmetry operations from CIF files. It supports CIFs with single or multiple structure entries.

XYZ

Single XYZ:

5
example
Fe1  0.000  0.000  0.000
N1   2.000  0.000  0.000
N2  -2.000  0.000  0.000
O1   0.000  2.000  0.000
O2   0.000 -2.000  0.000

Multi-XYZ:

5
fragment 1
Fe1  0.000  0.000  0.000
N1   2.000  0.000  0.000
N2  -2.000  0.000  0.000
O1   0.000  2.000  0.000
O2   0.000 -2.000  0.000

5
fragment 2
Cu1  0.000  0.000  0.000
N1   2.000  0.000  0.000
N2  -2.000  0.000  0.000
Cl1  0.000  2.000  0.000
Cl2  0.000 -2.000  0.000

The parser accepts atom labels such as Fe1, N2, Cl1 and normalizes the element symbol internally.

---

Output

Markdown export

The Markdown export contains one section per metal site, including:

• CN,
• τ₄, τ₄′, τ₅, O, where applicable,
• polyhedral volume,
• CShM table,
• ligand table with distances and symmetry information.

If the input file is:

example.cif

the Markdown export should be named:

example.md

If the input file is:

example.xyz

the Markdown export should also be named:

example.md

XYZ export

The XYZ export contains the selected coordination spheres.

For CIF input:

example.cif → example.xyz

For XYZ input, the export should avoid overwriting the original file, for example:

example.xyz → example_spheres.xyz

Each exported coordination sphere is centered on the metal atom:

7
example-Fe1 CN=6
Fe     0.000000     0.000000     0.000000
O     -0.616592    -1.061741    -1.501215
O      0.959974     1.212008    -1.158622
O      0.571590     1.007982     1.743717
O     -1.724182     1.000584     0.126840
N     -0.704425    -1.596884     1.194038
N      1.895974    -0.970502     0.221754

---

Geometry indices

The following indices are calculated where applicable.

τ₄

For four-coordinate compounds:

$$\tau_4 = \frac{360^\circ-(\alpha+\beta)}{141^\circ}$$

Square planar geometry:

τ₄ = 0

Tetrahedral geometry:

τ₄ = 1

Seesaw geometry:

τ₄ ≈ 0.43

τ₄′

Improved four-coordinate geometry index:

$$\tau'_4 = \frac{\beta-\alpha}{250.5^\circ} + \frac{180^\circ-\beta}{70.5^\circ}$$

Square planar geometry:

τ₄′ = 0

Tetrahedral geometry:

τ₄′ = 1

Seesaw geometry:

τ₄′ ≈ 0.24

τ₅

For five-coordinate compounds:

$$\tau_5 = \frac{\beta-\alpha}{60^\circ}$$

Square pyramidal geometry:

τ₅ = 0

Trigonal bipyramidal geometry:

τ₅ = 1

Here, α and β are the two largest ligand-metal-ligand angles, with:

β > α

Octahedricity O

For six-coordinate compounds:

$$O = \sqrt{ \frac{1}{15} \sum_{i=1}^{15} (\hat{\theta_i}-\theta_i)^2 }$$

where:

θ̂ᵢ = 180° for trans angles
θ̂ᵢ =  90° for cis angles
θᵢ  = experimental ligand-metal-ligand angle

O is close to zero for an almost ideal octahedron.

---

CShM reference shapes

The app currently supports CShM for CN 2–6.

CN 2

L-2
vT-2
vOC-2

CN 3

TP-3
vT-3
fvOC-3
mvOC-3

CN 4

SP-4
T-4
SS-4
vTBPY-4

CN 5

PP-5
vOC-5
TBPY-5
SPY-5
JTBPY-5

CN 6

HP-6
PPY-6
OC-6
TPR-6
JPPY-6

The reference coordinates are based on ideal structures used by cosymlib and related Continuous Shape Measure tools.

---

Bond detection

Possible coordinating atoms are detected using covalent radii.

The default radius table follows the "maximum radii" approach used in the Python cshm-cc tool, based on tested values from Alvarez, SHELX and Jmol-style radii. A default bond tolerance is applied to the sum of the central-atom and ligand radii.

The per-card slider changes this tolerance interactively.

Hydrogen ligands are excluded by default unless enabled.

Metal–metal contacts are excluded by default unless enabled.

---

Metal–metal contacts

By default, metal atoms are not considered as ligands. This avoids automatic inclusion of metal-metal contacts or symmetry-equivalent metal atoms in the coordination sphere.

The option:

Include metal–metal bonds

allows metal atoms to be considered as ligands if they fall within the current bond cutoff.

The exact same labelled atom as the central atom is always excluded.

---

Limitations

• Direct COD loading is not available in the browser.
• The browser CIF handling is not gemmi; difficult CIFs may behave differently from the Python CLI.
• Symmetry and periodic boundary handling are implemented in JavaScript and may not cover all crystallographic edge cases.
• Polyhedral volume is calculated with a browser-side convex-hull routine and may differ from SciPy/Qhull in degenerate cases.
• Estimated standard deviations on bond lengths and angles are not calculated.
• CShM is currently implemented for CN 2–6.
• Very large CIFs or many metal sites may be slower in the browser.

---

Third-party software

3Dmol.js

The web app uses 3Dmol.js for molecular visualization.

Project:

https://3dmol.csb.pitt.edu/

Reference:

Nicholas Rego and David Koes,
"3Dmol.js: molecular visualization with WebGL",
Bioinformatics 2015, 31, 1322–1324.
DOI: https://doi.org/10.1093/bioinformatics/btu829

CIF parser

The app uses a JavaScript CIF parser derived from cif.js by Gert-Jan Bekker.

Project/source:

https://gitlab.com/pdbjapan/tools/cif-parsers

License:

MIT

The license header in static/js/cif.js should be kept.

Shape reference structures

Ideal reference structures are based on:

https://github.com/GrupEstructuraElectronicaSimetria/cosymlib/blob/master/cosymlib/shape/ideal_structures_center.yaml

---

References

If you use τ₄, τ₄′, τ₅, O, or CShM to describe coordination geometries, please cite the relevant literature.

τ₄

Lei Yang, Douglas R. Powell, Robert P. Houser,
"Structural variation in copper(i) complexes with pyridylmethylamide ligands: structural analysis with a new four-coordinate geometry index, τ₄",
Dalton Transactions 2007, 955–964.
DOI: https://doi.org/10.1039/B617136B

τ₄′

Andrzej Okuniewski, Damian Rosiak, Jarosław Chojnacki, Barbara Becker,
"Coordination polymers and molecular structures among complexes of mercury(II) halides with selected 1-benzoylthioureas",
Polyhedron 2015, 90, 47–57.
DOI: https://doi.org/10.1016/j.poly.2015.01.035

τ₅

Anthony W. Addison, T. Nageswara Rao, Jan Reedijk, Jacobus van Rijn, Gerrit C. Verschoor,
"Synthesis, structure, and spectroscopic properties of copper(II) compounds containing nitrogen–sulphur donor ligands; the crystal and molecular structure of aqua[1,7-bis(N-methylbenzimidazol-2′-yl)-2,6-dithiaheptane]copper(II) perchlorate",
Journal of the Chemical Society, Dalton Transactions 1984, 1349–1356.
DOI: https://doi.org/10.1039/DT9840001349

Octahedricity O

Christopher M. Brown, Nicole E. Arsenault, Trevor N. K. Cross, Duane Hean, Zhen Xu, Michael O. Wolf,
"Structural, electrochemical and photophysical behavior of Ru(II) complexes with large bite angle sulfur-bridged terpyridyl ligands",
Inorganic Chemistry Frontiers 2020, 7, 117–127.
DOI: https://doi.org/10.1039/C9QI01009B

Continuous Shape Measures

Mark Pinsky, David Avnir,
"Continuous Symmetry Measures. 5. The Classical Polyhedra",
Inorganic Chemistry 1998, 37, 5575–5582.
DOI: https://doi.org/10.1021/ic9804925

Santiago Alvarez, Pere Alemany, David Casanova, Jordi Cirera, Miquel Llunell, David Avnir,
"Shape maps and polyhedral interconversion paths in transition metal chemistry",
Coordination Chemistry Reviews 2005, 249, 1693–1708.
DOI: https://doi.org/10.1016/j.ccr.2005.03.031

Covalent radii

Beatriz Cordero, Verónica Gómez, Ana E. Platero-Prats, Marc Revés, Jorge Echeverría, Eduard Cremades, Flavia Barragán, Santiago Alvarez,
"Covalent radii revisited",
Dalton Transactions 2008, 2832–2838.
DOI: https://doi.org/10.1039/B801115J

3Dmol.js

Nicholas Rego and David Koes,
"3Dmol.js: molecular visualization with WebGL",
Bioinformatics 2015, 31, 1322–1324.
DOI: https://doi.org/10.1093/bioinformatics/btu829

---

Related projects

• Python CLI tool:
  https://github.com/radi0sus/cshm-cc

• Manual atom-selection geometry tool:
  https://github.com/radi0sus/tau-calc

• Continuous Symmetry Measure / Shape code:
  https://github.com/continuous-symmetry-measure/shape

• SHAPE program:
  https://www.ee.ub.edu/downloads/

• Online CSM calculator:
  https://csm.ouproj.org.il/molecule

---

Notes on licenses and attribution

This repository contains original project code and third-party JavaScript libraries.

Keep license headers in bundled third-party files, especially:

static/js/cif.js
static/vendor/3Dmol-min.js

If redistributing the app, include appropriate license information for all third-party components.