Chemical Structure Converter
Interconvert between different chemical structure representations including IUPAC names, SMILES strings, molecular formulas, and common names. Essential for cheminformatics workflows, database standardization, and compound registration in drug discovery and chemical research.
Key Capabilities:
- Multi-Format Conversion: IUPAC names, SMILES, InChI, molecular formulas
- SMILES Validation: Validate SMILES syntax for structural correctness
- Batch Processing: Process multiple compounds for database standardization
- Identifier Lookup: Retrieve all available identifiers for known compounds
- Structure Standardization: Normalize chemical representations for consistency
Input Validation
This skill accepts: compound names (common or IUPAC), SMILES strings, or InChI identifiers. Batch input via CSV or plain text list is also supported.
If the request does not involve converting or validating chemical structure identifiers — for example, asking to predict biological activity, perform docking, or interpret spectra — do not proceed. Instead respond:
"Chemical Structure Converter is designed to interconvert chemical identifiers (names, SMILES, formulas). Please provide a compound name or SMILES string. For other cheminformatics tasks, use a more appropriate tool."
Quick Check
python -m py_compile scripts/main.py
python scripts/main.py --help
Workflow
- Confirm the input identifier type (name, SMILES, IUPAC) and desired output format.
- Validate that the request matches the documented scope; stop if the task requires unsupported assumptions.
- Run the script or apply the documented conversion path with only the inputs available.
- Return a structured result separating assumptions, deliverables, risks, and unresolved items.
- If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.
Fallback: If no identifier is provided, respond: "No chemical identifier provided. Please supply a compound name (--name), SMILES string (--smiles), or IUPAC name (--iupac). Cannot convert without an input identifier."
Core Capabilities
1. Multi-Format Conversion
from scripts.main import ChemicalStructureConverter
converter = ChemicalStructureConverter()
data = converter.name_to_identifiers("aspirin")
# → IUPAC: 2-acetoxybenzoic acid, SMILES: CC(=O)Oc1ccccc1C(=O)O, Formula: C9H8O4, MW: 180.16
| From → To |
Use Case |
| Name → SMILES |
Literature to database |
| SMILES → IUPAC |
Machine to human readable |
| IUPAC → SMILES |
Chemical registration |
| SMILES → Formula |
Quick MW calculation |
2. SMILES Validation
is_valid, message = converter.validate_smiles("CC(=O)Oc1ccccc1C(=O)O")
# → True, "Valid SMILES syntax"
| Check |
Example Error |
| Parentheses |
C(=O — missing closing |
| Ring closures |
C1CC — ring not closed |
| Atom validity |
@ — invalid character |
3. Batch Processing
for compound in compound_list:
data = converter.name_to_identifiers(compound)
if not data:
print(f"Warning: '{compound}' not found in database")
CLI Usage
# Convert by compound name
python scripts/main.py --name aspirin
# Convert SMILES to IUPAC
python scripts/main.py --smiles "CC(=O)Oc1ccccc1C(=O)O"
# Validate SMILES
python scripts/main.py --smiles "CCO" --validate
# List all compounds
python scripts/main.py --list
Parameters
| Parameter |
Type |
Required |
Description |
--name, -n |
string |
No |
Compound name |
--smiles, -s |
string |
No |
SMILES string |
--iupac, -i |
string |
No |
IUPAC name |
--validate |
flag |
No |
Validate SMILES syntax |
--list, -l |
flag |
No |
List available compounds |
Output Requirements
Every final response must make these explicit:
- Objective or requested deliverable
- Inputs used (identifier type and value) and assumptions introduced
- Conversion method applied
- Core result: all available identifiers (SMILES, IUPAC, formula, MW)
- Constraints and risks (local database limited; novel compounds may not be found)
- Unresolved items and next-step checks (validate against PubChem for critical work)
Error Handling
- If no identifier is provided, list the required input options and request clarification.
- If a compound is not found in the local database, flag it and provide direct lookup URLs:
https://pubchem.ncbi.nlm.nih.gov/compound/{compound_name} and https://www.chemspider.com/Search.aspx?q={compound_name}. For programmatic lookup, query the PubChem REST API: https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/name/{name}/JSON. The script should automatically query this endpoint when a compound is not found locally.
- If
scripts/main.py fails, report the failure point and provide manual fallback guidance.
- Do not fabricate SMILES strings, molecular weights, or identifiers.
- Batch mode: Include a summary line:
X/N compounds converted successfully, Y failed (list failed compound names).
- Database versioning: The local compound database version is tracked in
DB_VERSION in scripts/main.py. To add compounds, update the COMPOUND_DB dict and increment DB_VERSION.
Common Pitfalls
- Ambiguous names: Use CAS numbers or specific synonyms for unambiguous lookup
- Stereochemistry omitted: Specify @/@@ in SMILES for chiral compounds
- Hydrates vs anhydrous: Always specify form (e.g., "caffeine anhydrous")
- Duplicate entries: Deduplicate by canonical SMILES when building databases
- Character encoding: Use UTF-8 for IUPAC names with special characters
SMILES Quick Reference
C = aliphatic carbon, c = aromatic carbon= = double bond, # = triple bond() = branching, [] = explicit valence/charge@ = anticlockwise (S), @@ = clockwise (R)
References
Known Limitation: Local database contains common compounds only. Integrate PubChem API for production use.
1---2name: chemical-structure-converter3description: Convert between IUPAC names, SMILES strings, molecular formulas, and common names for chemical compounds. Supports SMILES validation, batch processing, structure standardization, and cheminformatics database preparation for drug discovery workflows.4license: MIT5---6
7# Chemical Structure Converter
8
9Interconvert between different chemical structure representations including IUPAC names, SMILES strings, molecular formulas, and common names. Essential for cheminformatics workflows, database standardization, and compound registration in drug discovery and chemical research.
10
11**Key Capabilities:**
12- **Multi-Format Conversion**: IUPAC names, SMILES, InChI, molecular formulas
13- **SMILES Validation**: Validate SMILES syntax for structural correctness
14- **Batch Processing**: Process multiple compounds for database standardization
15- **Identifier Lookup**: Retrieve all available identifiers for known compounds
16- **Structure Standardization**: Normalize chemical representations for consistency
17
18---
19
20## Input Validation
21
22This skill accepts: compound names (common or IUPAC), SMILES strings, or InChI identifiers. Batch input via CSV or plain text list is also supported.
23
24If the request does not involve converting or validating chemical structure identifiers — for example, asking to predict biological activity, perform docking, or interpret spectra — do not proceed. Instead respond:
25> "Chemical Structure Converter is designed to interconvert chemical identifiers (names, SMILES, formulas). Please provide a compound name or SMILES string. For other cheminformatics tasks, use a more appropriate tool."
26
27---
28
29## Quick Check
30
31```bash
32python -m py_compile scripts/main.py
33python scripts/main.py --help
34```
35
36## Workflow
37
381. Confirm the input identifier type (name, SMILES, IUPAC) and desired output format.
392. Validate that the request matches the documented scope; stop if the task requires unsupported assumptions.
403. Run the script or apply the documented conversion path with only the inputs available.
414. Return a structured result separating assumptions, deliverables, risks, and unresolved items.
425. If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.
43
44**Fallback:** If no identifier is provided, respond: "No chemical identifier provided. Please supply a compound name (`--name`), SMILES string (`--smiles`), or IUPAC name (`--iupac`). Cannot convert without an input identifier."
45
46---
47
48## Core Capabilities
49
50### 1. Multi-Format Conversion
51
52```python
53from scripts.main import ChemicalStructureConverter
54converter = ChemicalStructureConverter()
55data = converter.name_to_identifiers("aspirin")
56# → IUPAC: 2-acetoxybenzoic acid, SMILES: CC(=O)Oc1ccccc1C(=O)O, Formula: C9H8O4, MW: 180.16
57```
58
59| From → To | Use Case |
60|-----------|----------|
61| **Name → SMILES** | Literature to database |
62| **SMILES → IUPAC** | Machine to human readable |
63| **IUPAC → SMILES** | Chemical registration |
64| **SMILES → Formula** | Quick MW calculation |
65
66### 2. SMILES Validation
67
68```python
69is_valid, message = converter.validate_smiles("CC(=O)Oc1ccccc1C(=O)O")
70# → True, "Valid SMILES syntax"
71```
72
73| Check | Example Error |
74|-------|---------------|
75| **Parentheses** | `C(=O` — missing closing |
76| **Ring closures** | `C1CC` — ring not closed |
77| **Atom validity** | `@` — invalid character |
78
79### 3. Batch Processing
80
81```python
82for compound in compound_list:
83 data = converter.name_to_identifiers(compound)
84 if not data:
85 print(f"Warning: '{compound}' not found in database")
86```
87
88---
89
90## CLI Usage
91
92```text
93# Convert by compound name
94python scripts/main.py --name aspirin
95
96# Convert SMILES to IUPAC
97python scripts/main.py --smiles "CC(=O)Oc1ccccc1C(=O)O"
98
99# Validate SMILES
100python scripts/main.py --smiles "CCO" --validate
101
102# List all compounds
103python scripts/main.py --list
104```
105
106---
107
108## Parameters
109
110| Parameter | Type | Required | Description |
111|-----------|------|----------|-------------|
112| `--name`, `-n` | string | No | Compound name |
113| `--smiles`, `-s` | string | No | SMILES string |
114| `--iupac`, `-i` | string | No | IUPAC name |
115| `--validate` | flag | No | Validate SMILES syntax |
116| `--list`, `-l` | flag | No | List available compounds |
117
118---
119
120## Output Requirements
121
122Every final response must make these explicit:
123
124- Objective or requested deliverable
125- Inputs used (identifier type and value) and assumptions introduced
126- Conversion method applied
127- Core result: all available identifiers (SMILES, IUPAC, formula, MW)
128- Constraints and risks (local database limited; novel compounds may not be found)
129- Unresolved items and next-step checks (validate against PubChem for critical work)
130
131---
132
133## Error Handling
134
135- If no identifier is provided, list the required input options and request clarification.
136- If a compound is not found in the local database, flag it and provide direct lookup URLs: `https://pubchem.ncbi.nlm.nih.gov/compound/{compound_name}` and `https://www.chemspider.com/Search.aspx?q={compound_name}`. For programmatic lookup, query the PubChem REST API: `https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/name/{name}/JSON`. The script should automatically query this endpoint when a compound is not found locally.
137- If `scripts/main.py` fails, report the failure point and provide manual fallback guidance.
138- Do not fabricate SMILES strings, molecular weights, or identifiers.
139- **Batch mode:** Include a summary line: `X/N compounds converted successfully, Y failed (list failed compound names).`
140- **Database versioning:** The local compound database version is tracked in `DB_VERSION` in `scripts/main.py`. To add compounds, update the `COMPOUND_DB` dict and increment `DB_VERSION`.
141
142---
143
144## Common Pitfalls
145
146- **Ambiguous names**: Use CAS numbers or specific synonyms for unambiguous lookup
147- **Stereochemistry omitted**: Specify @/@@ in SMILES for chiral compounds
148- **Hydrates vs anhydrous**: Always specify form (e.g., "caffeine anhydrous")
149- **Duplicate entries**: Deduplicate by canonical SMILES when building databases
150- **Character encoding**: Use UTF-8 for IUPAC names with special characters
151
152---
153
154## SMILES Quick Reference
155
156- `C` = aliphatic carbon, `c` = aromatic carbon
157- `=` = double bond, `#` = triple bond
158- `()` = branching, `[]` = explicit valence/charge
159- `@` = anticlockwise (S), `@@` = clockwise (R)
160
161---
162
163## References
164
165- PubChem: https://pubchem.ncbi.nlm.nih.gov
166- ChemSpider: http://www.chemspider.com
167- SMILES Specification: http://opensmiles.org
168- RDKit Documentation: https://www.rdkit.org/docs/
169
170**Known Limitation:** Local database contains common compounds only. Integrate PubChem API for production use.
majiayu000