Timaeus

Timaeus is an Olex2$^1$ plugin that integrates several symmetry and shape analysis tools into a single graphical interface within Olex2.

Features

• All analysis methods in Timaeus will read the atomic coordinates directly from the OlexRefinementModel — no external input files needed.
• Olex2 GUI panel.
• Cosmochlore integration: Continuous Shape Measures, Continuous Symmetry Operation Measures and octahedral distortion.
• SHAPE 2.1 wrapper and output parser.
• Octahedral distortion parameters calculation.
• Centroid merging for pi-bonded ligands.
• Automatic disorder handling. If more than two parts are found in the selected structure, calculations will be run on each part separately.

Requirements

• Olex2 1.5.
• cosmochlore 1.1.1 or newer on your PATH (optional, needed for the Cosmochlore panel).
  • The path can also be set explicitly in the plugin settings (Extras > Settings).
• SHAPE 2.1 executable available on your system PATH (optional, needed for the SHAPE panel).
  • Download SHAPE 2.1 from the Electronic Strucutre Group's webpage

The plugin was developed/tested using a Windows 10/11 machine. The plugin should be system agnostic but please report any bugs found in any other operating systems.

Note: It is known that SHAPE 2.1 gives trouble in Mac machines with operating systems newer than 2022 and some Linux systems. Unfortunately, I can't do anything about that since the ESG hasn't published a precompiled SHAPE version since 2013. In the future I might introduce support for Cosymlib by ESG which is the updated version of their shape and symmetry measures program.

Instalation

1. Download the source code from the lastest GitHub release.
2. Go to the base directory of your Olex2 instalation. You can open the directory by typing shell BaseDir() in the Olex2 console.
3. Create a file called plugins.xld and write the following contents inside plugins.xld:

<Plugin
 <Timaeus>
>

4. Go to the <BaseDir>\util\pyUtil\PluginLib\ folder and create a folder called plugin-Timaeus.
5. Extract the downloaded zip into that folder.
6. On restarting Olex2, a Timaeus panel should appear under the Tools tab.

Note: I push development changes constantly to the master branch. You could git clone this repository to automatically keep the plugin updated. Usually, if changes are pushed it means that the plugin is in a usable state. But it does not guarantee that things won't break.

Cosmochlore

cosmochlore is a separate Rust program that calculates shape and symmetry measures. Timaeus wraps its three subcommands; each writes its output next to the structure and prints the results table to the console. Every option below has a phil parameter, editable in Extras > Settings or from the panel itself. Cosmochlore was intentionally developed to function as a background process to Timaeus. Most options of the program can be accessed through the GUI.

Function	Description
spy.Timaeus.autoCSHM()	Continuous Shape Measures against the built-in and user-defined reference polyhedra.
spy.Timaeus.autoCSOM()	Continuous Symmetry Operation Measures against a list of point groups.
spy.Timaeus.autoODIS()	Octahedral distortion parameters, independent of the OctaDist reimplementation below. Select the central atom of a 6-coordinate complex.

Usage

1. Open a structure in Olex2.
2. Select the atoms you want to include in the measurement.

• If one atom is selected, the neighbouring atoms will be taken into account to form a centered shape (e.g. a coordination structure).
• If multiple atoms are selected, they will be interpreted as a non centered shape (e.g. a borane cluster).

4. Run any of the cosmochlore functions from the Olex2 console or from the Tools/Timaeus/Cosmochlore panel.
5. Results are printed to the console and saved in <FilePath>/cosmochlore/.

User-defined shapes

Reference shapes beyond the built-in 90 can be added as .yaml files in the user_shapes/ folder of the plugin (Open user defined shapes folder in the CShM panel). A mismatched vertex count is reported as an error by cosmochlore itself.

AutoSHAPE

SHAPE 2.1$^2$ is a software published by ESG used to calculate Continuous Shape Measures (CShM's). autoSHAPE is a collection of personal Python scripts I developed and used to run and parse SHAPE i/o files. Timaeus contains an implementation of autoSHAPE to:

• Generate the necessary .dat input files for SHAPE automatically.
• Run SHAPE and parse the resulting .tab output.
• Output a summary table from the .out and .tab files. SM's autoSHAPE does not overwrite previous runs as it stores each run in a dedicated folder: <FilePath>\autoSHAPE\<FileName>_<part>_<atoms>\<run>.

Usage

1. autoSHAPE uses the same selection criteria as cosmochlore. Select a single atom for a centered measurement or multiple for a non-centered one.
2. Run spy.Timaeus.autoSHAPE() from the Olex2 command line or from the Tools/Timaeus/SHAPE 2.1 panel.

New in version 0.2

There is an option to merge pi-bonded ligands into a centroid. If checked, autoshape will interpret pi-bonded ligands as the average of the fragments as per Cirera et al$^2$ paper.

Octahedral Distortion Parameters.

Timaeus includes a reimplementation of the OctaDist$^3$ algorithm. Unlike the original implementation, this version identifies opposite faces and vertices of an octahedron using topological criteria. It relies on constructing a convex hull that is topologically equivalent to an octahedron. As a result, the algorithm may fail when more than three vertices are coplanar, causing the convex hull to degenerate into a different polyhedral shape.

Several features of the original OctaDist program have been omitted to simplify integration with Olex2 and to remove redundant functionality.

The Octahedral Distortion Parameters module computes all distortion parameters reported by OctaDist, together with an additional $\tau$ and $\mu$ parameters that quantify the deviation of trans angles from the ideal 180 $^\circ$ and the deviation of the metal centre to the centroid of the octahedron, respectively. The calculated values are generally consistent with those produced by OctaDist, although discrepancies may occur for highly distorted octahedra or for structures approaching an ideal trigonal prism.

• Bond length distortion:

$$\zeta = \sum_{i=1}^6 |d_i - d_{mean}|$$

where $d_i$ are the M-X bond distances and $d_{mean}$ is the mean M-X bond distance.

• Octahedral tilting parameter:

$$\Delta = \frac{1}{6}\sum_{i=1}^6 \left(\frac{d_i - d_{mean}}{d_{mean}}\right)^2$$

where $d_i$ are the M-X bond distances and $d_{mean}$ is the mean M-X bond distance.

• Cis angle distortion:

$$\Sigma = \sum_{i=1}^{12} |90^\circ - \phi_i|$$

where $\phi_i$ are the cis angles.

• Octahedral twisting distortion:

$$\Theta = \sum_{i=1}^{24} |60^\circ - \theta_i|$$

where $\theta_i$ are twisting angles between vectors of two opposite faces.

Extra parameters:

• Trans angle distortion:

$$\tau = \sum_{i=1}^3 |180^\circ - \psi_i|$$

where $\psi_i$ are the trans angles.

• Deviation of the metal from the centroid:

$$\vec{c} = \frac{1}{6}\sum^6_{i=1} \vec{r}_i$$ $$\mu = |\vec{r}_M - \vec{c}|$$

where $\vec{r}_M$ is the position of the metal and $\vec{r}_i$ are the position of the donor atoms.

Usage

1. Open a structure in Olex2.
2. Select the central atom of a 6-coordinate complex.
3. Run spy.Timaeus.autoOCTADIST() from the Olex2 console or from the Tools/Timaeus panel.
4. Results are printed in the console. A graph will saved in <FilePath>/OH_distortion showing the extracted octahedron.

Known limitations/upcoming features.

Status	Features
✔️	Suppport for disordered structures.
✔️	Centorid search for pi-bonded ligands. *Doesn't work with ligands outside ASU.
✔️	Custom reference shapes. *Via cosmochlore, see user_shapes/.
✔️	Smarter program logic (automatic coordination site detection, multiple selections, etc.).
✔️	Support for other measurement programs (cosmochlore: CShM, CSoM, ODis).
✔️	Reimplementation of octahedral distortion parameters (Zeta, Sigma, Theta) — relevant for spin-crossover (SCO) complexes.
✔️	Non centered shapes.
✔️	HTML UI.

License

• Not yet.

Citations

1. J. Appl. Cryst. (2009). 42, 339–341. DOI: https://doi.org/10.1107/S0021889808042726
2. Organometallics (2005), 24, 7, 1556–1562. DOI: https://doi.org/10.1021/om049150z
3. Dalton Trans. (2021) 50, 3, 1086–1096. DOI: https://doi.org/10.1039/d0dt03988h