orthonym.assembly.resolvers#

Note

Internal API. Names and behaviour may change between releases.

Resolver functions for parent structure classification and suffix resolution.

These are standalone functions that classify a molecule’s parent type and resolve its suffix information, without generating the final name string. They serve as the foundation for aspect-based composition in the composer.

Functions:

resolve_parent: Classify the parent structure type and extract metadata resolve_suffix: Determine suffix text, locants, and multiplier apply_ion_suffix_modification: Transform suffix for ionic species

Design principles:

  • Resolvers are CLASSIFIERS, not name generators

  • parent_label is a tag for handler selection, NOT the final IUPAC name

  • No circular imports: function-level imports for ring detection

  • Compatible with existing MolecularFeatures dataclass

class orthonym.assembly.resolvers.ParentInfo(parent_label, parent_type, atom_count, atom_to_locant=<factory>, is_named_ring=False)#

Bases: object

Describes the resolved parent structure for naming.

NOTE: This is a classification result, not a name generator. parent_label is a classification tag (e.g., “cyclohexane”, “indole”), NOT the final generated name string. It identifies the parent type for downstream handlers that will produce the actual name.

Variables:

  • parent_label (str) – Classification tag (e.g., “cyclohexane”, “indole”, “propane”). Used to select the naming handler. NOT the final IUPAC name.

  • parent_type (str) – One of “chain”, “ring”, “benzene”, “fused_heterocycle”, “polycyclic”, “complex_ring”, “polycyclic_aromatic”.

  • atom_count (int) – Number of atoms in parent (chain length or ring size).

  • atom_to_locant (Dict[int, Any]) – Atom index -> IUPAC locant mapping.

  • is_named_ring (bool) – True for benzene, naphthalene, indole (fixed numbering).

parent_label: str#
parent_type: str#
atom_count: int#
atom_to_locant: Dict[int, Any]#
is_named_ring: bool = False#
class orthonym.assembly.resolvers.SuffixInfo(text='', locants=<factory>, count=0, is_terminal=False)#

Bases: object

Describes the resolved suffix for the principal functional group.

Variables:

  • text (str) – Suffix text (e.g., “ol”, “one”, “oic acid”, “”).

  • locants (List[int]) – Locant positions (e.g., [1,3] for diol, [2] for ketone).

  • count (int) – Number of suffix instances (e.g., 2 for diol).

  • is_terminal (bool) – True if suffix group is always terminal (e.g., -oic acid, -al).

text: str = ''#
locants: List[int]#
count: int = 0#
is_terminal: bool = False#
orthonym.assembly.resolvers.resolve_parent(features, mol)#

Classify the parent structure and extract naming metadata.

Inspects MolecularFeatures to determine the parent type. This is a CLASSIFICATION function – it does NOT generate name strings. The parent_label is a tag used to select the appropriate naming handler.

Priority order (matches assemble_name routing in composer.py):

  1. polycyclic_name set -> polycyclic_aromatic

  2. is_cyclic and complex ring system -> complex_ring

  3. is_benzene -> benzene

  4. ring_type startswith “heterocyclic” -> ring (heterocyclic_aromatic/heterocyclic_saturated)

  5. ring_type in (cycloalkane, cycloalkene, aromatic) -> ring

  6. principal_chain -> chain

  7. Fallback -> chain (methane)

Parameters:

  • features (Any) – MolecularFeatures object with perceived/classified data.

  • mol (Any) – RDKit Mol object.

Returns:

ParentInfo with classification tag, type, atom count, and locant map.

Return type:

ParentInfo

orthonym.assembly.resolvers.resolve_suffix(features, parent_info)#

Determine suffix information for the principal functional group.

Extracts suffix text, locants, count, and terminal status from the features and the resolved parent info. Uses parent_info.atom_count for capacity validation (suffix count cannot exceed parent size).

Parameters:

  • features (Any) – MolecularFeatures object.

  • parent_info (ParentInfo) – ParentInfo from resolve_parent.

Returns:

SuffixInfo with text, locants, count, and is_terminal flag.

Return type:

SuffixInfo

orthonym.assembly.resolvers.apply_ion_suffix_modification(suffix_info, features)#

Apply ion suffix modification to transform neutral suffix to ionic form.

For single-component ions (not salts/zwitterions), modifies the suffix: - Anion: “-ol” -> “-olate”, “-oic acid” -> “-oate”, bare parent -> “-ide” - Cation: “-amine” -> “-aminium”, bare parent -> “-ium”

Salts, zwitterions, and neutral species are returned unchanged.

Parameters:

  • suffix_info (SuffixInfo) – SuffixInfo from resolve_suffix.

  • features (Any) – MolecularFeatures with species_type and total_charge.

Returns:

Modified SuffixInfo for ionic species, or unchanged for neutral/salt/zwitterion.

Return type:

SuffixInfo