Molecule Resolution

Use resolve_molecule() when you want to look up a single molecule from PubChem / ChEMBL and then move it into the rest of the Atomiverse SDK.

If you want the result directly as an Atoms object, use Atoms.from_molecule_resolve() instead.

Basic Usage

from atomiverse import resolve_molecule

mol = resolve_molecule("aspirin")

print(mol.name)
print(mol.formula)
print(mol.molecular_weight)
print(mol.canonical_smiles)

The returned ResolvedMolecule keeps the fields that are most useful in everyday work without exposing a large metadata surface by default.

Load Directly as Atoms

If you do not need the intermediate ResolvedMolecule, you can resolve and load the best match in one step:

from atomiverse import Atoms

atoms = Atoms.from_molecule_resolve("aspirin")
chembl_atoms = Atoms.from_molecule_resolve("CHEMBL25", source="chembl")

This is the most convenient option when your next step is to visualize the structure or pass it into a job.

Choose a Source

The default source is auto, which lets Atomiverse resolve the query across supported sources.

from atomiverse import resolve_molecule

auto_mol = resolve_molecule("aspirin")
pubchem_mol = resolve_molecule("aspirin", source="pubchem")
chembl_mol = resolve_molecule("CHEMBL25", source="chembl")

Supported source values:

• auto
• pubchem
• chembl

Supported Queries

resolve_molecule() accepts common molecule identifiers such as:

• Common names like aspirin and caffeine
• SMILES
• InChI
• InChIKey
• PubChem CID-like input such as CID2244
• ChEMBL IDs such as CHEMBL25

What You Get Back

ResolvedMolecule exposes a compact set of identity and provenance fields:

• resolved_query
• source
• sources
• name
• formula
• molecular_weight
• canonical_smiles
• inchi
• inchikey
• pubchem_cid
• chembl_id
• confidence
• warnings

Example:

from atomiverse import resolve_molecule

mol = resolve_molecule("caffeine")

print(mol.name)
print(mol.canonical_smiles)
print(mol.pubchem_cid)
print(mol.sources)
print(mol.warnings)

Convert Into Structures

Once resolved, the molecule can be converted into the formats that fit the rest of the SDK.

from atomiverse import resolve_molecule

mol = resolve_molecule("caffeine")

atoms = mol.to_ase()
smiles = mol.to_smiles()
sdf = mol.to_sdf()

to_ase() returns an Atomiverse Atoms object, so you can pass it directly into jobs or visualize it in the viewer:

from atomiverse import SinglePointEnergy, resolve_molecule
from atomiverse.levels import GFN2_XTB

mol = resolve_molecule("aspirin")
atoms = mol.to_ase()

job = SinglePointEnergy(
    atoms=atoms,
    level_of_theory=GFN2_XTB,
)
job.submit()

Error Handling

Resolution failures raise SDK-level exceptions with the original query and selected source included in the error message.

from atomiverse import (
    MoleculeResolutionAmbiguityError,
    MoleculeResolutionError,
    MoleculeResolutionNotFoundError,
    MoleculeResolutionUnavailableError,
    resolve_molecule,
)

try:
    mol = resolve_molecule("not-a-real-molecule")
except MoleculeResolutionNotFoundError as exc:
    print(f"Nothing matched: {exc}")
except MoleculeResolutionAmbiguityError as exc:
    print(f"Several incompatible matches were found: {exc}")
except MoleculeResolutionUnavailableError as exc:
    print(f"The source is temporarily unavailable: {exc}")
except MoleculeResolutionError as exc:
    print(f"Resolution failed: {exc}")

Typical Flow

from atomiverse import resolve_molecule

mol = resolve_molecule("aspirin", source="auto")
atoms = mol.to_ase()

print(mol.name)
print(mol.formula)
print(mol.chembl_id)

Use this when you want a convenient lookup/import step before moving into the usual Atoms, viewer, or job workflows.