Documentation

How it works

One rule governs the chemistry: the structure drawn follows the coordinates and the occupancies. The deposited formula is never used to decide which atoms are drawn; it is the check.

A file passes through these stages in a fixed order. The CIF is read into a cell, symmetry operators and atom sites with their occupancies and disorder labels. CIFlat chooses among alternative positions, generates symmetry images and bonds atoms by distance. Each connected piece that contains a site of the asymmetric unit is one fragment: the complex, a counter-ion or a solvent molecule. Bond orders, hydrogen counts and charges are then assigned. The result is set aside as the reference chemistry, which no later stage alters.

The drawing is made from a copy. In it, hydrogen atoms are folded into their parent atoms, common groups are abbreviated and a polymer is cut to one repeat unit. Each fragment is laid out and written. The written files are then read back and compared with the reference chemistry. Counter-ions and solvent molecules are drawn as separate fragments, never silently dropped.

Reading the CIF

CIFlat needs a CIF with a usable unit cell, symmetry operators (or a space-group name it can resolve) and fractional coordinates. It uses occupancies and disorder labels when they are present. Hydrogen atoms are optional, and the sum formula is read only for the check. When symmetry is missing or not recognised, the program says so: a molecule built from the identity operator alone may be incomplete. Not every CIF dialect or dictionary item is supported.

Completing the molecule by symmetry

The asymmetric unit is often not the molecule. Every symmetry image of every site is generated within one cell in each direction, and images of one element within 0.30 Å of each other are merged into one atom. Contacts are classified against sums of covalent radii, and the bonded graph is followed outward from the asymmetric unit. A molecule lying on an inversion centre, a rotation axis or a mirror plane is therefore obtained whole. The animation on the home page shows this for COD 2224481, where a twofold axis generates half the dicopper cation.

Disorder and partial occupancy

A site with occupancy below one can mean three different things, and CIFlat treats them differently. Each choice is recorded in the report with the site labels and occupancies.

Alternatives

An atom or group refined in two or more positions that cannot all be occupied at once. Disorder is resolved before symmetry images are merged. Within each disorder assembly, the group with the highest mean occupancy is kept whole. Assemblies whose partial sites lie within bonding distance of each other are resolved together. Unlabelled sites are taken as alternatives only in a narrow case: close sites of one element whose occupancies add up to one.

Disorder across a symmetry element

A site of occupancy one half or less whose own symmetry image lies within bonding distance is one atom in two places, and one image is kept. Keeping both can create rings that do not exist; in one development structure it turned a propane-1,3-diyl link into a four-membered ring.

Partial presence

A partly occupied group of the complex with no alternative is present in only a fraction of the molecules. A drawing cannot show a fraction of a group, so such a group is drawn whole when its occupancy is 0.5 or more and left out when it is less.

Shared sites

Where two elements share a site, the majority element is drawn, the same at every symmetry copy.

Partly occupied solvent and counter-ions

Always drawn whole, as separate fragments.

A structure in which a group is partly present, or a site is shared by two elements, is not one molecule, and the drawing can show only one. The interpretive cases give an example of each convention.

Polymers

A connected piece that contains a site together with a lattice-translated copy of the same site is a coordination polymer.

• A chain is rebuilt from its periodic connectivity. One repeat unit in which every ligand is whole is drawn in square brackets, [ ]n, with the bonds to the next units running out through the brackets.
• For sheets and frameworks, two symmetry copies of the asymmetric unit are drawn.
• Where an excerpt is cut, the atom beyond the cut is shown as a ghost: its element symbol, joined by a wavy bond. A ghost is laid out and judged like any other atom, but it is not counted in the formula, the charge or the exported structure.
• When the lines leaving a bracketed unit would run over a label or a ring, or cross a bond, the unit is laid out again with wavy ends. Of 18 bracketed units in the tests, 12 are drawn this way.

The composition of a polymer is counted through its sites, each weighted by the number of its images in the cell divided by Z. An atom shared between repeat units is therefore counted once, whatever excerpt is drawn, and charges are balanced on the same basis. Every polymer is returned as needs_review, because an excerpt is drawn.

Metal–ligand bonds

Contacts are judged against the sum of the two atoms' covalent radii, r₁ + r₂:

A metal–donor contact is marked long (semi-coordinate) when its length, relative to its radius sum, exceeds 1.15 times the shortest on that metal. The axial bonds of a 4+2 copper(II) centre are the typical case. Previews show such contacts dotted. A metal bound to the face of a ring is joined to it by one line and the ring is drawn delocalised, so ferrocene comes out as iron(II) with two cyclopentadienide rings. Every contact is written to the coordination table with its distance and classification.

These thresholds are tunable rules, not chemical facts. Changing them changes the chemistry, which is why the command-line options that set them are not cosmetic.

Bond orders, charges and oxidation states

Bond orders between non-metals are assigned from bond lengths by an exact search that yields a valid Kekulé structure for each aromatic ring. Groups whose terminal oxygen atoms have nearly equal bond lengths, such as carboxylate and nitro groups, are drawn delocalised. Whether the file's hydrogen atoms are complete is judged from the geometry of the carbon atoms. Geometry outranks the hydrogen list: an aromatic CH modelled as CH₂ is corrected and reported.

Charges are assigned in a fixed order:

1. Ligands first. Unfilled valence on a metal-bound O, S or N atom becomes a negative charge, with a few rules for carbenes, borates, halides, hydrides and anionic chelates.
2. Metals last. The metals receive the common oxidation states that make the whole structure neutral and, where parameters exist, agree with their bond-valence sums.
3. No invention. When no such assignment exists, the structure is left charged and a warning is raised. Mixed valence is not invented to reach neutrality.

Charges and oxidation states written in the file can take precedence. That option was switched off for every test reported on this site.

Checks and statuses

Three groups of checks decide the status.

Impossible features

For example a carbon atom with more than four covalent partners, which arises when two alternative positions have both been kept. These are errors.

The formula check

The perceived non-hydrogen formula is compared with the file's sum formula, and any difference is split in two. The part between the file's own atom list and its formula belongs to the depositor: solvent removed from the model, or a formula written for another Z. The part between the perceived structure and the atom list belongs to the program. That part is exact, so every atom of difference is attributed to named sites. Only a difference that nothing in the file explains is a program error. A difference that follows from the disorder conventions passes and is named. Hydrogen atoms are not compared.

Self-consistency

These checks need nothing to compare against. The structure should be neutral, every ligand atom should have a possible valence, and metal bond-valence sums should agree with the oxidation states. A hydrogen atom added by the program is doubted when the charge balance depends on it. Each of these makes the result needs_review.

The written files are also read back and checked against the reference chemistry: identity, bond endpoints, charges, isotopes and supported stereochemistry.

The status is deliberately cautious. Skipping verification never produces ready.

The layout search

Layout programs written for organic molecules have no model of a metal centre carrying many bonds, nor of metals joined by bridging ligands. CIFlat treats layout as a search for coordinates that satisfy stated drawing rules.

What counts as a clean drawing

A validator, independent of the search, measures the diagram as drawn, with labels at their font size. It reports:

• a bond passing over another atom's label;
• overlapping labels;
• a bond hidden beneath its labels;
• coincident atoms;
• anything inside an aromatic ring;
• an aromatic ring that is not a regular polygon.

A drawing with none of these faults is clean. Bond crossings are counted separately, since some graphs cannot be drawn without them. Label legibility is never given up to remove a crossing: a crossing can be traced by eye, but a line through a label cannot be read.

The drawing rules

• 120° at trigonal centres (every sp² carbon) and 180° at linear ones.
• Aromatic rings drawn as regular polygons.
• Bond lengths kept equal; metal–ligand bonds may stretch to make room for labels.
• A molecule with an inversion centre, a twofold axis or a mirror plane is drawn symmetric, unless that breaks another rule.
• The proportions of the chosen document style, by default ACS Document 1996, are used from the start.

How the search runs

Each fragment is laid out by minimising a restraint function, with terms for bond lengths, angles, regular rings and label clearance (L-BFGS-B). The search starts in turn from three layouts:

• the crystal coordinates projected onto their best plane, which have the correct topology;
• a CoordGen layout;
• a radial layout.

Crossings are invisible to a minimiser, so discrete moves are applied between minimisations. A piece joined to the rest through two atoms is reflected, and ligands and metals are shifted, turned or mirrored as rigid bodies. A move is kept only when the validator counts fewer conflicts.

Recurring cores are laid out from templates that may be turned but not deformed: a metal pair spanned by three-atom bridges, a cubane, two flat units face to face, and a wheel of identical sectors. A final pass treats the label and ring rules as constraints. It keeps the least conspicuous move that strictly reduces the faults.

Choosing the best drawing

Up to three searches with different seeds run side by side, each with 45 s per fragment by default. The best drawing is chosen in two steps:

1. first on the faults, in a fixed order of severity;
2. then on a penalty for "taste": equivalent ligands drawn unequally, lost symmetry, unevenly fanned coordination bonds, and sprawling or tilted arrangements.

With the compiled core, deadlines are counted in work done (evaluated restraint terms), not read from the clock. The same input and seed then give the same drawing on any computer; a slower machine takes longer instead of doing less.

Abbreviations

Common groups are written as labels before layout, for example NO₂, CF₃, OMe, Ph and ^tBu. Matching is structural, not textual. A group is contractible only if it hangs off the molecule by a single bond, and never if an atom inside it is bonded to a metal, so the coordination sphere remains visible. A label carries the composition and charge of the group it stands for. The formula, the charge balance and the MOL and SMILES chemistry are therefore those of the drawn-out structure.