Trees and fragments

Trees

ctopo.trees.build

Hierarchy builder for ligand datasets.

This module builds a hierarchical representation of a ligand dataset as a directed acyclic graph (a tree in the typical configuration), where internal nodes correspond to progressively more detailed structural abstractions and leaves correspond to individual ligands (or unique ligands if collapse_leaves=True).

The intended high-level hierarchy is:

denticity -> topology -> skeleton -> ligand

Where: - denticity is Ligand.denticity (number of donor atoms), - topology is the reduced donor-linker topology graph (computed by get_ligands_topology), - skeleton is the ligand skeleton subgraph (computed by get_ligands_skeleton), - ligand leaves represent the original ligand depiction/SMILES.

Levels are configured using LevelSpec objects (or short tuple forms such as ('skeleton', 'da', 'bonds')). Each level yields a grouping key (SMILES) and, for non-denticity nodes, a thumbnail SVG depiction.

Monotonic detail constraint

The level sequence must be hierarchical not only in kind (denticity -> topo -> skeleton -> ligand), but also in the information content ("flags") between adjacent levels.

Example (valid): ('skeleton', 'da') -> ('skeleton', 'da', 'bonds')

Example (invalid, loses information): ('skeleton', 'da') -> ('skeleton', 'bonds')

This constraint is validated by validate_levels.

Performance notes

Generating SVG depictions can be expensive. The builder avoids redundant work by: - computing SMILES keys per ligand per level (cheap), - generating SVG only once per unique (level, SMILES) node, - optionally disabling leaf SVG generation (include_leaf_svg=False).

Output graph format

The returned object is an nx.DiGraph with node attributes suitable for downstream rendering. At minimum, nodes store: - kind: 'root' | 'denticity' | 'topo' | 'skeleton' | 'ligand' - level: a tuple identifier of the level - label: short label - smiles: grouping key (None for root/denticity) - svg: thumbnail (None for root/denticity and optionally leaves) - leaf_count: number of leaf ligands under the node

The graph is expected to be a tree for tree_to_html: each node (except root) has exactly one parent.

LevelId = Union[str, Sequence[str]] module-attribute

_KIND_RANK = {'denticity': 0, 'topo': 1, 'topology': 1, 'skeleton': 2, 'ligand': 3} module-attribute

__all__ = ['LevelSpec', 'level_spec', 'validate_levels', 'build_ligand_tree'] module-attribute

LevelSpec(kind, flags=frozenset()) dataclass

A single hierarchy level specification.

A LevelSpec defines how ligands are grouped at a particular level of the hierarchy.

Parameters:

Name	Type	Description	Default
kind	str	One of: 'denticity', 'topo' (or 'topology'), 'skeleton', 'ligand'.	required
flags	frozenset[str]	A set of optional modifiers affecting how the grouping key and depiction are produced.	frozenset()

Supported flags (case-insensitive): 'da': Preserve original donor atom elements in depictions/SMILES where applicable (otherwise donors are shown as dummy atoms labelled 'DA'). 'bonds' (skeleton only): Preserve original bond orders in skeleton depictions/SMILES (otherwise all single). 'skeleton' (skeleton only): Preserve original elements for skeleton atoms (otherwise dummy atoms).

Notes

validate_levels enforces that adjacent levels are monotone in the information they retain, so that a later level never 'forgets' a previously requested feature.

features property

Features that must not be lost across adjacent levels.

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.

_norm_flag(x)

_smiles_metrics(smiles, cache)

Return (n_atoms, n_bonds, branching, rings) for sorting.

build_ligand_tree(ligands, levels=('denticity', ('topo',), ('skeleton',), ('skeleton', 'bonds'), ('skeleton', 'da', 'bonds'), 'ligand'), ligand_ids=None, collapse_leaves=False, include_leaf_svg=True, topo_kwargs=None, skeleton_kwargs=None, ligand_kwargs=None)

Build a hierarchical tree (as an nx.DiGraph) for a ligand dataset.

The resulting graph groups ligands by successive abstractions defined by levels. Internal nodes represent unique groups at each level; leaf nodes represent ligands.

Parameters:

Name	Type	Description	Default
ligands	Sequence[Ligand]	Input ligands.	required
levels	Sequence[Union[LevelSpec, LevelId]]	Level specification sequence. See LevelSpec and validate_levels.	('denticity', ('topo',), ('skeleton',), ('skeleton', 'bonds'), ('skeleton', 'da', 'bonds'), 'ligand')
ligand_ids	Optional[Sequence[str]]	Optional stable identifiers for ligands, used for leaf labels (non-collapsed mode) and for leaf example lists (collapsed mode).	None
collapse_leaves	bool	If False, create one leaf node per input ligand. If True, create one leaf node per unique ligand SMILES and store occurrences in count.	False
include_leaf_svg	bool	If True, leaf nodes store an SVG depiction. If False, leaves have svg=None.	True
topo_kwargs	Optional[Mapping[str, Any]]	Optional keyword arguments forwarded to ctopo.visuals.prepare_topology_visual.	None
skeleton_kwargs	Optional[Mapping[str, Any]]	Optional keyword arguments forwarded to ctopo.visuals.prepare_skeleton_visual.	None
ligand_kwargs	Optional[Mapping[str, Any]]	Optional keyword arguments forwarded to ctopo.visuals.prepare_ligand_visual.	None

Returns: An nx.DiGraph rooted at a single 'root' node.

Node attributes typically include: `kind`, `level`, `label`, `smiles`, `svg`,
`leaf_count`, and `sort_key`.

Leaf nodes additionally include `count` and (in non-collapsed mode) `source_index`
and/or `source_id`.

Notes

SVG generation is performed only for unique nodes per level (and optionally leaves), to reduce overhead on large datasets.

get_ligands_skeleton(G, atom_type_key='atom_type')

Return the ligand skeleton as an induced subgraph of the original graph.

Skeleton definition

• Prefer precomputed AtomType labels: keep atoms with type in {DONOR, SKELETON}.
• Otherwise compute skeleton as the union of nodes on all shortest paths between donor pairs (plus donors themselves).

Parameters:

Name	Type	Description	Default
G	Graph	Original ligand graph (NetworkX Graph).	required
atom_type_key	str	Node attribute holding AtomType integer codes.	'atom_type'

Returns:

Type	Description
Graph	A copy of the induced skeleton subgraph (same node ids as in G).

Raises:

Type	Description
ValueError	If no donor atoms are present.

get_ligands_topology(G, atom_type_key='atom_type')

Return a simplified topology graph of the ligand (ignore_cycles=False behavior).

Algorithm (mirrors your RDKit reference): - start from ligand skeleton - remove linear linkers (degree-2 non-donors, neighbors not bonded) by contracting - remove bubbles (degree-2 non-donors, neighbors bonded) by deleting - remove remaining linear linkers again - finalize: * donors keep original node attributes * non-donors become dummy nodes with only {'Z': 0} * all edges become single bonds with minimal attrs

Parameters:

Name	Type	Description	Default
G	Graph	Original ligand graph (NetworkX Graph).	required
atom_type_key	str	Node attribute holding AtomType integer codes.	'atom_type'

Returns:

Type	Description
Graph	A new NetworkX Graph representing the ligand topology.

Raises:

Type	Description
ValueError	If no donor atoms are present.

level_spec(level)

Creates LevelSpec object from text description

prepare_ligand_visual(ligand, donor_map_num=1, donor_color=(1.0, 0.8, 0.45), skeleton_bond_color=(0.65, 0.8, 1.0), donor_radius=0.45, mark_donors_in_smiles=True, highlight_skeleton_bonds=True)

Prepare an RDKit Mol of the ligand for drawing and SMILES generation.

Behavior

• starts from ligand.mol (source of truth)
• optionally sets the same atom-map number on all donor atoms
• highlights donor atoms and (optionally) skeleton bonds

Skeleton bonds are computed from the ligand graph partition.

prepare_skeleton_visual(G_skeleton, use_original_donor_atoms=True, use_original_skeleton_atoms=True, use_original_bonds=True, donor_map_num=1, mark_donors_in_smiles=True, donor_color=(1.0, 0.8, 0.45), donor_radius=0.45, donor_label='DA')

Prepare an RDKit Mol for a ligand skeleton graph.

prepare_topology_visual(G_topology, use_original_donor_atoms=False, donor_map_num=1, mark_donors_in_smiles=True, donor_color=(1.0, 0.8, 0.45), donor_radius=0.45, donor_label='DA')

Prepare an RDKit Mol for a ligand topology graph.

validate_levels(levels, *, require_leaf=True)

Validate and normalize a sequence of level specifications.

This function enforces two constraints:

1) Kind order: The level kinds must follow the structural hierarchy: denticity -> topo -> skeleton -> ligand

2) Monotone information retention: Adjacent levels must not lose features. For example: ('skeleton', 'da') -> ('skeleton', 'da', 'bonds') is valid ('skeleton', 'da') -> ('skeleton', 'bonds') is invalid (drops 'da')

Parameters:

Name	Type	Description	Default
levels	Sequence[Union[LevelSpec, LevelId]]	Sequence of LevelSpec or short forms: - 'denticity' - ('topo',) or ('topo', 'da') - ('skeleton',), ('skeleton', 'bonds'), ('skeleton', 'da', 'bonds'), ... - 'ligand'	required
require_leaf	bool	If True, the last level must be 'ligand'.	True

Returns:

Type	Description
List[LevelSpec]	A list of normalized LevelSpec instances.

Raises:

Type	Description
ValueError	if levels are empty, contain unknown kinds, violate kind ordering, violate monotonicity, or (if require_leaf=True) do not end with 'ligand'.

ctopo.trees.html

D3-based HTML renderer for ligand hierarchy trees.

This module turns a ligand hierarchy graph (typically produced by ctopo.trees.build.build_ligand_tree) into an interactive HTML document.

The chemistry-aware work remains in the Python tree builder: - grouping levels are defined by build_ligand_tree; - node depictions are the SVG snippets already stored on graph nodes; - ligand counts are read from leaf_count.

The renderer is only a presentation layer. It serializes the NetworkX tree into a small D3-friendly JSON structure and embeds node SVGs as data URIs so the returned HTML can be written to a single file.

_DEFAULT_ROOT_SVG = '<svg width="659" height="659" viewBox="0 0 659 659" fill="none" xmlns="http://www.w3.org/2000/svg">\n<g clip-path="url(#clip0_234_2)">\n<path d="M367.576 379.19L532.386 544" stroke="#1B1D24" stroke-width="20"/>\n<path d="M422.513 434.127L532.386 544" stroke="#1B1D24" stroke-width="40"/>\n<path d="M182.072 204.873C162.739 226.686 151 255.385 151 286.826C151 355.092 206.341 410.433 274.607 410.433C328.652 410.433 374.596 375.748 391.393 327.423" stroke="#1B1D24" stroke-width="20"/>\n<path d="M234.733 208.635C230.538 210.692 226.48 211.72 222.559 211.719C218.609 211.66 215.053 210.659 211.891 208.717C208.758 206.69 206.262 203.78 204.402 199.987L191.297 173.268C189.409 169.418 188.636 165.663 188.979 162.002C189.38 158.312 190.779 154.917 193.179 151.816C195.55 148.657 198.833 146.048 203.028 143.991C207.28 141.906 211.352 140.907 215.244 140.994C219.165 140.995 222.678 141.981 225.783 143.951C228.945 145.893 231.47 148.789 233.359 152.639L220.43 158.98C219.19 156.451 217.527 154.879 215.443 154.262C213.415 153.616 211.109 153.928 208.523 155.196C205.937 156.464 204.25 158.111 203.462 160.138C202.731 162.136 202.986 164.399 204.226 166.927L217.33 193.646C218.542 196.117 220.176 197.704 222.231 198.407C224.316 199.024 226.651 198.698 229.237 197.43C231.823 196.162 233.481 194.529 234.212 192.531C234.972 190.447 234.746 188.17 233.534 185.699L246.463 179.358C248.323 183.151 249.067 186.92 248.695 190.667C248.352 194.328 246.995 197.738 244.624 200.897C242.282 203.97 238.985 206.549 234.733 208.635Z" fill="#D1D1D1"/>\n<path d="M269.28 197.825L271.683 141.236L253.939 140.482L254.51 127.054L304.385 129.173L303.814 142.601L286.07 141.847L283.667 198.436L269.28 197.825Z" fill="#D1D1D1"/>\n<path d="M319.942 208.985C315.812 206.8 312.624 204.136 310.377 200.992C308.161 197.792 306.937 194.357 306.706 190.687C306.562 186.991 307.478 183.275 309.453 179.542L323.37 153.236C325.345 149.503 327.887 146.684 330.994 144.78C334.187 142.849 337.716 141.928 341.578 142.017C345.471 142.049 349.483 143.158 353.612 145.342C357.798 147.557 360.972 150.25 363.132 153.42C365.379 156.564 366.574 159.984 366.718 163.68C366.949 167.35 366.076 171.052 364.101 174.785L350.184 201.091C348.209 204.824 345.624 207.657 342.431 209.587C339.324 211.491 335.824 212.427 331.931 212.395C328.125 212.336 324.128 211.199 319.942 208.985ZM325.778 197.953C328.324 199.3 330.563 199.652 332.496 199.009C334.516 198.34 336.169 196.789 337.456 194.357L351.373 168.051C352.69 165.562 353.07 163.338 352.514 161.378C351.958 159.419 350.378 157.751 347.776 156.374C345.174 154.997 342.906 154.63 340.973 155.273C339.04 155.915 337.415 157.481 336.099 159.97L322.182 186.276C320.895 188.708 320.514 190.933 321.041 192.949C321.653 194.938 323.232 196.606 325.778 197.953Z" fill="#D1D1D1"/>\n<path d="M346.793 225.616L404.015 185.159L417.815 204.677C420.66 208.701 422.378 212.738 422.968 216.788C423.596 220.891 423.123 224.713 421.551 228.254C420.016 231.847 417.42 234.937 413.762 237.524C410.156 240.073 406.377 241.491 402.425 241.777C398.525 242.026 394.765 241.197 391.143 239.289C387.522 237.382 384.288 234.417 381.443 230.393L375.957 222.632L355.106 237.374L346.793 225.616ZM386.539 215.151L392.026 222.911C393.799 225.419 395.882 226.925 398.276 227.427C400.758 227.945 403.149 227.391 405.448 225.766C407.748 224.14 409.041 222.089 409.328 219.613C409.705 217.152 409.006 214.667 407.233 212.159L401.746 204.399L386.539 215.151Z" fill="#D1D1D1"/>\n<path d="M362.18 281.156C361.982 276.489 362.673 272.392 364.252 268.865C365.896 265.336 368.244 262.546 371.296 260.495C374.414 258.505 378.083 257.42 382.303 257.241L412.037 255.978C416.257 255.799 419.973 256.57 423.185 258.291C426.463 260.073 429.039 262.654 430.912 266.034C432.849 269.411 433.917 273.433 434.115 278.101C434.316 282.833 433.594 286.931 431.947 290.396C430.367 293.922 428.018 296.68 424.9 298.67C421.848 300.722 418.212 301.837 413.992 302.016L384.259 303.279C380.039 303.459 376.289 302.657 373.011 300.875C369.799 299.153 367.224 296.604 365.287 293.227C363.417 289.912 362.381 285.888 362.18 281.156ZM374.649 280.627C374.771 283.504 375.597 285.615 377.128 286.959C378.725 288.365 380.898 289.009 383.648 288.892L413.381 287.629C416.194 287.51 418.307 286.716 419.718 285.246C421.128 283.777 421.771 281.572 421.647 278.631C421.522 275.689 420.694 273.546 419.164 272.202C417.633 270.858 415.461 270.245 412.648 270.365L382.914 271.628C380.165 271.745 378.053 272.539 376.578 274.011C375.17 275.544 374.527 277.749 374.649 280.627Z" fill="#D1D1D1"/>\n</g>\n<defs>\n<clipPath id="clip0_234_2">\n<rect width="659" height="659" fill="white"/>\n</clipPath>\n</defs>\n</svg>' module-attribute

__all__ = ['tree_to_html'] module-attribute

_denticity_svg(denticity, width=659, height=659)

_find_root(G)

_image_data_uri_from_path(path)

_label_svg(label, width=160, height=96)

_node_image(attrs)

_node_name(nid, attrs)

_node_type(attrs)

_sorted_children(G, nid)

_svg_data_uri(svg)

_tree_to_d3_data(G, nid)

_validate_tree(G, root)

tree_to_html(G, root=None, title='cTopo ligand tree', max_children_visible=5, child_item_height_px=120, open_root=True, width=1440, height=1200, d3_url='https://d3js.org/d3.v7.min.js', root_image=None)

Render a ligand tree into a D3-based interactive HTML document.

Parameters:

Name	Type	Description	Default
G	DiGraph	A directed acyclic graph representing a tree. Typically produced by ctopo.trees.build.build_ligand_tree.	required
root	Optional[int]	Optional explicit root node id. If None, the unique node with in-degree 0 is used.	None
title	str	HTML document title and page heading.	'cTopo ligand tree'
max_children_visible	int	Maximum number of child nodes shown in a branch before D3 scrollbars are used.	5
child_item_height_px	int	Approximate child item height. Kept for API compatibility and used as the base vertical spacing for compact nodes.	120
open_root	bool	If True, the root's first level is visible on load.	True
width	int	SVG viewport width in pixels.	1440
height	int	Initial SVG viewport height in pixels.	1200
d3_url	str	URL for the D3 library.	'https://d3js.org/d3.v7.min.js'
root_image	Optional[Union[str, Path]]	Optional image file used for the root node. SVG is recommended; PNG, JPEG, and WebP are also supported. The image is embedded into the returned HTML as a data URI.	None

Returns:

Type	Description
str	A complete HTML document as a string.

Raises:

Type	Description
ValueError	if the graph is not a DAG, does not have exactly one root, or is not tree-like (some nodes have multiple parents).

Fragments

ctopo.fragments

Fragmentation utilities.

This module contains RDKit-based helpers to decompose a Complex into ligand fragments without reconstructing ligand RDKit molecules from graphs.

Current scope (v1): - Bridging ligands are not handled specially: removing metal centers may split a bridging ligand into multiple fragments. This is expected behavior for now.

__all__ = ['LigandCount', 'ligands_from_complex'] module-attribute

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

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.

LigandCount(smiles, ligand, count) dataclass

Unique ligand representative with occurrence count.

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.

_remove_atoms_by_index(mol, atom_indices)

_set_orig_idx_props(mol, prop='orig_idx')

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 mol is None or donor_atoms contains non-integers.
ValueError	If donor atom indices are out of range.
NodeNotFound	If a donor index is not present in the graph.

ligands_from_complex(complex, sanitize_frags=True, smiles_settings=None, svg_settings=None)

Extract ligand fragments from a Complex via RDKit fragmentation.

Assumptions

• complex.metal_atoms and complex.donor_atoms are correct (e.g. Complex was created via ctopo.core.complex.complex_from_mol which validates coordination).

Algorithm

• copy complex.mol
• annotate atoms with int prop 'orig_idx'
• remove metal atoms
• split into fragments via Chem.GetMolFrags(asMols=True)
• for each fragment, recover donor atoms by checking orig_idx ∈ complex.donor_atoms
• build Ligand objects from fragments
• compute unique ligands by canonical+isomeric SMILES (canonical=True, isomericSmiles=True)

Parameters:

Name	Type	Description	Default
complex	Complex	cTopo Complex object.	required
sanitize_frags	bool	Passed to RDKit GetMolFrags(sanitizeFrags=...). Default True.	True
smiles_settings	Optional[SmilesSettings]	Optional Ligand visualization default SMILES settings to store.	None
svg_settings	Optional[SvgSettings]	Optional Ligand visualization default SVG settings to store.	None

Returns:

Type	Description
List[LigandCount]	list of LigandCount (unique ligands with counts), sorted by SMILES.

Raises:

Type	Description
TypeError	If complex.mol is None.