asciichem 0.31.4 → 0.31.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9c3f297f95612987dbe2a4e7f15bcaa0d4628dbae0d074dce5aeea2fb5e0efa
-  data.tar.gz: 75a1ef4ea31451fccfb37369299d86afa1a08b26c825054de2eda109c636a561
+  metadata.gz: 6c9a131b0a052014c60f5be8b74972de24db882f7db088b82bdea1c506709a46
+  data.tar.gz: 9b280851bdc1fb8c4f4681f1887796f2eb688298f8c495cd81a766a879fd8a09
 SHA512:
-  metadata.gz: cba5c440d3da6c3a436b207d36203f07641ad1b76c61ade69ac5e39697c1b79a81374f7e7106a5764611b3f400f28f9dae89a7054a70c4124b6c21da0d6f8c8a
-  data.tar.gz: e7cb123f63497d962297ea6629e684a0b8af6417c494a7332e02a9729585e977a0c02e2acdd6ee7eb99868fa70475b9a8e57e748eb38fde789957c66a8dc2afa
+  metadata.gz: d5580a3f5f314447b3f1f932b37396bb5741bd5363d96e4ae97cc95fcbcf7cfbcd0690ae16253c532d21b2c790093fda0652cd3d1a330f3bcbce9e1801c66e66
+  data.tar.gz: 44a0d45dfca800429e648a5a3c3adab685c5813c7c23d5be68afb55c7dc4cf34410b8cb16ff43681a439d9ec258c7e4f71aa141e7d3561a6a05c0ccc2cbc3f5b

data/ARCHITECTURE.adoc

@@ -390,3 +390,81 @@ Ten registered checks (auto-load via `Linter::Base.register`):
 * `#atom_count` — total atoms (recurses through groups/nested molecules)
 * `#hill_formula` — Hill-system canonical formula (C first, H second, alpha)
 * `#formula_weight` — sum of atomic_mass * count (v0.13+)
+
+== Perception pass (v0.31+)
+
+`AsciiChem::Perception` derives the chemistry the syntax leaves
+implicit, as pure functions over the neutral graph pair
+(`Structure::Graph.build` returns `[atoms, edges]`):
+
+* `bond_order_sum` — valence-feasibility sum (aromatic orders as 1);
+  consumed by the linter's `ValenceCheck`.
+* `hydrogen_valence_sum` — hydrogen-counting sum (aromatic orders as
+  1.5, Hückel); paired with `implicit_hydrogens`, which returns a
+  whole, non-negative count or declines (`nil`): stated hydrogens win,
+  charged atoms and non-integral/over-valent sums decline.
+* `aromatic_rings` — π-electron counting for 5- and 6-membered cycles
+  (in-system double = 1, lone-pair donor N/O/S/P/Se/As = 2,
+  exocyclic-double carbon = 0; aromatic at totals 6 or 10). Charged
+  rings decline; aromatic-flagged rings are taken as stated. This
+  perceives furan/pyrrole/thiophene, fused systems, keeps quinones
+  Kekulé, and rejects four-π and three-membered rings.
+
+Semantics are shared through the corpus (`fixtures/perception.json`) —
+per-atom implicit hydrogens plus perceived ring indexes, declines
+included — and mirrored in TypeScript and Python.
+
+== Canonical SMILES (v0.31+)
+
+`Smiles::Writer` is a deterministic serialiser that consumes the
+perception pass: perceived aromatic rings are written lowercase with
+their ring bonds implicit, so Kekulé input canonicalizes
+(`C1=CC=CC=C1` → `c1ccccc1`, pyrrole → `c1c[nH]cc1`). Ring-closure
+digits stay out of branches (a closure-bearing child continues the
+chain). Stated-zero hydrogens emit `H0`. The canonical form is a fixed
+point; corpus fixtures whose input is not canonical state the expected
+output in `canonicalSmiles`.
+
+== Reactions as semantics (v0.31+)
+
+* `Reaction::Conditions#entries` — typed role entries
+  (`[cat: Pd; solv: THF]`) derived from the verbatim bracket text;
+  `ReactionRoles.roles_for` prefers explicit roles, falls back to the
+  above/below convention for free text.
+* `Reaction#stoichiometry` and `Molecule#stoichiometric_coefficient` —
+  coefficient-free species → integer coefficient, one rule shared by
+  the reaction, `BalanceCheck`, and `element_counts`.
+* `MechanismGraph.for(mechanism)` — parsed steps, catalysts (species on
+  both sides), inter-step links (product → later reactant), and the
+  step's electron-flow markers.
+* `Mechanism::Flow` — `| flow: SOURCE > TARGET` clauses on a step
+  (semicolon-separated), verbatim names, carried on the wire as
+  `steps[].flows`; unknown clauses and malformed arrows raise.
+* `Rxn::Writer` — MDL RXN V2000 emission (species, not
+  stoichiometry); `Rinchi::BinaryEngine` wraps the opt-in `rinchi-1`
+  binary for reaction identity (same contract as the InChI engine:
+  install guidance, `EngineMissingError`, nothing vendored).
+
+== Depiction backends (v0.31+)
+
+`AsciiChem::Layout.backend` is the depiction seam: a backend responds
+to `layout(molecule, algorithm:)` and returns a `Layout::Result`.
+`Layout::BuiltinBackend` (authored coordinates or deterministic elkrb
+layered layout) is the default; external engines (RDKit, CDK, a Rust
+layout core) plug in with one assignment. The renderer, the model, and
+the wire form never learn which engine placed the atoms.
+
+== Conformance contracts (v0.31+)
+
+Two sibling repositories are normative, not the implementation:
+
+* `asciichem-model` — versioned wire schemas (additive changes only),
+  LUTAML definitions, generated TS types; the gem vendors the schemas
+  into `spec/schemas` via `scripts/update-model-schemas.sh`.
+* `asciichem-tests` — the shared corpus. Fixture families: parser
+  acceptance/rejection, canonical-text round-trip, CML, MathML
+  goldens, identifiers, linter expectations, SMILES/molfile
+  interchange, perception (`implicitHydrogens`, `aromaticRings`),
+  condition entries, mechanism flows, and 300 seeded generated models
+  shared across implementations. Contract changes are versioned and
+  state new expectations; fixtures are never weakened.

data/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.31.5] - 2026-10-20
+
+### Changed
+- Aromaticity perception is now **Hückel counting** (TODO.v2/13 item 2,
+  finishing the documented later slice): 5- and 6-membered cycles
+  count π electrons — in-system double = 1, lone-pair donor
+  (N/O/S/P/Se/As) with no double = 2, exocyclic-double carbon = 0 —
+  and are aromatic at totals 6 or 10. Charged rings decline;
+  aromatic-flagged rings are taken as stated. Furan, pyrrole, and
+  thiophene are perceived from Kekulé bond orders; quinones remain
+  excluded, as do four-π and three-membered rings.
+- Canonical SMILES covers the five-membered heteroaromatics:
+  `C1=COC=C1` → `c1cocc1`, `C1=CNC=C1` → `c1c[nH]cc1`,
+  `C1=CSC=C1` → `c1cscc1`. A perceived pyrrole nitrogen is written
+  `[nH]` (bare aromatic `n` implies no hydrogen); inferred heteroatom
+  hydrogens apply only to rings perceived from Kekulé orders, so
+  source-aromatic thiophene never gains a phantom H.
+- Corpus contract 0.8.0 (`asciichem-tests`): Hückel fixtures for
+  furan/pyrrole/thiophene, cyclopentadiene and cyclopropene pinned as
+  not aromatic, plus `canonicalSmiles` expectations. TS and Python
+  parity merged; the Python writer also emits `H0` for stated-zero
+  hydrogens.
+
 ## [0.31.4] - 2026-10-20
 
 ### Changed

data/lib/asciichem/perception.rb

@@ -91,27 +91,56 @@ module AsciiChem
               .select { |deficit| deficit >= 0 && deficit.modulo(1).zero? }
     end
 
-    # Six-membered cycles where every atom is sp2 — participates in a
-    # double bond to an atom that is itself in a ring, or is
-    # aromatic-flagged. The partner-in-a-ring requirement keeps
-    # quinones out: their carbons are sp2, but the double bonds that
-    # make them so point at exocyclic oxygens, and writing such a
-    # ring as aromatic SMILES would state the wrong bond orders. A
-    # fused system still qualifies — naphthalene's fusion carbons
-    # double-bond to atoms of the neighbouring ring. Per-ring strict
-    # alternation can never see both rings (the shared bond is
-    # single); per-atom sp2-in-the-system does. Full Hückel
-    # pi-electron counting is a later slice.
+    # π-electron-donating heteroatoms: a ring atom with no double bond
+    # of its own contributes its lone pair (pyrrole N, furan O,
+    # thiophene S) — the 2 electrons that make those five-membered
+    # rings 4n+2.
+    LONE_PAIR_DONORS = %w[N O S P Se As].freeze
+
+    # Aromatic rings by Hückel counting: 5- and 6-membered cycles whose
+    # π-electron contributions total 6 or 10 (4n+2 with n >= 1; the
+    # n = 0 case is a charged three-membered ring, which perception
+    # declines, and a 2π six-ring would otherwise misread a diene as
+    # aromatic). Per
+    # atom: an in-system double bond contributes 1; a lone-pair donor
+    # with no double contributes 2; a carbon with only single bonds or
+    # an exocyclic double contributes 0. Charged atoms make the count
+    # undecidable and the ring is declined; aromatic-flagged rings are
+    # taken as stated.
+    #
+    # This sees fused systems (naphthalene's shared bond is single, but
+    # each atom's double bond lies in the ring system) and keeps
+    # quinones out (their carbons' only double bonds point at
+    # exocyclic oxygens, so the ring counts 5, not 4n+2).
     def aromatic_rings(atoms, edges)
       cycles = ring_cycles(edges, max_size: 6, atom_count: atoms.length)
       cyclic_atoms = cycles.flatten.uniq
-      six = cycles.select { |cycle| cycle.length == 6 }
-      six.select { |cycle| cycle.all? { |i| sp2?(i, atoms, edges, cyclic_atoms) } }
+      cycles.select { |cycle| aromatic_cycle?(cycle, atoms, edges, cyclic_atoms) }
     end
 
-    def sp2?(atom_index, atoms, edges, cyclic_atoms)
-      return true if atoms[atom_index].aromatic == true
+    def aromatic_cycle?(cycle, atoms, edges, cyclic_atoms)
+      return true if cycle.any? { |i| atoms[i].aromatic == true }
+      return false unless [5, 6].include?(cycle.length)
 
+      contributions = cycle.map do |i|
+        ring_pi_electrons(atoms[i], i, edges, cyclic_atoms)
+      end
+      return false if contributions.any?(&:nil?)
+
+      [6, 10].include?(contributions.sum)
+    end
+
+    # π electrons one ring atom contributes, or nil when the count is
+    # undecidable (charged atom).
+    def ring_pi_electrons(atom, atom_index, edges, cyclic_atoms)
+      return nil if atom.charge
+      return 1 if in_system_double?(atom_index, edges, cyclic_atoms)
+      return 2 if LONE_PAIR_DONORS.include?(atom.element)
+
+      0
+    end
+
+    def in_system_double?(atom_index, edges, cyclic_atoms)
       edges.any? do |edge|
         next false unless edge.from == atom_index || edge.to == atom_index
         next false unless edge.kind == :double

data/lib/asciichem/smiles/writer.rb

@@ -25,6 +25,10 @@ module AsciiChem
       }.freeze
       CONTINUATION_BONDS = %i[single aromatic].freeze
 
+      # Aromatic lowercase heteroatoms with an implicit hydrogen need
+      # brackets: bare `n`/`o`/`s` imply none.
+      HETERO_IMPLICIT_H = %w[N O S P Se As].freeze
+
       def initialize(molecule)
         @molecule = molecule
       end
@@ -71,13 +75,27 @@ module AsciiChem
       # item 2): atoms in perceived aromatic rings are written as
       # aromatic (lowercase) and the ring bonds between them carry no
       # bond symbol — Kekulé benzene canonicalizes to `c1ccccc1`, so
-      # both spellings converge. Perception's in-ring double-bond
-      # rule keeps quinone-like rings out.
+      # both spellings converge. Perception's Hückel counting keeps
+      # quinone-like rings out.
+      #
+      # Hydrogens are inferred for lowercase carbon but NOT for
+      # heteroatoms: pyrrole's N must be written `[nH]` or the SMILES
+      # states a pyridine-type nitrogen instead. The perceived
+      # implicit count for ring atoms is recorded for that decision.
       def perceive_aromaticity(atoms, edges)
         @perceived_aromatic = {}
         @perceived_ring_edges = {}
+        @perceived_hydrogens = {}
         AsciiChem::Perception.aromatic_rings(atoms, edges).each do |ring|
-          ring.each { |index| @perceived_aromatic[index] = true }
+          ring.each do |index|
+            @perceived_aromatic[index] = true
+            next if atoms[index].aromatic == true
+
+            @perceived_hydrogens[index] = AsciiChem::Perception.implicit_hydrogens(
+              atoms[index],
+              AsciiChem::Perception.hydrogen_valence_sum(index, edges)
+            )
+          end
           ring.each_with_index do |atom, i|
             other = ring[(i + 1) % ring.length]
             @perceived_ring_edges[[atom, other].minmax] = true
@@ -85,6 +103,19 @@ module AsciiChem
         end
       end
 
+      # Hydrogens the written token must state: the source's own count
+      # wins; otherwise only a ring PERCEIVED from Kekulé bond orders
+      # gets perception's implicit count. A source-aromatic atom
+      # already states its hydrogens the way SMILES does (`[nH]`), and
+      # aromatic 1.5 bond orders do not map onto heteroatom valences
+      # (thiophene's S would otherwise acquire a phantom H).
+      def writing_hydrogens(index)
+        stated = @atoms[index].hydrogens
+        return stated unless stated.nil?
+
+        @perceived_hydrogens[index]
+      end
+
       # Aromatic for WRITING: the source flagged the atom, or
       # perception found it in an aromatic ring.
       def aromatic?(index)
@@ -269,8 +300,12 @@ module AsciiChem
         atom = @atoms[index]
         aromatic = aromatic?(index)
         lowercase = aromatic && LOWERCASE_AROMATIC.include?(atom.element)
+        hyd = writing_hydrogens(index)
+        hetero_needs_h = aromatic && lowercase && hyd&.positive? &&
+                         HETERO_IMPLICIT_H.include?(atom.element)
         needs_bracket =
-          atom.charge || atom.isotope || atom.hydrogens || atom.chirality ||
+          atom.charge || atom.isotope || !atom.hydrogens.nil? || atom.chirality ||
+          hetero_needs_h ||
           (!ORGANIC.include?(atom.element) && !lowercase) ||
           (aromatic && !lowercase)
         token =
@@ -280,10 +315,10 @@ module AsciiChem
             t << atom.isotope if atom.isotope
             t << symbol
             t << chirality_token(index) if stereo && atom.chirality
-            if atom.hydrogens
+            if !atom.hydrogens.nil? || hetero_needs_h
               t << 'H'
               # Stated zero is H0, not a bare H (which means one).
-              t << atom.hydrogens.to_s unless atom.hydrogens == 1
+              t << hyd.to_s unless hyd == 1
             end
             t << charge_suffix(atom.charge) if atom.charge
             t << ']'

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.31.4"
+  VERSION = "0.31.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.31.4
+  version: 0.31.5
 platform: ruby
 authors:
 - Ribose Inc.