Perceive connectivity from Mayer bond orders (mol_from_dft)

[kfir4444]

Stack 3/5 — based on #952 (which is based on #951). This is the substantive PR of the stack.

What

mol, single_bond_mol = mol_from_dft(log_file_path, charge=None, multiplicity=None, bond_order_threshold=0.5)

in arc.species.converter. Both molecules preserve the log file's atom order and may hold several disconnected fragments (use .split()).

• mol — the perceived molecule with its bond orders.
• single_bond_mol — the same Mayer-derived connectivity with every bond set to order 1. Useful for connectivity-only isomorphism, and available even where no valid Lewis structure exists — e.g. a bridging H at a TS, which is genuinely bivalent in the graph.

Returns (None, None) when the log has no Mayer bond orders, so callers can fall back.

How

perceive_molecule_from_xyz() gains two optional arguments, both defaulting to today's behaviour:

• bonds replaces the distance-matrix step and is authoritative. The fragment count follows from it rather than from n_fragments, and _add_interfragment_bonds() is suppressed — otherwise genuinely separate fragments would be glued back together by the nearest-atom heuristic.
• bond_orders seeds multiple bonds through round_bond_order() (≥ 2.5 → 3, ≥ 1.5 → 2, else 1; thresholds sit midway between formal bond orders because computed orders of delocalized bonds fall between them). The seeded structure is kept only if is_mol_valid() accepts it; otherwise the existing generate_lewis_structure() A* search runs on the same connectivity.

So the computed bond orders are honoured wherever they are chemically consistent, and can never yield an invalid molecule.

Results on the fixtures

log	perceived
Orca, C4H5NO2	OCc1ccon1 — the correct isoxazole Kekulé structure, from Mayer orders of 1.56 (C=N), 1.60 (C=C) and 1.20 (C–C)
Gaussian, C8H14O2	C=C(C)COOCC(=C)C — both C=C preserved
Orca, formaldehyde	C=O (Mayer 2.14)
Orca, CH4 + OH TS	C.[OH] at the default threshold; at 0.3 the single-bond graph shows the H bridging C and O

The aromatic ring is the case worth noting: a distance-based criterion has no way to assign those bond orders.

Implementation note

converter.py must import the parser lazily inside the function body — arc/parser/parser.py imports str_to_xyz from converter, so a module-level import is circular. This is the same idiom str_to_xyz itself already uses.

Testing

pytest arc/species/ — 303 passed. New tests cover mol_from_dft against all four logs above, atom-order preservation, the single-bond copy having an identical edge set with all orders 1, and perceive_molecule_from_xyz(bonds=...) overriding the distance heuristic.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.60%. Comparing base (6146de7) to head (27c685d).

Additional details and impacted files

@@                       Coverage Diff                       @@
##           mayer_bond_orders_g16_route     #953      +/-   ##
===============================================================
- Coverage                        63.62%   63.60%   -0.02%     
===============================================================
  Files                              114      114              
  Lines                            38443    38505      +62     
  Branches                         10052    10071      +19     
===============================================================
+ Hits                             24461    24493      +32     
- Misses                           11061    11076      +15     
- Partials                          2921     2936      +15     

Flag	Coverage Δ
functionaltests	63.60% <ø> (-0.02%)	⬇️
unittests	63.60% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.