Adapter¶
Bidirectional sync between MolPy objects and external library representations.
Quick reference¶
| Symbol | Summary | Preferred for |
|---|---|---|
Adapter[I, E] |
ABC for internal ↔ external sync | Custom adapter implementations |
RDKitAdapter |
Sync Atomistic ↔ RDKit Mol |
3D generation, substructure search |
OpenBabelAdapter |
Sync Atomistic ↔ OpenBabel OBMol |
Format conversion |
Canonical example¶
from molpy.adapter import RDKitAdapter
from rdkit.Chem import AllChem
adapter = RDKitAdapter(internal=mol)
rd_mol = adapter.get_external()
AllChem.EmbedMolecule(rd_mol)
adapter.set_external(rd_mol)
adapter.sync_to_internal()
optimized = adapter.get_internal()
Key behavior¶
get_external()auto-syncs internal → external if neededget_internal()auto-syncs external → internal if needed- RDKit and OpenBabel are optional dependencies; adapters fail gracefully if not installed
Related¶
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 ¶
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 ¶
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 from internal to external representation.
Subclasses should override _do_sync_to_external() to implement the actual synchronization logic.
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.
Generate3D
dataclass
¶
Generate3D(add_hydrogens=True, sanitize=True, embed=True, optimize=True, max_embed_attempts=10, embed_random_seed=0, max_opt_iters=200, forcefield='UFF', update_internal=True)
RDKit-based 3D generation pipeline for RDKitAdapter.
Pipeline stages (each optional): 1. Add explicit hydrogens 2. Sanitize molecule 3. Generate 3D coordinates via embedding 4. Optimize geometry with force field
Attributes:
| Name | Type | Description |
|---|---|---|
add_hydrogens |
bool
|
Whether to add explicit hydrogens before embedding |
sanitize |
bool
|
Whether to sanitize the molecule |
embed |
bool
|
Whether to perform 3D coordinate embedding |
optimize |
bool
|
Whether to optimize geometry after embedding |
max_embed_attempts |
int
|
Maximum number of embedding attempts |
embed_random_seed |
int | None
|
Random seed for embedding (None for random) |
max_opt_iters |
int
|
Maximum optimization iterations |
forcefield |
str
|
Force field to use ("UFF" or "MMFF94") |
update_internal |
bool
|
Whether to sync internal structure after modifications |
Examples:
OptimizeGeometry
dataclass
¶
RDKit-based geometry optimization for RDKitAdapter.
Attributes:
| Name | Type | Description |
|---|---|---|
max_opt_iters |
int
|
Maximum optimization iterations |
forcefield |
str
|
Force field to use ("UFF" or "MMFF94") |
update_internal |
bool
|
Whether to sync internal structure after optimization |
raise_on_failure |
bool
|
Whether to raise exception on optimization failure |
Examples:
>>> optimizer = OptimizeGeometry(forcefield="UFF", max_opt_iters=200)
>>> result_adapter = optimizer(adapter)
RDKitAdapter ¶
Bases: Adapter[Atomistic, Mol]
Bridge between MolPy's atomistic representation and rdkit.Chem.Mol.
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. |
sync_to_internal ¶
Sync from external to internal representation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
update_topology
|
bool
|
Whether to update topology when internal already exists. |
True
|
generate_3d ¶
Generate 3D coordinates for a molecular structure via RDKit.
Wraps :class:RDKitAdapter + :class:Generate3D into a single
convenience call.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mol
|
'Atomistic'
|
Atomistic structure (typically from parser.parse_molecule) |
required |
add_hydrogens
|
bool
|
Add implicit hydrogens before embedding |
True
|
optimize
|
bool
|
Run force-field geometry optimization after embedding |
True
|
Returns:
| Type | Description |
|---|---|
'Atomistic'
|
New Atomistic with 3D coordinates and (optionally) explicit hydrogens |
OpenBabel¶
openbabel ¶
OpenBabel adapter for MolPy.
This module provides bidirectional synchronization between MolPy's Atomistic structures and OpenBabel's OBMol objects.
OpenBabel is an optional dependency.
OpenBabelAdapter ¶
Bases: Adapter[Atomistic, 'ob.OBMol']
Bridge between MolPy's Atomistic and OpenBabel's OBMol.
OpenBabel provides built-in force field typing via its FFCalcTypes() function, which can be used to compare against our GAFF typifier implementation.
assign_gaff_types ¶
Use OpenBabel's GAFF force field to assign atom types.
Returns:
| Type | Description |
|---|---|
dict[int, str]
|
Dictionary mapping atom index (0-based) to GAFF atom type. |
get_type_comparison ¶
Compare OpenBabel GAFF types against MolPy GAFF typing.
Requires that MolPy Atomistic has already been typed.
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary with comparison statistics and per-atom results. |