orthonym.decomposition.engine#

Note

Internal API. Names and behaviour may change between releases.

Decomposition engine with quality gating and orchestration.

The engine decides WHETHER to decompose a molecule (quality gate), calls bond_cleavage and fragment_capping to split it, names each fragment recursively, and assembles the final multi-component name.

Quality gate prevents regressions: molecules that the existing pipeline names correctly are left alone. Only molecules with poor names (unknown, suspiciously short, etc.) are decomposed.

orthonym.decomposition.engine.nacyl_float_refusing()#

True inside a refusal scope (_NACYL_FLOAT_REFUSALS); a memo-key component.

orthonym.decomposition.engine.nacyl_float_as_acylamino(amine_smiles, amine_name, acid_name, parent_smiles)#

The name of parent_smiles with its acylated nitrogen cited as the method-(1) acylamino PREFIX of the amine parent (‘(2R)-2-acetamido-…propanoic acid’), in place of the bare ‘N-<acyl>’ float onto a nitrogen that is not a suffix nitrogen.

(the Blue Book): “When a group having preference for citation as a

principal characteristic group is present, the group R-CO-NH-… is named… (1) substitutively, by using a prefix formed by changing the final letter e in the complete name of the amide to o… Method (1) generates preferred IUPAC names.” (:32998). The float cites the acyl group in front of the whole name (‘N-acetyl(2R)-2-amino-…’) and leaves the stereodescriptor of the parent after it, which ‘Naming of stereoisomers’ (:44643) puts “at the front of the complete name when related to the parent structure”.

The amine fragment’s name cites its nitrogen as an ‘amino’ prefix; the acylamino prefix takes its place at the same locant. Which ‘amino’ of the name is that nitrogen is not read from the name: every prefix of the name that is an ‘amino’ is a candidate and a candidate is offered only when OPSIN reads its name back to parent_smiles (full InChI) AND the registered spelling checks (validation.pin_spelling) find nothing wrong with it, exactly one doing so. Declines (None, the float keeps its place) when the nitrogen is not the one primary, acyclic, uncharged nitrogen of the amine fragment, when the amine parent’s principal class is not senior to the amide, when the acid has no simple amide name, when no or several candidates pass, and when OPSIN cannot be run.

orthonym.decomposition.engine.gate_nonsuffix_nacyl_float(amine_smiles, float_name, amine_name=None, *, acid_name=None, parent_smiles=None)#

Decision A gate for a bare N-<acyl> float (the amide branch of _try_single_bond_decompose and fragment_assembly._assemble_amide).

Returns float_name unchanged when the acylated N is a suffix nitrogen (_nacyl_float_n_is_suffix_nitrogen). Otherwise, inside a refusal scope the float is withheld (None) so that a systematic name can be built; outside one the float is not shipped as it stands when the nitrogen can be cited as the method-(1) acylamino prefix of the amine parent (nacyl_float_as_acylamino, given acid_name and parent_smiles): that name, proven by a round trip, is returned instead. Where it cannot be built the float ships as an honest demotion: validated as before, but recorded as a non-PIN fragment, so name_tiered labels any name that carries it below pin_verified. The acylamino name is recorded the same way: it is built from fragment names by a string assembler, which this gate does not certify as the PIN. In the second attempt of the peptide handler for a molecule that has a peptide name (dispatch_table._PEPTIDE_NAME_STANDS) the float is withheld (None) where its locant N would cite the nitrogen of an amino acid that the amine name gives its systematic name (_nacyl_float_on_systematic_amino_acid): the peptide name cites no N, and the name of an acylated amino acid cites N on a retained name only. Every other caller keeps the float as its demotion, where nothing else names the molecule.

orthonym.decomposition.engine.try_decompose(mol, style='pin')#

Attempt decomposition of a molecule into named fragments.

This is the main entry point for the decomposition engine. It: 1. Finds cleavable bonds (ester, amide, phosphodiester, thioester,

glycosidic, sulfonamide, carbamate, ether – 8 types)

  1. Checks if the existing pipeline name is acceptable (quality gate)

  2. Selects the best bond to cleave

  3. Cleaves and caps the fragments

  4. Names each fragment recursively

  5. Assembles the multi-component IUPAC name

Returns None if: - No cleavable bonds exist - The existing pipeline name is good enough (quality gate passes) - Fragment naming fails - Size guard detects non-shrinking fragments

Parameters:

  • mol – RDKit Mol object to decompose.

  • style (str) – Naming style (“pin” for preferred IUPAC names).

Returns:

Multi-component IUPAC name string, or None to fall through to the existing naming pipeline.

Return type:

str | None