Molecular naming¶

vibe-qc can produce IUPAC names from 3D molecular structures and, conversely, build 3D coordinates from chemical names. The naming engine is a standalone, pure-Python package (vibeqc_naming) that works without the C++ extension compiled.

Quick start¶

from vibeqc_naming import name_from_atoms, structure_from_name

# Structure → name
water = [(8, 0, 0, 0.117), (1, 0, 0.757, -0.469), (1, 0, -0.757, -0.469)]
name_from_atoms(water)
# → "water"

# Name → structure  
pyridine = structure_from_name("pyridine")
# → [(7, 1.40, 0.0, 0.0), (6, 0.70, 1.212, 0.0), ...]

Naming from a calculation¶

When using vibeqc.runner.run_job(), the IUPAC name is printed to the .out file by default:

from vibeqc import Molecule
from vibeqc.runner import run_job

mol = Molecule.from_xyz("ethanol.xyz")
run_job(mol, basis="def2-SVP", method="rks", functional="PBE")
# .out file contains:
#   IUPAC name: ethanol

Pass name_molecule=False to suppress the name.

NamedResult¶

The detailed API returns a NamedResult with provenance and confidence:

from vibeqc_naming import name_from_atoms_detailed

result = name_from_atoms_detailed(water)
print(result.name)        # "water"
print(result.source)      # NamingSource.TRIVIAL_IUPAC
print(result.confidence)  # Confidence.HIGH

Confidence levels:

Confidence	Meaning
`high`	Trivial/retained IUPAC name or confident systematic name
`medium`	Systematic name with some uncertainty
`low`	Formula-only compositional name or failed lookup

Built-in structure database¶

83 common molecules are available via structure_from_name():

Category	Examples
Small molecules	water, methane, ammonia, CO₂, HF, HCl, H₂, N₂, O₂
Alkanes	ethane, propane, butane
Alkenes/alkynes	ethylene, acetylene
Aromatics	benzene, toluene, phenol, aniline
Heterocycles	pyridine, pyrrole, furan, imidazole
Functional groups	formaldehyde, formic acid, acetic acid, acetone, acetaldehyde
Alcohols/amines	methanol, ethanol, methylamine
Nucleobases	adenine, thymine, uracil, cytosine, guanine
Amino acids	glycine, alanine
Solvents	DMSO, acetonitrile, dichloromethane, THF
Others	hydrogen peroxide, phosphine, silane, diborane, nitromethane, cyclohexane, benzaldehyde, benzoic acid, dimethyl ether

from vibeqc_naming import structure_from_name, known_names

len(known_names())  # → 83

Surface and slab naming¶

For periodic systems, the engine detects 2D slabs and adsorbed molecules:

from vibeqc_naming import name_from_atoms_with_lattice

# MgO slab + benzene adsorbate
result = name_from_atoms_with_lattice(mgo_benzene_atoms, lattice_vectors)
# → "benzene on magnesia"

The surface database contains 57 common materials (oxides, nitrides, semiconductors, elemental solids).

See Slabs and adsorbates for the periodic calculation setup.

SMILES generation¶

The molecular graph can produce SMILES strings:

from vibeqc_naming.smiles import smiles_from_name

smiles_from_name("benzene")    # → "C1CCCCC1"
smiles_from_name("acetylene")  # → "C#C"

External backends¶

For complex molecules beyond the built-in engine, optional backends provide authoritative IUPAC names:

result = name_from_atoms_detailed(complex_atoms, with_external=True)

Backends tried in order: RDKit (local) → CACTUS REST → PubChem REST. REST API results are cached in a 256-entry LRU to avoid repeated network calls.

API reference¶

`vibeqc_naming.name_from_atoms`	Return the IUPAC name for atoms given as (Z, x, y, z) in A.
`vibeqc_naming.name_from_atoms_detailed`	Return the IUPAC name for atoms with provenance.
`vibeqc_naming.name_molecule`	Return the IUPAC name for a vibe-qc Molecule.
`vibeqc_naming.name_molecule_detailed`	Return the IUPAC name for a vibe-qc Molecule with provenance.
`vibeqc_naming.name_from_graph`	Return the IUPAC name for a `MolecularGraph`.
`vibeqc_naming.formula_to_name`	Quick name lookup from Hill formula alone (no geometry needed).
`vibeqc_naming.name_from_qvf`	Get the IUPAC name for the structure inside a QVF archive.
`vibeqc_naming.structure_from_name`	Generate 3D atom coordinates from a chemical name or formula.
`vibeqc_naming.known_names`	Return all names for which built-in structures are available.
`vibeqc_naming.name_from_atoms_with_lattice`	Name a system that may be a periodic surface/slab.
`vibeqc_naming.name_periodic_system`	Name a periodic system, with surface/slab awareness.