orthonym.rules.polyfunctional#

Note

Internal API. Names and behaviour may change between releases.

Polyfunctional compound naming coordinator.

Handles naming of compounds with multiple functional groups: - Principal group (highest seniority) becomes the suffix - Lower-seniority groups become prefixes with locants - Ethers (no seniority) are always named as alkoxy prefixes

Based on IUPAC 2013 Blue Book to.

orthonym.rules.polyfunctional.detect_polyfunctional(mol, functional_groups)#

Determine if a molecule has multiple distinct functional groups.

Returns True if the molecule has 2+ distinct functional groups that participate in naming (excludes unsaturation markers and halogens).

A compound with multiple instances of the SAME group (e.g., diol) is NOT considered polyfunctional by this function - that’s multiplicity.

Parameters:

  • mol – RDKit Mol object

  • functional_groups (Dict[str, List[tuple]]) – Dict from detect_functional_groups

Returns:

True if molecule is polyfunctional (multiple distinct FGs)

Return type:

bool

orthonym.rules.polyfunctional.get_fg_prefix_form(fg_name, mol, atoms, principal_chain)#

Get the prefix form for a functional group.

For most groups, uses the standard prefix from seniority.py. For ethers, determines the alkoxy prefix based on substituent size.

a phase internal notes: chemistry rules lifted to assembly/substituent_prefix_forms.py. This shim consults the new dispatcher first; on None (out-of-14-row-set), falls back to the static PREFIX_FORMS lookup via get_prefix — preserving the original polyfunctional caller’s expectation that any FG in PREFIX_FORMS (e.g., hydroxyl, amino, carboxy) gets its static prefix form returned.

Parameters:

  • fg_name (str) – Name of the functional group

  • mol – RDKit Mol object

  • atoms (tuple) – Atom indices matching this FG instance

  • principal_chain (List[int]) – Atom indices of the principal chain

Returns:

Prefix string (e.g., “hydroxy”, “oxo”, “methoxy”) or None if no prefix

Return type:

str | None

orthonym.rules.polyfunctional.format_fg_prefix(prefix_form, locants, count)#

Format functional group prefix with locants and multiplier.

Per IUPAC, compound substituent prefixes (e.g., methylsulfinyl, methylsulfonyl) are enclosed in parentheses when used with locants. Simple prefixes (hydroxy, oxo, amino) are not parenthesized.

Parameters:

  • prefix_form (str) – Base prefix name (e.g., “hydroxy”, “oxo”, “methoxy”)

  • locants (List[int]) – List of locant positions

  • count (int) – Number of instances

Returns:

Formatted prefix string (e.g., “2-hydroxy”, “3-oxo”, “2-(methylsulfinyl)”)

Return type:

str

orthonym.rules.polyfunctional.get_non_principal_fg_locants(mol, fg_atoms, principal_chain, atom_to_locant, fg_name='')#

Get locants for non-principal functional groups.

For each FG match, find the functional group CENTER atom (the carbon bearing the heteroatom) on the principal chain and return its locant.

Parameters:

  • mol – RDKit Mol object

  • fg_atoms (List[tuple]) – List of atom index tuples for each FG match

  • principal_chain (List[int]) – Atom indices of the principal chain

  • atom_to_locant (Dict[int, int]) – Mapping from atom index to locant

  • fg_name (str) – Name of the functional group (for specialized handling)

Returns:

Sorted list of locants for the functional group positions

Return type:

List[int]

orthonym.rules.polyfunctional.get_non_principal_groups(functional_groups, principal_group)#

Get all functional groups that are not the principal group.

Filters out the principal group and unsaturation markers.

Parameters:

  • functional_groups (Dict[str, List[tuple]]) – Dict from detect_functional_groups

  • principal_group (str | None) – Name of the principal group (or None)

Returns:

Dict of non-principal functional group names to their atom indices

Return type:

Dict[str, List[tuple]]

orthonym.rules.polyfunctional.name_polyfunctional(features)#

Generate IUPAC name for a polyfunctional compound.

This is the main coordinator function for multi-FG naming. If the compound is not polyfunctional, returns None.

Parameters:

features (Any) – MolecularFeatures object with extracted features

Returns:

Complete IUPAC name string, or None if not polyfunctional

Return type:

str | None