Adapter

The adapter module handles conversion to and from other chemistry toolkits (e.g. RDKit).

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.

Source code in src/molpy/adapter/base.py

def __init__(
    self,
    internal: InternalT | None = None,
    external: ExternalT | None = None,
) -> None:
    self._internal: InternalT | None = internal
    self._external: ExternalT | None = external

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.

Source code in src/molpy/adapter/base.py

def check(self) -> None:
    """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.
    """

    if self._internal is None and self._external is None:
        raise ValueError(
            "Adapter has neither internal nor external representation set. "
            "Provide at least one of internal=... or external=..."
        )

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.

Source code in src/molpy/adapter/base.py

def sync_to_external(self) -> None:
    """Sync from internal to external representation.

    Subclasses should override _do_sync_to_external() to implement
    the actual synchronization logic.
    """
    if self._internal is None:
        raise ValueError(
            "Cannot sync to external: internal representation is None. "
            "Set internal using set_internal() first."
        )
    self._do_sync_to_external()

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.

Source code in src/molpy/adapter/base.py

def sync_to_internal(self) -> None:
    """Sync from external to internal representation.

    Subclasses should override _do_sync_to_internal() to implement
    the actual synchronization logic.
    """
    if self._external is None:
        raise ValueError(
            "Cannot sync to internal: external representation is None. "
            "Set external using set_external() first."
        )
    self._do_sync_to_internal()

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.

Source code in src/molpy/adapter/rdkit.py

def __init__(
    self,
    internal: Atomistic | None = None,
    external: Chem.Mol | None = None,
) -> None:
    super().__init__(internal, external)
    self._atom_mapper: _AtomMapper | None = None

    if internal is not None:
        self._ensure_atom_ids()

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

Source code in src/molpy/adapter/rdkit.py

def sync_to_internal(self, update_topology: bool = True) -> None:
    """Sync from external to internal representation.

    Args:
        update_topology: Whether to update topology when internal already exists.
    """
    if self._external is None:
        raise ValueError(
            "Cannot sync to internal: external representation is None. "
            "Set external using set_external() first."
        )
    self._do_sync_to_internal(update_topology=update_topology)

Utils

ensure_parent_dir

ensure_parent_dir(path)

Ensure the parent directory for path exists.

Source code in src/molpy/io/utils.py

def ensure_parent_dir(path: Path) -> None:
    """Ensure the parent directory for `path` exists."""

    path.parent.mkdir(parents=True, exist_ok=True)