Molecule I/O & Converters

Conversion utilities for molecular structure file formats.

Format parsing and writing are backed by the native libqdx Rust library.

rush.convert.from_json(json_content: Sequence[PathLike[str]] | dict) → TRC[source]
rush.convert.from_json(json_content: PathLike[str] | list[dict]) → list[TRC]

Load TRC structures from JSON.

Parameters:

json_content (Sequence[PathLike[str]] | dict | PathLike[str] | list[dict]) – JSON file path, dict, list of dicts, or (topology, residues, chains) paths

Returns:

TRC structure or list of TRC structures

Return type:

TRC | list[TRC]

rush.convert.from_mmcif(mmcif_content)[source]

Parse mmCIF file contents into TRC structures.

Parameters:

mmcif_content (str) – Raw mmCIF file text.

Returns:

A single TRC if the file contains one model, otherwise a list of TRCs.

Return type:

TRC | list[TRC]

rush.convert.from_pdb(pdb_content)[source]

Parse PDB file content into TRC structures.

Parameters:

pdb_content (str) – Raw PDB file text.

Returns:

A single TRC if the file contains one model, otherwise a list of TRCs.

Return type:

TRC | list[TRC]

rush.convert.from_sdf(sdf_content)[source]

Parse SDF file contents into TRC structures.

Parameters:

sdf_content (str) – Raw SDF / MOL file text.

Returns:

A single TRC if the file contains one molecule, otherwise a list of TRCs.

Return type:

TRC | list[TRC]

rush.convert.load_structure(file_path)[source]

Load a molecular structure from a file.

Supported formats: PDB, mmCIF (.cif / .mmcif), SDF, and TRC JSON. The format is determined by extension; when the extension is unrecognised the content is inspected heuristically.

Parameters:

file_path (str | Path) – Path to the structure file.

Returns:

A single TRC when the file contains one model/molecule, otherwise a list of TRCs.

Return type:

TRC | list[TRC]

rush.convert.merge_trcs(*trcs, output_file=None, skip_validation=False)[source]

Merge one or more TRC objects (or file paths) into a single TRC.

Atom, residue, and chain indices are renumbered so that the merged structure has unique indices throughout.

Parameters:

  • trcs (TRC | str | Path | Sequence[TRC | str | Path]) – TRC objects or file paths. A single list/tuple is treated as the full set of inputs.

  • output_file (str | Path | None) – Optional path to write the merged TRC as JSON.

  • skip_validation (bool) – If True, skip trc.check() on the result.

Returns:

The merged TRC object.

Raises:

  • ValueError – If no inputs are provided or validation fails.

  • FileNotFoundError – If a file path does not exist.

Return type:

TRC

rush.convert.save_structure(trcs, file_path, format=None)[source]

Save TRC structures to a file.

Parameters:

  • trcs (TRC | list[TRC]) – TRC structure or list of TRC structures to write.

  • file_path (str | Path) – Output file path.

  • format (str | None) – Output format ('pdb' or 'json'). When None the format is inferred from the file extension.

Raises:

ValueError – If the format cannot be inferred or is unsupported.

rush.convert.to_dict(trcs)[source]

Convert TRC structures to JSON-serializable dicts.

Parameters:

trcs (TRC | list[TRC]) – A single TRC or a list of TRC structures.

Returns:

A dict (if a single TRC was given) or a list of dicts, each containing topology, residues, and chains keys.

Return type:

dict | list[dict]

rush.convert.to_pdb(trc)[source]

Convert a TRC structure to PDB format text.

Parameters:

trc (TRC) – TRC structure to serialise.

Returns:

PDB-formatted string (includes trailing END record).

Return type:

str