chemicalml 0.2.1 → 0.4.0

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<bondStereo>`'s `value` attribute SHOULD be one of the
+        # XSD stereoType enum values: C/T/W/H/undefined/other.
+        # Warning severity.
+        class BondStereoShouldBeInEnum < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A `<bondStereo>`'s `value` attribute SHOULD be one of the XSD stereoType enum values: C/T/W/H/undefined/other. Warning severity."
+          include Chemicalml::Cml::Enums
+
+          applies_to Chemicalml::Cml::Role::BondStereo
+
+          def check_node(node, _path)
+            value = node.content.to_s
+            return [] if value.empty?
+            return [] if STEREO_VALUES.include?(value)
+
+            [violation(path: yield_path(node),
+                       message: "bondStereo #{node.id.inspect} value #{value.inspect} should be one of " \
+                                "#{STEREO_VALUES.to_a.sort.inspect}",
+                       severity: :warning,
+                       value: value)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "bondStereo[#{id}]" : 'bondStereo'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,11 +7,11 @@ module Chemicalml
         # Molecular convention: `<bondStereo>` value W (wedge) or H
         # (hatch) MUST have `atomRefs2` and MUST NOT have `atomRefs4`.
         class BondStereoWedgeHashMustHaveAtomRefs2 < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Molecular convention: `<bondStereo>` value W (wedge) or H (hatch) MUST have `atomRefs2` and MUST NOT have `atomRefs4`.'
           applies_to Chemicalml::Cml::Role::BondStereo
           WEDGE_HASH_VALUES = %w[W H].freeze
 
           def check_node(node, path)
-
             value = node.content.to_s.upcase
             return [] unless WEDGE_HASH_VALUES.include?(value)
 

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Walks the document and warns on any element whose `dictRef`
+        # attribute cannot be resolved against the built-in
+        # dictionaries. Catches typos like `dictRef="cml:bpingpoint"`.
+        #
+        # DocumentConstraint — needs the whole tree, but the resolver
+        # works per-node so it's just a wrapper around the per-node
+        # check.
+        class DictRefShouldResolve < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Walks the document and warns on any element whose `dictRef` attribute cannot be resolved against the built-in dictionaries. Catches typos like `dictRef="cml:bpingpoint"`.'
+          applies_to Chemicalml::Cml::Role::Atom,
+                     Chemicalml::Cml::Role::Bond,
+                     Chemicalml::Cml::Role::Molecule,
+                     Chemicalml::Cml::Role::Property,
+                     Chemicalml::Cml::Role::Scalar,
+                     Chemicalml::Cml::Role::Array,
+                     Chemicalml::Cml::Role::Matrix,
+                     Chemicalml::Cml::Role::Name,
+                     Chemicalml::Cml::Role::Label
+
+          def check_node(node, path)
+            dict_ref = node.dict_ref.to_s.strip
+            return [] if dict_ref.empty?
+            return [] if resolves?(dict_ref)
+
+            [violation(path: path_fingerprint(node, path),
+                       message: "#{node.element_name} #{node_id_or_blank(node).inspect} " \
+                                "dictRef #{dict_ref.inspect} does not resolve against any built-in dictionary",
+                       severity: :warning,
+                       value: dict_ref)]
+          end
+
+          private
+
+          def resolves?(dict_ref)
+            !Chemicalml::Dictionary::Registry.lookup(dict_ref).nil?
+          rescue StandardError
+            false
+          end
+
+          def path_fingerprint(node, path)
+            base = path.empty? ? node.element_name : path.join('/')
+            id = node.node_id
+            id ? "#{base}[#{id}]" : base
+          end
+
+          def node_id_or_blank(node)
+            node.node_id || ''
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,7 @@ module Chemicalml
         # OR child `<molecule>` elements, but not both. The two are
         # mutually exclusive ways of describing composition.
         class MoleculeAtomArrayMutuallyExclusiveWithChildren < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Molecular convention: a `<molecule>` MAY hold an `atomArray` OR child `<molecule>` elements, but not both. The two are mutually exclusive ways of describing composition.'
           applies_to Chemicalml::Cml::Role::Molecule
           def check_node(node, path)
             return [] if node.atom_array.nil?

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

@@ -7,6 +7,7 @@ module Chemicalml
         # Molecular convention: a `<molecule>` MAY hold a `bondArray`
         # OR child `<molecule>` elements, but not both.
         class MoleculeBondArrayMutuallyExclusiveWithChildren < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Molecular convention: a `<molecule>` MAY hold a `bondArray` OR child `<molecule>` elements, but not both.'
           applies_to Chemicalml::Cml::Role::Molecule
           def check_node(node, path)
             return [] if node.bond_array.nil?

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<molecule>`'s `chirality` attribute SHOULD be one of the
+        # XSD chiralityType enum values:
+        # enantiomer/racemate/unknown/other. Warning severity.
+        class MoleculeChiralityShouldBeInEnum < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A `<molecule>`'s `chirality` attribute SHOULD be one of the XSD chiralityType enum values: enantiomer/racemate/unknown/other. Warning severity."
+          include Chemicalml::Cml::Enums
+
+          applies_to Chemicalml::Cml::Role::Molecule
+
+          def check_node(node, _path)
+            chirality = node.chirality.to_s
+            return [] if chirality.empty?
+            return [] if CHIRALITY_VALUES.include?(chirality)
+
+            [violation(path: yield_path(node),
+                       message: "molecule #{node.id.inspect} chirality #{chirality.inspect} should be one of " \
+                                "#{CHIRALITY_VALUES.to_a.sort.inspect}",
+                       severity: :warning,
+                       value: chirality)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "molecule[#{id}]" : 'molecule'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,7 @@ module Chemicalml
         # molecules (direct children of `<cml>`). It is REQUIRED on
         # molecules nested inside another `<molecule>`.
         class MoleculeCountMustNotAppearOnTopLevel < Chemicalml::Convention::Constraint::DocumentConstraint
+          self.description = 'Molecular convention: `count` MUST NOT appear on top-level molecules (direct children of `<cml>`). It is REQUIRED on molecules nested inside another `<molecule>`.'
           def check(document)
             violations = []
             top_level_molecules(document).each do |mol, path|

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<molecule>`'s `id` attribute SHOULD match the XSD
+        # moleculeIDType pattern (letter/underscore start, alphanumeric
+        # body, optional namespace prefix). Warning severity.
+        class MoleculeIdShouldMatchPattern < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A `<molecule>`'s `id` attribute SHOULD match the XSD moleculeIDType pattern (letter/underscore start, alphanumeric body, optional namespace prefix). Warning severity."
+          include Chemicalml::Cml::Patterns
+
+          applies_to Chemicalml::Cml::Role::Molecule
+
+          def check_node(node, _path)
+            id = node.id.to_s
+            return [] if id.empty?
+            return [] if id.match?(/\A#{MOLECULE_ID_PATTERN.source}\z/)
+
+            [violation(path: yield_path(node),
+                       message: "molecule id #{id.inspect} should match the moleculeIDType pattern " \
+                                '(letter start, alphanumeric body, optional prefix)',
+                       severity: :warning,
+                       value: id)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "molecule[#{id}]" : 'molecule'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,9 +5,9 @@ module Chemicalml
     module Molecular
       module Constraints
         class MoleculeMustHaveId < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A <molecule> in a molecular document MUST have an id attribute unique within document scope.'
           applies_to Chemicalml::Cml::Role::Molecule
           def check_node(node, path)
-
             return [] unless node.id.to_s.empty?
 
             [violation(path: path.empty? ? 'molecule' : path.join('/'),

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

@@ -5,9 +5,9 @@ module Chemicalml
     module Molecular
       module Constraints
         class PropertyMustHaveDictRef < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A <property> MUST have a dictRef attribute that identifies the property type via a dictionary entry.'
           applies_to Chemicalml::Cml::Role::Property
           def check_node(node, path)
-
             return [] unless node.dict_ref.to_s.empty?
 
             [violation(path: path.empty? ? 'property' : path.join('/'),

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<property>` with a `dictRef` whose dictionary entry declares
+        # a `dataType` SHOULD have a child `<scalar>` whose `dataType`
+        # attribute matches. Catches inconsistencies like a property
+        # declaring `dictRef="cml:bp"` (boiling point, xsd:float) but
+        # carrying a `<scalar dataType="xsd:string">`.
+        #
+        # Warning severity — some dictionaries allow multiple dataTypes.
+        class PropertyScalarDataTypeMatchesDictionary < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A `<property>` with a `dictRef` whose dictionary entry declares a `dataType` SHOULD have a child `<scalar>` whose `dataType` attribute matches. Catches inconsistencies like a property'
+          applies_to Chemicalml::Cml::Role::Property
+
+          def check_node(node, _path)
+            dict_ref = node.dict_ref.to_s
+            return [] if dict_ref.empty?
+
+            entry = lookup_entry(dict_ref)
+            return [] unless entry
+
+            expected_type = entry.data_type.to_s
+            return [] if expected_type.empty?
+
+            scalar = node.scalar
+            return [] unless scalar
+
+            actual_type = scalar.data_type.to_s
+            return [] if actual_type.empty?
+            return [] if actual_type == expected_type
+
+            [violation(path: yield_path(node),
+                       message: "property #{node.id.inspect} dictRef #{dict_ref.inspect} " \
+                                "expects dataType #{expected_type.inspect} but scalar has #{actual_type.inspect}",
+                       severity: :warning,
+                       value: { expected: expected_type, actual: actual_type }.freeze)]
+          end
+
+          private
+
+          def lookup_entry(dict_ref)
+            Chemicalml::Dictionary::Registry.lookup(dict_ref)
+          rescue StandardError
+            nil
+          end
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "property[#{id}]" : 'property'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Walks the document via `Cml::ReferenceResolver` and reports
+        # every bond whose `atomRefs2` references atoms that don't
+        # exist in the parent molecule. Warning severity — there are
+        # edge cases (inter-molecular bonds in transition states).
+        #
+        # DocumentConstraint because it needs the whole tree to
+        # resolve references.
+        class ReferencesShouldResolve < Chemicalml::Convention::Constraint::DocumentConstraint
+          self.description = "Walks the document via `Cml::ReferenceResolver` and reports every bond whose `atomRefs2` references atoms that don't exist in the parent molecule. Warning severity — there are"
+          def check(document)
+            resolver = Chemicalml::Cml::ReferenceResolver.new(document)
+            resolver.unresolved_refs.map do |entry|
+              violation(path: describe(entry[:node]),
+                        message: "bond #{entry[:node].id.inspect} #{entry[:attr]} references " \
+                                 "missing atoms: #{entry[:missing].inspect}",
+                        severity: :warning,
+                        value: entry[:missing])
+            end
+          end
+
+          private
+
+          def describe(node)
+            id = node.node_id
+            id ? "#{node.element_name}[#{id}]" : node.element_name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,9 +5,9 @@ module Chemicalml
     module Molecular
       module Constraints
         class ScalarMustHaveDataType < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A <scalar> child of a <property> MUST have a dataType attribute (e.g. xsd:float, xsd:integer).'
           applies_to Chemicalml::Cml::Role::Scalar
           def check_node(node, path)
-
             return [] unless node.data_type.to_s.empty?
 
             [violation(path: path.empty? ? 'scalar' : path.join('/'),

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

@@ -5,51 +5,77 @@ module Chemicalml
     module Molecular
       module Constraints
         autoload :AtomArrayMustContainAtoms,
-                 "chemicalml/convention/molecular/constraints/atom_array_must_contain_atoms"
+                 'chemicalml/convention/molecular/constraints/atom_array_must_contain_atoms'
         autoload :AtomIdsUniqueWithinMolecule,
-                 "chemicalml/convention/molecular/constraints/atom_ids_unique_within_molecule"
+                 'chemicalml/convention/molecular/constraints/atom_ids_unique_within_molecule'
         autoload :BondMustReferenceAtomsInSameMolecule,
-                 "chemicalml/convention/molecular/constraints/bond_must_reference_atoms_in_same_molecule"
+                 'chemicalml/convention/molecular/constraints/bond_must_reference_atoms_in_same_molecule'
         autoload :AtomMustHaveId,
-                 "chemicalml/convention/molecular/constraints/atom_must_have_id"
+                 'chemicalml/convention/molecular/constraints/atom_must_have_id'
         autoload :AtomMustHaveElementType,
-                 "chemicalml/convention/molecular/constraints/atom_must_have_element_type"
+                 'chemicalml/convention/molecular/constraints/atom_must_have_element_type'
         autoload :BondMustHaveAtomRefs2,
-                 "chemicalml/convention/molecular/constraints/bond_must_have_atom_refs2"
+                 'chemicalml/convention/molecular/constraints/bond_must_have_atom_refs2'
         autoload :BondMustHaveOrder,
-                 "chemicalml/convention/molecular/constraints/bond_must_have_order"
+                 'chemicalml/convention/molecular/constraints/bond_must_have_order'
         autoload :MoleculeMustHaveId,
-                 "chemicalml/convention/molecular/constraints/molecule_must_have_id"
+                 'chemicalml/convention/molecular/constraints/molecule_must_have_id'
         autoload :AtomCoordinatesMustBePaired,
-                 "chemicalml/convention/molecular/constraints/atom_coordinates_must_be_paired"
+                 'chemicalml/convention/molecular/constraints/atom_coordinates_must_be_paired'
         autoload :PropertyMustHaveDictRef,
-                 "chemicalml/convention/molecular/constraints/property_must_have_dict_ref"
+                 'chemicalml/convention/molecular/constraints/property_must_have_dict_ref'
         autoload :ScalarMustHaveDataType,
-                 "chemicalml/convention/molecular/constraints/scalar_must_have_data_type"
+                 'chemicalml/convention/molecular/constraints/scalar_must_have_data_type'
         autoload :BondOrderShouldNotBeNumeric,
-                 "chemicalml/convention/molecular/constraints/bond_order_should_not_be_numeric"
+                 'chemicalml/convention/molecular/constraints/bond_order_should_not_be_numeric'
         autoload :AtomIdMustMatchPattern,
-                 "chemicalml/convention/molecular/constraints/atom_id_must_match_pattern"
+                 'chemicalml/convention/molecular/constraints/atom_id_must_match_pattern'
         autoload :MoleculeCountMustNotAppearOnTopLevel,
-                 "chemicalml/convention/molecular/constraints/molecule_count_must_not_appear_on_top_level"
+                 'chemicalml/convention/molecular/constraints/molecule_count_must_not_appear_on_top_level'
         autoload :MoleculeAtomArrayMutuallyExclusiveWithChildren,
-                 "chemicalml/convention/molecular/constraints/molecule_atom_array_mutually_exclusive_with_children"
+                 'chemicalml/convention/molecular/constraints/molecule_atom_array_mutually_exclusive_with_children'
         autoload :MoleculeBondArrayMutuallyExclusiveWithChildren,
-                 "chemicalml/convention/molecular/constraints/molecule_bond_array_mutually_exclusive_with_children"
+                 'chemicalml/convention/molecular/constraints/molecule_bond_array_mutually_exclusive_with_children'
         autoload :BondStereoWedgeHashMustHaveAtomRefs2,
-                 "chemicalml/convention/molecular/constraints/bond_stereo_wedge_hash_must_have_atom_refs2"
+                 'chemicalml/convention/molecular/constraints/bond_stereo_wedge_hash_must_have_atom_refs2'
         autoload :BondStereoCisTransMustHaveAtomRefs4,
-                 "chemicalml/convention/molecular/constraints/bond_stereo_cis_trans_must_have_atom_refs4"
+                 'chemicalml/convention/molecular/constraints/bond_stereo_cis_trans_must_have_atom_refs4'
         autoload :BondStereoOtherMustHaveDictRef,
-                 "chemicalml/convention/molecular/constraints/bond_stereo_other_must_have_dict_ref"
+                 'chemicalml/convention/molecular/constraints/bond_stereo_other_must_have_dict_ref'
         autoload :BondIdsUniqueWithinMolecule,
-                 "chemicalml/convention/molecular/constraints/bond_ids_unique_within_molecule"
+                 'chemicalml/convention/molecular/constraints/bond_ids_unique_within_molecule'
         autoload :BondOrderOtherMustHaveDictRef,
-                 "chemicalml/convention/molecular/constraints/bond_order_other_must_have_dict_ref"
+                 'chemicalml/convention/molecular/constraints/bond_order_other_must_have_dict_ref'
         autoload :AtomArrayMustBeChildOfMoleculeOrFormula,
-                 "chemicalml/convention/molecular/constraints/atom_array_must_be_child_of_molecule_or_formula"
+                 'chemicalml/convention/molecular/constraints/atom_array_must_be_child_of_molecule_or_formula'
         autoload :BondArrayMustBeChildOfMolecule,
-                 "chemicalml/convention/molecular/constraints/bond_array_must_be_child_of_molecule"
+                 'chemicalml/convention/molecular/constraints/bond_array_must_be_child_of_molecule'
+        autoload :BondOrderShouldBeInEnum,
+                 'chemicalml/convention/molecular/constraints/bond_order_should_be_in_enum'
+        autoload :BondStereoShouldBeInEnum,
+                 'chemicalml/convention/molecular/constraints/bond_stereo_should_be_in_enum'
+        autoload :MoleculeChiralityShouldBeInEnum,
+                 'chemicalml/convention/molecular/constraints/molecule_chirality_should_be_in_enum'
+        autoload :BondAtomRefs2ShouldBeDistinct,
+                 'chemicalml/convention/molecular/constraints/bond_atom_refs2_should_be_distinct'
+        autoload :ReferencesShouldResolve,
+                 'chemicalml/convention/molecular/constraints/references_should_resolve'
+        autoload :BondStereoAtomRefs4ShouldBeDistinct,
+                 'chemicalml/convention/molecular/constraints/bond_stereo_atom_refs4_should_be_distinct'
+        autoload :AtomParityAtomRefs4ShouldBeDistinct,
+                 'chemicalml/convention/molecular/constraints/atom_parity_atom_refs4_should_be_distinct'
+        autoload :AtomElementTypeShouldBeInPeriodicTable,
+                 'chemicalml/convention/molecular/constraints/atom_element_type_should_be_in_periodic_table'
+        autoload :DictRefShouldResolve,
+                 'chemicalml/convention/molecular/constraints/dict_ref_should_resolve'
+        autoload :MoleculeIdShouldMatchPattern,
+                 'chemicalml/convention/molecular/constraints/molecule_id_should_match_pattern'
+        autoload :BondIdShouldMatchPattern,
+                 'chemicalml/convention/molecular/constraints/bond_id_should_match_pattern'
+        autoload :AtomParityShouldIncludeParentAtom,
+                 'chemicalml/convention/molecular/constraints/atom_parity_should_include_parent_atom'
+        autoload :PropertyScalarDataTypeMatchesDictionary,
+                 'chemicalml/convention/molecular/constraints/property_scalar_data_type_matches_dictionary'
       end
     end
   end

data/lib/chemicalml/convention/molecular.rb

@@ -8,9 +8,9 @@ module Chemicalml
     module Molecular
       extend Base
 
-      autoload :Constraints, "chemicalml/convention/molecular/constraints"
+      autoload :Constraints, 'chemicalml/convention/molecular/constraints'
 
-      QNAME = "convention:molecular".freeze
+      QNAME = 'convention:molecular'
       NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}molecular".freeze
 
       def self.qname
@@ -44,6 +44,19 @@ module Chemicalml
       register Constraints::BondOrderOtherMustHaveDictRef
       register Constraints::AtomArrayMustBeChildOfMoleculeOrFormula
       register Constraints::BondArrayMustBeChildOfMolecule
+      register Constraints::BondOrderShouldBeInEnum
+      register Constraints::BondStereoShouldBeInEnum
+      register Constraints::MoleculeChiralityShouldBeInEnum
+      register Constraints::BondAtomRefs2ShouldBeDistinct
+      register Constraints::ReferencesShouldResolve
+      register Constraints::BondStereoAtomRefs4ShouldBeDistinct
+      register Constraints::AtomParityAtomRefs4ShouldBeDistinct
+      register Constraints::AtomElementTypeShouldBeInPeriodicTable
+      register Constraints::DictRefShouldResolve
+      register Constraints::MoleculeIdShouldMatchPattern
+      register Constraints::BondIdShouldMatchPattern
+      register Constraints::AtomParityShouldIncludeParentAtom
+      register Constraints::PropertyScalarDataTypeMatchesDictionary
     end
   end
 end

data/lib/chemicalml/convention/registry.rb

@@ -35,7 +35,7 @@ module Chemicalml
       # declares no convention or an unknown one.
       def self.detect_and_validate(document)
         qname = Convention::Detection.convention_of(document)
-        raise ArgumentError, "document declares no convention attribute" unless qname
+        raise ArgumentError, 'document declares no convention attribute' unless qname
 
         validate_report(document, qname: qname)
       end
@@ -44,21 +44,89 @@ module Chemicalml
         load_cache.keys.sort
       end
 
+      # Iterate every registered convention. Yields the convention
+      # module. Enumerable-style: returns an Enumerator if no block.
+      #
+      # @yield [Module] each convention module.
+      # @return [Array<Module>, Enumerator] the conventions if a
+      #   block is given; otherwise an Enumerator.
+      def self.each(&)
+        return to_enum(:each) unless block_given?
+
+        load_cache.values.sort_by(&:qname).each(&)
+      end
+
+      # Iterate every constraint across every convention. Yields
+      # (convention, constraint_class) pairs. Useful for documentation
+      # generation and code introspection.
+      #
+      # @yieldparam convention [Module] the convention module.
+      # @yieldparam constraint [Class] the constraint class.
+      # @return [Enumerator, Integer] count if block given; otherwise
+      #   an Enumerator.
+      def self.each_constraint(&)
+        return to_enum(:each_constraint) unless block_given?
+
+        count = 0
+        each do |conv|
+          conv.constraints.each do |constraint|
+            yield(conv, constraint)
+            count += 1
+          end
+        end
+        count
+      end
+
+      # Total count of registered constraints across all conventions.
+      def self.total_constraint_count
+        each.sum(&:constraint_count)
+      end
+
+      # True if a document with the given Role could carry a
+      # convention attribute that Detection would recognise.
+      #
+      # @param role [Module] a Role::* module.
+      # @return [Boolean]
+      def self.convention_root?(role)
+        Detection::CONVENTION_ROOTS.any? { |r| role <= r }
+      rescue StandardError
+        Detection::CONVENTION_ROOTS.include?(role)
+      end
+
+      # Register a custom convention at runtime. The convention module
+      # must extend `Chemicalml::Convention::Base` and implement
+      # `qname` and `namespace_uri`.
+      #
+      # @param mod [Module] the convention module (must `extend Base`).
+      # @return [Module] the registered module.
+      # @raise [ArgumentError] if `mod.qname` is nil/empty.
+      def self.register_custom(mod)
+        qname = mod.qname
+        raise ArgumentError, 'convention module must return a non-empty qname' if qname.nil? || qname.to_s.empty?
+
+        # Force load_cache to populate (acquires/releases mutex internally),
+        # then mutate directly without re-entering the mutex.
+        cache = load_cache
+        cache[qname.to_s] = mod
+        mod
+      end
+
       def self.reset!
-        @mutex.synchronize { @cache = nil }
+        @mutex.synchronize { @load_cache = nil }
       end
 
       def self.load_cache
         @mutex.synchronize do
-          @cache ||= begin
-            {
-              Molecular.qname            => Molecular,
-              Compchem.qname             => Compchem,
-              Dictionary.qname           => Dictionary,
-              UnitDictionary.qname       => UnitDictionary,
-              UnitTypeDictionary.qname   => UnitTypeDictionary
-            }
-          end
+          @load_cache ||= {
+            Molecular.qname => Molecular,
+            Compchem.qname => Compchem,
+            Dictionary.qname => Dictionary,
+            UnitDictionary.qname => UnitDictionary,
+            UnitTypeDictionary.qname => UnitTypeDictionary,
+            Spectroscopy.qname => Spectroscopy,
+            Cascade.qname => Cascade,
+            SimpleUnit.qname => SimpleUnit
+          }
         end
       end
       private_class_method :load_cache

data/lib/chemicalml/convention/simple_unit/constraints/root_must_be_unit_list.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module SimpleUnit
+      module Constraints
+        # The root of a simpleUnit document MUST be a `<unitList>`
+        # declaring `convention="convention:simpleUnit"`. Any other
+        # root shape is rejected.
+        class RootMustBeUnitList < Chemicalml::Convention::Constraint::DocumentConstraint
+          self.description = 'The root of a simpleUnit document MUST be a `<unitList>` declaring `convention="convention:simpleUnit"`. Any other root shape is rejected.'
+          def check(document)
+            return [] if document.is_a?(Chemicalml::Cml::Role::UnitList) &&
+                         document.convention == 'convention:simpleUnit'
+
+            [violation(path: '/',
+                       message: 'simpleUnit root must be <unitList> declaring ' \
+                                'convention="convention:simpleUnit"')]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/simple_unit/constraints/unit_must_have_power.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module SimpleUnit
+      module Constraints
+        # A `<unit>` under simpleUnit MUST declare a `power` attribute
+        # (integer). Without a power the unit's exponent is undefined.
+        class UnitMustHavePower < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A `<unit>` under simpleUnit MUST declare a `power` attribute (integer). Without a power the unit's exponent is undefined."
+          applies_to Chemicalml::Cml::Role::Unit
+
+          def check_node(node, _path)
+            power = node.power.to_s.strip
+            return [] unless power.empty?
+
+            [violation(path: yield_path(node),
+                       message: "unit #{node.id.inspect} must declare a power attribute",
+                       value: node.power)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "unit[#{id}]" : 'unit'
+          end
+        end
+      end
+    end
+  end
+end