dcc 0.2.0 → 0.2.2

data/lib/dcc/plugin/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Plugin
+    # Included by a plugin class so it can declare what it adds to Dcc.
+    #
+    # @example
+    #   class MyPlugin
+    #     include Dcc::Plugin::Base
+    #     register_validator MyRule
+    #   end
+    module Base
+      # @param base [Class] the including class.
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # `Profile#call` does `rule_class.new.check_on(dcc)`, so a validator
+      # has to be a class. An instance responds to `#check_on` and so looks
+      # right, but would fail deep inside validation with a message naming
+      # neither the plugin nor the author's line.
+      #
+      # @param entry [Object] the candidate rule.
+      # @raise [ArgumentError] unless entry is a class defining #check_on.
+      # @return [Class] the entry.
+      def self.rule_class!(entry)
+        return entry if rule_class?(entry)
+
+        raise ::ArgumentError,
+              "expected a rule class responding to #check_on, " \
+              "got #{describe(entry)}"
+      end
+
+      # @param entry [Object]
+      # @return [Boolean]
+      def self.rule_class?(entry)
+        entry.is_a?(::Class) && entry.method_defined?(:check_on)
+      end
+      private_class_method :rule_class?
+
+      # @param entry [Object]
+      # @return [String]
+      def self.describe(entry)
+        return entry.inspect if entry.is_a?(::Class)
+
+        "an instance of #{entry.class}"
+      end
+      private_class_method :describe
+
+      # Declaration helpers available on the including class.
+      module ClassMethods
+        # Add a Schematron rule to the active validation profile.
+        #
+        # @param rule_class [Class] a rule class defining `#check_on(dcc)`.
+        # @raise [ArgumentError] unless rule_class is such a class.
+        # @return [Class] the rule class.
+        def register_validator(rule_class)
+          checked = ::Dcc::Plugin::Base.rule_class!(rule_class)
+          ::Dcc::Plugin.register(:validators, checked)
+        end
+      end
+    end
+  end
+end

data/lib/dcc/plugin/registry.rb

@@ -9,12 +9,17 @@ module Dcc
       @mutex = ::Mutex.new
 
       class << self
+        # Idempotent per (category, entry): registering the same entry in
+        # the same category twice is a no-op, so a doubly-loaded plugin does
+        # not run its validators twice.
+        #
         # @param category [Symbol]
         # @param entry [Class, Object]
         # @return [Class, Object]
         def register(category, entry)
           @mutex.synchronize do
-            @categories[category.to_sym] << entry
+            entries = @categories[category.to_sym]
+            entries << entry unless entries.include?(entry)
             entry
           end
         end
@@ -42,4 +47,4 @@ module Dcc
       end
     end
   end
-end
+end

data/lib/dcc/plugin.rb

@@ -5,13 +5,17 @@
 # without modifying the core codebase (Open/Closed Principle).
 #
 # @example Register a custom validator
-#   Dcc::Plugin.register(:validators, MyCustomRule)
+#   class MyPlugin
+#     include Dcc::Plugin::Base
+#     register_validator MyCustomRule
+#   end
 #
 # @example List all registered validators
 #   Dcc::Plugin.all(:validators)
 module Dcc
   module Plugin
     autoload :Registry, "dcc/plugin/registry"
+    autoload :Base, "dcc/plugin/base"
 
     class << self
       # @param category [Symbol] e.g. :validators, :converters, :cli_commands.
@@ -39,4 +43,4 @@ module Dcc
       end
     end
   end
-end
+end

data/lib/dcc/quantity_format/formatter.rb

@@ -45,25 +45,24 @@ module Dcc
       private
 
       def format_value
-        # Two decimals by default; tightened to uncertainty precision when known.
-        return @value.round(2).to_s("F") if uncertainty.nil?
+        # Two decimals by default, tightened to the uncertainty's precision
+        # when it has any. Neither a nil nor a NaN uncertainty has one.
+        return @value.round(2).to_s("F") if uncertainty.nil? || uncertainty.nan?
 
-        # Decimal places = 1 - floor(log10(uncertainty))
-        decimal_places = [0, 1 - Integer(Math.log10(uncertainty.to_f).floor)].max
         @value.round(decimal_places).to_s("F")
       end
 
       def format_uncertainty
         return "" if uncertainty.nil?
+        return "NaN" if uncertainty.nan?
 
-        decimal_places = [0, 1 - Integer(Math.log10(uncertainty.to_f).floor)].max
         uncertainty.round(decimal_places).to_s("F")
       end
 
       def align_value_and_uncertainty
         return [@value.to_s("F"), uncertainty.to_s("F")] if uncertainty.nil?
+        return [format_value, "NaN"] if uncertainty.nan?
 
-        decimal_places = [0, 1 - Integer(Math.log10(uncertainty.to_f).floor)].max
         v_str = @value.round(decimal_places).to_s("F")
         u_str = uncertainty.round(decimal_places).to_s("F")
         # Short form: digits of uncertainty after the last common digit
@@ -71,6 +70,13 @@ module Dcc
         [v_str, last_digits]
       end
 
+      # Decimal places = 1 - floor(log10(uncertainty)). D-SI writes `NaN` for a
+      # not-measured entry (SI_Format.xsd:1195) and `Math.log10` cannot answer
+      # for it, so every caller excludes nil and NaN first.
+      def decimal_places
+        [0, 1 - Integer(Math.log10(uncertainty.to_f).floor)].max
+      end
+
       def unit_suffix
         return "" if unit.nil? || unit.empty?
 
@@ -81,10 +87,10 @@ module Dcc
         unit
           .to_s
           .gsub(/\\([a-z]+)/, '\\1') # \kelvin → kelvin
-          .gsub(/\\per/, '/')
-          .gsub(/\\cubic/, '^3')
-          .gsub(/\\square/, '^2')
+          .gsub("\\per", "/")
+          .gsub("\\cubic", "^3")
+          .gsub("\\square", "^2")
       end
     end
   end
-end
+end

data/lib/dcc/quantity_format.rb

@@ -7,4 +7,4 @@ module Dcc
   module QuantityFormat
     autoload :Formatter, "dcc/quantity_format/formatter"
   end
-end
+end

data/lib/dcc/quantity_math/complex.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Dcc
+  module QuantityMath
+    # A complex quantity in Cartesian form, backed by a two-element `Matrix`:
+    # element 0 is the real part, element 1 the imaginary part, and both
+    # share one unit.
+    #
+    # The full 2x2 covariance is propagated through every operation, so
+    # chaining stays correct. A product's real and imaginary parts are
+    # correlated, and dropping that off-diagonal term understates the next
+    # result — for `(z1 * z2) * z3` by a third in the worked case.
+    #
+    # `+` and `-` assume the two operands are statistically INDEPENDENT, so
+    # `z - z` returns twice the covariance rather than zero.
+    class Complex
+      ONE = BigDecimal(1)
+      private_constant :ONE
+
+      # Significant digits kept for the division derivatives. They are the
+      # only non-terminating arithmetic in the propagation path: Ruby's
+      # `Complex#/` runs Smith's algorithm, whose internal `bim/bre` does not
+      # terminate, so an unbounded derivative carries ~130 digits of which
+      # only ~30 are meaningful. Those digits then multiply forward into
+      # every downstream covariance.
+      #
+      # Bounding them here rather than rounding the covariance is deliberate.
+      # Inside `QuantityMath.exact_covariance`, which sets
+      # `BigDecimal.limit(0)`, multiplication and addition are exact, so
+      # `J C J^T` over bounded derivatives stays exact — and therefore
+      # exactly symmetric and exactly positive semi-definite. That exactness
+      # comes from the zero limit, not from BigDecimal itself: under a
+      # non-zero `BigDecimal.limit` both operations round. Moving any of this
+      # arithmetic outside that block reintroduces the asymmetry the
+      # covariance validation rejects. Rounding the covariance instead would
+      # risk failing PSD validation on the exactly-singular matrices that a
+      # component with no uncertainty produces.
+      #
+      # It happens to equal `SQRT_PRECISION`, but the two are independent:
+      # that one sizes a square root of a variance, this one a derivative.
+      # Changing either should not drag the other along.
+      DERIVATIVE_PRECISION = 30
+
+      attr_reader :matrix
+
+      # @param matrix [Matrix] two elements sharing one unit
+      def initialize(matrix:)
+        ensure_complex_shape!(matrix)
+        @matrix = matrix
+      end
+
+      # @param real [Real] real component
+      # @param imag [Real] imaginary component, same unit as `real`
+      # @param covariance [Array<Array>, nil] 2x2. Defaults to the diagonal
+      #   built from each component's uncertainty; a component with no
+      #   uncertainty contributes zero variance, i.e. is treated as exact.
+      # @return [Complex]
+      def self.cartesian(real:, imag:, covariance: nil)
+        new(matrix: Matrix.new(values: [real.value, imag.value],
+                               units: [real.unit, imag.unit],
+                               covariance: covariance || diagonal(real, imag)))
+      end
+
+      def self.diagonal(real, imag)
+        QuantityMath.exact_covariance do
+          zero = BigDecimal(0)
+          [[variance(real), zero], [zero, variance(imag)]]
+        end
+      end
+
+      def self.variance(component)
+        component.uncertain? ? component.uncertainty**2 : BigDecimal(0)
+      end
+      private_class_method :diagonal, :variance
+
+      # @return [String, nil] siunitx expression shared by both components.
+      def unit
+        matrix.units.first
+      end
+
+      # @return [Real]
+      def real
+        matrix[0]
+      end
+
+      # @return [Real]
+      def imag
+        matrix[1]
+      end
+
+      # @return [Array<Array<BigDecimal>>] the 2x2 covariance.
+      def covariance
+        matrix.covariance
+      end
+
+      # Reads the variances directly rather than going through
+      # `Matrix#uncertainties`: for the non-negative diagonal that validation
+      # guarantees, `x.zero?` and `sqrt(x).zero?` agree, and this avoids two
+      # 30-digit square roots to answer a zero test.
+      #
+      # @return [Boolean] whether either component carries uncertainty.
+      def uncertain?
+        covariance.each_with_index.any? { |row, i| !row[i].zero? }
+      end
+
+      # @return [::Complex] the value as a Ruby Complex of BigDecimals.
+      def to_c
+        ::Complex.rectangular(*matrix.values)
+      end
+
+      # Assumes independence from `other`.
+      # @return [Complex]
+      def +(other)
+        Complex.new(matrix: matrix + other.matrix)
+      end
+
+      # Assumes independence from `other`.
+      # @return [Complex]
+      def -(other)
+        Complex.new(matrix: matrix - other.matrix)
+      end
+
+      # @return [Complex]
+      def *(other)
+        combine(other,
+                value: to_c * other.to_c,
+                unit: compose_unit(unit, other.unit),
+                d_self: other.to_c,
+                d_other: to_c)
+      end
+
+      # The quotient VALUE follows the caller's ambient BigDecimal context,
+      # like every other value here. Its DERIVATIVES feed the covariance, so
+      # `1/z2` and `-z1/z2^2` are computed at full precision instead.
+      #
+      # @raise [ZeroDivisionError] when `other` is exactly 0 + 0i.
+      # @return [Complex]
+      def /(other)
+        ensure_nonzero!(other)
+        divisor = other.to_c
+        d_self, d_other = division_derivatives(divisor)
+        combine(other,
+                value: to_c / divisor,
+                unit: compose_unit(unit, inverse_unit(other.unit)),
+                d_self: d_self, d_other: d_other)
+      end
+
+      def to_s
+        re, im = matrix.values
+        sign = im.negative? ? "-" : "+"
+        suffix = unit ? " #{unit}" : ""
+        "(#{measured(re, 0)}) #{sign} (#{measured(im.abs, 1)})i#{suffix}"
+      end
+
+      private
+
+      # Renders one component, dropping the "± u" when its variance is zero.
+      # `uncertain?` already treats an all-zero covariance as exact, so
+      # printing "± 0.0" would have this class contradicting itself.
+      def measured(value, index)
+        variance = covariance[index][index]
+        return value.to_s if variance.zero?
+
+        "#{value} ± #{variance.sqrt(SQRT_PRECISION)}"
+      end
+
+      # dw/dz1 = 1/z2 and dw/dz2 = -z1/z2^2, both at full precision because
+      # they feed the covariance.
+      def division_derivatives(divisor)
+        QuantityMath.exact_covariance do
+          [bounded(ONE / divisor), bounded(-(to_c / divisor) / divisor)]
+        end
+      end
+
+      # Trims a derivative to DERIVATIVE_PRECISION significant digits.
+      def bounded(derivative)
+        ::Complex.rectangular(
+          derivative.real.div(ONE, DERIVATIVE_PRECISION),
+          derivative.imaginary.div(ONE, DERIVATIVE_PRECISION),
+        )
+      end
+
+      # Stacks self and `other` into one four-element quantity whose
+      # covariance is block-diagonal (the operands are assumed independent of
+      # each other, though each keeps its own internal correlation), then
+      # propagates the 2x4 Jacobian.
+      def combine(other, value:, unit:, d_self:, d_other:)
+        Complex.new(matrix: stack(other).propagate(
+          values: [value.real, value.imaginary],
+          units: [unit, unit],
+          jacobian: jacobian_for(d_self, d_other),
+        ))
+      end
+
+      # `d_self` and `d_other` are the complex derivatives dw/dz1 and dw/dz2.
+      # Multiplying by a complex number p has real Jacobian
+      # [[Re p, -Im p], [Im p, Re p]]. The signs WITHIN each 2x2 rotation
+      # block are load-bearing — unlike a diagonal model, they do not cancel
+      # under J C J^T. Negating a whole block is invisible, because `stack`
+      # always builds a block-diagonal C and each block contributes
+      # `A C A^T`, which is invariant under `A -> -A`. That would stop
+      # holding if correlated operands were ever supported.
+      def jacobian_for(d_self, d_other)
+        [[d_self.real, -d_self.imaginary, d_other.real, -d_other.imaginary],
+         [d_self.imaginary, d_self.real, d_other.imaginary, d_other.real]]
+      end
+
+      def stack(other)
+        Matrix.new(values: matrix.values + other.matrix.values,
+                   units: matrix.units + other.matrix.units,
+                   covariance: block_diagonal(covariance, other.covariance))
+      end
+
+      def block_diagonal(first, second)
+        zeros = [BigDecimal(0), BigDecimal(0)]
+        first.map { |row| row + zeros } + second.map { |row| zeros + row }
+      end
+
+      def ensure_complex_shape!(matrix)
+        unless matrix.values.size == 2
+          raise ::ArgumentError,
+                "complex quantity needs 2 elements, got #{matrix.values.size}"
+        end
+        return if matrix.units.uniq.size == 1
+
+        raise ::ArgumentError, "unit mismatch: #{matrix.units.inspect}"
+      end
+
+      def ensure_nonzero!(other)
+        return unless other.to_c.zero?
+
+        raise ::ZeroDivisionError, "divided by a zero complex quantity"
+      end
+
+      def compose_unit(left, right)
+        return nil if left.nil? && right.nil?
+        return left if right.nil?
+        return right if left.nil?
+
+        "#{left}\\cdot#{right}"
+      end
+
+      def inverse_unit(unit)
+        return nil if unit.nil?
+
+        "#{unit}^-1"
+      end
+    end
+  end
+end

data/lib/dcc/quantity_math/matrix.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Dcc
+  module QuantityMath
+    # A multivariate quantity: a vector of values with per-element units and
+    # a full covariance matrix. Propagation follows the GUM Supplement 2 law
+    # `C_y = J C J^T`, so correlation between elements survives.
+    #
+    # `+` and `-` assume the two operands are statistically INDEPENDENT: the
+    # covariance matrices are summed with no cross term, so `x - x` returns
+    # `2C` rather than zero. Model correlated quantities as elements of one
+    # `Matrix` and combine them with `propagate`.
+    class Matrix
+      attr_reader :values, :units, :covariance
+
+      # @param values [Array<BigDecimal, Numeric, String>]
+      # @param units [Array<String, nil>] one siunitx expression per element
+      # @param covariance [Array<Array<BigDecimal, Numeric, String>>] n by n,
+      #   symmetric and positive semi-definite
+      def initialize(values:, units:, covariance:)
+        @values = values.map { |v| decimal(v) }.freeze
+        @units = units.map { |u| u&.dup&.freeze }.freeze
+        @covariance = decimal_rows(covariance).map(&:freeze).freeze
+        validate!
+      end
+
+      # @return [Array<BigDecimal>] standard uncertainty of each element.
+      def uncertainties
+        covariance.each_with_index.map { |row, i| row[i].sqrt(SQRT_PRECISION) }
+      end
+
+      # @raise [IndexError] when `index` is outside the vector.
+      # @return [Real] element `index` as a univariate quantity.
+      def [](index)
+        ensure_index!(index)
+        Real.new(value: values[index], unit: units[index],
+                 uncertainty: covariance[index][index].sqrt(SQRT_PRECISION))
+      end
+
+      # Assumes independence from `other`.
+      # @return [Matrix]
+      def +(other)
+        ensure_same_units!(other)
+        combine(other) { |a, b| a + b }
+      end
+
+      # Assumes independence from `other`.
+      # @return [Matrix]
+      def -(other)
+        ensure_same_units!(other)
+        combine(other) { |a, b| a - b }
+      end
+
+      # Law of propagation of uncertainty: `C_y = J C J^T`.
+      #
+      # Only the Jacobian's shape is validated. The output values, the
+      # Jacobian entries and the output units are the caller's
+      # responsibility: this does not derive units from the Jacobian and does
+      # not check that `values` is what `jacobian` actually computes.
+      #
+      # @param values [Array<BigDecimal, Numeric>] output values, length m
+      # @param units [Array<String, nil>] output units, length m
+      # @param jacobian [Array<Array<BigDecimal, Numeric>>] m by n
+      # @return [Matrix]
+      def propagate(values:, units:, jacobian:)
+        j = decimal_rows(jacobian)
+        ensure_jacobian_shape!(j, values.size)
+        propagated = QuantityMath.exact_covariance do
+          multiply(multiply(j, covariance), j.transpose)
+        end
+        Matrix.new(values: values, units: units, covariance: propagated)
+      end
+
+      def to_s
+        values.each_index.map { |i| self[i].to_s }.join(", ")
+      end
+
+      private
+
+      # Values combine under the caller's operator. The covariance matrices
+      # always add, off-diagonals included, for both `+` and `-`.
+      def combine(other, &)
+        Matrix.new(
+          values: values.zip(other.values).map(&),
+          units: units,
+          covariance: QuantityMath.exact_covariance do
+            add(covariance, other.covariance)
+          end,
+        )
+      end
+
+      # A matching unit vector implies a matching length, so this also guards
+      # the element-wise zips.
+      def ensure_same_units!(other)
+        return if units == other.units
+
+        raise ::ArgumentError,
+              "unit mismatch: #{units.inspect} vs #{other.units.inspect}"
+      end
+
+      # Negative indices would otherwise wrap silently, and an over-large one
+      # would reach `nil[index]` instead of saying what went wrong.
+      def ensure_index!(index)
+        return if index.between?(0, values.size - 1)
+
+        raise ::IndexError,
+              "index #{index} out of range (0...#{values.size})"
+      end
+
+      def ensure_jacobian_shape!(jacobian, rows)
+        n = values.size
+        return if jacobian.size == rows && jacobian.all? { |row| row.size == n }
+
+        raise ::ArgumentError,
+              "jacobian shape mismatch: expected #{rows}x#{n}, got " \
+              "#{jacobian.size}x#{jacobian.map(&:size).uniq.join(',')}"
+      end
+
+      def validate!
+        validate_dimensions!
+        covariance.each_with_index { |row, i| validate_covariance_row!(row, i) }
+        return if semi_definite?
+
+        raise ::ArgumentError, "covariance matrix is not positive semi-definite"
+      end
+
+      def validate_dimensions!
+        n = values.size
+        return if units.size == n && covariance.size == n &&
+          covariance.all? { |row| row.size == n }
+
+        raise ::ArgumentError,
+              "dimension mismatch: expected #{n} units and a #{n}x#{n} " \
+              "covariance matrix"
+      end
+
+      def validate_covariance_row!(row, row_index)
+        row.each_with_index do |entry, column|
+          validate_covariance_entry!(entry, row_index, column)
+        end
+        return unless row[row_index].negative?
+
+        raise ::ArgumentError,
+              "covariance[#{row_index}][#{row_index}] is a negative variance"
+      end
+
+      def validate_covariance_entry!(entry, row_index, column)
+        unless entry.finite?
+          raise ::ArgumentError,
+                "covariance[#{row_index}][#{column}] is not finite"
+        end
+        return if entry == covariance[column][row_index]
+
+        raise ::ArgumentError,
+              "covariance is not symmetric at [#{row_index}][#{column}]"
+      end
+
+      # LDL^T elimination in exact Rational arithmetic, so there is no
+      # tolerance to tune and a legitimately singular matrix is not
+      # rejected. Nothing computed here escapes the predicate.
+      def semi_definite?
+        work = covariance.map { |row| row.map(&:to_r) }
+        work.each_index.all? { |index| eliminate_pivot!(work, index) }
+      end
+
+      # Eliminates below the pivot at `index`, returning false when that
+      # pivot proves the matrix is not positive semi-definite. A zero pivot
+      # is only admissible when the rest of its column is zero too.
+      def eliminate_pivot!(work, index)
+        pivot = work[index][index]
+        below = work[(index + 1)..]
+        return false if pivot.negative?
+        return below.all? { |row| row[index].zero? } if pivot.zero?
+
+        below.each { |row| reduce_row!(row, work[index], index, pivot) }
+        true
+      end
+
+      def reduce_row!(row, pivot_row, index, pivot)
+        factor = row[index] / pivot
+        (index...row.size).each do |column|
+          row[column] -= factor * pivot_row[column]
+        end
+      end
+
+      def multiply(left, right)
+        columns = right.transpose
+        left.map do |row|
+          columns.map { |column| row.zip(column).sum { |x, y| x * y } }
+        end
+      end
+
+      def add(left, right)
+        left.zip(right).map { |lr, rr| lr.zip(rr).map { |x, y| x + y } }
+      end
+
+      def decimal_rows(rows)
+        rows.map { |row| row.map { |x| decimal(x) } }
+      end
+
+      # Normalises -0 to 0: it survives the `negative?` variance check but
+      # keeps its sign through `sqrt`, which would print an uncertainty of
+      # `-0.0`. A non-terminating Rational is rounded to SQRT_PRECISION
+      # significant digits.
+      def decimal(value)
+        decimal = case value
+                  when ::BigDecimal then value
+                  when ::Rational then BigDecimal(value, SQRT_PRECISION)
+                  else BigDecimal(value.to_s)
+                  end
+        decimal.zero? ? BigDecimal(0) : decimal
+      end
+    end
+  end
+end

data/lib/dcc/quantity_math/quantity.rb

@@ -43,4 +43,4 @@ module Dcc
       end
     end
   end
-end
+end