Metal sites: accuracy and limits

orbitron analyze metal-sites and the Coordination section of the desktop’s Scene Info panel report an oxidation state, a d-electron configuration, an electron count and, for d1 to d9 centres, a ligand-field picture. The Python bridge has none of these; its one route to a metal’s state is orbitron.identify(...)["metal_states"], which gives the state the identifier was written at beside the reported one. This page says how often the state is right, what each site’s trust grade means, and what the tool declines to say. Read it before quoting a number from a paper-bound structure. For what each part of a report is and how to read it, see Metal sites; for how each step works and the papers behind it, see the developer guide.

4.1 What an oxidation state means here

Oxidation states are assigned in the ionic model: each ligand is taken at its closed-shell charge (chloride 1-, water 0, an amine 0, a hydride H⁻, a porphyrin 2-), and the metal takes whatever charge is left of the complex’s declared total. It is a bookkeeping convention, not a measurement of where the electrons are. Every report states it, and --json carries it per site as trust.convention.

Where a ligand has more than one closed-shell reading (a catecholate can be a quinone, a semiquinone or a catecholate) the convention picks one and the site is marked. See non-innocent ligands below.

The state comes from the first of these that answers:

--oxidation-state, when you give it;
a state the file states (a CIF _atom_type_oxidation_number, a PDB FORMUL ion charge);
a formal charge on the metal;
the ionic model, which needs the file to declare a total charge;
a bond-valence sum over every bond the metal has, when that is consistent.
the element’s one state, for a metal that has only one in practice (the alkali and alkaline-earth metals, Zn, Cd, group 3 and 13, most lanthanides, Th), where nothing above answered. It is graded high with an unresolved caution, since the ligands’ charges did not divide.

An ionic-model state of 0 yields to a consistent bond-valence sum, because 0 is the answer the model gives when it has failed to divide the charge. In a sphere of lone-pair donors with no metal-carbon, -hydrogen, -boron or -silicon bond (and not four phosphines or a dinitrogen) it yields to a complete sum, consistent or not; a state of 0 is where organometallic and zero-valent phosphine complexes are right. So does a state the element is almost never named at (Cu(IV), Co(VI), Ni(IV)), where the sum gives one it usually is; the report says so with a bond_valence_fallback caution. See when the ionic state is one the element almost never takes.

4.2 How often it is right

The benchmark is the Werner subset of the Cambridge Structural Database, after Reeves, Wood and Parsons (Acta Cryst. B 2019, 75, 1096): entries whose compound name gives a transition metal a Roman numeral, with no metal-carbon bond, nitrosyl, metal-ligand multiple bond, disorder, polymeric or powder entry, complete hydrogens, one entry per refcode family, exactly one metal atom, and the complex’s charge taken from the formal charges the CSD stores on its atoms. That leaves 64,104 complexes. The state Orbitron reports is right for 97.8% (62,723 of 64,104; 1,381 are wrong; measured 2026-10-23). The Roman numeral is a curated label, assigned by the CSD’s editors from the literature, not a measurement, so the figure is agreement with a name.

Methods	Entries	Right
Both methods answered and agree	53,269 of 63,762	98.8%
Both answered and disagree: the ionic model	10,493	92.9%
Both answered and disagree: the bond-valence sum	10,493	5.0%
Ionic model, of the 64,098 states it answers	64,098	97.8%
Bond-valence sum, of the 63,768 it answers	63,768	83.4%

Reeves et al. report 99.2% where their two methods agree; here it is 98.8%. The two methods are close to independent, one from the charge and the ligand identities and one from bond lengths, so agreement is strong evidence and disagreement is a warning.

Two other references give the same picture. Against BOS-Lig’s experimental oxidation states for 1,142 tmQM complexes, Orbitron’s state is right for 88.6% (1,012), against 84.3% (963) for tmQM’s own Hückel-derived states. Against tmQM’s ionic SMILES (written by xyz2mol_tm), the InChI Orbitron writes matches for 3,793 of 4,466 complexes (84.9%, stereo layers ignored; 316 differ in formula, 248 in charge placement; both measured 2026-10-23). The largest known cost is the nitrosyl convention: the reference writes every NO as NO⁻ and the metal one to two states higher, and Orbitron reads a linear nitrosyl as NO⁺, which cost 53 matches. That is a difference of convention, not a defect found. Both references are one method’s answer, and neither is independent of the data the rules were checked against.

Reproduce the CSD figure with scripts/csd_werner_benchmark.py. It needs a CSD licence, and the structures it extracts are licensed data that stay in a scratch directory, never in the repository.

The f block

scripts/csd_werner_benchmark.py extract --f-block takes the same subset for the lanthanides and actinides: names that give the metal a Roman numeral, one metal atom, no metal-carbon bond, and an actinyl’s oxo groups kept rather than filtered as multiple bonds. That leaves 3,214 complexes (September 2026 release). On 2026-10-16, before any rule had been tuned on them, the reported state was right for 96.8% (3,112); the changes made against them that day took it to 99.0% (3,182), with no entry that had been right going wrong. The second figure is in-sample. Two of the misses were uranyl dinitrates the CSD names “uranium(ii)”. An actinyl, O=An=O, is An(V), An(VI) or An(VII) by what it is, so the extract now leaves out an actinyl named below +5 as a naming error, and those two were the only ones: 3,212 complexes, 3,182 right (99.1%), and they are not in the trust table below. Of the 3,214, 1,269 are of metals with one state in practice (La, Gd, Dy and the rest at +3), right for all but one; what the benchmark tests is the metals with two or more:

State	Complexes	Right before	Right after, 2026-10-16	Bond-valence sum right / answered, after
Ce(III)	142	136	141	140 / 142
Ce(IV)	58	54	58	57 / 58
Pr(IV) and Tb(IV)	16	0	16	9 / 16
Sm(II)	59	59	59	55 / 59
Sm(III)	186	170	182	176 / 186
Eu(II)	70	67	70	69 / 70
Eu(III)	361	336	356	360 / 361
Yb(II)	87	86	86	86 / 87
Yb(III)	187	180	185	178 / 186
U(III)	64	59	59	0 / 64
U(IV)	160	154	154	152 / 160
U(V)	19	17	17	14 / 19
U(VI)	95	90	93	87 / 95
Np(IV)	25	25	25	16 / 16
Pu(IV)	15	15	15	8 / 14

The bond-valence sum, right for 2,165 of the 3,214 at the start (81.2% of those it answered), was right for 3,051 (95.7%) after them. The changes:

Bond-valence parameters fitted to the f block. The older tables fix B at 0.37 Å, fit oxides and solids, and had no row at all for many states, so a sum could only name a neighbouring state that had one: a uranyl’s came out at +5, and Sm(II), Yb(II), U(III), Np(IV) and Pu(IV) could never be named. Where those tables have no row, lanthanide complexes now take Trzesowska, Kruszynski and Bartczak’s parameters, fitted to lanthanide coordination complexes in the CSD (Acta Cryst. B 2004, 2005 and 2006: Ln(III) to O, N, Cl and S, and Ce(IV), Sm(II), Eu(II) and Yb(II)); the f block’s oxygen bonds Gagné and Hawthorne’s (Acta Cryst. B 2015), whose U(VI) row names a uranyl’s +6 for 87 of 95; Np(IV)-O and Pu(IV)-O fits to their crystal structures (Gilson and Burns, Coord. Chem. Rev. 2021; Diwu et al., Inorg. Chem. 2010); and the rest of the actinides’ (III) and (IV) bonds to O, F and Cl Zachariasen’s (J. Less-Common Met. 1978). There is still no U(III)-O or Np(III)-O row anywhere, so U(III) and Np(III) get none at all: halide rows alone would leave every all-oxygen uranium site, a uranyl’s among them, with a state its sum was never compared against. U(III)’s column is the sum naming U(IV).
Tb(IV) and Pr(IV), which were pinned at +3 like the one-state lanthanides and so could not be read under four anionic siloxides. Where the +3 reading fails the metal is read again free and kept at +4.
Usual states for the f block, so a lanthanide the ionic model reads at a state it is never named at (Eu at +5, Sm at 0) takes a consistent bond-valence sum’s state, as a d-block metal does; with the nitrogen parameters above, that includes the phthalocyanine and porphyrin double-deckers and bipyridine radical complexes the ionic model read at 0 with their ligands neutral.

Of the 30 complexes not right after that day’s changes, 14 were uranium (U(III) read as +4, U(IV) as +6 or +2) and 10 were Eu(III), Sm(III) or Yb(III) read at +2.

extract --f-block --organometallic takes the other side of the metal-carbon filter: 932 lanthanide and actinide organometallics whose names state the metal’s state, the Cp, COT and alkyl complexes and the Ln(II) of every lanthanide that only bulky Cp ligands support. Before anything was tuned on them the reported state was right for 93.6% (872); reading diazadienes from their bond lengths (above) took it to 94.4% (880), and reading the pinned lanthanides and thorium again free where their one state cannot be read, keeping a lower state only for a metal bonded to carbon, to 95.0% (885) on 2026-10-17 (94.8%, 884, at the readings of 2026-10-23), which is what lets a lanthanide(II) or thorium(III) under bulky cyclopentadienyls be read below the element’s usual state. The misses are mostly bipyridine, phenanthroline and iminopyridine radical anions, which no published calibration covers yet.

The f-block Werner complexes are in the trust grade’s table beside the d block’s (below). On the 579 of them held out from fitting it, high covered 83.9% and was right for 99.59%, moderate and low together 14.5% and 98.8% (measured 2026-10-17, before the table’s rows were floored at 10 complexes from 3 entries); the 1.6% left uncalibrated are of elements with fewer than 30 complexes (Pu, Am and the later actinides). The textbook uranyl, the guide’s uranyl nitrate (uo2_no3_2_h2o2_cod4344223.xyz), is high, 0.991 over 25 similar complexes; while uranyls named at another state were scored in its group it was low. These are in-sample for the rules, which were tuned on every f-block entry, so only three of the 579 are wrong and the grade has little to separate; what the table adds is that a lanthanide or uranium site has a measured grade at all, where until 2026-10-16 every one was uncalibrated. The organometallics are not in it: they are graded from a table of their own (below), since the Werner strata are not taken to transfer to them.

Organometallics

extract --organometallic without --f-block does the same for the d block: 26,658 mononuclear complexes with a metal-carbon bond whose names state the metal’s state (September 2026 release). Metal-carbon multiple bonds, alkylidenes and carbynes, are still left out with the other multiple bonds, and so are nitrosyls. Nothing had been tuned on these entries, and on 2026-10-16 the reported state was right for 95.1% (25,350), against 97.8% on the Werner complexes. With the ene-dithiolate, cyclobutadienide and second-state readings of 2026-10-17 (below) it was right for 95.4% (25,437), at the readings of 2026-10-21 for 95.7% (25,517), and at those of 2026-10-23, with every edge of a boron cage bonded, for 95.7% (25,521). By metal, to the whole per cent and for metals with at least 150 complexes (a finer figure would let the history of the trust tables pin some groups’ counts):

Metal	Complexes	Right	Metal	Complexes	Right
Pd	4,900	99%	Co	1,306	87%
Pt	3,545	97%	Fe	1,014	92%
Ir	3,379	94%	Cu	639	97%
Ru	2,433	97%	Ti	594	94%
Rh	2,397	95%	Zr	338	91%
Au	2,016	99%	Ni	1,995	95%

On 2026-10-16 the commonest misses were Co(III) read as Co(I) (182), Ir(I) read as Ir(III) (161) and Rh(I) read as Rh(III) (71); on 2026-10-17 they were Ir(I) as Ir(III) (161), Rh(I) as Rh(III) (73), Co(III) as Co(I) (59) and Co(I) as Co(III) (50). Most are conventions or naming, not reading faults:

78 of the cobalt ones were CpCo(η⁴-cyclobutadiene), which the CSD names Co(III), counting the ring as its aromatic dianion, for 86 of 113 entries; it names the platinum and palladium ones as the neutral ring. Since 2026-10-17 the ionic model reads the dianion, as it reads a cyclopentadienyl as the anion: 93 more organometallics at their named state, nearly all of them cobalt, and 45 fewer (CpCo named Co(I), and platinum, palladium, nickel and ruthenium named by the neutral ring). The non_innocent_ligand caution gives the other reading’s state.
34 more were CpCo(dithiolene), named Co(III) with the ligand an ene-dithiolate (57 of 59 cobalt dithiolenes). Their C-S bonds are short of the 1.73 Å that makes a metal-bound sulfur a thiolate, so perception drew a dithione with the ene left single. Since 2026-10-17 both sulfurs of an S-C=C-S are thiolates where the C=C is 1.40 Å or shorter: 37 more of these organometallics read at their named state and none fewer, and on the Werner benchmark 16 more and 3 fewer.
The iridium and rhodium ones are mostly names that disagree with the CSD’s own majority: 723 Cp*Ir complexes are named Ir(III) and 26 Ir(I), 424 cyclometalated 2-phenylpyridine iridium complexes Ir(III) and 13 Ir(I), and Orbitron reads them Ir(III).

Against other tools

The same structures were given to the three other programs that read a metal’s oxidation state from a structure, on 2026-10-17 (scripts/metal_state_head_to_head.py): xyz2mol-om and TMOS, which take coordinates and a total charge as Orbitron does, and cell2mol, which reads the whole crystal from the CSD entry’s CIF. The sample is 1,250 complexes: 500 held-out d-block Werner complexes (refcode families the trust grade was not fitted to, though Orbitron’s rules were tuned on that set), 500 d-block organometallics and 100 f-block ones (which no Orbitron rule was tuned on), and 150 held-out f-block Werner complexes. Each is scored against the Roman numeral in its CSD name. A tool that gives no state abstains; it is not counted wrong among the states it answers, and it is among all of them.

	Orbitron	xyz2mol-om	cell2mol	TMOS
d-block organometallics, right of 500	478 (95.6%)	462 (92.4%)	356 (71.2%)	198 (39.6%)
answered, and right of those	500, 95.6%	493, 93.7%	374, 95.2%	301, 65.8%
d-block Werner, right of 500	498 (99.6%)	433 (86.6%)	399 (79.8%)	334 (66.8%)
answered, and right of those	500, 99.6%	468, 92.5%	401, 99.5%	437, 76.4%
f-block, right of 250	240 (96.0%)	21	0	0

On the 226 organometallics that all four answered: cell2mol 96.5%, Orbitron 96.0%, xyz2mol-om 95.6%, TMOS 68.6%. The 95% interval on Orbitron’s 478 of 500 is 93.4% to 97.1%, so on the states they do give, Orbitron, cell2mol and xyz2mol-om are not told apart by this sample; what differs is how many they give. cell2mol abstains on a quarter, where the cell does not reconstruct or its charge distribution is not unique, and finds no valid distribution for any f-block complex. xyz2mol-om has no cadmium, mercury or technetium and, of the f block, only lanthanum and cerium. TMOS has no bond-length parameters for many metal-donor pairs (most Pt, Ir and Au complexes), and it would refuse a structure whose shortest X-H distance is under 0.80 Å as a unit error, which a crystal’s X-ray hydrogens often are; it was run with its ignore_scale switch, which answers 72 more and changes no conclusion. Where two answer and disagree, Orbitron matched the name 50 times to xyz2mol-om’s 5, 9 times to cell2mol’s 3 and 193 times to TMOS’s 6.

Orbitron’s trust grade held on the sample: high for 849 of the 1,250 and right for all of them, moderate for 232 and right for 98.7%, low for 148 and right for 81.1%. None of the other tools grades its answer this way.

Three things to keep in mind. xyz2mol-om was run without the GFN2-xTB Mayer bond orders it can take; its own figures put its oxidation states at .9867 without them and .9863 with, on relaxed geometries rather than crystal ones. TMOS’s README calls it “informal tools for internal use”. And oxiMACHINE, a machine-learned model for metal-organic frameworks, was not run.

4.3 The trust grade

Each site carries a grade and the reasons for it. The grade is how often the reported state was right for complexes like this one in the benchmark above, and the cautions explain: they do not set it.

The complexes are grouped by the element, where the state came from, whether the ionic model and a bond-valence sum agree, disagree or only one answered, how many bonds the metal has and what kinds of atom are on them, and three flags (a ligand whose charge is a convention, identical ligands read at different charges, a state outside the element’s usual set). A metal’s accuracy is its narrowest group’s, pulled toward the next broader one by a pseudo-count of ten and so on up to the accuracy over everything, so a small group says little and one of two thousand says what it measured. A group of fewer than 10 complexes from 3 CSD entries is not printed, nor is one from which such a set could be worked out by subtraction; a metal whose group is not printed is read from the next broader one, and where no group of its kind is printed the line says no group of similar complexes is large enough to report and gives the accuracy over everything. The counts are core/edit/src/geometry/trust_table.csv, written by scripts/trust_calibration.py table.

A printed group’s size is exact, but how many of its complexes were right is not. Up to 400 complexes the table gives a block of two or three counts: the less common outcome’s count rounded down to an even number and the next, with the counts left at the middle of an even-sized group made one block of three. 25 of 25 and 24 of 25 both print as 24 to 25, 3 wrong of 96 and 2 wrong as 93 to 94 right, and 4, 5 and 6 right of 10 all as 4 to 6. A larger group prints a wider block, one count more per 200 complexes (five counts at 1,000), by that fixed rule and nothing else. Every block holds at least two counts, so a row names no count even to a reader who knows the rule. The program reads the count it expects in the block, given the broader group’s accuracy, so what it prints is the same whichever is true. Until 2026-10-19 the table printed the counts themselves, and a group of 25 printed as 25 right said of each of its complexes that the program’s state matched the CSD’s name, as did every group of its own outcome below it. scripts/trust_calibration.py audit checks the table for that, for a reader who also knows every group’s size and the rule: no finest group’s outcome, all right or all wrong, and no finest group’s right count follows from the rows. The table of 2026-10-17 printed every group’s count, so it decided all of them; on the counts of the floored table that followed it, which left out groups under ten, the audit found 2,033 Werner groups decided and 191 more with their count pinned, and 1,035 and 174 organometallic ones; on the blocks, none. Those earlier tables stay in the repository’s history as they were, and for their own readings they print what the blocks leave out. So a new table is also checked for a reader of every earlier one (scripts/trust_calibration.py compose): a group unchanged since an earlier table’s readings counts as known exactly, and no group that changed may be worked out from the new rows, the known ones and the totals this page prints. Where one could, its element’s accuracy row is withheld (the element’s size stays printed, so its coverage is unchanged) or, for an element graded by its row, the narrowest row over the group; the 2026-10-23 tables withhold 27 Werner and 20 organometallic rows that way. The check also covers a reader who guesses that a group’s count moved by no more than its size did, which is usually true. The wider blocks of large groups are what keep that cost small: a broad row printed to within two counts, less the groups under it that are known, can name the few that changed.

Trust	Means	Share of the held-out complexes graded by group	Right
`high`	at least 99% of similar benchmark complexes were right	73.8%	99.68%
`moderate`	95% to 99%	16.5%	97.15%
`low`	under 95%	9.8%	82.40%
`uncalibrated`	neither benchmark describes this metal (a polynuclear or periodic structure, a file with another metal, no declared charge, an element with fewer than 30 benchmark complexes, or fewer than 30 organometallics for one with a metal-carbon bond)	0.1%
`as_stated`	you gave the state, or the file states it	not graded
`none`	there is no state	none in this benchmark

The shares and the accuracy are on the 11,283 of the 13,493 held-out complexes (one refcode family in five, chosen by a hash) that are graded by their group, with the grades’ cut points and the pseudo-count fixed on the other 53,823 (refitted 2026-10-23 at the readings of that day, scored on the rows and blocks the table prints, before the rows withheld against earlier tables, which only a table fitted on every complex has). Of the rest, 2,198 are metals with one state in practice (zinc, cadmium, the lanthanides at +3), graded by their element, and every one was right; 12 are uncalibrated. The grade ranks wrong states below right ones with an AUC of 0.914 and puts 74% of the wrong states in its least-trusted tenth of complexes. Until 2026-10-23 the figures were taken over every held-out complex, the 2,198 always-right fixed-state metals among them, which put the AUC at 0.926 and high at 77.6%; scored over the complexes the table grades, they describe the table. Calibration is checked, not assumed: among the held-out complexes graded high, 99.68% were right, which is above the 99% the grade claims. The shipped table is fitted on all 67,315.

Each graded site also gives the share it was graded from, with a 95% interval and the size of its closest group: 99.1% of similar benchmark complexes right (95% interval 88.6 to 99.9%); the closest group holds 25 for the uranyl nitrate above. The interval is the Wilson score interval on the estimate, its sample the group’s complexes plus the pseudo-count of ten it is pulled toward the broader groups with. The grade is the share’s, not the interval’s lower end. Grading by the lower end was tried on the same held-out complexes: it moves many grades down and shrinks high to a small part of the Werner complexes, because a small group is uncertain however good the groups above it. The interval is shown instead, so a group that sits near a cut point, like the 866 four-coordinate N,O-donor Ni(II) complexes at 95.3% (93.7 to 96.5%), can be seen to.

An organometallic is graded the same way from a second table, core/edit/src/geometry/trust_table_organometallic.csv, counted over the 27,589 organometallics above (26,657 of the d block with a state, 932 of the f block), where the element has at least 30 of them (37 elements do). Every such metal is graded by its group, even at its element’s one state: under bulky Cp ligands a lanthanide that is always Ln(III) among the Werner complexes can be Ln(II). The donor part of a group’s key counts the groups of bonded atoms on the metal that are bonded to one another (trust.features.hapto): ferrocene is other+5+5, a CpFe half-sandwich other+5, so the two are graded apart. Ferrocene’s own group, which the 2026-10-21 table printed as 93 or 94 of 96 right (moderate), is withheld from the 2026-10-23 table against the earlier ones, so ferrocene is graded from iron’s complexes whose two methods disagree, 434 at 88.9%, and is low. On the 5,489 organometallics held out from fitting it that it grades by group (222 wrong), high covers 43.9% and is right for 99.58%, moderate 33.2% and 97.42%, low 22.9% and 86.89%, with an AUC of 0.853 and 54% of the wrong states in the least-trusted tenth: honest, but it separates right from wrong less well than the Werner table (0.914). The AUC was 0.888 before the readings of 2026-10-17 fixed the cyclobutadienes and dithiolenes, which were wrong states easy to place in a low group, 0.877 before the rows were floored, and 0.862 before their right counts were printed as blocks; high covered 47.2% then. Its f-block part is thin: of the 185 f-block organometallics held out, 7 were wrong and 13% are of elements with too few organometallics to grade.

The same key splits the Werner complexes with a side-on donor pair (a peroxo, an eta2-Te2, 192 in the d block, 86% right) from their end-on neighbours. A group close to a cut can move on a handful of complexes; the grade is still what the benchmark says of it. This is in-sample for the state-choosing rules (they were tuned on every complex); what is held out is the grade’s ranking of their errors.

What it measures is agreement with the Roman numeral in a compound name. For a ligand with more than one closed-shell reading that numeral is a convention the program follows, so a high grade on a complex with a non-innocent ligand says the program agrees with the name, and the non_innocent_ligand caution says the state follows a reading of the ligand. The benchmarks leave out polynuclear and periodic structures and any entry with a second metal atom, a counter-ion included, so nothing here calibrates a grade for them, and they are uncalibrated; organometallics and hapto ligands are graded from the organometallic table. The d-block sets leave out metal-ligand multiple bonds (vanadyl, a Re=O, an alkylidene); the f-block set keeps an actinyl’s.

as_stated is not a grade of the state’s correctness. The tool repeats what it was told. Each caution has a kind and a sentence:

methods_disagree: names both states, and says which is usually right;
one_method: only the ionic model, or only the bond-valence sum, gave a state that counts; a sum that named a state without being a measurement is said with the reason;
odd_electrons: an odd electron count 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;
unusual_state: the state is not one of those usually named for this element. The usual set is the states the CSD names for at least 0.4% of that element’s complexes in the benchmark, plus the zero- and low-valent states organometallic chemistry uses (Ni(0), Pd(0), Pt(0), Fe(0), Co(-I) and the like); the lanthanides but promethium, Th, U, Np and Pu have one by the same rule from the f-block benchmark, and no other element. Of the 1,477 benchmark results outside it, 5% matched the name, so it outweighs the two methods agreeing. Cu(III) and Ni(IV) are real; this says the program reading one is usually wrong. It is also a flag of the grade’s table, which has almost no such state to learn from (too few to print a group of them), so a state outside the usual set is graded from a broader group;
bond_valence_fallback: a bond-valence sum’s state is reported in place of the ionic model’s, and the sentence says which rule did it: a 0 a consistent sum contradicts, a 0 or a +1 on iron or manganese in a sphere of lone-pair donors, or a state the element is almost never named at; see below;
coordination_prior: the computed state is one the coordination number rules out, so the state the element takes there is reported (oxidation_state_source is coordination): four-coordinate palladium and platinum at +4 become +2, and two- or three-coordinate gold at +3 becomes Au(I); copper that a bond-valence sum puts at +1 over nitrogen and oxygen donors alone becomes Cu(II), because those parameters do not depend on the state. When the rule was made the first two matched the CSD names for 106 of 108 results (the computed +4 in four bonds and the computed Au(III) in two or three bonds had almost never matched, over 97 such results) and the copper one for 42 of 48; at the readings of 2026-10-23 they match for 69 of 76 and 27 of 32 (one copper named Cu(I) and four Cu(III));
identical_ligands_differ: ligands with the same atoms (hydrogens included) and bonding were given different charges, which is suspicious (such ligands usually carry the same charge, though ligand-based mixed valence is a real exception), and is a prompt to look, not proof. Over 4,447 CSD complexes at the 97.7% step (all 1,447 wrong states and 3,000 of the right ones) it marks 7.3% of the wrong states and 0.3% of the right ones, about a third of the states it marks being wrong against 2% overall. It is a caution, not a repair: forcing the ligands to agree would lose every right state it marks. It is a flag of the grade’s table;
cluster_charge: a boron cage was charged from the cluster it forms with the metal, which counts the metal fragment as two skeletal electrons, and the state follows from that charge. The cluster’s edge count agrees with the class, which is a filter and not a structure determination, so the state is provisional and its grade is held at moderate at most. A cage has a metal-carbon bond, so it is graded from the organometallic table;
non_innocent_ligand: a ligand with more than one closed-shell reading is on the metal.

A low grade is not a rejected state. More than four in five of those were right in the held-out benchmark. It means look at this one, and in a large screen it is the list to look at.

  Cu(+2, from the ionic model) · atom #1 · CN 4
      Trust in the state: high
        - 99.5% of similar benchmark complexes right (95% interval 96.0 to 99.9%); the closest group holds 113
        - a dioxolene or o-amidophenolate ligand (atoms #6, #7) is on the metal and its bond
          lengths place it at -1.15 (0 quinone, -1 semiquinonate radical, -2 catecholate; ...)

(tmqm_batweb.xyz. The grade is the benchmark’s, so a state that is a ligand convention can be high; the caution and the atoms it names are what say the state follows a reading.)

4.4 Non-innocent ligands

Eight classes are recognised on a metal, from the geometry and the bonds:

Class	Readings
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 recognition is conservative on purpose: a dithiocarbamate, an ethane-dithiolate, a catechol with both hydrogens, a ring nitrogen on bipyridine and an N-oxide are not flagged, and each is a control in the test suite. A radical ligand outside these eight is not recognised. A radical on a ligand you know about is the largest single class of wrong states in the benchmark (193 of the 1,417 wrong on 2026-10-12, below), so a moderate or high grade on a structure with an unusual redox-active ligand is not a clearance. A ketyl (a diarylmethanolato radical, Ar2C(O)•) is one: its C-O is as long as a delocalised chelate’s, and the ionic model reads it as the neutral ketone. It cannot be told from the chelate by geometry, and the benchmark files carry no declared multiplicity to settle it (a Ti(III) ketyl complex comes out Ti(II)). A file that declares its multiplicity gives the model what it needs to keep an odd ligand odd.

A dioxolene’s redox level is read from its bond lengths

The one class in that list with a published remedy is the catecholate and the N-aryl 2-amidophenoxide, which a closed-shell charge assignment can only read as the dianion or the neutral quinone. The radical monoanion between them, the (imino)semiquinonate, is an odd-electron fragment, so the ionic model’s repairs turned it into the dianion and a Co(II) bis(semiquinonate) came out Co(IV).

Brown (Inorg. Chem. 2012, 51, 1251) fitted every bond of the ring, and the C-O and C-N bonds, against the ligand’s oxidation state over 109 amidophenolates and 259 catecholates whose state was unambiguous, and defined the metrical oxidation state (MOS) as the one value of the state that best reproduces a ligand’s lengths. Orbitron applies it: where a chelating catecholate or N-aryl amidophenoxide on a d-block metal has a MOS within 0.35 of -1, it is a radical monoanion, the ligand is charged -1, and the metal takes the rest. The curves are the paper’s, recovered exactly from the spreadsheet it ships with, and the solver reproduces that spreadsheet’s own MOS for all 368 of its training ligands to 5e-5. The report lists each such ligand with its MOS and what it means:

  Pd(+2, from the ionic model) · atom #1 · CN 4
      Amidophenoxide ligand (#2, #3): metrical oxidation state -1.07, iminosemiquinonate, radical monoanion
      Amidophenoxide ligand (#49, #56): metrical oxidation state -1.07, iminosemiquinonate, radical monoanion

It follows the paper’s domain and nothing wider. The nitrogen must carry an aryl; a ring fused to another (phenanthrenequinone, a phenoxazine, a quinolin-8-olate) is left alone, as is a catecholate with a halogen or a nitro group, an sp3 ring, a donor that bridges two metals, and every metal outside Cr to Zn, Ru to Cd and Os to Au: V(V), Mo(VI) and the like read a dianion as less reduced than it is, by π donation to the metal, which the paper attributes to bonding and not to electron transfer. A MOS between two states (the paper’s own mixed-valence ligands read -1.56) is not overridden. The ligand is only read as a radical where that leaves the other ligands no worse off.

Against the 64,104 CSD complexes this raised the reported state from 94.9% to 95.1% right (60,816 to 60,933): 128 complexes turned right and 11 turned wrong. Where the name and the geometry disagree it is usually a valence tautomer: a Ni complex named Ni(III) with an amidophenoxide whose bonds say iminosemiquinonate Ni(II). The geometry is the evidence this program has, and the name is the authors’ choice.

An odd electron count on a complex with an odd number of such radicals is consistent, and is said so: 17 on a Cu(II) and its closed-shell donors, made even by the ligand radical, an open-shell metal coupled to it, not a ligand charge gone wrong.

A diazadiene’s redox level is read the same way

A chelating 1,4-diazadiene, R-N=C(R’)-C(R’)=N-R, has the same three levels: the neutral diimine, the semi-iminato radical anion and the enediamide dianion. De Zwart, Reus, Laporte, Sinha and de Bruin (Inorg. Chem. 2021, 60, 3274) fitted its C-N and C-C lengths against the state over 254 CSD ligands on main-group, d-block and lanthanide metals, with a second fit for an enediamide whose C=C also binds the metal (η⁴), weighted by the distance from the C=C to the metal. Orbitron applies their fits and their protocol from the spreadsheet in their Supporting Information. Its solver finds that spreadsheet’s MOS where Excel’s Solver converged, and a lower sum of squares where it stopped early; on the paper’s own training set a MOS within 0.35 of -1 picks out all 43 radicals and none of the 147 diimines or 64 enediamides, and a MOS at or below -1.5 picks out every enediamide. The ligand is charged -1 or -2 accordingly, as a dioxolene is, and only where that leaves the other ligands no worse off.

It is within the paper’s domain: each backbone carbon carries a hydrogen or a methyl, so a bipyridine, phenanthroline, iminopyridine or BIAN, whose backbone is part of a ring, is not read; the ligand binds one metal through its two nitrogens (and, for an η⁴ enediamide, its C=C) and nothing else. The MOS is reported for every metal, but it decides the charge only off the groups 5 to 12 d block. On 2026-10-16, when it was left out on groups 4 to 12, deciding it there as well turned 3 states right and 7 wrong on the 64,104 d-block complexes: on a late metal the geometry can call the ligand a radical anion where the name, by the convention of non-innocent d-block chemistry, has a neutral diimine. On the f-block organometallics below it turned 8 right and none wrong. Group 4 has decided the charge since 2026-10-18: titanium, zirconium and hafnium in these complexes are d0 and cannot take the ligand’s pi electrons.

A delocalised chelate is one anion, however long its two bonds run. A diketonate, carboxylate or dithiocarboxylate has its charge shared across two donors, and a C-O past 1.285 Å (C-S past 1.73 Å) is the length at which a donor is read as an anion on its own. A crystal structure with both bonds past it charged both donors, left a carbon short of valence, and put the metal two states too high: Mn(acac)₃ as Mn(IV), Pt(II) in a phenalenonate chelate as Pt(IV). Where no choice of anions gives a sound ligand with the length rule on, the donors of such a chelate are read again without it, and a thioamide or thiourea sulfur is read as the neutral thione whatever its C-S length (AuCl₃ on tetramethylthiourea was Au(IV)). Against the 64,104 CSD complexes this raised the reported state from 95.1% to 95.3% right (60,933 to 61,108): 176 turned right and one turned wrong. tmQM’s InChI match is unchanged (3,679) and its odd counts on declared closed shells fall from 701 to 692. The rule is deliberately narrow: applied to every donor it gained about 100 more and broke 12 acylhydrazides and tripod thiolates, whose long C-O or C-S is the evidence that they are anions.

When the ionic state is one the element almost never takes

Against the CSD names, 1,477 results were at a state the element is almost never named at, and 5% of those were right. A late metal at +5 or more is the sharpest case: the ionic model was right for 18 of 386, a bond-valence sum for 284. The cause is a ligand the ionic model misread and charged too much (a coordinated nitrile or a nitroxide, a perchlorate), which pushes the metal up and leaves no mark on the bond lengths the sum reads. A Cu(II) bipyridine, acetonitrile, perchlorate complex came out Cu(VIII).

So where the ionic state is outside the element’s usual set (the table behind unusual_state) and a bond-valence sum gives a state inside it, the sum’s state is reported, with a bond_valence_fallback caution naming both and graded low. The sum need not be the consistent one the other rules ask for: a sum that misses its own state still beats a state that is right 5% of the time. Against the 64,104 CSD complexes this raised the reported state from 95.3% to 96.7% right (61,108 to 61,988): 958 turned right and 78 turned wrong, and the states it substitutes are right for 77% of the 1,220 complexes it touches (after the per-ligand perception below: 1,088, right for 76%). Taking only the consistent sums gained 463; the usual set was derived from the same names, and deriving it from one half of the entries and testing on the other half gave 1,093 gained and 71 lost.

The 78 that turned wrong are mostly real Cu(III) and Ni(IV) complexes, one step from the usual set. If you know the state is one of those, --oxidation-state gives it and the site is graded as_stated. Where a sum or the coordination number replaced the ionic state, the ligands are read again with their charges allocated to give it, so the identifiers and the electron count describe the complex that is reported: in the CSD benchmark that worked for 933 of the 1,507 complexes concerned. Where no reading of the ligands gives the reported state (or the file declares a closed shell and the state would need a ligand radical) the identifiers keep the ionic model’s charges and the count declines; orbitron identify --json and orbitron.identify list each metal’s state in the identifier beside the reported one (metal_states, with reconciled) and warn (identifier_state_differs) where they differ. The lanthanides, Th, U, Np and Pu have usual states from the f-block benchmark (above) since 2026-10-16; the alkali metals, americium and the heavier actinides and the main-group elements have no usual-state table, so nothing replaces their states.

Each ligand is perceived on its own

Bond orders and ligand charges used to be found in one search over every ligand in the file, the metal and the counter-ions included. That search was never complete for a metal complex: an isolated metal atom and each bare oxo or halide counted for a charge its formal charge did not, so the search could not match its target and returned the candidate nearest an offset one, and the charge repairs were tuned on that. One component it could not satisfy failed it for the rest: a perchlorate’s chlorine, with four partners and no valence to match, left a bipyridine and two acetonitriles in the same file with every bond single, so each ring carbon read one short, each nitrogen took a charge, and a Cu(II) read as Cu(VIII).

Each ligand is now searched on its own atoms, as xyz2mol for metal complexes does (Rasmussen et al., J. Cheminform. 2025, 17, 63). Every complete assignment of its bond orders is collected at the charge its pinned atoms sum to and at one and two units either side. The one kept has the fewest charged atoms (a negative charge on a metal-bound atom is not counted against it), then the bond orders that fit the bond lengths, then the total charge nearest an extended Hückel estimate for the ligand: the valence electrons less two for each orbital below -10 eV, moved by two while a positive guess sits beside a low LUMO or a charge of -2 or lower beside a high HOMO. The extended Hückel calculation is Orbitron’s own (the YAeHMOP parameters RDKit ships, a minimal valence basis with the Slater orbitals expanded in six Gaussians, the weighted Wolfsberg-Helmholz term with K = 1.75) and agrees with RDKit’s to 0.002 eV where the charge is decided.

Against the 64,104 CSD complexes the ionic model alone went from 60,368 to 60,752 right and the reported state from 61,994 to 62,164 (96.7% to 97.0%). Against tmQM’s own ionic SMILES the InChI match went from 3,678 to 3,777 of 4,466 (84.6%), and the odd electron counts on declared closed shells from 692 to 461. It is about four times slower than the single search, 30 ms a complex on average.

Two things were tried and left out. Putting the aromatic-system size first, as the paper does, was worse (60,254 against 60,733 right on CSD): its Kekulé-pattern count is a poor stand-in for RDKit’s aromaticity. Using the extended Hückel charge alone, with no other evidence, was worse too (60,083): by itself it matches the CSD named state for 87.5% of complexes, against 95.7% for the ionic model, and where the two disagree the ionic model is right 76% of the time and the guess 15%. It decides between assignments the other evidence cannot separate, a neutral quinoid or an aromatic dianion for the same atoms (tmQM KIXJIO).

4.5 What else the states get wrong

On 2026-10-12, 1,417 of the 64,104 states were wrong (1,377 at the readings of 2026-10-21, above). By ligand family then, from the compound names, the first family a name matches claiming it: radical ligands (193), carbene and ylidene ligands (133), phosphines and phosphites (112), dithiolato and dithiolene ligands (97), hydrido ligands named as neutral H (65), azido (31), cyano, nitrosyl-like and nitrito ligands (30), N-oxides and oxido ligands (24), glyoximato (4), and a tail of 728 with no single cause. The tail’s largest groups are nickel and cobalt named II and read as III, or the reverse (202), and iron the same way (73). scripts/csd_werner_benchmark.py score prints this table. At the 94.8% step (2026-10-01) the same patterns found 3,363: radical ligands 622, carbene and ylidene 303, phosphines 198, and a tail of 1,737; notes/archive/electron-counting.md has what was traced in each family then.

The size of the error still depends on the metal. On 2026-10-12 the largest confusions were nickel named III and reported II (114) or named II and reported III (110), cobalt II as III (95) and III as II (76), iron III as II (55) and II as III (48), and ruthenium II as IV (47). At the readings of 2026-10-21, reported accuracy is 99% for copper (12,693 entries), palladium and silver, 100% for zinc (7,154), and 97%, 96% and 96% for nickel (8,625), cobalt (6,883) and iron (4,311). It is lowest for the heavier metals of groups 6 to 9: iridium 83% (253), rhenium 89% (247), molybdenum 91% (164), osmium 92% (242) and ruthenium 95% (2,189). Whole per cent, and not every metal, because a finer figure would let the history of the trust tables pin some groups’ counts.

4.6 What is declined, and what is counted on a stated assumption

The tool says nothing rather than something wrong in a few cases, and says why. Where the count rests on something the geometry does not settle it is made on one reading and the others are given beside it (16 or 18 electrons, with the reason; unsettled in the JSON, with the other totals). Over tmQM’s 108,541 centres 99.88% (108,408) have a count, about 2,900 of them with a range (2026-10-23).

Counted with the other readings given. In 68% of the ranges at least one stated total is 18 (or 16 on a d8 centre), against 26 to 28% for the single one, and in under 0.5% is every reading over 18.

A contact the bonds left out that may be bound: an atom within bonding distance behind a bound carbon or boron donor (an η² thiocarbamoyl’s sulfur), two electrons more if bound (1,294 sites). The M-D-X angle says most about it: under 80° the CSD bonds the atom in 94% of cases, from 80° it is 30 to 70%, and the reason gives the angle. A hydrogen on silicon, or several on a boron already bonded to the metal (a borohydride), is two electrons per hydrogen if it binds.
A boron cage bound at only three or four vertices, or larger than one polyhedron (200): it is charged as the smallest class that holds its electrons (closo, nido, arachno), and the next class leaves the metal’s state two higher and the count two lower, so both are given. In 89% of these a stated total is 18, or 16 on a d8 centre.
A hapto ligand whose π electrons on the bound atoms are odd (1,433): the π system reaches past the atoms bound (a slipped allyl or ring, a folded fulvene), so the count is the lower even one and the upper two more. A flat Cp drawn as a fulvene is counted as the Cp anion beside a carbocation instead: 34 tmQM centres, 31 of them now 18.
A nitrosyl whose M-N-O angle is between 140° and 150°, or whose ligands cannot be read to match the angle: NO⁺ and NO⁻ both give two electrons and the metal’s state differs by two, so the totals do. Outside that band the angle decides (Enemark-Feltham): linear, 150° and over, is NO⁺ and bent, under 140°, is NO⁻.
A B-H hydrogen is otherwise counted by where its boron is: two electrons where the boron is not bonded to the metal (a scorpionate’s B-H), nothing for one B-H on a boron that is (an agostic contact).

Counted on one assumption, named.

A carbene with no heteroatom on it is a neutral Fischer carbene or a Schrock dianion, and the electron total is the same either way: only the metal’s state differs. It is neutral on group 8 and later and on any metal with a CO, and a dianion on the earlier metals without one, so a Grubbs-type ruthenium is Ru(II) at 16 electrons and a Schrock imido-alkylidene Mo(VI) at 14. That is a convention, and the literature names a Schrock centre by either reading.
A d0 metal offered more than 18 electrons by its π donors counts 18: with no electrons of its own and nine valence orbitals, it has no orbital for the π pairs past that, which stay on the ligands. Mo(NAr)₂Cl₂L₂, Re(NR)₃X and Cp₂Ti(N=CR₂)₂ read 18 where they read 20 (102 tmQM complexes, all d0 imido, nitrido, oxo or ketimide complexes of groups 4 to 7). Past d0 an over-18 total is left as it is, because there it can as well be a state the ionic model got wrong (a V(I) oxo, a Ti(II) bis-imido, a Ni(VI) on two dianions are among the 61 that would move).
A boron cage charged from its cluster with the metal. Where a cage is bound over a face and the metal fragment is worth two skeletal electrons as a BH is (CpCo, Cp*Ir, (arene)Ru, RhH(PR₃)₂ and the like), the cage takes the charge of the class one beyond the cluster’s, so the metal has a higher state and the count two fewer electrons (FEWRII goes from Ru(0) at 20 to Ru(II) at 18), provided the cluster’s own edge count shows the same class. The count is made on that reading and says so (cluster_charge; no alternative is offered). It applies to 10 tmQM complexes. FEWRII has its paper (Bown et al., J. Chem. Soc., Dalton Trans. 1987, 1169: an 18-electron Ru(II) complex); BEPSIY, CCOBOR, BAFRUV and KITDOH match the Cp*Co and Cp*Ir B₉H₁₃ family by formula (Barik, Roy and Ghosh, Dalton Trans. 2015, 44, 669), not by refcode. CPCONB, BAWCIL, KULPOW and POLZUL have their papers (Callahan et al. 1974, 24 electrons and nido; Maynard, Sinn and Grimes 1981, 26 and nido; Nestor et al. 1992, a formal 2n+4 count and a nido shape; Macias et al. 1994, a nido shape), each the class the rule reads. HIMXEK has no paper to check the reading against. The two-electron figure for the fragment is counted by the authors for CpCo (Miller, Weiss and Grimes, J. Am. Chem. Soc. 1977, 99, 5646; Maynard, Sinn and Grimes, Inorg. Chem. 1981, 20, 3858 for BAWCIL) and for the platinum and nickel phosphine fragments of AQUHOJ, VAFRAW and PEKTIL, which they give as M(II) complexes of a dianionic cage (Hong 2003, Kadlecek 2003, Bould 2017); the other fragments are taken on the same arithmetic. Nickel, palladium and platinum fragments are nonconical (Evans and Mingos, Organometallics 1983, 2, 435) and two of these clusters are arachno in shape where the count says nido; the charge is taken from the count and the class of the shape is not, so they read M(II) at 18. Until revision 24 they kept the smallest class and read at 20 with 18 as the alternative.
A boron cage’s class and contacts. A closo cage bound over a face (a B10H10 or B12H12 with the metal over it, nine to twelve vertices) holds the electrons of a closo class, four short of the nido the face branch looks for, and is charged as the closo dianion, which keeps every vertex. A boron between two cage carbons that carries a substituent (an ansa carborane’s cyclopentadienyl) is kept as a vertex where the metal is on it. A cage vertex that keeps its hydrogen and touches the metal is a face contact, not an exo bond; only a vertex with no other partner is read as bonded to the metal alone.
A cyclopentadienyl slipped to two contacts on a single titanium, zirconium or hafnium (an ansa ring pulled off by a chelating arm, 2.4 to 2.5 Å from two carbons and 3.3 Å or more from the rest, so not seen as a ring) comes out an anion from the ligands’ own reading, and the metal +4. It needs no rule of its own: one that pinned such a ring decided no reading in all of tmQM, and was removed.
Lone donors where the ionic state has no valence shell (Ti(VI), Nb(VII), Au(0) beside a borate, where the ligands came out over-charged): when every donor is a lone one, each gives two electrons whatever its charge, so the count is made at the reported state (29 of the 105 such tmQM centres; the other 76 stay declined, below).
A donor drawn at +1 (a phosphine as a phosphonium, the dative bond’s formal charges) is a neutral two-electron donor with the metal a state higher.
A charge the ionic model could not divide, on a metal with one state in practice (zinc, cadmium, the group 3 metals, lanthanum) and one-atom donors: each donor gives two electrons whatever its charge, so the count is exact where they are lone ones.
A state a bond-valence sum or a coordination number replaced where no reading of the ligands gives the reported state (the bond_valence_fallback and coordination_prior cases). Where the ligands can be read to give the state (the usual case) the count is made at it; where the donors are all lone ones it is made at the reported state, since each gives two electrons whatever its charge; otherwise it is made at the ionic state the identifiers carry, with the difference named. On a metal with a carbon bond, a bond-valence sum no reading reaches does not replace the ionic state at all: the sum is a loose one there, and against 18 electrons and BOS-Lig the ionic state is the better supported, unless the ionic state is above the metal’s group (a Ti(VI)), when the sum’s replaces it (a complex with no carbon bond keeps the sum, which the CSD names support).

How the count is read. It is set against 18 electrons, 16 on a d8 centre. A count over 18 is flagged only where the metal has a carbon bond; a complex with none (an octahedral Ni(II) at 20) is said to be outside the rule, over-Werner, and that is intended (1,689 tmQM centres). An odd count on a file that declares a closed shell is flagged (831 centres): the charge was divided wrongly somewhere, or a ligand is a radical.

Declined (0.12% of tmQM, 133 centres).

No declared total charge and no other source: no ionic-model state. The bond-valence sum may still answer.
A metal bonded to another metal directly or through a ligand, a metal with no coordination sphere (a mercury with no donor in range), and a state no d shell can hold (29 sites: a cyclopentadienyl beside a pendant protonated pyridine or a borate zwitterion, where the ligands came out over-charged; with lone donors only, the count is made at the bond-valence state).
A metallaborane the skeletal-electron count does not fit (uncharged_cage, 33 tmQM centres): a cluster 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. With every cage edge bonded such a cage’s borons would otherwise be counted as lone donors, and an iridium in an 18-vertex cluster came to 24.
A molecule whose charge the ionic model could not divide, on a metal that has no single state.
Periodic structures: no ligand-field picture; it is made for a molecule.

4.7 The ligand-field picture

For a d1 to d9 centre, analyze metal-sites and the desktop’s Coordination section (the command line also prints the flat pattern of a d0 or d10 centre) show the d-orbital pattern a σ-only angular overlap model gives the donor geometry, and how the d electrons fill it.

  Ligand field (sigma-only model, units of e_sigma): t2g x3 at 0.00, eg x2 at 3.00
    d6 high spin: 4/2 electrons per level, 4 unpaired, LFSE -1.20, weakly Jahn-Teller active
    d6 low spin: 6/0 electrons per level, 0 unpaired, LFSE -7.20

What it is: each donor contributes σ-antibonding energy to the d orbitals in proportion to the squared overlap, with every donor equal and each weighted by (r₀/r)⁵ so that a long bond pushes less. Energies are in units of e_σ, the σ-antibonding energy of one donor on a d orbital pointing at it, so an octahedron has Δ₀ = 3 e_σ and a tetrahedron Δₜ = 4/9 Δ₀. The levels come out as textbook patterns (an octahedron’s t₂g and e_g, a tetrahedron’s e and t₂, a square plane’s four levels, an elongation’s splitting) and the test suite pins each. The LFSE is Σ nᵢ(Eᵢ − Ē), in these model units. Both the high-spin and the low-spin filling are shown, with the number of unpaired electrons, and a Jahn-Teller flag where a partly filled degenerate level pulls the geometry: strong in a σ-antibonding level (d⁹, high-spin d⁴ and low-spin d⁷ in an octahedron), weak in a nonbonding one.

What it is not:

Not a prediction of a spin state. e_σ is not estimated, so neither filling is chosen. For 4d and 5d metals the low-spin reading is almost always the real one, and the output says so for Z = 39 to 48 and 72 to 80.
No π effects. A π donor or acceptor reorders the lower levels and is the reason real t₂g sets are not degenerate. An oxo, imido or nitride, or any short M-O or M-N contact (under 1.75 Å) with no electron count to say otherwise, declines the picture.
No d-s mixing, which matters for square-planar and linear centres.
Not an energy. The LFSE is a model quantity in e_σ. It is not the stabilization energy of a calculation, and Orbitron does not call it that.

The picture is declined, with the reason in the report, for: fewer than four or more than seven donors; an f-block metal (spin-orbit coupling dominates); a hapto ligand; a periodic structure; no oxidation state; an oxo, imido, linear ketimide, nitride or Schrock alkylidene (any donor read as a dianion, a triple-bonded one or a linear ketimide); a Z-type borane on the metal, which takes a pair rather than giving one; a B-H σ donor, whose hydrogen is bound but is not one of the sphere’s donors; and an electron count that is unsettled (a range in 4.6) or was declined, other than for a missing total charge or bond orders taken from the file. On the benchmark, 92.4% of the entries get a picture; the declines are 2-donor (3.1%), 3-donor (2.3%), a count the ionic model could not make (0.6%), and 8-donor spheres (0.4%), in that order.

orbitron plot ligand-field writes the same picture as a figure (SVG or PNG, with a CSV of the levels and each orbital’s electrons): both fillings side by side, the electrons as up and down arrows, each filling’s S and model LFSE above it, and the centre, state and trust in the notes. It is a figure of the model, and says so in those notes. A job’s own orbital levels, with the program’s symmetry labels and occupations, are plot levels. The two are different claims, and --orbitals is the one place they meet: it sets the model beside the calculation’s five d-dominant orbitals per spin channel, scaling the model to eV with a single fitted e_σ and stating the fit’s residual, so the figure shows how far a σ-only picture of the geometry is from what the calculation computed. The fitted e_σ is a one-parameter summary of those five orbitals, not a measured σ-donor strength, and a large residual is the result: it says π donation, covalency or exchange is doing something the model leaves out. The orbitals are picked by the share of their printed squared coefficients that sit on the metal’s d functions, which has no overlap in it and so is a guide to character, not a population (--min-d-share, default 0.5, sets the share).

The picture is computed on the donors the coordination sphere found, at their real positions. A distorted octahedron gives a split t₂g and e_g, and the levels keep the label of the polyhedron the sphere resembles.

4.8 What is not here

Orbitron does not extract ligand-field parameters from a calculation beyond the one fitted e_σ of plot ligand-field --orbitals above. A full Kohn-Sham d-orbital splitting analysis, or the ligand-field parameters a multireference job prints itself, are a separate feature and are not in this release. The σ-only pattern above is a model of the geometry; --orbitals only compares it with the five d-dominant orbitals a job printed.