# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """Chemical structures tied to words: SMILES and SMARTS scanning, identities and rules (paperspec.structures).""" import copy import hashlib import pytest from hypothesis import given, settings, strategies as st from conftest import read_jsonl, vector_cases from helpers_lib2 import PROPS, RECORDS, accepted_by_schema, rule_chapters from paperspec import structures CASES = vector_cases("structures") SCANS = [c for c in CASES if c["op"] == "scan"] IDENTITIES = [c for c in CASES if c["op"] == "identity"] PROBLEMS = [c for c in CASES if c["op"] == "problems"] RULES = ("layer.structure.value", "layer.structure.identity", "layer.structure.term") CHEMISTRY = read_jsonl(RECORDS / "chemistry" / "annotations.jsonl") SMARTS_TERMS = next(c for c in PROBLEMS if c["id"] == "valid-a-smarts-with-terms")[ "annotation" ] SMILES_TERMS = next(c for c in PROBLEMS if c["id"] == "valid-a-smiles-with-terms")[ "annotation" ] def scanned(text, smarts=False): """The atoms and sorted bonds `scan` reads from `text`, or None when it refuses the text.""" try: count, bonds = structures.scan(text, smarts=smarts) except ValueError: return None return {"atoms": count, "bonds": [list(b) for b in sorted(bonds)]} def edited(annotation, **body): """A copy of `annotation` whose body has the given fields replaced; None removes a field.""" out = copy.deepcopy(annotation) for key, value in body.items(): if value is None: out["body"].pop(key, None) else: out["body"][key] = value return out def rules_of(annotation): """The rules `problems` reports for `annotation`, in order.""" return [x["rule"] for x in structures.problems(annotation)] # --- scanning ------------------------------------------------------------------------------------------------ @pytest.mark.parametrize("case", SCANS, ids=lambda c: c["id"]) def test_scan_vectors(case): assert scanned(case["text"], smarts=case["format"] == "smarts") == case["expect"] @pytest.mark.parametrize( ("text", "expect"), [ ("C=1CC=1", {"atoms": 3, "bonds": [[0, 1], [0, 2], [1, 2]]}), ( "C1CC1C1CC1", { "atoms": 6, "bonds": [[0, 1], [0, 2], [1, 2], [2, 3], [3, 4], [3, 5], [4, 5]], }, ), ("C1(CC1)C", {"atoms": 4, "bonds": [[0, 1], [0, 2], [0, 3], [1, 2]]}), ("C(C)(C)C", {"atoms": 4, "bonds": [[0, 1], [0, 2], [0, 3]]}), ("C.C.C", {"atoms": 3, "bonds": []}), ("[13CH3][2H]", {"atoms": 2, "bonds": [[0, 1]]}), ("[Fe+2]", {"atoms": 1, "bonds": []}), ("[C@H](F)(Cl)Br", {"atoms": 4, "bonds": [[0, 1], [0, 2], [0, 3]]}), ( "CC(=O)OC(=O)C", {"atoms": 7, "bonds": [[0, 1], [1, 2], [1, 3], [3, 4], [4, 5], [4, 6]]}, ), ("C#N", {"atoms": 2, "bonds": [[0, 1]]}), ("[[N]]", {"atoms": 1, "bonds": []}), ], ids=[ "ring-with-explicit-bond", "ring-numbers-reused", "ring-opened-before-a-branch", "branches-after-branches", "dots-separate-components", "isotopes", "charged-metal", "stereo-centre", "anhydride", "triple-bond", "nested-brackets", ], ) def test_scan_reads_further_smiles(text, expect): assert scanned(text) == expect @pytest.mark.parametrize( ("text", "expect"), [ ("[C,N]C", {"atoms": 2, "bonds": [[0, 1]]}), ("C!C", {"atoms": 2, "bonds": [[0, 1]]}), ("[!C;R]~[#7]", {"atoms": 2, "bonds": [[0, 1]]}), ("A@a", {"atoms": 2, "bonds": [[0, 1]]}), ("C&C", {"atoms": 2, "bonds": [[0, 1]]}), ], ) def test_scan_reads_queries_only_in_smarts(text, expect): assert scanned(text, smarts=True) == expect assert scanned(text, smarts=False) is None def test_ring_closures_may_follow_a_bond_symbol_and_clear_the_pending_bond(): assert scanned("C1=CC=C1") == { "atoms": 4, "bonds": [[0, 1], [0, 3], [1, 2], [2, 3]], } @pytest.mark.parametrize( ("text", "message"), [ ("", "empty"), (" ", "empty"), (" C", "spaces at its ends"), ("C\n", "spaces at its ends"), ("C[N", "unclosed \\[ at 1"), ("C[]", "empty bracket atom at 1"), ("[C,N]", "a query inside the bracket atom at 0: that is SMARTS"), ("[$(C)]", "that is SMARTS"), ("=C", "a bond with no atom before it at 0"), ("C.=C", "a bond with no atom before it at 2"), ("1CC1", "a ring closure with no atom before it"), ("%10C", "a ring closure with no atom before it"), ("(C)C", "a branch with no atom before it at 0"), ("C=(C)C", "a bond before \\( at 2: write it inside the branch"), ("C)", "unmatched \\) at 1"), ("C(C=)C", "a bond with no atom after it at 4"), ("C()C", "an empty branch before 2"), ("C(C", "unclosed \\("), ("C=.C", "a bond with no atom after it at 2"), ("C1CC", "ring closure 1 is never closed"), ("C1C2C", "ring closure 1, 2 is never closed"), ("CC=", "a bond with no atom after it"), ("C?C", "'\\?' is not part of a SMILES at 1"), ("C C", "' ' is not part of a SMILES at 1"), ], ) def test_scan_refuses_text_and_says_why(text, message): with pytest.raises(ValueError, match=message): structures.scan(text) def test_scan_names_the_dialect_in_a_stray_character_message(): with pytest.raises(ValueError, match="is not part of a SMARTS at 1"): structures.scan("C?", smarts=True) with pytest.raises(ValueError, match="not part of a SMILES"): structures.scan("C?", smarts=False) def test_text_that_is_only_dots_has_no_atoms(): with pytest.raises(ValueError, match="no atoms"): structures.scan("..") def test_a_percent_without_two_digits_says_so(): with pytest.raises(ValueError, match="% needs two digits at 1"): structures.scan("C%1") @pytest.mark.parametrize("text", ["C%", "C%1", "C%1C", "C%a1", "C%-1"]) def test_a_ring_number_written_with_a_percent_needs_two_digits(text): assert scanned(text) is None @given(st.integers(1, 40)) @PROPS def test_a_chain_has_a_bond_between_neighbours(n): got = scanned("C" * n) assert got == {"atoms": n, "bonds": [[i, i + 1] for i in range(n - 1)]} @given(st.integers(3, 40)) @PROPS def test_a_ring_closes_its_last_atom_on_its_first(n): got = scanned("C1" + "C" * (n - 2) + "C1") assert got["atoms"] == n assert [0, n - 1] in got["bonds"] assert len(got["bonds"]) == n @given(st.integers(0, 6), st.integers(1, 5)) @PROPS def test_branches_attach_to_the_atom_before_them(branches, length): got = scanned("C" + ("(" + "C" * length + ")") * branches) assert got["atoms"] == 1 + branches * length attached = [b for b in got["bonds"] if b[0] == 0] assert len(attached) == branches TEXT = st.text(alphabet="CNOcnoBrCl[]()=#-+@H:*~,;&!$/\\.%0123456789 aA", max_size=24) @given(TEXT, st.booleans()) @settings(PROPS, max_examples=300) def test_scan_either_refuses_with_a_value_error_or_returns_consistent_bonds( text, smarts ): try: count, bonds = structures.scan(text, smarts=smarts) except ValueError: return assert count >= 1 assert all(0 <= i < j < count for i, j in bonds) @given(TEXT) @settings(PROPS, max_examples=300) def test_whatever_smiles_scans_scans_the_same_as_smarts(text): plain = scanned(text, smarts=False) if plain is not None: assert scanned(text, smarts=True) == plain # --- identities --------------------------------------------------------------------------------------------------- @pytest.mark.parametrize("case", IDENTITIES, ids=lambda c: c["id"]) def test_identity_vectors(case): assert ( structures.identity(case["format"], case["text"], case["inchikey"]) == case["expect"] ) @pytest.mark.parametrize("fmt", ["smiles", "smarts"]) def test_without_an_inchikey_the_identity_is_the_format_and_a_hash_of_the_text(fmt): digest = hashlib.sha256(b"CCO").hexdigest()[:12] assert structures.identity(fmt, "CCO") == f"{fmt}:{digest}" assert structures.identity(fmt, "CCO", "") == f"{fmt}:{digest}" assert structures.identity(fmt, "CCO", None) == f"{fmt}:{digest}" def test_only_a_smiles_takes_an_inchikey(): key = "OTMSDBZUPAUEDD-UHFFFAOYSA-N" assert structures.identity("smiles", "CC", key) == key assert structures.identity("smarts", "CC", key).startswith("smarts:") def test_two_spellings_of_one_molecule_have_two_text_identities(): assert structures.identity("smiles", "OCC") != structures.identity("smiles", "CCO") def test_the_formats_and_their_media_types_are_inverse(): assert structures.MEDIA == { "smiles": "chemical/x-daylight-smiles", "smarts": "chemical/x-daylight-smarts", } assert {structures.FORMATS[m]: m for m in structures.FORMATS} == structures.MEDIA # --- rules --------------------------------------------------------------------------------------------------------- @pytest.mark.parametrize("rule", RULES) def test_the_rules_are_registered_in_the_layers_chapter(rule): assert rule_chapters()[rule] == "spec/18-layers.md" @pytest.mark.parametrize("case", PROBLEMS, ids=lambda c: c["id"]) def test_problems_vectors(case): got = structures.problems(case["annotation"]) assert got == case["expect"] assert accepted_by_schema(case["annotation"]) is case["schema"] assert {x["rule"] for x in got} <= set(rule_chapters()) @pytest.mark.parametrize("case", PROBLEMS, ids=lambda c: c["id"]) def test_a_vector_is_named_for_the_rule_it_breaks(case): stem = case["id"].split("-", 1)[0] rules = {x["rule"] for x in case["expect"]} if stem == "valid": assert rules == set() else: assert "layer.structure." + stem in rules def test_every_rule_is_broken_by_some_vector(): assert {x["rule"] for c in PROBLEMS for x in c["expect"]} == set(RULES) @pytest.mark.parametrize("annotation", CHEMISTRY, ids=lambda a: a["body"]["label"]) def test_the_chemistry_layer_breaks_no_rule(annotation): assert structures.problems(annotation) == [] assert annotation["body"]["kind"] == "structure" def test_an_annotation_of_another_kind_is_refused(): with pytest.raises(ValueError, match="not a structure annotation"): structures.problems({"body": {"kind": "comment"}}) with pytest.raises(ValueError, match="not a structure annotation"): structures.problems({"body": {}}) def test_a_missing_format_breaks_the_value_rule_and_says_which_formats_exist(): got = structures.problems(edited(SMILES_TERMS, format=None)) assert [x["rule"] for x in got] == ["layer.structure.value"] assert "chemical/x-daylight-smarts" in got[0]["message"] def test_a_scan_failure_is_reported_with_its_reason(): got = structures.problems( edited(SMILES_TERMS, value="O(", identity="smiles:000000000000") ) assert got[0]["rule"] == "layer.structure.value" assert got[0]["message"] == "the value is not a SMILES: unclosed (" def test_a_percent_value_breaks_only_the_value_rule(): annotation = edited( SMILES_TERMS, value="C%1", terms=None, identity=structures.identity("smiles", "C%1"), ) assert rules_of(annotation) == ["layer.structure.value"] def test_a_value_with_a_query_is_a_smarts_not_a_smiles(): annotation = edited( SMILES_TERMS, value="[C,N]", identity="smiles:" + "0" * 12, terms=None ) got = structures.problems(annotation) assert got[0]["rule"] == "layer.structure.value" assert "that is SMARTS" in got[0]["message"] def test_a_smarts_must_carry_a_smarts_identity(): for identity in ("OTMSDBZUPAUEDD-UHFFFAOYSA-N", "smiles:2e2a923f840c", ""): got = structures.problems(edited(SMARTS_TERMS, identity=identity)) assert [x["rule"] for x in got] == ["layer.structure.identity"] assert "has no InChIKey" in got[0]["message"] def test_an_identity_of_the_other_format_is_named_as_such(): got = structures.problems(edited(SMILES_TERMS, identity="smarts:" + "0" * 12)) assert [x["message"] for x in got] == [ "the identity is a smarts one, the value a smiles" ] def test_an_identity_that_is_the_hash_of_another_text_gives_the_right_one(): right = structures.identity("smiles", "O([H])[H]") got = structures.problems(edited(SMILES_TERMS, identity="smiles:" + "0" * 12)) assert got == [ { "rule": "layer.structure.identity", "message": "the identity is not the SHA-256 of the value: " + right, } ] assert rules_of(edited(SMILES_TERMS, identity=right)) == [] def test_a_smiles_may_carry_an_inchikey_that_is_not_checked_against_the_text(): assert rules_of(edited(SMILES_TERMS, identity="OTMSDBZUPAUEDD-UHFFFAOYSA-N")) == [] def test_an_unknown_format_still_has_a_text_identity_checked_but_not_an_inchikey(): wrong = edited(SMILES_TERMS, format="text/plain", identity="smarts:" + "0" * 12) assert rules_of(wrong) == ["layer.structure.value", "layer.structure.identity"] keyed = edited(SMILES_TERMS, format="text/plain") assert rules_of(keyed) == ["layer.structure.value"] def term(kind, atoms, **extra): """A term of the given kind over `atoms`.""" return {"kind": kind, "atoms": atoms, **extra} @pytest.mark.parametrize( ("value", "terms", "fragment"), [ ("CCCC", [term("bond", [0, 1, 2])], "a bond cites 2 atoms"), ("CCCC", [term("angle", [0, 1])], "angle cites 3 atoms"), ("CCCC", [term("dihedral", [0, 1, 2, 3])], "a dihedral cites ? atoms"), ("CCCC", [{"atoms": [0, 1]}], "None cites ? atoms"), ("CCCC", [term("bond", [1, 1])], "an atom is cited twice"), ("CCCC", [term("bond", [0, 4])], "the value writes 4 atoms, numbered from 0"), ("CCCC", [term("bond", [0, 2])], "the atoms are not joined as"), ("CCCC", [term("angle", [0, 2, 1])], "the atoms are not joined as"), ("CCCC", [term("torsion", [0, 1, 3, 2])], "the atoms are not joined as"), ("CC(C)C", [term("improper", [1, 0, 2, 3])], None), ("CC(C)C", [term("improper", [0, 1, 2, 3])], "the atoms are not joined as"), ("CCCC", [term("bond", [0, 1], types=["C"])], "1 types for 2 atoms"), ( "CCCC", [term("bond", [0, 1], units={"k": "x"}, values={})], "units for values that are not given: k", ), ( "CCCC", [term("bond", [0, 1], units={"b": "x", "a": "x"}, values={"c": "1"})], "a, b", ), ], ) def test_terms_are_checked_against_the_atoms_and_bonds_the_text_writes( value, terms, fragment ): annotation = edited( SMILES_TERMS, value=value, identity=structures.identity("smiles", value), terms=terms, ) got = structures.problems(annotation) if fragment is None: assert got == [] return assert {x["rule"] for x in got} == {"layer.structure.term"} assert fragment in got[0]["message"] def test_every_term_is_numbered_in_its_message(): value = "CCC" terms = [term("bond", [0, 1]), term("bond", [0, 2]), term("angle", [0, 1])] annotation = edited( SMILES_TERMS, value=value, identity=structures.identity("smiles", value), terms=terms, ) messages = [x["message"] for x in structures.problems(annotation)] assert len(messages) == 2 assert messages[0].startswith("term 1:") assert messages[1].startswith("term 2:") def test_a_term_is_not_joined_against_a_value_that_failed_to_scan(): annotation = edited( SMILES_TERMS, value="C(", identity=structures.identity("smiles", "C("), terms=[term("bond", [0, 1])], ) assert rules_of(annotation) == ["layer.structure.value"]