schrodinger.seam.io.sourceid module

Structure source identification for tracking where structures came from.

This module enables traceability by attaching source metadata to structures. File readers automatically set source IDs, so most users only need to retrieve them.

Usage

Get the source ID from a structure:

from schrodinger.seam.io.sourceid import get_source_id

source_id = get_source_id(st)
if source_id is not None:
    print(f"Structure came from: {source_id}")

Source IDs are sortable and comparable:

source_ids = [get_source_id(st) for st in structures]
for sid in sorted(source_ids):
    print(sid)

Source ID Types

  • FileSourceID: Structures read from files (filename, index, file hash)

  • StructureSourceID: Fallback based on structure content hash

Extending

Custom source ID types can be created by subclassing SourceID and setting the source_type class variable. Subclasses auto-register for decoding via get_source_id().

class schrodinger.seam.io.sourceid.SourceID

Bases: ABC

Abstract base class for structure source identifiers.

Each source ID represents where a structure came from and provides: - Methods to encode/decode to/from structure properties - Comparison and sorting support - Human-readable string representation

Subclasses must define a source_type class variable to register themselves for automatic decoding via get_source_id().

source_type: ClassVar[str] = ''
abstract property sort_key: tuple

Return tuple for sorting within this source type.

The full comparison key is (source_type, sort_key).

Returns:

Tuple of comparable values

class schrodinger.seam.io.sourceid.FileSourceID(filename: str, index: int, file_hash: str)

Bases: SourceID

Source ID for structures read from files.

Encodes file information including filename, index within file, and a hash of the file metadata (name, size, mtime).

source_type: ClassVar[str] = 'file'
__init__(filename: str, index: int, file_hash: str)

Initialize FileSourceID.

Parameters:

  • filename – Filename (basename only, not full path)

  • index – Index within file (1-based)

  • file_hash – Hash of file metadata

property sort_key: tuple

Return tuple for sorting within this source type.

The full comparison key is (source_type, sort_key).

Returns:

Tuple of comparable values

classmethod from_file(filepath: str, index: int) → FileSourceID

Create FileSourceID from file path and index.

Computes the file hash from the actual file.

Parameters:

  • filepath – Full path to file

  • index – Index within file (1-based)

Returns:

FileSourceID instance

class schrodinger.seam.io.sourceid.StructureSourceID(structure_hash: str)

Bases: SourceID

Source ID based on structure content itself.

Used as a fallback when no external source information is available. The hash is based on coordinates, elements, and connectivity.

source_type: ClassVar[str] = 'content'
__init__(structure_hash: str)

Initialize StructureSourceID.

Parameters:

structure_hash – Hash of structure content

property sort_key: tuple

Return tuple for sorting within this source type.

The full comparison key is (source_type, sort_key).

Returns:

Tuple of comparable values

classmethod from_structure(st: Structure) → StructureSourceID

Create StructureSourceID by computing hash from structure.

Parameters:

st – Structure to hash

Returns:

StructureSourceID instance

schrodinger.seam.io.sourceid.get_source_id(st: Structure) → Optional[SourceID]

Get source ID from a structure.

Reads the PROP_SOURCE_TYPE property to determine which SourceID subclass to use for decoding.

Parameters:

st – Structure to get source ID from

Returns:

SourceID instance or None if no source ID present

schrodinger.seam.io.sourceid.set_source_id(st: Structure, source_id: SourceID) → None

Set source ID on a structure.

Sets PROP_SOURCE_TYPE and delegates to the source ID’s encoding method.

Parameters:

  • st – Structure to annotate

  • source_id – SourceID to set