On this page

API Reference¶

cosmolkit.bio_from_mmcif(text) → BioStructure¶: Parse mmCIF text into a structural object, preserving hierarchy, coordinates and supported metadata; this argument is text, not a file path.

cosmolkit.bio_from_pdb(text) → BioStructure¶: Parse PDB text into a structural object, preserving hierarchy, coordinates and supported source metadata; this argument is text, not a file path.

cosmolkit.canonical_tautomer_from_molecules(molecules) → Molecule¶: Choose the canonical tautomer from the supplied molecules using the configured score terms.

cosmolkit.canonical_tautomer_from_molecules_with_params(molecules, params) → Molecule¶: Choose the canonical tautomer from the supplied molecules using the configured score terms. Uses the supplied configuration object.

cosmolkit.compile_query(query) → CompiledQuery¶: Compile a QueryGraph for reuse by substructure matching without changing its predicates.

cosmolkit.default_tautomer_score_terms() → list[TautomerScoreTerm]¶: Return the built-in named SMARTS tautomer scoring terms.

cosmolkit.element_info(element) → ElementInfo¶

Returns RDKit periodic-table metadata for an element, including the dummy (*).

All elements with atomic numbers 0..=118 are supported. The record contains the canonical symbol, period, outer electron count, complete ordered valence list, Rb0 bond radius in angstroms, and atomic weight. Source-defined zeros and the unrestricted-valence sentinel -1 are preserved.

The returned symbol and valence slice borrow immutable shared table data. This query has no options or errors and does not change any molecule.

cosmolkit.expand_one_letter(code, kind) → Optional[str]¶: Expand a one-letter residue code to a three-letter residue code using the chosen polymer convention.

cosmolkit.expand_one_letter_sequence(seq, kind) → list[str]¶: Expand a sequence of one-letter residue codes to residue names in sequence order.

cosmolkit.explain_path_score(score, size=4) → tuple[tuple[str, int, int], ...]¶: Complete source decoding, including size zero and zero chunks after u64 ends.

cosmolkit.feature_spec(name) → Optional[FeatureSpec]¶: Looks up a generated feature by its exact canonical name.

cosmolkit.feature_specs() → FeatureSpecIter¶: Returns each feature referenced by the generated support matrix once.

cosmolkit.find_residue_info(name) → ResidueInfo¶: Look up a residue code and return its dictionary information, preserving the not-found state.

cosmolkit.find_residue_info_index(name) → int¶: Return the built-in dictionary index for a residue code when found.

cosmolkit.fingerprint_layered_query_with_output_with_params(query, params) → LayeredFingerprintResult¶: Compute layered fixed-width bit fingerprints for a QueryGraph without discarding its predicates; include the requested atom/bit environment metadata.

cosmolkit.fingerprint_layered_query_with_params(query, params) → Fingerprint¶: Compute layered fixed-width bit fingerprints for a QueryGraph without discarding its predicates.

cosmolkit.fingerprint_pattern_query(query) → Fingerprint¶: Compute pattern fixed-width bit fingerprints for a QueryGraph without discarding its predicates.

cosmolkit.fingerprint_pattern_query_with_params(query, params) → Fingerprint¶: Compute pattern fixed-width bit fingerprints for a QueryGraph without discarding its predicates.

cosmolkit.fingerprint_topological_query_with_output_with_params(query, params, request) → TopologicalFingerprintResult¶: Compute topological fixed-width bit fingerprints for a QueryGraph without discarding its predicates; include the requested atom/bit environment metadata.

cosmolkit.fingerprint_topological_query_with_params(query, params) → Fingerprint¶: Compute topological fixed-width bit fingerprints for a QueryGraph without discarding its predicates.

cosmolkit.inchi_to_key(inchi) → str¶: Convert InChI text directly into its InChIKey without constructing a molecule; invalid input raises InchiError.

cosmolkit.maximum_common_substructure(inputs) → McsResult¶: Experimental maximum common query search; inputs are not modified.

cosmolkit.maximum_common_substructure_with_params(inputs, params) → McsResult¶

Find an MCS with explicit options. timeout is in seconds; an interrupted search returns its best partial result with completed == false.

Options requiring ring or valence state use only valid existing assignments; absent state produces the owner’s typed error, never an implicit write-back.

cosmolkit.mol_from_binary(data) → Molecule¶: Read a native COSMolKit archive into a new Molecule, dispatching supported archive versions automatically.

cosmolkit.mol_from_inchi(text, params=None, *, sanitize=None, remove_hs=None) → Molecule¶: Parse InChI text into a new Molecule. sanitize and remove_hs default to True; params and keyword options are mutually exclusive. Invalid input raises InchiError.

cosmolkit.mol_from_mol(text) → Molecule¶: Parse a MOL text block into a Molecule with the selected coordinate policy.

cosmolkit.mol_from_mol2(text) → Molecule¶: Parse a Tripos MOL2 text block into a new Molecule using the read options.

cosmolkit.mol_from_rdkit(rdmol, sanitize=None) → Molecule¶: Copy RDKit graph fields and 3D conformers, as in COSMolKit 0.3.0. None prepares valence only; True sanitizes; False leaves caches unset.

cosmolkit.mol_from_sdf(text) → Molecule¶: Parse an SDF text record into a Molecule with the selected coordinate policy; use SdfRecord when the record may contain a query graph.

cosmolkit.mol_from_smiles(smiles) → Molecule¶: Parse SMILES text into a new Molecule with the selected parsing/sanitization options; invalid input raises SmilesError.

cosmolkit.mol_from_xyz_block(text) → Molecule¶: Parse XYZ without inferring bonds; preserve raw source coordinate values.

cosmolkit.mols_from_records(records, mode) → MoleculeBatch¶: Construct a batch from explicit records, preserving their input order and failure information.

cosmolkit.mols_from_sdf_records(text, errors=None, n_jobs=None) → MoleculeBatch¶: Parse SDF record texts into an ordered batch using the selected error policy; retained parse failures keep their input slots.

cosmolkit.mols_from_smiles_list(smiles) → MoleculeBatch¶

Parse SMILES strings into a MoleculeBatch, preserving input order.

Defaults: sanitize=True, errors=”raise”, one worker. Invalid SMILES raise BatchValidationError; errors=”keep” retains failed slots and errors(). Accepts SmilesParseParams as parse and BatchParams as params, or their fields as keywords. For example: ck.MoleculeBatch.from_smiles_list([“CCO”, “C1CC”], errors=”keep”, n_jobs=1).

cosmolkit.operation_invariant(method) → Optional[OperationInvariantEntry]¶: Looks up an invariant row by the exact generated operation method.

cosmolkit.operation_invariant_matrix() → list[OperationInvariantEntry]¶: Returns the generated operation-invariant matrix without copying its rows.

cosmolkit.operation_parity(method) → Optional[ParityMatrixEntry]¶: Looks up a parity row by the exact generated operation method.

cosmolkit.operation_spec(method) → Optional[MoleculeOpSpec]¶: Looks up a generated operation by its exact canonical method name.

cosmolkit.operation_specs() → list[MoleculeOpSpec]¶: Returns the generated operation declarations in declaration order.

cosmolkit.parity_matrix() → list[ParityMatrixEntry]¶: Returns the generated parity matrix without copying its rows.

cosmolkit.parse_smarts(text) → QueryGraph¶: Parse SMARTS text into a QueryGraph; this is a query, not a concrete Molecule.

cosmolkit.parse_smarts_with_params(text, params) → QueryGraph¶: Parse SMARTS text into a QueryGraph; this is a query, not a concrete Molecule. Uses the supplied configuration object.

cosmolkit.parse_smirks(text) → Reaction¶: Parse reaction SMIRKS text into a Reaction using the canonical reaction parser.

cosmolkit.parse_smirks_with_params(text, params) → Reaction¶: Parse reaction SMIRKS text into a Reaction using the canonical reaction parser. Uses the supplied configuration object.

cosmolkit.property_value_to_text(value) → str¶: Return the property’s lexical text as a Python string without changing its stored value or type.

cosmolkit.protein_from_mmcif(text) → Protein¶: Parse mmCIF text into a structural object, preserving hierarchy, coordinates and supported metadata; this argument is text, not a file path.

cosmolkit.protein_from_pdb(text) → Protein¶: Parse PDB text into a structural object, preserving hierarchy, coordinates and supported source metadata; this argument is text, not a file path.

cosmolkit.reaction_from_smirks(text) → Reaction¶: Parse reaction SMIRKS text into a Reaction; parsing failures raise ReactionParseError.

cosmolkit.residue_code(name) → ResidueCode¶: Return the canonical residue code from a residue identity.

cosmolkit.residue_info(index) → ResidueInfo¶: Return the residue dictionary entry at the supplied index.

cosmolkit.residue_info_checked(index) → Optional[ResidueInfo]¶: Return the residue dictionary entry at the supplied index; reject an invalid index.

cosmolkit.support_matrix() → list[SupportMatrixEntry]¶: Returns the generated support matrix without copying its rows.

cosmolkit.version() → str¶: Return the version identifier recorded by this value or implementation.

cosmolkit.write_cx_smarts(query, params) → str¶: Serialize a QueryGraph to SMARTS text with the selected CX annotations.

cosmolkit.write_smarts(query, params) → str¶: Serialize a QueryGraph to SMARTS text; return the text rather than writing a file.

class cosmolkit.Molecule¶

Owned molecular graph with properties and separate 2D/3D conformers.

Queries do not change the graph. Value transformations return a new molecule; methods ending in an underscore modify this object in place with copy-on-write isolation from other molecules.

Members (407)

add_3d_conformer_(coordinates) → int¶: In place, append a conformer using caller-supplied atom-ordered 3D coordinates. Copy-on-write isolates other molecule values; errors do not commit partial changes.

add_3d_conformer_with_params_(coordinates, params) → int¶: In place, append a conformer using caller-supplied atom-ordered 3D coordinates. Copy-on-write isolates other molecule values; errors do not commit partial changes.

add_hydrogens_() → None¶: In place, add explicit hydrogen atoms with the selected hydrogen/coordinate options. Copy-on-write isolates other molecule values; errors do not commit partial changes.

add_hydrogens_with_params_(params) → None¶: In place, add explicit hydrogen atoms with the selected hydrogen/coordinate options. Copy-on-write isolates other molecule values; errors do not commit partial changes.

align_conformers_(params=None) → ConformerAlignmentReport¶: In place, align the selected stored conformers to a reference conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes. Align selected or all conformers in place and return the ordered source RMS report.

align_conformers_with_params_(params) → ConformerAlignmentReport¶: In place, align the selected stored conformers to a reference conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes.

align_to_(reference, params=None) → AlignmentResult¶: In place, align the selected conformer to the reference molecule. Copy-on-write isolates other molecule values; errors do not commit partial changes. Align this molecule to reference in place and return the applied result.

align_to_with_params_(reference, params) → AlignmentResult¶: In place, align the selected conformer to the reference molecule. Copy-on-write isolates other molecule values; errors do not commit partial changes.

alignment_transform_to(reference, params=None) → AlignmentResult¶

Return an alignment result containing RMSD and the transform for the supplied atom correspondence; do not move either molecule.

Compute the transform aligning this molecule to reference without mutation.

The returned result contains the RMSD, 4x4 transform, and selected atom map. Use with_alignment_to() or align_to_() to apply the transform.

alignment_transform_to_with_params(reference, params) → AlignmentResult¶: Return an alignment result containing RMSD and the transform for the supplied atom correspondence; do not move either molecule. Uses the supplied configuration object.

all_conformer_best_rmsds(params=None) → list[ConformerRmsd]¶: Return best RMSDs for the stored conformer pairs using the configured mapping/symmetry policy. Return best RMSD values for every ordered triangular conformer pair without mutation.

all_conformer_best_rmsds_with_params(params) → list[ConformerRmsd]¶: Return best RMSDs for the stored conformer pairs using the configured mapping/symmetry policy. Uses the supplied configuration object.

apply_reaction(reaction) → ReactionApplyResult¶: Return the product and changed flag from single-reactant in-place-compatible reaction application, without changing this source molecule.

apply_reaction_(reaction) → bool¶: Apply the supported single-reactant reaction in place and return whether the molecule changed.

apply_reaction_with_params(reaction, params) → ReactionApplyResult¶: Return the product and changed flag from single-reactant in-place-compatible reaction application, without changing this source molecule. Uses the supplied configuration object.

apply_reaction_with_params_(reaction, params) → bool¶: Return the product and changed flag from single-reactant in-place-compatible reaction application, without changing this source molecule. Uses the supplied configuration object.

assign_aromaticity_() → None¶: In place, assign aromatic atom and bond flags using the selected aromaticity model. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_aromaticity_with_params_(params) → None¶: In place, assign aromatic atom and bond flags using the selected aromaticity model. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_chiral_tags_from_structure_() → None¶: In place, assign atom chiral tags from the selected stored conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_chiral_tags_from_structure_with_params_(params) → None¶: In place, assign atom chiral tags from the selected stored conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_cip_labels_() → None¶: In place, assign CIP stereochemical descriptors. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_cip_labels_with_options_(options) → None¶: In place, assign CIP stereochemical descriptors. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_radicals_() → None¶: In place, assign atomic radical electron counts. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_ring_families_() → None¶: In place, calculate and install unique ring families. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_ring_families_with_params_(params) → None¶: In place, calculate and install unique ring families. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_rings_() → None¶: In place, calculate and install ring membership and ring information. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_valence_() → None¶: In place, calculate and install the atom valence assignment. Copy-on-write isolates other molecule values; errors do not commit partial changes.

assign_valence_with_params_(params) → None¶: In place, calculate and install the atom valence assignment. Copy-on-write isolates other molecule values; errors do not commit partial changes.

atom(atom_id) → Optional[Atom]¶: Return the read-only Atom at the zero-based graph index, or None if the index is out of range.

atom_metadata(recalculate=True) → list[AtomMetadata]¶: Return atom-indexed metadata. recalculate=True requests a fresh calculation; False requires an existing valid cache and raises ValenceError if it is absent or invalid. Does not modify graph topology.

atom_property(atom, key) → bool | int | float | str | list[int] | list[str] | None¶: Read typed user metadata; missing keys return None.

atom_property_string(id, key) → Optional[str]¶: Return the string projection of an atom property; invalid indices/types raise an error.

atoms() → list[Atom]¶: Return read-only atom values in graph order with recalculated valence metadata. Use atom_metadata(recalculate=False) to inspect an existing valid cache without recalculation.

best_alignment_to(reference, params=None) → AlignmentResult¶: Return the best fitted alignment RMSD and transform across the allowed atom correspondences; leave the molecules unchanged. Return the best source-compatible alignment result without mutating either molecule.

best_alignment_to_with_params(reference, params) → AlignmentResult¶: Return the best fitted alignment RMSD and transform across the allowed atom correspondences; leave the molecules unchanged. Uses the supplied configuration object.

best_rmsd_to(reference, params=None) → float¶: Return the smallest fitted RMSD to the reference over the allowed atom mappings, in angstroms; leave both molecules unchanged. Return the best aligned RMSD without changing either molecule’s coordinates.

best_rmsd_to_with_params(reference, params) → float¶: Return the smallest fitted RMSD to the reference over the allowed atom mappings, in angstroms; leave both molecules unchanged. Uses the supplied configuration object.

bond(bond_id) → Optional[Bond]¶: Return the read-only Bond at the zero-based graph index, or None if the index is out of range.

bond_property_string(id, key) → Optional[str]¶: Return the string projection of a bond property; invalid indices/types raise an error.

bonds() → list[Bond]¶: Return bond rows in graph order.

canonical_tautomer() → Molecule¶: Return the highest-ranked canonical tautomer using the configured scoring rules; leave the source unchanged.

canonical_tautomer_with_params(params) → Molecule¶: Return the highest-ranked canonical tautomer using the configured scoring rules; leave the source unchanged. Uses the supplied configuration object.

chi_0() → float¶: Return the degree-based zeroth-order Chi molecular connectivity index.

chi_0_n() → float¶: Return the 0th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_0_n_with_params(force) → float¶: Return the 0th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_0_v() → float¶: Return the 0th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_0_v_with_params(force) → float¶: Return the 0th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_1() → float¶: Return the degree-based first-order Chi molecular connectivity index.

chi_1_n() → float¶: Return the 1th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_1_n_with_params(force) → float¶: Return the 1th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_1_v() → float¶: Return the 1th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_1_v_with_params(force) → float¶: Return the 1th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_2_n() → float¶: Return the 2th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_2_n_with_params(force) → float¶: Return the 2th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_2_v() → float¶: Return the 2th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_2_v_with_params(force) → float¶: Return the 2th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_3_n() → float¶: Return the 3th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_3_n_with_params(force) → float¶: Return the 3th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_3_v() → float¶: Return the 3th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_3_v_with_params(force) → float¶: Return the 3th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_4_n() → float¶: Return the 4th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_4_n_with_params(force) → float¶: Return the 4th-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_4_v() → float¶: Return the 4th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_4_v_with_params(force) → float¶: Return the 4th-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_n_n(order) → float¶: Return the requested-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_n_n_with_params(order, force) → float¶: Return the requested-order n-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_n_v(order) → float¶: Return the requested-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

chi_n_v_with_params(order, force) → float¶: Return the requested-order valence-weighted Chi molecular connectivity index. Requires prepared valence; does not change the graph.

cip_computed() → bool¶: Return whether the molecule carries the CIP-computed marker.

clear_3d_conformers_() → None¶: In place, remove all stored 3D conformers while retaining the separate 2D state. Copy-on-write isolates other molecule values; errors do not commit partial changes.

compute_2d_coordinates_() → None¶: In place, generate and store 2D drawing coordinates. Copy-on-write isolates other molecule values; errors do not commit partial changes.

compute_2d_coordinates_with_params_(params) → None¶: In place, generate and store 2D drawing coordinates. Copy-on-write isolates other molecule values; errors do not commit partial changes.

conformers_3d() → list[Conformer3D]¶: Return stored 3D conformer values in storage order, preserving each conformer ID.

coordinate_rmsd_to(reference, params=None) → float¶

Return coordinate RMSD to the reference without fitting or modifying either molecule.

Measure RMSD in the existing coordinate frame without alignment or mutation.

This method corresponds to RDKit CalcRMS semantics, including map enumeration and optional terminal-group symmetrization.

coordinate_rmsd_to_with_params(reference, params) → float¶: Return coordinate RMSD to the reference without fitting or modifying either molecule. Uses the supplied configuration object.

coordinates_2d() → Optional[numpy.ndarray[Any, numpy.dtype[numpy.float64]]]¶: Return an independent float64 NumPy array of shape (num_atoms, 2), or None when no 2D conformer is stored. Never generates coordinates or falls back to 3D.

coordinates_3d(conformer_id=0) → numpy.ndarray[Any, numpy.dtype[numpy.float64]]¶: Return an independent float64 NumPy array of shape (num_atoms, 3) for the exact stored conformer ID. Missing or ambiguous selection raises Coordinate3DReadError.

crippen_descriptors() → CrippenTotals¶

Return Wildman-Crippen logP and molar refractivity as CrippenTotals.

This is a read-only molecular query; the source graph and coordinates are unchanged.

crippen_descriptors_with_params(include_hydrogens, force) → CrippenTotals¶

Return Wildman-Crippen logP and molar refractivity as CrippenTotals. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

detect_chemistry_problems() → ChemistryProblemReport¶: Return structured chemistry problems without committing a sanitized molecule.

detect_chemistry_problems_with_params(params) → ChemistryProblemReport¶: Return structured chemistry problems without committing a sanitized molecule. Uses the supplied configuration object.

dg_bounds_matrix() → numpy.ndarray[Any, Any]¶: Return the atom-pair lower/upper bounds matrix used by distance-geometry embedding.

distance_matrix() → DenseMatrix¶: Return the atom-ordered graph-distance matrix using the selected bond/atom weight options.

distance_matrix_3d() → DenseMatrix¶: Return the atom-ordered Euclidean distance matrix for the selected stored 3D conformer, in angstroms.

distance_matrix_3d_with_params(params) → DenseMatrix¶: Return the atom-ordered Euclidean distance matrix for the selected stored 3D conformer, in angstroms. Uses the supplied configuration object.

distance_matrix_with_params(params) → DenseMatrix¶: Return the atom-ordered graph-distance matrix using the selected bond/atom weight options. Uses the supplied configuration object.

embed_3d_conformer_(params=None) → None¶: In place, embed one 3D conformer using the selected distance-geometry parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

embed_3d_conformer_result_(params=None) → EmbedMoleculeResult¶: In place, embed one 3D conformer and report its ID and updated embedding parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

embed_3d_conformer_result_with_params_(params) → EmbedMoleculeResult¶: In place, embed one 3D conformer and report its ID and updated embedding parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

embed_3d_conformer_with_params_(params) → None¶: In place, embed one 3D conformer using the selected distance-geometry parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

embed_3d_conformers_(num_confs, params=None) → None¶: In place, embed the requested number of 3D conformers using the selected distance-geometry parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

embed_3d_conformers_result_(num_confs, params=None) → EmbedMultipleConfsResult¶: In place, embed multiple 3D conformers and report generated IDs and embedding parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

embed_3d_conformers_result_with_params_(num_confs, params) → EmbedMultipleConfsResult¶: In place, embed multiple 3D conformers and report generated IDs and embedding parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

embed_3d_conformers_with_params_(num_confs, params) → None¶: In place, embed the requested number of 3D conformers using the selected distance-geometry parameters. Copy-on-write isolates other molecule values; errors do not commit partial changes.

enumerate_stereoisomers() → StereoisomerIterator¶: Return molecules for the allowed stereoisomers using StereoisomerOptions; leave the source unchanged.

enumerate_stereoisomers_with_options(options) → StereoisomerIterator¶: Return molecules for the allowed stereoisomers using StereoisomerOptions; leave the source unchanged. Uses the supplied configuration object.

enumerate_stereoisomers_with_random_bits(options, callback) → StereoisomerIterator¶: Enumerate stereoisomers using the supplied random-bit callback for sampling.

enumerate_tautomers() → TautomerEnumeration¶: Enumerate tautomers and return a TautomerEnumeration containing molecules, status and modified atom/bond indices.

enumerate_tautomers_with_params(params) → TautomerEnumeration¶: Enumerate tautomers and return a TautomerEnumeration containing molecules, status and modified atom/bond indices. Uses the supplied configuration object.

exact_molecular_weight() → float¶

Return the monoisotopic molecular mass, respecting explicit isotope labels.

This is a read-only molecular query; the source graph and coordinates are unchanged.

exact_molecular_weight_with_params(only_heavy) → float¶

Return the monoisotopic molecular mass, respecting explicit isotope labels. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

find_chiral_centers(include_unassigned=False) → list[tuple[int, str]]¶: Return atom indices and assigned or unspecified stereocenter labels using the selected options.

fingerprint_atom_pair() → Fingerprint¶: Compute atom pair fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_atom_pair_count() → SparseCountFingerprint32¶: Compute atom pair folded feature counts for this molecule without changing its graph or coordinates.

fingerprint_atom_pair_count_with_params(params, additional_output) → SparseCountFingerprint32¶: Compute atom pair folded feature counts for this molecule without changing its graph or coordinates.

fingerprint_atom_pair_sparse() → SparseBitFingerprint¶: Compute atom pair sparse feature bits for this molecule without changing its graph or coordinates.

fingerprint_atom_pair_sparse_count() → SparseCountFingerprint¶: Compute atom pair sparse feature counts for this molecule without changing its graph or coordinates.

fingerprint_atom_pair_sparse_count_with_params(params, additional_output) → SparseCountFingerprint¶: Compute atom pair sparse feature counts for this molecule without changing its graph or coordinates.

fingerprint_atom_pair_sparse_with_params(params, additional_output) → SparseBitFingerprint¶: Compute atom pair sparse feature bits for this molecule without changing its graph or coordinates.

fingerprint_atom_pair_with_params(params, additional_output) → Fingerprint¶: Compute atom pair fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_avalon() → Fingerprint¶: RDKit Python defaults; accepts configuration objects or keyword options.

fingerprint_avalon_with_params(params) → Fingerprint¶: Compute avalon fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_layered() → Fingerprint¶: Compute layered fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_layered_with_output() → LayeredFingerprintResult¶: Compute layered fixed-width bit fingerprints for this molecule without changing its graph or coordinates; include the requested atom/bit environment metadata.

fingerprint_layered_with_output_with_params(params) → LayeredFingerprintResult¶: Compute layered fixed-width bit fingerprints for this molecule without changing its graph or coordinates; include the requested atom/bit environment metadata.

fingerprint_layered_with_params(params) → Fingerprint¶: Compute layered fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_maccs() → Fingerprint¶: Compute maccs fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_maccs_raw() → Fingerprint¶: Compute maccs fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_maccs_with_params(params) → Fingerprint¶: Compute maccs fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_morgan() → Fingerprint¶: Compute morgan fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_morgan_count() → SparseCountFingerprint32¶: Compute morgan folded feature counts for this molecule without changing its graph or coordinates.

fingerprint_morgan_count_with_generator(generator, *, params=None, output=None) → SparseCountFingerprint32¶: Compute morgan folded feature counts for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_morgan_count_with_params(params, additional_output) → SparseCountFingerprint32¶: Compute morgan folded feature counts for this molecule without changing its graph or coordinates.

fingerprint_morgan_sparse() → SparseBitFingerprint¶: Compute morgan sparse feature bits for this molecule without changing its graph or coordinates.

fingerprint_morgan_sparse_count() → SparseCountFingerprint¶: Compute morgan sparse feature counts for this molecule without changing its graph or coordinates.

fingerprint_morgan_sparse_count_with_generator(generator, *, params=None, output=None) → SparseCountFingerprint¶: Compute morgan sparse feature counts for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_morgan_sparse_count_with_params(params, additional_output) → SparseCountFingerprint¶: Compute morgan sparse feature counts for this molecule without changing its graph or coordinates.

fingerprint_morgan_sparse_with_generator(generator, *, params=None, output=None) → SparseBitFingerprint¶: Compute morgan sparse feature bits for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_morgan_sparse_with_params(params, additional_output) → SparseBitFingerprint¶: Compute morgan sparse feature bits for this molecule without changing its graph or coordinates.

fingerprint_morgan_with_generator(generator, *, params=None, output=None) → Fingerprint¶: Compute morgan fixed-width bit fingerprints for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_morgan_with_params(params, additional_output) → Fingerprint¶: Compute morgan fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_pattern() → Fingerprint¶: Compute pattern fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_pattern_with_params(params) → Fingerprint¶: Compute pattern fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_topological() → Fingerprint¶: Compute topological fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion() → Fingerprint¶: Compute topological torsion fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion_count() → SparseCountFingerprint32¶: Compute topological torsion folded feature counts for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion_count_legacy() → SparseCountFingerprint¶: Compute topological torsion folded feature counts for this molecule without changing its graph or coordinates using the torsion-vector entry point.

fingerprint_topological_torsion_count_legacy_with_params(params) → SparseCountFingerprint¶: Compute topological torsion folded feature counts for this molecule without changing its graph or coordinates using the torsion-vector entry point.

fingerprint_topological_torsion_count_with_generator(generator, *, params=None, output=None) → SparseCountFingerprint32¶: Compute topological torsion folded feature counts for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_topological_torsion_count_with_params(params, additional_output) → SparseCountFingerprint32¶: Compute topological torsion folded feature counts for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion_legacy() → Fingerprint¶: Compute topological torsion fixed-width bit fingerprints for this molecule without changing its graph or coordinates using the torsion-vector entry point.

fingerprint_topological_torsion_legacy_with_params(params) → Fingerprint¶: Compute topological torsion fixed-width bit fingerprints for this molecule without changing its graph or coordinates using the torsion-vector entry point.

fingerprint_topological_torsion_sparse() → SparseBitFingerprint¶: Compute topological torsion sparse feature bits for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion_sparse_count() → SparseCountFingerprint¶: Compute topological torsion sparse feature counts for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion_sparse_count_legacy() → SparseCountFingerprint¶: Compute topological torsion sparse feature counts for this molecule without changing its graph or coordinates using the torsion-vector entry point.

fingerprint_topological_torsion_sparse_count_legacy_with_params(params) → SparseCountFingerprint¶: Compute topological torsion sparse feature counts for this molecule without changing its graph or coordinates using the torsion-vector entry point.

fingerprint_topological_torsion_sparse_count_with_generator(generator, *, params=None, output=None) → SparseCountFingerprint¶: Compute topological torsion sparse feature counts for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_topological_torsion_sparse_count_with_params(params, additional_output) → SparseCountFingerprint¶: Compute topological torsion sparse feature counts for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion_sparse_with_generator(generator, *, params=None, output=None) → SparseBitFingerprint¶: Compute topological torsion sparse feature bits for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_topological_torsion_sparse_with_params(params, additional_output) → SparseBitFingerprint¶: Compute topological torsion sparse feature bits for this molecule without changing its graph or coordinates.

fingerprint_topological_torsion_with_generator(generator, *, params=None, output=None) → Fingerprint¶: Compute topological torsion fixed-width bit fingerprints for this molecule without changing its graph or coordinates using the supplied generator and per-call options.

fingerprint_topological_torsion_with_params(params, additional_output) → Fingerprint¶: Compute topological torsion fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fingerprint_topological_with_output() → TopologicalFingerprintResult¶: Compute topological fixed-width bit fingerprints for this molecule without changing its graph or coordinates; include the requested atom/bit environment metadata.

fingerprint_topological_with_output_with_params(params, request) → TopologicalFingerprintResult¶: Compute topological fixed-width bit fingerprints for this molecule without changing its graph or coordinates; include the requested atom/bit environment metadata.

fingerprint_topological_with_params(params) → Fingerprint¶: Compute topological fixed-width bit fingerprints for this molecule without changing its graph or coordinates.

fraction_csp3() → float¶

Return the fraction of carbon atoms with sp3 hybridization.

This is a read-only molecular query; the source graph and coordinates are unchanged.

fragments() → list[Molecule]¶: Return sanitized connected components in source order, copying conformers. The source molecule is unchanged; empty input returns an empty list.

static from_binary(data) → Molecule¶: Read a native COSMolKit archive into a new Molecule, dispatching supported archive versions automatically.

static from_inchi(text, params=None, *, sanitize=None, remove_hs=None) → Molecule¶: Parse InChI text into a new Molecule. sanitize and remove_hs default to True; params and keyword options are mutually exclusive. Invalid input raises InchiError.

static from_inchi_with_params(text, params) → Molecule¶: Parse InChI text into a new Molecule. sanitize and remove_hs default to True; params and keyword options are mutually exclusive. Invalid input raises InchiError. Uses the supplied configuration object.

static from_mol(text) → Molecule¶: Parse a MOL text block into a Molecule with the selected coordinate policy.

static from_mol2(text) → Molecule¶: Parse a Tripos MOL2 text block into a new Molecule using the read options.

static from_mol2_with_params(text, params) → Molecule¶: Parse a Tripos MOL2 text block into a new Molecule using the read options. Uses the supplied configuration object.

static from_mol_with_params(text, params) → Molecule¶: Parse a MOL text block into a Molecule with the selected coordinate policy. Uses the supplied configuration object.

static from_parts(topology, coordinates, properties) → Molecule¶: Construct a value from explicit detached parts; required structural consistency is checked at the public boundary.

classmethod from_rdkit(rdmol, sanitize=None) → Molecule¶: Copy RDKit graph fields and 3D conformers, as in COSMolKit 0.3.0. None prepares valence only; True sanitizes; False leaves caches unset.

static from_sdf(text) → Molecule¶: Parse an SDF text record into a Molecule with the selected coordinate policy; use SdfRecord when the record may contain a query graph.

static from_sdf_with_params(text, params) → Molecule¶: Parse an SDF text record into a Molecule with the selected coordinate policy; use SdfRecord when the record may contain a query graph. Uses the supplied configuration object.

static from_smiles(smiles) → Molecule¶: Parse SMILES text into a new Molecule with the selected parsing/sanitization options; invalid input raises SmilesError.

static from_smiles_with_params(input, params) → Molecule¶: Parse SMILES text into a new Molecule with the selected parsing/sanitization options; invalid input raises SmilesError. Uses the supplied configuration object.

static from_xyz_block(text) → Molecule¶: Parse XYZ without inferring bonds; preserve raw source coordinate values.

hall_kier_alpha() → float¶

Return the Hall-Kier alpha correction from the stored atomic hybridization state.

This is a read-only molecular query; the source graph and coordinates are unchanged.

hall_kier_alpha_with_contributions() → tuple[float, list[float]]¶

Return the Hall-Kier alpha value and atom-indexed contribution values.

This is a read-only molecular query; the source graph and coordinates are unchanged.

has_2d_coordinates() → bool¶: Return whether a 2D conformer is stored; do not generate coordinates or use a 3D fallback.

has_substruct_match(query) → bool¶: Return whether the query matches this molecule using the supplied matching configuration.

has_substruct_match_with_params(query, params) → bool¶: Return whether the query matches this molecule using the supplied matching configuration. Uses the supplied configuration object.

has_valence_violation(atom_id) → bool¶: Return whether the atom has a valence violation under the current chemical state.

kappa_1() → float¶

Return the first-order Kier molecular shape index.

This is a read-only molecular query; the source graph and coordinates are unchanged.

kappa_2() → float¶

Return the second-order Kier molecular shape index.

This is a read-only molecular query; the source graph and coordinates are unchanged.

kappa_3() → float¶

Return the third-order Kier molecular shape index.

This is a read-only molecular query; the source graph and coordinates are unchanged.

kekulize_bonds_() → None¶: In place, assign explicit single/double bonds to aromatic systems. Copy-on-write isolates other molecule values; errors do not commit partial changes.

kekulize_bonds_with_params_(params) → None¶: In place, assign explicit single/double bonds to aromatic systems. Copy-on-write isolates other molecule values; errors do not commit partial changes.

labute_asa() → float¶

Return the Labute approximate accessible surface area.

This is a read-only molecular query; the source graph and coordinates are unchanged.

labute_asa_contributions() → LabuteAsaContributions¶

Return total Labute surface area, per-atom contributions and the hydrogen contribution as LabuteAsaContributions.

This is a read-only molecular query; the source graph and coordinates are unchanged.

labute_asa_contributions_with_params(include_hydrogens, force) → LabuteAsaContributions¶

Return total Labute surface area, per-atom contributions and the hydrogen contribution as LabuteAsaContributions. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

labute_asa_with_params(include_hydrogens, force) → float¶

Return the Labute approximate accessible surface area. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

largest_fragment() → Molecule¶: Most atoms, last component on ties; empty input raises OperationError.

lipinski_hba() → int¶

Return the Lipinski hydrogen-bond acceptor count.

This is a read-only molecular query; the source graph and coordinates are unchanged.

lipinski_hbd() → int¶

Return the Lipinski hydrogen-bond donor count.

This is a read-only molecular query; the source graph and coordinates are unchanged.

mmff_energy_gradient() → Optional[MmffEnergyGradient]¶: Evaluate MMFF energy in kcal/mol and atom-ordered Cartesian energy derivatives at the selected stored coordinates.

mmff_energy_gradient_with_params(params) → Optional[MmffEnergyGradient]¶: Evaluate MMFF energy in kcal/mol and atom-ordered Cartesian energy derivatives at the selected stored coordinates. Uses the supplied configuration object.

mmff_force_field(*, conformer_id=Ellipsis, mmff_variant=Ellipsis, non_bonded_threshold=Ellipsis, ignore_interfragment_interactions=Ellipsis) → MolecularForceField¶: Create an owned persistent MMFF evaluator from the selected stored conformer. Later evaluator edits do not change this molecule.

mmff_force_field_with_params(params) → MolecularForceField¶: Create an owned persistent MMFF evaluator from the selected stored conformer. Later evaluator edits do not change this molecule. Uses the supplied configuration object.

mmff_has_all_molecule_params() → bool¶: Return whether every atom can be parameterized by the selected MMFF variant.

mmff_properties() → MmffProperties¶: Return MMFF atom types, formal charges and partial charges for this molecule.

mmff_properties_with_params(params) → MmffProperties¶: Return MMFF atom types, formal charges and partial charges for this molecule. Uses the supplied configuration object.

molecular_formula() → str¶

Return the molecular formula using the selected isotope and element-count formatting.

This is a read-only molecular query; the source graph and coordinates are unchanged.

molecular_formula_with_params(separate_isotopes, abbreviate_h_isotopes) → str¶

Return the molecular formula using the selected isotope and element-count formatting. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

molecular_hash() → int¶: Compute the original native 64-bit hash in legacy CIP rank order. Requires already prepared valence; absent ordinary rings remain absent.

molecular_hash_with_ranks(ranks) → int¶: Compute the same native hash with exactly one supplied rank per atom.

molecular_weight() → float¶

Return the average molecular weight in g/mol, including implicit hydrogens.

This is a read-only molecular query; the source graph and coordinates are unchanged.

molecular_weight_with_params(only_heavy) → float¶

Return the average molecular weight in g/mol, including implicit hydrogens. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

mqns(force=False) → list[int]¶

Return all 42 molecular quantum numbers in their defined component order.

This is a read-only molecular query; the source graph and coordinates are unchanged.

murcko_decompose() → Molecule¶: ChemTransforms MurckoDecompose, including ring-exocyclic double bonds.

murcko_scaffold() → Molecule¶: MolHash MurckoScaffold: prune terminal atoms, returning a new molecule.

net_scaffold() → Molecule¶: MolHash ExtendedMurcko: retain adjacent substituents as dummy atoms.

static new() → Molecule¶: Construct a Molecule value from the supplied inputs.

num_3d_conformers() → int¶: Return the number of stored 3D conformers; 2D conformers are not included.

num_aliphatic_carbocycles() → int¶: Return the number of all-carbon non-aromatic rings; use the current perceived ring state without modifying the graph.

num_aliphatic_heterocycles() → int¶: Return the number of non-aromatic rings containing a heteroatom; use the current perceived ring state without modifying the graph.

num_aliphatic_rings() → int¶: Return the number of non-aromatic rings; use the current perceived ring state without modifying the graph.

num_amide_bonds() → int¶

Return the number of amide bonds.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_aromatic_carbocycles() → int¶: Return the number of all-carbon aromatic rings; use the current perceived ring state without modifying the graph.

num_aromatic_heterocycles() → int¶: Return the number of aromatic rings containing a heteroatom; use the current perceived ring state without modifying the graph.

num_aromatic_rings() → int¶: Return the number of aromatic rings; use the current perceived ring state without modifying the graph.

num_atom_stereo_centers() → int¶

Return the number of specified and unspecified atom stereocenters.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_atoms() → int¶: Number of atoms in the graph or selected structure.

num_bonds() → int¶: Number of bonds in the graph.

num_bridgehead_atoms() → int¶

Return the number of bridgehead atoms in the ring system.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_hba() → int¶

Return the hydrogen-bond acceptor count using the descriptor SMARTS definitions.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_hbd() → int¶

Return the hydrogen-bond donor count using the descriptor SMARTS definitions.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_heavy_atoms() → int¶

Return the number of non-hydrogen graph atoms.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_heteroatoms() → int¶

Return the number of graph atoms other than carbon and hydrogen.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_heterocycles() → int¶: Return the number of heterocyclic rings; use the current perceived ring state without modifying the graph.

num_rings() → int¶: Return the number of perceived rings; use the current perceived ring state without modifying the graph.

num_rotatable_bonds() → int¶

Return the rotatable bond count using the selected RotatableBondsOptions definition.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_rotatable_bonds_with_params(params) → int¶

Return the rotatable bond count using the selected RotatableBondsOptions definition. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_saturated_carbocycles() → int¶: Return the number of all-carbon saturated rings; use the current perceived ring state without modifying the graph.

num_saturated_heterocycles() → int¶: Return the number of saturated rings containing a heteroatom; use the current perceived ring state without modifying the graph.

num_saturated_rings() → int¶: Return the number of fully saturated rings; use the current perceived ring state without modifying the graph.

num_spiro_atoms() → int¶

Return the number of atoms shared by otherwise disjoint rings.

This is a read-only molecular query; the source graph and coordinates are unchanged.

num_unspecified_atom_stereo_centers() → int¶

Return the number of atom stereocenters without a specified configuration.

This is a read-only molecular query; the source graph and coordinates are unchanged.

perceive_stereochemistry() → None¶: Return the stereochemistry-perception result using the selected cleanup/assignment options.

phi() → float¶

Return the Kier molecular flexibility index.

This is a read-only molecular query; the source graph and coordinates are unchanged.

potential_stereo() → PotentialStereoResult¶: Return candidate stereocenters/bonds and the associated stereo-perception result.

potential_stereo_with_params(params) → PotentialStereoResult¶: Return candidate stereocenters/bonds and the associated stereo-perception result. Uses the supplied configuration object.

properties() → MoleculeProperties¶: Return a detached snapshot of the stored properties.

property(key) → Optional[PropertyValue]¶: Return the stored value for the requested property key, or None if absent.

qed() → float¶

Return the quantitative estimate of drug-likeness using the configured descriptor weights.

This is a read-only molecular query; the source graph and coordinates are unchanged.

reaction_products(reaction, reactant_template) → list[list[Molecule]]¶: Run this molecule against the selected reactant template and return reaction product sets; the source molecule is unchanged.

reaction_products_from_inputs(reaction, reactants, params) → list[list[Molecule]]¶: Run the reaction on the explicit reactant list and return product sets in enumeration order.

reaction_products_with_params(reaction, reactant_template, params) → list[list[Molecule]]¶: Run this molecule against the selected reactant template and return reaction product sets; the source molecule is unchanged. Uses the supplied configuration object.

static read_mol(path) → Molecule¶: Read a MOL file from a filesystem path and return a new Molecule; use from_* for in-memory text.

static read_mol2(path) → Molecule¶: Read a MOL2 file from a filesystem path and return a new Molecule; use from_* for in-memory text.

static read_mol2_with_params(path, params) → Molecule¶: Read a MOL2 file from a filesystem path and return a new Molecule; use from_* for in-memory text.

static read_mol_with_params(path, params) → Molecule¶: Read a MOL file from a filesystem path and return a new Molecule; use from_* for in-memory text.

static read_sdf(path) → Molecule¶: Read a SDF file from a filesystem path and return a new Molecule; use from_* for in-memory text.

static read_sdf_with_params(path, params) → Molecule¶: Read a SDF file from a filesystem path and return a new Molecule; use from_* for in-memory text.

static read_xyz(path) → Molecule¶: Read a XYZ file from a filesystem path and return a new Molecule; use from_* for in-memory text.

remove_hydrogens_() → None¶: In place, remove eligible explicit hydrogen atoms using the selected removal policy. Copy-on-write isolates other molecule values; errors do not commit partial changes.

remove_hydrogens_with_params_(params) → None¶: In place, remove eligible explicit hydrogen atoms using the selected removal policy. Copy-on-write isolates other molecule values; errors do not commit partial changes.

sanitize() → Molecule¶: Return the existing Rust sanitization operation’s new molecule value. Its runtime owns descriptor-cache clearing and atomic commit.

sanitize_() → None¶: In place, perform the selected chemical sanitization stages. Copy-on-write isolates other molecule values; errors do not commit partial changes.

sanitize_with_params(params) → Molecule¶: Apply to a new molecule and return the result: perform the selected chemical sanitization stages. The source molecule is unchanged.

sanitize_with_params_(params) → None¶: In place, perform the selected chemical sanitization stages. Copy-on-write isolates other molecule values; errors do not commit partial changes.

set_2d_coordinates_(coordinates) → None¶: In place, store caller-supplied atom-ordered 2D coordinates. Copy-on-write isolates other molecule values; errors do not commit partial changes.

set_2d_coordinates_with_params_(coordinates, params) → None¶: In place, store caller-supplied atom-ordered 2D coordinates. Copy-on-write isolates other molecule values; errors do not commit partial changes.

set_3d_coordinates_(coordinates) → None¶: In place, replace coordinates of the selected stored 3D conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes.

set_3d_coordinates_with_params_(coordinates, params) → None¶: In place, replace coordinates of the selected stored 3D conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes.

set_atom_position_(atom, position) → None¶: Replace the requested atom position in place using the selected stored conformer; invalid input raises an error before commit.

set_atom_position_with_params_(atom, position, params) → None¶: Replace the requested atom position in place using the selected stored conformer; invalid input raises an error before commit.

set_atom_property_(atom, key, value) → None¶: Set one typed user property in place; shared copies remain unchanged.

set_only_3d_conformer_(coordinates) → int¶: In place, replace the 3D conformer collection with one caller-supplied conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes.

set_only_3d_conformer_with_params_(coordinates, params) → int¶: In place, replace the 3D conformer collection with one caller-supplied conformer. Copy-on-write isolates other molecule values; errors do not commit partial changes.

slogp_vsa() → list[float]¶

Return the 12 surface-area bins grouped by atomic Wildman-Crippen logP contributions.

This is a read-only molecular query; the source graph and coordinates are unchanged.

slogp_vsa_1() → float¶: Return bin 1 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_10() → float¶: Return bin 10 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_11() → float¶: Return bin 11 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_12() → float¶: Return bin 12 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_2() → float¶: Return bin 2 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_3() → float¶: Return bin 3 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_4() → float¶: Return bin 4 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_5() → float¶: Return bin 5 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_6() → float¶: Return bin 6 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_7() → float¶: Return bin 7 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_8() → float¶: Return bin 8 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_9() → float¶: Return bin 9 of the logP-weighted accessible-surface-area descriptor.

slogp_vsa_with_params(bins, force) → list[float]¶

Return the 12 surface-area bins grouped by atomic Wildman-Crippen logP contributions. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

smr_vsa() → list[float]¶

Return the 10 surface-area bins grouped by atomic Wildman-Crippen molar-refractivity contributions.

This is a read-only molecular query; the source graph and coordinates are unchanged.

smr_vsa_1() → float¶: Return bin 1 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_10() → float¶: Return bin 10 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_2() → float¶: Return bin 2 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_3() → float¶: Return bin 3 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_4() → float¶: Return bin 4 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_5() → float¶: Return bin 5 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_6() → float¶: Return bin 6 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_7() → float¶: Return bin 7 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_8() → float¶: Return bin 8 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_9() → float¶: Return bin 9 of the molar-refractivity-weighted accessible-surface-area descriptor.

smr_vsa_with_params(bins, force) → list[float]¶

Return the 10 surface-area bins grouped by atomic Wildman-Crippen molar-refractivity contributions. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

stereoisomer_count() → int¶: Return the estimated number of stereoisomers for the configured enumeration scope.

stereoisomer_count_with_options(options) → int¶: Return the estimated number of stereoisomers for the configured enumeration scope. Uses the supplied configuration object.

substruct_match(query) → Optional[MatchResult]¶: Return the first query-to-target MatchResult, or None if there is no match. params and keyword configuration are mutually exclusive.

substruct_match_with_params(query, params) → Optional[MatchResult]¶: Return the first query-to-target MatchResult, or None if there is no match. params and keyword configuration are mutually exclusive. Uses the supplied configuration object.

substruct_matches(query) → list[MatchResult]¶: Return query-to-target MatchResult values subject to max_matches and uniquify. An unmatched query returns an empty list; callbacks and chirality use the supplied configuration.

substruct_matches_compiled(query) → list[MatchResult]¶: Match a reusable CompiledQuery against this molecule and return MatchResult values.

substruct_matches_with_params(query, params) → list[MatchResult]¶: Return query-to-target MatchResult values subject to max_matches and uniquify. An unmatched query returns an empty list; callbacks and chirality use the supplied configuration. Uses the supplied configuration object.

tautomer_score() → TautomerScore¶: Return ring, SMARTS-pattern and heteroatom-hydrogen score contributions for this tautomer.

tautomer_score_with_params(params) → TautomerScore¶: Return ring, SMARTS-pattern and heteroatom-hydrogen score contributions for this tautomer. Uses the supplied configuration object.

tetrahedral_stereo() → list[TetrahedralStereo]¶: Return tetrahedral stereochemical information for the current molecule.

to_binary() → bytes¶: Return a native COSMolKit archive as bytes, including stored graph, coordinates, properties and retained derived state.

to_builder() → MoleculeBuilder¶: Return an editable builder initialized from this molecule; building changes does not modify the source.

to_cx_smarts() → str¶: Return SMARTS text with supported CX annotations.

to_cx_smarts_with_params(params) → str¶: Return SMARTS text with supported CX annotations. Uses the supplied configuration object.

to_cx_smiles() → str¶: Return SMILES with the selected CXSMILES annotations; leave the molecule unchanged.

to_cx_smiles_with_params(params) → str¶: Return SMILES with the selected CXSMILES annotations; leave the molecule unchanged. Uses the supplied configuration object.

to_fragment_cx_smiles(atoms) → str¶: Return fragment SMILES with the selected CX annotations; indices refer to this molecule.

to_fragment_cx_smiles_with_params(params) → str¶: Return fragment SMILES with the selected CX annotations; indices refer to this molecule. Uses the supplied configuration object.

to_fragment_smiles(atoms) → str¶: Return SMILES for the explicitly selected atom/bond fragment; indices refer to this molecule.

to_fragment_smiles_with_params(params) → str¶: Return SMILES for the explicitly selected atom/bond fragment; indices refer to this molecule. Uses the supplied configuration object.

to_inchi(params=None, *, options=None) → str¶: Return InChI text for this molecule without changing it. Supply InchiWriteParams or options, not both; failures raise InchiError.

to_inchi_key(params=None, *, options=None) → str¶: Return the InChIKey for this molecule using the selected InChI options; leave the molecule unchanged.

to_inchi_key_with_params(params) → str¶: Return the InChIKey for this molecule using the selected InChI options; leave the molecule unchanged. Uses the supplied configuration object.

to_inchi_with_params(params) → str¶: Return InChI text for this molecule without changing it. Supply InchiWriteParams or options, not both; failures raise InchiError. Uses the supplied configuration object.

to_mol() → str¶: Return a MOL text block using the selected writer options; does not write a file or install generated drawing coordinates on this object.

to_mol_with_params(params) → str¶: Return a MOL text block using the selected writer options; does not write a file or install generated drawing coordinates on this object. Uses the supplied configuration object.

to_png(width, height) → bytes¶: Experimental PNG bytes from the same public drawing owner.

to_random_smiles(count, seed) → list[str]¶: Return randomized SMILES strings using the supplied seed and output options; leave the graph unchanged.

to_random_smiles_with_params(count, seed, params) → list[str]¶: Return randomized SMILES strings using the supplied seed and output options; leave the graph unchanged. Uses the supplied configuration object.

to_sdf() → str¶: Return an SDF text record using the selected writer options; does not write a file.

to_sdf_2d() → str¶: Return SDF text with 2D coordinates. When needed and enabled, generate temporary 2D coordinates for export without installing them on the source molecule.

to_sdf_2d_with_params(params) → str¶: Return SDF text with 2D coordinates. When needed and enabled, generate temporary 2D coordinates for export without installing them on the source molecule. Uses the supplied configuration object.

to_sdf_3d() → str¶: Return SDF text for the selected stored 3D conformer; does not fall back to 2D coordinates.

to_sdf_3d_with_params(params) → str¶: Return SDF text for the selected stored 3D conformer; does not fall back to 2D coordinates. Uses the supplied configuration object.

to_sdf_with_params(params) → str¶: Return an SDF text record using the selected writer options; does not write a file. Uses the supplied configuration object.

to_smarts() → str¶: Return SMARTS text describing this graph using the selected query writer options.

to_smarts_with_params(params) → str¶: Return SMARTS text describing this graph using the selected query writer options. Uses the supplied configuration object.

to_smiles() → str¶: Return a SMILES string using the selected writer settings; this does not modify the molecule.

to_smiles_with_params(params) → str¶: Return a SMILES string using the selected writer settings; this does not modify the molecule. Uses the supplied configuration object.

to_svg(width, height) → str¶: Experimental SVG; required dimensions follow the current registry.

to_xyz() → str¶: Return XYZ text for the selected stored 3D conformer; missing or ambiguous coordinates raise an error.

to_xyz_with_params(params) → str¶: Return XYZ text for the selected stored 3D conformer; missing or ambiguous coordinates raise an error. Uses the supplied configuration object.

topological_torsion_ids() → list[int]¶: Return feature identifiers for the enumerated topological torsion paths using the supplied atom-count/options.

topological_torsion_ids_with_params(torsion_atom_count) → list[int]¶: Return feature identifiers for the enumerated topological torsion paths using the supplied atom-count/options. Uses the supplied configuration object.

topological_torsion_path_score(path, size, atom_codes=None) → int¶: Return the packed topological-torsion identifier for the supplied path and atom codes.

topology() → TopologyBlock¶: Returns the immutable topology value.

total_atom_count() → int¶

Return the total atom count including graph atoms and implicit hydrogens.

This is a read-only molecular query; the source graph and coordinates are unchanged.

tpsa() → float¶

Return the topological polar surface area using the selected sulfur/phosphorus inclusion policy.

This is a read-only molecular query; the source graph and coordinates are unchanged.

tpsa_with_params(include_sulfur_phosphorus, force) → float¶

Return the topological polar surface area using the selected sulfur/phosphorus inclusion policy. Uses the explicit arguments shown in the signature.

This is a read-only molecular query; the source graph and coordinates are unchanged.

uff_energy_gradient() → UffEnergyGradient¶: Evaluate UFF energy in kcal/mol and atom-ordered Cartesian energy derivatives at the selected stored coordinates.

uff_energy_gradient_with_params(params) → UffEnergyGradient¶: Evaluate UFF energy in kcal/mol and atom-ordered Cartesian energy derivatives at the selected stored coordinates. Uses the supplied configuration object.

uff_force_field(*, conformer_id=Ellipsis, vdw_threshold=Ellipsis, ignore_interfragment_interactions=Ellipsis) → MolecularForceField¶: Create an owned persistent UFF evaluator from the selected stored conformer. Later evaluator edits do not change this molecule.

uff_force_field_with_params(params) → MolecularForceField¶: Create an owned persistent UFF evaluator from the selected stored conformer. Later evaluator edits do not change this molecule. Uses the supplied configuration object.

uff_has_all_molecule_params() → bool¶: Return whether UFF parameters are available for all atoms in this molecule.

with_2d_coordinate_block(coordinates) → Molecule¶: Apply to a new molecule and return the result: store caller-supplied atom-ordered 2D coordinates. The source molecule is unchanged.

with_2d_coordinate_block_with_params(coordinates, params) → Molecule¶: Apply to a new molecule and return the result: store caller-supplied atom-ordered 2D coordinates. The source molecule is unchanged.

with_2d_coordinates() → Molecule¶: Apply to a new molecule and return the result: generate and store 2D drawing coordinates. The source molecule is unchanged.

with_2d_coordinates_with_params(params) → Molecule¶: Apply to a new molecule and return the result: generate and store 2D drawing coordinates. The source molecule is unchanged.

with_3d_conformer(params=None) → Molecule¶: Apply to a new molecule and return the result: embed one 3D conformer using the selected distance-geometry parameters. The source molecule is unchanged.

with_3d_conformer_result(params=None) → EmbedMoleculeResult¶: Apply to a new molecule and return the result: embed one 3D conformer and report its ID and updated embedding parameters. The source molecule is unchanged.

with_3d_conformer_result_with_params(params) → EmbedMoleculeResult¶: Apply to a new molecule and return the result: embed one 3D conformer and report its ID and updated embedding parameters. The source molecule is unchanged.

with_3d_conformer_with_params(params) → Molecule¶: Apply to a new molecule and return the result: embed one 3D conformer using the selected distance-geometry parameters. The source molecule is unchanged.

with_3d_conformers(num_confs, params=None) → Molecule¶: Apply to a new molecule and return the result: embed the requested number of 3D conformers using the selected distance-geometry parameters. The source molecule is unchanged.

with_3d_conformers_result(num_confs, params=None) → EmbedMultipleConfsResult¶: Apply to a new molecule and return the result: embed multiple 3D conformers and report generated IDs and embedding parameters. The source molecule is unchanged.

with_3d_conformers_result_with_params(num_confs, params) → EmbedMultipleConfsResult¶: Apply to a new molecule and return the result: embed multiple 3D conformers and report generated IDs and embedding parameters. The source molecule is unchanged.

with_3d_conformers_with_params(num_confs, params) → Molecule¶: Apply to a new molecule and return the result: embed the requested number of 3D conformers using the selected distance-geometry parameters. The source molecule is unchanged.

with_3d_coordinates(coordinates) → Molecule¶: Apply to a new molecule and return the result: replace coordinates of the selected stored 3D conformer. The source molecule is unchanged.

with_3d_coordinates_with_params(coordinates, params) → Molecule¶: Apply to a new molecule and return the result: replace coordinates of the selected stored 3D conformer. The source molecule is unchanged.

with_added_3d_conformer(coordinates) → Molecule¶: Apply to a new molecule and return the result: append a conformer using caller-supplied atom-ordered 3D coordinates. The source molecule is unchanged.

with_added_3d_conformer_with_params(coordinates, params) → Molecule¶: Apply to a new molecule and return the result: append a conformer using caller-supplied atom-ordered 3D coordinates. The source molecule is unchanged.

with_aligned_conformers(params=None) → tuple[Molecule, ConformerAlignmentReport]¶: Apply to a new molecule and return the result: align the selected stored conformers to a reference conformer. The source molecule is unchanged. Return a molecule with aligned conformers and the ordered source RMS report.

with_aligned_conformers_with_params(params) → tuple[Molecule, ConformerAlignmentReport]¶: Apply to a new molecule and return the result: align the selected stored conformers to a reference conformer. The source molecule is unchanged.

with_alignment_to(reference, params=None) → tuple[Molecule, AlignmentResult]¶

Apply to a new molecule and return the result: align the selected conformer to the reference molecule. The source molecule is unchanged.

Return a new molecule aligned to reference together with its alignment result.

The source and reference molecules remain unchanged.

with_alignment_to_with_params(reference, params) → tuple[Molecule, AlignmentResult]¶: Apply to a new molecule and return the result: align the selected conformer to the reference molecule. The source molecule is unchanged.

with_assigned_aromaticity() → Molecule¶: Apply to a new molecule and return the result: assign aromatic atom and bond flags using the selected aromaticity model. The source molecule is unchanged.

with_assigned_aromaticity_with_params(params) → Molecule¶: Apply to a new molecule and return the result: assign aromatic atom and bond flags using the selected aromaticity model. The source molecule is unchanged.

with_assigned_radicals() → Molecule¶: Apply to a new molecule and return the result: assign atomic radical electron counts. The source molecule is unchanged.

with_assigned_ring_families() → Molecule¶: Apply to a new molecule and return the result: calculate and install unique ring families. The source molecule is unchanged.

with_assigned_ring_families_with_params(params) → Molecule¶: Apply to a new molecule and return the result: calculate and install unique ring families. The source molecule is unchanged.

with_assigned_rings() → Molecule¶: Apply to a new molecule and return the result: calculate and install ring membership and ring information. The source molecule is unchanged.

with_assigned_valence() → Molecule¶: Apply to a new molecule and return the result: calculate and install the atom valence assignment. The source molecule is unchanged.

with_assigned_valence_with_params(params) → Molecule¶: Apply to a new molecule and return the result: calculate and install the atom valence assignment. The source molecule is unchanged.

with_atom_pair_atom_code(atom_id, branch_subtract=0, include_chirality=False, use_legacy_stereo_perception=True) → AtomPairAtomCodeResult¶: Return the atom-pair atom code and associated molecule result for the requested atom.

with_atom_position(atom, position) → Molecule¶: Apply to a new molecule and return the result: replace the position of one atom in the selected stored conformer. The source molecule is unchanged.

with_atom_position_with_params(atom, position, params) → Molecule¶: Apply to a new molecule and return the result: replace the position of one atom in the selected stored conformer. The source molecule is unchanged.

with_atom_property(atom, key, value) → Molecule¶: Return an independently editable molecule with one typed user property.

with_chiral_tags_from_structure() → Molecule¶: Apply to a new molecule and return the result: assign atom chiral tags from the selected stored conformer. The source molecule is unchanged.

with_chiral_tags_from_structure_with_params(params) → Molecule¶: Apply to a new molecule and return the result: assign atom chiral tags from the selected stored conformer. The source molecule is unchanged.

with_cip_labels() → Molecule¶: Apply to a new molecule and return the result: assign CIP stereochemical descriptors. The source molecule is unchanged.

with_cip_labels_with_options(options) → Molecule¶: Apply to a new molecule and return the result: assign CIP stereochemical descriptors. The source molecule is unchanged.

with_cleared_3d_conformers() → Molecule¶: Apply to a new molecule and return the result: remove all stored 3D conformers while retaining the separate 2D state. The source molecule is unchanged.

with_hydrogens() → Molecule¶: Apply to a new molecule and return the result: add explicit hydrogen atoms with the selected hydrogen/coordinate options. The source molecule is unchanged.

with_hydrogens_with_params(params) → Molecule¶: Apply to a new molecule and return the result: add explicit hydrogen atoms with the selected hydrogen/coordinate options. The source molecule is unchanged.

with_kekulized_bonds() → Molecule¶: Apply to a new molecule and return the result: assign explicit single/double bonds to aromatic systems. The source molecule is unchanged.

with_kekulized_bonds_with_params(params) → Molecule¶: Apply to a new molecule and return the result: assign explicit single/double bonds to aromatic systems. The source molecule is unchanged.

with_mmff_optimized() → MmffOptimizeMoleculeResult¶: Apply to a new molecule and return the result: optimize the selected stored 3D conformer with the selected MMFF variant. The source molecule is unchanged.

with_mmff_optimized_conformers() → MmffOptimizeMoleculeConfsResult¶: Apply to a new molecule and return the result: optimize stored 3D conformers with MMFF and return per-conformer outcomes. The source molecule is unchanged.

with_mmff_optimized_conformers_with_params(params) → MmffOptimizeMoleculeConfsResult¶: Apply to a new molecule and return the result: optimize stored 3D conformers with MMFF and return per-conformer outcomes. The source molecule is unchanged.

with_mmff_optimized_with_params(params) → MmffOptimizeMoleculeResult¶: Apply to a new molecule and return the result: optimize the selected stored 3D conformer with the selected MMFF variant. The source molecule is unchanged.

with_only_3d_conformer(coordinates) → Molecule¶: Apply to a new molecule and return the result: replace the 3D conformer collection with one caller-supplied conformer. The source molecule is unchanged.

with_only_3d_conformer_with_params(coordinates, params) → Molecule¶: Apply to a new molecule and return the result: replace the 3D conformer collection with one caller-supplied conformer. The source molecule is unchanged.

with_uff_optimized() → UffOptimizationResult¶: Optimize the selected 3D conformer with UFF and return UffOptimizationResult containing the new molecule, convergence status and final energy. The source molecule is unchanged.

with_uff_optimized_conformers() → UffConformerOptimizationResult¶: Optimize stored 3D conformers with UFF and return a new molecule with per-conformer convergence statuses and energies. The source molecule is unchanged.

with_uff_optimized_conformers_with_params(params) → UffConformerOptimizationResult¶: Optimize stored 3D conformers with UFF and return a new molecule with per-conformer convergence statuses and energies. The source molecule is unchanged. Uses the supplied configuration object.

with_uff_optimized_with_params(params) → UffOptimizationResult¶: Optimize the selected 3D conformer with UFF and return UffOptimizationResult containing the new molecule, convergence status and final energy. The source molecule is unchanged. Uses the supplied configuration object.

without_hydrogens() → Molecule¶: Apply to a new molecule and return the result: remove eligible explicit hydrogen atoms using the selected removal policy. The source molecule is unchanged.

without_hydrogens_with_params(params) → Molecule¶: Apply to a new molecule and return the result: remove eligible explicit hydrogen atoms using the selected removal policy. The source molecule is unchanged.

write_mol(path) → None¶: Write MOL output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_mol_with_params(path, params) → None¶: Write MOL output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_png(path, width, height) → None¶: Write PNG output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_sdf(path) → None¶: Write SDF output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_sdf_files(directory, file_name=None) → pathlib.Path¶: Write SDF FILES output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_sdf_files_with_params(directory, file_name, params) → pathlib.Path¶: Write SDF FILES output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_sdf_with_params(path, params) → None¶: Write SDF output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_svg(path, width, height) → None¶: Write SVG output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_xyz(path) → None¶: Write XYZ output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_xyz_with_params(path, params) → None¶: Write XYZ output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

class cosmolkit.BioStructure¶

Owned PDB/mmCIF structural hierarchy with models, chains, residues, atoms, coordinates and metadata.

from_pdb()/from_mmcif() take text; read() takes a path. Local row IDs are distinct from retained source serials and author/label sequence identifiers.

Members (61)

assemblies() → list[BioAssembly]¶: Biological assembly definitions and their generators.

atom_by_altloc(residue_id, name, altloc) → tuple[int, BioAtomRow]¶: Find a residue atom using its name and alternate-location request.

atom_position(atom) → Optional[list[float]]¶: Return the (x, y, z) position in angstroms for a local atom ID.

atoms() → list[BioAtomRow]¶: Return atom rows in stored graph/hierarchy order.

chains() → list[BioChainRow]¶: Return chain rows/references in stored hierarchy order.

cispeps() → list[BioCisPep]¶: Stored cis-peptide annotations in source order.

connections() → list[BioConnection]¶: Stored inter-atom connection annotations in source order.

coordinates() → BioCoordinateBlock¶: Return the BIO coordinate block in structural atom-row order.

crystal() → Optional[BioCrystalInfo]¶: Crystallographic unit cell and space-group information.

entities() → list[BioEntityRow]¶: Return molecular entity rows in stored order.

find_atom(residue_id, name, request, element) → Optional[tuple[int, BioAtomRow]]¶: Find an atom by its structural address and alternate-location request.

find_entity(source_id) → Optional[tuple[int, BioEntityRow]]¶: Find the entity with the requested source entity identifier, or None if absent.

find_entity_of_subchain(subchain) → Optional[tuple[int, BioEntityRow]]¶: Find the entity associated with the requested subchain, or None if absent.

static from_mmcif(text) → BioStructure¶: Parse mmCIF text into a structural object, preserving hierarchy, coordinates and supported metadata; this argument is text, not a file path.

static from_parts(parts) → BioStructure¶: Construct a value from explicit detached parts; required structural consistency is checked at the public boundary.

static from_pdb(text) → BioStructure¶: Parse PDB text into a structural object, preserving hierarchy, coordinates and supported source metadata; this argument is text, not a file path.

static from_pdb_with_params(text, params) → BioStructure¶: Parse PDB text into a structural object, preserving hierarchy, coordinates and supported source metadata; this argument is text, not a file path. Uses the supplied configuration object.

static from_text(text) → BioStructure¶: Parse structural text using the requested BioReadParams input format.

static from_text_with_params(text, params) → BioStructure¶: Parse structural text using the requested BioReadParams input format. Uses the supplied configuration object.

has_origx() → bool¶: Whether the structure contains an original-coordinate transformation.

helices() → list[BioHelix]¶: Secondary-structure helix annotations.

input_format() → str¶: Detected/declared structural input format.

into_parts() → BioStructureParts¶: Return detached structure parts, including coordinates, hierarchy and metadata.

metadata() → BioMetadata¶: Experimental, crystallographic and bibliographic metadata.

mod_residues() → list[BioModRes]¶: Modified-residue annotations in source order.

models() → list[BioModelRow]¶: Return structural model rows in stored order.

name() → str¶: Stored name of this value.

ncs_oper_identity_id() → Optional[str]¶: Identifier of the identity noncrystallographic-symmetry operator, when available.

ncs_operators() → list[BioNcsOperator]¶: Noncrystallographic-symmetry transformations.

num_atoms() → int¶: Number of atoms in the graph or selected structure.

num_chains() → int¶: Number of chains.

num_entities() → int¶: Number of molecular entities.

num_models() → int¶: Number of structural models.

num_residues() → int¶: Number of residues.

origx() → BioTransform¶: Original-coordinate transformation stored in the structure.

protein() → Protein¶: Return a Protein view over the structure protein hierarchy.

static read(path) → BioStructure¶: Read a PDB/mmCIF file from a filesystem path, selecting its format through the read options.

static read_with_format(path, format) → BioStructure¶: Read a structural file from a filesystem path using an explicit input format.

residue_atoms(residue) → Optional[list[BioAtomRow]]¶: Return the atom rows belonging to the specified residue.

residues() → list[BioResidueRow]¶: Return residue rows/references in stored hierarchy order.

resolution() → float¶: Experimental resolution in angstroms as recorded in the structure.

retain_selection_(selection) → None¶: Retain only the selected structure rows in place, updating hierarchy, coordinates and references together.

selected_atom_ids(selection) → list[int]¶: Return the local atom identifiers matching the selection.

sheets() → list[BioSheet]¶: Secondary-structure sheet annotations.

source_state() → BioStructureSourceState¶: Source-format state retained for structural roundtrips.

ter_status() → int¶: Source TER-record handling state.

to_mmcif() → str¶: Return mmCIF text using the selected category/formatting options; does not write a file.

to_mmcif_with_params(params) → str¶: Return mmCIF text using the selected category/formatting options; does not write a file. Uses the supplied configuration object.

to_molecule(*, sanitize=True, remove_hs=True, flavor=0, proximity_bonding=True) → Molecule¶: Convert the selected BIO atoms and positions into a new Molecule using the conversion options.

to_molecule_with_params(params) → Molecule¶: Convert the selected BIO atoms and positions into a new Molecule using the conversion options. Uses the supplied configuration object.

to_pdb() → str¶: Return PDB text using the selected formatting options; does not write a file.

to_pdb_with_params(params) → str¶: Return PDB text using the selected formatting options; does not write a file. Uses the supplied configuration object.

translate_(offset) → None¶: Translate all structural atom positions in place by the supplied vector.

validate() → None¶: Validate the stored structure/template and return its validation result; invalid data is not silently repaired.

static validate_parts(parts) → None¶: Validate detached structure parts before constructing a live structure.

with_selection(selection) → BioStructure¶: Return a new structure restricted to the selection; leave the source unchanged.

with_translated_coordinates(offset) → BioStructure¶: Return a new structure with every atom position translated by the supplied vector; leave source coordinates unchanged.

write_mmcif(path) → None¶: Write MMCIF output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_mmcif_with_params(path, params) → None¶: Write MMCIF output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_pdb(path) → None¶: Write PDB output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

write_pdb_with_params(path, params) → None¶: Write PDB output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text.

class cosmolkit.Protein¶

Protein-oriented structural hierarchy with chain, residue and atom references. Parsing accepts text through from_* and files through read(); selection preserves the source unless the method ends in an underscore.

Members (26)

as_bio_structure() → BioStructure¶: Return the underlying structural representation without parsing or generating coordinates.

atoms() → list[ProteinAtomRef]¶: Return atom rows in stored graph/hierarchy order.

chain(index) → Optional[ProteinChainRef]¶: Return the chain reference for a local chain identifier.

chains() → list[ProteinChainRef]¶: Return chain rows/references in stored hierarchy order.

static from_mmcif(text) → Protein¶: Parse mmCIF text into a structural object, preserving hierarchy, coordinates and supported metadata; this argument is text, not a file path.

static from_pdb(text) → Protein¶: Parse PDB text into a structural object, preserving hierarchy, coordinates and supported source metadata; this argument is text, not a file path.

static from_pdb_with_params(text, params) → Protein¶: Parse PDB text into a structural object, preserving hierarchy, coordinates and supported source metadata; this argument is text, not a file path. Uses the supplied configuration object.

static from_text(text) → Protein¶: Parse structural text using the requested BioReadParams input format.

static from_text_with_params(text, params) → Protein¶: Parse structural text using the requested BioReadParams input format. Uses the supplied configuration object.

input_format() → str¶: Detected/declared structural input format.

into_bio_structure() → BioStructure¶: Return the structural representation as a BioStructure value.

num_atoms() → int¶: Number of atoms in the graph or selected structure.

num_chains() → int¶: Number of chains.

num_models() → int¶: Number of structural models.

num_residues() → int¶: Number of residues.

static read(path) → Protein¶: Read a PDB/mmCIF file from a filesystem path, selecting its format through the read options.

static read_with_format(path, format) → Protein¶: Read a structural file from a filesystem path using an explicit input format.

residues() → list[ProteinResidueRef]¶: Return residue rows/references in stored hierarchy order.

retain_selection_(selection) → None¶: Retain only the selected protein rows in place, updating hierarchy and coordinates together.

selected_atom_ids(selection) → list[int]¶: Return the local atom identifiers matching the selection.

selection_summary() → ProteinSelectionSummary¶: Return the numbers of chains, residues and atoms in the protein selection.

to_molecule(*, sanitize=True, remove_hs=True, flavor=0, proximity_bonding=True) → Molecule¶: Convert the selected BIO atoms and positions into a new Molecule using the conversion options.

to_molecule_with_params(params) → Molecule¶: Convert the selected BIO atoms and positions into a new Molecule using the conversion options. Uses the supplied configuration object.

translate_(offset) → None¶: Translate protein atom coordinates in place while retaining hierarchy and metadata.

with_selection(selection) → Protein¶: Return a new structure restricted to the selection; leave the source unchanged.

with_translated_coordinates(offset) → Protein¶: Return a new protein with translated atom coordinates, preserving hierarchy and metadata.

class cosmolkit.AddHsParams(*, explicit_only=False, add_coords=False, add_residue_info=False, skip_queries=False, only_on_atoms=None)¶

Writable configuration for explicit hydrogen addition.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (5)

property add_coords: bool¶: Whether coordinates for newly added hydrogens are generated from stored conformers.

property add_residue_info: bool¶: Whether added hydrogens inherit suitable residue metadata.

property explicit_only: bool¶: Whether only atom-stored explicit hydrogens are expanded into graph vertices.

property only_on_atoms: Optional[list[int]]¶: Optional atom indices restricting hydrogen addition.

property skip_queries: bool¶: Whether query atoms are excluded from hydrogen addition.

class cosmolkit.AlignmentAtomMap(probe_atom, reference_atom)¶

Explicit atom correspondences used for alignment, as (probe index, reference index) pairs.

Members (3)

static new(probe_atom, reference_atom) → AlignmentAtomMap¶: Construct a AlignmentAtomMap value from the supplied inputs.

probe_atom: int¶: Zero-based atom index in the probe molecule.

reference_atom: int¶: Zero-based atom index in the reference molecule.

exception cosmolkit.AlignmentError¶: Molecular alignment or RMSD evaluation failed for the coordinates, mapping or parameters.

class cosmolkit.AlignmentParameters(probe_conformer_id=Ellipsis, reference_conformer_id=Ellipsis, atom_map=None, weights=None, reflect=False, max_iterations=50)¶

Writable configuration for molecular alignment with explicit atom mapping.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

property atom_map: Optional[list[AlignmentAtomMap]]¶: Explicit probe-to-reference AlignmentAtomMap pairs, or None to determine a map by substructure matching.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

static new(probe_conformer_id=Ellipsis, reference_conformer_id=Ellipsis, atom_map=None, weights=None, reflect=False, max_iterations=50) → AlignmentParameters¶: Configure molecular alignment with explicit atom mapping; omitted fields use the defaults shown in the signature.

property probe_conformer_id: int¶: Stored conformer ID on the probe molecule.

property reference_conformer_id: int¶: Stored conformer ID on the reference molecule.

property reflect: bool¶: Whether the alignment fit may use a spatial reflection.

property weights: Optional[list[float]]¶: Optional per-correspondence weights for alignment/RMSD calculation.

class cosmolkit.AlignmentResult¶

Best alignment RMSD in angstroms together with the corresponding spatial transform.

Members (3)

atom_map() → list[AlignmentAtomMap]¶: Return the selected probe-to-reference atom correspondence as AlignmentAtomMap pairs.

rmsd() → float¶: Root-mean-square coordinate deviation in angstroms.

transform() → AlignmentTransform¶: Stored spatial transformation associated with this result or structural operator.

class cosmolkit.AlignmentTransform¶

Rigid 3D alignment transform; read the matrix rather than assuming coordinates were changed.

Members (1)

matrix() → list[list[float]]¶: Return the alignment homogeneous transformation matrix in row order.

class cosmolkit.AllConformerRmsdParameters(atom_maps=None, weights=None, max_matches=1000000, symmetrize_conjugated_terminal_groups=True, ignore_hydrogens=True, num_threads=1)¶

Writable configuration for pairwise best RMSD between stored conformers.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

property atom_maps: list[list[AlignmentAtomMap]]¶: Candidate probe-to-reference atom mappings considered during alignment/RMSD search.

property ignore_hydrogens: bool¶: Whether hydrogen atoms are excluded when finding alignment atom correspondences.

property max_matches: int¶: Maximum number of substructure matches to return.

static new(atom_maps=None, weights=None, max_matches=1000000, symmetrize_conjugated_terminal_groups=True, ignore_hydrogens=True, num_threads=1) → AllConformerRmsdParameters¶: Configure pairwise best RMSD between stored conformers; omitted fields use the defaults shown in the signature.

property num_threads: int¶: Requested worker count; interpretation of zero follows the corresponding operation.

property symmetrize_conjugated_terminal_groups: bool¶: Whether conjugated terminal groups are treated as equivalent during alignment mapping.

property weights: Optional[list[float]]¶: Optional per-correspondence weights for alignment/RMSD calculation.

class cosmolkit.AltLocLabel(value)¶

Stored alternate-location label for a structural atom site.

Members (1)

value() → int¶: Return the stored alternate-location character code.

class cosmolkit.AltLocRequest¶

Alternate-location selection request: any alternate or an exact label.

Members (2)

Any = <cosmolkit.AltLocRequest object>¶

static Exact(altloc) → AltLocRequest¶: Construct a request for the supplied alternate-location label.

exception cosmolkit.AromaticityError¶: Aromaticity assignment failed for the graph or selected aromaticity model.

class cosmolkit.AromaticityModel¶

Aromaticity assignment model selected for chemical perception.

Declared values: Rdkit, Simple, Mdl, Mmff94, Custom.

Members (5)

Custom = AromaticityModel.Custom¶

Mdl = AromaticityModel.Mdl¶

Mmff94 = AromaticityModel.Mmff94¶

Rdkit = AromaticityModel.Rdkit¶

Simple = AromaticityModel.Simple¶

class cosmolkit.AromaticityParams(model=Ellipsis)¶

Writable configuration for aromaticity assignment.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property model: AromaticityModel¶: AromaticityModel selecting the aromaticity assignment rules.

class cosmolkit.Atom¶

Read-only atom value identified by its graph index. Includes stored chemical flags and, when requested by the molecule accessor, calculated valence metadata.

Members (23)

atom_map() → Optional[int]¶: Reaction atom-map number, or None when no map is assigned.

atomic_number() → int¶: Atomic number (proton count); zero denotes a dummy atom.

chiral_tag() → ChiralTag¶: Stored local tetrahedral or non-tetrahedral chirality tag, not a CIP label.

chiral_tag_code() → int¶: Return the integer representation of the stored chiral tag.

chiral_tag_name() → str¶: Return the symbolic name of the stored chiral tag.

cip_descriptor() → Optional[CipDescriptor]¶: Assigned CIP stereochemical descriptor, when present.

cip_neighbor_order() → Optional[list[int]]¶: Neighbor ordering retained for interpreting the assigned CIP descriptor.

cip_rank() → Optional[int]¶: Assigned CIP ranking value, when present.

degree() → int¶: Number of graph neighbors, including explicit hydrogen vertices.

element() → Element¶: Chemical element as an Element value.

explicit_hydrogens() → int¶: Hydrogen count stored on the atom, excluding separate hydrogen graph vertices.

explicit_valence() → int¶: Valence contribution from explicit bonds and atom-stored explicit hydrogens.

formal_charge() → int¶: Formal charge in units of the elementary charge.

hybridization() → Hybridization¶: Assigned atomic hybridization as a Hybridization value.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

implicit_hydrogens() → int¶: Calculated implicit hydrogen count for this atom.

is_aromatic() → bool¶: Whether the stored atom or bond has the aromatic flag.

isotope() → Optional[int]¶: Explicit isotope mass number, or None when unspecified.

no_implicit() → bool¶: Whether implicit hydrogen addition is disabled for this atom.

radical_electrons() → int¶: Number of unpaired radical electrons assigned to the atom.

template_attachment_order() → Optional[TemplateAttachmentOrder]¶: Reaction-template attachment ordering, when recorded.

total_hydrogens() → int¶: Total attached hydrogen count under this metadata calculation.

total_valence() → int¶: Sum of explicit and implicit valence.

class cosmolkit.AtomAddress¶

Logical structural atom address identified by chain, residue, atom name and alternate-location label.

Members (4)

altloc: int¶: Alternate-location label represented as an integer character code.

chain_name: str¶: Chain name recorded by the source structural address.

logical_atom_name: str¶: Atom name used for structural-address matching, excluding storage padding.

residue: ResidueAddress¶: Return the parent residue reference.

class cosmolkit.AtomCodeExplanation¶

Decoded atom-pair atom-code fields: element symbol, branch count, pi-electron count and chirality.

Members (5)

branch_count() → int¶: Branch-count field decoded from an atom-pair atom code.

chirality() → Optional[str]¶: Chirality field decoded from an atom-pair atom code.

static from_code(code, branch_subtract=0, include_chirality=False) → AtomCodeExplanation¶: Decode an atom-pair atom code into its element, branching, pi-electron and chirality fields.

pi_electrons() → int¶: Pi-electron field decoded from an atom-pair atom code.

symbol() → str¶: Chemical element symbol represented by this value.

exception cosmolkit.AtomCodeExplanationError¶: An atom-pair or torsion code could not be decoded into the requested explanation.

class cosmolkit.AtomMetadata¶

Owned context-dependent atom read results. Canonical Atom vocabulary stays in the model; these rows hold only degree and calculated valence metadata.

Members (5)

degree() → int¶: Number of graph neighbors, including explicit hydrogen vertices.

explicit_valence() → int¶: Valence contribution from explicit bonds and atom-stored explicit hydrogens.

implicit_hydrogens() → int¶: Calculated implicit hydrogen count for this atom.

total_hydrogens() → int¶: Total attached hydrogen count under this metadata calculation.

total_valence() → int¶: Sum of explicit and implicit valence.

class cosmolkit.AtomName¶

Fixed-width structural atom name with explicit byte and text access.

Members (3)

as_bytes() → bytes¶: Return the stored source bytes without text normalization.

as_str() → str¶: Return the text representation of the stored name.

static from_ascii(bytes) → Optional[AtomName]¶: Construct an atom name from ASCII bytes; return None for invalid width or non-ASCII input.

class cosmolkit.AtomPairAtomCodeResult¶

Atom-pair code calculation result containing the code and the associated molecule value.

Members (2)

code: int¶: Stored residue/atom code; its interpretation is defined by the owning value type.

molecule: Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

class cosmolkit.AtomPairAtomInvariantsGenerator(*, include_chirality=False, topological_torsion_correction=False)¶

Atom-pair atom-code generator with chirality and torsion-correction configuration.

Members (4)

property include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

info_string() → str¶: Return a readable description of the generator settings.

to_json() → str¶: Return a JSON string containing this configuration.

property topological_torsion_correction: bool¶: Whether atom-pair atom codes include the topological-torsion branch correction.

class cosmolkit.AtomPairFingerprintParams(*, generator=None, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None, custom_bond_invariants=None, conformer_id=Ellipsis, atom_invariants_generator=None, use_legacy_stereo_perception=True)¶

Writable configuration for atom-pair generator selection and per-call invariants.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (8)

property atom_invariants_generator: Optional[AtomPairAtomInvariantsGenerator]¶: Atom-invariant generator used instead of the default invariant calculation.

property conformer_id: int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property custom_atom_invariants: Optional[list[int]]¶: Caller-supplied atom invariants in atom-index order.

property custom_bond_invariants: Optional[list[int]]¶: Caller-supplied bond invariants in bond-index order.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property generator: AtomPairParams¶: Fingerprint generator configuration; nested edits update the parent parameter object.

property ignore_atoms: Optional[list[int]]¶: Atom indices excluded from fingerprint feature enumeration.

property use_legacy_stereo_perception: bool¶: Whether legacy stereochemistry perception is used by the fingerprint operation.

class cosmolkit.AtomPairParams(*, min_distance=1, max_distance=30, include_chirality=False, use_2d=True, count_simulation=True, fp_size=2048, bits_per_feature=1, count_bounds=None)¶

Writable configuration for atom-pair fingerprint generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (11)

property bits_per_feature: int¶: Number of hashed bit positions generated per feature.

property count_bounds: list[int]¶: Occurrence-count thresholds used by count simulation.

property count_simulation: bool¶: Whether occurrence counts are represented using threshold bits.

property fp_size: int¶: Number of bins/bits in the folded fingerprint.

property include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

info_string() → str¶: Return a readable description of the generator settings.

property max_distance: int¶: Maximum separation for atom-pair fingerprints or MCS coordinate matching.

property min_distance: int¶: Minimum atom-pair separation included in fingerprinting.

to_json() → str¶: Return a JSON string containing this configuration.

property use_2d: bool¶: Whether atom-pair distances are graph distances rather than 3D geometric distances.

with_json(json) → AtomPairParams¶: Return an independent configuration updated from the supplied JSON text; invalid JSON/options raise an error.

exception cosmolkit.AtomPairReadError¶: Atom-pair fingerprint preparation could not read the required molecular state.

class cosmolkit.AtomPairsParameters¶

Read-only constants defining atom-pair code bit widths, supported atom types and fingerprint index space.

Members (10)

static atom_types() → list[int]¶: Element atomic numbers included in the atom-pair atom-type table.

static code_size() → int¶: Total bit width of the packed atom-pair atom code.

static max_path_length() → int¶: Maximum path length representable by the atom-pair code format.

static num_atom_pair_fingerprint_bits() → int¶: Logical atom-pair fingerprint index-space size.

static num_branch_bits() → int¶: Bit width used for the branch-count field of atom-pair codes.

static num_chiral_bits() → int¶: Bit width used for the chirality field of atom-pair codes.

static num_path_bits() → int¶: Bit width used for atom-pair path lengths.

static num_pi_bits() → int¶: Bit width used for the pi-electron field of atom-pair codes.

static num_type_bits() → int¶: Bit width used for the atom-type field of atom-pair codes.

static version() → str¶: Return the version identifier recorded by this value or implementation.

class cosmolkit.AtomPositionParams(*, conformer_id=None)¶

Writable configuration for single-atom position replacement and conformer selection.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

class cosmolkit.AtomSourceIds¶

Source atom-site identifiers, including the PDB serial number.

Members (1)

serial() → Optional[int]¶: Atom serial number from the source file.

class cosmolkit.AtomSpec(element)¶

Atom construction specification: element, charge, hydrogen count, isotope and map information. with_* methods return updated specifications.

Members (6)

static new(element) → AtomSpec¶: Construct a AtomSpec value from the supplied inputs.

with_atom_map(value) → AtomSpec¶: Return a new AtomSpec with the requested reaction atom-map number.

with_explicit_hydrogens(value) → AtomSpec¶: Return a new AtomSpec with the requested atom-stored explicit hydrogen count.

with_formal_charge(value) → AtomSpec¶: Return a new AtomSpec with the requested formal charge.

with_isotope(value) → AtomSpec¶: Return a new AtomSpec with the requested isotope mass number.

with_no_implicit(value) → AtomSpec¶: Return a new AtomSpec controlling whether implicit hydrogens are allowed.

exception cosmolkit.AvalonEngineError¶: The Avalon engine could not process the supplied molecular representation.

exception cosmolkit.AvalonFingerprintError¶: Avalon fingerprint preparation or generation failed.

class cosmolkit.AvalonFingerprintFlags¶

Avalon feature-family bit mask. from_bits_retain() preserves the supplied mask without silently selecting additional features.

Members (2)

bits() → int¶: Return the underlying unsigned integer bit mask.

static from_bits_retain(bits) → AvalonFingerprintFlags¶: Construct a flag value preserving all supplied integer bits.

class cosmolkit.AvalonFingerprintParams(*, n_bits=512, is_query=False, bit_flags=15761407)¶

Writable configuration for Avalon fingerprint generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property bit_flags: int¶: Avalon feature-selection mask.

property is_query: bool¶: Whether Avalon interprets the input as a query structure.

property n_bits: int¶: Logical width of the fingerprint in bits.

class cosmolkit.BatchError¶

Failure for one batch input, identified by its original index and operation name.

Members (4)

as_dict() → dict[str, int | str]¶: Return a fresh dictionary with an integer input index and string details.

index() → int¶: Original zero-based input record index; failed records retain their index.

message() → str¶: Human-readable failure description.

operation() → str¶: Name of the operation that produced this error.

class cosmolkit.BatchErrorMode(value)¶

Batch failure policy: RAISE stops with BatchValidationError; KEEP retains failures at their original input positions.

Members (2)

KEEP = 2¶

RAISE = 1¶

class cosmolkit.BatchExportParams(*, format=None, errors=None, n_jobs=None, progress_bar=None)¶

Writable configuration for batch molecular file export.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property errors: Any¶: BatchErrorMode controlling whether export failures raise or are retained in the export report.

property format: str¶: Input/output format selector accepted by the corresponding operation.

property n_jobs: Optional[int]¶: Worker count for batch execution; one selects sequential execution.

property progress_bar: Optional[bool]¶: Whether batch execution reports progress.

class cosmolkit.BatchExportReport¶

Batch file-export counts and per-input errors. Failed writes remain visible in the report.

Members (5)

errors() → list[BatchError]¶: Errors retained by this result, including original input positions when applicable.

failed() → int¶: Number of failed items.

success() → int¶: Number of successfully processed items.

total() → int¶: Total number of processed items.

write_report(path) → None¶: Write the source-defined count-only JSON/CSV report to a literal path. Path expansion is the caller’s language-boundary responsibility.

class cosmolkit.BatchFingerprintAdditionalOutput¶

Read-only per-record snapshot of requested fingerprint metadata; absent sinks return None.

Members (5)

atom_counts() → Optional[list[int]]¶: Return atom-indexed feature participation counts, or None if this sink was not allocated.

atom_to_bits() → Optional[list[list[int]]]¶: Return atom-indexed lists of contributed fingerprint bits, or None if this sink was not allocated.

atoms_per_bit() → Optional[dict[int, list[list[int]]]]¶: Return bit-to-environment mapping of contributing atom-index sequences, or None if this sink was not allocated.

bit_info_map() → Optional[dict[int, list[tuple[int, int]]]]¶: Return bit-to-environment mapping with atom/radius pairs, or None if this sink was not allocated.

bit_paths() → Optional[dict[int, list[list[int]]]]¶: Return bit-to-path mapping of contributing bond-index sequences, or None if this sink was not allocated.

class cosmolkit.BatchFingerprintOutput¶

One batch fingerprint plus its optional metadata snapshot.

Members (2)

additional_output() → BatchFingerprintAdditionalOutput¶: Return the requested fingerprint metadata snapshot; an absent snapshot raises BatchFingerprintOutputError.

fingerprint() → Fingerprint¶: Return the bit fingerprint stored in this result.

exception cosmolkit.BatchFingerprintOutputError¶: Requested additional fingerprint metadata is not available in this batch result.

exception cosmolkit.BatchImageError¶: Batch depiction could not render or export the requested molecular images.

class cosmolkit.BatchImageParams(*, format='png', width=300, height=300, execution=None, filenames=None, report_path=None)¶

Writable configuration for batch image file export.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (6)

property execution: BatchParams¶: Batch execution configuration, separate from the chemical/output options.

property filenames: Optional[list[Optional[str]]]¶: Per-record output filenames in input order, when explicitly supplied.

property format: str¶: Input/output format selector accepted by the corresponding operation.

property height: int¶: Output image height in pixels.

property report_path: Optional[str]¶: Optional filesystem path for the export report.

property width: int¶: Output image width in pixels.

class cosmolkit.BatchParams(*, errors=None, n_jobs=None, progress_bar=None)¶

Writable configuration for batch execution and error retention.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property errors: Any¶: BatchErrorMode controlling whether a failed input raises immediately or remains as a failed slot.

property n_jobs: Optional[int]¶: Worker count for batch execution; one selects sequential execution.

property progress_bar: Optional[bool]¶: Whether batch execution reports progress.

class cosmolkit.BatchQueryParams(*, n_jobs=None, progress_bar=None, progress_callback=None)¶

Runtime overrides for ordered read results; newly failed queries always raise.

Members (3)

property n_jobs: Optional[int]¶: Worker count for batch execution; one selects sequential execution.

property progress_bar: Optional[bool]¶: Whether batch execution reports progress.

property progress_callback: Optional[Any]¶: One notification after every completed input row, including invalid rows.

exception cosmolkit.BatchValidationError(message, error_count=0, reason=None, record_errors=None)¶

Batch execution failed; errors() returns structured failures with original input indices.

Members (1)

errors() → list[BatchError]¶: Return a copy of the structured per-record BatchError values.

class cosmolkit.BestAlignmentParameters(probe_conformer_id=Ellipsis, reference_conformer_id=Ellipsis, atom_maps=None, weights=None, reflect=False, max_iterations=50, max_matches=1000000, symmetrize_conjugated_terminal_groups=True, ignore_hydrogens=True, num_threads=1)¶

Writable configuration for symmetry-aware molecular alignment.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (11)

property atom_maps: list[list[AlignmentAtomMap]]¶: Candidate probe-to-reference atom mappings considered during alignment/RMSD search.

property ignore_hydrogens: bool¶: Whether hydrogen atoms are excluded when finding alignment atom correspondences.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

property max_matches: int¶: Maximum number of substructure matches to return.

static new(probe_conformer_id=Ellipsis, reference_conformer_id=Ellipsis, atom_maps=None, weights=None, reflect=False, max_iterations=50, max_matches=1000000, symmetrize_conjugated_terminal_groups=True, ignore_hydrogens=True, num_threads=1) → BestAlignmentParameters¶: Configure symmetry-aware molecular alignment; omitted fields use the defaults shown in the signature.

property num_threads: int¶: Requested worker count; interpretation of zero follows the corresponding operation.

property probe_conformer_id: int¶: Stored conformer ID on the probe molecule.

property reference_conformer_id: int¶: Stored conformer ID on the reference molecule.

property reflect: bool¶: Whether the alignment fit may use a spatial reflection.

property symmetrize_conjugated_terminal_groups: bool¶: Whether conjugated terminal groups are treated as equivalent during alignment mapping.

property weights: Optional[list[float]]¶: Optional per-correspondence weights for alignment/RMSD calculation.

class cosmolkit.BioAssembly¶

Biological assembly definition with provenance, oligomeric classification and transformation generators.

Members (11)

author_determined: bool¶: Whether the biological assembly was identified by the structure authors.

buried_surface_area: float¶: Reported buried surface area of the assembly.

generators: list[BioAssemblyGenerator]¶: Assembly generators selecting subchains and symmetry operators.

name: str¶: Stored name of this value.

oligomeric_count: int¶: Reported number of subunits in the biological assembly.

oligomeric_details: str¶: Source description of the assembly oligomeric state.

software_determined: bool¶: Whether the biological assembly was predicted by software.

software_name: str¶: Name of the software that determined the assembly.

solvent_free_energy_change: float¶: Reported solvent free-energy change for assembly formation.

special_kind: BioAssemblySpecialKind¶: Special biological-assembly classification.

surface_area: float¶: Reported assembly surface area.

class cosmolkit.BioAssemblyGenerator¶

Biological assembly generator selecting chains/subchains and operator combinations.

Members (3)

chains: list[str]¶: Return chain rows/references in stored hierarchy order.

operators: list[BioAssemblyOperator]¶: Spatial operators used by this assembly generator.

subchains: list[str]¶: Source subchain identifiers associated with the entity.

class cosmolkit.BioAssemblyOperator¶

Named biological-assembly spatial operator.

Members (3)

name: Optional[str]¶: Stored name of this value.

operator_type: Optional[str]¶: Source classification of the assembly operator.

transform: BioTransform¶: Stored spatial transformation associated with this result or structural operator.

class cosmolkit.BioAssemblySpecialKind¶

Special assembly classification retained from structural metadata.

Declared values: NotApplicable, CompleteIcosahedral, RepresentativeHelical, CompletePoint.

Members (4)

CompleteIcosahedral = BioAssemblySpecialKind.CompleteIcosahedral¶

CompletePoint = BioAssemblySpecialKind.CompletePoint¶

NotApplicable = BioAssemblySpecialKind.NotApplicable¶

RepresentativeHelical = BioAssemblySpecialKind.RepresentativeHelical¶

class cosmolkit.BioAsu¶

Unit-cell ASU relation for a structural connection.

Declared values: Same, Different, Any.

Members (3)

Any = BioAsu.Any¶

Different = BioAsu.Different¶

Same = BioAsu.Same¶

class cosmolkit.BioAtomRow¶

Read-only structural atom row with residue ownership, chemical identity, Cartesian position, occupancy and displacement factor.

Members (12)

altloc() → Optional[str]¶: Alternate-location label, or None when the site is not alternate.

b_iso() → float¶: Isotropic atomic displacement B factor in square angstroms.

calc_flag() → BioCalcFlag¶: Atom-site calculation/refinement flag.

element() → Element¶: Chemical element as an Element value.

element_symbol() → str¶: Chemical element symbol, such as “C” or “Cl”.

formal_charge() → int¶: Formal charge in units of the elementary charge.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

name() → str¶: Stored name of this value.

occupancy() → float¶: Crystallographic atom-site occupancy.

position() → Optional[tuple[float, float, float]]¶: Cartesian position as an (x, y, z) tuple in angstroms.

residue_id() → int¶: Local identifier of the parent residue.

source() → AtomSourceIds¶: Source-format identifiers retained separately from local row identifiers.

class cosmolkit.BioBasicRefinementInfo¶

Refinement statistics shared by overall refinement and per-bin values.

Members (15)

cc_fo_fc_free: float¶: Observed/calculated structure-factor correlation for the free set.

cc_fo_fc_work: float¶: Observed/calculated structure-factor correlation for the working set.

cc_intensity_free: float¶: Reported intensity correlation for the free set.

cc_intensity_work: float¶: Reported intensity correlation for the working set.

completeness: float¶: Reflection completeness reported by the source; source units/sentinels are preserved.

fsc_free: float¶: Reported Fourier-shell correlation for the free set.

fsc_work: float¶: Reported Fourier-shell correlation for the working set.

r_all: float¶: Reported R factor over all reflections.

r_free: float¶: Reported free-set R factor.

r_work: float¶: Reported working-set R factor.

reflection_count: int¶: Number of reflections used in this refinement record.

resolution_high: float¶: High-resolution limit in angstroms reported for this dataset/bin.

resolution_low: float¶: Low-resolution limit in angstroms reported for this dataset/bin.

rfree_set_count: int¶: Number of reflections in the R-free validation set.

work_set_count: int¶: Number of reflections in the refinement working set.

class cosmolkit.BioCalcFlag(value)¶

Origin/classification of a structural atom site, including determined, calculated and dummy positions.

Members (5)

Calculated = 'Calculated'¶

Determined = 'Determined'¶

Dummy = 'Dummy'¶

NoHydrogen = 'NoHydrogen'¶

NotSet = 'NotSet'¶

class cosmolkit.BioChainRow¶

Read-only chain row with local parent/entity identifiers, source identifiers and residue/atom spans.

Members (7)

atoms() → list[BioAtomRow]¶: Return atom rows in stored graph/hierarchy order.

entity_id() → Optional[int]¶: Local identifier of the associated molecular entity, when present.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

kind() → ChainKind¶: Classification/discriminant of this value as defined by its owning type.

model_id() → int¶: Local identifier of the parent model.

residues() → list[BioResidueRow]¶: Return residue rows/references in stored hierarchy order.

source() → ChainSourceIds¶: Source-format identifiers retained separately from local row identifiers.

class cosmolkit.BioCisPep¶

Cis-peptide relationship retained from Gemmi’s PDBx/mmCIF metadata.

Members (5)

model_num: int¶: Source model number associated with this annotation.

only_altloc: int¶: Alternate-location byte restricting this annotation, or the source unspecified sentinel.

partner_c: AtomAddress¶: Structural address of the peptide carbonyl-carbon partner.

partner_n: AtomAddress¶: Structural address of the peptide nitrogen partner.

reported_angle: float¶: Cis-peptide angle in degrees reported by the source structure.

class cosmolkit.BioConnection¶

Typed _struct_conn relationship with source atom addresses.

Members (8)

asu: BioAsu¶: Whether the structural connection is within one asymmetric unit or between symmetry-related units.

kind: BioConnectionKind¶

covalent, disulfide, hydrogen, metal or unknown.

Type:: Return the structural connection type

link_id: str¶: Connection link identifier retained from structural metadata.

name: str¶: Stored name of this value.

partner1: AtomAddress¶: Structural address of the first connection partner.

partner2: AtomAddress¶: Structural address of the second connection partner.

reported_distance: float¶: Connection distance in angstroms as reported by the source structure.

reported_sym: list[int]¶: Source symmetry annotation associated with the connection.

class cosmolkit.BioConnectionKind¶

Relationship kind retained from Gemmi’s _struct_conn model.

Declared values: Covale, Disulf, Hydrog, MetalC, Unknown.

Members (5)

Covale = BioConnectionKind.Covale¶

Disulf = BioConnectionKind.Disulf¶

Hydrog = BioConnectionKind.Hydrog¶

MetalC = BioConnectionKind.MetalC¶

Unknown = BioConnectionKind.Unknown¶

class cosmolkit.BioCoordinateBlock¶

Detached atom-ordered Cartesian coordinates for a BIO hierarchy.

Members (1)

positions: list[list[float]]¶: Return Cartesian (x, y, z) positions in structural atom-row order.

class cosmolkit.BioCoordinateFormat(value)¶

Biological coordinate input format. Detect selects format recognition; explicit values select PDB, mmCIF, mmJSON or chemical-component input.

Members (6)

ChemComp = 5¶

Detect = 1¶

Mmcif = 3¶

Mmjson = 4¶

Pdb = 2¶

Unknown = 0¶

class cosmolkit.BioCrystalCell(a=1.0, b=1.0, c=1.0, alpha=90.0, beta=90.0, gamma=90.0)¶

Crystallographic cell with edge lengths a/b/c in angstroms and alpha/beta/gamma angles in degrees.

Members (6)

a: float¶: Unit-cell edge length a in angstroms.

alpha: float¶: Unit-cell angle alpha in degrees.

b: float¶: Unit-cell edge length b in angstroms.

beta: float¶: Unit-cell angle beta in degrees.

c: float¶: Unit-cell edge length c in angstroms.

gamma: float¶: Unit-cell angle gamma in degrees.

class cosmolkit.BioCrystalInfo¶

Crystallographic unit-cell and space-group information.

Members (2)

cell() → BioCrystalCell¶: Crystallographic unit-cell dimensions and angles.

space_group_number() → Optional[int]¶: Crystallographic space-group number, when available.

class cosmolkit.BioDiffractionInfo¶

Source-ordered diffraction metadata for an experiment.

Members (14)

beamline: str¶: Beamline used for diffraction collection.

collection_date: str¶: Date of diffraction data collection.

detector: str¶: Detector type recorded for the diffraction experiment.

detector_make: str¶: Detector manufacturer/model recorded for the experiment.

id: str¶: Identifier of this diffraction dataset in the structural metadata.

mono_or_laue: int¶: The source’s single-byte monochromatic/Laue code; NUL means unset.

monochromator: str¶: Monochromator description recorded for the experiment.

optics: str¶: Source description of diffraction beam optics.

scattering_type: str¶: Scattering/radiation type used by the diffraction experiment.

source: str¶: Source-format identifiers retained separately from local row identifiers.

source_type: str¶: Classification of the diffraction radiation source.

synchrotron: str¶: Synchrotron facility name retained from source metadata.

temperature: float¶: Diffraction collection temperature in kelvin, as recorded.

wavelengths: str¶: Radiation wavelengths in angstroms reported for the diffraction dataset.

class cosmolkit.BioEntityDbRef(*, db_name='', accession_code='', id_code='', isoform='', seq_begin=None, seq_end=None, db_begin=None, db_end=None, label_seq_begin=None, label_seq_end=None)¶

External sequence/database reference and its source/database residue ranges.

Members (10)

accession_code: str¶: External database accession code.

db_begin: PdbSeqId¶: Beginning external database sequence position.

db_end: PdbSeqId¶: Ending external database sequence position.

db_name: str¶: External database name.

id_code: str¶: External database entry identifier.

isoform: str¶: External sequence isoform identifier.

label_seq_begin: Optional[int]¶: Beginning mmCIF label sequence position for this mapping.

label_seq_end: Optional[int]¶: Ending mmCIF label sequence position for this mapping.

seq_begin: PdbSeqId¶: Beginning source sequence position for this database mapping.

seq_end: PdbSeqId¶: Ending source sequence position for this database mapping.

class cosmolkit.BioEntityRow¶

Read-only molecular entity metadata, including polymer kind, sequence, subchains and database references.

Members (7)

dbrefs() → list[BioEntityDbRef]¶: External database references for the entity in stored order.

full_sequence() → list[str]¶: Complete entity sequence, including residues not resolved in coordinates.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

kind() → EntityKind¶: Classification/discriminant of this value as defined by its owning type.

polymer_kind() → PolymerKind¶: Polymer category, such as peptide or nucleic acid.

source() → EntitySourceIds¶: Source-format identifiers retained separately from local row identifiers.

subchains() → list[str]¶: Source subchain identifiers associated with the entity.

class cosmolkit.BioExperimentalCrystalInfo¶

Experimental crystal metadata, distinct from lattice/coordinate crystal state.

Members (5)

description: str¶: Source-provided description of this metadata record.

diffractions: list[BioDiffractionInfo]¶: Diffraction dataset metadata associated with this crystal.

id: str¶: Identifier of this experimental crystal in the structural metadata.

ph: float¶: Crystallization pH reported in the source metadata.

ph_range: str¶: Reported crystallization pH range.

class cosmolkit.BioExperimentInfo¶

Experimental method and its associated reflection statistics.

Members (7)

b_wilson: float¶: Reported Wilson B factor.

diffraction_ids: list[str]¶: Source identifiers of diffraction datasets associated with the experiment.

method: str¶: Experimental method, or canonical operation name in operation metadata.

number_of_crystals: int¶: Number of crystals contributing to the experiment.

reflections: BioReflectionsInfo¶: Overall reflection statistics associated with the experiment.

shells: list[BioReflectionsInfo]¶: Resolution-shell reflection statistics in stored order.

unique_reflections: int¶: Reported number of unique reflections.

class cosmolkit.BioHelix¶

Helix endpoints and reported classification from PDB/mmCIF metadata.

Members (4)

end: AtomAddress¶: Return the structural atom address marking the helix end.

length: int¶: Return the source-reported helix length.

pdb_helix_class: BioHelixClass¶: PDB helix-class designation.

start: AtomAddress¶: Return the structural atom address marking the helix beginning.

class cosmolkit.BioHelixClass¶

PDB helix class values used by Gemmi’s Helix metadata.

Declared values: UnknownHelix, RAlpha, ROmega, RPi, RGamma, R310, LAlpha, LOmega, LGamma, Helix27, HelixPolyProlineNone.

Members (11)

Helix27 = BioHelixClass.Helix27¶

HelixPolyProlineNone = BioHelixClass.HelixPolyProlineNone¶

LAlpha = BioHelixClass.LAlpha¶

LGamma = BioHelixClass.LGamma¶

LOmega = BioHelixClass.LOmega¶

R310 = BioHelixClass.R310¶

RAlpha = BioHelixClass.RAlpha¶

RGamma = BioHelixClass.RGamma¶

ROmega = BioHelixClass.ROmega¶

RPi = BioHelixClass.RPi¶

UnknownHelix = BioHelixClass.UnknownHelix¶

class cosmolkit.BioMetadata¶

Source-ordered metadata attached to a biological structure.

Members (8)

authors: list[str]¶: Structure authors in stored order.

crystals: list[BioExperimentalCrystalInfo]¶: Experimental crystal and diffraction records.

experiments: list[BioExperimentInfo]¶: Experimental method and reflection metadata records.

refinement: list[BioRefinementInfo]¶: Structure refinement metadata records.

remark_300_detail: str¶: Biological assembly detail retained from PDB REMARK 300.

software: list[BioSoftwareItem]¶: Software metadata records, or the writer option selecting that category.

solved_by: str¶: Method/software reported for solving the structure.

starting_model: str¶: Starting model description reported in structural metadata.

exception cosmolkit.BioMmcifReadError¶

mmCIF biological structure input could not be read or parsed.

Members (1)

stage() → BioMmcifReadStage¶: Return the stage context recorded by this error.

class cosmolkit.BioMmcifReadStage¶

Stage of structural mmCIF reading that produced a typed error.

Declared values: CifDocument, CoordinateBlock, CrystalCell, Refinement, Tls, Experimental, Reflections, Software, Ncs, FractionalTransform, Origx, AnisotropicU, AtomSites, EntitySequence, Helices, Sheets, Connections, CisPeptides, ModifiedResidues, Assemblies, SiftsUnp, CcdRestoration, Materialization, StructureValidation.

Members (24)

AnisotropicU = BioMmcifReadStage.AnisotropicU¶

Assemblies = BioMmcifReadStage.Assemblies¶

AtomSites = BioMmcifReadStage.AtomSites¶

CcdRestoration = BioMmcifReadStage.CcdRestoration¶

CifDocument = BioMmcifReadStage.CifDocument¶

CisPeptides = BioMmcifReadStage.CisPeptides¶

Connections = BioMmcifReadStage.Connections¶

CoordinateBlock = BioMmcifReadStage.CoordinateBlock¶

CrystalCell = BioMmcifReadStage.CrystalCell¶

EntitySequence = BioMmcifReadStage.EntitySequence¶

Experimental = BioMmcifReadStage.Experimental¶

FractionalTransform = BioMmcifReadStage.FractionalTransform¶

Helices = BioMmcifReadStage.Helices¶

Materialization = BioMmcifReadStage.Materialization¶

ModifiedResidues = BioMmcifReadStage.ModifiedResidues¶

Ncs = BioMmcifReadStage.Ncs¶

Origx = BioMmcifReadStage.Origx¶

Refinement = BioMmcifReadStage.Refinement¶

Reflections = BioMmcifReadStage.Reflections¶

Sheets = BioMmcifReadStage.Sheets¶

SiftsUnp = BioMmcifReadStage.SiftsUnp¶

Software = BioMmcifReadStage.Software¶

StructureValidation = BioMmcifReadStage.StructureValidation¶

Tls = BioMmcifReadStage.Tls¶

exception cosmolkit.BioMmcifWriteError¶: The biological structure could not be serialized as mmCIF.

class cosmolkit.BioMmcifWriteParams(all_groups=True, atoms=None, block_name=None, entry=None, database_status=None, author=None, cell=None, symmetry=None, entity=None, entity_poly=None, struct_ref=None, chem_comp=None, exptl=None, diffrn=None, reflns=None, refine=None, title_keywords=None, ncs=None, struct_asym=None, origx=None, struct_conf=None, struct_sheet=None, struct_biol=None, assembly=None, conn=None, cis=None, modres=None, scale=None, atom_type=None, entity_poly_seq=None, tls=None, software=None, group_pdb=None, auth_all=None, prefer_pairs=False, compact=False, misuse_hash=False, align_pairs=0, align_loops=0)¶

Writable configuration for mmCIF output category and formatting selection.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (39)

property align_loops: int¶: Whether mmCIF loop columns are aligned.

property align_pairs: int¶: Whether mmCIF key/value pairs are column-aligned.

property all_groups: bool¶: Read/write the collective group switch without changing formatting. A mixed selection reads false; assignment sets all 32 group flags.

property assembly: bool¶: Whether mmCIF biological assembly definitions are written.

property atom_type: bool¶: Whether the atom_type category is included in mmCIF output.

property atoms: bool¶: Whether the atom_site coordinate rows are included in mmCIF output.

property auth_all: bool¶: Whether all author identifiers are included in mmCIF output.

property author: bool¶: Whether mmCIF audit-author metadata is written.

property block_name: bool¶: Name used for the mmCIF data block.

property cell: bool¶: Whether the crystallographic cell category is included in mmCIF output.

property chem_comp: bool¶: Whether mmCIF chemical component descriptions are written.

property cis: bool¶: Whether mmCIF cis-peptide annotations are written.

property compact: bool¶: Whether compact mmCIF formatting is enabled.

property conn: bool¶: Whether mmCIF inter-atom connection annotations are written.

property database_status: bool¶: Whether mmCIF database-status metadata is written.

property diffrn: bool¶: Whether mmCIF diffraction experiment metadata is written.

property entity: bool¶: Whether mmCIF entity definitions are written.

property entity_poly: bool¶: Whether mmCIF polymer entity descriptions are written.

property entity_poly_seq: bool¶: Whether mmCIF complete polymer entity sequences are written.

property entry: bool¶: Whether mmCIF entry identification is written.

property exptl: bool¶: Whether mmCIF experimental-method metadata is written.

property group_pdb: bool¶: Whether atom-site mmCIF output includes the PDB ATOM/HETATM group field.

property misuse_hash: bool¶: Whether compact hash-line formatting is used for mmCIF output.

property modres: bool¶: Whether mmCIF modified-residue annotations are written.

property ncs: bool¶: Whether mmCIF noncrystallographic symmetry operators are written.

property origx: bool¶: Whether original-coordinate transformation metadata is written.

property prefer_pairs: bool¶: Whether single-row mmCIF categories use key/value pairs instead of loops.

property refine: bool¶: Whether mmCIF refinement statistics are written.

property reflns: bool¶: Whether mmCIF reflection statistics are written.

property scale: bool¶: Whether mmCIF fractional-coordinate transformations are written.

property software: bool¶: Whether structural software metadata is written.

property struct_asym: bool¶: Whether mmCIF asymmetric-unit chain/entity associations are written.

property struct_biol: bool¶: Whether mmCIF biological-structure descriptions are written.

property struct_conf: bool¶: Whether mmCIF secondary-structure helix annotations are written.

property struct_ref: bool¶: Whether mmCIF external sequence/database references are written.

property struct_sheet: bool¶: Whether mmCIF secondary-structure sheet annotations are written.

property symmetry: bool¶: Whether mmCIF crystallographic symmetry information is written.

property title_keywords: bool¶: Whether mmCIF structure title and keywords are written.

property tls: bool¶: Whether mmCIF translation/libration/screw refinement metadata is written.

class cosmolkit.BioModelRow¶

Read-only structural model row with a local model ID, source model number and child chain span.

Members (3)

chains() → list[BioChainRow]¶: Return chain rows/references in stored hierarchy order.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

source_model_number() → Optional[int]¶: Model number recorded in the source structure.

class cosmolkit.BioModRes¶

Modified-residue metadata retained from Gemmi’s ModRes value.

Members (5)

chain_name: str¶: Chain name recorded by the source structural address.

details: str¶: Source-provided annotation detail text.

mod_id: str¶: Identifier of the residue modification.

parent_comp_id: str¶: Chemical component identifier of the unmodified parent residue.

res_id: ResidueAddress¶: Structural residue address of the modified residue.

exception cosmolkit.BioMoleculeConversionError¶: Molecule-to-biological-structure conversion failed.

exception cosmolkit.BioMoleculeError¶: A biological structure could not be projected into a molecular graph.

class cosmolkit.BioMoleculeParams(*, sanitize=True, remove_hs=True, flavor=0, proximity_bonding=True)¶

Writable configuration for structural BIO-to-Molecule conversion.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property flavor: int¶: Bit mask controlling BIO-to-molecule conversion behavior.

property proximity_bonding: bool¶: Whether spatially close atoms are considered when building molecular bonds.

property remove_hs: bool¶: Whether removable explicit hydrogens are removed during input conversion.

property sanitize: bool¶

perform the selected chemical sanitization stages. The source molecule is unchanged.

Type:: Apply to a new molecule and return the result

class cosmolkit.BioNcsOperator¶

Noncrystallographic-symmetry operator with identity, supplied/generated flag and 3D transform.

Members (3)

given: bool¶: Whether the NCS operator was explicitly supplied by the source structure.

id: str¶: Identifier of this non-crystallographic symmetry operator in the structural metadata.

transform: BioTransform¶: Stored spatial transformation associated with this result or structural operator.

exception cosmolkit.BioOperationError¶: A biological structure operation failed without committing partial changes.

exception cosmolkit.BioPdbReadError¶

PDB biological structure input could not be read or parsed.

Members (3)

line_number() → Optional[int]¶: Return the line number context recorded by this error.

record_tag() → Optional[bytes]¶: Return the record tag context recorded by this error.

stage() → BioPdbReadStage¶: Return the stage context recorded by this error.

class cosmolkit.BioPdbReadParams(*, max_line_length=0, check_non_ascii=False, ignore_ter=False, split_chain_on_ter=False, skip_remarks=False)¶

Writable configuration for PDB record handling.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (5)

property check_non_ascii: bool¶: Whether non-ASCII bytes in PDB input are checked.

property ignore_ter: bool¶: Whether PDB TER records are ignored.

property max_line_length: int¶: Maximum accepted PDB input line length.

property skip_remarks: bool¶: Whether PDB REMARK records are omitted from retained source metadata.

property split_chain_on_ter: bool¶: Whether a TER record starts a separate chain.

class cosmolkit.BioPdbReadStage¶

Reading phase at which PDB input failed: stream access, record parsing or finalization.

Declared values: Stream, Record, Finalization.

Members (3)

Finalization = BioPdbReadStage.Finalization¶

Record = BioPdbReadStage.Record¶

Stream = BioPdbReadStage.Stream¶

exception cosmolkit.BioPdbWriteError¶: The biological structure could not be serialized as PDB.

class cosmolkit.BioPdbWriteParams(ter_records=True, numbered_ter=True, ter_ignores_type=False, preserve_serial=False, end_record=True)¶

Writable configuration for PDB text formatting.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (5)

property end_record: bool¶: Whether PDB output includes the final END record.

property numbered_ter: bool¶: Whether generated PDB TER records receive serial numbers.

property preserve_serial: bool¶: Whether atom serial numbers from the input are preserved in PDB output.

property ter_ignores_type: bool¶: Whether TER output ignores the polymer/non-polymer residue classification.

property ter_records: bool¶: Whether PDB output includes TER records.

exception cosmolkit.BioReadError¶: Biological structure input could not be read or parsed.

class cosmolkit.BioReadParams(*, format=0, source_name='<string>')¶

Writable configuration for PDB/mmCIF structural text or file reading.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property format: BioCoordinateFormat¶: Input/output format selector accepted by the corresponding operation.

property source_name: str¶: Source name retained as input provenance.

class cosmolkit.BioRefinementInfo¶

Overall refinement metadata, including the source-defined per-bin and restraint records.

Members (16)

aniso_b: list[float]¶

u11, u22, u33, u12, u13, u23.

Type:: Symmetric components in Gemmi’s source order

basic: BioBasicRefinementInfo¶: The inherited overall refinement statistics.

bin_count: int¶: Number of refinement resolution bins.

bins: list[BioBasicRefinementInfo]¶: Per-resolution-bin refinement statistics in stored order.

cross_validation_method: str¶: Cross-validation method reported for refinement.

dpi_blow_r: float¶: Blow diffraction precision index calculated from the R factor.

dpi_blow_rfree: float¶: Blow diffraction precision index calculated from R-free.

dpi_cruickshank_r: float¶: Cruickshank diffraction precision index calculated from the R factor.

dpi_cruickshank_rfree: float¶: Cruickshank diffraction precision index calculated from R-free.

id: str¶: Identifier of this refinement record in the structural metadata.

luzzati_error: float¶: Reported Luzzati coordinate error estimate.

mean_b: float¶: Reported mean atomic B factor in square angstroms.

remarks: str¶: Source refinement remarks.

restr_stats: list[BioRefinementRestraint]¶: Refinement restraint statistics in stored order.

rfree_selection_method: str¶: Method used to choose the R-free reflection set.

tls_groups: list[BioTlsGroup]¶: TLS refinement groups in stored order.

class cosmolkit.BioRefinementRestraint¶

One named restraint statistic in refinement metadata.

Members (5)

count: int¶: Number of restraints represented by this refinement statistic.

dev_ideal: float¶: Reported deviation from ideal restraint geometry.

function: str¶: Name of the restraint function or failing chemical function.

name: str¶: Stored name of this value.

weight: float¶: Residue molecular weight from the residue dictionary.

class cosmolkit.BioReflectionsInfo¶

Reflection statistics retained from diffraction metadata.

Members (7)

completeness: float¶: Reflection completeness reported by the source; source units/sentinels are preserved.

mean_i_over_sigma: float¶: Reported mean intensity divided by its uncertainty.

r_merge: float¶: Reported merging R statistic.

r_sym: float¶: Reported symmetry-related R statistic.

redundancy: float¶: Reported average reflection multiplicity.

resolution_high: float¶: High-resolution limit in angstroms reported for this dataset/bin.

resolution_low: float¶: Low-resolution limit in angstroms reported for this dataset/bin.

class cosmolkit.BioResidueRow¶

Read-only residue row with chain ownership, residue classification and retained source sequence identifiers.

Members (10)

atoms() → list[BioAtomRow]¶: Return atom rows in stored graph/hierarchy order.

chain_id() → int¶: Local identifier of the parent chain.

code() → ResidueCode¶: Stored residue/atom code; its interpretation is defined by the owning value type.

entity_kind() → EntityKind¶: Structural entity category of the residue.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

info() → ResidueInfo¶: Return the associated residue dictionary information, including its classification and sequence codes.

kind() → ResidueKind¶: Classification/discriminant of this value as defined by its owning type.

name() → str¶: Stored name of this value.

sifts_unp() → BioSiftsUnpResidue¶: SIFTS/UniProt residue mapping metadata, when present.

source() → ResidueSourceIds¶: Source-format identifiers retained separately from local row identifiers.

exception cosmolkit.BioRowChainError¶: A biological chain row reference is invalid.

exception cosmolkit.BioRowModelError¶: A biological model row reference is invalid.

class cosmolkit.BioRowSpan(start, len)¶

Contiguous half-open span of structural row IDs, represented by start and length.

Members (4)

end() → int¶: Return the exclusive ending local row ID of the span.

is_empty() → bool¶: Return whether there are no stored entries.

len() → int¶: Return the number of rows in the span.

start() → int¶: Return the first local row ID in the span.

exception cosmolkit.BioRowTraverseError¶: The biological hierarchy could not be traversed with the supplied row references.

class cosmolkit.BioSelection¶

Structural selection expressed using CID syntax; applies to hierarchy rows rather than chemical SMARTS predicates.

Members (2)

static from_cid(cid) → BioSelection¶: Parse a structural CID selection expression; invalid syntax raises BioSelectionError.

to_cid() → str¶: Return the canonical CID text for this structural selection.

exception cosmolkit.BioSelectionCopyCause¶: Underlying hierarchy or reference error encountered while copying a structural selection.

exception cosmolkit.BioSelectionCopyError¶: Selected biological rows could not be copied into a consistent structure.

exception cosmolkit.BioSelectionMatchError¶: A structural selection could not be evaluated against the biological hierarchy.

exception cosmolkit.BioSelectionParseError¶: The structural selection expression is invalid.

class cosmolkit.BioSheet¶

A sheet containing strands in source order.

Members (2)

name: str¶: Stored name of this value.

strands: list[BioStrand]¶: Sheet strand annotations in source order.

class cosmolkit.BioSiftsUnpResidue(residue=None, accession_index=0, number=0)¶

SIFTS mapping from a structural residue to a UniProt accession index and residue number.

Members (3)

accession_index: int¶: Index of the UniProt accession referenced by this SIFTS mapping.

number: int¶: UniProt residue number retained by this SIFTS mapping.

residue: Optional[int]¶: Return the parent residue reference.

class cosmolkit.BioSoftwareClassification¶

Classification of the software entry recorded in structural metadata.

The explicit representation and declaration order preserve Gemmi’s SoftwareItem::Classification integer values.

Declared values: DataCollection, DataExtraction, DataProcessing, DataReduction, DataScaling, ModelBuilding, Phasing, Refinement, Unspecified.

Members (9)

DataCollection = BioSoftwareClassification.DataCollection¶

DataExtraction = BioSoftwareClassification.DataExtraction¶

DataProcessing = BioSoftwareClassification.DataProcessing¶

DataReduction = BioSoftwareClassification.DataReduction¶

DataScaling = BioSoftwareClassification.DataScaling¶

ModelBuilding = BioSoftwareClassification.ModelBuilding¶

Phasing = BioSoftwareClassification.Phasing¶

Refinement = BioSoftwareClassification.Refinement¶

Unspecified = BioSoftwareClassification.Unspecified¶

class cosmolkit.BioSoftwareItem¶

One source-ordered software record from structural metadata.

Members (7)

classification: BioSoftwareClassification¶: Role of the software in collection, processing, model building or refinement.

contact_author: str¶: Contact author recorded for this software entry.

contact_author_email: str¶: Contact-author email recorded for this software entry.

date: str¶: Date recorded in the source metadata.

description: str¶: Source-provided description of this metadata record.

name: str¶: Stored name of this value.

version: str¶: Return the version identifier recorded by this value or implementation.

class cosmolkit.BioStrand¶

One ordered strand and its source endpoint/hydrogen-bond addresses.

Members (6)

end: AtomAddress¶: Return the structural atom address marking the strand end.

hbond_atom1: AtomAddress¶: Structural address of the first sheet hydrogen-bond atom.

hbond_atom2: AtomAddress¶: Structural address of the second sheet hydrogen-bond atom.

name: str¶: Stored name of this value.

sense: int¶: Strand orientation relative to the previous strand as encoded by the source.

start: AtomAddress¶: Return the structural atom address marking the strand beginning.

exception cosmolkit.BioStructureError¶: Biological hierarchy, coordinates or row references are structurally inconsistent.

class cosmolkit.BioStructureParts¶

Detached structural hierarchy, coordinates and metadata used for checked BioStructure construction.

Members (1)

input_format: Any¶: Detected/declared structural input format.

class cosmolkit.BioStructureSourceState¶

Source-defined structure state that is not part of the atom hierarchy.

Members (10)

conect_map: dict[int, list[int]]¶: PDB serial-to-serial connectivity; duplicate targets encode repeated connectivity entries and remain distinct in each sorted target list.

has_d_fraction: bool¶: Whether the source includes deuterium-fraction annotations.

has_origx: bool¶: Whether the structure contains an original-coordinate transformation.

info: dict[str, str]¶: Return the associated residue dictionary information, including its classification and sequence codes.

name: str¶: Stored name of this value.

non_ascii_line: int¶: Source line associated with non-ASCII input detection, when recorded.

origx: BioTransform¶: Original-coordinate transformation stored in the structure.

raw_remarks: list[str]¶: Original PDB REMARK records, in source order.

resolution: float¶: Experimental resolution in angstroms as recorded in the structure.

ter_status: int¶: Source TER-record handling state.

class cosmolkit.BioTlsGroup¶

Tensor, origin, and ordered selections for one TLS group.

Members (7)

id: str¶: Identifier of this TLS refinement group in the structural metadata.

l: list[float]¶

u11, u22, u33, u12, u13, u23.

Type:: Symmetric components in source order

num_id: int¶: Source’s small numeric ID; -1 means no numeric ID was assigned.

origin: list[float]¶: Cartesian origin of the TLS group in angstroms.

s: list[list[float]]¶: Full row-major 3x3 S matrix.

selections: list[BioTlsSelection]¶: Residue selections included in this TLS group.

t: list[float]¶

u11, u22, u33, u12, u13, u23.

Type:: Symmetric components in source order

class cosmolkit.BioTlsSelection¶

Residue range selected for TLS refinement, with chain name, sequence endpoints and insertion codes.

Members (4)

chain: str¶: Return the chain reference for a local chain identifier.

details: str¶: Source-provided annotation detail text.

res_begin: PdbSeqId¶: Beginning residue address of the TLS selection.

res_end: PdbSeqId¶: Ending residue address of the TLS selection.

class cosmolkit.BioTransform¶

Three-dimensional affine transformation used by structural symmetry and assembly metadata.

Members (3)

approx(other, epsilon) → bool¶: Source affine-transform approximate equality, including its asymmetric NaN treatment.

matrix: list[list[float]]¶: Return the 3 by 3 linear transformation matrix in row order.

translation: list[float]¶: Return the three-component translation vector.

class cosmolkit.Bond¶

Read-only bond value containing endpoint atom indices, order and stereochemical annotations.

Members (17)

begin() → int¶: Zero-based index of the bond begin atom.

cip_descriptor() → Optional[CipDescriptor]¶: Assigned CIP stereochemical descriptor, when present.

cip_neighbor_order() → Optional[list[int]]¶: Neighbor ordering retained for interpreting the assigned CIP descriptor.

direction() → BondDirection¶: Stored directional/wedge bond annotation.

direction_code() → int¶: Return the integer representation of the stored direction.

direction_name() → str¶: Return the symbolic name of the stored direction.

end() → int¶: Zero-based index of the bond end atom.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

is_aromatic() → bool¶: Whether the stored atom or bond has the aromatic flag.

is_conjugated() → bool¶: Whether the bond is marked conjugated.

order() → BondOrder¶: Bond order as a BondOrder value, including aromatic and dative orders.

order_code() → int¶: Integer code identifying the stored bond order.

order_name() → str¶: Return the symbolic name of the stored order.

stereo() → BondStereo¶: Stored double-bond or other bond stereochemistry annotation.

stereo_atoms() → Optional[list[int]]¶: Atom indices used to define the bond stereochemistry.

stereo_code() → int¶: Return the integer representation of the stored stereo.

stereo_name() → str¶: Return the symbolic name of the stored stereo.

class cosmolkit.BondDirection(value)¶

Directional bond annotation used by wedge, dash and double-bond notation.

Members (7)

BEGINDASH = 2¶

BEGINWEDGE = 1¶

EITHERDOUBLE = 5¶

ENDDOWNRIGHT = 3¶

ENDUPRIGHT = 4¶

NONE = 0¶

UNKNOWN = 6¶

class cosmolkit.BondOrder(value)¶

Chemical bond order, including aromatic, dative and zero-order bonds.

Members (22)

AROMATIC = 12¶

DATIVE = 17¶

DATIVEL = 18¶

DATIVEONE = 16¶

DATIVER = 19¶

DOUBLE = 2¶

FIVEANDAHALF = 11¶

FOURANDAHALF = 10¶

HEXTUPLE = 6¶

HYDROGEN = 14¶

IONIC = 13¶

ONEANDAHALF = 7¶

OTHER = 20¶

QUADRUPLE = 4¶

QUINTUPLE = 5¶

SINGLE = 1¶

THREEANDAHALF = 9¶

THREECENTER = 15¶

TRIPLE = 3¶

TWOANDAHALF = 8¶

UNSPECIFIED = 0¶

ZERO = 21¶

class cosmolkit.BondSpec(begin, end, order)¶

Bond construction specification containing begin/end atom indices and bond order.

Members (1)

static new(begin, end, order) → BondSpec¶: Construct a BondSpec value from the supplied inputs.

class cosmolkit.BondStereo(value)¶

Stored bond stereochemistry, including cis/trans, E/Z and atropisomeric states.

Members (8)

STEREOANY = 1¶

STEREOATROPCCW = 7¶

STEREOATROPCW = 6¶

STEREOCIS = 4¶

STEREOE = 3¶

STEREONONE = 0¶

STEREOTRANS = 5¶

STEREOZ = 2¶

class cosmolkit.ChainKind(value)¶

Structural chain classification based on its residue composition, including protein, nucleic acids, ligands, water and mixed chains.

Members (9)

Dna = 'Dna'¶

LigandOnly = 'LigandOnly'¶

Mixed = 'Mixed'¶

Protein = 'Protein'¶

ProteinDnaComplex = 'ProteinDnaComplex'¶

ProteinRnaComplex = 'ProteinRnaComplex'¶

Rna = 'Rna'¶

Unknown = 'Unknown'¶

WaterOnly = 'WaterOnly'¶

class cosmolkit.ChainSourceIds¶

Source chain identifiers: author chain name and mmCIF label asymmetric-unit ID.

Members (2)

auth_chain_id() → Optional[str]¶: Author-provided chain identifier from the input structure.

label_asym_id() → Optional[str]¶: mmCIF label_asym_id identifying the asymmetric-unit chain.

class cosmolkit.ChemistryProblem¶

One chemical problem recorded during validation, with its sanitization stage and typed error.

Members (2)

error: ChemistryProblemError¶: Return the typed exception describing this detected chemistry problem.

operation: SanitizeStage¶: Sanitization stage in which this chemical problem was detected.

exception cosmolkit.ChemistryProblemError¶: Chemical problem detection could not inspect or prepare the supplied molecule.

class cosmolkit.ChemistryProblemReport¶

Ordered chemical problems found while inspecting a molecular graph.

Members (1)

problems: list[ChemistryProblem]¶: Return all detected chemistry problems in report order.

class cosmolkit.ChiralTag(value)¶

Local atom chirality annotation; this is not an assigned CIP descriptor.

Members (9)

CHI_ALLENE = 5¶

CHI_OCTAHEDRAL = 8¶

CHI_OTHER = 3¶

CHI_SQUAREPLANAR = 6¶

CHI_TETRAHEDRAL = 4¶

CHI_TETRAHEDRAL_CCW = 2¶

CHI_TETRAHEDRAL_CW = 1¶

CHI_TRIGONALBIPYRAMIDAL = 7¶

CHI_UNSPECIFIED = 0¶

class cosmolkit.CipDescriptor(value)¶

CIP stereochemical descriptor; values preserve upper/lower-case distinctions such as R versus r.

Members (12)

E = 'E'¶

M = 'M'¶

P = 'P'¶

R = 'R'¶

S = 'S'¶

Z = 'Z'¶

e = 'e'¶

m = 'm'¶

p = 'p'¶

r = 'r'¶

s = 's'¶

z = 'z'¶

exception cosmolkit.CipDescriptorError¶: The requested CIP descriptor is not recognized.

exception cosmolkit.CipLabelerError¶: CIP stereochemical labeling failed or exceeded the requested iteration limit.

class cosmolkit.CipLabelOptions(*, atoms=None, bonds=None, max_recursive_iterations=0)¶

Writable configuration for CIP stereochemical label assignment.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property atoms: Optional[list[int]]¶: Atom indices to label, or None to consider all atoms.

property bonds: Optional[list[int]]¶: Bond indices to label, or None to consider all bonds.

property max_recursive_iterations: int¶: Maximum recursive CIP ranking iterations; zero removes the user-specified iteration limit.

exception cosmolkit.CipRankError¶: CIP atom ranking failed for the supplied molecule.

class cosmolkit.CompiledQuery¶

Reusable query with a precomputed matching order; retains the canonical QueryGraph predicates.

Members (4)

atom_order() → list[int]¶: Return the query atom visitation order chosen by the matcher compiler.

num_atoms() → int¶: Number of atoms in the graph or selected structure.

num_bonds() → int¶: Number of bonds in the graph.

query() → QueryGraph¶: Return the QueryGraph represented by this compiled query.

class cosmolkit.Conformer2D¶

Stored 2D conformer with atom-ordered XY coordinates, distinct from 3D conformers.

Members (3)

coordinates() → list[list[float]]¶: Return atom-ordered XY coordinate rows from this stored 2D conformer.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

props() → dict[str, str]¶: Stored typed properties; returned values do not provide mutable access to the owning molecule.

class cosmolkit.Conformer3D¶

Read-only stored 3D conformer with an explicit ID and atom-ordered positions. coordinates() returns an independent float64 NumPy array of shape (N, 3).

Members (4)

coordinates() → numpy.ndarray[Any, numpy.dtype[numpy.float64]]¶: Return an independent float64 NumPy array of shape (num_atoms, 3), in angstroms and molecule atom order.

id() → int¶: Return the stored conformer identifier, which need not equal its list position.

is_3d() → bool¶: Whether the conformer/input is designated three-dimensional.

props() → dict[str, str]¶: Stored typed properties; returned values do not provide mutable access to the owning molecule.

class cosmolkit.ConformerAlignmentParameters(atom_indices=None, conformer_ids=None, weights=None, reflect=False, max_iterations=50)¶

Writable configuration for alignment of stored conformers within one molecule.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (6)

property atom_indices: Optional[list[int]]¶: Optional atom indices restricting the conformer alignment calculation.

property conformer_ids: Optional[list[int]]¶: Identifiers of the selected/generated 3D conformers.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

static new(atom_indices=None, conformer_ids=None, weights=None, reflect=False, max_iterations=50) → ConformerAlignmentParameters¶: Configure alignment of stored conformers within one molecule; omitted fields use the defaults shown in the signature.

property reflect: bool¶: Whether the alignment fit may use a spatial reflection.

property weights: Optional[list[float]]¶: Optional per-correspondence weights for alignment/RMSD calculation.

class cosmolkit.ConformerAlignmentReport¶

Molecule/conformer alignment report with ordered RMSD values.

Members (1)

rmsds() → list[float]¶: Per-conformer RMSD values in the reported conformer order.

class cosmolkit.ConformerRmsd¶

RMSD in angstroms for one probe/reference conformer-ID pair.

Members (3)

probe_conformer_id() → int¶: Stored conformer ID on the probe molecule.

reference_conformer_id() → int¶: Stored conformer ID on the reference molecule.

rmsd() → float¶: Root-mean-square coordinate deviation in angstroms.

exception cosmolkit.Coordinate2DError¶: 2D coordinate generation or assignment failed.

class cosmolkit.Coordinate2DInputParams(z_policy=Ellipsis)¶

Writable configuration for caller-supplied 2D coordinates and optional Z-column policy.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property z_policy: CoordinateZPolicy¶

ignore, require_zero, or error.

Type:: Policy for a Z column supplied to a 2D coordinate API

exception cosmolkit.Coordinate2DLayoutError¶: The molecular 2D layout could not be computed.

class cosmolkit.Coordinate2DParams(coordinate_map=None, *, canonical_orientation=False, clear_existing_2d=True, flips_per_sample=0, samples=0, sample_seed=0, permute_degree_four=False, force_rdkit=False, use_ring_templates=False)¶

Writable configuration for 2D coordinate generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (9)

property canonical_orientation: bool¶: Whether generated 2D coordinates are canonically oriented.

property clear_existing_2d: bool¶: Whether existing 2D conformers are cleared before storing generated coordinates.

property coordinate_map: dict[int, list[float]]¶: Fixed coordinates indexed by atom index for coordinate generation.

property flips_per_sample: int¶: Number of rotatable-bond flips attempted per 2D layout sample.

property force_rdkit: bool¶: Whether to force the RDKit-style coordinate generation path.

property permute_degree_four: bool¶: Whether degree-four atom arrangements are permuted during 2D sampling.

property sample_seed: int¶: Random seed for sampled 2D coordinate generation.

property samples: int¶: Number of randomized 2D layout samples.

property use_ring_templates: bool¶: Whether ring templates are used for 2D layouts.

exception cosmolkit.Coordinate2DTemplateError¶: A 2D depiction template could not be used for the supplied molecule.

class cosmolkit.Coordinate3DInputParams(is_3d=True)¶

Writable configuration for caller-supplied 3D conformers.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property is_3d: bool¶: Whether the conformer/input is designated three-dimensional.

exception cosmolkit.Coordinate3DReadError¶: The requested stored 3D conformer or atom coordinate is unavailable.

class cosmolkit.CoordinateBlock¶

Detached coordinate storage with separate 2D and 3D conformer collections.

Members (4)

conformers_2d: list[Conformer2D]¶

Zero or more 2D conformers.

Coordinates are stored in the same atom-index order as TopologyBlock. Any operation changing atom indices must remap or drop this block through a topology report. Do not mutate this block directly from operation code.

conformers_3d: list[Conformer3D]¶: Return stored 3D conformer values in storage order, preserving each conformer ID.

source_conformer_order: Optional[list[CoordinateDimension]]¶: The actual interleaving of source conformer appends. Occurrences index each dimension’s collection; IDs and is_3d do not encode this fact. None is sufficient only when at most one dimension has stored rows.

source_coordinate_dim: Optional[CoordinateDimension]¶: Coordinate dimensionality recorded by the source format, when present.

class cosmolkit.CoordinateDimension¶

Coordinate dimensionality: TwoD denotes XY rows and ThreeD denotes XYZ rows.

Declared values: TwoD, ThreeD.

Members (2)

ThreeD = CoordinateDimension.ThreeD¶

TwoD = CoordinateDimension.TwoD¶

exception cosmolkit.CoordinateInputError¶: Coordinate input has an invalid shape, atom count, index or numerical value.

class cosmolkit.CoordinateRmsdParameters(probe_conformer_id=Ellipsis, reference_conformer_id=Ellipsis, atom_maps=None, weights=None, max_matches=1000000, symmetrize_conjugated_terminal_groups=True)¶

Writable configuration for coordinate RMSD evaluation without fitting.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

property atom_maps: list[list[AlignmentAtomMap]]¶: Candidate probe-to-reference atom mappings considered during alignment/RMSD search.

property max_matches: int¶: Maximum number of substructure matches to return.

static new(probe_conformer_id=Ellipsis, reference_conformer_id=Ellipsis, atom_maps=None, weights=None, max_matches=1000000, symmetrize_conjugated_terminal_groups=True) → CoordinateRmsdParameters¶: Configure coordinate RMSD evaluation without fitting; omitted fields use the defaults shown in the signature.

property probe_conformer_id: int¶: Stored conformer ID on the probe molecule.

property reference_conformer_id: int¶: Stored conformer ID on the reference molecule.

property symmetrize_conjugated_terminal_groups: bool¶: Whether conjugated terminal groups are treated as equivalent during alignment mapping.

property weights: Optional[list[float]]¶: Optional per-correspondence weights for alignment/RMSD calculation.

class cosmolkit.CoordinateZPolicy¶

Policy for a third coordinate column supplied to a 2D API: Ignore drops it, RequireZero accepts only zero Z, and Error rejects a third column.

Declared values: Ignore, RequireZero, Error.

Members (4)

Error = CoordinateZPolicy.Error¶

Ignore = CoordinateZPolicy.Ignore¶

RequireZero = CoordinateZPolicy.RequireZero¶

static from_name(value) → CoordinateZPolicy¶: Parse a documented selector string; unknown strings raise an error.

class cosmolkit.CrippenTotals¶

Wildman-Crippen logP and molar-refractivity scalar results.

Members (2)

logp: float¶: Wildman-Crippen octanol/water log partition coefficient.

molar_refractivity: float¶: Wildman-Crippen molar refractivity.

class cosmolkit.CxCoordinateSelection¶

Selects which stored coordinate set a CXSMILES export uses.

Members (3)

static auto() → CxCoordinateSelection¶: Construct a coordinate selection for automatic coordinate resolution, rejecting an ambiguous selection.

static three_d(id) → CxCoordinateSelection¶: Construct a coordinate selection for the stored 3D conformer with the supplied ID.

static two_d(id) → CxCoordinateSelection¶: Construct a coordinate selection for the separate stored 2D conformer.

class cosmolkit.CxSmilesFields¶

Bit mask selecting CXSMILES/CXSMARTS annotation fields. Combine flags with bitwise OR; coordinate fields use explicit coordinate selection.

Members (19)

ALL = <cosmolkit.CxSmilesFields object>¶

ALL_BUT_COORDS = <cosmolkit.CxSmilesFields object>¶

ATOM_LABELS = <cosmolkit.CxSmilesFields object>¶

ATOM_PROPS = <cosmolkit.CxSmilesFields object>¶

BOND_ATROPISOMER = <cosmolkit.CxSmilesFields object>¶

BOND_CFG = <cosmolkit.CxSmilesFields object>¶

COORDINATE_BONDS = <cosmolkit.CxSmilesFields object>¶

COORDS = <cosmolkit.CxSmilesFields object>¶

ENHANCED_STEREO = <cosmolkit.CxSmilesFields object>¶

HYDROGEN_BONDS = <cosmolkit.CxSmilesFields object>¶

LINKNODES = <cosmolkit.CxSmilesFields object>¶

MOLFILE_VALUES = <cosmolkit.CxSmilesFields object>¶

NONE = <cosmolkit.CxSmilesFields object>¶

POLYMER = <cosmolkit.CxSmilesFields object>¶

RADICALS = <cosmolkit.CxSmilesFields object>¶

SGROUPS = <cosmolkit.CxSmilesFields object>¶

ZERO_BONDS = <cosmolkit.CxSmilesFields object>¶

bits() → int¶: Return the underlying unsigned integer bit mask.

contains(other) → bool¶: Return whether every bit in the supplied flag value is included in this mask.

class cosmolkit.CxSmilesWriteParams(*, smiles=None, fields=None, coordinate_selection=None)¶

Writable configuration for CXSMILES serialization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property coordinate_selection: CxCoordinateSelection¶: Explicit selection of stored 2D coordinates, a 3D conformer, or automatic resolution.

property fields: CxSmilesFields¶: CX annotation field-selection bit mask.

property smiles: SmilesWriteParams¶: Nested SMILES writer configuration.

class cosmolkit.DenseMatrix¶

Square dense numeric matrix with atom-indexed rows and columns; values retain the algorithm-defined order.

Members (3)

dimension() → int¶: Return the number of rows and columns in this square matrix.

get(row, column) → Optional[float]¶: Return the value at the supplied row and column indices.

values() → list[float]¶: Return flattened matrix values in row-major order.

exception cosmolkit.DescriptorError¶: A molecular descriptor could not be evaluated for the supplied molecule or options.

exception cosmolkit.DescriptorReadError¶: A molecular descriptor could not read the required chemical state.

class cosmolkit.DistanceMatrix3dParams(*, conformer_id=None, use_atom_weights=False)¶

Writable configuration for 3D distance-matrix conformer selection.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property use_atom_weights: bool¶: Whether atomic weights contribute to the distance-matrix diagonal.

class cosmolkit.DistanceMatrixParams(*, use_bond_order=False, use_atom_weights=False)¶

Writable configuration for graph distance-matrix weights.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property use_atom_weights: bool¶: Whether atomic weights contribute to the distance-matrix diagonal.

property use_bond_order: bool¶: Whether bond-order weights are included in the calculation.

exception cosmolkit.DrawingError¶: Molecular depiction or image rendering failed for the graph or drawing options.

exception cosmolkit.DrawingWriteError¶: A rendered molecular image could not be written to the requested path.

class cosmolkit.Element¶

Stable chemical-element identity.

The private atomic number is always in the inclusive range 0..=118. Zero is the source-compatible dummy atom (*); 1..=118 are H through Og.

Members (123)

AC = Element(symbol='Ac', atomic_number=89)¶

AG = Element(symbol='Ag', atomic_number=47)¶

AL = Element(symbol='Al', atomic_number=13)¶

AM = Element(symbol='Am', atomic_number=95)¶

AR = Element(symbol='Ar', atomic_number=18)¶

AS = Element(symbol='As', atomic_number=33)¶

AT = Element(symbol='At', atomic_number=85)¶

AU = Element(symbol='Au', atomic_number=79)¶

B = Element(symbol='B', atomic_number=5)¶

BA = Element(symbol='Ba', atomic_number=56)¶

BE = Element(symbol='Be', atomic_number=4)¶

BH = Element(symbol='Bh', atomic_number=107)¶

BI = Element(symbol='Bi', atomic_number=83)¶

BK = Element(symbol='Bk', atomic_number=97)¶

BR = Element(symbol='Br', atomic_number=35)¶

C = Element(symbol='C', atomic_number=6)¶

CA = Element(symbol='Ca', atomic_number=20)¶

CD = Element(symbol='Cd', atomic_number=48)¶

CE = Element(symbol='Ce', atomic_number=58)¶

CF = Element(symbol='Cf', atomic_number=98)¶

CL = Element(symbol='Cl', atomic_number=17)¶

CM = Element(symbol='Cm', atomic_number=96)¶

CN = Element(symbol='Cn', atomic_number=112)¶

CO = Element(symbol='Co', atomic_number=27)¶

CR = Element(symbol='Cr', atomic_number=24)¶

CS = Element(symbol='Cs', atomic_number=55)¶

CU = Element(symbol='Cu', atomic_number=29)¶

DB = Element(symbol='Db', atomic_number=105)¶

DS = Element(symbol='Ds', atomic_number=110)¶

DUMMY = Element(symbol='*', atomic_number=0)¶

DY = Element(symbol='Dy', atomic_number=66)¶

ER = Element(symbol='Er', atomic_number=68)¶

ES = Element(symbol='Es', atomic_number=99)¶

EU = Element(symbol='Eu', atomic_number=63)¶

F = Element(symbol='F', atomic_number=9)¶

FE = Element(symbol='Fe', atomic_number=26)¶

FL = Element(symbol='Fl', atomic_number=114)¶

FM = Element(symbol='Fm', atomic_number=100)¶

FR = Element(symbol='Fr', atomic_number=87)¶

GA = Element(symbol='Ga', atomic_number=31)¶

GD = Element(symbol='Gd', atomic_number=64)¶

GE = Element(symbol='Ge', atomic_number=32)¶

H = Element(symbol='H', atomic_number=1)¶

HE = Element(symbol='He', atomic_number=2)¶

HF = Element(symbol='Hf', atomic_number=72)¶

HG = Element(symbol='Hg', atomic_number=80)¶

HO = Element(symbol='Ho', atomic_number=67)¶

HS = Element(symbol='Hs', atomic_number=108)¶

I = Element(symbol='I', atomic_number=53)¶

IN = Element(symbol='In', atomic_number=49)¶

IR = Element(symbol='Ir', atomic_number=77)¶

K = Element(symbol='K', atomic_number=19)¶

KR = Element(symbol='Kr', atomic_number=36)¶

LA = Element(symbol='La', atomic_number=57)¶

LI = Element(symbol='Li', atomic_number=3)¶

LR = Element(symbol='Lr', atomic_number=103)¶

LU = Element(symbol='Lu', atomic_number=71)¶

LV = Element(symbol='Lv', atomic_number=116)¶

MC = Element(symbol='Mc', atomic_number=115)¶

MD = Element(symbol='Md', atomic_number=101)¶

MG = Element(symbol='Mg', atomic_number=12)¶

MN = Element(symbol='Mn', atomic_number=25)¶

MO = Element(symbol='Mo', atomic_number=42)¶

MT = Element(symbol='Mt', atomic_number=109)¶

N = Element(symbol='N', atomic_number=7)¶

NA = Element(symbol='Na', atomic_number=11)¶

NB = Element(symbol='Nb', atomic_number=41)¶

ND = Element(symbol='Nd', atomic_number=60)¶

NE = Element(symbol='Ne', atomic_number=10)¶

NH = Element(symbol='Nh', atomic_number=113)¶

NI = Element(symbol='Ni', atomic_number=28)¶

NO = Element(symbol='No', atomic_number=102)¶

NP = Element(symbol='Np', atomic_number=93)¶

O = Element(symbol='O', atomic_number=8)¶

OG = Element(symbol='Og', atomic_number=118)¶

OS = Element(symbol='Os', atomic_number=76)¶

P = Element(symbol='P', atomic_number=15)¶

PA = Element(symbol='Pa', atomic_number=91)¶

PB = Element(symbol='Pb', atomic_number=82)¶

PD = Element(symbol='Pd', atomic_number=46)¶

PM = Element(symbol='Pm', atomic_number=61)¶

PO = Element(symbol='Po', atomic_number=84)¶

PR = Element(symbol='Pr', atomic_number=59)¶

PT = Element(symbol='Pt', atomic_number=78)¶

PU = Element(symbol='Pu', atomic_number=94)¶

RA = Element(symbol='Ra', atomic_number=88)¶

RB = Element(symbol='Rb', atomic_number=37)¶

RE = Element(symbol='Re', atomic_number=75)¶

RF = Element(symbol='Rf', atomic_number=104)¶

RG = Element(symbol='Rg', atomic_number=111)¶

RH = Element(symbol='Rh', atomic_number=45)¶

RN = Element(symbol='Rn', atomic_number=86)¶

RU = Element(symbol='Ru', atomic_number=44)¶

S = Element(symbol='S', atomic_number=16)¶

SB = Element(symbol='Sb', atomic_number=51)¶

SC = Element(symbol='Sc', atomic_number=21)¶

SE = Element(symbol='Se', atomic_number=34)¶

SG = Element(symbol='Sg', atomic_number=106)¶

SI = Element(symbol='Si', atomic_number=14)¶

SM = Element(symbol='Sm', atomic_number=62)¶

SN = Element(symbol='Sn', atomic_number=50)¶

SR = Element(symbol='Sr', atomic_number=38)¶

TA = Element(symbol='Ta', atomic_number=73)¶

TB = Element(symbol='Tb', atomic_number=65)¶

TC = Element(symbol='Tc', atomic_number=43)¶

TE = Element(symbol='Te', atomic_number=52)¶

TH = Element(symbol='Th', atomic_number=90)¶

TI = Element(symbol='Ti', atomic_number=22)¶

TL = Element(symbol='Tl', atomic_number=81)¶

TM = Element(symbol='Tm', atomic_number=69)¶

TS = Element(symbol='Ts', atomic_number=117)¶

U = Element(symbol='U', atomic_number=92)¶

V = Element(symbol='V', atomic_number=23)¶

W = Element(symbol='W', atomic_number=74)¶

XE = Element(symbol='Xe', atomic_number=54)¶

Y = Element(symbol='Y', atomic_number=39)¶

YB = Element(symbol='Yb', atomic_number=70)¶

ZN = Element(symbol='Zn', atomic_number=30)¶

ZR = Element(symbol='Zr', atomic_number=40)¶

atomic_number() → int¶: Atomic number (proton count); zero denotes a dummy atom.

static from_atomic_number(atomic_number) → Optional[Element]¶: Construct an element from a checked atomic number.

static from_symbol(symbol) → Optional[Element]¶: Construct an element from a source-recognized symbol.

symbol() → str¶: Chemical element symbol represented by this value.

class cosmolkit.ElementInfo¶

Periodic-table metadata for one element, including its symbol, atomic number, atomic weights and allowed valences.

Members (8)

atomic_number() → int¶: Atomic number (proton count); zero denotes a dummy atom.

atomic_weight() → float¶: Average atomic weight from the element table.

element() → Element¶: Chemical element as an Element value.

outer_electrons() → int¶: Number of outer-shell electrons from the element table.

period() → int¶: Periodic-table period of the element.

rb0() → float¶: RDKit’s source-defined Rb0 bond radius in angstroms.

symbol() → str¶: Chemical element symbol represented by this value.

valences() → list[int]¶: Allowed valence values from the element table.

class cosmolkit.EmbedMoleculeResult¶

Single-conformer embedding result: molecule, updated parameters, conformer ID and success flag.

Members (4)

conf_id() → int¶: Identifier of the generated conformer, or the operation failure sentinel.

molecule() → Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

ok() → bool¶: Whether the embedding attempt produced a conformer.

params() → EmbedParams¶: Return the parameter values associated with this result or settings view.

class cosmolkit.EmbedMultipleConfsResult¶

Multi-conformer embedding result containing generated IDs, requested/generated counts and updated parameters.

Members (5)

conf_ids() → list[int]¶: Identifiers of the successfully generated conformers in generation order.

generated_count() → int¶: Number of successfully generated conformers.

molecule() → Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

params() → EmbedParams¶: Return the parameter values associated with this result or settings view.

requested_num_confs() → int¶: Number of conformers requested from the embedding operation.

class cosmolkit.EmbedParams(*, max_iterations=0, num_threads=1, random_seed=-1, clear_conformers=True, use_random_coords=False, box_size_mult=2.0, rand_neg_eig=True, num_zero_fail=1, coord_map=None, optimizer_force_tol=0.001, ignore_smoothing_failures=False, enforce_chirality=True, use_exp_torsion_angle_prefs=False, use_basic_knowledge=False, verbose=False, basin_thresh=5.0, prune_rms_thresh=-1.0, only_heavy_atoms_for_rms=True, et_version=2, embed_fragments_separately=True, use_small_ring_torsions=False, use_macrocycle_torsions=False, use_macrocycle14config=False, timeout=0, cpci=None, force_trans_amides=True, use_symmetry_for_pruning=True, bounds_mat_force_scaling=1.0, track_failures=False, enable_sequential_random_seeds=False, symmetrize_conjugated_terminal_groups_for_pruning=True)¶

Writable configuration for distance-geometry 3D conformer embedding.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (43)

property basin_thresh: float¶: Energy threshold used when considering distinct embedding basins.

property bounds_mat_force_scaling: float¶: Scale applied to distance-bound constraint forces.

property box_size_mult: float¶: Scale controlling the initial random-coordinate box.

property clear_conformers: bool¶: Whether existing 3D conformers are cleared before embedding.

property coord_map: Optional[dict[int, list[float]]]¶: Fixed 3D coordinates indexed by atom index for embedding.

property cpci: Optional[dict[tuple[int, int], float]]¶: Custom pairwise Coulomb-like interaction strengths keyed by atom-index pairs.

static dg() → EmbedParams¶: Return distance-geometry embedding parameters without experimental torsion or basic-knowledge constraints.

property embed_fragments_separately: bool¶: Whether disconnected fragments are embedded independently.

property enable_sequential_random_seeds: bool¶: Whether successive embeddings derive seeds sequentially from the configured seed.

property enforce_chirality: bool¶: Whether embedding enforces specified stereochemistry.

property et_version: int¶: Version of the experimental torsion-angle preference parameter set.

static etdg() → EmbedParams¶: Return distance-geometry parameters with experimental torsion preferences.

static etdg_v2() → EmbedParams¶: Return distance-geometry parameters using version 2 experimental torsion preferences.

static etkdg() → EmbedParams¶: Return embedding parameters combining experimental torsions and basic chemical knowledge.

static etkdg_v2() → EmbedParams¶: Return ETKDG embedding parameters using version 2 torsion preferences.

static etkdg_v3() → EmbedParams¶: Return ETKDGv3 embedding parameters, including its macrocycle geometry configuration.

failures: list[int]¶: Counts of recorded embedding failures by failure-cause category.

property force_trans_amides: bool¶: Whether amide bonds are constrained toward trans geometry during embedding.

property ignore_smoothing_failures: bool¶: Whether embedding may proceed after bounds-smoothing failure.

static kdg() → EmbedParams¶: Return distance-geometry parameters with basic chemical knowledge constraints.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

static new() → EmbedParams¶: Configure distance-geometry 3D conformer embedding; omitted fields use the defaults shown in the signature.

property num_threads: int¶: Requested worker count; interpretation of zero follows the corresponding operation.

property num_zero_fail: int¶: Number of zero eigenvalues that causes embedding to fail.

property only_heavy_atoms_for_rms: bool¶: Whether conformer RMSD pruning excludes hydrogen atoms.

property optimizer_force_tol: float¶: Force tolerance for the distance-geometry optimizer.

property prune_rms_thresh: float¶: RMSD threshold in angstroms for pruning similar conformers; a negative value disables pruning.

property rand_neg_eig: bool¶: Whether negative eigenvalues are handled by randomizing the corresponding coordinates.

property random_seed: int¶: Embedding random seed; a negative value requests nondeterministic seeding.

static sr_etkdg_v3() → EmbedParams¶: Return ETKDGv3 parameters with additional small-ring torsion preferences.

property symmetrize_conjugated_terminal_groups_for_pruning: bool¶: Whether conjugated terminal groups are treated as symmetry-equivalent when pruning conformers.

property timeout: int¶: Time limit in seconds for the corresponding search or embedding operation.

to_json() → str¶: Return a JSON string containing this configuration.

property track_failures: bool¶: Whether counts of embedding failure causes are recorded.

property use_basic_knowledge: bool¶: Whether basic chemical geometry constraints are used during embedding.

property use_exp_torsion_angle_prefs: bool¶: Whether experimental torsion-angle preferences are used.

property use_macrocycle14config: bool¶: Whether macrocycle-specific 1-4 distance bounds are used.

property use_macrocycle_torsions: bool¶: Whether macrocycle torsion preferences are included.

property use_random_coords: bool¶: Whether embedding starts from random Cartesian coordinates instead of distance-matrix eigenvectors.

property use_small_ring_torsions: bool¶: Whether small-ring torsion preferences are included.

property use_symmetry_for_pruning: bool¶: Whether symmetry-equivalent atom mappings are considered during RMSD pruning.

property verbose: bool¶: Whether diagnostic output is enabled.

with_json(json) → EmbedParams¶: Return an independent configuration updated from the supplied JSON text; invalid JSON/options raise an error.

class cosmolkit.EntityKind(value)¶

Biological entity classification: polymer, non-polymer, branched, water or unknown.

Members (5)

Branched = 'Branched'¶

NonPolymer = 'NonPolymer'¶

Polymer = 'Polymer'¶

Unknown = 'Unknown'¶

Water = 'Water'¶

class cosmolkit.EntitySourceIds¶

Source entity identifier retained separately from local entity IDs.

Members (1)

source_entity_id() → str¶: Entity identifier used in the source structure.

exception cosmolkit.EnumerationError¶: Stereoisomer enumeration failed for the graph or enumeration options.

exception cosmolkit.EnumerationRunError¶: Stereoisomer enumeration could not prepare or process the supplied molecule.

class cosmolkit.FeatureSpec¶

Read-only description of a compiled public feature selection.

Members (3)

category: str¶: Category of this compiled public feature.

docs: str¶: Description of the feature from its canonical declaration.

name: str¶: Stored name of this value.

class cosmolkit.FeatureSpecIter¶: Allocation-free, declaration-ordered projection of unique feature specs.

class cosmolkit.Fingerprint¶

Fixed-width binary fingerprint backed by Rust.

Use on_bits() for set-bit indices and to_numpy() for a uint8 vector of shape (n_bits,). Logical bit width is distinct from population count.

Members (5)

static from_on_bits(n_bits, on_bits) → Fingerprint¶: Construct a bit fingerprint of the given width from zero-based set-bit indices; out-of-range indices raise FingerprintError.

n_bits() → int¶: Return the logical fingerprint width in bits, not the number of set bits.

on_bits() → list[int]¶: Return set-bit indices in increasing logical bit order.

tanimoto(other) → float¶: Return intersection/union Tanimoto similarity with an equal-width bit fingerprint; unequal widths raise FingerprintError.

to_numpy() → numpy.typing.NDArray[numpy.uint8]¶: Return an independent C-contiguous uint8 NumPy array of shape (n_bits,), containing 0 or 1 in logical bit-index order.

class cosmolkit.FingerprintAdditionalOutput¶

Optional fingerprint metadata collector.

Allocate the desired atom-count, atom-to-bit or bit-environment sinks before a fingerprint call. Unallocated sinks return None. The collector does not own the returned fingerprint.

Members (12)

allocate_atom_counts() → None¶: Enable collection of atom counts for subsequent fingerprint calls using this collector.

allocate_atom_to_bits() → None¶: Enable collection of atom to bits for subsequent fingerprint calls using this collector.

allocate_atoms_per_bit() → None¶: Enable collection of atoms per bit for subsequent fingerprint calls using this collector.

allocate_bit_info_map() → None¶: Enable collection of bit info map for subsequent fingerprint calls using this collector.

allocate_bit_paths() → None¶: Enable collection of bit paths for subsequent fingerprint calls using this collector.

atom_counts() → Optional[list[int]]¶: Return atom-indexed feature participation counts, or None if this sink was not allocated.

atom_to_bits() → Optional[list[list[int]]]¶: Return atom-indexed lists of contributed fingerprint bits, or None if this sink was not allocated.

atoms_per_bit() → Optional[dict[int, list[list[int]]]]¶: Return bit-to-environment mapping of contributing atom-index sequences, or None if this sink was not allocated.

bit_info_map() → Optional[dict[int, list[tuple[int, int]]]]¶: Return bit-to-environment mapping with atom/radius pairs, or None if this sink was not allocated.

bit_paths() → Optional[dict[int, list[list[int]]]]¶: Return bit-to-path mapping of contributing bond-index sequences, or None if this sink was not allocated.

static default() → FingerprintAdditionalOutput¶: Construct a FingerprintAdditionalOutput value from the supplied inputs.

static new() → FingerprintAdditionalOutput¶: Construct a FingerprintAdditionalOutput value from the supplied inputs.

class cosmolkit.FingerprintBatch(fingerprints)¶

Ordered Rust-backed bit fingerprints, including failed input slots.

Indexing returns Fingerprint or None; slicing returns a FingerprintBatch. to_numpy() returns a uint8 matrix of shape (rows, bits), rejecting failed slots and unequal widths rather than silently dropping or padding rows.

Members (1)

to_numpy() → numpy.typing.NDArray[numpy.uint8]¶: Return an independent, C-contiguous uint8 matrix (rows, bits). None rows and unequal widths raise ValueError; rows are never discarded or silently replaced with zero fingerprints. An empty batch is (0, 0); empty slices retain the original batch’s width.

exception cosmolkit.FingerprintError¶: Fingerprint construction, indexing or conversion failed.

exception cosmolkit.FingerprintJsonError¶: A fingerprint JSON representation could not be parsed or serialized.

exception cosmolkit.FingerprintPreparationError¶: The molecular state required by fingerprint generation could not be prepared.

class cosmolkit.ForceFieldEnergyGradient¶

Energy in kcal/mol and an independent atom-ordered float64 gradient array of shape (N, 3).

Members (2)

energy: float¶: Force-field potential energy in kcal/mol.

gradient: numpy.typing.NDArray[numpy.float64]¶: Independent float64 NumPy array of shape (num_atoms, 3) containing Cartesian energy derivatives.

exception cosmolkit.ForceFieldError¶

Persistent force-field evaluation or minimization failed; inspect the typed kind property and the available context properties.

Members (6)

property actual: Optional[int]¶: The actual context recorded by this force-field error, or None when not applicable.

property atom_index: Optional[int]¶: The atom index context recorded by this force-field error, or None when not applicable.

property component: Optional[int]¶: The component context recorded by this force-field error, or None when not applicable.

property expected: Optional[int]¶: The expected context recorded by this force-field error, or None when not applicable.

property kind: MolecularForceFieldErrorKind¶: The kind context recorded by this force-field error, or None when not applicable.

property requested: Optional[int]¶: The requested context recorded by this force-field error, or None when not applicable.

class cosmolkit.ForceFieldMinimizeOutcome¶

Persistent force-field minimization result containing final energy and convergence status.

Members (3)

converged: bool¶: Whether minimization met its convergence criteria.

energy: float¶: Force-field potential energy in kcal/mol.

iterations: int¶: Number of minimization iterations performed.

class cosmolkit.ForceFieldMinimizeParams(*, max_iterations=Ellipsis, force_tolerance=Ellipsis, energy_tolerance=Ellipsis)¶

Writable configuration for persistent force-field minimization with iteration, force and energy convergence limits.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property energy_tolerance: float¶: Energy-change convergence tolerance for minimization.

property force_tolerance: float¶: Force/gradient convergence tolerance for minimization.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

class cosmolkit.FragmentCxSmilesWriteParams(atoms, *, cx=None, bonds=None, atom_symbols=None, bond_symbols=None)¶

Fragment selection with explicit CX fields and dimension-scoped coordinates.

Members (5)

property atom_symbols: Optional[list[str]]¶: Optional atom-indexed output symbol overrides for fragment serialization.

property atoms: list[int]¶: Zero-based atom indices to include in fragment CXSMILES output.

property bond_symbols: Optional[list[str]]¶: Optional bond-indexed output symbol overrides for fragment serialization.

property bonds: Optional[list[int]]¶: Zero-based bond indices to include, or None to include the bonds between selected atoms.

property cx: CxSmilesWriteParams¶: Nested CXSMILES writer configuration.

class cosmolkit.FragmentSmilesWriteParams(atoms, *, smiles=None, bonds=None, atom_symbols=None, bond_symbols=None)¶

Original-index fragment selection; symbol arrays are indexed by the full molecule.

Members (5)

property atom_symbols: Optional[list[str]]¶: Optional atom-indexed output symbol overrides for fragment serialization.

property atoms: list[int]¶: Zero-based atom indices to include in fragment SMILES output.

property bond_symbols: Optional[list[str]]¶: Optional bond-indexed output symbol overrides for fragment serialization.

property bonds: Optional[list[int]]¶: Zero-based bond indices to include, or None to include the bonds between selected atoms.

property smiles: SmilesWriteParams¶: Nested SMILES writer configuration.

class cosmolkit.FunctionStatus¶

Declared behavior commitment and reference library, not a test-pass result.

Members (3)

explanation: Optional[str]¶: Approved behavior difference explanation, or None when no difference is declared.

kind: str¶

Parity, ParityWithDifferences, Native or Experimental; this is not a test-pass claim.

Type:: Return the declared status

reference: Optional[str]¶: Reference library named by the function behavior commitment, or None for native/experimental behavior.

class cosmolkit.Hybridization(value)¶

Assigned atomic orbital hybridization, including unspecified and other states.

Members (9)

OTHER = 8¶

S = 1¶

SP = 2¶

SP2 = 3¶

SP2D = 5¶

SP3 = 4¶

SP3D = 6¶

SP3D2 = 7¶

UNSPECIFIED = 0¶

exception cosmolkit.HydrogenError¶: Explicit hydrogen addition or removal failed for the supplied graph and options.

exception cosmolkit.InchiError¶: InChI conversion or key generation failed; diagnostic results expose engine messages and status.

class cosmolkit.InchiErrorKind¶

Stable category for failures at the toolkit-neutral InChI boundary.

Declared values: AllocationFailed, UnsupportedState, InvalidInput, InvalidSourceOutput, SanitizeFailed, Toolkit, SourcePort.

Members (7)

AllocationFailed = InchiErrorKind.AllocationFailed¶

InvalidInput = InchiErrorKind.InvalidInput¶

InvalidSourceOutput = InchiErrorKind.InvalidSourceOutput¶

SanitizeFailed = InchiErrorKind.SanitizeFailed¶

SourcePort = InchiErrorKind.SourcePort¶

Toolkit = InchiErrorKind.Toolkit¶

UnsupportedState = InchiErrorKind.UnsupportedState¶

class cosmolkit.InchiReadParams(sanitize=True, remove_hs=True)¶

Writable configuration for InChI parsing and chemical preprocessing.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property remove_hs: bool¶: Whether removable explicit hydrogens are removed during input conversion.

property sanitize: bool¶: Return a new result that will perform the selected chemical sanitization stages. The source molecule is unchanged.

class cosmolkit.InchiWriteParams(options=Ellipsis)¶

Writable configuration for InChI/InChIKey generation options.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property options: str¶: InChI option string passed to the InChI engine; an empty string selects its default options.

exception cosmolkit.KekulizeError¶: A valid Kekule bond assignment could not be found for the requested aromatic graph.

class cosmolkit.KekulizeParams(*, mark_atoms_bonds=True, canonical=True, max_backtracks=100)¶

Writable configuration for aromatic-system kekulization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property canonical: bool¶: Whether canonical atom traversal is used for output.

property mark_atoms_bonds: bool¶: Whether aromatic atom/bond flags are cleared during kekulization.

property max_backtracks: int¶: Maximum backtracking attempts during kekulization.

class cosmolkit.LabuteAsaContributions¶

Total Labute accessible surface area plus atom-indexed and hydrogen contributions.

Members (3)

asa: float¶: Total Labute approximate accessible surface area.

atom_contributions: list[float]¶: Per-atom contributions in atom-index order.

hydrogen_contribution: float¶: Hydrogen contribution to the total Labute accessible surface area.

exception cosmolkit.LayeredFingerprintError¶: Layered fingerprint generation failed for the molecule or query.

class cosmolkit.LayeredFingerprintLayers¶

Bit mask selecting topology, bond order, atom type, ring size and aromaticity layers for layered fingerprints.

Members (2)

bits() → int¶: Return the underlying unsigned integer bit mask.

static from_bits_retain(bits) → LayeredFingerprintLayers¶: Construct a flag value preserving all supplied integer bits.

class cosmolkit.LayeredFingerprintParams(*, layers=4294967295, min_path=1, max_path=7, fp_size=2048, atom_counts=None, set_only_bits=None, branched_paths=True, from_atoms=None)¶

Writable configuration for layered fingerprint generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (8)

property atom_counts: Optional[list[int]]¶: Return atom-indexed feature participation counts, or None if this sink was not allocated.

property branched_paths: bool¶: Whether branched subgraphs, not just linear paths, are included.

property fp_size: int¶: Number of bins/bits in the folded fingerprint.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property layers: int¶: Layer flags. Unknown high bits are retained and emit no components.

property max_path: int¶: Maximum number of bonds in an enumerated fingerprint path.

property min_path: int¶: Minimum number of bonds in an enumerated fingerprint path.

property set_only_bits: Optional[Fingerprint]¶: Optional projection mask, which must have exactly fp_size bits.

class cosmolkit.LayeredFingerprintResult¶

Layered bit fingerprint plus optional atom-count metadata requested by the call.

Members (2)

atom_counts() → Optional[list[int]]¶: Return atom-indexed feature participation counts, or None if this sink was not allocated.

fingerprint() → Fingerprint¶: Return the bit fingerprint stored in this result.

class cosmolkit.LegacyTopologicalTorsionParams(*, torsion_atom_count=4, include_chirality=False, fp_size=2048, bits_per_entry=4, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None)¶

Owned, immutable legacy torsion settings and call selections.

Members (8)

property bits_per_entry: int¶: Number of hashed bits generated per torsion entry.

property custom_atom_invariants: Optional[list[int]]¶: Caller-supplied atom invariants in atom-index order.

property fp_size: int¶: Number of bins/bits in the folded fingerprint.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property ignore_atoms: Optional[list[int]]¶: Atom indices excluded from fingerprint feature enumeration.

property include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

static new(*, torsion_atom_count=4, include_chirality=False, fp_size=2048, bits_per_entry=4, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None) → LegacyTopologicalTorsionParams¶: Configure topological-torsion vector entry points; omitted fields use the defaults shown in the signature.

property torsion_atom_count: int¶: Number of atoms in each topological torsion path.

class cosmolkit.LigandRef(atom=None)¶

Stereochemical ligand reference identifying a graph atom or an implicit hydrogen.

Members (2)

atom: Optional[int]¶: Return the ligand atom index, or None when this reference denotes an implicit hydrogen.

is_implicit_hydrogen: bool¶: Whether this stereo ligand reference denotes an implicit hydrogen.

exception cosmolkit.MaccsFingerprintError¶: MACCS key generation failed for the supplied molecule.

class cosmolkit.MaccsFingerprintParams(*, n_bits=166)¶

Writable configuration for MACCS key generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property n_bits: int¶: Logical width of the fingerprint in bits.

exception cosmolkit.MatchError¶: The substructure matcher could not evaluate the supplied query and target.

class cosmolkit.MatchResult¶

Substructure match mapping query atoms and bonds to target graph indices. Atom order is query order, not target traversal order.

Members (3)

atom_mapping() → list[int]¶: Return target atom indices in query-atom order.

atom_pairs() → list[tuple[int, int]]¶: Return (query atom index, target atom index) pairs for this match.

bond_mapping() → list[int]¶: Return target bond indices in query-bond order.

exception cosmolkit.MatrixError¶: A molecular distance or adjacency matrix could not be constructed.

class cosmolkit.McsAtomComparator¶

MCS atom comparison rule: Any, element identity, isotope identity, or any non-hydrogen atom.

Declared values: Any, Elements, Isotopes, AnyHeavyAtom.

Members (4)

Any = McsAtomComparator.Any¶

AnyHeavyAtom = McsAtomComparator.AnyHeavyAtom¶

Elements = McsAtomComparator.Elements¶

Isotopes = McsAtomComparator.Isotopes¶

class cosmolkit.McsAtomCompareParameters(*, match_valences=False, match_chiral_tag=False, match_formal_charge=False, ring_matches_ring_only=False, complete_rings_only=False, match_isotope=False, max_distance=Ellipsis)¶

Writable configuration for MCS atom comparison.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

property complete_rings_only: bool¶: Whether incomplete ring fragments are excluded from the MCS.

property match_chiral_tag: bool¶: Whether MCS atom matching considers chiral tags.

property match_formal_charge: bool¶: Whether MCS atom matching requires equal formal charge.

property match_isotope: bool¶: Whether MCS atom matching requires equal isotope labels.

property match_valences: bool¶: Whether MCS atom matching requires equal valence.

property max_distance: float¶: Maximum permitted distance between matched atoms in angstroms; a negative value disables coordinate-distance matching.

property ring_matches_ring_only: bool¶: Whether ring atoms/bonds may match only other ring atoms/bonds.

class cosmolkit.McsBondComparator¶

MCS bond comparison rule: Any, bond order, or exact bond-order matching.

Declared values: Any, Order, OrderExact.

Members (3)

Any = McsBondComparator.Any¶

Order = McsBondComparator.Order¶

OrderExact = McsBondComparator.OrderExact¶

class cosmolkit.McsBondCompareParameters(*, ring_matches_ring_only=False, complete_rings_only=False, match_fused_rings=False, match_fused_rings_strict=False, match_stereo=False)¶

Writable configuration for MCS bond comparison.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (5)

property complete_rings_only: bool¶: Whether incomplete ring fragments are excluded from the MCS.

property match_fused_rings: bool¶: Whether MCS matching considers ring-fusion relationships.

property match_fused_rings_strict: bool¶: Whether MCS matching requires identical ring-fusion relationships.

property match_stereo: bool¶: Whether MCS bond matching considers bond stereochemistry.

property ring_matches_ring_only: bool¶: Whether ring atoms/bonds may match only other ring atoms/bonds.

exception cosmolkit.McsError¶: Maximum-common-substructure search failed for the supplied molecules or parameters.

class cosmolkit.McsParameters(*, store_all=False, maximize_bonds=True, threshold=1.0, timeout=0, verbose=False, atom_compare_parameters=None, bond_compare_parameters=None, atom_comparator=Ellipsis, bond_comparator=Ellipsis, initial_seed=Ellipsis)¶

Writable configuration for maximum-common-substructure search.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (10)

property atom_comparator: McsAtomComparator¶: Atom comparison rule used by maximum-common-substructure search.

property atom_compare_parameters: McsAtomCompareParameters¶: Nested MCS atom-comparison configuration; edits update this parameter object.

property bond_comparator: McsBondComparator¶: Bond comparison rule used by maximum-common-substructure search.

property bond_compare_parameters: McsBondCompareParameters¶: Nested MCS bond-comparison configuration; edits update this parameter object.

property initial_seed: str¶: Optional SMARTS pattern used to seed MCS search.

property maximize_bonds: bool¶: Whether MCS search maximizes bond count rather than atom count.

property store_all: bool¶: Whether all degenerate maximum common substructures are retained.

property threshold: float¶: Minimum fraction of input molecules that must contain the common substructure.

property timeout: int¶: Time limit in seconds for the corresponding search or embedding operation.

property verbose: bool¶: Whether diagnostic output is enabled.

class cosmolkit.McsResult¶

Maximum-common-substructure result with its query and retained alternative queries as independent snapshots.

Members (6)

atom_count: int¶: Number of atoms in the maximum common substructure.

bond_count: int¶: Number of bonds in the maximum common substructure.

completed: bool¶: Whether MCS search finished without reaching its timeout.

degenerate: dict[str, QueryGraph]¶: All retained degenerate MCS queries when store_all is enabled.

query: Optional[QueryGraph]¶: Return the QueryGraph represented by this compiled query.

smarts: str¶: SMARTS text defining the query or scoring pattern.

class cosmolkit.MmffAtomProperties¶

MMFF type and formal/partial charge for one atom.

Members (3)

atom_type() → int¶: MMFF atom type identifier.

formal_charge() → float¶: Formal charge in units of the elementary charge.

partial_charge() → float¶: MMFF partial charge in units of the elementary charge.

class cosmolkit.MmffConformerOptimizationParams(num_threads=1, max_iterations=1000, mmff_variant='MMFF94', non_bonded_threshold=10.0, ignore_interfragment_interactions=True)¶

Writable configuration for multi-conformer MMFF minimization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (5)

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

property mmff_variant: str¶: MMFF parameterization variant, normally “MMFF94” or “MMFF94s”.

property non_bonded_threshold: float¶: MMFF nonbonded interaction distance threshold in angstroms.

property num_threads: int¶: Requested worker count; interpretation of zero follows the corresponding operation.

class cosmolkit.MmffEnergyGradient¶

MMFF energy in kcal/mol and atom-ordered Cartesian energy derivatives.

Members (2)

energy() → float¶: Force-field potential energy in kcal/mol.

gradient() → list[float]¶: Return atom-ordered Cartesian energy derivatives in kcal/(mol angstrom); physical force is the negative gradient.

class cosmolkit.MmffEvaluationParams(mmff_variant='MMFF94', non_bonded_threshold=100.0, conformer_id=None, ignore_interfragment_interactions=True)¶

Writable configuration for MMFF energy and gradient evaluation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property mmff_variant: str¶: MMFF parameterization variant, normally “MMFF94” or “MMFF94s”.

property non_bonded_threshold: float¶: MMFF nonbonded interaction distance threshold in angstroms.

exception cosmolkit.MmffForceFieldError¶

An MMFF force-field evaluator could not be prepared from the molecule and parameters.

Members (6)

property actual: Optional[int]¶: The actual context recorded by this force-field error, or None when not applicable.

property atom_index: Optional[int]¶: The atom index context recorded by this force-field error, or None when not applicable.

property component: Optional[int]¶: The component context recorded by this force-field error, or None when not applicable.

property expected: Optional[int]¶: The expected context recorded by this force-field error, or None when not applicable.

property kind: MolecularForceFieldErrorKind¶: The kind context recorded by this force-field error, or None when not applicable.

property requested: Optional[int]¶: The requested context recorded by this force-field error, or None when not applicable.

class cosmolkit.MmffForceFieldParams(*, conformer_id=Ellipsis, mmff_variant=Ellipsis, non_bonded_threshold=Ellipsis, ignore_interfragment_interactions=Ellipsis)¶

Writable configuration for persistent MMFF evaluator construction.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property mmff_variant: str¶: MMFF parameterization variant, normally “MMFF94” or “MMFF94s”.

property non_bonded_threshold: float¶: MMFF nonbonded interaction distance threshold in angstroms.

exception cosmolkit.MmffMolPropertiesError¶: MMFF atom typing, charges or molecular parameter availability could not be determined.

exception cosmolkit.MmffOptimizationError¶: MMFF optimization could not prepare or minimize the selected conformer.

class cosmolkit.MmffOptimizationParams(mmff_variant='MMFF94', max_iterations=200, non_bonded_threshold=100.0, conformer_id=None, ignore_interfragment_interactions=True)¶

Writable configuration for single-conformer MMFF minimization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (5)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

property mmff_variant: str¶: MMFF parameterization variant, normally “MMFF94” or “MMFF94s”.

property non_bonded_threshold: float¶: MMFF nonbonded interaction distance threshold in angstroms.

class cosmolkit.MmffOptimizeMoleculeConfResult¶

MMFF result for one conformer: convergence/status and final energy in kcal/mol.

Members (3)

energy() → float¶: Force-field potential energy in kcal/mol.

needs_more() → bool¶: Whether optimization stopped before convergence and may need additional iterations.

status_code() → int¶: Optimizer status code; zero indicates convergence.

class cosmolkit.MmffOptimizeMoleculeConfsResult¶

Molecule with optimized MMFF conformers plus their ordered optimization reports.

Members (2)

conformer_results() → list[MmffOptimizeMoleculeConfResult]¶: Per-conformer optimization reports in input conformer order.

molecule() → Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

class cosmolkit.MmffOptimizeMoleculeResult¶

Molecule produced by single-conformer MMFF optimization with convergence/status information.

Members (3)

molecule() → Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

needs_more() → bool¶: Whether optimization stopped before convergence and may need additional iterations.

status_code() → int¶: Optimizer status code; zero indicates convergence.

class cosmolkit.MmffProperties¶

MMFF parameterization result containing atom types, formal charges and partial charges in atom order.

Members (6)

atom_type(atom_index) → int¶: MMFF atom type identifier.

atoms() → list[MmffAtomProperties]¶: Return atom-indexed MMFF types and charge properties as MmffAtomProperties values.

formal_charge(atom_index) → float¶: Formal charge in units of the elementary charge.

is_valid() → bool¶: Whether this result satisfies its domain validity conditions.

partial_charge(atom_index) → float¶: MMFF partial charge in units of the elementary charge.

variant() → MmffVariant¶: Named variant/category of the result.

class cosmolkit.MmffPropertiesParams(mmff_variant='MMFF94')¶

Writable configuration for MMFF atom typing and charge assignment.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property mmff_variant: str¶: MMFF parameterization variant, normally “MMFF94” or “MMFF94s”.

class cosmolkit.MmffVariant¶

MMFF force-field parameterization variant: MMFF94 or MMFF94s.

Declared values: Mmff94, Mmff94s.

Members (2)

Mmff94 = MmffVariant.Mmff94¶

Mmff94s = MmffVariant.Mmff94s¶

exception cosmolkit.Mol2PostError¶: A parsed MOL2 graph could not be chemically prepared as requested.

exception cosmolkit.Mol2ReadError¶: MOL2 molecular text could not be parsed.

class cosmolkit.Mol2ReadParams(*, sanitize=True, remove_hs=True, variant=Ellipsis, cleanup_substructures=True)¶

Writable configuration for Tripos MOL2 parsing.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property cleanup_substructures: bool¶: Whether MOL2-specific substructure cleanup is performed after parsing.

property remove_hs: bool¶: Whether removable explicit hydrogens are removed during input conversion.

property sanitize: bool¶: Return a new result that will perform the selected chemical sanitization stages. The source molecule is unchanged.

property variant: Mol2Type¶: Named variant/category of the result.

class cosmolkit.Mol2Type¶

Tripos MOL2 atom-typing convention selected by the reader.

Declared values: Corina.

Members (1)

Corina = Mol2Type.Corina¶

class cosmolkit.MolBlockWriteParams(*, format=Ellipsis, force_2d=False, include_stereo=True, kekulize=True, precision=6, coordinate_selection=None, include_coordinates=True)¶

Writable configuration for MOL/SDF text output and coordinate selection.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

property coordinate_selection: MolCoordinateSelection¶: Explicit selection of stored 2D coordinates, a 3D conformer, or automatic resolution.

property force_2d: bool¶: Whether molecular output requests a 2D representation.

property format: SdfFormat¶: Input/output format selector accepted by the corresponding operation.

property include_coordinates: bool¶: Whether coordinate data is included in the output.

property include_stereo: bool¶: Whether supported stereochemical annotations are emitted.

property kekulize: bool¶: Whether aromatic systems are kekulized as part of output preprocessing.

property precision: int¶: Number of decimal places used for coordinate output.

class cosmolkit.MolCoordinateSelection¶

Canonical unique-or-explicit geometry selection for MOL and SDF export.

Members (5)

static auto() → MolCoordinateSelection¶: Construct a coordinate selection for automatic coordinate resolution, rejecting an ambiguous selection.

conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

dimension: Optional[CoordinateDimension]¶: Return the selected coordinate dimension, or None for automatic resolution.

static three_d(id) → MolCoordinateSelection¶: Construct a coordinate selection for the stored 3D conformer with the supplied ID.

static two_d(id) → MolCoordinateSelection¶: Construct a coordinate selection for the separate stored 2D conformer.

class cosmolkit.MolecularForceField¶

Owned persistent MMFF/UFF evaluator for interactive coordinate editing.

Build through mol.mmff_force_field() or mol.uff_force_field(). Position updates and minimize_() change only evaluator state, not the source molecule. Gradients are energy derivatives; physical force is their negative.

Members (12)

energy() → float¶: Evaluate potential energy in kcal/mol at the current evaluator positions; does not minimize or modify coordinates.

energy_gradient() → ForceFieldEnergyGradient¶: Return energy and the constrained atom-ordered gradient evaluated at the current positions.

fixed_atoms() → tuple[int, ...]¶: Return the tuple of fixed atom indices. Fixed atoms remain in their current positions during minimization.

gradient() → numpy.typing.NDArray[numpy.float64]¶: Return an independent float64 (num_atoms, 3) array of energy derivatives in kcal/(mol angstrom). Fixed-atom rows are zero; physical force is the negative gradient.

gradient_unconstrained() → numpy.typing.NDArray[numpy.float64]¶: Full energy derivative as an independent float64 (N, 3) array. Fixed-atom rows are not zeroed; the fixed set and positions are unchanged. Physical force is the negative of this gradient.

minimize_(*, max_iterations=Ellipsis, force_tolerance=Ellipsis, energy_tolerance=Ellipsis) → ForceFieldMinimizeOutcome¶: Minimize evaluator positions in place while holding fixed atoms still. Return ForceFieldMinimizeOutcome with energy and convergence status; the source Molecule is unchanged. Uses max_iterations, force_tolerance and energy_tolerance.

minimize_with_params_(params) → ForceFieldMinimizeOutcome¶: Minimize evaluator positions in place using ForceFieldMinimizeParams and the current fixed atom set; return energy and convergence status without changing the source Molecule. Uses the supplied configuration object.

position(atom_id) → tuple[float, float, float]¶: Return one atom position as an (x, y, z) tuple in angstroms; invalid indices raise ForceFieldError.

positions() → numpy.typing.NDArray[numpy.float64]¶: Return an independent float64 NumPy array of shape (num_atoms, 3), in angstroms and atom-index order. Editing the array does not change the evaluator.

set_fixed_atoms_(atom_ids) → None¶: Replace the set of fixed atom indices used by subsequent minimization. Invalid indices raise ForceFieldError without changing the fixed set.

set_position_(atom_id, position) → None¶: Replace one evaluator atom position with three finite coordinates in angstroms; invalid input leaves evaluator positions unchanged.

set_positions_(positions) → None¶: Replace evaluator coordinates from an array-like of shape (num_atoms, 3). Validate shape, count and finite values before changing state; the source Molecule is unaffected.

class cosmolkit.MolecularForceFieldErrorKind¶

Stable categories shared by persistent evaluators and their factories.

Declared values: MissingConformer, Parameterization, InvalidParameterization, InvalidAtomIndex, InvalidFixedAtom, CoordinateCount, CoordinateShape, NonFiniteCoordinate, InvalidTolerance, Preparation, Construction, Initialization, Rings, Kernel.

Members (14)

Construction = MolecularForceFieldErrorKind.Construction¶

CoordinateCount = MolecularForceFieldErrorKind.CoordinateCount¶

CoordinateShape = MolecularForceFieldErrorKind.CoordinateShape¶

Initialization = MolecularForceFieldErrorKind.Initialization¶

InvalidAtomIndex = MolecularForceFieldErrorKind.InvalidAtomIndex¶

InvalidFixedAtom = MolecularForceFieldErrorKind.InvalidFixedAtom¶

InvalidParameterization = MolecularForceFieldErrorKind.InvalidParameterization¶

InvalidTolerance = MolecularForceFieldErrorKind.InvalidTolerance¶

Kernel = MolecularForceFieldErrorKind.Kernel¶

MissingConformer = MolecularForceFieldErrorKind.MissingConformer¶

NonFiniteCoordinate = MolecularForceFieldErrorKind.NonFiniteCoordinate¶

Parameterization = MolecularForceFieldErrorKind.Parameterization¶

Preparation = MolecularForceFieldErrorKind.Preparation¶

Rings = MolecularForceFieldErrorKind.Rings¶

exception cosmolkit.MolecularIoError¶: A molecular text format could not be parsed, serialized or read/written as a file.

class cosmolkit.MoleculeBatch¶

Ordered collection of molecule records and per-input errors.

Failed input slots retain their indices. Chemical operations preserve input order; with_valid_records() explicitly compacts valid entries. Execution defaults to one worker, and can be configured independently of chemical parameters.

Members (70)

dg_bounds_matrix_list() → list[numpy.ndarray | None]¶: Return per-record distance-geometry bounds matrices in input order, preserving None slots for failed records.

dg_bounds_matrix_list_with_params(params) → list[numpy.ndarray | None]¶: Return per-record distance-geometry bounds matrices in input order, preserving None slots for failed records. Uses the supplied configuration object.

error_mode() → BatchErrorMode¶: Return the error policy inherited by transforms and exports.

errors() → list[BatchError]¶: Errors retained by this result, including original input positions when applicable.

fingerprint_atom_pair_count_list() → list[Optional[SparseCountFingerprint32]]¶: Compute atom pair folded feature counts in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_count_list_with_params(options, params) → list[Optional[SparseCountFingerprint32]]¶: Compute atom pair folded feature counts in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_list() → FingerprintBatch¶: Compute atom pair fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_list_with_params(options, params) → FingerprintBatch¶: Compute atom pair fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_sparse_bits_list() → list[Optional[SparseBitFingerprint]]¶: Compute atom pair sparse feature bits in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_sparse_bits_list_with_params(options, params) → list[Optional[SparseBitFingerprint]]¶: Compute atom pair sparse feature bits in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_sparse_count_list() → list[Optional[SparseCountFingerprint]]¶: Compute atom pair sparse feature counts in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_sparse_count_list_with_params(options, params) → list[Optional[SparseCountFingerprint]]¶: Compute atom pair sparse feature counts in original batch order, retaining None slots for failed records.

fingerprint_atom_pair_with_output_list() → list[Optional[BatchFingerprintOutput]]¶: Compute atom pair fixed-width bit fingerprints in original batch order, retaining None slots for failed records; include the requested atom/bit environment metadata.

fingerprint_atom_pair_with_output_list_with_params(options, collect_additional_output=True, params=None) → list[Optional[BatchFingerprintOutput]]¶: Compute atom pair fixed-width bit fingerprints in original batch order, retaining None slots for failed records; include the requested atom/bit environment metadata.

fingerprint_layered_list() → FingerprintBatch¶: Compute layered fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

fingerprint_layered_list_with_params(options, params) → FingerprintBatch¶: Compute layered fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

fingerprint_layered_with_output_list() → list[Optional[LayeredFingerprintResult]]¶: Compute layered fixed-width bit fingerprints in original batch order, retaining None slots for failed records; include the requested atom/bit environment metadata.

fingerprint_layered_with_output_list_with_params(options, params) → list[Optional[LayeredFingerprintResult]]¶: Compute layered fixed-width bit fingerprints in original batch order, retaining None slots for failed records; include the requested atom/bit environment metadata.

fingerprint_morgan_list() → FingerprintBatch¶

Return Morgan fingerprints in input order (default radius 3, 2048 bits).

Existing failed records produce None; new calculation errors raise BatchValidationError. The source batch is unchanged. Accepts MorganFingerprintParams as options and BatchQueryParams as params, or their fields as keywords. For example: batch.fingerprint_morgan_list(generator=ck.MorganParams(radius=2), n_jobs=1). Omitted n_jobs uses the batch setting, or one worker if unset.

fingerprint_morgan_list_with_generator_params(options, atom_invariants, bond_invariants, call, params) → FingerprintBatch¶: Compute morgan fixed-width bit fingerprints in original batch order, retaining None slots for failed records using the supplied generator and per-call options.

fingerprint_morgan_list_with_params(options, params) → FingerprintBatch¶: Return ordered Morgan fingerprints using explicit options and execution params. Existing failed records produce None; new calculation errors raise BatchValidationError. Does not modify the source batch.

fingerprint_morgan_with_output_list() → list[Optional[BatchFingerprintOutput]]¶: Compute morgan fixed-width bit fingerprints in original batch order, retaining None slots for failed records; include the requested atom/bit environment metadata.

fingerprint_morgan_with_output_list_with_generator_params(options, atom_invariants, bond_invariants, call, collect_additional_output, params) → list[Optional[BatchFingerprintOutput]]¶: Compute morgan fixed-width bit fingerprints in original batch order, retaining None slots for failed records; include the requested atom/bit environment metadata using the supplied generator and per-call options.

fingerprint_morgan_with_output_list_with_params(options, collect_additional_output=True, params=None) → list[Optional[BatchFingerprintOutput]]¶: Compute morgan fixed-width bit fingerprints in original batch order, retaining None slots for failed records; include the requested atom/bit environment metadata.

fingerprint_pattern_list() → FingerprintBatch¶: Compute pattern fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

fingerprint_pattern_list_with_params(options, params) → FingerprintBatch¶: Compute pattern fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

fingerprint_topological_torsion_list() → FingerprintBatch¶: Compute topological torsion fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

fingerprint_topological_torsion_list_with_params(options, params) → FingerprintBatch¶: Compute topological torsion fixed-width bit fingerprints in original batch order, retaining None slots for failed records.

static from_dataset_indices(dataset, indices, mode) → MoleculeBatch¶: Read the specified indexed SDF records into a batch in the requested index order.

static from_records(records, mode) → MoleculeBatch¶: Construct a batch from explicit records, preserving their input order and failure information.

static from_sdf_records(text, errors=None, n_jobs=None) → MoleculeBatch¶: Parse SDF record texts into an ordered batch using the selected error policy; retained parse failures keep their input slots.

static from_sdf_records_with_params(text, read, errors=None, n_jobs=None) → MoleculeBatch¶: Parse SDF record texts into an ordered batch using the selected error policy; retained parse failures keep their input slots. Uses the supplied configuration object.

static from_smiles_list(smiles) → MoleculeBatch¶

Parse SMILES strings into a MoleculeBatch, preserving input order.

static from_smiles_list_with_params(smiles, parse, params) → MoleculeBatch¶: Parse SMILES using explicit parse and execution params, preserving input order. BatchParams.errors controls whether failures raise BatchValidationError or remain as failed records accessible through errors().

get(index) → Molecule | BatchError | None¶: Return the molecule at the original zero-based input index, or None for a retained failed slot.

invalid_count() → int¶: Number of failed records in the batch.

invalid_mask() → list[bool]¶: Boolean flags in original input order; True marks a failed record.

is_empty() → bool¶: Return whether there are no stored entries.

len() → int¶: Return the number of stored entries.

parallel_jobs() → Optional[int]¶: Configured batch worker count; the default is one worker.

progress_bar() → Optional[bool]¶: Whether batch execution reports progress.

static read_sdf(path, errors=None, n_jobs=None, progress_bar=False) → MoleculeBatch¶: Read a SDF file from a filesystem path and return a new Molecule; use from_* for in-memory text.

static read_sdf_with_params(path, read, errors=None, n_jobs=None, progress_bar=False) → MoleculeBatch¶: Read a SDF file from a filesystem path and return a new Molecule; use from_* for in-memory text.

records() → list[Molecule | BatchError]¶: Return batch records in original input order, preserving failed entries and their errors.

sanitize() → MoleculeBatch¶: Apply to a new batch: perform the selected chemical sanitization stages. Preserve record order and retained errors; the source batch is unchanged.

sanitize_with_params(options, params) → MoleculeBatch¶: Apply to a new batch: perform the selected chemical sanitization stages. Preserve record order and retained errors; the source batch is unchanged.

to_list() → list[Optional[Molecule]]¶: Return molecule-or-None entries in original input order; failed slots are retained.

to_smiles_list() → list[Optional[str]]¶

Return SMILES strings in input order; defaults to canonical, isomeric SMILES.

Existing failed records produce None; new writing errors raise BatchValidationError. The source batch is unchanged. Accepts SmilesWriteParams as options and BatchQueryParams as params, or their fields as keywords: batch.to_smiles_list(canonical=False, n_jobs=1). Omitted n_jobs uses the batch setting, or one worker if unset.

to_smiles_list_with_params(options, params) → list[Optional[str]]¶: Return ordered SMILES strings using explicit options and execution params. Existing failed records produce None; new writing errors raise BatchValidationError. Does not modify the source batch.

to_svg_list(width, height) → list[Optional[str]]¶: Return SVG results in original input order; retained failed records produce None rather than shifting subsequent indices.

to_svg_list_with_params(width, height, params) → list[Optional[str]]¶: Return SVG results in original input order; retained failed records produce None rather than shifting subsequent indices.

valid_count() → int¶: Number of valid records in the batch.

valid_mask() → list[bool]¶: Boolean flags in original input order; True marks a valid record.

with_2d_coordinates() → MoleculeBatch¶: Apply to a new batch: generate and store 2D drawing coordinates. Preserve record order and retained errors; the source batch is unchanged.

with_2d_coordinates_with_params(options, params) → MoleculeBatch¶: Apply to a new batch: generate and store 2D drawing coordinates. Preserve record order and retained errors; the source batch is unchanged.

with_hydrogens() → MoleculeBatch¶

Return a new batch with explicit hydrogens; leave the source batch unchanged.

Input order and the batch error policy are preserved. Override errors=”raise” to reject failures or errors=”keep” to retain existing and new failed records. Accepts AddHsParams as options and BatchParams as params, or their fields as keywords: batch.with_hydrogens(errors=”keep”, n_jobs=1). Omitted n_jobs uses the batch setting, or one worker if unset.

with_hydrogens_with_params(options, params) → MoleculeBatch¶: Return a new hydrogen-added batch using explicit options and execution params. Input order is preserved; the source batch is unchanged. BatchParams.errors controls whether existing and new failures raise or remain as failed records.

with_kekulized_bonds() → MoleculeBatch¶: Apply to a new batch: assign explicit single/double bonds to aromatic systems. Preserve record order and retained errors; the source batch is unchanged.

with_kekulized_bonds_with_params(options, params) → MoleculeBatch¶: Apply to a new batch: assign explicit single/double bonds to aromatic systems. Preserve record order and retained errors; the source batch is unchanged.

with_parallel_jobs(n_jobs) → MoleculeBatch¶: Return a batch with the requested worker count; leave the original batch unchanged.

with_progress_bar(progress_bar) → MoleculeBatch¶: Return a batch with progress reporting enabled or disabled; leave the original batch unchanged.

with_valid_records() → MoleculeBatch¶: Return a new batch containing only valid records; this is explicit compaction.

without_hydrogens() → MoleculeBatch¶: Apply to a new batch: remove eligible explicit hydrogen atoms using the selected removal policy. Preserve record order and retained errors; the source batch is unchanged.

without_hydrogens_with_params(options, params) → MoleculeBatch¶: Apply to a new batch: remove eligible explicit hydrogen atoms using the selected removal policy. Preserve record order and retained errors; the source batch is unchanged.

write_images(directory) → BatchExportReport¶: Write IMAGES output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text. Return a report with success/failure counts and original input errors.

write_images_with_params(directory, options) → BatchExportReport¶: Write IMAGES output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text. Return a report with success/failure counts and original input errors.

write_sdf(path, format=None, errors=None, n_jobs=None, report_path=None, progress_bar=None) → BatchExportReport¶: Write SDF output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text. Return a report with success/failure counts and original input errors.

write_sdf_files(out_dir, format=None, errors=None, n_jobs=None, report_path=None, filenames=None, progress_bar=None) → BatchExportReport¶: Write SDF FILES output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text. Return a report with success/failure counts and original input errors.

write_sdf_files_with_params(directory, params, filenames, report_path) → BatchExportReport¶: Write SDF FILES output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text. Return a report with success/failure counts and original input errors.

write_sdf_with_params(path, params, report_path) → BatchExportReport¶: Write SDF output to the supplied filesystem path/directory using the selected options. This writes files rather than returning serialized text. Return a report with success/failure counts and original input errors.

class cosmolkit.MoleculeBuilder¶

Editable molecular construction state.

Add atoms/bonds and set coordinates or properties, then call build() to validate and obtain a Molecule. Editing a builder created from a molecule does not change the source molecule.

Members (26)

add_2d_conformer(coordinates) → int¶: Adds one checked 2D conformer and returns its dimension-local id.

add_3d_conformer(coordinates) → int¶: Return a new result that will append a conformer using caller-supplied atom-ordered 3D coordinates. The source molecule is unchanged.

add_atom(spec) → int¶: Append an atom using AtomSpec and return its zero-based atom index.

add_bond(spec) → int¶: Append a bond using BondSpec; validate its endpoint atom indices.

add_stereo_group(group) → int¶: Append an enhanced-stereochemistry group referencing local atoms.

add_substance_group(group) → SubstanceGroupId¶: Append a substance-group annotation using local atom/bond identifiers.

atoms() → list[Atom]¶: Return atom rows in stored graph/hierarchy order.

bond_between_atoms(begin_atom, end_atom) → Optional[int]¶: Return the bond joining the two specified builder atoms, when present.

bonds() → list[Bond]¶: Return bond rows in graph order.

build() → Molecule¶: Construct and validate an owned Molecule from the builder state; invalid graph or coordinate parts raise OperationError.

coordinates() → CoordinateBlock¶: Return the builder coordinate block, keeping 2D and 3D storage separate.

degree(atom_id) → int¶: Number of graph neighbors, including explicit hydrogen vertices.

static from_parts(topology, coordinates, properties) → MoleculeBuilder¶: Construct a value from explicit detached parts; required structural consistency is checked at the public boundary.

neighbor_bonds(atom_id) → list[int]¶: Return the bond indices incident to the specified builder atom.

static new() → MoleculeBuilder¶: Construct a MoleculeBuilder value from the supplied inputs.

properties() → MoleculeProperties¶: Return a detached snapshot of the stored properties.

remove_bond_between_atoms(begin_atom, end_atom) → bool¶: Remove the bond joining the two specified atom indices, if one is present.

set_2d_coordinates(coordinates) → None¶: Set atom-ordered 2D positions on the builder; the row count must equal the atom count.

set_atom_formal_charge(atom, charge) → None¶: Update the formal charge of the specified builder atom.

set_bond_order(bond, order) → None¶: Update the bond order of the specified builder bond.

stereo_groups() → list[StereoGroup]¶: Enhanced stereochemistry groups referencing graph atoms.

substance_groups() → list[SubstanceGroup]¶: Substance-group annotations referencing graph atoms and bonds.

with_name(name) → MoleculeBuilder¶: Return a builder with the requested molecule name.

with_properties(properties) → MoleculeBuilder¶: Return a builder with the supplied detached molecule properties.

with_property(key, value) → MoleculeBuilder¶: Return a builder with the supplied molecule property key/value.

with_sdf_data_field(key, value) → MoleculeBuilder¶: Return a builder with an appended ordered SDF data field.

exception cosmolkit.MoleculeHashError¶: A molecular hash could not be computed for the requested hash function.

class cosmolkit.MoleculeOpSpec¶

Read-only operation declaration metadata; inspecting it does not grant mutation or runtime access.

Members (17)

access: dict[str, int]¶: Exact read/write block bit masks from the generated declaration.

auto_remap: int¶: Whether the runtime automatically remaps referenced data for this operation.

cip_state: str¶: Declared effect on cached CIP assignment state.

derived_effects: dict[str, int]¶: Exact derived-state masks, including operation-defined transitions.

domain: str¶: Chemical/API domain associated with the operation or error.

impl_fn: str¶: Implementation function name recorded by the operation declaration; not a callable Python entry point.

io_roundtrip: bool¶: Declared input/output preservation commitment.

kind: str¶: Classification/discriminant of this value as defined by its owning type.

may_mutate: int¶: Declared graph/coordinate/property blocks that the operation may change.

method: str¶: Experimental method, or canonical operation name in operation metadata.

output: str¶: Output multiplicity/category recorded by the operation declaration.

parity: ParityPolicy¶: Declared reference-comparison policy; not a test execution result.

requires_mapping: str¶: Whether the operation must produce an atom/bond topology mapping.

result_type: str¶: Declared operation result type name.

semantic_preconditions: int¶: Semantic preconditions declared for the operation.

status: FunctionStatus¶: Declared status of the operation/result; inspect the typed value rather than inferring success from a message.

topology_edit: str¶: Declared topology-edit category of this operation.

class cosmolkit.MoleculeProperties¶

Read-only molecule name, typed properties, computed-property markers and ordered SDF data fields.

Members (7)

computed_prop_names() → list[str]¶: Property names marked as computed.

is_prop_computed(key) → bool¶: Returns whether a property is registered as computed state.

name() → Optional[str]¶: Stored name of this value.

prop(key) → Optional[PropertyValue]¶: Return the typed property for the requested key, or None if absent.

props() → dict[str, PropertyValue]¶: Stored typed properties; returned values do not provide mutable access to the owning molecule.

sdf_data_fields() → list[tuple[str, str]]¶: Return ordered SDF (name, value) string pairs, preserving duplicate names.

sdf_property_lists() → list[SdfPropertyList]¶: Interpreted atom/bond SDF property lists in stored order.

exception cosmolkit.MolWriteError¶: The molecular graph could not be serialized as a MOL/SDF block with the requested coordinates and options.

class cosmolkit.MorganAtomInvariantsGenerator¶

Immutable, independently captured atom-invariant provider configuration.

Members (3)

static atom_pair(generator) → MorganAtomInvariantsGenerator¶: Select atom-pair atom-code invariants with the requested chirality setting.

static connectivity(include_ring_membership=True) → MorganAtomInvariantsGenerator¶: Select atom invariants based on chemical graph connectivity.

static features(patterns=None) → MorganAtomInvariantsGenerator¶: Select pharmacophore/chemical-feature atom invariants for Morgan fingerprinting.

class cosmolkit.MorganBondInvariantsGenerator(*, use_bond_types=True, include_chirality=False)¶

Immutable explicit bond-provider flags, captured independently of live settings.

Members (3)

property include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

static new(*, use_bond_types=True, include_chirality=False) → MorganBondInvariantsGenerator¶: Construct a MorganBondInvariantsGenerator value from the supplied inputs.

property use_bond_types: bool¶: Whether bond types contribute to fingerprint invariants.

class cosmolkit.MorganCallParams(*, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None, custom_bond_invariants=None, conformer_id=Ellipsis)¶

Writable configuration for per-call Morgan atom selection and invariants.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (6)

property conformer_id: int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property custom_atom_invariants: Optional[list[int]]¶: Caller-supplied atom invariants in atom-index order.

property custom_bond_invariants: Optional[list[int]]¶: Caller-supplied bond invariants in bond-index order.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property ignore_atoms: Optional[list[int]]¶: Atom indices excluded from fingerprint feature enumeration.

static new(*, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None, custom_bond_invariants=None, conformer_id=Ellipsis) → MorganCallParams¶: Configure per-call Morgan atom selection and invariants; omitted fields use the defaults shown in the signature.

class cosmolkit.MorganFingerprintGenerator(*, params=None, atom_invariants=None, bond_invariants=None)¶

Reusable Morgan fingerprint generator. settings() is a live view; later edits affect subsequent calls, not previously returned fingerprints.

Members (9)

counts(molecules, *, num_threads=1) → list[Optional[SparseCountFingerprint32]]¶: Generate folded count fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

fingerprints(molecules, *, num_threads=1) → FingerprintBatch¶: Generate fixed-width bit fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

static from_json(json) → MorganFingerprintGenerator¶: Construct a generator from serialized JSON settings; invalid JSON/options raise an error.

info_string() → str¶: Return a readable description of the generator settings.

static new(*, params=None, atom_invariants=None, bond_invariants=None) → MorganFingerprintGenerator¶: Construct a MorganFingerprintGenerator value from the supplied inputs.

settings() → MorganSettings¶: Return a live settings view; edits affect subsequent calls on this generator.

sparse_counts(molecules, *, num_threads=1) → list[Optional[SparseCountFingerprint]]¶: Generate sparse count fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

sparse_fingerprints(molecules, *, num_threads=1) → list[Optional[SparseBitFingerprint]]¶: Generate sparse bit fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

to_json() → str¶: Return a JSON string containing this configuration.

class cosmolkit.MorganFingerprintParams(*, generator=None, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None, custom_bond_invariants=None, conformer_id=Ellipsis, invariants=None)¶

Owned call options; optional empty vectors retain their source meaning.

Members (7)

property conformer_id: int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property custom_atom_invariants: Optional[list[int]]¶: Caller-supplied atom invariants in atom-index order.

property custom_bond_invariants: Optional[list[int]]¶: Caller-supplied bond invariants in bond-index order.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property generator: MorganParams¶: Fingerprint generator configuration; nested edits update the parent parameter object.

property ignore_atoms: Optional[list[int]]¶: Atom indices excluded from fingerprint feature enumeration.

property invariants: MorganInvariants¶: Morgan atom-invariant selection, such as connectivity or feature invariants.

class cosmolkit.MorganInvariants¶

Detached invariant selection, interpreted by the canonical Rust owner.

Members (2)

static connectivity() → MorganInvariants¶: Select atom invariants based on chemical graph connectivity.

static features() → MorganInvariants¶: Select pharmacophore/chemical-feature atom invariants for Morgan fingerprinting.

class cosmolkit.MorganParams(*, radius=3, include_chirality=False, use_bond_types=True, include_ring_membership=True, only_nonzero_invariants=False, include_redundant_environments=False, fp_size=2048, count_simulation=False, count_bounds=None, bits_per_feature=1)¶

Writable configuration for Morgan fingerprint generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (13)

property bits_per_feature: int¶: Number of hashed bit positions generated per feature.

property count_bounds: list[int]¶: Occurrence-count thresholds used by count simulation.

property count_simulation: bool¶: Whether occurrence counts are represented using threshold bits.

property fp_size: int¶: Number of bins/bits in the folded fingerprint.

property include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

property include_redundant_environments: bool¶: Whether redundant Morgan environments are retained.

property include_ring_membership: bool¶: Whether ring membership contributes to Morgan connectivity invariants.

info_string() → str¶: Return a readable description of the generator settings.

property only_nonzero_invariants: bool¶: Whether atoms with zero invariants are excluded as environment centers.

property radius: int¶: Morgan environment radius, measured in graph bonds.

to_json() → str¶: Return a JSON string containing this configuration.

property use_bond_types: bool¶: Whether bond types contribute to fingerprint invariants.

with_json(json) → MorganParams¶: Return an independent configuration updated from the supplied JSON text; invalid JSON/options raise an error.

exception cosmolkit.MorganReadError¶: Morgan fingerprint preparation could not read the required molecular state.

class cosmolkit.MorganSettings¶

Live Morgan generator settings. Property assignment and set_* methods update the owning generator.

Members (17)

bits_per_feature: int¶: Number of hashed bit positions generated per feature.

count_bounds: list[int]¶: Occurrence-count thresholds used by count simulation.

count_simulation: bool¶: Whether occurrence counts are represented using threshold bits.

fp_size: int¶: Number of bins/bits in the folded fingerprint.

include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

include_redundant_environments: bool¶: Whether redundant Morgan environments are retained.

only_nonzero_invariants: bool¶: Whether atoms with zero invariants are excluded as environment centers.

params() → MorganParams¶: Return the parameter values associated with this result or settings view.

radius: int¶: Morgan environment radius, measured in graph bonds.

set_bits_per_feature(value) → None¶: Update the owning generator setting. Number of hashed bit positions generated per feature.

set_count_bounds(value) → None¶: Update the owning generator setting. Occurrence-count thresholds used by count simulation.

set_count_simulation(value) → None¶: Update the owning generator setting. Whether occurrence counts are represented using threshold bits.

set_fp_size(value) → None¶: Update the owning generator setting. Number of bins/bits in the folded fingerprint.

set_include_chirality(value) → None¶: Update the owning generator setting. Whether stereochemical information contributes to fingerprint features.

set_include_redundant_environments(value) → None¶: Update the owning generator setting. Whether redundant Morgan environments are retained.

set_only_nonzero_invariants(value) → None¶: Update the owning generator setting. Whether atoms with zero invariants are excluded as environment centers.

set_radius(value) → None¶: Update the owning generator setting. Morgan environment radius, measured in graph bonds.

exception cosmolkit.OperationError¶: A molecular operation failed validation or execution without committing partial changes.

class cosmolkit.OperationInvariantEntry¶

Read-only invariant-validation profile associated with a public operation.

Members (2)

operation: MoleculeOpSpec¶: Name of the operation that produced this error.

profile: str¶: Validation/reference profile recorded by this matrix entry.

class cosmolkit.ParityMatrixEntry¶

Read-only reference-comparison declaration for a public operation; not a test result.

Members (4)

feature: FeatureSpec¶: Owning compiled capability recorded for this declaration.

operation: MoleculeOpSpec¶: Name of the operation that produced this error.

profile: str¶: Validation/reference profile recorded by this matrix entry.

rdkit_version: Optional[str]¶: Reference RDKit version recorded by this parity matrix entry.

class cosmolkit.ParityPolicy¶

Declared reference-validation policy for an operation; does not indicate that any tests have run.

Declared values: NotApplicable, RequiredWhenSupported, RequiredNow.

Members (3)

NotApplicable = ParityPolicy.NotApplicable¶

RequiredNow = ParityPolicy.RequiredNow¶

RequiredWhenSupported = ParityPolicy.RequiredWhenSupported¶

exception cosmolkit.PatternFingerprintError¶: Pattern fingerprint generation failed for the molecule or query.

class cosmolkit.PatternFingerprintParams(*, n_bits=2048, tautomeric=False)¶

Writable configuration for Pattern fingerprint generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property n_bits: int¶: Logical width of the fingerprint in bits.

property tautomeric: bool¶: Whether single, double, and aromatic bonds use tautomer-aware hashing.

class cosmolkit.PdbSeqId(seq_num, ins_code=None)¶

Source residue sequence number plus insertion code; not a local residue row ID.

Members (2)

ins_code() → Optional[str]¶: Residue insertion code retained with the sequence number.

seq_num() → int¶: Residue sequence number, when present.

exception cosmolkit.PickleError¶: Invalid, unsupported or inconsistent native molecular archive data.

class cosmolkit.PolymerKind(value)¶

Polymer chemistry classification, distinguishing peptide handedness, DNA, RNA, saccharides and other polymer types.

Members (11)

CyclicPseudoPeptide = 'CyclicPseudoPeptide'¶

Dna = 'Dna'¶

DnaRnaHybrid = 'DnaRnaHybrid'¶

Other = 'Other'¶

PeptideD = 'PeptideD'¶

PeptideL = 'PeptideL'¶

Pna = 'Pna'¶

Rna = 'Rna'¶

SaccharideD = 'SaccharideD'¶

SaccharideL = 'SaccharideL'¶

Unknown = 'Unknown'¶

class cosmolkit.PotentialStereoCenter¶

Index and category of a potential atom/bond stereo feature.

Members (2)

index: int¶: Original zero-based input record index; failed records retain their index.

kind: str¶: Classification/discriminant of this value as defined by its owning type.

class cosmolkit.PotentialStereoDescriptor(value)¶

Perceived local stereo orientation, including tetrahedral handedness, cis/trans and atropisomeric directions.

Members (7)

BOND_ATROP_CCW = 'bond_atrop_ccw'¶

BOND_ATROP_CW = 'bond_atrop_cw'¶

BOND_CIS = 'bond_cis'¶

BOND_TRANS = 'bond_trans'¶

NONE = 'none'¶

TETRAHEDRAL_CLOCKWISE = 'tetrahedral_clockwise'¶

TETRAHEDRAL_COUNTERCLOCKWISE = 'tetrahedral_counterclockwise'¶

exception cosmolkit.PotentialStereoError¶: Potential stereocenters could not be identified for the supplied graph.

class cosmolkit.PotentialStereoInfo¶

Potential stereo feature with its center, specification state, descriptor and controlling atoms.

Members (6)

centered_on: PotentialStereoCenter¶: Atom or bond index on which the stereo feature is centered.

controlling_atoms: list[Optional[int]]¶: Atom indices defining the local stereo feature.

descriptor: Any¶: Local stereo descriptor retained by the perception result.

permutation: int¶: Permutation code for non-tetrahedral stereochemistry, when applicable.

specified: Any¶: Whether the stereochemistry is specified, unspecified or unknown.

stereo_type: Any¶: Type of potential stereogenic atom or bond.

class cosmolkit.PotentialStereoParams(*, clean=False, flag_possible=True, allow_nontetrahedral=True)¶

Writable configuration for potential stereocenter perception.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property allow_nontetrahedral: bool¶: Whether non-tetrahedral stereochemistry is considered.

property clean: bool¶: Whether invalid stereo annotations are cleaned during perception.

property flag_possible: bool¶: Whether potential stereocenters are flagged even if unspecified.

class cosmolkit.PotentialStereoResult¶

Potential-stereochemistry analysis with stereocenter rows, atom ranks and ring relationships. The cleaned_molecule is present only when clean=True requested a cleaned result.

Members (4)

atom_ranks: list[int]¶: Atom-indexed ranks used by stereo perception.

cleaned_molecule: Optional[Molecule]¶: Molecule value with the requested stereo cleanup applied; source input is unchanged.

ring_relations: list[RingStereoRelation]¶: Relative stereochemical relationships between ring centers.

stereo: list[PotentialStereoInfo]¶: Return the perceived PotentialStereoInfo rows for potential atom and bond stereocenters.

class cosmolkit.PotentialStereoSpecified(value)¶

Whether potential stereochemistry is unspecified, specified or explicitly unknown.

Members (3)

SPECIFIED = 'specified'¶

UNKNOWN = 'unknown'¶

UNSPECIFIED = 'unspecified'¶

class cosmolkit.PotentialStereoType(value)¶

Type of a potential stereocenter, distinguishing atom geometries from double, cumulene and atropisomeric bonds.

Members (7)

ATOM_OCTAHEDRAL = 'atom_octahedral'¶

ATOM_SQUAREPLANAR = 'atom_squareplanar'¶

ATOM_TETRAHEDRAL = 'atom_tetrahedral'¶

ATOM_TRIGONALBIPYRAMIDAL = 'atom_trigonalbipyramidal'¶

BOND_ATROPISOMER = 'bond_atropisomer'¶

BOND_CUMULENE_EVEN = 'bond_cumulene_even'¶

BOND_DOUBLE = 'bond_double'¶

exception cosmolkit.PropertyStringError¶

A molecular property could not be converted to the requested textual representation.

Members (1)

kind() → PropertyValueKind¶: Return the kind context recorded by this error.

class cosmolkit.PropertyValue¶

Typed property value; as_* accessors require the corresponding value kind and raise PropertyValueError on a mismatch.

Members (7)

as_bool() → bool¶: Return the boolean value; a different PropertyValueKind raises PropertyValueError.

as_double() → float¶: Return the floating-point value; a different PropertyValueKind raises PropertyValueError.

as_int() → int¶: Return the signed integer value; a different PropertyValueKind raises PropertyValueError.

as_int_vector() → list[int]¶: Return a list of signed integer values; a different PropertyValueKind raises PropertyValueError.

as_string() → str¶: Return the string value; a different PropertyValueKind raises PropertyValueError.

as_uint() → int¶: Return the unsigned integer value; a different PropertyValueKind raises PropertyValueError.

kind() → PropertyValueKind¶: Return the PropertyValueKind discriminant; it determines the valid as_* accessor.

exception cosmolkit.PropertyValueError¶

A property value has the wrong type for the requested accessor.

Members (2)

actual() → PropertyValueKind¶: Return the actual context recorded by this error.

expected() → PropertyValueKind¶: Return the expected context recorded by this error.

class cosmolkit.PropertyValueKind¶

The modeled source value kinds supported by atom and bond properties.

Declared values: String, Int, UInt, IntVector, StringVector, Double, Bool.

Members (7)

Bool = PropertyValueKind.Bool¶

Double = PropertyValueKind.Double¶

Int = PropertyValueKind.Int¶

IntVector = PropertyValueKind.IntVector¶

String = PropertyValueKind.String¶

StringVector = PropertyValueKind.StringVector¶

UInt = PropertyValueKind.UInt¶

class cosmolkit.ProteinAtomRef¶

Read-only protein atom reference with parent residue and Cartesian position.

Members (9)

altloc() → Optional[str]¶: Alternate-location label, or None when the site is not alternate.

atomic_number() → int¶: Atomic number (proton count); zero denotes a dummy atom.

element() → Element¶: Chemical element as an Element value.

element_symbol() → str¶: Chemical element symbol, such as “C” or “Cl”.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

name() → str¶: Stored name of this value.

position() → tuple[float, float, float]¶: Cartesian position as an (x, y, z) tuple in angstroms.

residue() → ProteinResidueRef¶: Return the parent residue reference.

row() → BioAtomRow¶: Return the detached row represented by this hierarchy reference.

class cosmolkit.ProteinChainRef¶

Read-only reference to a protein chain and its residue/atom hierarchy.

Members (6)

atoms() → list[ProteinAtomRef]¶: Return atom rows in stored graph/hierarchy order.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

kind() → ChainKind¶: Classification/discriminant of this value as defined by its owning type.

residues() → list[ProteinResidueRef]¶: Return residue rows/references in stored hierarchy order.

row() → BioChainRow¶: Return the detached row represented by this hierarchy reference.

source() → ChainSourceIds¶: Source-format identifiers retained separately from local row identifiers.

exception cosmolkit.ProteinProjectionError¶: The biological structure could not be projected as the requested protein view.

exception cosmolkit.ProteinReadError¶: Protein input could not be read into the structural model.

class cosmolkit.ProteinResidueRef¶

Read-only protein residue reference with dictionary classification, sequence codes and atom access.

Members (14)

atoms() → list[ProteinAtomRef]¶: Return atom rows in stored graph/hierarchy order.

canonical_one_letter_code() → Optional[str]¶: One-letter code of the corresponding standard parent residue.

chain() → ProteinChainRef¶: Return the chain reference for a local chain identifier.

code() → ResidueCode¶: Stored residue/atom code; its interpretation is defined by the owning value type.

fasta_code() → str¶: Residue code suitable for FASTA sequence output.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

info() → ResidueInfo¶: Return the associated residue dictionary information, including its classification and sequence codes.

is_modified_amino_acid() → bool¶: Whether the residue dictionary identifies a modified amino acid.

is_standard() → bool¶: Whether the residue belongs to the standard residue set.

kind() → ResidueKind¶: Classification/discriminant of this value as defined by its owning type.

name() → str¶: Stored name of this value.

one_letter_code() → str¶: One-letter residue code recorded by the residue dictionary.

parent_standard_code() → Optional[ResidueCode]¶: Standard parent residue code for a modified residue, when known.

row() → BioResidueRow¶: Return the detached row represented by this hierarchy reference.

class cosmolkit.ProteinSelectionSummary¶

Counts of chains, residues and atoms retained by a protein selection.

Members (3)

atoms: int¶: Return the number of atoms in the structural selection.

chains: int¶: Return chain rows/references in stored hierarchy order.

residues: int¶: Return residue rows/references in stored hierarchy order.

class cosmolkit.QueryAtom¶

Read-only query atom metadata. Predicates belong to the owning QueryGraph; these fields do not turn it into a concrete atom.

Members (10)

atom_map() → Optional[int]¶: Reaction atom-map number, or None when no map is assigned.

atomic_number() → int¶: Atomic number (proton count); zero denotes a dummy atom.

degree() → int¶: Number of graph neighbors, including explicit hydrogen vertices.

explicit_hydrogens() → int¶: Hydrogen count stored on the atom, excluding separate hydrogen graph vertices.

formal_charge() → int¶: Formal charge in units of the elementary charge.

id() → int¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

is_aromatic() → bool¶: Whether the stored atom or bond has the aromatic flag.

isotope() → Optional[int]¶: Explicit isotope mass number, or None when unspecified.

no_implicit() → bool¶: Whether implicit hydrogen addition is disabled for this atom.

radical_electrons() → int¶: Number of unpaired radical electrons assigned to the atom.

exception cosmolkit.QueryCompileError¶: The SMARTS query could not be compiled into a reusable matching plan.

class cosmolkit.QueryGraph¶

SMARTS query graph with atom/bond predicates.

Construct with from_smarts() or parse_smarts(). A query graph is not a concrete molecule and retains predicates needed by substructure matching.

Members (5)

static from_smarts(text) → QueryGraph¶: Parse SMARTS text into a QueryGraph; this is a query, not a concrete Molecule.

static from_smarts_with_params(text, params) → QueryGraph¶: Parse SMARTS text into a QueryGraph; this is a query, not a concrete Molecule. Uses the supplied configuration object.

name() → Optional[str]¶: Stored name of this value.

num_atoms() → int¶: Number of atoms in the graph or selected structure.

num_bonds() → int¶: Number of bonds in the graph.

class cosmolkit.RandomSmilesWriteParams(*, isomeric_smiles=True, kekule=False, all_bonds_explicit=False, all_hydrogens_explicit=False)¶

Source options accepted by RDKit’s random-SMILES vector writer.

Members (4)

property all_bonds_explicit: bool¶: Whether all bonds, including single bonds, have explicit output symbols.

property all_hydrogens_explicit: bool¶: Whether hydrogen counts are written explicitly on every atom.

property isomeric_smiles: bool¶: Whether isotope and stereochemical information is included in the output notation.

property kekule: bool¶: Whether aromatic systems are written with explicit single/double bonds.

class cosmolkit.Reaction¶

Owned reaction template with reactant, agent and product QueryGraph values.

Construct from SMIRKS or explicit templates. run() accepts the ordered reactant list and returns product sets without mutating those reactants. Template edits use value-returning methods.

Members (34)

agent_template(index) → QueryGraph¶: Return agent QueryGraph template(s) in stored template order; indices are zero-based.

agent_templates() → list[QueryGraph]¶: Return agent QueryGraph template(s) in stored template order; indices are zero-based.

static from_smirks(text) → Reaction¶: Parse reaction SMIRKS text into a Reaction; parsing failures raise ReactionParseError.

static from_smirks_with_params(text, params) → Reaction¶: Parse reaction SMIRKS text into a Reaction; parsing failures raise ReactionParseError. Uses the supplied configuration object.

static from_templates(reactants, products, agents) → Reaction¶: Construct a Reaction from reactant, product and agent query templates.

implicit_properties() → bool¶: Return whether unspecified product atom properties may be inherited from reactants.

is_initialized() → bool¶: Return whether reactant matchers have been initialized.

match_params() → SubstructMatchParams¶: Return the substructure-matching configuration used to find reactant template matches.

num_agent_templates() → int¶: Return the number of agent query templates.

num_product_templates() → int¶: Return the number of product query templates.

num_reactant_templates() → int¶: Return the number of reactant query templates.

product_template(index) → QueryGraph¶: Return product QueryGraph template(s) in stored template order; indices are zero-based.

product_templates() → list[QueryGraph]¶: Return product QueryGraph template(s) in stored template order; indices are zero-based.

reactant_template(index) → QueryGraph¶: Return reactant QueryGraph template(s) in stored template order; indices are zero-based.

reactant_templates() → list[QueryGraph]¶: Return reactant QueryGraph template(s) in stored template order; indices are zero-based.

run(reactants, params=None) → list[list[Molecule]]¶: Run this reaction on the ordered reactant Molecule list. Return a list of product sets, each a list of Molecule values in product-template order. Reactants are unchanged; params and keyword options are mutually exclusive.

to_cx_smirks() → str¶: Return reaction SMIRKS text with supported CX annotations.

to_cx_smirks_with_params(params) → str¶: Return reaction SMIRKS text with supported CX annotations. Uses the supplied configuration object.

to_smirks() → str¶: Return reaction SMIRKS text with reactants, agents and products; leave the Reaction unchanged.

to_smirks_with_params(params) → str¶: Return reaction SMIRKS text with reactants, agents and products; leave the Reaction unchanged. Uses the supplied configuration object.

validate() → ReactionValidationReport¶: Return a ReactionValidationReport with warnings and errors for template and atom-map consistency; do not silently repair the reaction.

validate_with_params(params) → ReactionValidationReport¶: Return a ReactionValidationReport with warnings and errors for template and atom-map consistency; do not silently repair the reaction. Uses the supplied configuration object.

with_agent_template(template) → Reaction¶: Return a new Reaction with the supplied agent QueryGraph template; leave the source reaction unchanged.

with_implicit_properties(enabled) → Reaction¶: Return a new Reaction with the requested product-property inheritance policy.

with_initialized() → Reaction¶: Return an initialized Reaction with compiled reactant matchers; leave the source Reaction unchanged.

with_initialized_with_params(params) → Reaction¶: Return an initialized Reaction with compiled reactant matchers; leave the source Reaction unchanged. Uses the supplied configuration object.

with_match_params(params) → Reaction¶: Return a new Reaction using the supplied SubstructMatchParams for reactant template matching.

with_product_template(template) → Reaction¶: Return a new Reaction with the supplied product QueryGraph template; leave the source reaction unchanged.

with_reactant_template(template) → Reaction¶: Return a new Reaction with the supplied reactant QueryGraph template; leave the source reaction unchanged.

without_agents() → ReactionTemplateRemoval¶: Return a new Reaction with all agent templates removed.

without_unmapped_products() → ReactionTemplateRemoval¶: Return a ReactionTemplateRemoval containing the new reaction and removed product templates, according to the unmapped-atom threshold.

without_unmapped_products_with_params(params) → ReactionTemplateRemoval¶: Return a ReactionTemplateRemoval containing the new reaction and removed product templates, according to the unmapped-atom threshold. Uses the supplied configuration object.

without_unmapped_reactants() → ReactionTemplateRemoval¶: Return a ReactionTemplateRemoval containing the new reaction and removed reactant templates, according to the unmapped-atom threshold.

without_unmapped_reactants_with_params(params) → ReactionTemplateRemoval¶: Return a ReactionTemplateRemoval containing the new reaction and removed reactant templates, according to the unmapped-atom threshold. Uses the supplied configuration object.

exception cosmolkit.ReactionApplyError¶: A reaction could not be applied to the molecule.

class cosmolkit.ReactionApplyParams(*, remove_unmatched_atoms=True)¶

Writable configuration for single-reactant reaction application.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property remove_unmatched_atoms: bool¶: Whether atoms not matched by the reaction template are removed during application.

class cosmolkit.ReactionApplyResult¶

Result of single-reactant reaction application: the resulting molecule and whether it changed.

Members (2)

changed: bool¶: Whether reaction application changed the molecule.

molecule: Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

class cosmolkit.ReactionCoordinateSelection¶

Explicit reaction coordinate selection: automatic, stored 2D, or a specified 3D conformer ID.

Members (7)

static auto() → ReactionCoordinateSelection¶: Construct a coordinate selection for automatic coordinate resolution, rejecting an ambiguous selection.

id: Optional[int]¶: Requested stored 2D or 3D conformer ID, or None for automatic selection.

is_2d: bool¶: Return whether this selection uses stored 2D coordinates.

is_3d: bool¶: Whether the conformer/input is designated three-dimensional.

is_auto: bool¶: Return whether this selection uses automatic coordinate resolution.

static three_d(id) → ReactionCoordinateSelection¶: Construct a coordinate selection for the stored 3D conformer with the supplied ID.

static two_d(id) → ReactionCoordinateSelection¶: Construct a coordinate selection for the separate stored 2D conformer.

exception cosmolkit.ReactionInitializationError¶: Reaction templates could not be initialized for execution.

exception cosmolkit.ReactionModelError¶: The reaction templates or their references are structurally invalid.

exception cosmolkit.ReactionParseError¶: Reaction SMARTS, SMILES or reaction-block text could not be parsed.

class cosmolkit.ReactionParseParams(*, use_smiles=False, sanitize=False, replacements=None, allow_cxsmiles=True, strict_cxsmiles=True)¶

Writable configuration for reaction SMIRKS parsing.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (5)

property allow_cxsmiles: bool¶: Whether a CX extension following the graph notation is parsed.

property replacements: dict[str, str]¶: Text substitutions applied before parsing.

property sanitize: bool¶

perform the selected chemical sanitization stages. The source molecule is unchanged.

Type:: Apply to a new molecule and return the result

property strict_cxsmiles: bool¶: Whether malformed CX extension data is rejected.

property use_smiles: bool¶: Whether reaction components are parsed as SMILES rather than SMARTS.

exception cosmolkit.ReactionProductError¶: A reaction product could not be constructed or finalized.

class cosmolkit.ReactionRole¶

Source template role, retaining source vector order.

Declared values: Reactant, Product, Agent.

Members (3)

Agent = ReactionRole.Agent¶

Product = ReactionRole.Product¶

Reactant = ReactionRole.Reactant¶

exception cosmolkit.ReactionRunError¶: A reaction could not be executed with the supplied reactants and options.

class cosmolkit.ReactionRunParams(*, max_products=1000, coordinate_selections=None, copy_atom_properties=False)¶

Writable configuration for multi-reactant reaction execution.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property coordinate_selections: list[ReactionCoordinateSelection]¶: Empty selects Auto for each input; otherwise input arity must match.

property copy_atom_properties: bool¶

fill missing product user properties from atom origins. False preserves native behavior; it never clears existing properties.

Type:: CK extension

property max_products: int¶: RDKit default 1000; zero leaves matching and combinations unlimited.

class cosmolkit.ReactionSingleRunParams(*, coordinate_selection=None)¶

Writable configuration for single-reactant reaction coordinate selection.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property coordinate_selection: ReactionCoordinateSelection¶: Explicit selection of stored 2D coordinates, a 3D conformer, or automatic resolution.

class cosmolkit.ReactionTemplateRemoval¶

New reaction plus the query templates removed by a template-filtering operation.

Members (2)

reaction: Reaction¶: Reaction value produced by this result.

removed_templates: list[QueryGraph]¶: QueryGraph templates removed by the filtering operation.

class cosmolkit.ReactionTemplateRemovalParams(*, threshold_unmapped_atoms=0.2, move_to_agent_templates=True)¶

Writable configuration for filtering unmapped reaction templates.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property move_to_agent_templates: bool¶: Whether removed reactant/product templates are retained as agent templates.

property threshold_unmapped_atoms: float¶: Unmapped-atom fraction above which a reaction template is removed.

exception cosmolkit.ReactionValidationError¶: Reaction-template validation could not be completed.

class cosmolkit.ReactionValidationIssue¶

Structured reaction validation issue, with severity, template role/index, atom/map context and detail.

Members (8)

atom: Optional[int]¶: Atom index associated with the validation issue, when available.

detail: str¶: Human-readable context for this issue.

kind: ReactionValidationIssueKind¶: Classification/discriminant of this value as defined by its owning type.

map: Optional[int]¶: Atom-map number associated with this issue, when available.

maps: list[int]¶: Atom-map numbers associated with this issue.

role: Optional[ReactionRole]¶: Reactant, product or agent template role associated with this issue.

severity: ReactionValidationSeverity¶: Validation issue severity.

template: Optional[int]¶: Zero-based template index associated with this issue, when available.

class cosmolkit.ReactionValidationIssueKind¶

Typed category of reaction template or atom-map validation failure.

Declared values: MissingReactants, MissingProducts, DuplicateReactantMap, UnmappedReactant, DuplicateProductMap, MissingProductMapReactant, UnmappedProduct, UnmappedReactantMaps, MultipleCharge, MultipleHydrogenCount, MultipleMass, MultipleIsotope.

Members (12)

DuplicateProductMap = ReactionValidationIssueKind.DuplicateProductMap¶

DuplicateReactantMap = ReactionValidationIssueKind.DuplicateReactantMap¶

MissingProductMapReactant = ReactionValidationIssueKind.MissingProductMapReactant¶

MissingProducts = ReactionValidationIssueKind.MissingProducts¶

MissingReactants = ReactionValidationIssueKind.MissingReactants¶

MultipleCharge = ReactionValidationIssueKind.MultipleCharge¶

MultipleHydrogenCount = ReactionValidationIssueKind.MultipleHydrogenCount¶

MultipleIsotope = ReactionValidationIssueKind.MultipleIsotope¶

MultipleMass = ReactionValidationIssueKind.MultipleMass¶

UnmappedProduct = ReactionValidationIssueKind.UnmappedProduct¶

UnmappedReactant = ReactionValidationIssueKind.UnmappedReactant¶

UnmappedReactantMaps = ReactionValidationIssueKind.UnmappedReactantMaps¶

class cosmolkit.ReactionValidationParams(*, silent=False)¶

Writable configuration for reaction validation diagnostics.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property silent: bool¶: Whether reaction validation suppresses diagnostic output.

class cosmolkit.ReactionValidationReport¶

Reaction-template validation warnings and errors; is_valid reports whether errors are absent.

Members (5)

errors: list[ReactionValidationIssue]¶: Return the reaction-template validation issues classified as errors.

is_valid: bool¶: Whether this result satisfies its domain validity conditions.

num_errors: int¶: Number of reaction validation errors.

num_warnings: int¶: Number of reaction validation warnings.

warnings: list[ReactionValidationIssue]¶: Reaction validation warning issues in report order.

class cosmolkit.ReactionValidationSeverity¶

Severity of a reaction validation issue: warning or error.

Declared values: Warning, Error.

Members (2)

Error = ReactionValidationSeverity.Error¶

Warning = ReactionValidationSeverity.Warning¶

exception cosmolkit.ReactionWriteError¶: The reaction could not be serialized in the requested notation or format.

class cosmolkit.ReactionWriteParams(*, canonical=False, isomeric_smiles=True, rooted_at_atom=None, include_dative_bonds=True, include_cx=False, cx_fields=None, coordinate_selections=None)¶

Writable configuration for reaction SMIRKS/CX output.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

property canonical: bool¶: Whether canonical atom traversal is used for output.

property coordinate_selections: list[ReactionCoordinateSelection]¶: Per template in original reactant, agent, product insertion order.

property cx_fields: CxSmilesFields¶: Bit mask selecting CX annotation fields.

property include_cx: bool¶: Whether reaction output includes supported CX annotations.

property include_dative_bonds: bool¶: Whether dative bonds are included in the requested graph operation/output.

property isomeric_smiles: bool¶: Whether isotope and stereochemical information is included in the output notation.

property rooted_at_atom: Optional[int]¶: Atom index at which output traversal starts, or None for the default traversal.

class cosmolkit.RemoveHsParams(*, remove_degree_zero=False, remove_higher_degrees=False, remove_only_h_neighbors=False, remove_isotopes=False, remove_and_track_isotopes=False, remove_dummy_neighbors=False, remove_defining_bond_stereo=False, remove_with_wedged_bond=True, remove_with_query=False, remove_mapped=True, remove_in_sgroups=True, show_warnings=True, remove_nonimplicit=True, update_explicit_count=False, remove_hydrides=False, remove_nontetrahedral_neighbors=False, sanitize=True)¶

Writable configuration for explicit hydrogen removal.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (17)

property remove_and_track_isotopes: bool¶: Whether removed isotope-labeled hydrogens are tracked for later restoration.

property remove_defining_bond_stereo: bool¶: Whether hydrogens needed to define bond stereochemistry may be removed.

property remove_degree_zero: bool¶: Whether isolated hydrogen atoms are eligible for removal.

property remove_dummy_neighbors: bool¶: Whether hydrogens attached to dummy atoms are eligible for removal.

property remove_higher_degrees: bool¶: Whether hydrogen atoms bonded to more than one atom are eligible for removal.

property remove_hydrides: bool¶: Whether negatively charged hydrogen atoms may be removed.

property remove_in_sgroups: bool¶: Whether hydrogen atoms referenced by substance groups may be removed.

property remove_isotopes: bool¶: Whether isotope-labeled hydrogen atoms are eligible for removal.

property remove_mapped: bool¶: Whether atom-mapped hydrogen atoms may be removed.

property remove_nonimplicit: bool¶: Whether hydrogens not originating from implicit hydrogen expansion may be removed.

property remove_nontetrahedral_neighbors: bool¶: Whether hydrogens defining non-tetrahedral stereochemistry may be removed.

property remove_only_h_neighbors: bool¶: Whether hydrogens attached only to other hydrogens are eligible for removal.

property remove_with_query: bool¶: Whether query-bearing hydrogen atoms may be removed.

property remove_with_wedged_bond: bool¶: Whether hydrogens attached by wedge-marked bonds may be removed.

property sanitize: bool¶: Return a new result that will perform the selected chemical sanitization stages. The source molecule is unchanged.

property show_warnings: bool¶: Whether hydrogen-removal warnings are emitted.

property update_explicit_count: bool¶: Whether parent-atom explicit hydrogen counts are updated after removal.

class cosmolkit.Replace3DCoordinatesParams(conformer_id=0)¶

Writable configuration for replacement of a stored 3D conformer by ID.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property conformer_id: int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

class cosmolkit.ResidueAddress¶

Structural residue address carrying sequence number, insertion code, segment and residue name; not a local row index.

Members (4)

insertion_code: Optional[int]¶: Source residue insertion code.

name: str¶: Stored name of this value.

segment: str¶: Source segment identifier, when present.

sequence_number: Optional[int]¶: Source residue sequence number, not a local row identifier.

class cosmolkit.ResidueCode(value)¶

Residue identities from the built-in chemical dictionary, including amino acids, nucleotides, water and non-polymer entries.

Members (368)

A = 327¶

A2G = 323¶

ABA = 3¶

ACA = 228¶

ACE = 169¶

ACN = 229¶

ACT = 162¶

ACY = 242¶

ADP = 167¶

AG = 342¶

AGM = 127¶

AIB = 81¶

AL = 343¶

ALA = 0¶

ALC = 96¶

ALY = 44¶

ARG = 1¶

ASN = 2¶

ASP = 4¶

ASX = 5¶

ATP = 176¶

AZI = 234¶

B3E = 115¶

B3P = 210¶

B7G = 273¶

BA = 344¶

BCN = 238¶

BE7 = 189¶

BEQ = 288¶

BFD = 124¶

BGC = 237¶

BMA = 166¶

BME = 187¶

BMT = 85¶

BNG = 235¶

BOG = 236¶

BR = 345¶

BRO = 239¶

BRU = 152¶

BTB = 211¶

BU1 = 196¶

BU2 = 194¶

BU3 = 192¶

C = 328¶

C10 = 274¶

C15 = 289¶

C8E = 213¶

CA = 346¶

CAC = 240¶

CAF = 108¶

CAS = 46¶

CBM = 243¶

CBR = 153¶

CBX = 241¶

CCC = 143¶

CCN = 230¶

CD = 347¶

CE1 = 295¶

CGU = 66¶

CIR = 84¶

CIT = 188¶

CL = 348¶

CLO = 244¶

CM = 349¶

CM5 = 227¶

CME = 37¶

CN = 350¶

CO = 351¶

CPS = 222¶

CR2 = 60¶

CR8 = 103¶

CRF = 122¶

CRO = 47¶

CRQ = 89¶

CRY = 301¶

CS = 352¶

CSD = 35¶

CSH = 7¶

CSO = 32¶

CSS = 52¶

CSX = 48¶

CU = 353¶

CU1 = 247¶

CXE = 297¶

CXM = 71¶

CYN = 248¶

CYS = 6¶

DA = 335¶

DAB = 126¶

DAL = 39¶

DAR = 62¶

DAS = 69¶

DC = 336¶

DCY = 73¶

DDQ = 255¶

DG = 337¶

DGL = 50¶

DGN = 80¶

DHA = 106¶

DHD = 202¶

DHI = 76¶

DI = 338¶

DIA = 296¶

DIL = 86¶

DIO = 257¶

DLE = 55¶

DLY = 63¶

DMF = 256¶

DMS = 168¶

DMU = 254¶

DMX = 223¶

DN = 341¶

DOC = 148¶

DOD = 155¶

DOX = 258¶

DPN = 53¶

DPR = 49¶

DR6 = 232¶

DSG = 74¶

DSN = 54¶

DT = 339¶

DTH = 78¶

DTR = 70¶

DTY = 75¶

DU = 340¶

DVA = 51¶

DXG = 226¶

EDO = 159¶

EEE = 263¶

EGL = 264¶

EOH = 262¶

EPE = 185¶

ETF = 313¶

F = 333¶

FAD = 165¶

FCY = 267¶

FE = 354¶

FE2 = 319¶

FGA = 87¶

FLO = 265¶

FME = 43¶

FMN = 183¶

FMT = 180¶

FRU = 268¶

FUC = 179¶

FVA = 120¶

G = 329¶

GAL = 181¶

GBL = 269¶

GCD = 225¶

GDP = 178¶

GHP = 91¶

GL3 = 119¶

GLA = 324¶

GLC = 231¶

GLN = 8¶

GLO = 251¶

GLU = 9¶

GLX = 10¶

GLY = 11¶

GOL = 158¶

GPX = 270¶

GYS = 101¶

H2U = 135¶

HEM = 156¶

HEZ = 276¶

HG = 355¶

HIC = 56¶

HIS = 12¶

HOH = 154¶

HTG = 272¶

HTO = 271¶

HYP = 45¶

I = 330¶

IAS = 83¶

ICI = 279¶

ICT = 280¶

IDO = 278¶

ILE = 13¶

IOD = 277¶

IOH = 207¶

IPA = 208¶

IPH = 298¶

JEF = 293¶

K = 334¶

KCX = 34¶

KPI = 104¶

LAT = 282¶

LBT = 283¶

LDA = 284¶

LEU = 14¶

LI = 356¶

LLP = 36¶

LMT = 261¶

LYS = 15¶

M2G = 140¶

M3L = 42¶

MA4 = 249¶

MA6 = 139¶

MAA = 100¶

MAN = 164¶

MDO = 99¶

MEA = 116¶

MED = 117¶

MEN = 77¶

MEQ = 125¶

MES = 172¶

MET = 16¶

MG = 357¶

MG8 = 290¶

MHA = 191¶

MHO = 92¶

MHS = 111¶

MIA = 147¶

MK8 = 102¶

MLE = 68¶

MLU = 112¶

MLY = 38¶

MLZ = 59¶

MN = 358¶

MN3 = 285¶

MOH = 287¶

MPD = 171¶

MPO = 224¶

MRD = 190¶

MRY = 286¶

MSE = 17¶

MTL = 252¶

MVA = 58¶

N = 332¶

N8E = 219¶

NA = 359¶

NAD = 173¶

NAG = 160¶

NAP = 174¶

NCO = 246¶

NDG = 325¶

NEP = 93¶

NGA = 326¶

NH2 = 170¶

NH4 = 233¶

NHE = 212¶

NI = 360¶

NLE = 57¶

NO = 361¶

NO3 = 292¶

NRQ = 65¶

OAS = 118¶

OCS = 41¶

OMC = 133¶

OMG = 131¶

OMU = 137¶

OMY = 107¶

OMZ = 123¶

ORN = 18¶

OTE = 214¶

P33 = 218¶

P4C = 294¶

PB = 362¶

PCA = 31¶

PDO = 195¶

PE4 = 215¶

PE7 = 199¶

PE8 = 217¶

PEG = 163¶

PEU = 203¶

PG4 = 177¶

PG5 = 200¶

PG6 = 197¶

PGE = 182¶

PGO = 193¶

PGQ = 303¶

PGR = 302¶

PHD = 114¶

PHE = 19¶

PHI = 88¶

PHL = 121¶

PIG = 209¶

PIN = 299¶

PLP = 184¶

PO4 = 161¶

POL = 291¶

PRO = 20¶

PSU = 128¶

PTR = 33¶

PYL = 28¶

R0AF = 109¶

R0TD = 67¶

R12P = 259¶

R144 = 314¶

R15P = 300¶

R16D = 275¶

R1BO = 198¶

R1MA = 141¶

R1MG = 145¶

R1PS = 221¶

R2MA = 144¶

R2MG = 134¶

R2OS = 220¶

R3CO = 245¶

R3DR = 151¶

R3FG = 97¶

R3NI = 320¶

R4OC = 138¶

R4SU = 136¶

R5BU = 146¶

R5CM = 150¶

R5MU = 129¶

R6MZ = 142¶

R7MG = 130¶

R8OG = 149¶

RB = 363¶

SAC = 79¶

SAL = 206¶

SAR = 61¶

SBT = 205¶

SCH = 98¶

SCN = 311¶

SCY = 105¶

SDS = 260¶

SEC = 27¶

SEP = 29¶

SER = 21¶

SF4 = 186¶

SIA = 321¶

SMC = 82¶

SME = 90¶

SNC = 113¶

SNN = 110¶

SO4 = 157¶

SOR = 253¶

SPD = 304¶

SPK = 305¶

SPM = 306¶

SR = 364¶

SUC = 307¶

TAR = 250¶

TAU = 204¶

TBU = 308¶

TEP = 310¶

TFP = 201¶

THR = 22¶

TLA = 281¶

TMA = 309¶

TOX = 95¶

TPO = 30¶

TPQ = 72¶

TRE = 312¶

TRP = 23¶

TRQ = 94¶

TRS = 175¶

TRT = 266¶

TYR = 24¶

TYS = 40¶

U = 331¶

UMQ = 315¶

UNK = 25¶

UNKNOWN = 367¶

UR3 = 132¶

URE = 316¶

VAL = 26¶

XPE = 216¶

XYP = 322¶

Y1 = 365¶

YCM = 64¶

YT3 = 317¶

ZN = 366¶

ZN2 = 318¶

exception cosmolkit.ResidueCodeParseError(input)¶

A residue dictionary code name is not recognized; input() returns the supplied name.

Members (1)

input() → str¶: Return the input context recorded by this error.

class cosmolkit.ResidueIdentity¶

Residue name and its dictionary classification, preserving unrecognized names.

Members (5)

code() → ResidueCode¶: Stored residue/atom code; its interpretation is defined by the owning value type.

info() → ResidueInfo¶: Return the associated residue dictionary information, including its classification and sequence codes.

is_tabulated() → bool¶: Return whether the residue name appears in the built-in residue dictionary.

name() → str¶: Stored name of this value.

static new(name) → ResidueIdentity¶: Construct a ResidueIdentity value from the supplied inputs.

class cosmolkit.ResidueInfo¶

Read-only residue dictionary entry containing identity, class, sequence codes, composition and standard/modified status.

Members (22)

canonical_one_letter_code() → Optional[str]¶: One-letter code of the corresponding standard parent residue.

code() → ResidueCode¶: Stored residue/atom code; its interpretation is defined by the owning value type.

fasta_code() → str¶: Residue code suitable for FASTA sequence output.

found() → bool¶: Whether the residue name was found in the built-in dictionary.

hydrogen_count() → int¶: Hydrogen count recorded in the residue dictionary.

is_amino_acid() → bool¶: Whether the residue dictionary identifies an amino acid.

is_buffer_or_water() → bool¶: Return whether the residue is classified as buffer or water.

is_dna() → bool¶: Return whether the dictionary classifies this residue as DNA.

is_modified_amino_acid() → bool¶: Whether the residue dictionary identifies a modified amino acid.

is_na_linking() → bool¶: Return whether the residue participates in nucleic-acid polymer linkage.

is_nucleic_acid() → bool¶: Whether the residue dictionary identifies a nucleic-acid residue.

is_peptide_linking() → bool¶: Return whether the residue participates in peptide polymer linkage.

is_rna() → bool¶: Return whether the dictionary classifies this residue as RNA.

is_standard() → bool¶: Whether the residue belongs to the standard residue set.

is_water() → bool¶: Whether the residue dictionary identifies water.

kind() → ResidueInfoKind¶: Return the residue dictionary chemical classification.

kind_name() → str¶: Return the text name of the residue dictionary classification.

linking_type() → int¶: Residue polymer-linking classification.

name() → str¶: Stored name of this value.

one_letter_code() → str¶: One-letter residue code recorded by the residue dictionary.

parent_standard_code() → Optional[ResidueCode]¶: Standard parent residue code for a modified residue, when known.

weight() → float¶: Residue molecular weight from the residue dictionary.

class cosmolkit.ResidueInfoKind(value)¶

Chemical classification of a residue dictionary entry, including peptide, nucleic-acid and non-polymer classes.

Members (12)

AA = 1¶

AAD = 2¶

BUF = 7¶

DNA = 6¶

ELS = 11¶

HOH = 8¶

KET = 10¶

MAA = 4¶

PAA = 3¶

PYR = 9¶

RNA = 5¶

UNKNOWN = 0¶

class cosmolkit.ResidueKind(value)¶

Structural residue classification, including amino acids, nucleotides, saccharides, water, buffers and ligands.

Members (8)

AminoAcid = 'AminoAcid'¶

Buffer = 'Buffer'¶

Dna = 'Dna'¶

Ligand = 'Ligand'¶

Rna = 'Rna'¶

Saccharide = 'Saccharide'¶

Unknown = 'Unknown'¶

Water = 'Water'¶

exception cosmolkit.ResidueSequenceError¶: Residue sequence conversion failed for the selected residue classification.

class cosmolkit.ResidueSourceIds¶

Source residue identifiers: author number/insertion code, label number, subchain and entity.

Members (4)

label_entity_id() → Optional[str]¶: mmCIF label entity identifier.

label_seq_id() → Optional[int]¶: mmCIF label residue sequence number, when present.

seq_id() → Optional[PdbSeqId]¶: Author residue sequence identifier, including insertion code.

subchain_id() → Optional[str]¶: Source subchain identifier.

class cosmolkit.RingSearchParams(*, include_dative_bonds=False, include_hydrogen_bonds=False)¶

Writable configuration for ring perception.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property include_dative_bonds: bool¶: Whether dative bonds are included in the requested graph operation/output.

property include_hydrogen_bonds: bool¶: Whether hydrogen bonds participate in ring search.

class cosmolkit.RingStereoRelation¶

Relative stereochemical orientation between two ring stereocenters.

Members (3)

atom: int¶: Zero-based atom index of the first stereocenter in this ring relationship.

other: int¶: Index of the other stereocenter in this ring relationship.

same_orientation: bool¶: Whether the linked ring stereocenters have the same relative orientation.

class cosmolkit.RotatableBondsOptions¶

Selects which rotatable-bond definition the count functions use.

Mirrors RDKit NumRotatableBondsOptions (Lipinski.h:39-43). The C++ int discriminants (Default = -1, NonStrict = 0, Strict = 1, StrictLinkages = 2) are never observable through the source API (the option is only compared for equality), so the Rust projection carries no numeric discriminants.

The source also exposes a deprecated bool overload (Lipinski.cpp:185-187) mapping strict == true to Strict and false to NonStrict. This binding exposes the enum options, not the deprecated boolean overload.

Declared values: Default, NonStrict, Strict, StrictLinkages.

Members (4)

Default = RotatableBondsOptions.Default¶

NonStrict = RotatableBondsOptions.NonStrict¶

Strict = RotatableBondsOptions.Strict¶

StrictLinkages = RotatableBondsOptions.StrictLinkages¶

exception cosmolkit.SanitizeError¶: Chemical sanitization failed; the message identifies the failing chemical condition.

class cosmolkit.SanitizeOperations¶

Bit mask selecting chemical sanitization stages. Combine stage values with bitwise OR; NONE disables all stages and ALL selects all supported stages.

Members (18)

ADJUST_HS = <cosmolkit.SanitizeOperations object>¶

ALL = <cosmolkit.SanitizeOperations object>¶

CLEANUP = <cosmolkit.SanitizeOperations object>¶

CLEANUP_ATROPISOMERS = <cosmolkit.SanitizeOperations object>¶

CLEANUP_CHIRALITY = <cosmolkit.SanitizeOperations object>¶

CLEANUP_ORGANOMETALLICS = <cosmolkit.SanitizeOperations object>¶

FIND_RADICALS = <cosmolkit.SanitizeOperations object>¶

KEKULIZE = <cosmolkit.SanitizeOperations object>¶

NONE = <cosmolkit.SanitizeOperations object>¶

PROPERTIES = <cosmolkit.SanitizeOperations object>¶

SET_AROMATICITY = <cosmolkit.SanitizeOperations object>¶

SET_CONJUGATION = <cosmolkit.SanitizeOperations object>¶

SET_HYBRIDIZATION = <cosmolkit.SanitizeOperations object>¶

SYMM_RINGS = <cosmolkit.SanitizeOperations object>¶

bits() → int¶: Return the underlying unsigned integer bit mask.

contains(operation) → bool¶: Return whether every bit in the supplied flag value is included in this mask.

static from_bits(bits) → SanitizeOperations¶: Construct a flag value from an integer mask using the declared flag validation.

is_empty() → bool¶: Return whether there are no stored entries.

class cosmolkit.SanitizeParams(operations=None)¶

Writable configuration for chemical sanitization stages.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property operations: SanitizeOperations¶: Sanitization stage bit mask; combine SanitizeOperations values with bitwise OR.

class cosmolkit.SanitizeStage¶

Exact sanitization stage used for source-compatible failure reporting.

Declared values: .

Members (13)

AdjustHs = SanitizeStage.AdjustHs¶

Cleanup = SanitizeStage.Cleanup¶

CleanupAtropisomers = SanitizeStage.CleanupAtropisomers¶

CleanupChirality = SanitizeStage.CleanupChirality¶

CleanupOrganometallics = SanitizeStage.CleanupOrganometallics¶

FindRadicals = SanitizeStage.FindRadicals¶

Kekulize = SanitizeStage.Kekulize¶

None_ = SanitizeStage.None_¶

Properties = SanitizeStage.Properties¶

SetAromaticity = SanitizeStage.SetAromaticity¶

SetConjugation = SanitizeStage.SetConjugation¶

SetHybridization = SanitizeStage.SetHybridization¶

SymmRings = SanitizeStage.SymmRings¶

class cosmolkit.SdfBatchIterator¶

Iterator over bounded batches from an indexed SDF dataset.

Members (1)

next_batch() → Optional[MoleculeBatch]¶: Return the next batch of records, or None when the input is exhausted.

class cosmolkit.SdfCoordinateMode¶

Explicit interpretation requested for the one conformer read from a MolBlock/SDF record.

Declared values: Preserve, Require2D, Require3D.

Members (3)

Preserve = SdfCoordinateMode.Preserve¶

Require2D = SdfCoordinateMode.Require2D¶

Require3D = SdfCoordinateMode.Require3D¶

class cosmolkit.SdfDataset¶

Indexed SDF file for random access. Open once, then request record text, parsed records or batches.

Members (11)

batches(size=1024, indices=None, errors=None, n_jobs=None, progress_bar=False) → SdfBatchIterator¶: Return an iterator that reads records in bounded batches.

is_empty() → bool¶: Return whether there are no stored entries.

iter() → SdfDatasetIterator¶: Return an iterator over entries in stored order.

len() → int¶: Return the number of stored entries.

metadata(index) → SdfRecordMetadata¶: Experimental, crystallographic and bibliographic metadata.

static open(path, index=None, build=None) → SdfDataset¶: Open and index an SDF file for random record access; individual records are parsed when requested.

static open_with_params(path, params) → SdfDataset¶: Open and index an SDF file for random record access; individual records are parsed when requested. Uses the supplied configuration object.

path() → str¶: Return the source filesystem path.

record(index) → SdfRecord¶: Parse and return the SDF record at the specified zero-based index.

record_text(index) → str¶: Return the unparsed text of the specified SDF record.

record_with_params(index, params) → SdfRecord¶: Parse and return the SDF record at the specified zero-based index. Uses the supplied configuration object.

class cosmolkit.SdfDatasetIterator¶: Iterator over parsed records in SDF dataset order.

exception cosmolkit.SdfError¶: An SDF record could not be parsed, converted or serialized.

class cosmolkit.SdfFormat¶

Molecular connection-table output format: automatic, V2000 or V3000.

Declared values: V2000, V3000.

Members (2)

V2000 = SdfFormat.V2000¶

V3000 = SdfFormat.V3000¶

class cosmolkit.SdfGraph¶

This tag wraps an existing Molecule or QueryGraph; it never lowers a query.

Members (3)

kind: str¶: Return whether this record stores a concrete molecule or a query graph.

molecule: Optional[Molecule]¶: Return the concrete molecule if this is a molecule record; a query remains a query.

query_graph: Optional[QueryGraph]¶: Return the QueryGraph if this is a query record.

class cosmolkit.SdfPropertyList¶

Interpreted SDF atom/bond property list. Entries follow target graph order; None marks an explicit missing value.

Members (3)

name() → str¶: Stored name of this value.

target() → SdfPropertyListTarget¶: Target identifier of this template attachment or SDF property list.

values() → list[Optional[PropertyValue]]¶: Return typed values in target atom/bond order; None denotes an explicit missing value.

class cosmolkit.SdfPropertyListTarget¶

Graph entity to which an interpreted SDF property list applies: Atom or Bond.

Declared values: Atom, Bond.

Members (2)

Atom = SdfPropertyListTarget.Atom¶

Bond = SdfPropertyListTarget.Bond¶

class cosmolkit.SdfReader¶

Streaming SDF reader configured at open time; batches retain per-record outcomes.

Members (5)

batches(size=1024, errors=None, n_jobs=None, progress_bar=False) → SdfReaderBatchIterator¶: Return an iterator that reads records in bounded batches.

static open(path) → SdfReader¶: Open an SDF file for streaming reads using the selected BatchReadParams.

static open_with_params(path, params) → SdfReader¶: Open an SDF file for streaming reads using the selected BatchReadParams. Uses the supplied configuration object.

params() → SdfReadParams¶: Return the parameter values associated with this result or settings view.

path() → pathlib.Path¶: Return the source filesystem path.

class cosmolkit.SdfReaderBatchIterator¶

Iterator over bounded batches from a streaming SDF reader.

Members (1)

next_batch() → Optional[MoleculeBatch]¶: Return the next batch of records, or None when the input is exhausted.

exception cosmolkit.SdfReadError¶: An SDF record or property list could not be read consistently.

class cosmolkit.SdfReadParams(*, sanitize=True, remove_hs=True, strict_parsing=True, expand_attachment_points=False, process_property_lists=True, coordinate_mode=Ellipsis)¶

Writable configuration for MOL/SDF parsing, query handling and coordinate retention.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (6)

property coordinate_mode: SdfCoordinateMode¶

“preserve”, “require_2d”, or “require_3d”; accepts SdfCoordinateMode too.

Type:: Coordinate retention policy

property expand_attachment_points: bool¶: Whether MOL/SDF attachment-point annotations are expanded during parsing.

property process_property_lists: bool¶: Whether SDF atom/bond property lists are interpreted; strict count mismatches raise an error.

property remove_hs: bool¶: Whether removable explicit hydrogens are removed during input conversion.

property sanitize: bool¶: Return a new result that will perform the selected chemical sanitization stages. The source molecule is unchanged.

property strict_parsing: bool¶: Whether malformed or inconsistent format fields are rejected.

class cosmolkit.SdfRecord¶

One SDF record with a concrete Molecule or QueryGraph and ordered data fields.

Query predicates are retained. Data-field names may repeat; their order and raw values are distinct from interpreted atom/bond property lists.

Members (17)

data_field(name) → Optional[str]¶: Return the requested SDF field value if present; ordered duplicate fields remain available through data_fields().

data_fields() → list[tuple[str, str]]¶: Return ordered (name, value) string pairs from the SDF data section, preserving duplicate names.

static from_query_graph(query, properties) → SdfRecord¶: Validate the canonical query graph and retain every ordered source field.

static from_sdf(input) → SdfRecord¶: Parse one SDF record, retaining a concrete or query graph plus ordered data fields; strict property-list count mismatches raise an error.

static from_sdf_with_params(input, params) → SdfRecord¶: Parse one SDF record, retaining a concrete or query graph plus ordered data fields; strict property-list count mismatches raise an error. Uses the supplied configuration object.

graph() → SdfGraph¶: Return the concrete Molecule or QueryGraph stored in this record without discarding query predicates.

index() → int¶: Original zero-based input record index; failed records retain their index.

molecule() → Molecule¶: Return the concrete molecule when the record contains one; query records are not silently converted to concrete molecules.

properties() → MoleculeProperties¶: Return a detached snapshot of the stored properties.

query_graph() → QueryGraph¶: Return the query graph when the record contains one; concrete records are not silently converted into queries.

source_coordinate_dim() → Optional[CoordinateDimension]¶: Coordinate dimensionality recorded by the source format, when present.

substance_groups() → list[SubstanceGroup]¶: Substance-group annotations referencing graph atoms and bonds.

title() → Optional[str]¶: Title recorded in the source header.

to_mol() → str¶: Return a MOL text block using the selected writer options; does not write a file or install generated drawing coordinates on this object.

to_mol_with_params(params) → str¶: Return a MOL text block using the selected writer options; does not write a file or install generated drawing coordinates on this object. Uses the supplied configuration object.

to_sdf() → str¶: Return an SDF text record using the selected writer options; does not write a file.

to_sdf_with_params(params) → str¶: Return an SDF text record using the selected writer options; does not write a file. Uses the supplied configuration object.

class cosmolkit.SdfRecordMetadata¶

Source record position: original index, byte/line ranges and title.

Members (6)

byte_len() → int¶: Length of the source record in bytes.

byte_offset() → int¶: Byte offset of the record in its source file.

byte_range() → tuple[int, int]¶: Byte range occupied by the source record.

index() → int¶: Original zero-based input record index; failed records retain their index.

line_range() → tuple[int, int]¶: Line range occupied by the source record.

title() → Optional[str]¶: Title recorded in the source header.

class cosmolkit.SdfRecordStream¶

Incremental SDF record stream with read position and record/byte/line counters.

Members (8)

batches(size, mode, n_jobs) → SdfReaderBatchIterator¶: Return an iterator that reads records in bounded batches.

bytes_consumed() → int¶: Number of source bytes consumed from this stream.

is_end() → bool¶: Return whether the SDF stream has reached end of input.

lines_consumed() → int¶: Number of source lines consumed from this stream.

next_record() → Optional[SdfRecord]¶: Read the next SDF record, or None at end of input; malformed input remains an error.

static open(path) → SdfRecordStream¶: Open the input SDF path for indexed or streaming access; does not interpret a text block as a path.

static open_with_params(path, params) → SdfRecordStream¶: Open the input SDF path for indexed or streaming access; does not interpret a text block as a path. Uses the supplied configuration object.

records_consumed() → int¶: Number of records consumed from this stream.

class cosmolkit.SGroupBracket¶

Three-point bracket geometry associated with a substance group.

Members (2)

static new(points) → SGroupBracket¶: Construct a SGroupBracket value from the supplied inputs.

points() → list[list[float]]¶: Three points defining the substance-group bracket geometry.

class cosmolkit.SGroupCState¶

Substance-group bond reference and its three-component crossing/connection vector.

Members (3)

bond() → int¶: Return the zero-based bond index referenced by this substance-group connection state.

static new(bond, vector) → SGroupCState¶: Construct a SGroupCState value from the supplied inputs.

vector() → list[float]¶: Three-component vector retained by this SGroup connection state.

class cosmolkit.SGroupDisplay¶

Display annotations attached to a substance group, including bracket geometries.

Members (1)

brackets() → list[SGroupBracket]¶: Substance-group bracket geometries in stored order.

exception cosmolkit.SmartsParseError¶: SMARTS text could not be parsed into a query graph.

class cosmolkit.SmartsParseParams(*, allow_cxsmiles=True, strict_cxsmiles=True, parse_name=True, merge_hs=False, skip_cleanup=False, debug_parse=False, replacements=None)¶

Writable configuration for SMARTS query parsing.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

property allow_cxsmiles: bool¶: Whether a CX extension following the graph notation is parsed.

property debug_parse: bool¶: Parser debug-output level.

property merge_hs: bool¶: Whether explicit query hydrogens are merged into hydrogen-count predicates.

property parse_name: bool¶: Whether trailing text is interpreted as the molecule/query name.

property replacements: dict[str, str]¶: Text substitutions applied before parsing.

property skip_cleanup: bool¶: Whether parser post-processing is skipped.

property strict_cxsmiles: bool¶: Whether malformed CX extension data is rejected.

exception cosmolkit.SmartsWriteError¶: The query graph could not be serialized as SMARTS.

class cosmolkit.SmartsWriteParams(*, include_atom_maps=True, isomeric_smiles=True, include_dative_bonds=True, rooted_at_atom=None)¶

Writable configuration for SMARTS query serialization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property include_atom_maps: bool¶: Whether atom-map numbers are included in SMARTS output.

property include_dative_bonds: bool¶: Whether dative bonds are included in the requested graph operation/output.

property isomeric_smiles: bool¶: Whether isotope and stereochemical information is included in the output notation.

property rooted_at_atom: Optional[int]¶: Atom index at which output traversal starts, or None for the default traversal.

exception cosmolkit.SmilesError¶: SMILES text could not be parsed or chemically prepared as requested.

class cosmolkit.SmilesParseParams(*, sanitize=True, allow_cxsmiles=True, strict_cxsmiles=True, parse_name=True, remove_hs=True, skip_cleanup=False, debug_parse=False, replacements=None)¶

Writable configuration for SMILES parsing.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (8)

property allow_cxsmiles: bool¶: Whether a CX extension following the graph notation is parsed.

property debug_parse: bool¶: Parser debug-output level.

property parse_name: bool¶: Whether trailing text is interpreted as the molecule/query name.

property remove_hs: bool¶: Whether removable explicit hydrogens are removed during input conversion.

property replacements: dict[str, str]¶: Text substitutions applied before parsing.

property sanitize: bool¶

perform the selected chemical sanitization stages. The source molecule is unchanged.

Type:: Apply to a new molecule and return the result

property skip_cleanup: bool¶: Whether parser post-processing is skipped.

property strict_cxsmiles: bool¶: Whether malformed CX extension data is rejected.

exception cosmolkit.SmilesStereoError¶: SMILES stereochemical annotations could not be interpreted consistently.

exception cosmolkit.SmilesWriteError¶: The molecule could not be serialized as SMILES with the supplied options.

class cosmolkit.SmilesWriteParams(*, isomeric_smiles=True, kekule=False, canonical=True, clean_stereo=True, rooted_at_atom=None, all_bonds_explicit=False, all_hydrogens_explicit=False, include_dative_bonds=True, ignore_atom_map_numbers=False)¶

Writable configuration for SMILES serialization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (9)

property all_bonds_explicit: bool¶: Whether all bonds, including single bonds, have explicit output symbols.

property all_hydrogens_explicit: bool¶: Whether hydrogen counts are written explicitly on every atom.

property canonical: bool¶: Whether canonical atom traversal is used for output.

property clean_stereo: bool¶: Whether invalid stereochemical annotations are cleaned before SMILES output.

property ignore_atom_map_numbers: bool¶: Whether atom-map numbers are excluded from canonical ranking.

property include_dative_bonds: bool¶: Whether dative bonds are included in the requested graph operation/output.

property isomeric_smiles: bool¶: Whether isotope and stereochemical information is included in the output notation.

property kekule: bool¶: Whether aromatic systems are written with explicit single/double bonds.

property rooted_at_atom: Optional[int]¶: Atom index at which output traversal starts, or None for the default traversal.

class cosmolkit.SparseBitFingerprint¶

Sparse bit vector (SparseBitVect equivalent).

Members (2)

n_bits() → int¶: Logical width of the fingerprint in bits.

on_bits() → list[int]¶

On bits as raw signed storage values, in the set’s signed ascending order (source IntVect is std::vector<int>).

Source: void SparseBitVect::getOnBits(IntVect &v) const (SparseBitVect.cpp:252-263): the set<int> iterates in signed order, so indices >= 2^31 appear first as wrapped negative values (oracle: {5, 2^31+1} -> [-2147483647, 5]; {7, u32::MAX} -> [-1, 7]).

class cosmolkit.SparseCountFingerprint¶

Sparse count fingerprint with 64-bit feature indices and integer counts for nonzero entries.

Members (14)

fuzzy_and(other) → SparseCountFingerprint¶: Return a new sparse count fingerprint containing the element-wise minimum counts.

fuzzy_or(other) → SparseCountFingerprint¶: Return a new sparse count fingerprint containing the element-wise maximum counts.

length() → int¶: Logical size of the sparse fingerprint index space.

static new(length) → SparseCountFingerprint¶: Construct a SparseCountFingerprint value from the supplied inputs.

nonzero_elements() → dict[int, int]¶: Return a dictionary mapping sparse fingerprint feature indices to nonzero counts.

set_value(index, value) → None¶: Set the count at one sparse fingerprint index; a zero count removes the nonzero entry.

total_value(use_abs=False) → int¶: Return the sum of the stored sparse fingerprint counts.

value(index) → int¶: Return the count at the supplied sparse fingerprint index; absent entries have count zero.

with_added(other) → SparseCountFingerprint¶: Return the element-wise sum of two compatible sparse count fingerprints.

with_added_scalar(value) → SparseCountFingerprint¶: Return a sparse count fingerprint with the scalar added to stored nonzero counts.

with_divided_scalar(value) → SparseCountFingerprint¶: Return a sparse count fingerprint with stored counts divided by the scalar using integer arithmetic.

with_multiplied_scalar(value) → SparseCountFingerprint¶: Return a sparse count fingerprint with stored counts multiplied by the scalar.

with_subtracted(other) → SparseCountFingerprint¶: Return the element-wise difference of two compatible sparse count fingerprints.

with_subtracted_scalar(value) → SparseCountFingerprint¶: Return a sparse count fingerprint with the scalar subtracted from stored nonzero counts.

class cosmolkit.SparseCountFingerprint32¶

Sparse count fingerprint with 32-bit feature indices and integer counts for nonzero entries.

Members (14)

fuzzy_and(other) → SparseCountFingerprint32¶: Return a new sparse count fingerprint containing the element-wise minimum counts.

fuzzy_or(other) → SparseCountFingerprint32¶: Return a new sparse count fingerprint containing the element-wise maximum counts.

length() → int¶: Logical size of the sparse fingerprint index space.

static new(length) → SparseCountFingerprint32¶: Construct a SparseCountFingerprint32 value from the supplied inputs.

nonzero_elements() → dict[int, int]¶: Return a dictionary mapping sparse fingerprint feature indices to nonzero counts.

set_value(index, value) → None¶: Set the count at one sparse fingerprint index; a zero count removes the nonzero entry.

total_value(use_abs=False) → int¶: Return the sum of the stored sparse fingerprint counts.

value(index) → int¶: Return the count at the supplied sparse fingerprint index; absent entries have count zero.

with_added(other) → SparseCountFingerprint32¶: Return the element-wise sum of two compatible sparse count fingerprints.

with_added_scalar(value) → SparseCountFingerprint32¶: Return a sparse count fingerprint with the scalar added to stored nonzero counts.

with_divided_scalar(value) → SparseCountFingerprint32¶: Return a sparse count fingerprint with stored counts divided by the scalar using integer arithmetic.

with_multiplied_scalar(value) → SparseCountFingerprint32¶: Return a sparse count fingerprint with stored counts multiplied by the scalar.

with_subtracted(other) → SparseCountFingerprint32¶: Return the element-wise difference of two compatible sparse count fingerprints.

with_subtracted_scalar(value) → SparseCountFingerprint32¶: Return a sparse count fingerprint with the scalar subtracted from stored nonzero counts.

exception cosmolkit.StereoError¶: Stereochemical assignment or manipulation failed.

class cosmolkit.StereoGroup¶

Detached enhanced-stereo membership with independent read and write IDs.

Members (3)

atoms() → list[int]¶: Return zero-based atom indices belonging to this enhanced-stereochemistry group.

bonds() → list[int]¶: Return zero-based bond indices belonging to this enhanced-stereochemistry group.

id() → Optional[int]¶: Stored enhanced-stereochemistry group identifier, or None when no explicit identifier is present.

class cosmolkit.StereoisomerIterator¶

Lazy iterator over source-ordered stereoisomers.

Construction performs the source-defined preprocessing and candidate discovery. Configuration application, uniqueness, optional embedding, and their errors are deferred until next() requests an output.

Members (2)

next() → Optional[Molecule]¶: Return the next stereoisomer, or None when enumeration is exhausted.

yielded_count: int¶: Number of stereoisomers already yielded by this iterator.

class cosmolkit.StereoisomerOptions(try_embedding=False, only_unassigned=True, max_isomers=1024, random_source=None, unique=True, only_stereo_groups=False)¶

Writable configuration for stereoisomer enumeration and sampling.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (7)

static default() → StereoisomerOptions¶: Return a new StereoisomerOptions value with the standard enumeration defaults.

property max_isomers: int¶: Maximum number of stereoisomers to produce; zero requests exhaustive enumeration.

property only_stereo_groups: bool¶: Whether enumeration is restricted to enhanced stereo groups.

property only_unassigned: bool¶: Whether enumeration changes only currently unspecified stereocenters.

property random_source: Optional[Any]¶: Seeded or callback-based random source used when stereoisomer sampling is required.

property try_embedding: bool¶: Whether candidate stereoisomers are embedded to reject infeasible configurations.

property unique: bool¶: Whether equivalent stereoisomers are deduplicated.

class cosmolkit.StereoisomerRandomSource¶

Source-defined seed or shared random-bits provider.

Cloning a seed does not share an advanced generator. Cloning a provider retains its identity and state without locking or drawing any bits.

Members (2)

static from_integer_seed(value) → StereoisomerRandomSource¶: Construct a reproducible stereoisomer random source from an integer seed.

static from_random_bits(value) → StereoisomerRandomSource¶: Construct a stereoisomer random source from a callable accepting a bit count and returning a nonnegative integer.

exception cosmolkit.StereoReadError¶: The requested stereochemical information could not be read from the molecule.

class cosmolkit.StructureTagParams(*, conformer_id=Ellipsis, replace_existing_tags=True)¶

Writable configuration for chiral-tag assignment from stored coordinates.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property conformer_id: int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property replace_existing_tags: bool¶: Whether existing chiral tags may be replaced by structure-derived tags.

class cosmolkit.SubstanceGroup¶

Substance-group annotation with typed kind, referenced atoms/bonds, properties and display/connection data.

Members (7)

crossing_bond_correspondence() → list[int]¶: Ordered crossing-bond correspondence references encoded by V3000 XBCORR and CX polymer tail-crossing state.

cstates() → list[SGroupCState]¶: Substance-group bond crossing/connection vectors in stored order.

display() → Optional[SGroupDisplay]¶: Substance-group display annotations.

head_crossing_bonds() → list[int]¶: Ordered crossing-bond references encoded by V3000 XBHEAD and CX polymer head-crossing state.

id() → SubstanceGroupId¶: Zero-based identifier in the owning object; not a PDB serial or residue number.

kind() → SubstanceGroupKind¶: Classification/discriminant of this value as defined by its owning type.

static new(id, kind) → SubstanceGroup¶: Construct a SubstanceGroup value from the supplied inputs.

class cosmolkit.SubstanceGroupId¶

Local identifier of a substance-group annotation in a molecular graph.

Members (2)

index() → int¶: Return the zero-based substance-group index in its owning molecule.

static new(index) → SubstanceGroupId¶: Construct a SubstanceGroupId value from the supplied inputs.

class cosmolkit.SubstanceGroupKind¶

MOL/SDF substance-group classification, including standard kinds and an explicit generic kind.

Members (16)

AnyPolymer = <cosmolkit.SubstanceGroupKind object>¶

Copolymer = <cosmolkit.SubstanceGroupKind object>¶

Crosslink = <cosmolkit.SubstanceGroupKind object>¶

Data = <cosmolkit.SubstanceGroupKind object>¶

Formulation = <cosmolkit.SubstanceGroupKind object>¶

static Generic(value) → SubstanceGroupKind¶: Construct an explicitly named substance-group kind not represented by a dedicated standard value.

Graft = <cosmolkit.SubstanceGroupKind object>¶

Mer = <cosmolkit.SubstanceGroupKind object>¶

Mixture = <cosmolkit.SubstanceGroupKind object>¶

MixtureComponent = <cosmolkit.SubstanceGroupKind object>¶

Modification = <cosmolkit.SubstanceGroupKind object>¶

Monomer = <cosmolkit.SubstanceGroupKind object>¶

MultipleGroup = <cosmolkit.SubstanceGroupKind object>¶

StructuralRepeatUnit = <cosmolkit.SubstanceGroupKind object>¶

Superatom = <cosmolkit.SubstanceGroupKind object>¶

generic_value: Optional[str]¶: Return the generic substance-group kind text, or None for a dedicated standard kind.

exception cosmolkit.SubstructMatchError¶: Substructure matching failed while preparing or evaluating the query and target.

class cosmolkit.SubstructMatchParams(*, max_matches=1000, uniquify=True, use_chirality=False, use_enhanced_stereo=False, specified_stereo_query_matches_unspecified=False, use_query_query_matches=False, recursion_possible=True, max_recursive_matches=1000, num_threads=1, aromatic_matches_conjugated=False, aromatic_matches_single_or_double=False, atom_properties=None, bond_properties=None, extra_atom_check_overrides_default_check=False, extra_bond_check_overrides_default_check=False, use_generic_matchers=False, final_match=None, atom_match=None, bond_match=None)¶

Writable substructure matching configuration.

Accept constructor fields or assign them afterward. final_match/atom_match/ bond_match callbacks filter matches and propagate their original Python exceptions. Unknown attributes/options are rejected rather than ignored.

Members (22)

property aromatic_matches_conjugated: bool¶: Whether aromatic query bonds may match conjugated target bonds.

property aromatic_matches_single_or_double: bool¶: Whether aromatic bonds may match single or double bonds.

property atom_match: Optional[Callable[[QueryAtom, Atom], bool]]¶: Optional callback (query_atom, target_atom) -> bool filtering an atom pair. Arguments are QueryAtom and Atom values, not indices. extra_atom_check is an accepted alias; callback exceptions propagate unchanged.

property atom_properties: list[str]¶: Atom property names whose values must agree during matching.

property bond_match: Optional[Callable[[Bond, Bond], bool]]¶: Optional callback (query_bond, target_bond) -> bool filtering a bond pair. Arguments are Bond values, not indices. extra_bond_check is an accepted alias; callback exceptions propagate unchanged.

property bond_properties: list[str]¶: Bond property names whose values must agree during matching.

property extra_atom_check¶: Optional callback (query_atom, target_atom) -> bool filtering an atom pair. Arguments are QueryAtom and Atom values, not indices. extra_atom_check is an accepted alias; callback exceptions propagate unchanged.

property extra_atom_check_overrides_default_check: bool¶: Whether the atom callback replaces, rather than supplements, the default atom test.

property extra_bond_check¶: Optional callback (query_bond, target_bond) -> bool filtering a bond pair. Arguments are Bond values, not indices. extra_bond_check is an accepted alias; callback exceptions propagate unchanged.

property extra_bond_check_overrides_default_check: bool¶: Whether the bond callback replaces, rather than supplements, the default bond test.

property extra_final_check¶: Optional callback (target, atom_indices) -> bool filtering a complete match. Indices are target atoms in query-atom order; callback exceptions propagate unchanged. extra_final_check is an accepted alias.

property final_match: Optional[Callable[[Molecule, Sequence[int]], bool]]¶: Optional callback (target, atom_indices) -> bool filtering a complete match. Indices are target atoms in query-atom order; callback exceptions propagate unchanged. extra_final_check is an accepted alias.

property max_matches: int¶: Maximum number of substructure matches to return.

property max_recursive_matches: int¶: Maximum matches retained while evaluating recursive SMARTS predicates.

property num_threads: int¶: Requested worker count; interpretation of zero follows the corresponding operation.

property recursion_possible: bool¶: Whether recursive SMARTS predicates are evaluated.

property specified_stereo_query_matches_unspecified: bool¶: Whether a stereospecified query may match an unspecified target stereocenter.

property uniquify: bool¶: Whether matches using the same target atom set are deduplicated.

property use_chirality: bool¶: Whether stereochemistry participates in substructure matching.

property use_enhanced_stereo: bool¶: Whether enhanced stereo groups participate in matching.

property use_generic_matchers: bool¶: Whether generic query-group matching is enabled.

property use_query_query_matches: bool¶: Whether query predicates may be matched against target query predicates.

class cosmolkit.SupportMatrixEntry¶

Read-only feature/support declaration associated with a public operation.

Members (2)

feature: FeatureSpec¶: Owning compiled capability recorded for this declaration.

operation: Optional[MoleculeOpSpec]¶: Return the operation declaration associated with this support entry, when available.

exception cosmolkit.TautomerCatalogError¶: A tautomer transformation or scoring catalog could not be loaded or interpreted.

class cosmolkit.TautomerEnumeration¶

Ordered tautomer enumeration result with termination status, modified graph indices and canonical selection methods.

Members (11)

canonical_smiles() → list[str]¶: Canonical SMILES strings for retained tautomers in enumeration order.

canonical_tautomer() → Molecule¶: Return the highest-ranked canonical tautomer using the configured scoring rules; leave the source unchanged.

canonical_tautomer_with_params(params) → Molecule¶: Return the highest-ranked canonical tautomer using the configured scoring rules; leave the source unchanged. Uses the supplied configuration object.

entries() → list[tuple[str, Molecule]]¶: Return retained tautomer molecules in enumeration order.

get(index) → Optional[Molecule]¶: Return the retained tautomer at the supplied zero-based index.

is_empty() → bool¶: Return whether there are no stored entries.

iter() → Iterator[Molecule]¶: Return an iterator over entries in stored order.

len() → int¶: Return the number of stored entries.

modified_atoms() → list[int]¶: Indices of atoms participating in enumerated tautomer transformations.

modified_bonds() → list[int]¶: Indices of bonds participating in enumerated tautomer transformations.

status() → TautomerEnumerationStatus¶: Return why enumeration finished, including completion, limits or callback cancellation.

class cosmolkit.TautomerEnumerationStatus¶

Completion state of a tautomer-enumeration run.

Declared values: Completed, MaxTautomersReached, MaxTransformsReached, Canceled.

Members (4)

Canceled = TautomerEnumerationStatus.Canceled¶

Completed = TautomerEnumerationStatus.Completed¶

MaxTautomersReached = TautomerEnumerationStatus.MaxTautomersReached¶

MaxTransformsReached = TautomerEnumerationStatus.MaxTransformsReached¶

class cosmolkit.TautomerMoleculeView¶

Read-only molecule view valid during a tautomer callback. Use to_owned() for an independent Molecule that outlives the callback.

Members (12)

atom(index) → Optional[Atom]¶: Return the read-only atom at the zero-based graph index, or None if the index is out of range.

atom_degree(index) → Optional[int]¶: Degree from the validated detached adjacency, independent of valence errors.

atom_metadata() → list[AtomMetadata]¶: Canonical metadata query through its unique foundational owner.

atoms() → list[Atom]¶: Return atom rows in stored graph/hierarchy order.

bond(index) → Optional[Bond]¶: Return the read-only bond at the zero-based graph index, or None if the index is out of range.

bonds() → list[Bond]¶: Return bond rows in graph order.

num_atoms() → int¶: Number of atoms in the graph or selected structure.

num_bonds() → int¶: Number of bonds in the graph.

properties() → MoleculeProperties¶: Return a detached snapshot of the stored properties.

tautomer_score() → TautomerScore¶: Return ring, SMARTS-pattern and heteroatom-hydrogen score contributions for this tautomer.

to_owned() → TautomerMoleculeView¶: Return an owned snapshot that remains usable independently of this borrowed callback view.

to_smiles() → str¶: Return a SMILES string using the selected writer settings; this does not modify the molecule.

class cosmolkit.TautomerParams(*, max_tautomers=1000, max_transforms=1000, remove_sp3_stereo=True, remove_bond_stereo=True, remove_isotopic_hydrogens=True, reassign_stereo=True, callback=None, scorer=None, score_params=None)¶

Writable configuration for tautomer enumeration and canonical selection.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (27)

property callback: Optional[Any]¶: Optional tautomer progress callback; return False to stop enumeration and retain the corresponding status.

static from_transform_data(data) → TautomerParams¶: Construct tautomer enumeration parameters from explicitly supplied transformation rule text.

static from_transform_file(path) → TautomerParams¶: Load tautomer transformation rules from the supplied filesystem path.

property max_tautomers: int¶: Maximum number of distinct tautomers retained during enumeration.

property max_transforms: int¶: Maximum number of tautomer transformations attempted.

property reassign_stereo: bool¶: Whether stereochemistry is reassigned after tautomer transformations.

property remove_bond_stereo: bool¶: Whether stereo labels on potentially modified bonds are removed.

property remove_isotopic_hydrogens: bool¶: Whether isotope labels on hydrogens involved in tautomer transforms are removed.

property remove_sp3_stereo: bool¶: Whether stereo labels at potentially modified tetrahedral centers are removed.

property score_params: TautomerScoreParams¶: SMARTS scoring terms used when no custom scorer is supplied.

property scorer: Optional[Any]¶: Optional callback computing a tautomer ranking score from a read-only molecule view.

set_callback(value) → None¶: Replace the tautomer progress callback; callback failures propagate rather than being ignored.

set_max_tautomers(value) → None¶: Update this configuration setting. Maximum number of distinct tautomers retained during enumeration.

set_max_transforms(value) → None¶: Update this configuration setting. Maximum number of tautomer transformations attempted.

set_reassign_stereo(value) → None¶: Update this configuration setting. Whether stereochemistry is reassigned after tautomer transformations.

set_remove_bond_stereo(value) → None¶: Update this configuration setting. Whether stereo labels on potentially modified bonds are removed.

set_remove_isotopic_hydrogens(value) → None¶: Update this configuration setting. Whether isotope labels on hydrogens involved in tautomer transforms are removed.

set_remove_sp3_stereo(value) → None¶: Update this configuration setting. Whether stereo labels at potentially modified tetrahedral centers are removed.

set_scorer(value) → None¶: Replace the tautomer ranking callback.

transform_count() → int¶: Number of transformation rules loaded in the enumerator.

static v1() → TautomerParams¶: Return tautomer enumeration parameters using the v1 transform rule set.

with_max_tautomers(value) → TautomerParams¶: Return a new configuration with this setting. Maximum number of distinct tautomers retained during enumeration.

with_max_transforms(value) → TautomerParams¶: Return a new configuration with this setting. Maximum number of tautomer transformations attempted.

with_reassign_stereo(value) → TautomerParams¶: Return a new configuration with this setting. Whether stereochemistry is reassigned after tautomer transformations.

with_remove_bond_stereo(value) → TautomerParams¶: Return a new configuration with this setting. Whether stereo labels on potentially modified bonds are removed.

with_remove_isotopic_hydrogens(value) → TautomerParams¶: Return a new configuration with this setting. Whether isotope labels on hydrogens involved in tautomer transforms are removed.

with_remove_sp3_stereo(value) → TautomerParams¶: Return a new configuration with this setting. Whether stereo labels at potentially modified tetrahedral centers are removed.

class cosmolkit.TautomerProgress¶

Read-only tautomer callback progress view. Use to_owned() to retain a snapshot after the callback.

Members (8)

entries() → list[tuple[str, TautomerMoleculeView]]¶: Return retained entries in their stored order.

is_empty() → bool¶: Return whether there are no stored entries.

len() → int¶: Return the number of stored entries.

modified_atoms() → list[int]¶: Indices of atoms participating in enumerated tautomer transformations.

modified_bonds() → list[int]¶: Indices of bonds participating in enumerated tautomer transformations.

num_transforms() → int¶: Number of tautomer transformations attempted so far.

status() → TautomerEnumerationStatus¶: Return the current enumeration termination/progress status.

to_owned() → TautomerProgress¶: Return an owned snapshot that remains usable independently of this borrowed callback view.

exception cosmolkit.TautomerRunError¶: Tautomer enumeration, scoring or canonicalization failed.

class cosmolkit.TautomerScore¶

Tautomer ranking contributions for ring patterns, SMARTS terms and heteroatom hydrogens, plus their total.

Members (4)

hetero_hydrogen() → int¶: Heteroatom hydrogen contribution to the tautomer score.

ring() → int¶: Ring-pattern contribution to the tautomer score.

substructure() → int¶: SMARTS substructure contribution to the tautomer score.

total() → int¶: Total number of processed items.

class cosmolkit.TautomerScoreParams(terms=None)¶

Writable configuration for tautomer SMARTS scoring terms.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (1)

property terms: Optional[list[TautomerScoreTerm]]¶: Named SMARTS scoring terms used to rank tautomers.

class cosmolkit.TautomerScoreTerm(name, smarts, score)¶

Named SMARTS pattern and integer score used by tautomer ranking.

Members (4)

name() → str¶: Stored name of this value.

static new(name, smarts, score) → TautomerScoreTerm¶: Construct a TautomerScoreTerm value from the supplied inputs.

score() → int¶: Integer weight contributed by a matching tautomer scoring term.

smarts() → str¶: SMARTS text defining the query or scoring pattern.

class cosmolkit.TemplateAttachment¶

One ordered template-attachment entry carried by an atom.

target is a canonical COSMolKit atom-table id. Source row numbers and bookmarks must be resolved before this value is constructed.

Members (2)

label() → str¶: Label retained for this template attachment.

target() → int¶: Target identifier of this template attachment or SDF property list.

class cosmolkit.TemplateAttachmentOrder¶

Ordered template attachment state associated with one carrier atom.

Members (1)

entries() → list[TemplateAttachment]¶: Return retained entries in their stored order.

exception cosmolkit.TemplateAttachmentOrderError¶: Reaction-template attachment order metadata is invalid.

class cosmolkit.TetrahedralStereo(center, ligands)¶

Create new instance of TetrahedralStereo(center, ligands)

Members (2)

center¶: Alias for field number 0

ligands¶: Alias for field number 1

exception cosmolkit.TopologicalFingerprintError¶: Topological fingerprint generation failed for the supplied graph or options.

class cosmolkit.TopologicalFingerprintOutput¶

Typed provenance returned by the source atomBits and bitInfo outputs.

Members (2)

atom_bits: Optional[list[list[int]]]¶: Atom-indexed fingerprint bit participation, or request flag enabling that sink.

bit_info: Optional[dict[int, list[list[int]]]]¶: Map from fingerprint bit indices to contributing paths, or request flag enabling that sink.

class cosmolkit.TopologicalFingerprintOutputRequest(*, atom_bits=False, bit_info=False)¶

Flags selecting atom-to-bit participation and bit-path metadata for a topological fingerprint.

Members (2)

property atom_bits: bool¶: Atom-indexed fingerprint bit participation, or request flag enabling that sink.

property bit_info: bool¶: Map from fingerprint bit indices to contributing paths, or request flag enabling that sink.

class cosmolkit.TopologicalFingerprintParams(*, min_path=1, max_path=7, fp_size=2048, num_bits_per_feature=2, use_hs=True, target_density=0.0, min_size=128, branched_paths=True, use_bond_order=True, atom_invariants=None, from_atoms=None)¶

Writable configuration for RDKit topological path fingerprints.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (11)

property atom_invariants: Optional[list[int]]¶: Atom-indexed invariants used for path fingerprint hashing.

property branched_paths: bool¶: Whether branched subgraphs, not just linear paths, are included.

property fp_size: int¶: Number of bins/bits in the folded fingerprint.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property max_path: int¶: Maximum number of bonds in an enumerated fingerprint path.

property min_path: int¶: Minimum number of bonds in an enumerated fingerprint path.

property min_size: int¶: Minimum folded fingerprint width.

property num_bits_per_feature: int¶: Number of hashed bit positions generated per path feature.

property target_density: float¶: Target on-bit density for optional iterative fingerprint folding.

property use_bond_order: bool¶: Whether bond-order weights are included in the calculation.

property use_hs: bool¶: Whether explicit graph hydrogens participate in fingerprint paths.

class cosmolkit.TopologicalFingerprintResult¶

Topological bit fingerprint plus the requested atom/bit-path metadata.

Members (3)

atom_bits() → list[list[int]]¶: Atom-indexed fingerprint bit participation, or request flag enabling that sink.

bit_info() → dict[int, list[list[int]]]¶: Map from fingerprint bit indices to contributing paths, or request flag enabling that sink.

fingerprint() → Fingerprint¶: Return the bit fingerprint stored in this result.

class cosmolkit.TopologicalTorsionCallParams(*, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None, custom_bond_invariants=None, conformer_id=Ellipsis, use_legacy_stereo_perception=True)¶

Writable configuration for per-call topological-torsion atom selection and invariants.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (6)

property conformer_id: int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property custom_atom_invariants: Optional[list[int]]¶: Caller-supplied atom invariants in atom-index order.

property custom_bond_invariants: Optional[list[int]]¶: Caller-supplied bond invariants in bond-index order.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property ignore_atoms: Optional[list[int]]¶: Atom indices excluded from fingerprint feature enumeration.

property use_legacy_stereo_perception: bool¶: Whether legacy stereochemistry perception is used by the fingerprint operation.

class cosmolkit.TopologicalTorsionFingerprintGenerator(*, params=None, atom_invariants_generator=None)¶

Reusable topological-torsion fingerprint generator with a live settings view and bit/count, dense/sparse output methods.

Members (9)

counts(molecules, *, num_threads=1) → list[Optional[SparseCountFingerprint32]]¶: Generate folded count fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

fingerprints(molecules, *, num_threads=1) → FingerprintBatch¶: Generate fixed-width bit fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

static from_json(json) → TopologicalTorsionFingerprintGenerator¶: Construct a generator from serialized JSON settings; invalid JSON/options raise an error.

info_string() → str¶: Return a readable description of the generator settings.

static new(*, params=None, atom_invariants_generator=None) → TopologicalTorsionFingerprintGenerator¶: Construct a TopologicalTorsionFingerprintGenerator value from the supplied inputs.

settings() → TopologicalTorsionSettings¶: Return a live settings view; edits affect subsequent calls on this generator.

sparse_counts(molecules, *, num_threads=1) → list[Optional[SparseCountFingerprint]]¶: Generate sparse count fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

sparse_fingerprints(molecules, *, num_threads=1) → list[Optional[SparseBitFingerprint]]¶: Generate sparse bit fingerprints for the supplied molecules in input order using this generator and the per-call parameters.

to_json() → str¶: Return a JSON string containing this configuration.

class cosmolkit.TopologicalTorsionFingerprintParams(*, generator=None, from_atoms=None, ignore_atoms=None, custom_atom_invariants=None, custom_bond_invariants=None, conformer_id=Ellipsis, atom_invariants_generator=None, use_legacy_stereo_perception=True)¶

Writable configuration for topological-torsion generator selection and per-call invariants.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (8)

property atom_invariants_generator: Optional[AtomPairAtomInvariantsGenerator]¶: Atom-invariant generator used instead of the default invariant calculation.

property conformer_id: int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property custom_atom_invariants: Optional[list[int]]¶: Caller-supplied atom invariants in atom-index order.

property custom_bond_invariants: Optional[list[int]]¶: Caller-supplied bond invariants in bond-index order.

property from_atoms: Optional[list[int]]¶: Atom indices used as fingerprint starting centers; an omitted list uses all eligible atoms.

property generator: TopologicalTorsionParams¶: Fingerprint generator configuration; nested edits update the parent parameter object.

property ignore_atoms: Optional[list[int]]¶: Atom indices excluded from fingerprint feature enumeration.

property use_legacy_stereo_perception: bool¶: Whether legacy stereochemistry perception is used by the fingerprint operation.

class cosmolkit.TopologicalTorsionParams(*, torsion_atom_count=4, only_shortest_paths=False, include_chirality=False, count_simulation=True, fp_size=2048, bits_per_feature=1, count_bounds=None)¶

Writable configuration for topological-torsion fingerprint generation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (10)

property bits_per_feature: int¶: Number of hashed bit positions generated per feature.

property count_bounds: list[int]¶: Occurrence-count thresholds used by count simulation.

property count_simulation: bool¶: Whether occurrence counts are represented using threshold bits.

property fp_size: int¶: Number of bins/bits in the folded fingerprint.

property include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

info_string() → str¶: Return a readable description of the generator settings.

property only_shortest_paths: bool¶: Whether only torsion paths that are shortest between their endpoints are retained.

to_json() → str¶: Return a JSON string containing this configuration.

property torsion_atom_count: int¶: Number of atoms in each topological torsion path.

with_json(json) → TopologicalTorsionParams¶: Return an independent configuration updated from the supplied JSON text; invalid JSON/options raise an error.

exception cosmolkit.TopologicalTorsionPathScoreError¶: A topological-torsion atom path could not be encoded or scored.

exception cosmolkit.TopologicalTorsionReadError¶: Topological-torsion fingerprint preparation could not read the required molecular state.

class cosmolkit.TopologicalTorsionSettings¶

Live topological-torsion generator settings. Changes affect subsequent generator calls.

Members (15)

bits_per_feature: int¶: Number of hashed bit positions generated per feature.

count_bounds: list[int]¶: Occurrence-count thresholds used by count simulation.

count_simulation: bool¶: Whether occurrence counts are represented using threshold bits.

fp_size: int¶: Number of bins/bits in the folded fingerprint.

include_chirality: bool¶: Whether stereochemical information contributes to fingerprint features.

only_shortest_paths: bool¶: Whether only torsion paths that are shortest between their endpoints are retained.

params() → TopologicalTorsionParams¶: Return the parameter values associated with this result or settings view.

set_bits_per_feature(value) → None¶: Update the owning generator setting. Number of hashed bit positions generated per feature.

set_count_bounds(value) → None¶: Update the owning generator setting. Occurrence-count thresholds used by count simulation.

set_count_simulation(value) → None¶: Update the owning generator setting. Whether occurrence counts are represented using threshold bits.

set_fp_size(value) → None¶: Update the owning generator setting. Number of bins/bits in the folded fingerprint.

set_include_chirality(value) → None¶: Update the owning generator setting. Whether stereochemical information contributes to fingerprint features.

set_only_shortest_paths(value) → None¶: Update the owning generator setting. Whether only torsion paths that are shortest between their endpoints are retained.

set_torsion_atom_count(value) → None¶: Update the owning generator setting. Number of atoms in each topological torsion path.

torsion_atom_count: int¶: Number of atoms in each topological torsion path.

class cosmolkit.TopologyBlock¶

Detached atoms, bonds, adjacency and group annotations for explicit molecule construction.

Members (4)

atoms: list[Atom]¶: Return atom rows in stored graph/hierarchy order.

bonds: list[Bond]¶: Return bond rows in graph order.

stereo_groups: list[StereoGroup]¶: Enhanced stereochemistry groups referencing graph atoms.

substance_groups: list[SubstanceGroup]¶: Substance-group annotations referencing graph atoms and bonds.

exception cosmolkit.TransformError¶: A coordinate transform could not be applied to the requested coordinates.

class cosmolkit.UffConformerOptimizationParams(num_threads=1, max_iterations=1000, vdw_threshold=10.0, ignore_interfragment_interactions=True)¶

Writable configuration for multi-conformer UFF minimization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

property num_threads: int¶: Requested worker count; interpretation of zero follows the corresponding operation.

property vdw_threshold: float¶: UFF van der Waals interaction threshold used during force-field construction.

class cosmolkit.UffConformerOptimizationResult¶

Optimized molecule with per-conformer UFF statuses and final energies.

Members (2)

conformer_results() → list[UffConformerResult]¶: Per-conformer optimization reports in input conformer order.

molecule() → Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

class cosmolkit.UffConformerResult¶

One source-ordered conformer status and final UFF energy.

Members (4)

conformer_id() → int¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

energy() → float¶: Force-field potential energy in kcal/mol.

needs_more() → bool¶: Whether optimization stopped before convergence and may need additional iterations.

status_code() → int¶: Optimizer status code; zero indicates convergence.

class cosmolkit.UffEnergyGradient¶

UFF energy in kcal/mol and atom-ordered Cartesian energy derivatives.

Members (2)

energy() → float¶: Force-field potential energy in kcal/mol.

gradient() → list[float]¶: Return atom-ordered Cartesian energy derivatives in kcal/(mol angstrom); physical force is the negative gradient.

class cosmolkit.UffEvaluationParams(vdw_threshold=10.0, conformer_id=None, ignore_interfragment_interactions=True)¶

Writable configuration for UFF energy and gradient evaluation.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property vdw_threshold: float¶: UFF van der Waals interaction threshold used during force-field construction.

exception cosmolkit.UffForceFieldError¶

A UFF force-field evaluator could not be prepared from the molecule and parameters.

Members (2)

property kind: MolecularForceFieldErrorKind¶: The kind context recorded by this force-field error, or None when not applicable.

property requested: Optional[int]¶: The requested context recorded by this force-field error, or None when not applicable.

class cosmolkit.UffForceFieldParams(*, conformer_id=Ellipsis, vdw_threshold=Ellipsis, ignore_interfragment_interactions=Ellipsis)¶

Writable configuration for persistent UFF evaluator construction.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (3)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property vdw_threshold: float¶: UFF van der Waals interaction threshold used during force-field construction.

exception cosmolkit.UffOptimizationError¶

UFF optimization could not prepare or minimize the selected conformer.

Members (1)

kind() → UffOptimizationErrorKind¶: Return the kind context recorded by this error.

class cosmolkit.UffOptimizationErrorKind¶

Stable categories; unavailable geometry is not a guessed 2D fallback.

Members (2)

requested: Optional[int]¶: Requested conformer identifier in a missing-conformer error, when available.

variant: str¶: Named variant/category of the result.

class cosmolkit.UffOptimizationParams(max_iterations=1000, vdw_threshold=10.0, conformer_id=None, ignore_interfragment_interactions=True)¶

Writable configuration for single-conformer UFF minimization.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (4)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property ignore_interfragment_interactions: bool¶: Whether force-field interactions between disconnected fragments are omitted.

property max_iterations: int¶: Maximum iterations allowed by the optimizer or embedding algorithm.

property vdw_threshold: float¶: UFF van der Waals interaction threshold used during force-field construction.

class cosmolkit.UffOptimizationResult¶

Optimized molecule with UFF convergence status and final energy in kcal/mol.

Members (4)

energy() → float¶: Force-field potential energy in kcal/mol.

molecule() → Molecule¶: Return the molecule produced by this operation; the input molecule remains independently owned.

needs_more() → bool¶: Whether optimization stopped before convergence and may need additional iterations.

status_code() → int¶: Optimizer status code; zero indicates convergence.

exception cosmolkit.UffParameterError¶

UFF parameters are unavailable or invalid for the requested atom types.

Members (1)

kind() → UffParameterErrorKind¶: Return the kind context recorded by this error.

class cosmolkit.UffParameterErrorKind¶

Category of UFF parameterization failure: preparation, parameter-table lookup or atom typing.

Declared values: Preparation, ParameterTable, Typing.

Members (3)

ParameterTable = UffParameterErrorKind.ParameterTable¶

Preparation = UffParameterErrorKind.Preparation¶

Typing = UffParameterErrorKind.Typing¶

exception cosmolkit.UffParameterQueryError¶: A UFF interaction parameter could not be queried for the requested atoms.

exception cosmolkit.ValenceError¶: Valence assignment or validation failed for the molecular graph.

class cosmolkit.ValenceModel¶

Valence calculation model used when assigning atom valence.

Declared values: RdkitLike.

Members (1)

RdkitLike = ValenceModel.RdkitLike¶

class cosmolkit.ValenceParams(model=Ellipsis, strict=True)¶

Writable configuration for valence assignment.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property model: ValenceModel¶: ValenceModel selecting the valence assignment rules.

property strict: bool¶: Whether invalid valence assignments are rejected rather than retained.

exception cosmolkit.XyzReadError¶: XYZ coordinate text could not be parsed into a molecular coordinate graph.

exception cosmolkit.XyzWriteError¶: The selected molecular coordinates could not be serialized as XYZ.

class cosmolkit.XyzWriteParams(conformer_id=None, precision=6)¶

Writable configuration for XYZ text output.

Set fields in the constructor or assign them afterward. Omitted values use the documented constructor defaults; invalid assignments leave the previous value unchanged.

Members (2)

property conformer_id: Optional[int]¶: Stored 3D conformer identifier used by this operation; not its position in the conformer list.

property precision: int¶: Number of decimal places used for coordinate output.

cosmolkit.BATCH_ERROR_MODE_MAP¶: Read-only mapping from "raise" and "keep" to cosmolkit.BatchErrorMode values.

cosmolkit.RESIDUE_CODE_MAP¶: Read-only mapping from residue names to cosmolkit.ResidueCode values.

cosmolkit.RESIDUE_INFO_KIND_MAP¶: Read-only mapping from residue-kind names to cosmolkit.ResidueInfoKind values.

COSMolKit Docs

Loading documentation