orthonym.data.chain_names

Note

Internal API. Names and behaviour may change between releases.

Centralized IUPAC chain naming module.

Provides authoritative chain prefix generation for all carbon chain lengths from 1 to 9999, following IUPAC 2013 Blue Book nomenclature rules.

IUPAC Long Chain Naming System, the Blue Book; numerical terms , Table 1.4 at:2794): - 1-20: Individual retained prefixes (meth, eth, prop,… icos) - 21+: the basic numerical term of the number with its terminal ‘a’ elided

before ‘ane’. The term is built from the basic terms of Table 1.4 cited in the order opposite to the digits (units, tens, hundreds, thousands): - Units (1-9), in association: hen, do, tri, tetra, penta, hexa, hepta,

octa, nona,:2807: ‘1’ is ‘hen’ and ‘2’ is ‘do’ in association, except ‘undeca’, ‘dicta’ and ‘dilia’)

• Tens (10-90): deca, icosa, triaconta, tetraconta,… nonaconta

• Hundreds (100-900): hecta, dicta, tricta, tetracta,… nonacta

• Thousands (1000-9000): kilia, dilia, trilia, tetralia,… nonalia

Joining,:2811): “The composite terms are formed by direct joining of the basic terms, without hyphen(s). The letter ‘i’ in ‘icosa’ is elided after a vowel.” So there is no linking letter: 101 henhecta (Table 1.4), 111 undecahecta, 363 trihexacontatricta, 486 hexaoctacontatetracta, 1001 henkilia (Table 1.4); and ‘icosa’ keeps its ‘i’ unless a vowel precedes it: 21 henicosa, 22 docosa, 120 icosahecta.

References

IUPAC 2013 Blue Book,, Table 1.4 (basic numerical terms) IUPAC 2013 Blue Book, (derivation of basic numerical terms) IUPAC 2013 Blue Book, (unbranched acyclic hydrocarbons)

Examples

>>> get_chain_prefix(1)
'meth'
>>> get_chain_prefix(21)
'henicos'
>>> get_chain_prefix(32)
'dotriacont'
>>> get_chain_prefix(100)
'hect'
>>> get_chain_prefix(101)
'henhect'
>>> get_chain_prefix(120)
'icosahect'
>>> get_chain_prefix(132)
'dotriacontahect'
>>> get_chain_prefix(1000)
'kili'
>>> get_chain_prefix(1001)
'henkili'

orthonym.data.chain_names.UNIT_TERMS = {1: 'hen', 2: 'do', 3: 'tri', 4: 'tetra', 5: 'penta', 6: 'hexa', 7: 'hepta', 8: 'octa', 9: 'nona'}

‘hen’ for 1 and ‘do’ for 2).

orthonym.data.chain_names.get_chain_prefix(n)

Get IUPAC chain prefix for n carbons.

Supports chain lengths from 1 to 9999.

Parameters:

n (int) – Number of carbon atoms (1-9999).

Returns:

IUPAC chain prefix string (e.g., ‘meth’, ‘eth’, ‘henicos’, ‘dotriacont’).

Raises:

ValueError – If n is outside supported range (1-9999).

Return type:

str

Examples

>>> get_chain_prefix(1)
'meth'
>>> get_chain_prefix(10)
'dec'
>>> get_chain_prefix(20)
'icos'
>>> get_chain_prefix(21)
'henicos'
>>> get_chain_prefix(27)
'heptacos'
>>> get_chain_prefix(30)
'triacont'
>>> get_chain_prefix(32)
'dotriacont'
>>> get_chain_prefix(41)
'hentetracont'
>>> get_chain_prefix(53)
'tripentacont'
>>> get_chain_prefix(100)
'hect'
>>> get_chain_prefix(102)
'dohect'
>>> get_chain_prefix(132)
'dotriacontahect'
>>> get_chain_prefix(1000)
'kili'
>>> get_chain_prefix(1001)
'henkili'

orthonym.data.chain_names.numerical_term(n)

The basic numerical term for n (21-9999) in association.

The basic terms of Table 1.4 are cited in the order opposite to the digits (units, tens, hundreds, thousands) and joined directly, without a linking letter; the ‘i’ of ‘icosa’ is elided after a vowel.

Examples: 21 ‘henicosa’, 22 ‘docosa’, 101 ‘henhecta’, 111 ‘undecahecta’, 120 ‘icosahecta’, 363 ‘trihexacontatricta’, 486 ‘hexaoctacontatetracta’, 1001 ‘henkilia’.

orthonym.data.chain_names.get_chain_name(n)

Get full IUPAC chain name (alkane) for n carbons.

Parameters:

n (int) – Number of carbon atoms (1-9999).

Returns:

Full alkane name (e.g., ‘methane’, ‘ethane’, ‘henicosane’).

Return type:

str

Examples

>>> get_chain_name(1)
'methane'
>>> get_chain_name(21)
'henicosane'
>>> get_chain_name(32)
'dotriacontane'

orthonym.data.chain_names.get_alkyl_name(n)

Get IUPAC alkyl substituent name for n carbons.

Uses the standard ‘-yl’ suffix appended to the chain prefix.

Parameters:

n (int) – Number of carbon atoms (1-9999).

Returns:

Alkyl substituent name (e.g., ‘methyl’, ‘ethyl’, ‘henicosyl’).

Return type:

str

Examples

>>> get_alkyl_name(1)
'methyl'
>>> get_alkyl_name(6)
'hexyl'
>>> get_alkyl_name(21)
'henicosyl'
>>> get_alkyl_name(41)
'hentetracontyl'

orthonym.data.chain_names.get_acid_name(n)

Get IUPAC carboxylic acid name for n carbons (including COOH carbon).

Parameters:

n (int) – Number of carbon atoms (1-9999).

Returns:

Acid name (e.g., ‘methanoic acid’, ‘ethanoic acid’, ‘henicosanoic acid’).

Return type:

str

Examples

>>> get_acid_name(1)
'methanoic acid'
>>> get_acid_name(2)
'ethanoic acid'
>>> get_acid_name(28)
'octacosanoic acid'

orthonym.data.chain_names.get_acid_stem(n)

Get IUPAC acid stem (prefix + ‘anoic’) for n carbons.

Used when just the stem is needed without ‘ acid’.

Parameters:

n (int) – Number of carbon atoms (1-9999).

Returns:

Acid stem (e.g., ‘methanoic’, ‘ethanoic’, ‘octacosanoic’).

Return type:

str

Examples

>>> get_acid_stem(2)
'ethanoic'
>>> get_acid_stem(28)
'octacosanoic'

orthonym.data.chain_names.get_anoate_name(n)

Get IUPAC ester suffix (anoate form) for n carbons.

Parameters:

n (int) – Number of carbon atoms (1-9999).

Returns:

Anoate name (e.g., ‘methanoate’, ‘ethanoate’, ‘icosanoate’).

Return type:

str

Examples

>>> get_anoate_name(1)
'methanoate'
>>> get_anoate_name(20)
'icosanoate'

orthonym.data.chain_names.get_enoate_name(n, unsaturation=None)

Systematic (un)saturated -oate stem, with leading (E/Z) stereo block.

Parameters:

• n (int) – Number of carbons including the carbonyl carbon.

• unsaturation – Optional list of (double_bond_locant, 'E'|'Z'|'') tuples (locants counted from the carbonyl carbon = 1). None/empty → the saturated -anoate form (identical to:func:get_anoate_name).

Returns:

e.g. 'octadecanoate' (saturated), '(9Z)-octadec-9-enoate' (1 db), '(9Z,12Z)-octadeca-9,12-dienoate' (2 db). Mirrors the systematic form the chain/ester pipeline already emits for unsaturated fatty esters.

Return type:

str