orthonym.rules.adducts#

Note

Internal API. Names and behaviour may change between releases.

Adduct / solvate / hydrate nomenclature — Blue Book (Wave-2 P0A).

: “Names are formed by citing the names of individual compounds in the order of the formula connected by long (em) dashes (—). The proportions of components are indicated after the name by an arabic number separated by a solidus from other numbers; arabic numbers and the solidus are placed in parentheses, separated from the name by a space.”

: “organic components in order as described in, inorganic components…; water (if present), is cited last.” General nomenclature: “hydrates may be named by adding the word ‘hydrate’ to the name preceded by an appropriate numerical prefix… Terms such as ‘hemi’ and ‘sesqui’ are also used.”

Fail-closed: name_adduct returns None unless EVERY component fragment is fully nameable and every single-heavy-atom fragment is a recognized inorganic component. Scope: ALL-NEUTRAL fragment sets only — charged multi-fragment input is owned by the salt/ion routing (dispatch priority < 800) and never reaches this module.

Breadth Job 2 (best-effort tier only): a disconnected drawing with a metal in it (‘CC(N)C(=O)O.CC(N)C(=O)O.[Ni]’, six ‘[C-]#N’ with ‘[Fe+2]’) is named as a mixed organic - inorganic adduct of its components – a metal atom by its element name, a metal cation with its charge number, a metal halide or oxide by an additive name – and ships only when OPSIN reads the name back to exactly the drawn structure. Such a name is never a PIN (the Blue Book).

orthonym.rules.adducts.split_components(mol)#

Split a multi-fragment mol into deduped (canonical_smiles, count).

Returns None for single-fragment input or when RDKit cannot split / sanitize the fragments (fail-closed).

orthonym.rules.adducts.component_sort_key(frag_smi)#

Deterministic citation order for one component.

(bucket, seniority index, -heavy_atoms, canonical_smiles): organic components ordered by the seniority of the class of their principal characteristic group: “cited in the order of seniority of classes (see “); components without a suffix-capable PCG (hydrocarbons, N-heterocycles-as-π-bases) rank after all PCG-bearing organics; ties by descending size then canonical SMILES — reproduces every Blue Book example (coronene—trinitrobenzene big-first; benzene—pyridine resolved form).

orthonym.rules.adducts.name_adduct(mol, canonical_smiles=None, style='pin', *, general_fallback=False, allow_aromatic_general=False, general_fallback_unverified=False)#

Name an all-neutral multi-component input per, or None.

Fail-closed refusals (return None; the dispatch cascade then falls through to the honest ‘unknown organic compound’):

  • fewer than 2 DISTINCT components (identical-only sets are not adducts — the dispatch handler keeps the frozen space-join there);

  • no multi-atom component at all;

  • any single-heavy-atom fragment outside SINGLE_ATOM_COMPONENT_NAMES (bare metals -> organometallic routing, never swallowed here);

  • any charged fragment (salt/ion routing owns charged input);

  • ANY component the single-component pipeline cannot name.

: general_fallback / allow_aromatic_general (default False -> byte-identical PIN output) select the complete tier for the per-component namer (see:func:_name_component), so a multi-fragment input whose only unnameable part was a general-engine-only component (silyl-heteroarene, von-Baeyer polyene cage,…) is named under complete instead of abstaining. All other scope (charge / single-atom / proportion assembly / ordering) is unchanged.