Skip to content

Adapter

Bidirectional sync between MolPy objects and an external library's representation — the in-memory half of MolPy's two bridging patterns. The other half is the wrapper, which shells out to a binary instead.

MolPy keeps one worked example of adapter: RDKitAdapter here. Packing is not an adapter — use molpack (pip install molcrafts-molpack). An example is not a dependency — RDKit is an optional extra (pip install "molcrafts-molpy[rdkit]"), importing molpy never requires it, and no molpy code path routes through it.

Quick reference

Symbol Summary Preferred for
Adapter[I, E] ABC for internal ↔ external sync Your own integration
RDKitAdapter Sync Atomistic ↔ RDKit Mol Reaching RDKit's own algorithms

Canonical example

The examples below share this setup:

import molpy as mp

mol = mp.io.read_smiles("CCO")

# docs: skip — RDKit optional adapter example; not unit-tested
import molpy as mp
from molpy.adapter import RDKitAdapter
from rdkit.Chem import AllChem

mol = mp.io.read_smiles("CCO")

adapter = RDKitAdapter(internal=mol)
rd_mol = adapter.get_external()

AllChem.EmbedMolecule(rd_mol) # RDKit's algorithm, on RDKit's object
AllChem.MMFFOptimizeMolecule(rd_mol)

adapter.set_external(rd_mol)
adapter.sync_to_internal()
optimized = adapter.get_internal() # back to a molpy Atomistic

Do not use it for what MolPy already does

The adapter exists to reach algorithms MolPy does not implement. For anything below, the native path is the supported one and needs no third-party install:

Task Native
3D embedding Conformer — ETKDGv3 → torsion refinement → MMFF94 cleanup
Hydrogens / aromaticity / stereo mp.Perceive().find_hydrogens(...) / .find_aromaticity(...)
SMILES / SMARTS mp.io.read_smiles(...), mp.SmilesIR, mp.SmartsPattern — see Parser
Ring queries mp.RingInfo(mol)
GAFF types AmberTools wrapper — antechamber delegation 
mol_3d, report = mp.conformer.Conformer(add_hydrogens=True, seed=42).generate(mol)

Key behavior

  • get_external() auto-syncs internal → external if needed
  • get_internal() auto-syncs external → internal if needed
  • RDKit is optional; molpy.adapter.RDKitAdapter is None when it is not installed
  • an adapter does data synchronisation only — executing an external binary belongs in a wrapper

Full API

Base

base

Base Adapter class for MolPy.

This module provides the abstract base class for adapters that maintain bidirectional synchronization between MolPy's internal data structures and external representations.

Adapters do NOT execute external tools or spawn subprocesses.

Adapter 

Adapter(internal=None, external=None)

Bases: ABC, Generic[InternalT, ExternalT]

Abstract base class for representation adapters.

Adapters maintain bidirectional synchronization between MolPy's internal data structures (e.g., Atomistic, Frame) and external representations.

Adapters MUST NOT execute external tools or spawn subprocesses.

check 
check()

Validate the adapter has enough state to do useful work.

This is intentionally lightweight and side-effect free. Concrete adapters may override with stronger validation.

sync_to_external 
sync_to_external()

Sync from internal to external representation.

Subclasses should override _do_sync_to_external() to implement the actual synchronization logic.

sync_to_internal 
sync_to_internal()

Sync from external to internal representation.

Subclasses should override _do_sync_to_internal() to implement the actual synchronization logic.

RDKit

rdkit

RDKit adapter for MolPy.

This module provides bidirectional synchronization between MolPy's Atomistic structures and RDKit's Chem.Mol objects.

RDKit is an optional dependency.

RDKitAdapter 

RDKitAdapter(internal=None, external=None)

Bases: Adapter[Atomistic, Mol]

Bridge between MolPy's atomistic representation and rdkit.Chem.Mol.

copy 
copy()

Return a new RDKitAdapter with copied internal and external state.

Both the Atomistic (internal) and Chem.Mol (external) are deep-copied so that the returned adapter is fully independent of the original.

Returns:

Type Description
'RDKitAdapter'

A new RDKitAdapter instance with copied state.
generate_3d 
generate_3d(*, add_hydrogens=True, optimize=True)

Add hydrogens, embed 3D coordinates, and optimize geometry via RDKit.

Returns a new :class:~molpy.core.atomistic.Atomistic with coordinates; this adapter is not mutated. For molpy's native (molrs) embedder, use :class:molpy.conformer.Conformer instead.

sync_to_internal 
sync_to_internal(update_topology=True)

Sync from external to internal representation.

Parameters:

Name Type Description Default
update_topology bool

Whether to update topology when internal already exists.

 True