Core¶
Ligand¶
ctopo.core.ligand
¶
Ligand graph object and construction from an RDKit molecule.
A Ligand is defined by
- an RDKit Mol (source of truth)
- a NetworkX graph representation of that Mol
- an atom partition into donors, skeleton, and substituents
Partition rule (ligand): - donor_atoms are provided by the caller - skeleton_atoms are atoms on any shortest path between any donor pair (excluding donors) - substituent_atoms are all remaining atoms
__all__ = ['SmilesSettings', 'SvgSettings', 'LigandVisualization', 'Ligand', 'ligand_from_mol']
module-attribute
¶
AtomType
¶
Bases: IntEnum
Atom partition labels stored in graph node attribute atom_type.
Ligand(mol, G, donor_atoms, skeleton_atoms, substituent_atoms, smiles_settings=SmilesSettings(), svg_settings=SvgSettings())
dataclass
¶
Ligand represented as an RDKit molecule plus a NetworkX graph and atom partitions.
Attributes:
| Name | Type | Description |
|---|---|---|
mol |
Mol
|
RDKit molecule |
G |
Graph
|
NetworkX graph with node attributes |
donor_atoms |
FrozenSet[int]
|
Frozen set of donor atom indices |
skeleton_atoms |
FrozenSet[int]
|
Frozen set of skeleton atom indices (excluding donors) |
substituent_atoms |
FrozenSet[int]
|
Frozen set of substituent atom indices |
smiles_settings |
SmilesSettings
|
Default settings for SMILES generation in visualization helpers |
svg_settings |
SvgSettings
|
Default settings for SVG generation in visualization helpers |
Visualization
The methods visualize_ligand, visualize_skeleton, and visualize_topology
return (smiles, svg) pairs that are convenient for building dataset browsers.
Keyword arguments for visual style are forwarded to the corresponding functions
in ctopo.visuals:
- visualize_ligand -> ctopo.visuals.prepare_ligand_visual
- visualize_skeleton -> ctopo.visuals.prepare_skeleton_visual
- visualize_topology -> ctopo.visuals.prepare_topology_visual
See ctopo.visuals for the available options.
denticity
property
¶
Returns ligand's denticity
visualize_ligand(**kwargs)
¶
Return ligand visualization (SMILES with donor maps + chemical-like SVG).
Keyword arguments are forwarded to ctopo.visuals.prepare_ligand_visual.
See ctopo.visuals for available options.
visualize_skeleton(donors=True, skeleton=True, bonds=True, **kwargs)
¶
Return skeleton visualization (SMILES + SVG) for this ligand.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
donors
|
bool
|
If True, donor atoms are shown as original elements. If False, donors are dummies labeled 'DA'. |
True
|
skeleton
|
bool
|
If True, skeleton atoms are shown as original elements. If False, skeleton atoms are dummies with empty labels. |
True
|
bonds
|
bool
|
If True, keep original bond orders from the skeleton graph. If False, force all bonds to be single. |
True
|
Keyword arguments are forwarded to ctopo.visuals.prepare_skeleton_visual.
See ctopo.visuals for available options.
visualize_topology(donors=False, **kwargs)
¶
Return topology visualization (SMILES + SVG) for this ligand.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
donors
|
bool
|
If True, donor atoms are shown as original elements. If False, donors are dummies labeled 'DA'. Non-donor atoms are always dummies with empty labels in the topology depiction. |
False
|
Keyword arguments are forwarded to ctopo.visuals.prepare_topology_visual.
See ctopo.visuals for available options.
LigandVisualization(smiles, svg)
dataclass
¶
Simple output container for ligand visualizations.
SmilesSettings(canonical=True, isomeric=False)
dataclass
¶
Settings for SMILES generation.
Mirrors PreparedMol.to_smiles() in ctopo.visuals.
SvgSettings(size=(300, 220), line_width=2, add_atom_indices=False)
dataclass
¶
Settings for SVG generation.
Mirrors PreparedMol.to_svg() in ctopo.visuals.
ligand_from_mol(mol, donor_atoms, smiles_settings=None, svg_settings=None)
¶
Construct a Ligand from an RDKit Mol and explicit donor atom indices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mol
|
Mol
|
RDKit molecule. |
required |
donor_atoms
|
Sequence[int]
|
Atom indices that should be treated as donor atoms. |
required |
smiles_settings
|
Optional[SmilesSettings]
|
Optional default SMILES settings stored in the Ligand and used by visualization helpers. |
None
|
svg_settings
|
Optional[SvgSettings]
|
Optional default SVG settings stored in the Ligand and used by visualization helpers. |
None
|
Returns:
| Type | Description |
|---|---|
Ligand
|
Ligand instance with populated graph and atom partitions. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ValueError
|
If donor atom indices are out of range. |
NodeNotFound
|
If a donor index is not present in the graph. |
mol_to_nx(mol)
¶
Transform an RDKit Mol into a NetworkX Graph.
Adds two extra node attributes useful for atom-pair / topological-torsion style atom typing: - heavy_degree: number of non-hydrogen neighbors (independent of whether H are explicit) - num_pi_electrons: RDKit-style "pi count" used in atom-pairs/torsions (aromatic -> 1, otherwise (heavy_valence - heavy_degree), rounded and floored at 0)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mol
|
Mol
|
RDKit molecule to convert. |
required |
Returns:
| Type | Description |
|---|---|
Graph
|
A NetworkX undirected graph whose nodes correspond to atom indices. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
skeleton_from_donors(G, donor_atoms)
¶
Union of nodes on all shortest paths between all donor-atom pairs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
G
|
Graph
|
NetworkX graph where nodes are atom indices. |
required |
donor_atoms
|
Sequence[int]
|
Donor atom node indices. |
required |
Returns:
| Type | Description |
|---|---|
set[int]
|
Set of atom indices on shortest paths between donor pairs (may include donors). |
Raises:
| Type | Description |
|---|---|
NodeNotFound
|
If a donor index is not present in G. |
validate_atom_indices(n_atoms, indices, name)
¶
Validate and normalize a collection of atom indices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_atoms
|
int
|
Number of atoms in the parent molecule/graph. |
required |
indices
|
Iterable[int]
|
Iterable of atom indices to validate. |
required |
name
|
str
|
Name of the parameter for error messages. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
Sorted list of unique valid indices. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If any index is not an int |
ValueError
|
If any index is out of range [0, n_atoms - 1]. |
Complex¶
ctopo.core.complex
¶
Complex graph object and construction from an RDKit molecule.
A Complex is defined by
- an RDKit Mol (source of truth)
- a NetworkX graph representation of that Mol
- an atom partition into metals, donors, skeleton, and substituents
Partition rule (complex): - metal_atoms are provided by the caller - donor_atoms are all neighbors of metal_atoms (excluding metals) - metals are removed from the graph - skeleton_atoms are atoms on any shortest path between any donor pair (excluding donors) - substituent_atoms are all remaining non-metal atoms
__all__ = ['Complex', 'complex_from_mol']
module-attribute
¶
AtomType
¶
Bases: IntEnum
Atom partition labels stored in graph node attribute atom_type.
Complex(mol, G, metal_atoms, donor_atoms, skeleton_atoms, substituent_atoms)
dataclass
¶
Complex represented as an RDKit molecule plus a NetworkX graph and atom partitions.
Attributes:
| Name | Type | Description |
|---|---|---|
mol |
Mol
|
RDKit molecule |
G |
Graph
|
NetworkX graph with node attributes |
metal_atoms |
FrozenSet[int]
|
Frozen set of metal atom indices |
donor_atoms |
FrozenSet[int]
|
Frozen set of donor atom indices |
skeleton_atoms |
FrozenSet[int]
|
Frozen set of skeleton atom indices (excluding donors) |
substituent_atoms |
FrozenSet[int]
|
Frozen set of substituent atom indices |
_is_dative_bond(b)
¶
_validate_metal_bonding(mol, metal_atoms)
¶
Validate coordination encoding around metal atoms.
Rules
- Metal–nonmetal bonds must be dative and oriented donor -> metal (metal is the end atom of the dative bond).
- Metal–metal bonds are allowed, but must be non-dative.
complex_from_mol(mol, metal_atoms)
¶
Construct a Complex from an RDKit Mol and explicit metal atom indices.
Node attribute atom_type is assigned as:
- int(AtomType.CENTER) for metal atoms (metal centers / center atoms)
- int(AtomType.DONOR) for donor atoms (neighbors of metals, excluding metals)
- int(AtomType.SKELETON) for skeleton atoms (excluding donors/metals)
- int(AtomType.SUBSTITUENT) for remaining non-metal atoms
Skeleton is computed on the graph with metal atoms removed, so shortest paths do not traverse metal centers.
Validity checks (coordination encoding): - metal–nonmetal bonds must be dative and oriented donor -> metal (metal is end atom) - metal–metal bonds are allowed but must be non-dative
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mol
|
Mol
|
RDKit molecule. |
required |
metal_atoms
|
Sequence[int]
|
Atom indices that should be treated as metal centers. |
required |
Returns:
| Type | Description |
|---|---|
Complex
|
Complex instance with populated graph and atom partitions. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ValueError
|
If metal atom indices are out of range or metal_atoms is empty, or if bonding validity checks fail. |
NodeNotFound
|
If a metal index is not present in the graph (shouldn’t happen if mol is consistent). |
mol_to_nx(mol)
¶
Transform an RDKit Mol into a NetworkX Graph.
Adds two extra node attributes useful for atom-pair / topological-torsion style atom typing: - heavy_degree: number of non-hydrogen neighbors (independent of whether H are explicit) - num_pi_electrons: RDKit-style "pi count" used in atom-pairs/torsions (aromatic -> 1, otherwise (heavy_valence - heavy_degree), rounded and floored at 0)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mol
|
Mol
|
RDKit molecule to convert. |
required |
Returns:
| Type | Description |
|---|---|
Graph
|
A NetworkX undirected graph whose nodes correspond to atom indices. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
skeleton_from_donors(G, donor_atoms)
¶
Union of nodes on all shortest paths between all donor-atom pairs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
G
|
Graph
|
NetworkX graph where nodes are atom indices. |
required |
donor_atoms
|
Sequence[int]
|
Donor atom node indices. |
required |
Returns:
| Type | Description |
|---|---|
set[int]
|
Set of atom indices on shortest paths between donor pairs (may include donors). |
Raises:
| Type | Description |
|---|---|
NodeNotFound
|
If a donor index is not present in G. |
validate_atom_indices(n_atoms, indices, name)
¶
Validate and normalize a collection of atom indices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_atoms
|
int
|
Number of atoms in the parent molecule/graph. |
required |
indices
|
Iterable[int]
|
Iterable of atom indices to validate. |
required |
name
|
str
|
Name of the parameter for error messages. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
Sorted list of unique valid indices. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If any index is not an int |
ValueError
|
If any index is out of range [0, n_atoms - 1]. |
Graph and partitioning¶
ctopo.core.graph
¶
NetworkX-based chemical graph initialized from an RDKit Mol.
This module provides a single conversion utility that maps an RDKit molecule to an undirected NetworkX graph with atom and bond attributes.
__all__ = ['mol_to_nx']
module-attribute
¶
AtomType
¶
Bases: IntEnum
Atom partition labels stored in graph node attribute atom_type.
mol_to_nx(mol)
¶
Transform an RDKit Mol into a NetworkX Graph.
Adds two extra node attributes useful for atom-pair / topological-torsion style atom typing: - heavy_degree: number of non-hydrogen neighbors (independent of whether H are explicit) - num_pi_electrons: RDKit-style "pi count" used in atom-pairs/torsions (aromatic -> 1, otherwise (heavy_valence - heavy_degree), rounded and floored at 0)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mol
|
Mol
|
RDKit molecule to convert. |
required |
Returns:
| Type | Description |
|---|---|
Graph
|
A NetworkX undirected graph whose nodes correspond to atom indices. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ctopo.core.partition
¶
Graph-based partitioning utilities (donors/skeleton/substituents) for chemical graphs.
This module contains shared helper functions used by Ligand and Complex constructors, including validation of atom indices and skeleton construction from donor atoms.
__all__ = ['validate_atom_indices', 'skeleton_from_donors']
module-attribute
¶
skeleton_from_donors(G, donor_atoms)
¶
Union of nodes on all shortest paths between all donor-atom pairs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
G
|
Graph
|
NetworkX graph where nodes are atom indices. |
required |
donor_atoms
|
Sequence[int]
|
Donor atom node indices. |
required |
Returns:
| Type | Description |
|---|---|
set[int]
|
Set of atom indices on shortest paths between donor pairs (may include donors). |
Raises:
| Type | Description |
|---|---|
NodeNotFound
|
If a donor index is not present in G. |
validate_atom_indices(n_atoms, indices, name)
¶
Validate and normalize a collection of atom indices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_atoms
|
int
|
Number of atoms in the parent molecule/graph. |
required |
indices
|
Iterable[int]
|
Iterable of atom indices to validate. |
required |
name
|
str
|
Name of the parameter for error messages. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
Sorted list of unique valid indices. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If any index is not an int |
ValueError
|
If any index is out of range [0, n_atoms - 1]. |