# Lexichem TK

> Chemical nomenclature conversion: IUPAC name generation and parsing, multi-language support

## Links
- [Full Documentation](https://docs.eyesopen.com/toolkits/python/lexichemtk/index.html)
- [Theory](https://docs.eyesopen.com/toolkits/python/lexichemtk/theory.html)
- [Code Examples](https://docs.eyesopen.com/toolkits/python/lexichemtk/examples_summary.html)
- [API Reference](https://docs.eyesopen.com/toolkits/python/lexichemtk/api.html)

## Core API - Function Quick Reference

### Name Generation
```
OECreateIUPACName(mol: OEMolBase) -> str
  Use for: Generate IUPAC systematic name from molecule structure
  Example: name = OECreateIUPACName(mol)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OECreateIUPACName.html

OEGetIUPACNamStyle() -> int
  Use for: Get current naming style (OpenEye, IUPAC, CAS, Traditional, Systematic)
  Example: style = OEGetIUPACNamStyle()
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEGetIUPACNamStyle.html
```

### Name Parsing
```
OEParseIUPACName(mol: OEMolBase, name: str) -> bool
  Use for: Convert IUPAC name string to molecule structure
  Example: success = OEParseIUPACName(mol, "ethanol")
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEParseIUPACName.html
```

### Language Translation
```
OEToLanguage(name: str, language: int) -> str
  Use for: Translate IUPAC name to specified language
  Example: german_name = OEToLanguage(name, OELanguage_German)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToLanguage.html

OEFromLanguage(name: str, language: int) -> str
  Use for: Translate name from specified language to English
  Example: english_name = OEFromLanguage(german_name, OELanguage_German)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEFromLanguage.html

OEToFrench(name: str) -> str
  Use for: Translate IUPAC name to French
  Example: french_name = OEToFrench(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToFrench.html

OEToGerman(name: str) -> str
  Use for: Translate IUPAC name to German
  Example: german_name = OEToGerman(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToGerman.html

OEToSpanish(name: str) -> str
  Use for: Translate IUPAC name to Spanish
  Example: spanish_name = OEToSpanish(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToSpanish.html

OEToChinese(name: str) -> str
  Use for: Translate IUPAC name to Chinese
  Example: chinese_name = OEToChinese(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToChinese.html

OEToJapanese(name: str) -> str
  Use for: Translate IUPAC name to Japanese
  Example: japanese_name = OEToJapanese(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToJapanese.html
```

### Character Set Conversion
```
OEToUTF8(name: str) -> str
  Use for: Convert name to UTF-8 encoding
  Example: utf8_name = OEToUTF8(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToUTF8.html

OEFromUTF8(name: str) -> str
  Use for: Convert name from UTF-8 encoding
  Example: ascii_name = OEFromUTF8(utf8_name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEFromUTF8.html

OEToHTML(name: str) -> str
  Use for: Convert name to HTML entity encoding
  Example: html_name = OEToHTML(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToHTML.html

OEFromHTML(name: str) -> str
  Use for: Convert name from HTML entity encoding
  Example: plain_name = OEFromHTML(html_name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEFromHTML.html

OEToASCII(name: str) -> str
  Use for: Convert name to ASCII-only representation
  Example: ascii_name = OEToASCII(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEToASCII.html

OEGetIUPACCharSet() -> int
  Use for: Get current character set encoding
  Example: charset = OEGetIUPACCharSet()
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEGetIUPACCharSet.html
```

### Name Formatting
```
OECapitalizeName(name: str) -> str
  Use for: Capitalize first letter of name
  Example: capitalized = OECapitalizeName("ethanol")
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OECapitalizeName.html

OELowerCaseName(name: str) -> str
  Use for: Convert name to lowercase
  Example: lowercase = OELowerCaseName("Ethanol")
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OELowerCaseName.html

OEReorderIndexName(name: str) -> str
  Use for: Reorder locants in name for proper formatting
  Example: reordered = OEReorderIndexName(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEReorderIndexName.html

OENameLocant(name: str) -> str
  Use for: Extract locant information from name
  Example: locant = OENameLocant(name)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OENameLocant.html
```

### Stereochemistry
```
OEGetCIPStereo(mol: OEMolBase) -> str
  Use for: Get CIP stereochemistry descriptors for molecule
  Example: stereo = OEGetCIPStereo(mol)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEGetCIPStereo.html

OESetCIPStereo(mol: OEMolBase) -> bool
  Use for: Assign CIP stereochemistry descriptors to molecule
  Example: success = OESetCIPStereo(mol)
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OESetCIPStereo.html
```

### Licensing
```
OEIUPACIsLicensed() -> bool
  Use for: Check if Lexichem TK is properly licensed
  Example: if OEIUPACIsLicensed(): print("Licensed")
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEIUPACIsLicensed.html

OEIUPACGetVersion() -> str
  Use for: Get Lexichem TK version string
  Example: version = OEIUPACGetVersion()
  See: https://docs.eyesopen.com/toolkits/python/lexichemtk/OEIUPACFunctions/OEIUPACGetVersion.html
```

## Common Patterns - Complete Working Examples

### Pattern: Generate IUPAC Name from SMILES
```python
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "CCO")
name = oechem.OECreateIUPACName(mol)
print(f"IUPAC name: {name}")
# Output: "ethanol"
```
Use when: Converting molecular structures to systematic chemical names

### Pattern: Parse IUPAC Name to Molecule
```python
from openeye import oechem

mol = oechem.OEGraphMol()
success = oechem.OEParseIUPACName(mol, "2-methylpropane")
if success:
    smiles = oechem.OEMolToSmiles(mol)
    print(f"SMILES: {smiles}")
# Output: "CC(C)C"
```
Use when: Converting chemical names to molecular structures for further processing

### Pattern: Translate Name to Multiple Languages
```python
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "CCO")
english_name = oechem.OECreateIUPACName(mol)

french_name = oechem.OEToFrench(english_name)
german_name = oechem.OEToGerman(english_name)
spanish_name = oechem.OEToSpanish(english_name)

print(f"English: {english_name}")
print(f"French: {french_name}")
print(f"German: {german_name}")
print(f"Spanish: {spanish_name}")
```
Use when: Creating multilingual chemical databases or documentation

### Pattern: Convert Between Name Formats
```python
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccccc1")

# Generate different naming styles
openeye_name = oechem.OECreateIUPACName(mol)
# Can set style with OESetIUPACNamStyle() for CAS, Traditional, etc.

print(f"Name: {openeye_name}")
```
Use when: Need different nomenclature conventions (IUPAC, CAS, Traditional)

### Pattern: Handle UTF-8 and HTML Encoding
```python
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "CCO")
name = oechem.OECreateIUPACName(mol)

# Convert to UTF-8 for international characters
utf8_name = oechem.OEToUTF8(name)

# Convert to HTML entities for web display
html_name = oechem.OEToHTML(name)

# Convert back from HTML
plain_name = oechem.OEFromHTML(html_name)

print(f"UTF-8: {utf8_name}")
print(f"HTML: {html_name}")
```
Use when: Displaying chemical names in web applications or handling international text

### Pattern: Process Name File to Structure File
```python
from openeye import oechem

ifs = oechem.oemolistream("names.txt")
ofs = oechem.oemolostream("structures.sdf")

mol = oechem.OEGraphMol()
for line in ifs.GetString():
    name = line.strip()
    if oechem.OEParseIUPACName(mol, name):
        oechem.OEWriteMolecule(ofs, mol)
    else:
        print(f"Failed to parse: {name}")

ifs.close()
ofs.close()
```
Use when: Batch converting chemical names to structure files

### Pattern: Generate Names with Stereochemistry
```python
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "C[C@H](O)CC")

# Ensure stereochemistry is assigned
oechem.OESetCIPStereo(mol)

# Generate name with stereochemistry
name = oechem.OECreateIUPACName(mol)
print(f"Name with stereo: {name}")
# Will include (R) or (S) descriptors
```
Use when: Working with chiral molecules requiring stereochemical specification

### Pattern: Validate and Format Chemical Names
```python
from openeye import oechem

input_name = "ETHANOL"
mol = oechem.OEGraphMol()

# Parse to validate
if oechem.OEParseIUPACName(mol, input_name):
    # Regenerate in standard format
    standard_name = oechem.OECreateIUPACName(mol)
    
    # Apply formatting
    lowercase_name = oechem.OELowerCaseName(standard_name)
    capitalized_name = oechem.OECapitalizeName(lowercase_name)
    
    print(f"Standardized: {capitalized_name}")
else:
    print(f"Invalid name: {input_name}")
```
Use when: Standardizing chemical name formatting in databases

### Pattern: Extract CIP Stereochemistry Descriptors
```python
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "C[C@H](O)[C@@H](O)C")

# Get CIP descriptors
stereo_info = oechem.OEGetCIPStereo(mol)
print(f"CIP descriptors: {stereo_info}")

# Generate name with stereochemistry
name = oechem.OECreateIUPACName(mol)
print(f"Name: {name}")
```
Use when: Need explicit stereochemical descriptors for documentation or analysis

### Pattern: Translate Foreign Language Name to English
```python
from openeye import oechem

# German chemical name
german_name = "Ethanol"  # Example German name

# Convert to English
english_name = oechem.OEFromGerman(german_name)

# Parse to molecule
mol = oechem.OEGraphMol()
if oechem.OEParseIUPACName(mol, english_name):
    smiles = oechem.OEMolToSmiles(mol)
    print(f"SMILES: {smiles}")
```
Use when: Processing chemical literature in foreign languages

### Pattern: Check License and Version
```python
from openeye import oechem

if oechem.OEIUPACIsLicensed():
    version = oechem.OEIUPACGetVersion()
    print(f"Lexichem TK version {version} is licensed")
    
    # Proceed with name generation
    mol = oechem.OEGraphMol()
    oechem.OESmilesToMol(mol, "CCO")
    name = oechem.OECreateIUPACName(mol)
    print(f"Name: {name}")
else:
    print("Lexichem TK is not licensed")
```
Use when: Verifying toolkit availability before processing

## API Decision Guide

- **For structure to name**: use `OECreateIUPACName()` (generates IUPAC systematic name from molecule)
- **For name to structure**: use `OEParseIUPACName()` (converts IUPAC name to molecule object)
- **For language translation**: use `OEToLanguage()` or specific functions like `OEToFrench()`, `OEToGerman()` (translate names to target language)
- **For reverse translation**: use `OEFromLanguage()` or specific functions like `OEFromFrench()`, `OEFromGerman()` (translate foreign names to English)
- **For web display**: use `OEToHTML()` (convert to HTML entities) or `OEToUTF8()` (convert to UTF-8 encoding)
- **For ASCII-only output**: use `OEToASCII()` (removes special characters, converts to plain ASCII)
- **For name formatting**: use `OECapitalizeName()` for title case, `OELowerCaseName()` for lowercase
- **For stereochemistry**: use `OESetCIPStereo()` before name generation, `OEGetCIPStereo()` to extract descriptors
- **For locant handling**: use `OEReorderIndexName()` to standardize locant ordering, `OENameLocant()` to extract locants
- **OEToLanguage() vs specific functions**: use `OEToLanguage(name, OELanguage_German)` for programmatic language selection, use `OEToGerman(name)` for clearer code when language is fixed
- **OEToHTML() vs OEToUTF8()**: use HTML for web pages with entity encoding, use UTF-8 for modern applications with Unicode support

## Common Parameters & Types

**OEMolBase**: Molecule object for structure representation
  - Create with: `mol = oechem.OEGraphMol()` or `mol = oechem.OEMol()`
  - Common in: `OECreateIUPACName()`, `OEParseIUPACName()`, `OESetCIPStereo()`, `OEGetCIPStereo()`
  - Gotcha: Must be initialized before use; `OEParseIUPACName()` modifies the molecule in-place

**name (str)**: Chemical name string
  - Create with: String literal or variable containing IUPAC name
  - Common in: All name translation and formatting functions
  - Typical values: "ethanol", "2-methylpropane", "benzene"
  - Gotcha: Case-sensitive for parsing; use formatting functions to standardize

**language (int)**: Language code constant
  - Create with: Use constants like `OELanguage_German`, `OELanguage_French`, `OELanguage_Spanish`
  - Common in: `OEToLanguage()`, `OEFromLanguage()`
  - Typical values: `OELanguage_German`, `OELanguage_French`, `OELanguage_Spanish`, `OELanguage_Chinese`, `OELanguage_Japanese`
  - Gotcha: Must use predefined constants from `OELanguage` namespace

**charset (int)**: Character set encoding constant
  - Create with: Use constants like `OECharSet_UTF8`, `OECharSet_HTML`, `OECharSet_ASCII`
  - Common in: Character set conversion functions
  - Typical values: `OECharSet_UTF8`, `OECharSet_HTML`, `OECharSet_ASCII`, `OECharSet_Latin1`

**naming style (int)**: Nomenclature convention constant
  - Create with: Use constants like `OEIUPAC_OpenEye`, `OEIUPAC_CAS`, `OEIUPAC_Traditional`, `OEIUPAC_Systematic`
  - Common in: `OEGetIUPACNamStyle()`, affects `OECreateIUPACName()` output
  - Typical values: `OEIUPAC_OpenEye` (default), `OEIUPAC_CAS`, `OEIUPAC_Traditional`, `OEIUPAC_Systematic`
  - Gotcha: Different styles produce different names for the same molecule; OpenEye style is most commonly used

## Return Types & Error Handling

```python
# Pattern 1: Boolean returns for success/failure
mol = oechem.OEGraphMol()
success = oechem.OEParseIUPACName(mol, "ethanol")
if success:
    # Molecule was successfully created
    smiles = oechem.OEMolToSmiles(mol)
else:
    # Name parsing failed - invalid or unrecognized name
    print("Failed to parse name")

# Pattern 2: String returns for name generation
mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "CCO")
name = oechem.OECreateIUPACName(mol)
if name:  # Empty string indicates failure
    print(f"Generated name: {name}")
else:
    print("Failed to generate name")

# Pattern 3: License checking before operations
if not oechem.OEIUPACIsLicensed():
    print("ERROR: Lexichem TK is not licensed")
    exit(1)

# Proceed with operations
mol = oechem.OEGraphMol()
name = oechem.OECreateIUPACName(mol)

# Pattern 4: Handling translation failures
translated = oechem.OEToGerman(english_name)
if not translated or translated == english_name:
    # Translation may have failed or name unchanged
    print("Translation issue - verify input")