Metal sites

For each metal centre in a structure, orbitron analyze metal-sites reports an oxidation state in the ionic model with a trust grade and the reasons for it, the d or f electron configuration, and a valence electron count that gives the alternatives when the geometry does not settle it. It also flags ligands whose charge is a convention, draws a ligand-field pattern (the desktop draws it for d1 to d9; the command line also prints the flat pattern of a d0 or d10 centre), and reads boron cages by their skeletal electron count. The same oxidation-state code decides the charges in the InChI and SMILES that orbitron identify writes.

Start with Running it and the first two worked reports. This page explains what each part means and how to read it. How often the reported state is right, and the numbers behind each trust grade, are on Metal sites: accuracy and limits. The command’s flags are in CLI §4.9.

Running it

Command line

orbitron analyze metal-sites complex.xyz
orbitron analyze metal-sites complex.xyz --json --no-banner
orbitron analyze metal-sites complex.xyz --oxidation-state 3
orbitron plot ligand-field complex.xyz -o complex.svg --data complex.csv

analyze metal-sites takes any structure with a metal in it: a molecule, a protein with ions, a periodic cell. The text report has one block per metal. With --json the output is the orbitron.analyze.metal-sites/2 object: schema, sites, site_count, flagged_count, verdict_counts, warnings, distance_anomaly_threshold_angstrom, source and producer. Each entry of sites has atom, element, coordination_number, radius_coordination_number, oxidation_state, oxidation_state_source, valence_electrons, trust, electron_count, ligand_field, redox_ligands, hapto_sites, agostic_contacts, bond_valence, donors, shape, shapes, shape_path, measure, verdict, worst_deviation_angstrom, oxo_expected, oxo_found, buried_volume, cone_angles and needs_review; a metal with an oxo core also has oxo_angle_degrees, oxo_review_range_degrees, oxo_scaled and, on a two-oxo axial core, equatorial_girdle (see the coordination sphere). An open-shell fⁿ ion that is not an actinyl carries free_ion, and oxo groups found in a structure with no hydrogens set oxo_by_distance_only. These names hold for the life of /2: a field may be added, and one removed or renamed changes the schema to /3.

--oxidation-state N states one state and applies it to every metal in the file. For a file with several different metals, use orbitron identify --oxidation-state ATOM=STATE, which takes a state per atom (see stating a state).

Python

The Python bridge has no separate metal-sites call. Its one route to a metal’s state is orbitron.identify(scene)["metal_states"], which lists, for each metal, the state the identifiers were written at beside the reported state, its trust grade and its cautions:

import orbitron as orb

scene = orb.load("complex.xyz")
for metal in orb.identify(scene)["metal_states"]:
    print(metal["element"], metal["reported_state"], metal["confidence"])

The electron count, the configuration and the ligand-field picture are not in that dictionary. Run the CLI for them, or read analyze metal-sites --json from a subprocess. Python §identify has the full field list.

Desktop viewer

The Coordination readout in the rail’s Scene section (Scene Info) shows the oxidation state with the d or f count, the electron count, the trust grade with its cautions, the polyhedron and a collapsible Ligand field drawing. The state and the count come from the same code as the CLI report. For a structure with residue annotation, the Metal sites list in the Sequence / Residues panel names each centre’s donors by residue. See the viewer guide.

What the file has to say

The ionic model divides a complex’s charge between the ligands and the metal, so it needs the total charge. In an XYZ file, put charge= on the comment line (charge=1, or charge=-2 multiplicity=1). Without a declared charge:

  • the electron count is declined: “the file declares no total charge, so the ligands’ charges cannot be divided from the metal’s”;
  • there is no ionic-model state, so the state falls to what the file states, a formal charge on the metal, a consistent bond-valence sum, or the element’s one usual state, and if none of those answers the site reads state unknown with no trust grade and no ligand-field picture.

A multiplicity= that is odd (1, 3, 5) tells the count the complex has an even number of electrons. Without it an odd count is reported as odd instead of odd_on_closed_shell (see the electron count).

A worked report

Everything below was produced with the release orbitron binary on fixtures committed under io/pipelines/tests/fixtures/xyz/, all but co_hexadentate_chelate.xyz in its ionic/ folder. The tmqm_* files are tmQM geometries (the comment line names the refcode), co_hexadentate_chelate.xyz is a GFN-FF structure from Architector, and mn2_co10_cod2103866.xyz comes from the COD. Blocks are trimmed to the relevant lines; the SHAPE and donor-distance lines are left out.

A Werner complex: co_hexadentate_chelate.xyz

Cobalt in an N2O4 donor set, declared charge -2.

  1 metal centre, 0 flagged for review
  Oxidation states are in the ionic model: each ligand at its closed-shell charge, the metal takes the rest, hydride as H-

  Co(+2, from the ionic model) · atom #1 · CN 6
      Trust in the state: high
        - 99.1% of similar benchmark complexes right (95% interval 98.6 to 99.5%); the closest group holds 1934
        - only the ionic model gave a state that counts: the bond-valence sum is closest to +2 but lands 0.88 from it, and a sum is a measurement within 0.25
      Configuration: d7
      Electron count: 19 electrons, odd: an open-shell complex, or a ligand charge is wrong
      Geometry: octahedral, 1.39 from ideal (clean)
      Ligand field (sigma-only model, units of e_sigma): t2g-like x2 at 0.06, t2g-like x1 at 0.29, eg-like x1 at 2.63, eg-like x1 at 3.00
        d7 high spin: 4/1/1/1 electrons per level, 3 unpaired, LFSE -2.29
        d7 low spin: 4/2/1/0 electrons per level, 1 unpaired, LFSE -5.00
        A model of the pattern, not a prediction: e_sigma is not estimated and neither spin state is chosen

The header gives the element, the state with its source, the atom id (1-based, as in the file) and the coordination number. The convention line above the first site is printed once.

Trust in the state: high with only the ionic model gave a state that counts means the bond-valence sum, the second method, did not confirm the state; the grade is still the benchmark’s (cobalt, six N and O donors, 99.1% right over 1,934 similar complexes), and the caution says what was not checked and why. Here the report’s Bond valence: line reads 2.88 over 6 bonds, closest to +2, and grades the fit as poor: a sum that far from the state it names is not counted as a second opinion. It is not evidence against the state either. Where no bond had parameters, the caution reads only the ionic model gave a state.

Configuration: d7 is the group number less the state, a bookkeeping count in the ionic model. The electron count is odd and the file declares no multiplicity, so the reading is odd (see below): Co(II) is d7 and open-shell, which is the expected result. The geometry line says the six donors sit close to an octahedron (clean). The ligand-field block gives the d levels a sigma-only model produces for this geometry, and fills them both ways because the model does not choose the spin state.

An organometallic 18-electron complex: tmqm_fohgeq.xyz

[CpFe(CO)2(NHC)]+, declared charge 1.

  Fe(+2, from the ionic model) · atom #1 · CN 4
      Trust in the state: low
        - 88.9% of similar benchmark complexes right (95% interval 85.7 to 91.5%); the closest group holds 434
        - only the ionic model gave a state that counts: the bond-valence sum is closest to +3 but lands 0.36 from it, and a sum is a measurement within 0.25
      Configuration: d6
      Electron count: 18 electrons
      Hapto ligand: η5-Cp, 1.853 A from the metal
      Geometry: tetrahedral, 3.04 from ideal (drifted)
      Buried volume: 86.8% of a 3.5 A sphere on the metal (Bondi radii x1.17, hydrogens left out); cone angles exact, Bondi radii, hydrogens in
        ligand bound at #6: 27.7%, cone angle 179.4°
        ligand bound at #37, #39 and 3 more: 38.4%, cone angle 167.1°
        ligand bound at #47: 18.4%, cone angle 152.0°
        ligand bound at #48: 18.4%, cone angle 151.8°
      Ligand field: not made, a hapto ligand is a π ligand, not a set of σ donors

The Cp counts as one site, so the iron is four-coordinate (Cp, two CO, the carbene) and the geometry is judged on those four. The count is the ionic-model total: d6 plus two electrons from each lone donor plus six from the Cp anion. The ligand-field picture is declined for a hapto ligand. The buried volume is the carbene’s 27.7%, the Cp’s 38.4% and each CO’s 18.4%, and each ligand’s exact cone angle follows its share (below).

The grade comes from the organometallic benchmark, and it is low for its group, not for this complex. A group of iron with one Cp (hapto: [5] in trust.features), carbon among the donors and the two methods disagreeing is not printed, nor is iron with eight or more bonds and the methods disagreeing, so the grade is read from the broader group named by level, iron with the methods disagreeing, which the table prints as 384 to 386 of its 434 complexes right. Ferrocene’s own group, two Cp rings, is withheld too: the table leaves out rows a reader of its earlier versions could combine to learn a group’s outcome, and ferrocene is graded from the same 434 and is low.

An actinyl: uo2_no3_2_h2o2_cod4344223.xyz

UO2(NO3)2(H2O)2, uranyl nitrate dihydrate from the COD (4344223), neutral.

  U(+6, from the ionic model) · atom #5 · CN 8
      Trust in the state: high
        - 99.1% of similar benchmark complexes right (95% interval 88.6 to 99.9%); the closest group holds 25
      Configuration: f0
      Electron count: 20 electrons; no electron-count rule applies to an f-block metal
      Geometry: hexagonal bipyramidal, 0.39 from ideal (clean)
        (the oxo groups were drawn out to the mean equatorial distance for this verdict, so their multiple bond is not read as distortion; the SHAPE numbers below are the geometry as it is)
      Equatorial girdle: 6 donors at a mean 2.492 A, within 0.06 A of the plane normal to the O=M=O axis
      Ligand field: not made, an f-block metal: spin-orbit coupling dominates and the d-orbital model does not apply
      Bond valence: 6.06 over 8 bonds, closest to +6 (consistent)

The two oxygens at 1.753 Å, opposite each other, are the uranyl’s oxo groups, and the shape is judged with them drawn out to the equatorial distance, so their short multiple bonds are not read as distortion. Round the O=U=O axis the two waters and the two bidentate nitrates make a girdle of six oxygens at a mean 2.492 Å, against the 2.47 Å six-coordinate U(VI) girdles average, flat to within 0.06 Å. The bond-valence sum agrees with the ionic model, at 6.06, and the grade is high: of 25 similar uranyl complexes in the f-block benchmark, both methods agreeing over eight oxygens, the table prints 24 or 25 right (accuracy, the f block). An actinyl gets no free-ion line (below); a lanthanide does.

CpW(CO)2(η²-SCNMe2), a thiocarbamoyl.

  W(+2, from the ionic model) · atom #1 · CN 4
      Trust in the state: moderate
        - 97.0% of similar benchmark complexes right (95% interval 96.2 to 97.7%); the closest group holds 2122
        - only the ionic model gave a state
      Configuration: d4
      Electron count: 16 or 18 electrons: atom #2 is within bonding distance of the metal but sits behind donor #8 at an M-D-X angle of 88°, so it was read as a 1-3 contact; bound side-on it adds two electrons, and the geometry does not settle which (the CSD bonds 30 to 70% of those at 80° or more)

The sulfur sits close enough to tungsten that it may be bound side-on. If it is, the count is 18; if not, 16. The report makes the count on one reading and gives the other. In the JSON this is reading: "unsettled":

"electron_count": {
  "total": 16,
  "reading": "unsettled",
  "unsettled": {
    "alternatives": [18],
    "reason": "atom #2 is within bonding distance of the metal but sits behind donor #8 ..."
  }
}

A ruthenium arene complex of a B10 cage, declared charge -1.

  Ru(+2, from the ionic model) · atom #1 · CN 5
      Trust in the state: moderate
        - 98.1% of similar benchmark complexes right (95% interval 97.3 to 98.7%); the closest group holds 1673
        - only the ionic model gave a state that counts: the bond-valence sum is closest to +4 but covers 2 of the metal's 10 bonds, the others having no parameters
        - the boron cage was charged from the cluster it forms with the metal, which counts the metal fragment as two skeletal electrons, and this state follows from that charge; the cluster's edge count is consistent with the class but is not a structure determination, so the state is provisional and its grade is held at moderate at most
      Configuration: d6
      Electron count: 18 electrons; the boron cage through atom #16 was charged from the cluster it forms with the metal, whose other ligands leave it two skeletal electrons as a BH has, so the cage is one class beyond the cluster's and not the smallest class that holds its own electrons; the cluster's edge count is consistent with that class, and the reading is provisional
      Hapto ligand: η6-arene

The second caution is cluster_charge. The relevant JSON:

"oxidation_state": 2,
"oxidation_state_source": "ionic_model",
"valence_electrons": { "count": 6, "shell": "d" },
"trust": {
  "confidence": "moderate",
  "cautions": [
    { "kind": "one_method", "message": "only the ionic model gave a state that counts: the bond-valence sum is closest to +4 but covers 2 of the metal's 10 bonds, ...", "ligands": [] },
    { "kind": "cluster_charge", "message": "the boron cage was charged from the cluster ...", "ligands": [] }
  ],
  "convention": "ionic model: each ligand at its closed-shell charge, the metal takes the rest, hydride as H-"
},
"electron_count": {
  "total": 18,
  "oxidation_state": 2,
  "shell": "d",
  "shell_electrons": 6,
  "reading": "eighteen",
  "unsettled": { "alternatives": [], "reason": "the boron cage through atom #16 was charged from the cluster ..." }
}

unsettled with an empty alternatives means the count was made on one stated assumption and no other total is offered. The reading here is still eighteen. The assumption is the cluster reading of the cage, which set both the cage’s charge and the metal’s +2, so a different reading of the cage would move both. See metallaboranes.

A platinum or nickel phosphine fragment on a cage is counted the same way. tmqm_aquhoj.xyz, a platinaphosphadicarbaborane, reads Pt(+2) at 18 electrons with the same cluster_charge caution; its authors (Hong et al., J. Am. Chem. Soc. 2003, 125, 16058) give it as a Pt(II) complex of the cage dianion and predict 26 skeletal electrons for its nido structure. Until revision 24 the rule was withheld for these metals and it read Pt(0) at 20.

A scandium complex of two N,N’-dimesityl-1,4-diazabutadienes and an anilide.

  Sc(+3, from the ionic model) · atom #1 · CN 5
      Trust in the state: high
        - 99.2% of similar benchmark complexes right (95% interval 95.4 to 99.9%); the closest group holds 107
        - an alpha-diimine ligand is on the metal: neutral diimine, radical anion or ene-diamide 2-; the state is one of these readings; read the other ways the ionic model's state would be +2 or +4
        - an alpha-diimine ligand is on the metal: neutral diimine, radical anion or ene-diamide 2-; the state is one of these readings; read the other ways the ionic model's state would be +2 or +4
      Configuration: d0
      Diazadiene ligand (#117, #118): metrical oxidation state -1.00, semi-iminato, radical monoanion
      Diazadiene ligand (#119, #120): metrical oxidation state -0.90, semi-iminato, radical monoanion

The two ligands have the same bond lengths, C-N 1.33 to 1.34 Å and C-C 1.39 Å, between the neutral diimine’s (C=N about 1.28, C-C about 1.49) and the enediamide’s, and their metrical oxidation states read both as radical monoanions. Each is charged -1, so the complex is Sc(III), d0, with two ligand radicals. The ionic model alone has only the closed-shell forms, neutral or dianion, and until identifier revision 39 it charged these two identical ligands 0 and -2: the same Sc(III), but the charge on the wrong ligands, an identical_ligands_differ caution on the site, and an InChI charge layer of /q;-2;-1;+3 where it is now /q3*-1;+3.

Bis(benzosemiquinonediimine)platinum(II), two identical ligands made from o-phenylenediamine.

  Pt(+2, from bond valence) · atom #1 · CN 4
      Trust in the state: low
        - 73.1% of similar benchmark complexes right (95% interval 64.4 to 80.3%); the closest group holds 107
        - the ionic model gives 0, which it also gives where it cannot divide the charge, and a bond-valence sum gives +2: +2 is reported. Where the ionic model left a CSD complex at 0, the compound name almost never agreed with 0, and the sum's state usually matched. If 0 is right, say so with --oxidation-state
        - ligands with the same atoms and bonding were given different charges (+0, -2); that is suspicious, since such ligands usually carry the same charge, though ligand-based mixed valence is a real exception; in a CSD benchmark a state it marks was wrong far more often than one it does not
      Configuration: d8
      Electron count: 16 electrons, d8: the usual count for a square-planar centre

The two ligands are the same, and the reading charges one 0 and the other -2. The ionic model read both neutral and the platinum at 0; the bond-valence sum says +2, and the reconciled reading puts the two charges on one ligand, so identical_ligands_differ is raised and the identifiers carry the same split (/q;-2;+2). The usual description is Pt(II) with two radical-anion ligands, a reading no closed-shell charge assignment can give. Orbitron reads a dioxolene’s and a diazadiene’s level from their bond lengths, and a dithiolene’s from its C=C; it has no such calibration for this N,N ligand.

A neutral nickel bis(dithiolene) is the other standard example, and it is no longer marked: both ligands’ C=C are under 1.40 Å, so both are ene-dithiolates, the ionic model reads Ni(IV), and the bond-valence sum’s Ni(II) is reported (tmqm_icihor.xyz).

The caution is a prompt to look, not proof that one charge is wrong: identical connectivity does not force identical charge. Ligand-based mixed valence is the standing counterexample, for instance a chromium(III) complex holding a semiquinonate and a catecholate of the same framework (Chang, Mochizuki and Kitagawa, Inorg. Chem. 2002, doi:10.1021/ic025643p). Of the CSD complexes it marks, about a third have a wrong state; the state itself may still be right.

A copy of tmqm_fohgeq.xyz with its comment line replaced by no charge declared:

  Fe(state unknown) · atom #1 · CN 4
      Trust in the state: no state to grade
      Electron count: not made, the file declares no total charge, so the ligands' charges cannot be divided from the metal's
      Hapto ligand: η5-Cp
      Ligand field: not made, no oxidation state, so no d count

The coordination half of the report is unchanged. The JSON has oxidation_state_source: "none", trust.confidence: "none" and electron_count: {"declined": "..."}. The oxidation_state field reads 0 there, and the source is what says that 0 is not a state; check the source before using the number in a script.

mn2_co10_cod2103866.xyz, Mn2(CO)10, shows a decline for a different reason: each manganese reads Mn(+0, from the ionic model), d7, and then Electron count: not made, bonded to another metal, directly or through a ligand. Both sites are bridged and neither gets a ligand-field picture.

Reading each part

The oxidation state and where it came from

The state is in the ionic model. Each ligand is taken at its closed-shell charge (chloride 1-, water 0, a phosphine 0, a hydride as H-, a cyclopentadienyl 1-), and the metal takes what is left of the declared charge. It is a bookkeeping convention that tells you the charge assigned to the metal, not where the electrons are. The report prints the convention once, and --json carries it as trust.convention.

The state comes from the first of these that answers, and oxidation_state_source says which:

oxidation_state_source Source
given --oxidation-state on the command line
stated the file: a CIF _atom_type_oxidation_number or Fe3+ type symbol
formal_charge a nonzero formal charge on the metal atom, including a single-atom ion’s charge from a PDB FORMUL record or an mmCIF _chem_comp.formula
ionic_model the ionic model, from the declared total charge
bond_valence a bond-valence sum over every bond the metal has
element the element’s one state in practice (alkali and alkaline-earth metals, Zn, Cd, group 3 and 13, most lanthanides, Th)
coordination the state the element takes at this coordination number, replacing a state the donors cannot carry
none nothing answered

The order has exceptions, all written into the trust cautions below. The ionic model comes before the bond-valence sum when the charge is declared, but a consistent sum replaces an ionic-model state of 0, or a state the element is almost never found at, and a state the donor count cannot carry is replaced by the one the element takes there. In each case the report says so. The full rules and their evidence are on the accuracy page.

The trust grade

The grade is how often the state the program reports was right for complexes like this one. It was measured: the reported state was scored against the Roman numeral in the compound name of 67,315 mononuclear CSD complexes, 64,104 of the d block and 3,211 lanthanides and actinides, and the complexes were grouped by what the program knows of each metal (the element, where the state came from, whether the ionic model and a bond-valence sum agree, how many bonds the metal has and what is at the end of them, and two flags about the ligands). A metal is graded from the group it falls in.

Grade Means
high at least 99% of the benchmark complexes like this one were right
moderate 95% to 99% were right
low fewer than 95% were right
uncalibrated no benchmark describes this metal, and trust.calibration.domain says why: it is bonded to another metal, sits in a structure with a unit cell, has no declared total charge, is an element the benchmark has too few complexes of, or has a metal-carbon bond on an element with too few organometallics (metal_carbon_bond)
as_stated you gave the state, or the file states it. Nothing was computed, so this does not grade correctness
none there is no state

A cap for cages. A state read from a boron cage’s cluster with the metal (the cluster_charge caution) is held at moderate at most, whatever its stratum gives. The benchmark is mononuclear Werner complexes and a cage is outside it: the stratum such a metal lands in (platinum or nickel with N and P donors) describes the metal and its other ligands and says nothing about whether the cage was charged right, however many complexes it holds (3,038 for PEDROF). Only high is lowered; low stays low, and uncalibrated and as_stated are not grades of this kind. trust.calibration still reports the stratum’s own accuracy and size.

A metal with one oxidation state in practice (zinc, cadmium, scandium, most lanthanides and the like), reported at that state, is graded by its element across the benchmark, whatever its surroundings, and is fixed_state in trust.calibration.domain. Not with a metal-carbon bond: under bulky Cp ligands a lanthanide that is Ln(III) in every Werner complex can be Ln(II), so an organometallic is graded by its group in the organometallic table like any other.

An organometallic is graded from a second table of the same groups, counted over 27,589 CSD organometallics whose names state the metal’s state, and is organometallic in trust.calibration.domain. The Werner complexes are not taken to describe organometallics, whose sites and errors differ. The organometallic table covers 37 elements; accuracy has its held-out scores.

trust.calibration carries the evidence: accuracy (the share right for the group, to three decimals), complexes (how many benchmark complexes the narrowest group large enough to report holds) and level (what that group is made of). A group is reported only with at least 10 complexes from 3 CSD entries; a narrower one is not printed and the estimate is read from the next broader group. Nor does the table say exactly how many of a group’s complexes were right. It gives a block of two or three counts, the less common outcome’s count rounded down to an even number and the next (three at the middle of an even-sized group; above 400 complexes one count more per 200), so a group of 25 all right and one with a single wrong state both read 24 or 25 right, and the program takes the count it expects in the block given the broader group. No group, however small, is printed as all right or all wrong, and no complex’s outcome can be worked out from the table. Where no group of the site’s kind is that large, the line reads no group of similar complexes is large enough to report, the accuracy is the benchmark’s overall one, and complexes is 0. trust.features carries what the grade was made from. Its bond_valence_state is the state a bond-valence sum is nearest, however poorly the sum fits, since that is what the table was fitted on; identify’s field of the same name is given only for a consistent sum (below). The grade does not see what it cannot recognise, and it measures agreement with the compound names, which for a ligand with more than one reading is a convention; the cautions below are the program saying what it saw, and do not set the grade.

A bond-valence sum counts as a second method only when it is consistent: within 0.25 of the state it names, over every bond the metal has, with parameters for every candidate state. The Bond valence: line grades its own fit as consistent, approximate or poor fit.

A low grade is not a rejected state. It means this site is the one to look at. Each grade comes with cautions, and the kind of each is one of these:

kind Meaning
methods_disagree the ionic model and the bond-valence sum give different states; both are named
one_method only the ionic model (or only the sum) gave a state; where the sum named one that is not a measurement, the sentence says why: it leaves out bonds it has no parameters for, lands more than 0.25 from its own state, or could not compare another state
odd_electrons the count is odd on a file that declares a closed shell, so the division of charge is wrong somewhere
unresolved the ionic model could not divide the charge between ligands and metal
unusual_state the state is not one usually named for this element; the usual set is listed in the message
bond_valence_fallback the ionic model gave 0, or +1 on iron or manganese with no pi-acceptor, or a state the element is almost never named at, and a sum gave a usual one, which is reported. --oxidation-state overrides it
coordination_prior the computed state is one this coordination number rules out, so the state the element takes there is reported: four-coordinate Pd or Pt at +4 becomes +2, two- or three-coordinate Au at +3 becomes Au(I), and copper that a bond-valence sum puts at +1 over nitrogen and oxygen donors alone becomes Cu(II)
non_innocent_ligand a ligand with more than one closed-shell reading is on the metal; the state is one of its readings, and the sentence ends with the state each other reading would give
cluster_charge a boron cage was charged from the cluster it forms with the metal; the state is provisional
identical_ligands_differ ligands with the same atoms and bonding were given different charges

cluster_charge and identical_ligands_differ are the two cautions that mark a state as provisional where there is no alternative state to show it. A stated state does not clear them. Neither sets the grade: that is the benchmark’s, and for a boron cage, an organometallic, the organometallic table’s, held at moderate at most. Each message gives the benchmark rate for what it flags.

Each caution also has ligands, the ligands it is about, so that two cautions of one kind with the same words can be told apart without reading the words. A non_innocent_ligand caution has one entry, {"atoms": [117, 118], "charge": 0}: the atoms that decide its class (a diimine’s two nitrogens, a nitroxide’s oxygen and nitrogen) and the charge the reading gave the whole ligand. identical_ligands_differ has an entry for each ligand of the set, with every atom of the ligand and the charge it was given, {"atoms": [...], "charge": -2}. Every other caution is about the site as a whole and has an empty list. The ids are the scene’s own, the ones metal_states[].atom and --select ids(...) use, counted from 1 in the order the input lists its atoms. They name atoms of this input, not a chemical identity that survives reordering the file.

The d or f configuration

Configuration: d6 is the count the ionic model implies: the metal’s group less its state, or the f count for a lanthanide or actinide. In the JSON it is valence_electrons: {"shell": "d", "count": 6}. It is printed only where there is a state, and it follows the reported state, so a stated or replaced state changes it.

For an open f shell, Free ion: 8S7/2, g_J 2.000, 7.94 μB gives the Russell-Saunders ground term by Hund’s rules and the moment g_J √(J(J+1)) it implies (free_ion in the JSON). For a lanthanide(III) that is close to what is measured: its crystal field, about 100 cm⁻¹, is small against the spacing of its J levels. Two exceptions are noted where they apply, Sm(III) and Eu(III), whose excited J levels are populated at room temperature, so their complexes measure about 1.6 and 3.4 μB against 0.85 and 0. For an actinide the line is marked approximate: its coupling is intermediate and its crystal field exceeds kT, so the free-ion moment is usually not what is measured, 5f⁷ excepted. A closed shell (f⁰, f¹⁴) and an actinyl get no line: an actinyl’s two oxo groups set an axial field the free ion does not describe.

The electron count

The count is the valence electron total in the ionic model: the metal’s d (or f) count, two electrons for each lone donor whether neutral or anionic, and the extra electrons a multiple-bonded or hapto ligand supplies (four for an oxo or bent imido, six for a nitride or linear imido, a hapto ligand’s pi electrons). The count starts from the ionic division of the declared charge, with three exceptions. Where a bond-valence sum or the coordination number replaced the ionic state and every donor is a lone one, the count is made at the reported state, since each lone donor gives two electrons whatever its charge. Where no reading of the ligands reaches the reported state and the donors are not all lone ones, the count stays at the ionic state and the difference is named. And for a metal with one state in practice, where the ionic model could not divide the charge and every donor is one atom, each donor counts two. When a stated or replaced state differs, electron_count.oxidation_state says which state the count used; with --oxidation-state 3 on the iron complex above, the report gives state +3, d5, and a count of 18 made at +2.

The reading says what the number means:

reading Meaning
eighteen 18 electrons
sixteen_d8 16 on a d8 centre, the usual square-planar count
under_eighteen an even count under 18: common for early metals and bulky ligands
over_eighteen over 18 with a carbon on the metal: a hapticity or a ligand charge is likely wrong, or pi donors offer more pairs than the metal has orbitals for
over_eighteen_werner over 18 with no carbon on the metal; octahedral Ni(II) is 20, and the 18-electron rule does not apply
odd_on_closed_shell odd on a file that declares an odd multiplicity (an even number of electrons): a ligand charge or the state is wrong
odd odd, and the file declares no multiplicity or an even one: an open-shell complex, or a wrong charge
ligand_radical odd on the metal and its closed-shell donors, and made even by the unpaired electrons of ligands read as radicals (an open-shell metal coupled to them)
filled_d_shell d10 on a group 11 or 12 metal (Cu(I), Ag(I), Au(I), Zn(II), Cd(II), Hg(II)): no 18-electron rule
f_block an f-block metal: no count rule applies
unsettled the total depends on a reading the geometry does not settle

Over 18 is flagged only where the metal has a carbon bond. A Werner complex over 18 is intended, not a warning.

unsettled and alternatives. The count is made on one reading and the other totals are listed in unsettled.alternatives; the text report prints them as 16 or 18 electrons, or 8 to 16 where there are several. The reason names the first thing unsettled. The causes are:

  • an atom within bonding distance behind a bound carbon or boron donor that may be bound side-on (the M-D-X angle in the reason helps: small angles are usually bound);
  • a hapto ligand whose bound atoms hold an odd number of pi electrons, so the pi system reaches past them (a slipped allyl or ring, a folded fulvene). A flat five-membered ring drawn as a fulvene, its exocyclic C=C to a carbon, is not one of these: it is counted as the Cp anion beside a carbocation (an amidinium, a tropylium), six electrons, as a ferrocenylcarbenium’s ring is. It counts as folded, a four-electron diene, where the carbon carrying the C=C sits more than 0.15 Å farther from the metal than the rest of the ring;
  • a B-H or Si-H hydrogen that may bind the metal;
  • a nitrosyl whose M-N-O angle is between 140 and 150 degrees, where NO+ and NO- differ by two in the metal’s state;
  • a boron cage bound at only three or four vertices, or larger than one polyhedron, where the next cage class moves the count by two.

With alternatives empty, unsettled names one assumption the count rests on, and no other total follows from it. These are a carbene with no heteroatom on it taken as neutral or as a dianion by its metal, a donor drawn at +1, ligand charges the ionic model could not divide on a metal with one state, a state replaced by a sum that no reading of the ligands reaches, a d0 metal whose pi donors offer more than 18 (counted as 18), and a boron cage charged from its cluster.

Neither an unsettled count nor a decline is an error. The unsettled totals are a range to compare against a reference, not a verdict.

Declines. A count is declined, with the reason in the report and as electron_count: {"declined": "..."} in the JSON, where there is nothing to count on:

  • the file declares no total charge;
  • the file states its own bond orders, which the ionic model would overwrite;
  • the structure is periodic (the count is made on a molecule);
  • the metal is bonded to another metal, directly or through a ligand, so bridging ligands and metal-metal bonds are shared by conventions this does not choose between;
  • the metal has no coordination sphere;
  • the ionic model could not divide the charge, on a metal with no single usual state;
  • the ionic model found no division and the geometry shows carbons off the metal with fewer neighbours than they need (usually missing hydrogens), so the ligands cannot be charged as whole molecules: the decline then says the file looks short of atoms;
  • the metal is not a d- or f-block metal at a state it can have;
  • a metallaborane whose skeletal-electron count does not fit.

The short-of-atoms message only relabels a count that was already declined. A file that is missing hydrogens but still divides into charged ligands is counted, and the count is wrong without any message, so check the hydrogens before you trust a count.

Non-innocent ligands

Eight ligand classes are recognised on a metal from the geometry and bonds, and the site carries a non_innocent_ligand caution, naming the ligand’s atoms, when one is there. The grade is the benchmark’s, and a state that is a convention can be high where the convention matches how the benchmark’s compounds were named. The grade is not lowered for the ligand; instead the caution says what the state would be under the ligand’s other readings (“read the other ways the ionic model’s state would be +4 or +5”). Where the reported state is a bond-valence sum’s that the ligands were read again to reach, the other states count from that state and say so (“the reported state would be +1 or +3”). Over the CSD benchmark on 2026-10-15, 304 of the 1,403 states this program read wrongly carried the caution and for 201 of them the compound name’s state was one it listed; it was on about 4.5% of the states read right:

Class Closed-shell readings the state may be one of
dithiolene neutral dithioketone, radical anion or ene-dithiolate 2-
dioxolene (catechol, o-amidophenolate) neutral quinone, semiquinonate 1- or catecholate 2-
acyclic α-diimine neutral diimine, radical anion or ene-diamide 2-
nitroxide neutral radical or hydroxylamide 1-
nitrosyl NO+ (linear), neutral NO or NO- (bent)
verdazyl verdazylium 1+, neutral radical or verdazylide 1-
flavin (isoalloxazine, alloxazine) oxidised, semiquinone radical or reduced hydroquinone
η⁴ cyclobutadiene neutral cyclobutadiene or aromatic cyclobutadienide 2-

The ionic model reads a verdazyl as the neutral radical, and a cyclobutadiene as the aromatic 6π dianion, the closed-shell form it gives every carbocyclic π ring, as it reads a cyclopentadienyl as the anion: (η⁴-C4H4)Fe(CO)3 is Fe(II) (tmqm_furroz.xyz). Which reading a compound name follows depends on the metal: the CSD names CpCo(η⁴-C4R4) Co(III), the dianion, for 86 of its 113 cobalt entries, and (η⁴-C4R4)PtX2 Pt(II), the neutral ring, which Orbitron reads Pt(IV) with Pt(II) in the caution (tmqm_zahjat.xyz). A fulvene bound by its ring and its exocyclic carbon on a group 3 to 5 metal, a tucked-in Cp, is read from that exocyclic bond: at 1.40 Å or longer, a single bond’s length, it is the η⁵:η¹ dianion, a cyclopentadienyl and a carbanion, and the metal Ti(IV), Zr(IV) or Ta(V) as the CSD names them (tmqm_eboyez.xyz); a later metal’s η⁶ fulvene, its exocyclic bond shorter, stays neutral (tmqm_wilsuh.xyz). An alkyne side-on to one metal of groups 4 to 9 is the neutral ligand, as the CSD names count it, though back-donation draws its C-C out to 1.27-1.36 Å: CpV(η²-PhC≡CPh)(PMe3)2 is V(I) (tmqm_jerceo.xyz). On a group 10 metal it stays the dianion, a metallacyclopropene, as the names there mostly count it: a platinum hexafluorobutyne is Pt(II) (tmqm_fbupta.xyz). An η² alkene is read from its C-C length. A flavin’s three readings are one electron apart, and their charges depend on the protons on its ring nitrogens: with none beyond the oxidised parent’s two (riboflavin’s N3-H and N10-ribityl) they are 0, -1 and -2, and each further proton moves all three up by one.

Recognition is conservative. A radical ligand outside these eight is not recognised, so a moderate or high grade on a structure with an unusual redox-active ligand is not a clearance.

A chelating catecholate or N-aryl 2-amidophenoxide on a d-block metal gets more than a flag. Its redox level is read from its bond lengths as a metrical oxidation state (Brown, Inorg. Chem. 2012, 51, 1251): 0 for a quinone, -1 for a radical semiquinonate, -2 for the dianion. Where it is within 0.35 of -1 the ligand is charged -1 and the metal takes the rest. The report lists each such ligand:

  Cu(+2, from the ionic model) · atom #1 · CN 4
      Electron count: 17 electrons on the metal and its closed-shell donors, odd: with 1 ligand radical the complex is even-electron, an open-shell metal coupled to them
      Catecholate ligand (#6, #7): metrical oxidation state -1.15, semiquinonate, radical monoanion

(tmqm_batweb.xyz.) The odd 17 is the expected count for a Cu(II) coupled to a ligand radical, and the reading is ligand_radical. A chelating 1,4-diazadiene (R-N=C(R’)-C(R’)=N-R, with H or CH3 on the backbone) is read the same way from its C-N and C-C lengths (de Zwart et al., Inorg. Chem. 2021, 60, 3274), as a diimine, a semi-iminato radical anion or an enediamide dianion, and on a lanthanide, an actinide or a main-group or group 3 metal that reading decides its charge; on a d-block metal of groups 5 to 12 it is reported but the charge follows the ionic model, as accuracy explains. The JSON has the same information under redox_ligands (atoms, family, metrical_oxidation_state, reading). A metrical oxidation state between two integer states is reported as “between states: mixed valence, or pi bonding to the metal”, not rounded.

What the state means for these ligands

For a metal with a redox-active ligand, the oxidation state is a statement about how the electrons are shared between the metal and the ligand, and the structure does not fix that. Crabtree puts it this way: the oxidation state is “the charge that the metal would have on the ionic model”, a formal classification that does not give the real charge on the metal; where several resonance forms contribute comparably “it is therefore necessary to specify the resonance form to which the formal oxidation state applies”, the neutral free-state form of the ligand being the usual choice; and an electron can sit on an easily reduced ligand instead of the metal, as in a ruthenium complex that looks like a 19-electron Ru(I) and is, by EPR, an 18-electron Ru(II) with a ligand radical anion (The Organometallic Chemistry of the Transition Metals, 4th ed., 2005, §2.4, pp. 39-40).

Orbitron states its form. Every ligand is read at its closed-shell charge, which is the convention printed above the sites, except a ligand its own bond lengths place within 0.35 of a radical level, which is read as the radical. A ligand between two levels is reported between them. The same ligand can therefore carry a different state in a paper whose authors chose another form, and the benchmark shows it: states for complexes with a recognised non-innocent ligand match the CSD compound name 90.1% of the time against 98.1% for the rest, and the misses run in both directions (the reported state one or two too high in 19 of 32 sites with a recognised radical ligand and too low in 13).

The electron count follows the form, because moving an electron between the metal and the ligand changes the metal’s own count by one, as Crabtree’s 19- and 18-electron ruthenium does. tmqm_hanboq.xyz, a copper with an iminosemiquinonate, read as Cu(II) with a ligand radical counts 17 on the metal and its closed-shell donors plus one ligand radical; stated as Cu(I) with the ligand neutral it counts 18 and no radical. This is why ligand_radicals is reported beside the total. What does not change with the form is the formal charge and the ligand’s geometry, so those are the things to check first when a state disagrees with a paper.

Metallaboranes

A borane or carborane cage is not a set of ordinary atoms with ordinary valences, and the ionic model cannot charge it vertex by vertex. Orbitron charges a cage by counting its skeletal electron pairs, as Wade’s rules do: a closo cage of n vertices needs n + 1 pairs, a nido cage n + 2, an arachno cage n + 3. The cage is charged as the smallest class that holds its own electrons, and the charge is the shortfall, one to three units, carried on the vertices nearest the metal (carbon first). The class is not read from the cage’s shape alone. The one place the shape is asked is the cluster rule below, where it is a filter.

A cage the metal does not touch, or touches by one or two sigma bonds and no more than two face contacts, is a free or exo-bonded ligand. A cage bound over a face is a nido or larger ligand with the metal as the missing vertex. A closo cage of nine to twelve vertices bound over a face keeps every vertex and is the closo dianion.

The reading is provisional in two situations:

  • A cage charged from its cluster with the metal (cluster_charge). When a cage is bound over a face, the metal fragment, whose other ligands leave it two skeletal electrons as a BH has, is counted into the cluster, and the cage is charged for the class the cluster implies instead of the smallest class that holds its own electrons. The cage then carries more negative charge, so at the complex’s fixed total charge the metal has a higher oxidation state and the count fewer electrons (FEWRII goes from Ru(0) at 20 to Ru(II) at 18). The cluster’s edge count must be consistent with that class, but that is a filter on where the rule applies, not a structure determination. The site carries the cluster_charge caution (its grade is held at moderate at most) and the count carries an unsettled note with no alternatives (the Ru example above).
  • Nickel, palladium and platinum fragments. A d10 ML2 fragment is nonconical (Evans and Mingos, Organometallics 1983, 2, 435), and in two of the clusters the electron count says nido where the structure is arachno; the authors put that down to the pseudo-square-planar metal and still give each metal as M(II) with a dianionic cage and count the fragment as two electrons (Hong 2003, Kadlecek 2003, Bould 2017). The rule takes the charge from the count, not the class of the shape, so these fragments are treated like the others and read M(II) at 18 (AQUHOJ, VAFRAW and PEDROF at Pt(II), PEKTIL at Ni(II)). The reading is provisional and says so. Before revision 24 they kept the smallest class and read Pt(0) or Ni(0) at 20.

A cage bound at only three or four vertices, or larger than one polyhedron, is charged as the smallest class that holds its electrons, and the next class (two more electrons on the cage) leaves the metal’s state two higher and the count two lower, so both totals are given. A metallaborane whose electron count is odd, whose face is short by four or more, or whose metal is itself a vertex of a fused macropolyhedral cage is declined.

The coordination sphere

Every site lists its donors and compares them with the geometry and distances expected for the metal.

  • Donors and coordination number. A hapto ligand bound through several contiguous atoms is one site, so Cp2ZrCl2 is four-coordinate. Hapto ligands are named by hapticity and whether the atoms close a ring (η5-Cp, η6-arene).
  • Polyhedron. The donors are matched against SHAPE’s reference polyhedra for that coordination number. The Geometry: line names the best match and how far the sphere is from it (octahedral, 1.39 from ideal (clean)). The SHAPE (ML_n) line gives the continuous shape measure for every reference polyhedron with the metal counted as a vertex, which is the number a paper’s table quotes. At five donors the table also lists SHAPE’s spherical square pyramid (SPY-5, every donor on a sphere and the metal at their centroid, so the apex angle is 104.5°) beside the octahedron less a vertex (vOC-5, the metal in the base, which the Geometry: verdict uses). Two donors are measured with the metal, against the line, the V at 109.5° and the right angle; a two-coordinate copper, silver, gold or mercury is held to the line, and ferrocene, two η5-Cp sites, reads linear. An arsenic, antimony or bismuth(III), selenium or tellurium(IV), or germanium, tin or lead(II) centre without a boron donor is judged against the shapes its lone pair leaves: the right-angled pyramid (fvOC-3) at three, the seesaw (SS-4) at four and vOC-5 at five. The table lists fvOC-3 and SS-4 for every centre with three or four donors. The references are SHAPE’s own: at seven donors the pentagonal bipyramid, capped octahedron and capped trigonal prism; at eight the square antiprism, triangular dodecahedron, cube, hexagonal bipyramid and bicapped trigonal prism; at nine the tricapped trigonal prism, capped square antiprism, muffin and capped cube.
  • Shape path. A sphere between two shapes is placed on the minimal distortion path from one to the other, as a shape map draws it (Casanova et al., J. Am. Chem. Soc. 2004, 126, 1755): the Shape path: line takes the two references nearest by the ML_n measure and gives the path deviation, 0% on the path, and the generalized coordinate, 0% at the first shape and 100% at the second (Cp2ZrCl2: 13% of the way from T-4 to SP-4 (9.3% off the path)). Past 10% off the path, the limit Alvarez gives for reading a structure as in between (Eur. J. Inorg. Chem. 2021, doi 10.1002/ejic.202100500), the place along it means nothing and is left out. The JSON’s shape_path has from, to, separation_degrees (the angle between the two ideal shapes), deviation_percent and coordinate_percent (null past 10%). The pair is the two nearest references, ordered as SHAPE lists them, except at five donors, where it is always the trigonal bipyramid and the spherical square pyramid: that path is the Berry pseudorotation, 5.38 apart, and the coordinate is how far a sphere has come along it. A sphere on the path and at least 25% from each end is between the two shapes, and the desktop’s Snap and Clean leave it as built rather than snap it to either. Over tmQM that is 1,578 of 21,165 drifted spheres, 1,439 of them four-coordinate between the tetrahedron and the square.
  • Actinyl and vanadyl cores. The oxo groups of a yl ion are a multiple bond, 1.78 Å for An=O against equatorial contacts at 2.3 to 2.7, and a shape measure that compares positions would read that difference as distortion. For a site with oxo groups the verdict, shape and measure are made with the oxo groups drawn out along their own directions to the mean equatorial distance, oxo_scaled is true in the JSON and the text report says so, and the SHAPE rows keep the geometry as it is (what SHAPE gives for the same coordinates). A uranyl with every angle exactly 90 and 180 degrees measures 3.005 against the octahedron as it stands and 0 with the oxo groups drawn out. Three equatorial donors are needed to give the distance; fewer leave the measure as it was. The drift line then means the same for a yl ion as for any sphere (about 33 degrees of displacement of one donor, whether it is an equatorial donor tilted out of the plane or an oxo tilted off the axis). That is too loose for the axis, which is rigid: an actinyl is linear, “98% of all crystal structures have O=U=O angles in the range 174-180” (Katz, Morss, Edelstein and Fuger, 2006, p. 2400), so a two-oxo core reports oxo_angle_degrees and a core under 170 degrees marks the site for review, whatever its shape verdict says. In 879 CSD actinyls 15 (1.7%) are under 170. The range is in the report (oxo_review_range_degrees) because it belongs to the core: see the osmyl ion below. A two-oxo core also reports its equatorial donors as a girdle (equatorial_girdle): how many, their mean distance, and the furthest any lies from the plane through the metal normal to the axis. Four, five or six is usual, planar for four and five and sometimes puckered for six (Cotton, Lanthanide and Actinide Chemistry, 2006, ch. 11); U(VI) crystal structures average 2.29, 2.37 and 2.47 Å to them for four, five and six (Burns, Ewing and Hawthorne 1997, as plotted in Morss, Edelstein and Fuger, Fig. 28.4).
  • Cis-dioxo vanadium(V). A d0 metal with two terminal oxo groups puts them cis, at 105 to 110 degrees, because each oxo needs its own d-pi orbital and a trans pair would have to share one (Schindler, Hawthorne and Baur 2000; Winkler and Gray 2012). Of 292 mononuclear CSD vanadium complexes with two terminal oxo groups, 258 have five neighbours and 28 six. For V(V) the template is that cis-dioxo ion, five donors preferred and six at most, and an oxygen within 1.74 Å of the metal is read as an oxo group whose expected distance is 1.625 Å. The number of oxo groups is reported (oxo_found) and not compared with two, because vanadium(V) also carries one or three. The shape verdict is not made with the oxo groups drawn out, unlike an actinyl: the metal sits above the plane of the donors it binds, and drawing the short bond out moved 52 of 75 sites away from their reference shape. There is no bent-core check, because 105 degrees is the normal angle.
  • Oxo groups of the other metals. An oxygen bonded to the metal and to nothing else (no hydrogen, no carbon, no second metal: those are single bonds however short) and shorter than a limit that depends on the element is read as an oxo group whatever the oxidation state: Ti 1.72 Å, V 1.74, Cr 1.70, Mn and Fe 1.75, Nb 1.82, Mo, Tc, Ru, Ta, W, Re and Os 1.80. The limit is the minimum between the multiple-bond and single-bond populations of M-O distances in the CSD (mononuclear, ordered complexes: Mo 1,368, Re 1,033, W 329, Tc 118, Os 101). The distance it is compared with is a per-element M=O taken from the same complexes, and the donors list marks it oxo. The number found is oxo_found; it is expected to be a particular number only for the cores the template knows. Osmium(VI) is the one trans-dioxo ion the builder makes by default: 50 of the 62 CSD osmium(VI) complexes with two oxo groups are trans (the rest are four- and five-coordinate cis isomers), against 743 mono-oxo rhenium(V) to 21 trans-dioxo and 84 to 11 for technetium(V), which stay mono-oxo. A build that states two oxo groups gets them trans on those and on ruthenium(VI), at each ion’s own trans-dioxo M=O, which for rhenium and technetium is longer than the mono-oxo one. The trans osmyl ion is bent more than an actinyl (median 166 degrees over 49), so it is marked for review between 140 and 155 degrees, which leaves the cis isomers alone. Molybdenum(VI) and tungsten(VI) are the cis-dioxo ion (cis in 902 six-coordinate molybdenum complexes), molybdenum(V), rhenium(V) and technetium(V) mono-oxo. The drawing-out described above is used only where it makes the measure no worse. In 15 technetium(V) square pyramids it made 14 worse; in rhenium and technetium octahedra it improved 25 of 38. The bond is taken from the structure’s own bonds, so an oxo group is only as good as the hydrogens it was given: when a structure has no hydrogen atoms at all, a bare oxygen at a short distance cannot be told from an O-H whose hydrogen was left out, and the report sets oxo_by_distance_only and says so. A bridging oxygen makes the site bridged, which is not assessed. Chromium(V) is built as mono-oxo (Cr=O 1.57 Å) and chromium(VI) as the tetrahedral chromate (63 of 67 CSD complexes are four-coordinate). Titanium(IV), niobium(V) and tantalum(V) are recognised and not built with an oxo core, because only 1%, 27% and 3% of their mononuclear CSD complexes have one; a default would be wrong for the rest. notes/archive/oxo-metals.md has the share for every state a core exists for, including two that are minority classes (vanadium(V) cis-dioxo 30%, tungsten(VI) cis-dioxo 20%). Nothing is recognised for Co, Rh, Pd, Pt, Cu or Au: the CSD has no ordered mononuclear complex with a terminal oxo on them, the “oxo wall” of Winkler and Gray. notes/archive/oxo-metals.md has the table.
  • Verdict. clean is a close match, drifted a recognisable but distorted shape, no_clear_match means reference shapes exist and none fits, unrecognised means there is no reference for that donor count, too_few_donors is one donor, no_donors is nothing in bonding range, and bridged is a metal whose sphere is shared with another metal: bonded to it, or joined to it through a donor and at most two more atoms. A bridged metal is not assessed as a sphere of its own; a metal in its own pocket of a ligand that holds another is.
  • Donor distances. Each donor distance is compared with the tabulated metal-donor distance for that state (Shannon radii plus a radius per donor element, nitrogen’s 1.43 Å on a metal of groups 4 to 12 and 1.48 Å on any other, and CSD-measured radii where Shannon has none). An actinyl’s equatorial donors are compared 0.25 Å further out, since the actinide’s Shannon radius averages in its two short M=O bonds, and a mercury(II) chloride, bromide or iodide at mercury’s two-coordinate radius. This needs a state: without one the distances are reported without a comparison. Where fewer donors are found than the ion usually has, the report says so and compares at the usual number, except for nickel(II), copper(II), zinc(II) and mercury(II), whose usual number is the aqua ion’s six and whose crystals are mostly four-coordinate, and scandium(III), yttrium(III) and the lanthanides(III) without a hapto ligand, which crystallise well below their usual six, eight or nine: from four donors up their distances are compared at the number found, and with three or fewer at the usual number. Shannon has no radius below six for those last ions, so at four and five it is extended down along the slope of its own two lowest entries. Between two tabulated coordination numbers equally far below and above, the radius is their mean, except that a square-planar d8 ion or copper(I) with five donors reads its four-coordinate radius, its fifth contact being apical. A six-coordinate copper(II) or manganese(III) is compared against its Jahn-Teller octahedron, the two donors on its long axis 0.28 Å (Cu) or 0.13 Å (Mn) further out and the other four nearer. The nitrogen of a dinitrogen, nitrosyl or thionitrosyl binds through a multiple bond, about 0.23 Å inside an amine’s distance, and is compared with nothing: its row’s kind is dinitrogen, nitrosyl or thionitrosyl rather than donor, and the text report says so. A carbonyl’s, isocyanide’s or cyanide’s carbon is compared with a CSD-derived metal-carbon distance for its kind and metal rather than a radius sum, the longer one where another carbon is trans to it; its row’s kind is carbonyl, isocyanide or cyanide. Beside a hapto ligand it is compared with nothing, since a piano stool binds its carbonyls tighter than the centres the distances were measured on (about 0.055 Å on chromium, molybdenum and tungsten), and likewise on a metal with no measured distance. On a site with a non_innocent_ligand caution, the distances are compared at the reported state, which is one of the ligand’s readings. A site is marked [review] when it matches no reference shape, or when a donor is more than 0.5 Å from its tabulated value.
  • Bond valence. The sum over the site’s bonds and the state it is most consistent with, graded consistent, approximate or poor fit. It is also the second method behind the trust grade.
  • Agostic and anagostic contacts. A C-H close to the metal is listed under the distance and angle windows of Brookhart, Green and Parkin. An agostic-window contact on a d8 square-planar centre, or on a metal whose settled electron count is past 16, is reported as anagostic, and basis says which rule decided.

clean is a statement about shape, not about correctness. An unflagged too_few_donors or no_donors site has not been examined and is not approved.

Buried volume and cone angles

Buried volume is the percent buried volume, %V_bur, of Cavallo and co-workers: the share of a sphere about the metal that its ligands fill (Poater et al., Eur. J. Inorg. Chem. 2009, 1759; SambVca 2, Falivene et al., Organometallics 2016, 35, 2286). The conventions are the published ones, as MORFEUS implements them: a 3.5 Å sphere on the metal, Bondi radii scaled by 1.17, hydrogens and the metal left out, and the sphere sampled on a cubic grid of about 0.001 ų a point. The grid is MORFEUS’s own, and with the same radii the two agree on all 744 ligands and 227 whole spheres of the repository’s ionic fixtures to 0.005 of a percentage point.

The first figure is all the metal’s ligands together. Each line under it is one ligand alone, named by the atoms it binds through. A ligand is a connected set of non-metal atoms with an atom on the metal, so a counter-ion or a solvent molecule in the file is not counted. The JSON has buried_volume: percent, sphere_radius_angstrom, and ligands, each with its donors, its counted atoms (by id) and its percent.

Three things differ from a table in a paper:

  • The metal-ligand distance is the structure’s own. Many published values put the metal at a fixed 2.00 Å from an NHC carbon or 2.28 Å from a phosphorus so that ligands can be compared apart from the metal they were measured on. Here a ligand further from the metal buries less: a Cp ring is 41.4% in ferrocene and 32.5% in Cp2ZrCl2. analyze sterics --metal-ligand-distance puts each one-donor ligand at a fixed distance first (below).
  • Elements Bondi has no radius for take Alvarez’s. Boron, aluminium and most metals are missing from Bondi’s table. Alvarez’s (2013) value is used, scaled the same, and the report names the elements (Alvarez's for B, alvarez_radii_for). MORFEUS uses 2.0 Å there, so a boron, at 1.91 Å in Alvarez, differs between the two.
  • A structure with a unit cell has none. Its ligands are where the cell put them, not round the metal.

Each ligand line also gives the ligand’s exact cone angle (Bilbrey, Kazez, Locklin and Allen, J. Comput. Chem. 2013, 34, 1189): the smallest cone with its apex on the metal that holds every atom of the ligand, each a sphere of its van der Waals radius. It is Tolman’s cone angle made exact and defined for any ligand, asymmetric or chelating. As in the paper, the radii are Bondi’s unscaled and hydrogens are included, since a cone usually touches them. The JSON has cone_angles, one per ligand with its donors, degrees and the tangent_atoms the cone touches. MORFEUS’s own algorithm, given the same atoms and radii, agrees on all 741 ligands of the ionic fixtures to 0.01 of a degree.

A cone angle depends on the metal-ligand distance even more than a buried volume does. A carbonyl’s cone is its carbon’s own, 2 asin(1.70 / d), because the oxygen lies inside it: at Fe-C 1.73 Å that is 160°, where a table’s value for CO fixes a longer distance. Each of ferrocene’s Cp rings needs 182°, the cone tangent to all five carbons, and a chelate that wraps the metal can need more than 180°. A ligand of more than 200 atoms, a protein chain round a metal, has no cone angle.

Quadrants, octants, a fixed distance and the steric map

analyze sterics takes one metal’s buried volume apart the way SambVca 2 does, in MORFEUS’s frame, and plot steric-map draws the map:

orbitron analyze sterics complex.xyz --z-atoms 27,29,31,33,35 --xz-atoms 6
orbitron analyze sterics complex.xyz --metal-ligand-distance 2.28
orbitron plot steric-map complex.xyz --z-atoms 27,29,31,33,35 --xz-atoms 6 -o map.svg
  • The frame. The metal is at the origin and the centroid of --z-atoms on −z, so the ligand they belong to lies below and the side a substrate comes from is above. The centroid of --xz-atoms lies in the xz plane at +x; without it, the rotation is the smallest that takes the z direction there. --atom names the metal where the structure has several.
  • Quadrants and octants. NE (+x, +y), NW, SW and SE, each the share of its quarter of the sphere the ligands fill; the octants are numbered 0 to 7 as MORFEUS numbers them, the four with z > 0 first. The JSON has quadrants and octants in that order.
  • --metal-ligand-distance. Moves each ligand with one donor along its metal-donor line to that distance before anything is measured, as SambVca’s tables are made: 2.0 Å for an N-heterocyclic carbene, 2.28 Å for a phosphine. The cone angles are taken there too. A ligand with more than one donor stays where it is and is named (not_moved).
  • The steric map. Over the frame’s xy plane, the height z of the ligands’ surface highest above it, coloured from −3.5 to 3.5 Å, with each quadrant’s share in its corner. A point is drawn where that surface is above the plane or inside the sphere, as MORFEUS draws it.

CpFe(CO)2(Bpin) (tmqm_acohuz.xyz) looked down on from the side away from its Cp, the boryl’s boron in the xz plane:

Buried volume of Fe #1: 81.0% of a 3.5 A sphere (Bondi radii x1.17, hydrogens left out); cone angles exact, Bondi radii, hydrogens in
  ligand bound at #2: 18.4%, cone angle 156.9°
  ligand bound at #4: 18.5%, cone angle 159.6°
  ligand bound at #6: 24.9%, cone angle 167.3°
  ligand bound at #27, #29 and 3 more: 38.3%, cone angle 167.3°
Frame: z toward the metal from the centroid of atoms 27, 29, 31, 33, 35, x toward 6
  Quadrants: NE 83.0%  NW 81.1%  SW 72.0%  SE 88.0%
  Octants, z > 0: 0 (+,+,+) 83.3%  1 (-,+,+) 82.3%  2 (-,-,+) 67.2%  3 (+,-,+) 90.0%
  Octants, z < 0: 4 (+,-,-) 85.9%  5 (-,-,-) 76.7%  6 (-,+,-) 79.9%  7 (+,+,-) 82.8%

The same complex’s steric map: the two carbonyls and the boryl, the three lobes, rise toward the viewer; the Cp is below the plane.

MORFEUS 0.7.2, given the same frame and radii, gives these quadrant and octant values exactly, and over 89 of the ionic fixtures, each in a frame on its first donor, the two agree to 0.008 of a percentage point; its map, computed the same way, matches this one at every grid point. The whole sphere moves by a few hundredths with the frame (81.03% in the file’s own axes here), because the grid stays put while the atoms turn. The radii are the whole-sphere value’s, so bromine is Bondi’s 1.85 Å, where MORFEUS has 1.83.

The ligand-field picture

For a d1 to d9 centre with four to seven donors, analyze metal-sites and the Coordination readout give the d-orbital pattern a sigma-only angular overlap model produces for the donor geometry, and fill it. The levels are in units of e_σ, the σ-antibonding energy of one donor on a d orbital pointing at it, so an octahedron has Δo = 3 e_σ. Both the high-spin and the low-spin fillings are shown with their unpaired electrons, a model LFSE, and a Jahn-Teller flag where a partly filled degenerate level pulls the geometry.

It is a pattern, not an energy. It does not choose a spin state (e_σ is not estimated), leaves out pi effects and d-s mixing, and its LFSE is in model units, not a computed stabilization energy. For 4d and 5d metals the report says the low-spin reading is almost always the real one. It is declined, with the reason, for fewer than four or more than seven donors, an f-block metal, a hapto ligand, a periodic structure, no oxidation state, an oxo, imido, nitride or other multiply-bonded donor, a Z-type borane on the metal, and an electron count that is unsettled or was declined (other than for a missing total charge or bond orders taken from the file).

orbitron plot ligand-field FILE -o out.svg draws the same picture: both fillings side by side with the electrons as arrows and the centre, state and trust in the notes. --data out.csv writes the levels and each orbital’s electrons. With several centres, --atom N picks one. --orbitals sets the model beside the five d-dominant orbitals of a calculation. See CLI §4.3.4 for the flags. Without --height the figure is made tall enough for every electron’s arrow, up to six inches; past that, levels too close to draw an arrow between are named in the notes.

The Co(II) chelate above, co_hexadentate_chelate.xyz: a distorted octahedron splits t2g by 0.23 e_σ and eg by 0.36, and the d7 fills either way.

A square-planar Ni(II) within 0.01 of ideal (tmQM AZEREC): d(x²−y²) at 3 e_σ, d(z²) at 1, the rest at 0. The σ-only model puts d(z²) that high; d-s mixing lowers it in practice.

A square-planar Cu(II) (tmQM BATWEB), d9: the one hole is in the orbital pointing at the donors. High and low spin fill alike, so one filling is drawn.

scripts/generate-docs-figures.sh draws these three from the fixtures; rerun it after a change to the model.

What identify adds

orbitron identify FILE --json and orbitron.identify(scene) write the InChI, InChIKey, SMILES and formula, and the metal’s charge in each comes from the same state assignment. The response carries metal_states, one entry per metal:

Field Meaning
atom, element which metal
identifier_state the state the identifiers were written at
reported_state, reported_state_source the state analyze metal-sites reports, and where it came from
differs the two differ
reconciled the reported state was not the ionic model’s, and the ligands were read again with their charges allocated to give it, so the identifier carries it
supplied_state, inferred_state a state you stated, and what the structure gives without it
conflict the stated state differs from the inferred one
bond_valence_state a consistent sum’s state, for comparison
alternatives, ambiguous other states the evidence supports; ambiguous is true when none was stated and a metal is bound to both ends of an O-O unit (peroxide or two oxides)
side_on_dioxygen both ends of an O-O unit are bound to this metal (peroxide or two oxides), whether or not a state was stated
confidence, cautions, calibration the trust grade, cautions and benchmark coverage, as in analyze metal-sites; calibration is null for a stated or absent state

The response also has identifier_revision, which is bumped whenever a change to the ionic model or the writers can move the identifier of the same structure. Store it with any identifier you keep.

Five warning codes concern the oxidation state:

Code Raised when
identifier_state_differs the identifier carries the ionic model’s state and no reading of the ligands gives the reported one
supplied_state_conflict a state you stated differs from the one the structure gives
oxidation_state_ambiguous the coordinates do not decide between states and none was stated
cluster_charge a boron cage was charged from its cluster with the metal
identical_ligands_differ identical ligands were read at different charges

The last two do not change the identifiers. For tmqm_hxebcu.xyz, a copper complex where a bond-valence sum replaced the ionic model’s Cu(III):

The output of orbitron identify tmqm_hxebcu.xyz --json, condensed to the relevant fields:

reported_state: 2, reported_state_source: bond_valence, identifier_state: 3,
reconciled: false, differs: true, confidence: low
warning code: identifier_state_differs
inchi: InChI=1S/C6H2NOS.3BrH.Cu/c1-5-6(2-3-8)9-4-7-5;;;;/h1H2;3*1H;/q-1;;;;+3/p-3

The identifier says Cu(III) (the +3 in the charge layer) while the report says Cu(II). They disagree because no reading of the ligands reaches +2, so the identifier keeps the ionic model’s state and the warning says so.

Stating a state

A coordinate file cannot say what a metal’s oxidation state is. If you know it, state it:

orbitron analyze metal-sites complex.xyz --oxidation-state 3
orbitron identify complex.xyz --json --oxidation-state 1=5       # atom 1 at +5
scene = orb.with_oxidation_states(scene, {1: 5})

On analyze metal-sites, the state applies to every metal and the site is graded as_stated (source given). The distance comparison, the configuration and the ligand-field picture then use it. The electron count is still made at the ionic-model division of the file’s charge, and electron_count.oxidation_state says which state it used. A cluster-charged boron cage keeps its cluster_charge caution when the state is stated.

On identify, the ligands are read toward the given state where they can reach it, and the identifier then carries it. Its source is given, as on analyze metal-sites; a state the file itself states, a CIF’s Fe3+, is stated, and where both are there the caller’s is used. For the copper complex above, with --oxidation-state 4=3 (condensed from the JSON):

reported_state: 3, reported_state_source: given, identifier_state: 3,
supplied_state: 3, inferred_state: 3, differs: false, conflict: false,
confidence: as_stated
no oxidation-state warnings

A state the ligands contradict is not forced. For tmqm_fohgeq.xyz stated at +3 with --oxidation-state 1=3 (the structure gives +2):

reported_state: 3, identifier_state: 2, supplied_state: 3, inferred_state: 2,
conflict: true, differs: true, alternatives: [3], confidence: as_stated
warning codes: identifier_state_differs, supplied_state_conflict

The identifier keeps +2, both warnings appear, and the stated state is held apart. Treat that as information: either the state is wrong, the charge is wrong, or a ligand is not what the connectivity says.

Use a stated state when:

  • a bond_valence_fallback or coordination_prior caution replaced a state you have reason to think is right (the message names the flag to use);
  • the grade is low and you know the chemistry;
  • the file has no declared charge and you know the state;
  • you are building identifiers for a database and want them to carry the state from the literature. Check conflict afterwards.

A stated state is a claim you make. The grade as_stated says that nothing was checked.

When to doubt a result

A reported state is a convention applied to a geometry. Go back to the structure when any of these holds:

  • The grade is low, or any of methods_disagree, unusual_state, bond_valence_fallback, odd_electrons is in the cautions. Take the state as a lead, not as an answer.
  • The count is odd_on_closed_shell. The charge was divided wrongly somewhere, or a ligand is a radical.
  • A ligand you know to be redox-active is not one of the eight classes. The recognition is conservative on purpose: a dithiocarbamate, an ethane-dithiolate, a ring nitrogen on bipyridine and an N-oxide are not flagged. A high or moderate grade does not clear such a ligand.
  • There is a metal-metal bond or a bridging ligand. The count is declined and the sphere is not assessed. A multinuclear complex has no per-metal state this convention can choose.
  • The compound is a cluster, a metallaborane, or any structure where the metal is part of a delocalised framework. cluster_charge and unsettled are there to flag it.
  • The report carries a fragmented_scene warning. Bond inference found more than one disconnected piece in a molecular file (a periodic cell or a biopolymer is exempt), the same warning identify and info give and with the same words. A ligand atom left behind by a missed bond is the commonest way the ionic reading goes wrong, because the metal’s sphere looks fine around what is left. A counter-ion or a solvent molecule in the file is a piece of its own and raises it too; read it as a check on the file in that case, not a fault. When a piece is one to three carbons and nothing else (a methyl, a methylene, a lone carbon), the message says so and that a bond to the rest of the molecule was probably missed: over the CSD Werner complexes that fragment, those with such a piece are wrong in their oxidation state 35% of the time (20 of 57) against 1.8% for the other fragmented ones. It is in the JSON warnings and on stderr; identify, smiles, inchi and info give the same message.
  • Your geometry is not the benchmark’s. The grades were calibrated on experimental CSD structures, and the identifier checks use tmQM’s GFN2-xTB geometries. A grade describes the method on those sets, not your file. Missing hydrogens and missing counter-ions change the charge division. A file short of hydrogens is sometimes declined with a message to that effect, but not reliably: a count made from an incomplete file can look normal.
  • The state is going into a paper. It is a bookkeeping convention. A paper’s oxidation state is a claim from spectroscopy or a reference compound, and a state from this tool is not a measurement of where the electrons are.
  • The ligand-field block is used as an energy. It is a pattern for the geometry.

For how often the reported state agrees with the name of the compound, and by metal and ligand family, see Metal sites: accuracy and limits. The short statement of the limits is in Scope and known limits.