Isomer Detection Analysis

Detect molecular formulas and isomer groups from structure connectivity.

This module identifies molecules, groups them by formula, and derives isomer partitions from single-structure connectivity representations. It is scoped to graph-based molecule/isomer detection and does not perform time-resolved molecular tracking.

Usage context

• Structure decomposition: Enumerate molecules present in one geometry.
• Isomer counting: Split molecules into isomer classes per formula.
• Topology summaries: Export formula/isomer tables for structural reports.

Request: MoleculeIsomerDetectionRequest

Request payload for single-structure molecule/isomer detection.

This request controls component-size thresholds and optional element/motif inclusion or exclusion filters applied before formula/isomer grouping.

Fields

Field	Type	Default	Help	Choices
min_atoms_per_molecule	int	1	Minimum component size retained as a molecule.
include_any_elements	tuple[str, ...] \| None		Keep molecules containing at least one of these elements.
include_all_elements	tuple[str, ...] \| None		Keep molecules containing all listed elements.
exclude_any_elements	tuple[str, ...] \| None		Exclude molecules containing any listed element.
include_motifs	tuple[str, ...] \| None		Keep molecules matching at least one motif rule (e.g. 'SFx' or 'only:F,S;S==1;F>=1').
exclude_motifs	tuple[str, ...] \| None		Exclude molecules matching any motif rule (e.g. 'SFx' or 'only:F,S;S==1;F>=1').

Examples

request = MoleculeIsomerDetectionRequest(
    min_atoms_per_molecule=2,
    include_motifs=("SFx",),
    exclude_any_elements=("H",),
)

The request keeps sulfur/fluorine motif matches while excluding hydrogen-containing molecules.

Task: MoleculeIsomerDetectionTask

Connected-components molecule detection + formula + graph isomer grouping.

Method: recommended_presentations(_result: MoleculeIsomerDetectionResult, _payload: dict[str, Any])

Recommend the default isomer summary table presentation.

The isomer table is the canonical human-readable summary and is exposed as the default view for this analyzer.

Works on Analyzer task output for molecule_isomer_detection.

Parameters

Name	Type	Description
_result	MoleculeIsomerDetectionResult	Typed analyzer result instance (unused by current logic).
_payload	dict[str, Any]	Serialized payload (unused for this fixed recommendation).

Returns

Type	Description
list[PresentationSpec]	Single table presentation specification.

Examples

specs = MoleculeIsomerDetectionTask.recommended_presentations(_result, {})

The returned list contains one table presentation spec.

Method: run(data: GeometryData, request: MoleculeIsomerDetectionRequest, reporter=None)

Run molecule detection, formula grouping, and isomer partitioning.

Builds molecular connected components from geometry connectivity, applies request filters, groups molecules by formula, and splits each formula into graph-isomorphic isomer classes.

Works on GeometryData representing one structure with coordinates and connectivity.

Parameters

Name	Type	Description
data	GeometryData	Parsed geometry model containing atom and connectivity tables.
request	MoleculeIsomerDetectionRequest	Component threshold and element/motif filter configuration.
reporter	Any, optional	Progress callback accepted by analyzer tasks.

Returns

Type	Description
MoleculeIsomerDetectionResult	Result containing formula, isomer, and molecule summary tables.

Examples

result = MoleculeIsomerDetectionTask().run(
    data,
    MoleculeIsomerDetectionRequest(min_atoms_per_molecule=2),
)

result.isomer_table contains grouped isomer classes for retained molecules.

Result: MoleculeIsomerDetectionResult

Result payload for molecule and isomer detection outputs.

The analyzer returns three related summary tables over one geometry: formula-level counts, isomer-level groupings, and per-molecule assignments.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
formula_table	pd.DataFrame
isomer_table	pd.DataFrame
molecule_table	pd.DataFrame
request	MoleculeIsomerDetectionRequest

Examples

isomer_row = {
    "formula": "C2H6O1",
    "isomer_id": 1,
    "molecule_count": 2,
    "atom_count": 9,
    "representative_molecule_id": 3,
}

The sample row summarizes one detected isomer class for a formula.