asciichem 0.3.0

data/lib/asciichem/model_adapter/to_canonical.rb

@@ -0,0 +1,429 @@
+# frozen_string_literal: true
+
+require "chemicalml"
+
+module AsciiChem
+  module ModelAdapter
+    # AsciiChem::Model -> Chemicalml::Model. Walks the AsciiChem tree
+    # and builds a canonical document. Pure transformation; no I/O.
+    #
+    # Mapping rules:
+    #
+    # - `Formula`           -> `Chemicalml::Model::Document`.
+    # - `Molecule`          -> `Chemicalml::Model::Molecule`. Inner atoms
+    #                         collect IDs; bonds reference consecutive
+    #                         IDs. Groups flatten with their multiplicity
+    #                         applied to each contained atom's count.
+    # - `Atom`              -> `Chemicalml::Model::Atom` (element,
+    #                         isotope, charge, count, lone pairs,
+    #                         radical electrons).
+    # - `Bond`              -> `Chemicalml::Model::Bond` (kind, refs).
+    # - `Reaction`          -> `Chemicalml::Model::Reaction`.
+    # - `ReactionCascade`   -> `Chemicalml::Model::ReactionList`.
+    # - `ElectronConfiguration`, `EmbeddedMath`, `Text` -> skipped
+    #   (no canonical representation yet; a future extension can carry
+    #   them as namespaced metadata).
+    class ToCanonical
+      attr_reader :atom_mapping, :groups
+
+      def initialize(formula)
+        @formula = formula
+        @ids = IdRegistry.new
+        @atom_mapping = {}
+        # Map of canonical molecule ID -> array of GroupRecord.
+        # Keyed by molecule ID because aci:group elements live inside
+        # their parent <molecule>, and multiple molecules can exist
+        # (top-level + reactants + products).
+        @groups = Hash.new { |hash, key| hash[key] = [] }
+        @molecule_id_stack = []
+      end
+
+      def build
+        molecules = []
+        reactions = []
+        reaction_lists = []
+        @formula.nodes.each do |node|
+          case node
+          when AsciiChem::Model::Molecule
+            molecules << molecule_to_canonical(node)
+          when AsciiChem::Model::Reaction
+            reactions << reaction_to_canonical(node)
+          when AsciiChem::Model::ReactionCascade
+            reaction_lists << reaction_cascade_to_canonical(node)
+          end
+        end
+        Chemicalml::Model::Document.new(
+          molecules: molecules,
+          reactions: reactions,
+          reaction_lists: reaction_lists
+        )
+      end
+
+      private
+
+      # -- Molecules --------------------------------------------------
+
+      def molecule_to_canonical(molecule)
+        walker = MoleculeWalker.new(@ids)
+        atoms, bonds = walker.walk(molecule)
+        @atom_mapping.merge!(walker.atom_mapping)
+        canonical_molecule = Chemicalml::Model::Molecule.new(
+          id: @ids.next(:molecule),
+          atoms: atoms,
+          bonds: bonds,
+          count: molecule.coefficient,
+          formal_charge: total_formal_charge(atoms),
+          names: map_names(molecule.names),
+          identifiers: map_identifiers(molecule.identifiers),
+          title: molecule.title,
+          formulas: map_formulas(molecule.formulas),
+          properties: map_properties(molecule.properties),
+          labels: map_labels(molecule.labels)
+        )
+        @groups[canonical_molecule.id].concat(walker.groups) unless walker.groups.empty?
+        canonical_molecule
+      end
+
+      def map_names(names)
+        return [] if names.nil? || names.empty?
+
+        names.map do |n|
+          Chemicalml::Model::Name.new(
+            content: n.content,
+            convention: n.convention,
+            dict_ref: n.dict_ref
+          )
+        end
+      end
+
+      def map_identifiers(identifiers)
+        return [] if identifiers.nil? || identifiers.empty?
+
+        identifiers.map do |i|
+          Chemicalml::Model::Identifier.new(
+            value: i.value,
+            convention: i.convention,
+            dict_ref: i.dict_ref
+          )
+        end
+      end
+
+      def map_formulas(formulas)
+        return [] if formulas.nil? || formulas.empty?
+
+        formulas.map do |f|
+          Chemicalml::Model::Formula.new(
+            concise: f[:concise],
+            inline: f[:inline],
+            formal_charge: f[:formal_charge],
+            count: f[:count],
+            title: f[:title],
+            convention: f[:convention],
+            dict_ref: f[:dict_ref]
+          )
+        end
+      end
+
+      def map_properties(properties)
+        return [] if properties.nil? || properties.empty?
+
+        properties.map do |p|
+          Chemicalml::Model::Property.new(
+            title: p[:title],
+            value: build_scalar(p[:value]),
+            dict_ref: p[:dict_ref],
+            convention: p[:convention]
+          )
+        end
+      end
+
+      def build_scalar(value)
+        return nil if value.nil?
+
+        Chemicalml::Model::Scalar.new(
+          value: value.to_s,
+          dict_ref: nil
+        )
+      end
+
+      def map_labels(labels)
+        return [] if labels.nil? || labels.empty?
+
+        labels.map do |l|
+          Chemicalml::Model::Label.new(
+            value: l[:value],
+            dict_ref: l[:dict_ref],
+            convention: l[:convention]
+          )
+        end
+      end
+
+      def total_formal_charge(canonical_atoms)
+        charges = canonical_atoms.map { |a| parse_charge(a.formal_charge) }.compact
+        return nil if charges.empty?
+
+        sum = charges.sum
+        sum.positive? ? "+#{sum}" : sum.to_s
+      end
+
+      def parse_charge(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        match = value.to_s.match(/\A(?<n>\d*)(?<sign>[+-])\z/) ||
+                value.to_s.match(/\A(?<sign>[+-])(?<n>\d*)\z/)
+        return nil unless match
+
+        n = match[:n].empty? ? 1 : match[:n].to_i
+        match[:sign] == "+" ? n : -n
+      end
+
+      # -- Reactions --------------------------------------------------
+
+      def reaction_to_canonical(reaction)
+        Chemicalml::Model::Reaction.new(
+          id: @ids.next(:reaction),
+          reactant_list: reactant_list_to_canonical(reaction.reactants),
+          product_list: product_list_to_canonical(reaction.products),
+          arrow: reaction.arrow,
+          conditions_above: conditions_above(reaction),
+          conditions_below: conditions_below(reaction),
+          title: reaction.arrow.to_s,
+          type: reaction.arrow.to_s
+        )
+      end
+
+      def reaction_cascade_to_canonical(cascade)
+        Chemicalml::Model::ReactionList.new(
+          reactions: cascade.steps.map { |s| reaction_to_canonical(s) }
+        )
+      end
+
+      def reactant_list_to_canonical(reactants)
+        Chemicalml::Model::ReactantList.new(
+          reactants: reactants.map { |m| participant_to_canonical(m, :reactant) }
+        )
+      end
+
+      def product_list_to_canonical(products)
+        Chemicalml::Model::ProductList.new(
+          products: products.map { |m| participant_to_canonical(m, :product) }
+        )
+      end
+
+      def participant_to_canonical(molecule, role)
+        Chemicalml::Model::Reactant.new(
+          substance: Chemicalml::Model::Substance.new(
+            molecule: molecule_to_canonical(molecule),
+            role: role
+          )
+        )
+      end
+
+      def conditions_above(reaction)
+        reaction.conditions&.above
+      end
+
+      def conditions_below(reaction)
+        reaction.conditions&.below
+      end
+
+      # Walks an AsciiChem::Model::Molecule and produces an ordered
+      # atom list + a bond list with proper atomRefs. The walker is
+      # the single source of truth for atom ID assignment — bonds,
+      # reactants, and products all reference the IDs it produces.
+      # Also exposes `atom_mapping` (canonical_id => source Atom) so
+      # downstream consumers (CML extension serializer, debug tools)
+      # can match canonical atoms back to their AsciiChem source, and
+      # `groups` (per-molecule list of group structure records) so the
+      # aci: extension can preserve grouping through CML round-trip.
+      class MoleculeWalker
+        attr_reader :atom_mapping, :groups
+
+        def initialize(ids)
+          @ids = ids
+          @atoms = []
+          @bonds = []
+          @atom_mapping = {}
+          @atom_id_by_object_id = {}
+          @groups = []
+          @group_stack = []
+          @pending_bond_kind = nil
+          @last_atom_id = nil
+        end
+
+        def walk(molecule)
+          walk_nodes(molecule.nodes, multiplier: nil)
+          emit_ring_bonds(molecule)
+          [@atoms, @bonds]
+        end
+
+        # Emit canonical bonds for each ring-closure pair on atoms
+        # in this molecule. The walker has already assigned IDs to
+        # every atom; RingBonds.each_in yields pairs which we look up
+        # in @atom_id_by_object_id to translate Ruby object identity
+        # into canonical atom IDs. Skips pairs that already have a
+        # positional bond between them (degenerate case like `C1-C1`).
+        def emit_ring_bonds(molecule)
+          existing_pair_keys = @bonds.map { |b| pair_key(b.atom_refs) }.to_set
+          AsciiChem::RingBonds.each_in(molecule) do |ring_bond|
+            from_id = @atom_id_by_object_id[ring_bond.from_atom.object_id]
+            to_id = @atom_id_by_object_id[ring_bond.to_atom.object_id]
+            next unless from_id && to_id
+
+            key = pair_key([from_id, to_id])
+            next if existing_pair_keys.include?(key)
+
+            @bonds << Chemicalml::Model::Bond.new(
+              id: @ids.next(:bond),
+              atom_refs: [from_id, to_id],
+              kind: :single
+            )
+            existing_pair_keys << key
+          end
+        end
+
+        # Order-independent key for a pair of atom IDs, so a-b and b-a
+        # compare equal.
+        def pair_key(refs)
+          refs.sort.join(":")
+        end
+
+        private
+
+        def walk_nodes(nodes, multiplier:)
+          nodes.each do |node|
+            case node
+            when AsciiChem::Model::Atom
+              emit_atom(node, multiplier)
+            when AsciiChem::Model::Bond
+              @pending_bond_kind = node.kind
+            when AsciiChem::Model::Group
+              enter_group(node, multiplier)
+            when AsciiChem::Model::Molecule
+              walk_nodes(node.nodes, multiplier: combine(multiplier, node.coefficient))
+            end
+          end
+        end
+
+        def enter_group(group, multiplier)
+          record = GroupRecord.new(
+            id: @ids.next(:group),
+            multiplicity: group.multiplicity,
+            bracket: group.bracket,
+            atom_ids: []
+          )
+          @groups << record
+          @group_stack.push(record)
+          walk_nodes(group.nodes, multiplier: combine(multiplier, group.multiplicity))
+          @group_stack.pop
+        end
+
+        def emit_atom(atom, multiplier)
+          id = @ids.next(:atom)
+          @atom_mapping[id] = atom
+          @atom_id_by_object_id[atom.object_id] = id
+          @group_stack.each { |record| record.atom_ids << id }
+          attrs = {
+            id: id,
+            element: atom.element,
+            isotope: atom.isotope,
+            formal_charge: atom.charge,
+            count: effective_count(atom, multiplier),
+            lone_pairs: atom.lone_pairs,
+            radical_electrons: atom.radical_electrons
+          }
+          merge_coordinates(attrs, atom)
+          @atoms << Chemicalml::Model::Atom.new(**attrs)
+          emit_pending_bond(id) if @pending_bond_kind && @last_atom_id
+          @last_atom_id = id
+          @pending_bond_kind = nil
+        end
+
+        def emit_pending_bond(next_atom_id)
+          @bonds << Chemicalml::Model::Bond.new(
+            id: @ids.next(:bond),
+            atom_refs: [@last_atom_id, next_atom_id],
+            kind: @pending_bond_kind,
+            bond_stereo: bond_stereo_for(@pending_bond_kind)
+          )
+        end
+
+        # CML bondStereo codes for stereo bonds. Wedge (coming out of
+        # page) → "W"; hash (going into page) → "H". Other bond kinds
+        # have no stereo meaning.
+        BOND_STEREO_CODES = { wedge: "W", hash: "H" }.freeze
+
+        def bond_stereo_for(kind)
+          code = BOND_STEREO_CODES[kind]
+          return nil unless code
+
+          Chemicalml::Model::BondStereo.new(value: code)
+        end
+
+        def effective_count(atom, multiplier)
+          sub = atom.subscript
+          return combine(multiplier, sub) if multiplier
+          return sub if sub
+
+          nil
+        end
+
+        # Map AsciiChem 2D/3D coordinates onto canonical atom attrs.
+        # If z2 is present, it's 3D → x3/y3/z3. Otherwise 2D → x2/y2.
+        def merge_coordinates(attrs, atom)
+          return unless atom.x2 && atom.y2
+
+          if atom.z2
+            attrs[:x3] = atom.x2
+            attrs[:y3] = atom.y2
+            attrs[:z3] = atom.z2
+          else
+            attrs[:x2] = atom.x2
+            attrs[:y2] = atom.y2
+          end
+        end
+
+        def combine(left, right)
+          lv = integer_or_nil(left)
+          rv = integer_or_nil(right)
+          return nil unless lv || rv
+
+          (lv || 1) * (rv || 1)
+        end
+
+        def integer_or_nil(value)
+          return nil if value.nil? || value.to_s.empty?
+
+          Integer(value, exception: false)
+        end
+      end
+      private_constant :MoleculeWalker
+
+      # Captures the structure of an AsciiChem::Model::Group during
+      # the canonical walk. The walker assigns IDs to atoms in source
+      # order; the GroupRecord lists which atoms were inside the group
+      # (transitively, for nested groups). Used by `Cml::GroupExtensions`
+      # to preserve grouping through the canonical model.
+      GroupRecord = Struct.new(:id, :multiplicity, :bracket, :atom_ids, keyword_init: true)
+      private_constant :GroupRecord
+
+      # Per-build ID registry. Issues stable IDs within a single
+      # translation pass (a1, a2, b1, m1, r1, ...) so re-running the
+      # adapter on equivalent input yields byte-equal output.
+      class IdRegistry
+        PREFIXES = { atom: "a", bond: "b", molecule: "m",
+                     reaction: "r", group: "g" }.freeze
+
+        def initialize
+          @counters = Hash.new(0)
+        end
+
+        def next(kind)
+          @counters[kind] += 1
+          "#{PREFIXES.fetch(kind)}#{@counters[kind]}"
+        end
+      end
+      private_constant :IdRegistry
+    end
+  end
+end

data/lib/asciichem/model_adapter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Adapter between AsciiChem::Model (the chemistry-semantic tree the
+  # text parser produces) and Chemicalml::Model (the format-agnostic
+  # canonical hub every chemistry interchange format speaks).
+  #
+  # The adapter is bidirectional and pure — no I/O, no wire format
+  # concerns. Composed with `Chemicalml::Cml::Translator` it forms the
+  # AsciiChem <-> CML pipeline:
+  #
+  #   AsciiChem::Model <-> ModelAdapter <-> Chemicalml::Model
+  #                                                ^
+  #                                                |
+  #                                       Chemicalml::Cml::Translator
+  #                                                |
+  #                                                v
+  #                                       Chemicalml::Cml::* (wire)
+  #
+  # Adding a new field to either model means updating this adapter's
+  # mapping rules; the parsers, formatters, and wire classes stay
+  # independent.
+  module ModelAdapter
+    autoload :ToCanonical, "asciichem/model_adapter/to_canonical"
+    autoload :FromCanonical, "asciichem/model_adapter/from_canonical"
+
+    # Result of a translation that also exposes the per-atom mapping
+    # (canonical_atom_id => AsciiChem::Model::Atom) and the per-molecule
+    # group structure (molecule_id => Array<GroupRecord>). Used by
+    # callers that need to track per-atom side data through the
+    # canonical pipeline (e.g. the CML extension namespace).
+    Translation = Struct.new(:document, :atom_mapping, :groups, keyword_init: true)
+
+    def self.to_canonical(formula)
+      ToCanonical.new(formula).build
+    end
+
+    # Returns the canonical document plus the per-atom mapping and
+    # per-molecule group structure. Use this when you need to know
+    # which canonical atom corresponds to which AsciiChem::Model::Atom
+    # or which atoms were originally grouped (e.g. for extension data).
+    def self.to_canonical_with_mapping(formula)
+      builder = ToCanonical.new(formula)
+      document = builder.build
+      Translation.new(
+        document: document,
+        atom_mapping: builder.atom_mapping,
+        groups: builder.groups
+      )
+    end
+
+    def self.from_canonical(document)
+      FromCanonical.new(document).build
+    end
+  end
+end

data/lib/asciichem/parser.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  class Parser
+    attr_reader :text
+
+    def initialize(text)
+      @text = text.to_s
+    end
+
+    def parse
+      tree = AsciiChem::Grammar.new.parse(text)
+      AsciiChem::Transform.new.apply(tree)
+    rescue Parslet::ParseFailed => e
+      raise AsciiChem::ParseError, format_error(e)
+    end
+
+    private
+
+    def format_error(error)
+      pos = error.message.match(/char (\d+)/)
+      char = pos ? pos[1].to_i : 0
+      snippet = text[[char - 10, 0].max, 20] || text
+      pointer = " " * (char - [char - 10, 0].max) + "^"
+      expected = extract_expected(error.message)
+      "Parse error at char #{char}: expected #{expected}\n" \
+        "  ...#{snippet}...\n" \
+        "  #{pointer}"
+    end
+
+    def extract_expected(message)
+      match = message.match(/Expected:? (.+?)(?:\s+at|\s*$)/)
+      match ? match[1].strip : "valid AsciiChem syntax"
+    end
+  end
+end

data/lib/asciichem/periodic_table.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Periodic table as a single source of truth for element data.
+  # Used by linter checks (element validation, isotope sanity, valence)
+  # and any future code that needs chemically-grounded defaults.
+  #
+  # Adding a new field (e.g. covalent radius for layout, common
+  # oxidation states for redox checks) means adding one column to
+  # `Element` and populating it across `ELEMENTS` — no other code
+  # changes.
+  module PeriodicTable
+    Element = Struct.new(:symbol, :atomic_number, :max_valence, keyword_init: true)
+
+    # Subset covering the elements chemistry most commonly deals with.
+    # Each entry: symbol => Element. Adding more elements is one
+    # line per element; the linter picks them up automatically.
+    ELEMENTS = {
+      # Period 1
+      "H"  => Element.new(symbol: "H",  atomic_number: 1,  max_valence: 1),
+      "He" => Element.new(symbol: "He", atomic_number: 2,  max_valence: 0),
+      # Period 2
+      "Li" => Element.new(symbol: "Li", atomic_number: 3,  max_valence: 1),
+      "Be" => Element.new(symbol: "Be", atomic_number: 4,  max_valence: 2),
+      "B"  => Element.new(symbol: "B",  atomic_number: 5,  max_valence: 3),
+      "C"  => Element.new(symbol: "C",  atomic_number: 6,  max_valence: 4),
+      "N"  => Element.new(symbol: "N",  atomic_number: 7,  max_valence: 3),
+      "O"  => Element.new(symbol: "O",  atomic_number: 8,  max_valence: 2),
+      "F"  => Element.new(symbol: "F",  atomic_number: 9,  max_valence: 1),
+      "Ne" => Element.new(symbol: "Ne", atomic_number: 10, max_valence: 0),
+      # Period 3
+      "Na" => Element.new(symbol: "Na", atomic_number: 11, max_valence: 1),
+      "Mg" => Element.new(symbol: "Mg", atomic_number: 12, max_valence: 2),
+      "Al" => Element.new(symbol: "Al", atomic_number: 13, max_valence: 3),
+      "Si" => Element.new(symbol: "Si", atomic_number: 14, max_valence: 4),
+      "P"  => Element.new(symbol: "P",  atomic_number: 15, max_valence: 5),
+      "S"  => Element.new(symbol: "S",  atomic_number: 16, max_valence: 6),
+      "Cl" => Element.new(symbol: "Cl", atomic_number: 17, max_valence: 1),
+      "Ar" => Element.new(symbol: "Ar", atomic_number: 18, max_valence: 0),
+      # Period 4 (common)
+      "K"  => Element.new(symbol: "K",  atomic_number: 19, max_valence: 1),
+      "Ca" => Element.new(symbol: "Ca", atomic_number: 20, max_valence: 2),
+      "Sc" => Element.new(symbol: "Sc", atomic_number: 21, max_valence: 3),
+      "Ti" => Element.new(symbol: "Ti", atomic_number: 22, max_valence: 4),
+      "V"  => Element.new(symbol: "V",  atomic_number: 23, max_valence: 5),
+      "Cr" => Element.new(symbol: "Cr", atomic_number: 24, max_valence: 6),
+      "Mn" => Element.new(symbol: "Mn", atomic_number: 25, max_valence: 7),
+      "Fe" => Element.new(symbol: "Fe", atomic_number: 26, max_valence: 6),
+      "Co" => Element.new(symbol: "Co", atomic_number: 27, max_valence: 4),
+      "Ni" => Element.new(symbol: "Ni", atomic_number: 28, max_valence: 4),
+      "Cu" => Element.new(symbol: "Cu", atomic_number: 29, max_valence: 4),
+      "Zn" => Element.new(symbol: "Zn", atomic_number: 30, max_valence: 2),
+      "Ga" => Element.new(symbol: "Ga", atomic_number: 31, max_valence: 3),
+      "Ge" => Element.new(symbol: "Ge", atomic_number: 32, max_valence: 4),
+      "As" => Element.new(symbol: "As", atomic_number: 33, max_valence: 3),
+      "Se" => Element.new(symbol: "Se", atomic_number: 34, max_valence: 2),
+      "Br" => Element.new(symbol: "Br", atomic_number: 35, max_valence: 1),
+      "Kr" => Element.new(symbol: "Kr", atomic_number: 36, max_valence: 0),
+      # Period 5 (common)
+      "Rb" => Element.new(symbol: "Rb", atomic_number: 37, max_valence: 1),
+      "Sr" => Element.new(symbol: "Sr", atomic_number: 38, max_valence: 2),
+      "Y"  => Element.new(symbol: "Y",  atomic_number: 39, max_valence: 3),
+      "Zr" => Element.new(symbol: "Zr", atomic_number: 40, max_valence: 4),
+      "Nb" => Element.new(symbol: "Nb", atomic_number: 41, max_valence: 5),
+      "Mo" => Element.new(symbol: "Mo", atomic_number: 42, max_valence: 6),
+      "Tc" => Element.new(symbol: "Tc", atomic_number: 43, max_valence: 6),
+      "Ru" => Element.new(symbol: "Ru", atomic_number: 44, max_valence: 6),
+      "Rh" => Element.new(symbol: "Rh", atomic_number: 45, max_valence: 6),
+      "Pd" => Element.new(symbol: "Pd", atomic_number: 46, max_valence: 4),
+      "Ag" => Element.new(symbol: "Ag", atomic_number: 47, max_valence: 4),
+      "Cd" => Element.new(symbol: "Cd", atomic_number: 48, max_valence: 2),
+      "In" => Element.new(symbol: "In", atomic_number: 49, max_valence: 3),
+      "Sn" => Element.new(symbol: "Sn", atomic_number: 50, max_valence: 4),
+      "Sb" => Element.new(symbol: "Sb", atomic_number: 51, max_valence: 3),
+      "Te" => Element.new(symbol: "Te", atomic_number: 52, max_valence: 2),
+      "I"  => Element.new(symbol: "I",  atomic_number: 53, max_valence: 1),
+      "Xe" => Element.new(symbol: "Xe", atomic_number: 54, max_valence: 0),
+      # Period 6 (common)
+      "Cs" => Element.new(symbol: "Cs", atomic_number: 55, max_valence: 1),
+      "Ba" => Element.new(symbol: "Ba", atomic_number: 56, max_valence: 2),
+      "W"  => Element.new(symbol: "W",  atomic_number: 74, max_valence: 6),
+      "Pt" => Element.new(symbol: "Pt", atomic_number: 78, max_valence: 4),
+      "Au" => Element.new(symbol: "Au", atomic_number: 79, max_valence: 6),
+      "Hg" => Element.new(symbol: "Hg", atomic_number: 80, max_valence: 2),
+      "Tl" => Element.new(symbol: "Tl", atomic_number: 81, max_valence: 3),
+      "Pb" => Element.new(symbol: "Pb", atomic_number: 82, max_valence: 4),
+      "Bi" => Element.new(symbol: "Bi", atomic_number: 83, max_valence: 3),
+      # Period 7 (common)
+      "U"  => Element.new(symbol: "U",  atomic_number: 92, max_valence: 6)
+    }.freeze
+
+    def self.element(symbol)
+      ELEMENTS[symbol.to_s]
+    end
+
+    def self.known?(symbol)
+      ELEMENTS.key?(symbol.to_s)
+    end
+
+    def self.atomic_number(symbol)
+      element(symbol.to_s)&.atomic_number
+    end
+
+    def self.max_valence(symbol)
+      element(symbol.to_s)&.max_valence
+    end
+
+    def self.symbols
+      ELEMENTS.keys
+    end
+  end
+end