chemicalml 0.1.0

data/lib/chemicalml/cml/translator/value_translations.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    class Translator
+      # Canonical-form translations for the value-container and module
+      # elements introduced when the compchem / molecular conventions
+      # were added. Each method is symmetric with the existing
+      # molecule/atom/bond translators.
+      module ValueTranslations
+        module ClassMethods
+          def scalar_to_canonical(cml_scalar)
+            return nil unless cml_scalar
+
+            Model::Scalar.new(
+              value: cml_scalar.content,
+              data_type: cml_scalar.data_type,
+              units: cml_scalar.units,
+              id: cml_scalar.id,
+              title: cml_scalar.title,
+              dict_ref: cml_scalar.dict_ref
+            )
+          end
+
+          def scalar_from_canonical(scalar)
+            return nil unless scalar
+
+            Cml::Scalar.new(
+              content: scalar.value,
+              data_type: scalar.data_type,
+              units: scalar.units,
+              id: scalar.id,
+              title: scalar.title,
+              dict_ref: scalar.dict_ref
+            )
+          end
+
+          def array_to_canonical(cml_array)
+            return nil unless cml_array
+
+            Model::Array.new(
+              values: cml_array.content.to_s.split,
+              data_type: cml_array.data_type,
+              units: cml_array.units,
+              size: cml_array.size,
+              id: cml_array.id,
+              title: cml_array.title,
+              dict_ref: cml_array.dict_ref
+            )
+          end
+
+          def array_from_canonical(array)
+            return nil unless array
+
+            Cml::Array.new(
+              content: Array(array.values).join(" "),
+              data_type: array.data_type,
+              units: array.units,
+              size: array.size,
+              id: array.id,
+              title: array.title,
+              dict_ref: array.dict_ref
+            )
+          end
+
+          def matrix_to_canonical(cml_matrix)
+            return nil unless cml_matrix
+
+            Model::Matrix.new(
+              values: cml_matrix.content.to_s.split,
+              rows: cml_matrix.rows,
+              columns: cml_matrix.columns,
+              data_type: cml_matrix.data_type,
+              units: cml_matrix.units,
+              id: cml_matrix.id,
+              title: cml_matrix.title,
+              dict_ref: cml_matrix.dict_ref
+            )
+          end
+
+          def matrix_from_canonical(matrix)
+            return nil unless matrix
+
+            Cml::Matrix.new(
+              content: Array(matrix.values).join(" "),
+              rows: matrix.rows,
+              columns: matrix.columns,
+              data_type: matrix.data_type,
+              units: matrix.units,
+              id: matrix.id,
+              title: matrix.title,
+              dict_ref: matrix.dict_ref
+            )
+          end
+
+          def value_container_to_canonical(cml_value)
+            return nil unless cml_value
+
+            if cml_value.is_a?(Cml::Matrix)
+              matrix_to_canonical(cml_value)
+            elsif cml_value.is_a?(Cml::Array)
+              array_to_canonical(cml_value)
+            elsif cml_value.is_a?(Cml::Scalar)
+              scalar_to_canonical(cml_value)
+            end
+          end
+
+          def value_container_from_canonical(value)
+            case value
+            when Model::Matrix then matrix_from_canonical(value)
+            when Model::Array  then array_from_canonical(value)
+            when Model::Scalar then scalar_from_canonical(value)
+            end
+          end
+
+          def property_to_canonical(cml_prop)
+            return nil unless cml_prop
+
+            Model::Property.new(
+              id: cml_prop.id,
+              title: cml_prop.title,
+              dict_ref: cml_prop.dict_ref,
+              convention: cml_prop.convention,
+              value: property_value_to_canonical(cml_prop)
+            )
+          end
+
+          def property_from_canonical(prop)
+            return nil unless prop
+
+            value = value_container_from_canonical(prop.value)
+            Cml::Property.new(
+              id: prop.id,
+              title: prop.title,
+              dict_ref: prop.dict_ref,
+              convention: prop.convention,
+              scalar: value.is_a?(Cml::Scalar) ? value : nil,
+              array: value.is_a?(Cml::Array) ? value : nil,
+              matrix: value.is_a?(Cml::Matrix) ? value : nil
+            )
+          end
+
+          def parameter_to_canonical(cml_param)
+            return nil unless cml_param
+
+            Model::Parameter.new(
+              id: cml_param.id,
+              title: cml_param.title,
+              dict_ref: cml_param.dict_ref,
+              convention: cml_param.convention,
+              value: parameter_value_to_canonical(cml_param)
+            )
+          end
+
+          def parameter_from_canonical(param)
+            return nil unless param
+
+            value = value_container_from_canonical(param.value)
+            Cml::Parameter.new(
+              id: param.id,
+              title: param.title,
+              dict_ref: param.dict_ref,
+              convention: param.convention,
+              scalar: value.is_a?(Cml::Scalar) ? value : nil,
+              array: value.is_a?(Cml::Array) ? value : nil,
+              matrix: value.is_a?(Cml::Matrix) ? value : nil
+            )
+          end
+
+          def label_to_canonical(cml_label)
+            return nil unless cml_label
+
+            Model::Label.new(
+              id: cml_label.id,
+              value: cml_label.value,
+              dict_ref: cml_label.dict_ref,
+              convention: cml_label.convention
+            )
+          end
+
+          def label_from_canonical(label)
+            return nil unless label
+
+            Cml::Label.new(
+              id: label.id,
+              value: label.value,
+              dict_ref: label.dict_ref,
+              convention: label.convention
+            )
+          end
+
+          def metadata_to_canonical(cml_md)
+            return nil unless cml_md
+
+            Model::Metadata.new(
+              id: cml_md.id,
+              name: cml_md.name,
+              content: cml_md.content,
+              convention: cml_md.convention,
+              title: cml_md.title
+            )
+          end
+
+          def metadata_from_canonical(md)
+            return nil unless md
+
+            Cml::Metadata.new(
+              id: md.id,
+              name: md.name,
+              content: md.content,
+              convention: md.convention,
+              title: md.title
+            )
+          end
+
+          def formula_to_canonical(cml_formula)
+            return nil unless cml_formula
+
+            Model::Formula.new(
+              id: cml_formula.id,
+              concise: cml_formula.concise,
+              inline: cml_formula.inline,
+              formal_charge: cml_formula.formal_charge,
+              count: cml_formula.count,
+              title: cml_formula.title,
+              convention: cml_formula.convention,
+              dict_ref: cml_formula.dict_ref
+            )
+          end
+
+          def formula_from_canonical(formula)
+            return nil unless formula
+
+            Cml::Formula.new(
+              id: formula.id,
+              concise: formula.concise,
+              inline: formula.inline,
+              formal_charge: formula.formal_charge,
+              count: formula.count,
+              title: formula.title,
+              convention: formula.convention,
+              dict_ref: formula.dict_ref
+            )
+          end
+
+          private
+
+          def property_value_to_canonical(cml_prop)
+            value_container_to_canonical(cml_prop.scalar) ||
+              value_container_to_canonical(cml_prop.array) ||
+              value_container_to_canonical(cml_prop.matrix)
+          end
+
+          def parameter_value_to_canonical(cml_param)
+            value_container_to_canonical(cml_param.scalar) ||
+              value_container_to_canonical(cml_param.array) ||
+              value_container_to_canonical(cml_param.matrix)
+          end
+        end
+      end
+
+      extend ValueTranslations::ClassMethods
+    end
+  end
+end

data/lib/chemicalml/cml/translator.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    # Adapter between the canonical `Chemicalml::Model` and the CML XML
+    # wire-format layer (`Chemicalml::Cml::*` lutaml-model classes).
+    #
+    # Pure transformation. No I/O. Two class methods, one per
+    # direction. Adding a new CML element means updating the
+    # translator's mapping rules; the canonical classes and the CML
+    # wire classes stay independent.
+    class Translator
+      autoload :ValueTranslations, "chemicalml/cml/translator/value_translations"
+
+      # CML wire format -> canonical. Accepts either Schema3 or
+      # Schema24 wire documents; dispatches based on class.
+      def self.to_canonical(document)
+        Model::Document.new(
+          molecules: document.molecules.map { |m| molecule_to_canonical(m) },
+          reactions: document.reactions.map { |r| reaction_to_canonical(r) }
+        )
+      end
+
+      # Canonical -> CML wire format. `schema:` selects the target
+      # version (`:schema3` default, or `:schema24`).
+      def self.from_canonical(document, schema: :schema3)
+        wire_class = document_class_for(schema)
+        wire_class.new(
+          molecules: document.molecules.map { |m| molecule_from_canonical(m) },
+          reactions: document.reactions.map { |r| reaction_from_canonical(r) }
+        )
+      end
+
+      def self.document_class_for(schema)
+        case schema.to_sym
+        when :schema3  then Chemicalml::Cml::Schema3::Document
+        when :schema24 then Chemicalml::Cml::Schema24::Document
+        else
+          raise ArgumentError, "unsupported schema: #{schema.inspect}"
+        end
+      end
+      private_class_method :document_class_for
+
+      # -- CML -> canonical --------------------------------------------
+
+      def self.molecule_to_canonical(cml_mol)
+        Model::Molecule.new(
+          id: cml_mol.id,
+          atoms: cml_mol.atom_array&.atoms&.map { |a| atom_to_canonical(a) } || [],
+          bonds: cml_mol.bond_array&.bonds&.map { |b| bond_to_canonical(b) } || [],
+          names: cml_mol.names.map { |n| Model::Name.new(content: n.content, convention: n.convention, dict_ref: n.dict_ref) },
+          identifiers: cml_mol.identifiers.map { |i| Model::Identifier.new(value: i.value, convention: i.convention, dict_ref: i.dict_ref) },
+          count: cml_mol.count,
+          formal_charge: cml_mol.formal_charge,
+          title: cml_mol.title
+        )
+      end
+
+      def self.atom_to_canonical(cml_atom)
+        Model::Atom.new(
+          id: cml_atom.id,
+          element: cml_atom.element_type,
+          formal_charge: cml_atom.formal_charge,
+          isotope: cml_atom.isotope,
+          count: cml_atom.count,
+          hydrogen_count: cml_atom.hydrogen_count,
+          spin_multiplicity: cml_atom.spin_multiplicity,
+          title: cml_atom.title
+        )
+      end
+
+      def self.bond_to_canonical(cml_bond)
+        Model::Bond.new(
+          id: cml_bond.id,
+          atom_refs: cml_bond.atom_refs2&.split(" ") || [],
+          kind: cml_order_to_kind(cml_bond.order)
+        )
+      end
+
+      def self.reaction_to_canonical(cml_rxn)
+        Model::Reaction.new(
+          id: cml_rxn.id,
+          reactant_list: reactant_list_to_canonical(cml_rxn.reactant_list),
+          product_list: product_list_to_canonical(cml_rxn.product_list),
+          arrow: type_to_arrow(cml_rxn.type || cml_rxn.title),
+          title: cml_rxn.title,
+          type: cml_rxn.type
+        )
+      end
+
+      def self.reactant_list_to_canonical(cml_list)
+        return Model::ReactantList.new unless cml_list
+
+        Model::ReactantList.new(
+          reactants: cml_list.reactants.map do |r|
+            Model::Reactant.new(
+              substance: Model::Substance.new(
+                molecule: molecule_to_canonical(r.substance.molecule),
+                title: r.substance.title,
+                role: r.substance.role
+              )
+            )
+          end
+        )
+      end
+
+      def self.product_list_to_canonical(cml_list)
+        return Model::ProductList.new unless cml_list
+
+        Model::ProductList.new(
+          products: cml_list.products.map do |p|
+            Model::Product.new(
+              substance: Model::Substance.new(
+                molecule: molecule_to_canonical(p.substance.molecule),
+                title: p.substance.title,
+                role: p.substance.role
+              )
+            )
+          end
+        )
+      end
+
+      # -- Canonical -> CML --------------------------------------------
+
+      def self.molecule_from_canonical(mol)
+        Cml::Molecule.new(
+          id: mol.id,
+          atom_array: mol.atoms.empty? ? nil : Cml::AtomArray.new(
+            atoms: mol.atoms.map { |a| atom_from_canonical(a) }
+          ),
+          bond_array: mol.bonds.empty? ? nil : Cml::BondArray.new(
+            bonds: mol.bonds.map { |b| bond_from_canonical(b) }
+          ),
+          names: mol.names.map { |n| Cml::Name.new(content: n.content, convention: n.convention, dict_ref: n.dict_ref) },
+          identifiers: mol.identifiers.map { |i| Cml::Identifier.new(value: i.value, convention: i.convention, dict_ref: i.dict_ref) },
+          count: mol.count,
+          formal_charge: mol.formal_charge,
+          title: mol.title
+        )
+      end
+
+      def self.atom_from_canonical(atom)
+        Cml::Atom.new(
+          id: atom.id,
+          element_type: atom.element,
+          formal_charge: atom.formal_charge,
+          isotope: atom.isotope,
+          count: atom.count,
+          hydrogen_count: atom.hydrogen_count,
+          spin_multiplicity: atom.spin_multiplicity,
+          title: atom.title
+        )
+      end
+
+      def self.bond_from_canonical(bond)
+        Cml::Bond.new(
+          id: bond.id,
+          atom_refs2: bond.atom_refs.join(" "),
+          order: bond.cml_order
+        )
+      end
+
+      def self.reaction_from_canonical(rxn)
+        Cml::Reaction.new(
+          id: rxn.id,
+          title: rxn.title || rxn.arrow.to_s,
+          type: rxn.type || rxn.arrow.to_s,
+          reactant_list: reactant_list_from_canonical(rxn.reactant_list),
+          product_list: product_list_from_canonical(rxn.product_list)
+        )
+      end
+
+      def self.reactant_list_from_canonical(list)
+        Cml::ReactantList.new(
+          reactants: list.reactants.map do |r|
+            Cml::Reactant.new(
+              substance: Cml::Substance.new(
+                molecule: molecule_from_canonical(r.substance.molecule),
+                title: r.substance.title,
+                role: r.substance.role
+              )
+            )
+          end
+        )
+      end
+
+      def self.product_list_from_canonical(list)
+        Cml::ProductList.new(
+          products: list.products.map do |p|
+            Cml::Product.new(
+              substance: Cml::Substance.new(
+                molecule: molecule_from_canonical(p.substance.molecule),
+                title: p.substance.title,
+                role: p.substance.role
+              )
+            )
+          end
+        )
+      end
+
+      # -- Lookup tables -----------------------------------------------
+
+      ORDER_TO_KIND = {
+        "S" => :single, "D" => :double, "T" => :triple,
+        "Q" => :quadruple, "A" => :aromatic, "W" => :wedge,
+        "H" => :hash, "DG" => :dative, "V" => :wavy
+      }.freeze
+
+      TYPE_TO_ARROW = {
+        "forward" => :forward,
+        "reverse" => :reverse,
+        "equilibrium" => :equilibrium,
+        "resonance" => :resonance
+      }.freeze
+
+      def self.cml_order_to_kind(order)
+        return :single if order.nil?
+
+        ORDER_TO_KIND.fetch(order.upcase, :single)
+      end
+
+      def self.type_to_arrow(value)
+        return :forward if value.nil?
+
+        TYPE_TO_ARROW.fetch(value.to_s.downcase, :forward)
+      end
+
+      private_class_method :cml_order_to_kind, :type_to_arrow
+
+      extend ValueTranslations::ClassMethods
+    end
+  end
+end

data/lib/chemicalml/cml/unit.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Backward-compatible alias. New code should reference the versioned
+# class directly: Chemicalml::Cml::Schema3::Unit.
+module Chemicalml
+  module Cml
+    remove_const(:Unit) if const_defined?(:Unit, false)
+    const_set(:Unit, Chemicalml::Cml::Schema3::Unit)
+  end
+end

data/lib/chemicalml/cml/unit_list.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Backward-compatible alias. New code should reference the versioned
+# class directly: Chemicalml::Cml::Schema3::UnitList.
+module Chemicalml
+  module Cml
+    remove_const(:UnitList) if const_defined?(:UnitList, false)
+    const_set(:UnitList, Chemicalml::Cml::Schema3::UnitList)
+  end
+end

data/lib/chemicalml/cml/unit_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Backward-compatible alias. New code should reference the versioned
+# class directly: Chemicalml::Cml::Schema3::UnitType.
+module Chemicalml
+  module Cml
+    remove_const(:UnitType) if const_defined?(:UnitType, false)
+    const_set(:UnitType, Chemicalml::Cml::Schema3::UnitType)
+  end
+end

data/lib/chemicalml/cml/unit_type_list.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Backward-compatible alias. New code should reference the versioned
+# class directly: Chemicalml::Cml::Schema3::UnitTypeList.
+module Chemicalml
+  module Cml
+    remove_const(:UnitTypeList) if const_defined?(:UnitTypeList, false)
+    const_set(:UnitTypeList, Chemicalml::Cml::Schema3::UnitTypeList)
+  end
+end

data/lib/chemicalml/cml/visitable.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    # Marker mixin included by every wire class. Provides a uniform
+    # interface the convention-constraint walker relies on:
+    #
+    #   - `wire_children` returns the child wire nodes
+    #   - `node_id` returns the id attribute or `nil`
+    #   - `element_name` returns the XML tag name
+    #
+    # All three use lutaml-model's attribute registry — no duck typing.
+    # A wire class that doesn't declare an `:id` attribute simply has
+    # `node_id` return `nil`.
+    module Visitable
+      def wire_children
+        declared_attribute_names.flat_map do |name|
+          collect_wire_nodes(public_send(name))
+        end
+      end
+
+      def node_id
+        return id if declared_attribute?(:id)
+
+        nil
+      end
+
+      def element_name
+        xml_mapping = self.class.mappings[:xml]
+        root = xml_mapping && xml_mapping.root
+        root && root.name || self.class.name.split("::").last
+      rescue StandardError
+        self.class.name.split("::").last
+      end
+
+      def collect_wire_nodes(value)
+        return [] if value.nil?
+
+        if value.is_a?(::Array)
+          value.select { |v| wire_node?(v) }
+        elsif wire_node?(value)
+          [value]
+        else
+          []
+        end
+      end
+
+      def wire_node?(value)
+        value.is_a?(Lutaml::Model::Serializable)
+      end
+
+      def declared_attribute_names
+        self.class.model.attributes.keys
+      rescue StandardError
+        []
+      end
+
+      def declared_attribute?(name)
+        self.class.model.attributes.key?(name)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/chemicalml/cml/wire_class_macro.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    # Macro for defining a schema version's wire classes without
+    # writing 35+ boilerplate files. Each generated class:
+    #
+    #   - subclasses `Lutaml::Model::Serializable`
+    #   - includes the corresponding `Base::*` mixin (shared attribute
+    #     declarations and xml mapping)
+    #   - includes `Cml::Visitable` (uniform interface for the
+    #     constraint walker)
+    #   - defines `self.lutaml_default_register` returning the
+    #     provided context_id
+    #
+    # Usage:
+    #
+    #   Chemicalml::Cml.define_wire_classes(
+    #     namespace: Chemicalml::Cml::Schema3,
+    #     context_id: :chemicalml_schema3
+    #   )
+    #
+    # Pass `except:` to skip elements (e.g. Schema 2.4 lacks <module>):
+    #
+    #   Chemicalml::Cml.define_wire_classes(
+    #     namespace: Chemicalml::Cml::Schema24,
+    #     context_id: :chemicalml_schema24,
+    #     except: Chemicalml::Cml::Elements::SCHEMA3_ONLY
+    #   )
+    def self.define_wire_classes(namespace:, context_id:, except: [])
+      skip = except.to_set
+      Elements::ALL.each_key do |class_name|
+        next if skip.include?(class_name)
+
+        base_module = Base.const_get(class_name)
+        klass = Class.new(Lutaml::Model::Serializable) do
+          include base_module
+          include Chemicalml::Cml::Visitable
+        end
+        klass.define_singleton_method(:lutaml_default_register) { context_id }
+        namespace.const_set(class_name, klass)
+      end
+    end
+  end
+end