API Reference

class cosmolkit.Atom

Read-only atom feature record returned by Molecule.atoms().

The methods on this object expose common atom properties such as atomic number, formal charge, aromaticity, chiral tag, hydrogen counts, and valence values.

class cosmolkit.BatchError

A per-record batch processing error.

Batch methods can keep invalid records when errors="keep" is used. In that case, MoleculeBatch.errors() returns BatchError objects describing the input index, processing stage, error type, and message.

as_dict()

Return the error as key-value pairs.

error_type()

Return a short machine-readable error category.

index()

Return the zero-based input index that produced the error.

input()

Return the original input value when available.

message()

Return the human-readable error message.

stage()

Return the processing stage where the error occurred.

class cosmolkit.BatchExportReport

Summary returned by batch export methods.

The report records how many inputs were processed successfully and includes structured errors for records that could not be exported.

errors()

Return structured errors for failed records.

failed()

Return the number of records that failed during export.

success()

Return the number of records exported successfully.

total()

Return the total number of records considered for export.

exception cosmolkit.BatchValidationError
class cosmolkit.Bond

Read-only bond feature record returned by Molecule.bonds().

The methods on this object expose atom endpoints, bond type, direction, stereo labels, stereo atom indices, and aromaticity.

class cosmolkit.Molecule

A molecule value.

Molecule stores atoms, bonds, stereochemistry, and optional coordinate data. Transformation methods such as with_hydrogens(), without_hydrogens(), with_kekulized_bonds(), and with_2d_coords() return new molecule values. The original molecule is left unchanged.

Examples

Create molecules with Molecule.from_smiles(), transform them with value methods such as with_2d_coords(), then export strings, arrays, or depiction files.

atoms()

Return read-only atom feature records.

bonds()

Return read-only bond feature records.

coords_2d()

Return 2D coordinates as a NumPy array with shape (num_atoms, 3).

The z column is zero-filled.

coords_3d(conformer_index=0)

Return 3D coordinates as a NumPy array with shape (num_atoms, 3).

dg_bounds_matrix()

Return the distance-geometry bounds matrix as a NumPy array.

edit()

Create an explicit edit context for this molecule.

The edit context is useful when several changes should be staged and committed as one new molecule value.

find_chiral_centers(include_unassigned=True)

Return chiral center labels.

Parameters:

include_unassigned (bool, default True) – Include atoms with unspecified tetrahedral chirality.

classmethod from_rdkit(rdmol, sanitize=None)

Create a molecule from an RDKit molecule object.

Parameters:

  • rdmol (object) – An object compatible with RDKit’s molecule API.

  • sanitize (bool, optional) – Optional molecule preparation flag.

Returns:

COSMolKit molecule copied from the input object.

Return type:

Molecule

classmethod from_smiles(smiles, sanitize=None)

Create a molecule from a SMILES string.

Parameters:

  • smiles (str) – Input SMILES string.

  • sanitize (bool, optional) – Optional molecule preparation flag. COSMolKit applies the available preparation behavior during construction.

Returns:

Parsed molecule.

Return type:

Molecule

Examples

Use Molecule.from_smiles("CCO") to create a molecule and mol.to_smiles() to write it back.

has_2d_coords()

Return whether the molecule has 2D coordinates.

num_atoms()

Return the number of atoms.

num_bonds()

Return the number of bonds.

num_conformers()

Return the number of stored 3D conformers.

classmethod read_sdf(path, sanitize=None, coordinate_dim=None)

Read the first molecule record from an SDF file.

Parameters:

  • path (str) – SDF file path.

  • sanitize (bool, optional) – Optional molecule preparation flag.

  • coordinate_dim ({"auto", "2d", "3d"}, optional) – How coordinate columns should be interpreted.

classmethod read_sdf_record_from_str(sdf_text, sanitize=None, coordinate_dim=None)

Read one molecule from an SDF record string.

classmethod read_sdf_records_from_str(sdf_text, sanitize=None, coordinate_dim=None)

Read all molecule records from an SDF string.

tetrahedral_stereo()

Return ordered tetrahedral stereo ligand records.

Each record is (center_atom_index, ordered_ligands). Implicit hydrogen is represented as None.

to_sdf_string(format=None)

Return the molecule as an SDF record string.

to_smiles(isomeric_smiles=True)

Return a SMILES string.

Parameters:

isomeric_smiles (bool, default True) – Include stereochemical and isotopic information when available.

to_svg(width=300, height=300)

Render the molecule to an SVG string.

with_2d_coords()

Return a new molecule with 2D coordinates.

with_hydrogens()

Return a new molecule with explicit hydrogens added.

with_kekulized_bonds(sanitize=None)

Return a new molecule with aromatic bonds converted to an explicit Kekule form.

without_hydrogens()

Return a new molecule with explicit hydrogens removed.

write_png(path, width=300, height=300)

Write a PNG depiction to a file.

write_sdf(path, format=None)

Write the molecule as an SDF file.

write_sdf_to_directory(directory, file_name=None, format=None)

Write the molecule to an SDF file inside a directory.

Returns:

The output path.

Return type:

str

write_svg(path, width=300, height=300)

Write an SVG depiction to a file.

class cosmolkit.MoleculeBatch

An ordered collection of molecules for batch workflows.

MoleculeBatch keeps input order and supports construction, transformation, filtering, rendering, and SDF export across many molecules. Methods that transform molecules return a new batch.

Parameters such as errors control invalid-record handling:

  • "raise" raises an exception when any record fails.

  • "keep" keeps failed records and exposes them through errors().

  • "skip" omits failed records from the returned batch or export.

Examples

Construct a batch with MoleculeBatch.from_smiles_list(), choose an errors mode for invalid records, and pass n_jobs to methods that expose parallel execution.

add_hydrogens(errors=None, n_jobs=None)

Return a new batch with explicit hydrogens added to each valid molecule.

compute_2d_coords(errors=None, n_jobs=None)

Return a new batch with 2D coordinates computed for each valid molecule.

dg_bounds_matrix_list(n_jobs=None)

Return distance-geometry bounds matrices for all valid records.

errors()

Return structured errors collected for invalid records.

filter_valid()

Return a batch containing only valid molecules.

classmethod from_sdf_record_strings(sdf_records, coordinate_dim=None, errors=None, n_jobs=None)

Create a batch from SDF record strings.

Parameters:

  • sdf_records (list[str]) – Individual SDF records.

  • coordinate_dim ({"auto", "2d", "3d"}, optional) – How coordinate columns should be interpreted.

  • errors ({"raise", "keep", "skip"}, optional) – Invalid-record handling mode. The default is "raise".

  • n_jobs (int, optional) – Number of worker threads to use.

classmethod from_smiles_list(smiles, sanitize=None, errors=None, n_jobs=None)

Create a batch from a list of SMILES strings.

Parameters:

  • smiles (list[str]) – Input SMILES strings.

  • sanitize (bool, optional) – Optional molecule preparation flag. COSMolKit applies the available preparation behavior during construction.

  • errors ({"raise", "keep", "skip"}, optional) – Invalid-record handling mode. The default is "raise".

  • n_jobs (int, optional) – Number of worker threads to use. None uses the default scheduler.

Returns:

A batch preserving the input order for valid and kept records.

Return type:

MoleculeBatch

invalid_count()

Return the number of invalid records.

invalid_mask()

Return a boolean mask indicating which records are invalid.

remove_hydrogens(errors=None, n_jobs=None)

Return a new batch with explicit hydrogens removed from each valid molecule.

sanitize(strict=None, errors=None, n_jobs=None)

Return a sanitized batch.

Parameters:

  • strict (bool, optional) – Optional strictness flag for available validation steps.

  • errors ({"raise", "keep", "skip"}, optional) – Invalid-record handling mode.

  • n_jobs (int, optional) – Number of worker threads to use.

to_images(out_dir, format=None, size=None, n_jobs=None, errors=None, report_path=None)

Write molecule depictions to a directory.

Parameters:

  • out_dir (str) – Output directory.

  • format ({"png", "svg"}, optional) – Image format. The default is "png".

  • size (tuple[int, int], optional) – Output image size as (width, height).

  • n_jobs (int, optional) – Number of worker threads to use.

  • errors ({"raise", "keep", "skip"}, optional) – Export error handling mode.

  • report_path (str, optional) – Write a JSON or CSV error report.

Returns:

Export summary.

Return type:

BatchExportReport

to_sdf(path, format=None, errors=None, n_jobs=None, report_path=None)

Write valid molecules to an SDF file.

Parameters:

  • path (str) – Output SDF path.

  • format ({"auto", "v2000", "v3000"}, optional) – SDF output format.

  • errors ({"raise", "keep", "skip"}, optional) – Export error handling mode.

  • n_jobs (int, optional) – Number of worker threads to use.

  • report_path (str, optional) – Write a JSON or CSV error report.

to_smiles_list(isomeric_smiles=True, canonical=True, kekule=False, clean_stereo=True, all_bonds_explicit=False, all_hs_explicit=False, include_dative_bonds=True, ignore_atom_map_numbers=False, rooted_at_atom=None, n_jobs=None)

Return one SMILES string per record.

Invalid records are returned as None when they are kept in the batch.

Parameters:

  • isomeric_smiles (bool, default True) – Include stereochemical and isotopic information when available.

  • canonical (bool, default True) – Return canonical SMILES when enabled.

  • kekule (bool, default False) – Write aromatic systems in Kekule form.

  • clean_stereo (bool, default True) – Normalize stereo output where possible.

  • all_bonds_explicit (bool, default False) – Write explicit bond symbols.

  • all_hs_explicit (bool, default False) – Write explicit hydrogens.

  • include_dative_bonds (bool, default True) – Include dative bond notation.

  • ignore_atom_map_numbers (bool, default False) – Omit atom map numbers from canonical decisions.

  • rooted_at_atom (int, optional) – Start traversal from a selected atom index.

  • n_jobs (int, optional) – Number of worker threads to use.

to_svg_list(width=300, height=300, n_jobs=None)

Render each valid molecule to an SVG string.

valid_count()

Return the number of valid records.

valid_mask()

Return a boolean mask indicating which records are valid.

with_kekulized_bonds(sanitize=None, errors=None, n_jobs=None)

Return a new batch with aromatic bonds converted to an explicit Kekule form.

class cosmolkit.MoleculeEdit

An explicit molecule editing context.

Use Molecule.edit() to create an editor, apply changes, and call commit() to receive a new Molecule.

Examples

Create an editor with mol.edit(), apply atom and bond changes, then call commit() to produce a new Molecule.

add_atom(element)

Add an atom by element symbol and return its atom index.

add_bond(begin, end, order)

Add a bond between two atom indices.

Parameters:

  • begin (int) – Begin atom index.

  • end (int) – End atom index.

  • order ({"single", "double", "triple", "aromatic", "dative", "unspecified"}) – Bond order.

commit(sanitize=None)

Commit staged edits and return a new molecule.

set_atom_charge(atom_index, charge)

Set an atom formal charge.