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.multiplying_prefix(n, kind='simple', table=None)

The multiplying prefix for n identical features, for every n from 2 to 9999.

The one home of the rule, so no producer ever spells a count as digits (21oxa, 33yne, 22kis), a form OPSIN cannot read. “Basic multiplicative prefixes” (the Blue Book, Table 1.4): the basic terms are di tri tetra... icosa, and the numerical terms above 20 are composed by

“Derivation of basic numerical terms” (:2811), as numerical_term

does: 21 henicosa, 22 docosa, 33 tritriaconta, 101 henhecta.

kind="simple" gives that term (the prefix of a suffix, a replacement ‘a’ prefix, an ‘ene’/’yne’ ending, a simple substituent: tritriacontayne, henicosaoxa). kind="complex" gives the term for compound or complex entities, “Numerical terms for compound or complex features” (:2826): “formed by adding the ending ‘kis’ to the basic multiplicative prefix ending in ‘a’”, with ‘bis’ and ‘tris’ for 2 and 3: 4 tetrakis, 21 henicosakis, 231 hentriacontadictakis.

table is a producer’s own {count: word} dict (it may carry 1: ""); its entry for n wins, and only a count it lacks is composed here.

Raises ValueError for an n with no word (below 2 and absent from table, or above 9999), never a digit string: a producer that meets it fails closed instead of emitting a name of the wrong spelling.

The word is the Blue Book’s for every count. OPSIN 2.9.0 reads a simple prefix only up to 50 (‘pentaconta’) and a ‘kis’ prefix up to 30 (‘triacontakis’), so a name past those is spelled right and the read-back gate keeps it from shipping.

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