asciichem 0.31.0 → 0.31.2

data/lib/asciichem/model/bond.rb

@@ -4,40 +4,48 @@ module AsciiChem
   module Model
     # A bond between two adjacent nodes in a structural chain.
     class Bond < Node
-      attr_accessor :kind
+      attr_accessor :kind, :direction
 
       KINDS = {
-        single:    { ascii: "-",  mathml_entity: "-" },
-        double:    { ascii: "=",  mathml_entity: "=" },
-        triple:    { ascii: "#",  mathml_entity: "≡" },
-        quadruple: { ascii: "##", mathml_entity: "≣" },
-        wedge:     { ascii: ">-", mathml_entity: "↑" },
-        hash:      { ascii: "-<", mathml_entity: "↓" },
-        dative:    { ascii: "~>", mathml_entity: "→" },
-        wavy:      { ascii: "~~", mathml_entity: "∼" },
-        aromatic:  { ascii: ":",  mathml_entity: ":" }
+        single: { ascii: '-',  mathml_entity: '-' },
+        double: { ascii: '=',  mathml_entity: '=' },
+        triple: { ascii: '#',  mathml_entity: '≡' },
+        quadruple: { ascii: '##', mathml_entity: '≣' },
+        wedge: { ascii: '>-', mathml_entity: '↑' },
+        hash: { ascii: '-<', mathml_entity: '↓' },
+        dative: { ascii: '~>', mathml_entity: '→' },
+        wavy: { ascii: '~~', mathml_entity: '∼' },
+        aromatic: { ascii: ':', mathml_entity: ':' }
       }.freeze
 
       # CML wire order codes per bond kind. Single source of truth
       # for both adapter directions — to_canonical emits, from_canonical
       # parses. Adding a new bond kind = one entry here + one in KINDS.
       CML_ORDER_CODES = {
-        single: "S", double: "D", triple: "T",
-        quadruple: "Q", wedge: "W", hash: "H",
-        dative: "A", wavy: "V"
+        single: 'S', double: 'D', triple: 'T',
+        quadruple: 'Q', wedge: 'W', hash: 'H',
+        dative: 'A', wavy: 'V'
       }.freeze
       KIND_BY_CML_ORDER = CML_ORDER_CODES.invert.freeze
 
       # Subset that carries stereo meaning (wedge = out of page,
       # hash = into page). Used for <bondStereo> elements.
-      CML_STEREO_CODES = { wedge: "W", hash: "H" }.freeze
+      CML_STEREO_CODES = { wedge: 'W', hash: 'H' }.freeze
 
-      def initialize(kind: :single)
+      def initialize(kind: :single, direction: nil)
         @kind = kind
+        @direction = direction
+      end
+
+      # SMILES directional-bond orientation (`/` up, `\` down) on the
+      # single bonds flanking a stereogenic double bond. Orthogonal to
+      # the bond kind; only :single carries it.
+      def direction
+        @direction if kind == :single
       end
 
       def value_attributes
-        { kind: kind }
+        { kind: kind, direction: direction }
       end
 
       def ascii
@@ -49,7 +57,7 @@ module AsciiChem
       end
 
       def cml_order_code
-        CML_ORDER_CODES.fetch(kind, "S")
+        CML_ORDER_CODES.fetch(kind, 'S')
       end
 
       def cml_stereo_code

data/lib/asciichem/model/reaction.rb

@@ -29,6 +29,14 @@ module AsciiChem
           conditions: conditions }
       end
 
+      # Normalized stoichiometry (item 4): each side maps the species'
+      # coefficient-free canonical text to its integer coefficient
+      # (absent coefficient = 1). A species can appear on both sides.
+      def stoichiometry
+        { reactants: side_stoichiometry(reactants),
+          products: side_stoichiometry(products) }
+      end
+
       def children
         reactants + products
       end
@@ -59,6 +67,16 @@ module AsciiChem
         "Reaction(#{reactants.map(&:to_s).join(' + ')} " \
           "#{arrow_ascii} #{products.map(&:to_s).join(' + ')})"
       end
+
+      private
+
+      def side_stoichiometry(side)
+        side.each_with_object(Hash.new(0)) do |molecule, out|
+          coefficient = (molecule.coefficient || '1').to_i
+          coefficient = 1 if coefficient.zero?
+          out[molecule.to_text.sub(/\A\d+/, '')] += coefficient
+        end
+      end
     end
   end
 end

data/lib/asciichem/perception.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # The perception pass (TODO.v2/13 item 2): chemistry that the SYNTAX
+  # leaves implicit, derived once here and consumed everywhere — the
+  # linter, the canonicalizer, renderers, and the SMILES writer.
+  #
+  # Everything is a pure function of the model; nothing mutates.
+  module Perception
+    # Default valences per element (the common ground-state values;
+    # multi-valent elements list their allowed valences in order).
+    DEFAULT_VALENCES = {
+      'H' => [1], 'B' => [3], 'C' => [4], 'N' => [3], 'O' => [2],
+      'F' => [1], 'Al' => [3], 'Si' => [4], 'P' => [3, 5],
+      'S' => [2, 4, 6], 'Cl' => [1], 'Br' => [1], 'I' => [1]
+    }.freeze
+
+    BOND_ORDER = {
+      single: 1, double: 2, triple: 3, quadruple: 4,
+      aromatic: 1, wedge: 1, hash: 1, dative: 1, wavy: 1
+    }.freeze
+
+    module_function
+
+    # Perception runs over the neutral graph pair from
+    # Structure::Graph.build: [atoms, edges].
+
+    # Neighbour indexes of an atom, in edge order.
+    def neighbours(atom_index, edges)
+      edges.each_with_object([]) do |edge, acc|
+        acc << edge.to if edge.from == atom_index
+        acc << edge.from if edge.to == atom_index
+      end
+    end
+
+    # Sum of explicit bond orders at an atom (wedge/hash/dative/wavy
+    # bonds order as single; aromatic orders as 1 — Hückel alternation
+    # is a ring-perception concern, not a bond-order sum concern).
+    def bond_order_sum(atom_index, edges)
+      edges.sum do |edge|
+        next 0 unless edge.from == atom_index || edge.to == atom_index
+
+        BOND_ORDER.fetch(edge.kind, 1)
+      end
+    end
+
+    # Implicit hydrogens for an atom: the smallest default valence
+    # that the explicit bond order fits, minus the bond order.
+    # - Atoms that STATE hydrogens ([NH4+], [CH4]) return 0 — never
+    #   add to what the source said.
+    # - Charged atoms return nil: charge algebra on valence is
+    #   element-specific and deferred until the perception pass grows
+    #   one (wrong implicit hydrogens are worse than none).
+    # - Elements without a table entry, or explicit orders exceeding
+    #   every default, return nil — never invent.
+    def implicit_hydrogens(atom, bond_order_sum)
+      return 0 if atom.hydrogens
+      return nil if atom.charge
+
+      valences = DEFAULT_VALENCES[atom.element]
+      return nil if valences.nil?
+
+      fitting = valences.select { |v| v >= bond_order_sum }
+      return nil if fitting.empty?
+
+      fitting.min - bond_order_sum
+    end
+
+    # Six-membered cycles where every atom is sp2 (participates in a
+    # double bond) or aromatic-flagged — the practical fused-system
+    # rule: per-ring strict alternation can never see both rings of
+    # naphthalene (the shared bond is single), but per-atom sp2 does.
+    # Returns arrays of atom indexes, one per perceived ring, or an
+    # empty list. Full Hückel pi-electron counting is a later slice.
+    def aromatic_rings(atoms, edges)
+      cycles = ring_cycles(edges, max_size: 6, atom_count: atoms.length)
+        .select { |cycle| cycle.length == 6 }
+      cycles.select { |cycle| cycle.all? { |i| sp2?(i, atoms, edges) } }
+    end
+
+    def sp2?(atom_index, atoms, edges)
+      return true if atoms[atom_index].aromatic == true
+
+      edges.any? do |edge|
+        (edge.from == atom_index || edge.to == atom_index) && edge.kind == :double
+      end
+    end
+
+    def bond_kind(a, b, edges)
+      edge = edges.find do |e|
+        (e.from == a && e.to == b) || (e.from == b && e.to == a)
+      end
+      edge&.kind
+    end
+
+    # Simple cycles up to max_size via DFS (molecules are small).
+    def ring_cycles(edges, max_size:, atom_count:)
+      found = []
+      atom_count.times do |start|
+        dfs_cycles(edges, start, start, [start], max_size, found)
+      end
+      found.uniq { |cycle| cycle.minmax }
+    end
+
+    def dfs_cycles(edges, start, current, path, max_size, found)
+      neighbours(current, edges).each do |nb|
+        next if nb == path[-2]
+
+        if nb == start
+          found << path.dup if path.length >= 3
+        elsif !path.include?(nb) && path.length < max_size
+          dfs_cycles(edges, start, nb, path + [nb], max_size, found)
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/reaction_roles.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Reaction-roles perception (TODO.v2/13 item 4, slice A): the
+  # chemistry-writing convention puts catalysts and light reagents
+  # ABOVE the arrow and solvents/conditions BELOW; the conditions
+  # text carries them free-form. This derives structured role hints
+  # from that convention — pure functions, nothing mutates. A full
+  # roles syntax (structured entries in the grammar) is the later
+  # slice.
+  module ReactionRoles
+    CATALYST_HINTS = %w[pd pt ni fe catalyst cat].freeze
+    SOLVENT_HINTS = %w[h2o thf dmso dmf etoh meoh toluene solvent sol water].freeze
+
+    module_function
+
+    # Returns { catalysts: [strings], solvents: [strings],
+    # reagents: [strings], other_above: [strings], other_below: [] }
+    # — entries split from the conditions text by whitespace, each
+    # classified by hint matching against the role vocabularies.
+    def roles_for(reaction)
+      conditions = reaction.conditions
+      above = split_entries(conditions&.above)
+      below = split_entries(conditions&.below)
+      {
+        catalysts: above.select { |e| matches?(e, CATALYST_HINTS) },
+        reagents: above.reject { |e| matches?(e, CATALYST_HINTS) },
+        solvents: below.select { |e| matches?(e, SOLVENT_HINTS) },
+        other_below: below.reject { |e| matches?(e, SOLVENT_HINTS) }
+      }
+    end
+
+    def split_entries(text)
+      return [] if text.nil? || text.strip.empty?
+
+      text.strip.split(/[;,\s]+/).reject(&:empty?)
+    end
+
+    def matches?(entry, hints)
+      hints.any? { |hint| entry.to_s.downcase.include?(hint) }
+    end
+  end
+end

data/lib/asciichem/resolver/opsin.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'net/https'
+require 'uri'
+
+module AsciiChem
+  module Resolver
+    # OPSIN source adapter (TODO.v2/13 item 3): IUPAC name → structure
+    # — name-to-structure perception for systematic names, the piece
+    # PubChem's name lookup cannot do (PubChem indexes a curated name
+    # list; OPSIN *derives* the structure from any systematic IUPAC
+    # name). Uses the public OPSIN web service
+    # (https://opsin.ch.cam.ac.uk), which answers with CML or SMILES.
+    #
+    # Citation profile: publisher University of Cambridge Centre for
+    # Molecular Informatics; per-access retrievedAt provenance.
+    class Opsin < Adapter
+      source_name :opsin
+      # Derivation only: 'name' is the curated-lookup convention
+      # (PubChem/Common Chemistry). OPSIN DERIVES structures from
+      # systematic names - reachable via 'iupac-name' so it can
+      # never preempt a lookup source.
+      supports 'iupac-name'
+
+      BASE = 'https://opsin.ch.cam.ac.uk/opsin'
+      private_constant :BASE
+
+      def fetch_record(value:, convention: nil, fetch:)
+        body = fetch.get("#{BASE}/#{CGI.escape(value.to_s)}.smiles")
+        return nil unless body
+
+        substance_from(body.strip)
+      rescue StandardError => e
+        raise Error, "opsin request failed: #{e.message}"
+      end
+
+      def attribution
+        'OPSIN, University of Cambridge Centre for Molecular Informatics'
+      end
+
+      private
+
+      def substance_from(smiles)
+        return nil if smiles.empty?
+
+        provenance = default_provenance
+        Substance.new(
+          preferred_name: nil,
+          identifiers: [Identifier.new(value: smiles, convention: 'canonical-smiles',
+                                       provenance: provenance)],
+          properties: [],
+          structure: parse_structure(smiles)
+        )
+      end
+
+      # OPSIN answers SMILES that may use features outside the
+      # supported subset (wildcards, exotic stereo); then the SMILES
+      # stays as an identifier and structure is nil — no silent loss.
+      def parse_structure(smiles)
+        AsciiChem.parse_smiles(smiles).nodes.first
+      rescue AsciiChem::ParseError
+        nil
+      end
+    end
+  end
+end

data/lib/asciichem/resolver.rb

@@ -17,6 +17,7 @@ module AsciiChem
     autoload :Adapter, "asciichem/resolver/adapter"
     autoload :Cache, "asciichem/resolver/cache"
     autoload :PubChem, "asciichem/resolver/pubchem"
+    autoload :Opsin, "asciichem/resolver/opsin"
     autoload :CommonChemistry, "asciichem/resolver/common_chemistry"
     autoload :Substance, "asciichem/resolver/substance"
 

data/lib/asciichem/smiles/parser.rb

@@ -22,7 +22,7 @@ module AsciiChem
       # Returns a Model::Formula with one Molecule per dot component.
       def parse
         molecules = [component]
-        molecules << component while eat(".")
+        molecules << component while eat('.')
         unless @pos == @source.length
           raise ParseError,
                 "unexpected character #{peek.inspect} at position #{@pos} in #{@source.inspect}"
@@ -35,9 +35,11 @@ module AsciiChem
       def component
         @atoms = []
         @adjacency = []
+        @edge_directions = {}
         @open_rings = {}
         @parent = nil
         @pending_kind = nil
+        @pending_direction = nil
 
         chain
 
@@ -48,7 +50,14 @@ module AsciiChem
 
         edges = []
         @adjacency.each_with_index do |neighbors, index|
-          neighbors.each { |to, kind| edges << Structure::Graph::Edge.new(from: index, to: to, kind: kind) if to > index }
+          neighbors.each do |to, kind|
+            next unless to > index
+
+            edges << Structure::Graph::Edge.new(
+              from: index, to: to, kind: kind,
+              direction: @edge_directions[[index, to]]
+            )
+          end
         end
         Model::Molecule.new(nodes: Structure::Linearizer.new(atoms: @atoms, edges: edges).nodes)
       end
@@ -58,42 +67,51 @@ module AsciiChem
       def chain
         atom_token
         until eoc?
-          if peek == "("
+          if peek == '('
             branch
           elsif bond_start?
-            kind = bond_token
-            if peek == "("
-              branch(kind)
+            kind, direction = bond_token
+            if peek == '('
+              branch(kind, direction)
             elsif digit_start?
-              ringbond(kind)
+              ringbond(kind, direction)
             else
               @pending_kind = kind
+              @pending_direction = direction
               atom_token
             end
           elsif digit_start?
             ringbond(nil)
           else
             @pending_kind = nil
+            @pending_direction = nil
             atom_token
           end
         end
       end
 
-      def branch(kind = nil)
-        expect("(")
+      def branch(kind = nil, direction = nil)
+        expect('(')
         # The bond may lead the branch ("C-(O)") or open it ("C(=O)").
-        kind = bond_token if kind.nil? && bond_start?
+        kind, direction = bond_token if kind.nil? && bond_start?
         saved_parent = @parent
         saved_pending = @pending_kind
+        saved_direction = @pending_direction
         @pending_kind = kind
+        @pending_direction = direction
         chain
-        expect(")")
+        expect(')')
         @parent = saved_parent
         @pending_kind = saved_pending
+        @pending_direction = saved_direction
       end
 
-      def ringbond(kind)
+      def ringbond(kind, direction = nil)
         digit = ring_digit
+        if direction
+          raise ParseError,
+                "directional ring closures (#{direction}) are not representable in the model's ring-closure form"
+        end
         if @open_rings.key?(digit)
           opener = @open_rings.delete(digit)
           # The model's ring-closure digits carry no bond kind, so an
@@ -115,9 +133,13 @@ module AsciiChem
         index = @atoms.length
         @atoms << atom
         @adjacency[index] = {}
-        add_edge(@parent, index, @pending_kind) if @parent
+        if @parent
+          add_edge(@parent, index, @pending_kind)
+          @edge_directions[[@parent, index].minmax] = @pending_direction if @pending_direction
+        end
         @parent = index
         @pending_kind = nil
+        @pending_direction = nil
       end
 
       def add_edge(from, to, explicit)
@@ -133,7 +155,7 @@ module AsciiChem
       # -- tokens ----------------------------------------------------------
 
       def read_atom
-        return bracket_atom if peek == "["
+        return bracket_atom if peek == '['
 
         two = @source[@pos, 2].to_s
         if (symbol = ORGANIC.find { |s| two.start_with?(s) })
@@ -149,19 +171,20 @@ module AsciiChem
       end
 
       def bracket_atom
-        expect("[")
+        expect('[')
         isotope = digits
         symbol = bracket_symbol
-        reject_chirality
+        chirality = read_chirality
         hydrogens = hcount
         charge = bracket_charge
         skip_class
-        expect("]")
+        expect(']')
         Model::Atom.new(
           element: symbol.capitalize,
           isotope: isotope,
           charge: charge,
           hydrogens: hydrogens,
+          chirality: chirality,
           aromatic: symbol.match?(/\A[a-z]/) || nil
         )
       end
@@ -188,15 +211,23 @@ module AsciiChem
         raise ParseError, "expected an element symbol at position #{@pos} in #{@source.inspect}"
       end
 
-      def reject_chirality
-        return unless peek == "@"
+      # `@' (TH1) / `@@' (TH2): SMILES ordered-neighbour tetrahedral
+      # parity, stored verbatim on the atom — the writer recomputes
+      # the token for its own traversal order.
+      def read_chirality
+        return nil unless peek == '@'
 
-        token = @source[@pos, 2] == "@@" ? "'@@'" : "'@'"
-        raise ParseError, "chirality #{token} is not supported in the v1 subset"
+        if @source[@pos, 2] == '@@'
+          @pos += 2
+          'TH2'
+        else
+          @pos += 1
+          'TH1'
+        end
       end
 
       def hcount
-        return nil unless peek == "H"
+        return nil unless peek == 'H'
 
         @pos += 1
         count = digits
@@ -206,7 +237,7 @@ module AsciiChem
       # "+" | "++" | "+n" | "-" | "--" | "-n" → number-then-sign.
       def bracket_charge
         sign = peek
-        return nil unless sign == "+" || sign == "-"
+        return nil unless ['+', '-'].include?(sign)
 
         @pos += 1
         second = @source[@pos].to_s
@@ -221,32 +252,35 @@ module AsciiChem
       end
 
       def skip_class
-        return unless peek == ":"
+        return unless peek == ':'
 
         @pos += 1
         digits
       end
 
+      # Returns [kind, direction]: `/' and `\' are DIRECTIONAL SINGLE
+      # bonds (SMILES E/Z stereo) — kind stays :single, the direction
+      # rides the model's Bond#direction.
       def bond_token
         ch = peek
-        kind = { "-" => :single, "=" => :double, "#" => :triple, "$" => :quadruple,
-                 ":" => :aromatic }[ch]
+        kind = { '-' => :single, '=' => :double, '#' => :triple, '$' => :quadruple,
+                 ':' => :aromatic }[ch]
         unless kind
-          if ch == "/" || ch == "\\"
-            raise ParseError,
-                  "bond direction #{ch.inspect} (E/Z stereo) is not supported in the v1 subset"
+          if ['/', '\\'].include?(ch)
+            @pos += 1
+            return [:single, ch == '/' ? :up : :down]
           end
           raise ParseError, "expected a bond or atom at position #{@pos} in #{@source.inspect}"
         end
         @pos += 1
-        kind
+        [kind, nil]
       end
 
       def ring_digit
-        if peek == "%"
+        if peek == '%'
           @pos += 1
           digit = @source[@pos, 2].to_s
-          raise ParseError, "malformed %nn ring closure" unless digit.match?(/\A\d\d\z/)
+          raise ParseError, 'malformed %nn ring closure' unless digit.match?(/\A\d\d\z/)
 
           @pos += 2
           digit
@@ -291,9 +325,7 @@ module AsciiChem
       end
 
       def expect(char)
-        unless peek == char
-          raise ParseError, "expected #{char.inspect} at position #{@pos} in #{@source.inspect}"
-        end
+        raise ParseError, "expected #{char.inspect} at position #{@pos} in #{@source.inspect}" unless peek == char
 
         @pos += 1
       end