dcc 0.2.1 → 0.2.2

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.rb

@@ -5,10 +5,38 @@ require "bigdecimal/math"
 
 module Dcc
   # `Dcc::QuantityMath` provides BigDecimal-based arithmetic on D-SI
-  # quantities with proper uncertainty propagation. RSS (root-sum-square)
-  # for addition/subtraction, fractional for multiplication/division.
+  # quantities with proper uncertainty propagation.
+  #
+  # `Real` is scalar: RSS (root-sum-square) for addition and subtraction,
+  # fractional for multiplication and division. `Matrix` is multivariate and
+  # carries a full covariance matrix, propagating by `C_y = J C J^T`.
+  # `Complex` is a Cartesian complex quantity built on a two-element
+  # `Matrix`, so the correlation between its real and imaginary parts
+  # survives every operation.
   module QuantityMath
+    # Significant digits requested when taking the square root of a
+    # BigDecimal variance. Well past double precision; metrology
+    # uncertainties never carry this many digits. Ordinary arithmetic
+    # follows the caller's ambient BigDecimal context.
+    SQRT_PRECISION = 30
+
     autoload :Quantity, "dcc/quantity_math/quantity"
     autoload :Real, "dcc/quantity_math/real"
+    autoload :Matrix, "dcc/quantity_math/matrix"
+    autoload :Complex, "dcc/quantity_math/complex"
+
+    # Runs `block` with an unlimited BigDecimal precision, restoring the
+    # caller's `BigDecimal.limit` on the way out (including when the block
+    # raises). Everything feeding a covariance matrix goes through here: a
+    # rounded result is no longer exactly symmetric, and `Matrix`'s
+    # validation would reject our own output.
+    #
+    # @return [Object] whatever `block` returns
+    def self.exact_covariance
+      BigDecimal.save_limit do
+        BigDecimal.limit(0)
+        yield
+      end
+    end
   end
 end