Charge, mass, formula

These are properties of the ChemicalSystem:

property ChemicalSystem.charge: float

The total charge of the system in atomic units (i.e. in units of elementary charge).

ChemicalSystem.total_mass() → float

Total mass in atomic mass units (dalton).

ChemicalSystem.get_formal_charges() → ndarray[Any, dtype[int64]]

Guess a per-atom formal charge from the elements and the bond orders of the system.

Returns a num_atoms sized integer array with one guessed formal charge per atom.

A ChemicalSystem only stores bond orders and a single total charge, not the formal charge of each individual atom. This method reconstructs a plausible per-atom formal charge, which is for example needed to recognize charge-bearing groups such as nitro, carboxylate or ammonium. It is used internally when converting to RDKit (and hence by to_smiles() and the skeletal-image methods).

The guess is a heuristic:

  • For the common main-group non-metals (H, C, N, O, F, P, S, Cl, Se, Br, I) the charge follows from the deviation of the summed bond order from the element’s typical valence (octet rule). For example a nitrogen with four bonds is assigned +1 and a singly bonded oxygen -1.

  • Atoms of other elements (metals, boron, noble gases, …), atoms without bonds, and expanded-octet cases (e.g. the sulfur of a sulfate) are left uncharged.

  • Any remaining difference between the sum of the guessed charges and the system’s total charge is then distributed over the most suitable atoms so that the total is reproduced.

Because it is a heuristic based only on connectivity, the result is not guaranteed to be chemically correct for every system. It is best-effort in another sense too: the guessed charges sum to the system’s total charge whenever possible, but the sum may fall short if no atom can validly carry the remaining charge. A system without any bonds yields an all-zero array.

To set or get the mass of individual atoms, see Atom Attributes.

ChemicalSystem.formula() → str

Chemical formula in Hill notation (e.g. H2O, CH4):

  • If Carbon is present, the order is: C, H, alphabetical.

  • If Carbon is not present all the elements (including Hydrogen) are listed alphabetically.

  • Single-letter elements come before 2-letters elements (e.g. ‘K’ comes before ‘Kr’, ‘B’ before ‘Be’)