Entry Types

lcmd_db.Molecule	A molecule entry with typed properties and optional structure file.
lcmd_db.Reaction	A reaction entry with typed properties and participant molecules.
lcmd_db.Fragment	A molecular fragment entry with typed properties.
lcmd_db.Participant	A molecule's participation in a reaction step.
lcmd_db.ParticipantRole	Role of a molecule participating in a reaction.
lcmd_db.SubsetData	Container for data returned by a subset download.
lcmd_db.SubsetMetadata
lcmd_db.PropertyInfo

Type Parameters

Properties = TypeVar(Properties, bound=Mapping)

Type:    TypeVar

Invariant TypeVar bound to collections.abc.Mapping[str, object].

Properties type parameter for Molecule, Reaction, and Fragment. Defaults to dict[str, Value]; narrowed to a TypedDict with per-subset stubs.

FType = TypeVar(FType)

Type:    TypeVar

Invariant TypeVar.

Fragment type parameter for Fragment. Defaults to str | None; narrowed to a Literal with per-subset stubs.

lcmd_db.types.Value: TypeAlias = str | int | float | bool | None

Union of allowed property value types.

Molecule

class Molecule

Bases: Generic[~Properties]

A molecule entry with typed properties and optional structure file.

Access properties via subscript: mol.properties["energy"]. Per-subset type stubs narrow property types; see lcmd-db stubs sync.

Reaction

class Reaction

Bases: Generic[~Properties]

A reaction entry with typed properties and participant molecules.

Access properties via subscript: rxn.properties["barrier"]. Per-subset type stubs narrow property types; see lcmd-db stubs sync.

Fragment

class Fragment

Bases: Generic[~Properties, ~FType]

A molecular fragment entry with typed properties.

Access properties via subscript: frag.properties["charge"]. Per-subset type stubs narrow property types; see lcmd-db stubs sync.

Participants

class Participant

A molecule’s participation in a reaction step.

molecule

The participating molecule.

Type:

Molecule[dict[str, Value]]

role

Role in the reaction (reactant, product, catalyst, …).

Type:

ParticipantRole

step_from

Starting step index, if applicable.

Type:

float | None

step_to

Ending step index, if applicable.

Type:

float | None

label

Optional human-readable label.

Type:

str

class ParticipantRole

Bases: StrEnum

Role of a molecule participating in a reaction.

REACTANT = 'reactant'

PRODUCT = 'product'

CATALYST = 'catalyst'

CO_CATALYST = 'co_catalyst'

SUBSTRATE = 'substrate'

INTERMEDIATE = 'intermediate'

TRANSITION_STATE = 'transition_state'

SOLVENT = 'solvent'

ADDITIVE = 'additive'

Container

class SubsetData

Bases: Generic[~MProperties, ~RProperties, ~FProperties, ~FType, ~ATemplates]

Container for data returned by a subset download.

Generic over molecule, reaction, and fragment property types. When returned by a generated load_dataset overload the type parameters are bound to per-subset TypedDict classes so that data.as_dataset("molecules")[0].properties["energy"] is fully typed.

Without explicit type parameters, defaults to dict[str, Value] for all three (backward-compatible).

property dataframes: dict[str, polars.DataFrame]

Return a mapping of entity type names to their non-null DataFrames.

as_dataset(entity_type)

Build a typed Dataset for the given entity type.

Parameters:

entity_type (str) – One of "molecules", "reactions", or "fragments".

Return type:

Dataset[Molecule[MProperties]] | Dataset[Reaction[RProperties]] | Dataset[Fragment[FProperties, FType]]

Returns:

A MoleculeDataset, ReactionDataset, or FragmentDataset depending on the entity type.

Raises:

ValueError – If no data directory is available or the entity type is unknown.

Example:

molecules = data.as_dataset("molecules")   # MoleculeDataset
reactions = data.as_dataset("reactions")    # ReactionDataset

property assembly_templates: ATemplates

Assembly templates available for this subset.

Each template can assemble fragment SMILES into a molecule via template.assemble(core="...", sub1="...").

Metadata

class SubsetMetadata

Bases: BaseModel

class EntityMetadata

Bases: BaseModel

class PropertyInfo

Bases: BaseModel

Enums

class DataFormat

Bases: StrEnum

CSV = 'csv'

TSV = 'tsv'

XLSX = 'xlsx'

PARQUET = 'parquet'

JSON = 'json'

class EntityType

Bases: StrEnum

MOLECULES = 'molecules'

REACTIONS = 'reactions'

FRAGMENTS = 'fragments'

class PropertyDataType

Bases: StrEnum

FLOAT = 'float'

INTEGER = 'integer'

STRING = 'string'

BOOLEAN = 'boolean'