neurosnap.io.sdf module

Parser and writer for SDF files.

This module provides Neurosnap-native parse_sdf() and save_sdf() helpers for reading and writing Structure, StructureEnsemble, and StructureStack objects.

The implementation intentionally follows RDKit’s own SDF reading and writing logic as closely as possible: molecules are parsed through RDKit suppliers, sanitized using RDKit defaults, and written back using RDKit’s SD writer.

neurosnap.io.sdf.parse_sdf(sdf, return_type='auto')

Parse an SDF file into Neurosnap structure containers.

Each SDF record is parsed with RDKit and converted into one Neurosnap Structure model. Multi-record SDF files therefore map naturally to a StructureEnsemble, and return_type="auto" will return a StructureStack when all records share identical atom annotations and bonds.

Because SDF is a small-molecule format, chain and residue hierarchy are not natively represented. Parsed structures therefore default to a single heterogen residue LIG in chain A unless RDKit monomer information is present on the atoms.

Parameters:

• sdf (Union[str, Path, IOBase]) – SDF filepath or open file handle.

• return_type (Literal['ensemble', 'stack', 'auto']) – Output container type. "ensemble" always returns a StructureEnsemble, "stack" requires stack-compatible models, and "auto" returns a StructureStack when possible or falls back to a StructureEnsemble.

Return type:

Union[StructureEnsemble, StructureStack]

Returns:

A StructureEnsemble or StructureStack depending on return_type and model compatibility.

neurosnap.io.sdf.save_sdf(structure, sdf)

Save a Neurosnap structure container as an SDF file.

Parameters:

• structure (Union[Structure, StructureEnsemble, StructureStack]) – Structure container to write.

• sdf (Union[str, Path, IOBase]) – Output filepath or open file handle.

Notes

SDF is a small-molecule format, so chain and residue hierarchy are flattened during output. Each model is written as a separate SDF record using RDKit’s own SD writer. Structure metadata is exported as SDF molecule properties when the values are scalar.