chemicalml 0.1.0

data/lib/chemicalml/cml.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # CML model layer. The wire classes live under `Schema3::` and
+  # `Schema24::` namespaces; the top-level `Cml::*` constants are
+  # backward-compatible aliases pointing at the Schema3 versions.
+  # Shared attribute + xml-mapping declarations live under `Base::*`
+  # and are included by both schema-versioned class hierarchies.
+  module Cml
+    autoload :Array, "chemicalml/cml/array"
+    autoload :Atom, "chemicalml/cml/atom"
+    autoload :AtomArray, "chemicalml/cml/atom_array"
+    autoload :AtomParity, "chemicalml/cml/atom_parity"
+    autoload :Base, "chemicalml/cml/base"
+    autoload :Bond, "chemicalml/cml/bond"
+    autoload :BondArray, "chemicalml/cml/bond_array"
+    autoload :BondStereo, "chemicalml/cml/bond_stereo"
+    autoload :Dictionary, "chemicalml/cml/dictionary"
+    autoload :DictionaryEntry, "chemicalml/cml/dictionary_entry"
+    autoload :Document, "chemicalml/cml/document"
+    autoload :Elements, "chemicalml/cml/elements"
+    autoload :Formula, "chemicalml/cml/formula"
+    autoload :Identifier, "chemicalml/cml/identifier"
+    autoload :Label, "chemicalml/cml/label"
+    autoload :List, "chemicalml/cml/list"
+    autoload :Matrix, "chemicalml/cml/matrix"
+    autoload :Metadata, "chemicalml/cml/metadata"
+    autoload :MetadataList, "chemicalml/cml/metadata_list"
+    autoload :Module, "chemicalml/cml/cml_module"
+    autoload :Molecule, "chemicalml/cml/molecule"
+    autoload :Name, "chemicalml/cml/name"
+    autoload :Namespace, "chemicalml/cml/namespace"
+    autoload :Parameter, "chemicalml/cml/parameter"
+    autoload :ParameterList, "chemicalml/cml/parameter_list"
+    autoload :Product, "chemicalml/cml/product"
+    autoload :ProductList, "chemicalml/cml/product_list"
+    autoload :Property, "chemicalml/cml/property"
+    autoload :PropertyList, "chemicalml/cml/property_list"
+    autoload :Reaction, "chemicalml/cml/reaction"
+    autoload :ReactionList, "chemicalml/cml/reaction_list"
+    autoload :Reactant, "chemicalml/cml/reactant"
+    autoload :ReactantList, "chemicalml/cml/reactant_list"
+    autoload :Role, "chemicalml/cml/role"
+    autoload :Scalar, "chemicalml/cml/scalar"
+    autoload :Schema3, "chemicalml/cml/schema3"
+    autoload :Schema24, "chemicalml/cml/schema24"
+    autoload :Substance, "chemicalml/cml/substance"
+    autoload :Translator, "chemicalml/cml/translator"
+    autoload :Unit, "chemicalml/cml/unit"
+    autoload :UnitList, "chemicalml/cml/unit_list"
+    autoload :UnitType, "chemicalml/cml/unit_type"
+    autoload :UnitTypeList, "chemicalml/cml/unit_type_list"
+    autoload :Visitable, "chemicalml/cml/visitable"
+  end
+end

data/lib/chemicalml/context_configuration.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # Shared behaviour for versioned schema configurations. Each schema
+  # version (`Cml::Schema3`, `Cml::Schema24`) extends this module via
+  # its own `Configuration` sub-module, giving it:
+  #
+  #   - `context_id` — the lutaml-model `GlobalContext` id
+  #   - `register_model(klass, id:)` — record one wire class
+  #   - `populate_context!` — rebuild the type registry on demand
+  #   - `ensure_registered!` — lazily populate on first parse
+  #
+  # Mirrors `Mml::ContextConfiguration`. Adapted to Chemicalml's
+  # schema-registry terminology.
+  module ContextConfiguration
+    def context_id
+      self::CONTEXT_ID
+    end
+
+    def context
+      Lutaml::Model::GlobalContext.context(context_id)
+    end
+
+    def ensure_registered!
+      return if @models_registered
+
+      register_models!
+      @models_registered = true
+    end
+
+    # Default: subclasses override with a centralized registration
+    # block (V4-style). The fallback eager-loads every autoloaded
+    # constant on the parent module.
+    def register_models!
+      parent = version_parent_module
+      parent.constants.each { |name| parent.const_get(name) }
+    end
+
+    # Walk the shared `Chemicalml::Cml::Elements::ALL` table, look up
+    # each class on the parent (schema) module, and register it. Pass
+    # `except:` to skip specific elements (used by Schema 2.4 which
+    # lacks `<module>`).
+    def register_elements!(except: [])
+      parent = version_parent_module
+      skip = except.to_set
+      Chemicalml::Cml::Elements::ALL.each do |class_name, element_id|
+        next if skip.include?(class_name)
+        next unless parent.const_defined?(class_name)
+
+        register_model(parent.const_get(class_name), id: element_id)
+      end
+    end
+
+    def register_model(klass, id:)
+      normalized_id = id.to_sym
+      registered_models[normalized_id] = klass
+      target_context = context || create_base_context
+      target_context.registry.register(normalized_id, klass)
+      klass
+    end
+
+    def populate_context!
+      ensure_version_registered
+      Lutaml::Model::GlobalContext.unregister_context(context_id) if context
+      register_models_in(base_type_context)
+    end
+
+    def create_context(id:, registry: nil, fallback_to: [context_id])
+      normalized_id = id.to_sym
+      ensure_version_registered
+      Lutaml::Model::GlobalContext.unregister_context(normalized_id) if Lutaml::Model::GlobalContext.context(normalized_id)
+      Lutaml::Model::GlobalContext.create_context(
+        id: normalized_id,
+        registry: registry || Lutaml::Model::TypeRegistry.new,
+        fallback_to: Array(fallback_to).map(&:to_sym)
+      ).tap { Lutaml::Model::GlobalContext.clear_caches }
+    end
+
+    def default_context_id
+      context_id
+    end
+
+    private
+
+    def registered_models
+      @registered_models ||= {}
+    end
+
+    def create_base_context
+      Lutaml::Model::GlobalContext.create_context(
+        id: context_id,
+        registry: Lutaml::Model::TypeRegistry.new,
+        fallback_to: [:default]
+      )
+    end
+
+    def base_type_context
+      create_base_context
+    end
+
+    def register_models_in(type_context)
+      registered_models.each do |model_id, klass|
+        type_context.registry.register(model_id, klass)
+      end
+      Lutaml::Model::GlobalContext.clear_caches
+      type_context
+    end
+
+    def ensure_version_registered
+      parent = version_parent_module
+      return unless parent
+
+      parent.ensure_registered!
+    end
+
+    def version_parent_module
+      return nil unless name
+
+      parent_const_name = name.split("::")[0..-2].join("::")
+      return nil if parent_const_name.empty?
+
+      Object.const_get(parent_const_name)
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/chemicalml/convention/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # Mixin that gives a convention module its registry behavior:
+    #
+    #   - `qname` / `namespace_uri` (must be implemented by the host)
+    #   - `constraints` (lazy array)
+    #   - `register(SomeConstraintClass)`
+    #   - `validate(document)` -> [Violation, ...]
+    #
+    # The framework never inspects which constraints a convention has;
+    # it just walks whatever was registered. Adding a new rule = a new
+    # constraint subclass + a `register` call.
+    module Base
+      def qname
+        raise NotImplementedError, "#{name} must define its QName"
+      end
+
+      def namespace_uri
+        raise NotImplementedError, "#{name} must define its namespace URI"
+      end
+
+      def constraints
+        @constraints ||= []
+      end
+
+      def register(constraint_class)
+        constraints << constraint_class unless constraints.include?(constraint_class)
+        self
+      end
+
+      def validate(document)
+        constraints.flat_map do |klass|
+          klass.new.check(document)
+        end
+      end
+
+      def constraint_count
+        constraints.length
+      end
+
+      def reset_constraints!
+        @constraints = []
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/compchem/constraints/compchem_module_must_contain_job_list.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Compchem
+      module Constraints
+        # A CompChem module MUST contain at least one jobList module
+        # child per the compchem convention.
+        class CompchemModuleMustContainJobList < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] unless compchem_root?(node)
+
+            job_lists = node.modules.select { |m| m.dict_ref == "compchem:jobList" }
+            return [] unless job_lists.empty?
+
+            [violation(path: path.join("/"),
+                       message: "compchem module must contain at least one jobList module")]
+          end
+
+          private
+
+          def compchem_root?(node)
+            module?(node) && node.convention == "convention:compchem"
+          end
+
+          def module?(node)
+            node.is_a?(Chemicalml::Cml::Role::Module)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/compchem/constraints/job_must_contain_initialization.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Compchem
+      module Constraints
+        # A job module MUST contain exactly one initialization module
+        # child per the compchem convention.
+        class JobMustContainInitialization < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] unless job_module?(node)
+
+            modules = node.modules || []
+            inits = modules.select { |m| m.dict_ref == "compchem:initialization" }
+            return [] if inits.length == 1
+
+            message = if inits.empty?
+                        "job module must contain exactly one initialization module (found 0)"
+                      else
+                        "job module must contain exactly one initialization module (found #{inits.length})"
+                      end
+            [violation(path: path.join("/"), message: message)]
+          end
+
+          private
+
+          def job_module?(node)
+            module?(node) && node.dict_ref == "compchem:job"
+          end
+
+          def module?(node)
+            node.is_a?(Chemicalml::Cml::Role::Module)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/compchem/constraints.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Compchem
+      module Constraints
+        autoload :CompchemModuleMustContainJobList,
+                 "chemicalml/convention/compchem/constraints/compchem_module_must_contain_job_list"
+        autoload :JobMustContainInitialization,
+                 "chemicalml/convention/compchem/constraints/job_must_contain_initialization"
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/compchem.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # The CompChem convention. Constraints based on
+    # http://www.xml-cml.org/convention/compchem (archived in
+    # `reference-docs/conventions/compchem.md`).
+    module Compchem
+      extend Base
+
+      autoload :Constraints, "chemicalml/convention/compchem/constraints"
+
+      QNAME = "convention:compchem".freeze
+      NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}compchem".freeze
+
+      def self.qname
+        QNAME
+      end
+
+      def self.namespace_uri
+        NAMESPACE_URI
+      end
+
+      register Constraints::CompchemModuleMustContainJobList
+      register Constraints::JobMustContainInitialization
+    end
+  end
+end

data/lib/chemicalml/convention/constraint.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # Abstract base class for a single constraint. Subclasses implement
+    # `check_node` (one node at a time) or `check_document` (whole
+    # document at once). The base class provides traversal and
+    # collection plumbing.
+    #
+    # To add a new constraint:
+    #
+    #   1. Subclass `Constraint::NodeConstraint` or
+    #      `Constraint::DocumentConstraint`
+    #   2. Implement `check_node` / `check_document`
+    #   3. Register it on the convention: `register(MyConstraint)`
+    #
+    # No framework code changes.
+    class Constraint
+      def self.name_for_display
+        to_s.split("::").last
+      end
+
+      def check(_document)
+        raise NotImplementedError,
+              "#{self.class.name_for_display} must implement #check(document)"
+      end
+
+      protected
+
+      def violation(path:, message:, severity: :error)
+        Violation.new(path: path, message: message,
+                      severity: severity, constraint: self.class)
+      end
+
+      # Walk every wire node reachable from `node`. Yields (node, path)
+      # pairs. Path is a slash-joined breadcrumb. Nodes that don't
+      # include `Chemicalml::Cml::Visitable` are skipped.
+      def walk_nodes(node, path = [], &block)
+        return unless node
+        return unless visitable?(node)
+
+        yield(node, path)
+        node.wire_children.each do |child|
+          walk_nodes(child, path + [describe(child)], &block)
+        end
+      end
+
+      def visitable?(node)
+        node.is_a?(Chemicalml::Cml::Visitable)
+      end
+
+      def describe(node)
+        id_value = node.node_id
+        id_value ? "#{node.element_name}[#{id_value}]" : node.element_name
+      end
+
+      # Constraint that walks the document tree once per node and calls
+      # `check_node(node, path)`. Subclasses get traversal for free.
+      class NodeConstraint < Constraint
+        def check(document)
+          violations = []
+          walk_nodes(document) do |node, path|
+            violations.concat(Array(check_node(node, path)))
+          end
+          violations
+        end
+
+        def check_node(_node, _path)
+          []
+        end
+      end
+
+      # Constraint that operates on the whole document at once — used
+      # for cross-cutting rules like "atom ids unique within molecule".
+      class DocumentConstraint < Constraint
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/entry_ids_unique_within_dictionary.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # Entry ids MUST be unique within the parent dictionary per
+        # the dictionary convention.
+        class EntryIdsUniqueWithinDictionary < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] unless dictionary?(node)
+
+            entries = node.entries || []
+            ids = entries.map { |e| e.id }.compact
+            duplicates = ids.group_by { |x| x }.select { |_, v| v.length > 1 }.keys
+            return [] if duplicates.empty?
+
+            duplicates.map do |dup|
+              violation(path: path.join("/"),
+                        message: "duplicate entry id #{dup.inspect} within dictionary")
+            end
+          end
+
+          private
+
+          def dictionary?(node)
+            node.is_a?(Chemicalml::Cml::Role::Dictionary)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/entry_must_have_id_and_term.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # Every entry MUST have an `id` and a `term` attribute per the
+        # dictionary convention.
+        class EntryMustHaveIdAndTerm < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] unless entry?(node)
+
+            violations = []
+            if node.id.to_s.empty?
+              violations << violation(path: path.join("/"),
+                                      message: "entry must have an id attribute")
+            end
+            if node.term.to_s.empty?
+              violations << violation(path: path.join("/"),
+                                      message: "entry must have a term attribute")
+            end
+            violations
+          end
+
+          private
+
+          def entry?(node)
+            node.is_a?(Chemicalml::Cml::Role::DictionaryEntry)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        autoload :EntryMustHaveIdAndTerm,
+                 "chemicalml/convention/dictionary/constraints/entry_must_have_id_and_term"
+        autoload :EntryIdsUniqueWithinDictionary,
+                 "chemicalml/convention/dictionary/constraints/entry_ids_unique_within_dictionary"
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # The dictionary convention. Constraints based on
+    # http://www.xml-cml.org/convention/dictionary (archived in
+    # `reference-docs/conventions/dictionary.md`).
+    module Dictionary
+      extend Base
+
+      autoload :Constraints, "chemicalml/convention/dictionary/constraints"
+
+      QNAME = "convention:dictionary".freeze
+      NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}dictionary".freeze
+
+      def self.qname
+        QNAME
+      end
+
+      def self.namespace_uri
+        NAMESPACE_URI
+      end
+
+      register Constraints::EntryMustHaveIdAndTerm
+      register Constraints::EntryIdsUniqueWithinDictionary
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/atom_array_must_contain_atoms.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # `atomArray` MUST contain at least one `atom` child per the
+        # molecular convention.
+        class AtomArrayMustContainAtoms < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] unless molecule?(node)
+            return [] unless node.atom_array
+
+            atoms = node.atom_array.atoms || []
+            return [] unless atoms.empty?
+
+            [violation(path: path.empty? ? "molecule" : path.join("/"),
+                       message: "atomArray must contain at least one atom")]
+          end
+
+          private
+
+          def molecule?(node)
+            node.is_a?(Chemicalml::Cml::Role::Molecule)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/atom_ids_unique_within_molecule.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Atom ids MUST be unique within the eldest containing molecule
+        # per the molecular convention.
+        class AtomIdsUniqueWithinMolecule < Chemicalml::Convention::Constraint::DocumentConstraint
+          def check(document)
+            violations = []
+            walk_nodes(document) do |node, path|
+              next unless molecule?(node)
+
+              ids = atom_ids_within(node)
+              duplicates = ids.group_by { |x| x }.select { |_, v| v.length > 1 }.keys
+              duplicates.each do |dup|
+                violations << violation(
+                  path: path.empty? ? "molecule[#{node.id}]" : path.join("/"),
+                  message: "duplicate atom id #{dup.inspect} within molecule #{node.id.inspect}"
+                )
+              end
+            end
+            violations
+          end
+
+          private
+
+          def molecule?(node)
+            node.is_a?(Chemicalml::Cml::Role::Molecule)
+          end
+
+          def atom_ids_within(molecule)
+            return [] unless molecule.atom_array
+
+            (molecule.atom_array.atoms || []).map { |a| a.id }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/bond_must_reference_atoms_in_same_molecule.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Bonds MUST reference atoms within the same parent molecule
+        # per the molecular convention.
+        class BondMustReferenceAtomsInSameMolecule < Chemicalml::Convention::Constraint::DocumentConstraint
+          def check(document)
+            violations = []
+            walk_nodes(document) do |node, path|
+              next unless molecule?(node)
+
+              known = atom_ids_within(node).to_set
+              bonds_within(node).each do |bond|
+                missing = atom_refs_of(bond).reject { |r| known.include?(r) }
+                next if missing.empty?
+
+                violations << violation(
+                  path: path.empty? ? "molecule[#{node.id}]" : path.join("/"),
+                  message: "bond #{bond.id.inspect} references atoms not in the same molecule: #{missing.inspect}"
+                )
+              end
+            end
+            violations
+          end
+
+          private
+
+          def molecule?(node)
+            node.is_a?(Chemicalml::Cml::Role::Molecule)
+          end
+
+          def atom_ids_within(molecule)
+            return [] unless molecule.atom_array
+
+            (molecule.atom_array.atoms || []).map { |a| a.id }
+          end
+
+          def bonds_within(molecule)
+            return [] unless molecule.bond_array
+
+            molecule.bond_array.bonds || []
+          end
+
+          def atom_refs_of(bond)
+            bond.atom_refs2.to_s.split(" ")
+          end
+        end
+      end
+    end
+  end
+end