asciichem 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82e379bdd585e67154ee2ac11685d34d343fc7603dad41c8e629d27610f66a0e
-  data.tar.gz: 443e0c865b127e706b61ec9d8781b3516aecb8dfb86a83630e1363af5ae52779
+  metadata.gz: 7d401ee7215f54961b4126b1da5451a2e71ac316c05e3864d199c5482e28d366
+  data.tar.gz: c132a8c376dd7485bf0319f8d971d89cb952c27d9f2466c0f3af4af945b0ca4b
 SHA512:
-  metadata.gz: 1dca3abf1149dbbeb1166053cdc6afd58e90c4ad1635c5d13a8884aa11e00b1f43dbdadda6a860d5110dc3924f1ce8f01cba41992faaabbe5bd8a5b05382cdf6
-  data.tar.gz: 2fb960db615687093e7cb30f70752303d1b143fc9c3af8cd582d0fef7afcff00e45feabe88769bbb8f6af6431171b3b431d2689339a1d52903f21f397acc23a3
+  metadata.gz: ab9ee8f2410f46c659cc97426a7272c511e983b601cbf043809c5b657621f0d7a48e79f17c2c4f79707cfebaf265e963077a5f636d8e03c87be2942e4fddc27e
+  data.tar.gz: 1cf4d97ef6459a29b9d7f05ddbd8b8b1db0ca512f547cb48badd7ebb5abc42f9c70c98cdade086af9dedf48f2e16c96ddd199097ee90c3e2ba56984e66a91aa7

data/TODO.beyond-formulas/01-crystallography.md

@@ -0,0 +1,69 @@
+# 01 — Crystallography: unit cell and space group
+
+- **Priority:** P1
+- **Status:** in progress
+
+## Motivation
+
+Crystallography is the foundation of materials science. CML's
+`<crystal>`, `<scalar>` (for a/b/c/α/β/γ), and `<symmetry>` elements
+capture crystal structures. An ASCII encoding is dramatically more
+readable than XML:
+
+```
+crystal[NaCl](a=5.64,b=5.64,c=5.64,alpha=90,beta=90,gamma=90,sg=Fm-3m){
+  Na@f(0,0,0)
+  Cl@f(0.5,0.5,0.5)
+}
+```
+
+vs CML's verbose `<crystal><scalar title="a">5.64</scalar>...`.
+
+## Syntax design
+
+```
+crystal[<name>](
+  a=<float>, b=<float>, c=<float>,
+  alpha=<float>, beta=<float>, gamma=<float>,
+  sg=<spacegroup>
+) {
+  <atoms with @f(x,y,z) fractional coords>
+}
+```
+
+- `crystal` is a keyword (not an element symbol — parsed before
+  molecule).
+- Square brackets carry the optional crystal name/title.
+- Parentheses carry unit cell parameters as `key=value` pairs.
+- Curly braces carry the asymmetric unit atoms with fractional coords.
+- `sg` is the Hermann-Mauguin space group symbol.
+
+## Model
+
+```ruby
+class Crystal < Node
+  attr_accessor :name, :a, :b, :c, :alpha, :beta, :gamma,
+                :spacegroup, :atoms
+end
+```
+
+Atoms inside a crystal use `@f(x,y,z)` fractional coordinates
+(already implemented in v0.3.4).
+
+## CML mapping
+
+- `Crystal` → `<crystal>` with child `<scalar>` elements for cell
+  parameters and `<symmetry>` for space group.
+- Atoms with fractional coords → `<atom xFract="..." yFract="..."`
+  zFract="..."/> inside `<atomArray>`.
+- The crystal is a child of `<molecule>` (CML convention: crystal
+  structures live inside molecules).
+
+## Acceptance criteria
+
+- [ ] `crystal[NaCl](...)` parses to a Crystal model node
+- [ ] Text round-trip: `parse(s).to_text == s`
+- [ ] CML round-trip: `parse(s).to_cml → parse → .to_text == s`
+- [ ] Cell parameters carry through as CML `<scalar>` elements
+- [ ] Space group carries as CML `<symmetry>` element
+- [ ] Fractional coordinates on atoms (already supported)

data/TODO.beyond-formulas/02-spectroscopy.md

@@ -0,0 +1,39 @@
+# 02 — Spectroscopy: NMR / IR / MS spectra
+
+- **Priority:** P2
+- **Status:** pending
+
+## Syntax
+
+```
+spectrum[nmr](type=1H,solvent=CDCl3,freq=400){
+  1.2: 3H s "CH3"
+  3.5: 2H q J=7 "CH2"
+  7.2: 5H m "C6H5"
+}
+
+spectrum[ir]{
+  3300: broad "O-H stretch"
+  1700: strong "C=O stretch"
+}
+
+spectrum[ms]{
+  18: 100% "M+"
+  17: 23% "M-1"
+}
+```
+
+## Model
+
+```ruby
+class Spectrum < Node
+  attr_accessor :type, :params, :peaks
+  # peaks: [{position:, intensity:, multiplicity:, assignment:}, ...]
+end
+```
+
+## CML mapping
+
+Maps to `<spectrum>` with `<peakList>` containing `<peak>` children.
+CML peak attributes: `xValue`, `xUnits`, `yValue`, `yUnits`,
+`atomRefs`, `title`.

data/TODO.beyond-formulas/03-compchem.md

@@ -0,0 +1,31 @@
+# 03 — Computational chemistry: QC calculation results
+
+- **Priority:** P2
+- **Status:** pending
+
+## Syntax
+
+```
+calc(dft, b3lyp/6-31G*){
+  energy: -234.5 Hartree
+  dipole: [0.1, 0.2, 0.3] Debye
+  homo: -0.32 Hartree
+  lumo: 0.15 Hartree
+  gap: 0.47 Hartree
+  zpe: 0.05 Hartree
+}
+```
+
+## Model
+
+```ruby
+class Calculation < Node
+  attr_accessor :method, :basis, :properties
+  # properties: [{title:, value:, units:}, ...]
+end
+```
+
+## CML mapping
+
+Maps to `<module convention="convention:compchem">` containing
+`<parameterList>` (method/basis) and `<propertyList>` (results).

data/TODO.beyond-formulas/04-structural.md

@@ -0,0 +1,48 @@
+# 04 — Structural extensions: Z-Matrix and fragments
+
+- **Priority:** P3
+- **Status:** pending
+
+## Syntax
+
+### Z-Matrix
+
+```
+zmatrix{
+  C1
+  H2  C1  1.09
+  H3  C1  1.09  H2  109.5
+  H4  C1  1.09  H2  109.5  H3  120.0
+}
+```
+
+Each line: atom, reference atom, bond length, [reference atom, angle,
+[reference atom, dihedral]].
+
+### Fragments
+
+```
+fragment(phenyl){
+  C1-C2=C3-C4=C5-C6=1
+}
+```
+
+Named structural fragments that can be referenced by other molecules.
+
+## Model
+
+```ruby
+class ZMatrix < Node
+  attr_accessor :rows
+  # rows: [{atom:, ref1:, r12:, ref2:, angle:, ref3:, dihedral:}, ...]
+end
+
+class Fragment < Node
+  attr_accessor :name, :molecule
+end
+```
+
+## CML mapping
+
+ZMatrix → `<zMatrix>` with rows as `<atom>` references.
+Fragment → `<fragment>` containing a `<molecule>`.

data/TODO.beyond-formulas/05-mechanisms.md

@@ -0,0 +1,40 @@
+# 05 — Reaction mechanisms and spectators
+
+- **Priority:** P3
+- **Status:** pending
+
+## Syntax
+
+### Reaction mechanism
+
+```
+mechanism{
+  step1: Cl- + CH3Br -> [TS: Cl...C...Br] -> ClCH3 + Br-
+  step2: ClCH3 + Na+ -> CH3Cl + Na+
+  spectator: Na+
+}
+```
+
+### Spectator ions
+
+```
+Ag+(aq) + Cl-(aq) -> AgCl(s) | spectator: Na+(aq) NO3-(aq)
+```
+
+Inline notation: `| spectator: <atoms>` after the reaction.
+
+## Model
+
+```ruby
+class Mechanism < Node
+  attr_accessor :steps, :spectators, :reactive_centre
+  # steps: [{label:, transition_state:, reaction:}, ...]
+end
+```
+
+## CML mapping
+
+Mechanism → `<reactionScheme>` with `<reactionStepList>`
+containing `<reactionStep>` children.
+Spectators → `<spectatorList>` with `<spectator>` children.
+ReactiveCentre → `<reactiveCentre>` with atom references.

data/TODO.beyond-formulas/README.md

@@ -0,0 +1,69 @@
+# TODO.beyond-formulas index
+
+Expanding AsciiChem beyond molecular formulas into the full CML
+domain. Each workstream adds a new construct type with grammar,
+model, formatter, and CML round-trip support.
+
+## Phase 1: Crystallography
+
+| # | Title | Status |
+|---|---|---|
+| 01 | [Crystallography — unit cell and space group](01-crystallography.md) | **in progress** |
+
+Syntax: `crystal[NaCl](a=5.64,b=5.64,c=5.64,alpha=90,beta=90,gamma=90,sg=Fm-3m){Na@f(0,0,0) Cl@f(0.5,0.5,0.5)}`
+
+## Phase 2: Spectroscopy
+
+| # | Title | Status |
+|---|---|---|
+| 02 | [NMR / IR / MS spectra](02-spectroscopy.md) | pending |
+
+Syntax:
+```
+spectrum[nmr](type=1H,solvent=CDCl3){
+  1.2: 3H s "CH3"
+  7.2: 5H m "ArH"
+}
+```
+
+## Phase 3: Computational Chemistry
+
+| # | Title | Status |
+|---|---|---|
+| 03 | [QC calculation results](03-compchem.md) | pending |
+
+Syntax: `calc(b3lyp/6-31G*){energy:-234.5 dipole:[0.1,0.2,0.3]}`
+
+## Phase 4: Structural Extensions
+
+| # | Title | Status |
+|---|---|---|
+| 04 | [Z-Matrix and fragments](04-structural.md) | pending |
+
+Syntax:
+```
+zmatrix{C1; H2 C1 1.09; H3 C1 1.09 H2 109.5}
+fragment(phenyl){C1-C2=C3-C4=C5-C6=1}
+```
+
+## Phase 5: Reaction Mechanisms
+
+| # | Title | Status |
+|---|---|---|
+| 05 | [Mechanisms and spectators](05-mechanisms.md) | pending |
+
+Syntax: `mechanism{step: A->[TS:B*]->C; spectator:Na+}`
+
+## Architecture
+
+Each domain adds:
+1. A new `Model::*` class (autoload from `lib/asciichem/model/`)
+2. A grammar rule in `grammar.rb`
+3. A transform rule in `transform.rb`
+4. `visit_*` methods on formatters (Text, CML, others as needed)
+5. ModelAdapter mapping to `Chemicalml::Cml::*` wire classes
+6. Specs
+
+The OCP principle: each domain is a self-contained construct that
+plugs into the existing `Formula` → `nodes` array. No changes to
+existing model classes.

data/lib/asciichem/formatter/text.rb

@@ -123,6 +123,23 @@ module AsciiChem
         %("#{text.content}")
       end
 
+      def visit_crystal(crystal)
+        parts = ["crystal"]
+        parts << "[#{crystal.name}]" if crystal.name
+        params = []
+        params << "a=#{crystal.a}" if crystal.a
+        params << "b=#{crystal.b}" if crystal.b
+        params << "c=#{crystal.c}" if crystal.c
+        params << "alpha=#{crystal.alpha}" if crystal.alpha
+        params << "beta=#{crystal.beta}" if crystal.beta
+        params << "gamma=#{crystal.gamma}" if crystal.gamma
+        params << "sg=#{crystal.spacegroup}" if crystal.spacegroup
+        parts << "(#{params.join(',')})" unless params.empty?
+        atom_strs = crystal.atoms.map { |a| render_node(a) }
+        parts << "{#{atom_strs.join(' ')}}" unless atom_strs.empty?
+        parts.join
+      end
+
       private
 
       def render_node(node)

data/lib/asciichem/grammar.rb

@@ -27,7 +27,29 @@ module AsciiChem
 
     rule(:nodes) { node >> (spaces? >> node).repeat }
 
-    rule(:node)  { reaction_cascade | reaction | electron_config | annotated_molecule | molecule | embedded_math | text_run.as(:text_run) }
+    rule(:node)  { reaction_cascade | reaction | electron_config | crystal | annotated_molecule | molecule | embedded_math | text_run.as(:text_run) }
+
+    # -- crystallography -------------------------------------------------
+
+    # crystal[Name](a=X,b=Y,...,sg=SG){atoms with @f(x,y,z)}
+    rule(:crystal) do
+      str('crystal') >>
+        crystal_name.maybe >>
+        crystal_params.maybe >>
+        crystal_body.maybe
+    end
+
+    rule(:crystal_name) do
+      str('[') >> (str(']').absent? >> any).repeat.as(:crystal_name) >> str(']')
+    end
+
+    rule(:crystal_params) do
+      str('(') >> (str(')').absent? >> any).repeat.as(:crystal_params) >> str(')')
+    end
+
+    rule(:crystal_body) do
+      str('{') >> (str('}').absent? >> any).repeat.as(:crystal_body) >> str('}')
+    end
 
     # Annotated molecule: a molecule followed by one or more
     # `@key("value")` annotations for CML metadata (names,

data/lib/asciichem/model/crystal.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A crystal structure: unit cell parameters + space group +
+    # asymmetric-unit atoms with fractional coordinates.
+    #
+    # Syntax:
+    #   crystal[NaCl](a=5.64,b=5.64,c=5.64,alpha=90,beta=90,gamma=90,sg=Fm-3m){
+    #     Na@f(0,0,0)
+    #     Cl@f(0.5,0.5,0.5)
+    #   }
+    class Crystal < Node
+      attr_accessor :name, :a, :b, :c, :alpha, :beta, :gamma,
+                    :spacegroup, :atoms
+
+      def initialize(name: nil, a: nil, b: nil, c: nil,
+                     alpha: nil, beta: nil, gamma: nil,
+                     spacegroup: nil, atoms: [])
+        @name = name
+        @a = a
+        @b = b
+        @c = c
+        @alpha = alpha
+        @beta = beta
+        @gamma = gamma
+        @spacegroup = spacegroup
+        @atoms = atoms
+      end
+
+      def value_attributes
+        { name: name, a: a, b: b, c: c, alpha: alpha,
+          beta: beta, gamma: gamma, spacegroup: spacegroup,
+          atoms: atoms }
+      end
+
+      def children
+        atoms
+      end
+
+      def diagnostic_label
+        "Crystal(#{name || 'unnamed'})"
+      end
+
+      def to_s
+        params = []
+        params << "a=#{a}" if a
+        params << "b=#{b}" if b
+        params << "c=#{c}" if c
+        params << "alpha=#{alpha}" if alpha
+        params << "beta=#{beta}" if beta
+        params << "gamma=#{gamma}" if gamma
+        params << "sg=#{spacegroup}" if spacegroup
+        "crystal[#{name}](#{params.join(',')}){#{atoms.map(&:to_s).join(' ')}}"
+      end
+    end
+  end
+end

data/lib/asciichem/model.rb

@@ -8,6 +8,7 @@ module AsciiChem
   module Model
     autoload :Atom, "asciichem/model/atom"
     autoload :Bond, "asciichem/model/bond"
+    autoload :Crystal, "asciichem/model/crystal"
     autoload :ElectronConfiguration, "asciichem/model/electron_configuration"
     autoload :EmbeddedMath, "asciichem/model/embedded_math"
     autoload :Formula, "asciichem/model/formula"

data/lib/asciichem/transform.rb

@@ -146,8 +146,75 @@ module AsciiChem
       Model::ElectronConfiguration.new(orbitals: pairs)
     end
 
+    # -- crystals -------------------------------------------------------
+    #
+    # Grammar captures crystal_name, crystal_params, and crystal_body
+    # as optional strings. CrystalBuilder parses them into the model.
+
+    rule(crystal_name: subtree(:name),
+         crystal_params: subtree(:params),
+         crystal_body: subtree(:body)) do
+      CrystalBuilder.new(name, params, body).build
+    end
+
     # -- internal helpers ------------------------------------------------
 
+    # Builds a Crystal from parsed grammar captures. The grammar
+    # captures the name, params, and body as raw strings; this class
+    # parses them into the model fields.
+    class CrystalBuilder
+      def initialize(name, params_str, body_str)
+        @name = strip_parslet(name)
+        @params_str = strip_parslet(params_str)
+        @body_str = strip_parslet(body_str)
+      end
+
+      def build
+        params = parse_params(@params_str)
+        atoms = parse_atoms(@body_str)
+        Model::Crystal.new(
+          name: @name,
+          a: params['a'],
+          b: params['b'],
+          c: params['c'],
+          alpha: params['alpha'],
+          beta: params['beta'],
+          gamma: params['gamma'],
+          spacegroup: params['sg'],
+          atoms: atoms
+        )
+      end
+
+      private
+
+      def strip_parslet(value)
+        return nil if value.nil?
+
+        s = value.to_s.strip
+        s.empty? ? nil : s
+      end
+
+      def parse_params(str)
+        return {} unless str
+
+        str.split(',').each_with_object({}) do |pair, memo|
+          key, val = pair.strip.split('=', 2)
+          memo[key] = val&.strip if key
+        end
+      end
+
+      def parse_atoms(str)
+        return [] unless str
+
+        formula = AsciiChem.parse(str)
+        formula.nodes.flat_map do |node|
+          next [] unless node.is_a?(Model::Molecule)
+
+          node.nodes.select { |n| n.is_a?(Model::Atom) }
+        end
+      end
+    end
+
     # Strips the surrounding `"..."` quotes from a quoted text match.
     # Used by both `text_run` and `group_text_run` rules so the
     # model never carries the delimiters — the formatter re-adds them

data/lib/asciichem/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -114,6 +114,12 @@ files:
 - README.adoc
 - RELEASING.md
 - Rakefile
+- TODO.beyond-formulas/01-crystallography.md
+- TODO.beyond-formulas/02-spectroscopy.md
+- TODO.beyond-formulas/03-compchem.md
+- TODO.beyond-formulas/04-structural.md
+- TODO.beyond-formulas/05-mechanisms.md
+- TODO.beyond-formulas/README.md
 - asciichem.gemspec
 - benchmarks/RESULTS.md
 - benchmarks/benchmark.rb
@@ -149,6 +155,7 @@ files:
 - lib/asciichem/model.rb
 - lib/asciichem/model/atom.rb
 - lib/asciichem/model/bond.rb
+- lib/asciichem/model/crystal.rb
 - lib/asciichem/model/electron_configuration.rb
 - lib/asciichem/model/embedded_math.rb
 - lib/asciichem/model/formula.rb