measurand 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77e11fd475e1104e6ff1b26e9d0528c9e6918a0340832106b58eefe09b46da1e
+  data.tar.gz: ca6538ff0f68ec369df90ced58ab97aa8ed4083680a3c4f4f555f5af80b7ee63
+SHA512:
+  metadata.gz: 48bf9b4e4110cede8150f8abd1521d39e9e39c701d3db7cd0e9697fef8e59aba0e2ac21dd60590b8b71be8d6845bc14212ecc896f1a3085c45cb85ca433dc19e
+  data.tar.gz: 99f5e0811d117c252c0d703b144f30f1283f72d47ffb65b2b07e27d603357f7ac6cc4aa4c4413e1754c54d9734a2f7e9cf7db3abf754c89eb74fae73dc233762

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# CHANGELOG
+
+## [0.0.0] - 20260716
+## + Measurand: measured values with uncertainty and GUM-conformant error propagation.
+
+1. + lib/measurand.rb: Measurand — forward-mode automatic differentiation over a {Source => partial} map; the uncertainty is derived from the partials, not stored, so shared sources correlate (x - x is exactly 0 ± 0).
+2. + Measurand construction: .new, .relative, .cast, .cast\_relative, .from\_samples (mean ± standard error of the mean), .derived
+3. + Measurand arithmetic: +, -, \*, /, \*\*, -@, abs, apply — chain-rule propagation; independent uncertainties combine in quadrature; scalars are exact
+4. + Measurand comparison: ==/eql?/hash (exact: value and uncertainty), <=> (by value, Comparable), consistent\_with?, overlaps?, coerce (scalar-on-the-left arithmetic)
+5. + Measurand readers: value, uncertainty, relative\_uncertainty, exact?
+6. + lib/Measurand/Source.rb: opaque per-source identity carrying its own uncertainty; deliberately no ==/eql?/hash, so shared sources correlate and independently-constructed ones never collapse
+7. + lib/Measurand/Format.rb: uncertainty-driven, PDG-rounded to\_s (ascii: keyword emits +/- instead of ±), to\_parenthetic, inspect (full precision)
+8. + lib/Measurand/Parse.rb: Measurand.parse for ±, +/-, parenthetic (10), relative %, and exact forms; raises ArgumentError rather than returning nil
+9. + lib/Measurand/Math.rb: Measurand::Math.sqrt, exp, log, log10, sin, cos, tan — chain-rule propagation with no Math monkeypatching
+10. + lib/Measurand/Numeric.rb: opt-in Numeric#pm / #± and Enumerable#pm (separate require, so nothing is monkeypatched unless asked)
+11. + lib/Measurand/VERSION.rb
+12. + measurand.gemspec
+13. + Gemfile
+14. + LICENSE
+15. + README.md
+16. + test/test\_helper.rb, test/test\_all.rb
+17. + test/Measurand/Measurand\_test.rb
+18. + test/Measurand/Source\_test.rb
+19. + test/Measurand/Format\_test.rb
+20. + test/Measurand/Parse\_test.rb
+21. + test/Measurand/Math\_test.rb
+22. + test/Measurand/Numeric\_test.rb

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://www.rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thoran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,195 @@
+# measurand
+
+Measured values with uncertainty, and GUM-conformant error propagation.
+
+A `Measurand` is a value with an associated uncertainty. Arithmetic on
+measurands propagates the uncertainty correctly, so a calculation chain can
+tell the truth about how well its result is known.
+
+Uncertainty is propagated by first-order (GUM) error propagation over an
+automatic-differentiation graph. Because each measurand remembers which
+independent sources it depends on, shared sources correlate correctly:
+`x - x` is exactly `0 ± 0`, not `0 ± √2·σ`.
+
+## Installation
+
+```
+gem install measurand
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'measurand'
+```
+
+## Usage
+
+```ruby
+require 'measurand'
+```
+
+### Construction
+
+```ruby
+Measurand.new(5.129213, 0.01)              # value ± uncertainty
+Measurand.new(5.129213)                    # exact; uncertainty 0
+Measurand.relative(5.129213, 0.02)         # 2% relative — how instruments are spec'd
+
+Measurand.cast([5.129, 5.132, 5.128], 0.001)        # shared absolute uncertainty
+Measurand.cast_relative([5.129, 5.132], 0.0002)     # shared relative uncertainty
+
+Measurand.from_samples([5.129, 5.132, 5.128])       # mean ± standard error of the mean
+```
+
+### Parsing
+
+```ruby
+Measurand.parse('5.129213 ± 0.01')
+Measurand.parse('5.129213 +/- 0.01')       # ASCII, since ± is awkward to type
+Measurand.parse('5.129213(10)')            # parenthetic — CODATA/NIST notation
+Measurand.parse('5.129213 ± 1.9%')         # relative
+Measurand.parse('5.129213')                # exact
+```
+
+`parse` raises `ArgumentError` on anything it does not recognise, rather than
+returning `nil`.
+
+### Arithmetic
+
+```ruby
+a + b
+a - b
+a * b
+a / b
+a ** b
+-a
+a.abs
+
+Measurand.new(3.2, 0.1) * 2                # => 6.4 ± 0.2 — scalars are exact
+2 * Measurand.new(3.2, 0.1)                # => 6.4 ± 0.2 — either side
+```
+
+Independent uncertainties combine in quadrature. Shared sources are handled by
+the derivative graph, not assumed independent:
+
+```ruby
+x = Measurand.new(5.0, 0.1)
+x - x                                      # => 0.0 ± 0.0
+x * 2 - x                                  # => 5.0 ± 0.1  (exactly x)
+```
+
+This is the difference from the old `plusminus` gem, which added errors
+linearly: `3.2±0.1 + 4.5±0.1` is `7.7 ± 0.1414`, not `7.7 ± 0.2`.
+
+### Comparison
+
+```ruby
+a == b                 # exact: value AND uncertainty match
+a.eql?(b)
+a <=> b                # by value; Comparable (so <, >, sort order by value)
+a.consistent_with?(b)  # same measurement within combined uncertainty?
+a.overlaps?(b)         # do the ± intervals intersect?
+```
+
+Note that `==` is stricter than `<=>`: two measurands with equal values but
+different uncertainties compare `0` under `<=>` yet are not `==`. The
+scientific question — "are these the same within error?" — is
+`consistent_with?`, which subtracts (so correlation is handled) and asks
+whether zero lies within the combined uncertainty.
+
+### Presentation
+
+Digits follow the uncertainty — showing more precision than the measurement
+supports would be a lie. The uncertainty is rounded by the Particle Data Group
+convention, and the value is rounded to match:
+
+```ruby
+m = Measurand.new(5.129213, 0.01)
+m.to_s                 # => "5.129 ± 0.010"
+m.to_s(ascii: true)    # => "5.129 +/- 0.010"  — for ASCII-only sinks
+m.to_parenthetic       # => "5.129(10)"
+m.inspect              # => "Measurand(5.129213, 0.01)"  — full precision
+```
+
+`to_s` emits the `±` character by default; pass `ascii: true` when writing to a
+stream that isn't UTF-8. `parse` reads both forms, so either round-trips.
+
+### Transcendentals
+
+Kept in a separate module rather than monkeypatching `Math`:
+
+```ruby
+Measurand::Math.sqrt(m)
+Measurand::Math.exp(m)
+Measurand::Math.log(m)
+Measurand::Math.log10(m)
+Measurand::Math.sin(m)
+Measurand::Math.cos(m)
+Measurand::Math.tan(m)
+```
+
+### Numeric sugar — opt-in
+
+Required separately, so nothing is monkeypatched unless you ask:
+
+```ruby
+require 'Measurand/Numeric'
+
+5.129213.pm(0.01)                          # => Measurand(5.129213, 0.01)
+5.129213.±(0.01)                           # alias; not infix — Ruby won't allow it
+[5.129, 5.132].pm(0.001)                   # Enumerable#pm — array of measurands
+```
+
+## Design notes
+
+- **Forward-mode automatic differentiation.** Each measurand carries a map of
+  partial derivatives with respect to the independent sources it depends on.
+  The uncertainty is derived from those partials and the sources' own
+  uncertainties. Shared sources cancel correctly.
+- **`==` is exact, `consistent_with?` is the science.** Equality compares both
+  value and uncertainty; consistency is the interesting question and gets its
+  own name.
+- **The value is not coerced to `Float` at construction.** A reading from a
+  6-digit instrument keeps its type; coercion happens at the point of
+  arithmetic.
+- **No `Math` monkeypatching.** `Measurand::Math` is a separate module.
+
+## Limitations
+
+**Uncertainty is symmetric.** A measurand carries a single standard
+uncertainty, so it is always `value ± σ` — never `value +a −b`. This is the
+first-order (GUM) model, and it matches the reference tools
+([`uncertainties`](https://pypi.org/project/uncertainties/),
+[`errors`](https://cran.r-project.org/package=errors)), which are symmetric by
+design.
+
+Two consequences worth knowing:
+
+- **Quoted asymmetric errors are not represented.** Literature values written
+  `5.3 +0.4 −0.2` — from non-Gaussian likelihoods, low-count Poisson
+  statistics, or parameters near a physical boundary — cannot be stored as
+  such.
+- **Nonlinear propagation is linearized, and therefore symmetrized.** Even from
+  symmetric inputs, a nonlinear function produces an asymmetric interval that
+  first-order propagation flattens back to a single σ. For example,
+  `Measurand::Math.exp(Measurand.new(0.0, 1.0))` reports `1.0 ± 1.0`, but the
+  true ±1σ interval is `[exp(−1), exp(+1)] = [0.368, 2.718]`, i.e. `+1.72 /
+  −0.63`. Near strong nonlinearity or large *relative* uncertainty, read the
+  single σ as a linear approximation, not an exact interval.
+
+Asymmetric and second-order propagation are deferred: combining asymmetric
+errors correctly is genuinely unsettled (see Barlow, *Asymmetric Errors*), and
+doing it properly means Monte-Carlo sampling or second-order moments rather
+than the quadrature used here.
+
+## Related
+
+- Python [`uncertainties`](https://pypi.org/project/uncertainties/) — the
+  reference implementation of this approach.
+- R [`errors`](https://cran.r-project.org/package=errors) — GUM-conformant,
+  and, correctly, leaves units to a separate package.
+
+## License
+
+MIT

data/lib/Measurand/Format.rb

@@ -0,0 +1,68 @@
+# Measurand/Format.rb
+# Measurand::Format
+
+# Uncertainty-driven display. The value is only shown to the precision the
+# uncertainty supports; showing more digits than the measurement supports
+# would be a lie. Rounding of the uncertainty follows the Particle Data Group
+# convention on its three leading digits:
+#   100..354 -> keep two significant figures
+#   355..949 -> keep one significant figure
+#   950..999 -> round up to 1000, keep two significant figures
+# The value is then rounded to the same decimal place as the uncertainty.
+
+class Measurand
+  module Format
+    module_function
+
+    # Returns [rounded_uncertainty, place], where place is the power of ten of
+    # the least significant shown digit (negative for digits after the point).
+    def round_uncertainty(uncertainty)
+      exponent = ::Math.log10(uncertainty).floor
+      leading = (uncertainty / 10.0 ** (exponent - 2)).round
+      if leading < 355
+        significant_figures = 2
+      elsif leading < 950
+        significant_figures = 1
+      else
+        significant_figures = 2
+        exponent += 1
+      end
+      place = exponent - significant_figures + 1
+      [round_to_place(uncertainty, place), place]
+    end
+
+    def round_to_place(number, place)
+      factor = 10.0 ** place
+      (number / factor).round * factor
+    end
+
+    def decimals(place)
+      place < 0 ? -place : 0
+    end
+  end
+
+  def to_s(ascii: false)
+    return @value.to_s if exact?
+    rounded_uncertainty, place = Format.round_uncertainty(uncertainty)
+    digits = Format.decimals(place)
+    "#{fixed(Format.round_to_place(@value, place), digits)} #{ascii ? '+/-' : '±'} #{fixed(rounded_uncertainty, digits)}"
+  end
+
+  def to_parenthetic
+    return @value.to_s if exact?
+    rounded_uncertainty, place = Format.round_uncertainty(uncertainty)
+    digits = Format.decimals(place)
+    parenthetic_digits = (rounded_uncertainty / 10.0 ** place).round
+    "#{fixed(Format.round_to_place(@value, place), digits)}(#{parenthetic_digits})"
+  end
+
+  def inspect
+    "Measurand(#{@value}, #{uncertainty})"
+  end
+
+  private
+
+  def fixed(number, digits)
+    format("%.#{digits}f", number)
+  end
+end

data/lib/Measurand/Math.rb

@@ -0,0 +1,53 @@
+# Measurand/Math.rb
+# Measurand::Math
+
+# Transcendental functions that propagate uncertainty by the chain rule. Kept
+# in a separate module rather than monkeypatching the standard Math, so that
+# requiring measurand changes nothing you did not ask it to.
+#
+# Each function evaluates f(value) and multiplies the partials by f'(value).
+
+class Measurand
+  module Math
+    module_function
+
+    def sqrt(measurand)
+      measurand = wrap(measurand)
+      measurand.apply(::Math.sqrt(measurand.value), 1.0 / (2 * ::Math.sqrt(measurand.value)))
+    end
+
+    def exp(measurand)
+      measurand = wrap(measurand)
+      measurand.apply(::Math.exp(measurand.value), ::Math.exp(measurand.value))
+    end
+
+    def log(measurand)
+      measurand = wrap(measurand)
+      measurand.apply(::Math.log(measurand.value), 1.0 / measurand.value)
+    end
+
+    def log10(measurand)
+      measurand = wrap(measurand)
+      measurand.apply(::Math.log10(measurand.value), 1.0 / (measurand.value * ::Math.log(10)))
+    end
+
+    def sin(measurand)
+      measurand = wrap(measurand)
+      measurand.apply(::Math.sin(measurand.value), ::Math.cos(measurand.value))
+    end
+
+    def cos(measurand)
+      measurand = wrap(measurand)
+      measurand.apply(::Math.cos(measurand.value), -::Math.sin(measurand.value))
+    end
+
+    def tan(measurand)
+      measurand = wrap(measurand)
+      measurand.apply(::Math.tan(measurand.value), 1.0 / (::Math.cos(measurand.value) ** 2))
+    end
+
+    def wrap(measurand)
+      measurand.is_a?(Measurand) ? measurand : Measurand.new(measurand)
+    end
+  end
+end

data/lib/Measurand/Numeric.rb

@@ -0,0 +1,26 @@
+# Measurand/Numeric.rb
+# Measurand::Numeric
+
+# Opt-in sugar. Required separately so that nobody gets a monkeypatch they did
+# not ask for. pm is primary; ± is an alias, since Ruby's parser won't accept
+# it infix (5.129213 ± 0.01 is a SyntaxError) but 5.129213.±(0.01) parses.
+
+require_relative '../measurand'
+
+class Measurand
+  module Numeric
+    def pm(uncertainty)
+      Measurand.new(self, uncertainty)
+    end
+    alias_method :"±", :pm
+  end
+
+  module Enumerable
+    def pm(uncertainty)
+      map{|value| Measurand.new(value, uncertainty)}
+    end
+  end
+end
+
+Numeric.include(Measurand::Numeric)
+Enumerable.include(Measurand::Enumerable)

data/lib/Measurand/Parse.rb

@@ -0,0 +1,38 @@
+# Measurand/Parse.rb
+# Measurand.parse
+
+# Parses the notations a measurand is written in. Raises on anything it does
+# not recognise, rather than returning nil: the whole job of parse is to fail
+# informatively.
+#
+#   "5.129213 ± 0.01"     "5.129213 +/- 0.01"     absolute
+#   "5.129213 ± 1.9%"                             relative
+#   "5.129213(10)"                                parenthetic (CODATA/NIST)
+#   "5.129213"                                    exact
+
+class Measurand
+  NUMBER = '[-+]?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?'
+  PLUS_MINUS = '(?:±|\+/-|\+-)'
+
+  def self.parse(string)
+    string = string.strip
+    case string
+    when /\A(#{NUMBER})\((\d+)\)\z/
+      value, digits = $1, $2
+      new(value.to_f, digits.to_i * 10.0 ** -decimal_places(value))
+    when /\A(#{NUMBER})\s*#{PLUS_MINUS}\s*(#{NUMBER})%\z/
+      relative($1.to_f, $2.to_f / 100)
+    when /\A(#{NUMBER})\s*#{PLUS_MINUS}\s*(#{NUMBER})\z/
+      new($1.to_f, $2.to_f)
+    when /\A#{NUMBER}\z/
+      new(string.to_f)
+    else
+      raise ArgumentError, "can't parse measurand: #{string.inspect}"
+    end
+  end
+
+  def self.decimal_places(number)
+    point = number.index('.')
+    point ? number.length - point - 1 : 0
+  end
+end

data/lib/Measurand/Source.rb

@@ -0,0 +1,19 @@
+# Measurand/Source.rb
+# Measurand::Source
+
+# An independent source of uncertainty. Its identity is load-bearing: two
+# Sources are never equal unless they are the same object, so error
+# propagation can tell whether the same measurement reappears in an
+# expression. Deliberately does not define ==, eql? or hash.
+
+class Measurand
+  class Source
+    attr_reader :uncertainty
+
+    private
+
+    def initialize(uncertainty)
+      @uncertainty = uncertainty.abs
+    end
+  end
+end

data/lib/Measurand/VERSION.rb

@@ -0,0 +1,3 @@
+class Measurand
+  VERSION = '0.0.0'
+end

data/lib/measurand.rb

@@ -0,0 +1,193 @@
+# measurand.rb
+# Measurand
+
+require_relative 'Measurand/Format'
+require_relative 'Measurand/Math'
+require_relative 'Measurand/Parse'
+require_relative 'Measurand/Source'
+require_relative 'Measurand/VERSION'
+
+# A measured value with an associated uncertainty. Arithmetic propagates the
+# uncertainty by first-order (GUM) error propagation, using forward-mode
+# automatic differentiation so that shared sources correlate correctly:
+# x - x is exactly 0 ± 0, not 0 ± sqrt(2)*sigma.
+#
+# Internally a Measurand carries a central @value and a map of @partials,
+# {Source => dvalue/dsource}. The uncertainty is derived from the partials
+# and the sources' own uncertainties, not stored.
+
+class Measurand
+  include Comparable
+
+  class << self
+    # Bypasses the one-source initializer to build a Measurand directly from
+    # a value and an already-computed partials map. Used by every operator.
+    def derived(value, partials)
+      measurand = allocate
+      measurand.send(:build, value, partials)
+      measurand
+    end
+
+    # A value whose uncertainty is a fraction of the value itself, which is
+    # how instruments are usually specified: relative(5.0, 0.02) is 5.0 +/- 2%.
+    def relative(value, relative_uncertainty)
+      new(value, value.abs * relative_uncertainty)
+    end
+
+    def cast(values, uncertainty)
+      values.map{|value| new(value, uncertainty)}
+    end
+
+    def cast_relative(values, relative_uncertainty)
+      values.map{|value| relative(value, relative_uncertainty)}
+    end
+
+    # Mean +/- standard error of the mean, from repeated readings.
+    def from_samples(values)
+      raise ArgumentError, "need at least two samples" if values.size < 2
+      floats = values.map(&:to_f)
+      mean = floats.sum / floats.size
+      variance = floats.map{|value| (value - mean) ** 2}.sum / (floats.size - 1)
+      new(mean, ::Math.sqrt(variance / floats.size))
+    end
+  end
+
+  def value
+    @value
+  end
+
+  def uncertainty
+    @uncertainty ||= ::Math.sqrt(@partials.sum{|source, partial| (partial * source.uncertainty) ** 2})
+  end
+
+  def relative_uncertainty
+    return 0.0 if uncertainty.zero?
+    uncertainty / @value.abs
+  end
+
+  def exact?
+    uncertainty.zero?
+  end
+
+  def +(other)
+    other = wrap(other)
+    self.class.derived(@value + other.value, combine(1.0, other, 1.0))
+  end
+
+  def -(other)
+    other = wrap(other)
+    self.class.derived(@value - other.value, combine(1.0, other, -1.0))
+  end
+
+  def *(other)
+    other = wrap(other)
+    self.class.derived(@value * other.value, combine(other.value, other, @value))
+  end
+
+  def /(other)
+    other = wrap(other)
+    self.class.derived(@value / other.value, combine(1.0 / other.value, other, -@value.to_f / (other.value ** 2)))
+  end
+
+  def **(other)
+    other = wrap(other)
+    dself = other.value * @value ** (other.value - 1)
+    if other.exact?
+      self.class.derived(@value ** other.value, scale(dself))
+    else
+      self.class.derived(@value ** other.value, combine(dself, other, @value ** other.value * ::Math.log(@value)))
+    end
+  end
+
+  def -@
+    self.class.derived(-@value, scale(-1.0))
+  end
+
+  def abs
+    self.class.derived(@value.abs, scale(@value < 0 ? -1.0 : 1.0))
+  end
+
+  # Applies a differentiable unary function: the caller supplies f(value) and
+  # f'(value). This is how Measurand::Math builds transcendentals.
+  def apply(value, derivative)
+    self.class.derived(value, scale(derivative))
+  end
+
+  def ==(other)
+    other.is_a?(Measurand) && @value == other.value && uncertainty == other.uncertainty
+  end
+
+  def eql?(other)
+    other.instance_of?(Measurand) && @value.eql?(other.value) && uncertainty.eql?(other.uncertainty)
+  end
+
+  def hash
+    [@value, uncertainty].hash
+  end
+
+  # By value only, so Comparable's < > sort etc. order by magnitude. Note this
+  # is intentionally looser than ==: two measurands with equal values but
+  # different uncertainties compare 0 here yet are not ==.
+  def <=>(other)
+    other = wrap(other) if other.is_a?(Numeric)
+    return nil unless other.is_a?(Measurand)
+    @value <=> other.value
+  end
+
+  # Are these the same measurement within error? Uses subtraction so shared
+  # sources correlate correctly, then asks whether zero lies within sigmas of
+  # the difference.
+  def consistent_with?(other, sigmas: 1)
+    difference = self - wrap(other)
+    difference.value.abs <= sigmas * difference.uncertainty
+  end
+
+  def overlaps?(other)
+    other = wrap(other)
+    low, high = @value - uncertainty, @value + uncertainty
+    other_low, other_high = other.value - other.uncertainty, other.value + other.uncertainty
+    low <= other_high && other_low <= high
+  end
+
+  # Ruby calls this when a bare number is on the left: 2 * measurand.
+  def coerce(other)
+    [wrap(other), self]
+  end
+
+  protected
+
+  def partials
+    @partials
+  end
+
+  private
+
+  def initialize(value, uncertainty = 0)
+    @value = value
+    @partials = uncertainty.zero? ? {} : {Source.new(uncertainty) => 1.0}
+  end
+
+  def build(value, partials)
+    @value = value
+    @partials = partials
+  end
+
+  def wrap(other)
+    other.is_a?(Measurand) ? other : self.class.new(other)
+  end
+
+  # New partials for a two-operand function f, given df/dself and df/dother.
+  # Sources shared between the operands sum here, which is where correlation
+  # is actually handled.
+  def combine(dself, other, dother)
+    result = Hash.new(0.0)
+    @partials.each{|source, partial| result[source] += partial * dself}
+    other.partials.each{|source, partial| result[source] += partial * dother}
+    result
+  end
+
+  # New partials for a unary function, scaling every partial by df/dself.
+  def scale(dself)
+    @partials.each_with_object({}){|(source, partial), result| result[source] = partial * dself}
+  end
+end

data/measurand.gemspec

@@ -0,0 +1,27 @@
+require_relative './lib/Measurand/VERSION'
+
+Gem::Specification.new do |spec|
+  spec.name = 'measurand'
+  spec.version = Measurand::VERSION
+
+  spec.summary = "Measured values with uncertainty and GUM-conformant error propagation."
+  spec.description = "Measured values with uncertainty, propagated by first-order (GUM) error propagation over an automatic-differentiation graph, so that shared sources correlate correctly. Quadrature done right, not linear addition. Parsing, PDG-rounded presentation, and transcendentals."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'http://github.com/thoran/measurand'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 2.5'
+
+  spec.files = [
+    'measurand.gemspec',
+    'Gemfile',
+    Dir['lib/**/*.rb'],
+    'CHANGELOG.md',
+    'LICENSE',
+    'README.md',
+    Dir['test/**/*.rb']
+  ].flatten
+  spec.require_paths = ['lib']
+end

data/test/Measurand/Format_test.rb

@@ -0,0 +1,54 @@
+# test/Measurand/Format_test.rb
+
+require_relative '../test_helper'
+
+describe "Measurand formatting" do
+  describe "to_s, PDG-rounded" do
+    it "keeps two significant figures when the leading digits are 100..354" do
+      _(Measurand.new(5.129213, 0.01).to_s).must_equal "5.129 ± 0.010"
+      _(Measurand.new(1.23456, 0.0123).to_s).must_equal "1.235 ± 0.012"
+    end
+
+    it "keeps one significant figure when the leading digits are 355..949" do
+      _(Measurand.new(1.23456, 0.0356).to_s).must_equal "1.23 ± 0.04"
+    end
+
+    it "rounds up to two significant figures when the leading digits are 950..999" do
+      _(Measurand.new(1.23456, 0.096).to_s).must_equal "1.23 ± 0.10"
+    end
+
+    it "handles uncertainty larger than one" do
+      _(Measurand.new(1234.4, 12.3).to_s).must_equal "1234 ± 12"
+    end
+
+    it "shows only the value when exact" do
+      _(Measurand.new(5.0).to_s).must_equal "5.0"
+      _(Measurand.new(5).to_s).must_equal "5"
+    end
+
+    it "emits ASCII +/- on request, and parse reads it back" do
+      m = Measurand.new(5.129213, 0.01)
+      _(m.to_s(ascii: true)).must_equal "5.129 +/- 0.010"
+      reparsed = Measurand.parse(m.to_s(ascii: true))
+      _(reparsed.value).must_be_close_to 5.129
+      _(reparsed.uncertainty).must_be_close_to 0.010
+    end
+  end
+
+  describe "to_parenthetic" do
+    it "expresses the uncertainty in units of the last shown digit" do
+      _(Measurand.new(5.129213, 0.01).to_parenthetic).must_equal "5.129(10)"
+      _(Measurand.new(1.23456, 0.0356).to_parenthetic).must_equal "1.23(4)"
+    end
+
+    it "shows only the value when exact" do
+      _(Measurand.new(5.0).to_parenthetic).must_equal "5.0"
+    end
+  end
+
+  describe "inspect" do
+    it "shows the full-precision value and uncertainty" do
+      _(Measurand.new(5.129213, 0.01).inspect).must_equal "Measurand(5.129213, 0.01)"
+    end
+  end
+end

data/test/Measurand/Math_test.rb

@@ -0,0 +1,41 @@
+# test/Measurand/Math_test.rb
+
+require_relative '../test_helper'
+
+describe Measurand::Math do
+  it "propagates through sqrt: d/dx sqrt(x) = 1/(2 sqrt(x))" do
+    m = Measurand::Math.sqrt(Measurand.new(4.0, 0.1))
+    _(m.value).must_equal 2.0
+    _(m.uncertainty).must_be_close_to 0.025
+  end
+
+  it "propagates through exp: d/dx exp(x) = exp(x)" do
+    m = Measurand::Math.exp(Measurand.new(1.0, 0.1))
+    _(m.value).must_be_close_to ::Math::E
+    _(m.uncertainty).must_be_close_to ::Math::E * 0.1, 0.0001
+  end
+
+  it "propagates through log: d/dx ln(x) = 1/x" do
+    m = Measurand::Math.log(Measurand.new(2.0, 0.1))
+    _(m.value).must_be_close_to ::Math.log(2.0)
+    _(m.uncertainty).must_be_close_to 0.05
+  end
+
+  it "propagates through sin: d/dx sin(x) = cos(x)" do
+    m = Measurand::Math.sin(Measurand.new(0.0, 0.1))
+    _(m.value).must_equal 0.0
+    _(m.uncertainty).must_be_close_to 0.1
+  end
+
+  it "propagates through cos: d/dx cos(x) = -sin(x)" do
+    m = Measurand::Math.cos(Measurand.new(0.0, 0.1))
+    _(m.value).must_equal 1.0
+    _(m.uncertainty).must_equal 0.0
+  end
+
+  it "accepts a bare number and returns an exact result" do
+    m = Measurand::Math.sqrt(4.0)
+    _(m.value).must_equal 2.0
+    _(m.exact?).must_equal true
+  end
+end

data/test/Measurand/Measurand_test.rb

@@ -0,0 +1,206 @@
+# test/Measurand/Measurand_test.rb
+
+require_relative '../test_helper'
+
+describe Measurand do
+  describe "construction" do
+    it "holds a value and an uncertainty" do
+      m = Measurand.new(5.129213, 0.01)
+      _(m.value).must_equal 5.129213
+      _(m.uncertainty).must_equal 0.01
+    end
+
+    it "is exact with no uncertainty" do
+      m = Measurand.new(5.129213)
+      _(m.uncertainty).must_equal 0.0
+      _(m.exact?).must_equal true
+    end
+
+    it "does not coerce the value to Float" do
+      _(Measurand.new(5).value).must_be_kind_of Integer
+      _(Measurand.new(Rational(1, 3)).value).must_be_kind_of Rational
+    end
+
+    it "builds from a relative uncertainty" do
+      m = Measurand.relative(5.0, 0.02)
+      _(m.uncertainty).must_be_close_to 0.1
+    end
+
+    it "casts a collection with a shared uncertainty" do
+      ms = Measurand.cast([5.129, 5.132, 5.128], 0.001)
+      _(ms.map(&:uncertainty)).must_equal [0.001, 0.001, 0.001]
+    end
+
+    it "casts a collection with a shared relative uncertainty" do
+      ms = Measurand.cast_relative([10.0, 20.0], 0.01)
+      _(ms.map(&:uncertainty)).must_equal [0.1, 0.2]
+    end
+  end
+
+  describe "readers" do
+    it "reports relative uncertainty" do
+      _(Measurand.new(10.0, 0.5).relative_uncertainty).must_be_close_to 0.05
+    end
+
+    it "reports zero relative uncertainty when exact" do
+      _(Measurand.new(10.0).relative_uncertainty).must_equal 0.0
+    end
+  end
+
+  describe "from_samples" do
+    it "is the mean plus or minus the standard error of the mean" do
+      m = Measurand.from_samples([5.0, 5.0, 5.0, 5.0])
+      _(m.value).must_equal 5.0
+      _(m.uncertainty).must_equal 0.0
+    end
+
+    it "computes the standard error of the mean" do
+      # sample sd of [2,4,4,4,5,5,7,9] is 2.138; sem = 2.138/sqrt(8)
+      m = Measurand.from_samples([2, 4, 4, 4, 5, 5, 7, 9])
+      _(m.value).must_equal 5.0
+      _(m.uncertainty).must_be_close_to 0.7559, 0.001
+    end
+
+    it "needs at least two samples" do
+      _{Measurand.from_samples([5.0])}.must_raise ArgumentError
+    end
+  end
+
+  describe "arithmetic" do
+    it "adds in quadrature, not linearly (the plusminus regression)" do
+      sum = Measurand.new(3.2, 0.1) + Measurand.new(4.5, 0.1)
+      _(sum.value).must_equal 7.7
+      _(sum.uncertainty).must_be_close_to 0.14142, 0.00001
+    end
+
+    it "subtracts in quadrature" do
+      difference = Measurand.new(4.5, 0.1) - Measurand.new(3.2, 0.1)
+      _(difference.value).must_be_close_to 1.3
+      _(difference.uncertainty).must_be_close_to 0.14142, 0.00001
+    end
+
+    it "combines relative uncertainties in quadrature when multiplying" do
+      product = Measurand.new(10.0, 0.1) * Measurand.new(20.0, 0.4)
+      _(product.value).must_equal 200.0
+      _(product.relative_uncertainty).must_be_close_to 0.02236, 0.00001
+    end
+
+    it "combines relative uncertainties in quadrature when dividing" do
+      quotient = Measurand.new(10.0, 0.1) / Measurand.new(20.0, 0.4)
+      _(quotient.value).must_equal 0.5
+      _(quotient.relative_uncertainty).must_be_close_to 0.02236, 0.00001
+    end
+
+    it "propagates through a scalar power" do
+      squared = Measurand.new(3.0, 0.1) ** 2
+      _(squared.value).must_equal 9.0
+      _(squared.uncertainty).must_be_close_to 0.6, 0.00001
+    end
+
+    it "propagates through an uncertain power" do
+      result = Measurand.new(2.0, 0.1) ** Measurand.new(3.0, 0.1)
+      _(result.value).must_be_close_to 8.0
+      # df/da = 3*2^2 = 12, df/db = 2^3*ln2 = 5.545
+      # unc = sqrt((12*0.1)^2 + (5.545*0.1)^2) = sqrt(1.44 + 0.3075)
+      _(result.uncertainty).must_be_close_to 1.3222, 0.001
+    end
+
+    it "negates" do
+      m = -Measurand.new(3.0, 0.1)
+      _(m.value).must_equal(-3.0)
+      _(m.uncertainty).must_equal 0.1
+    end
+
+    it "takes an absolute value, preserving uncertainty" do
+      m = Measurand.new(-3.0, 0.1).abs
+      _(m.value).must_equal 3.0
+      _(m.uncertainty).must_equal 0.1
+    end
+  end
+
+  describe "scalars are exact" do
+    it "scales value and uncertainty together without adding uncertainty" do
+      m = Measurand.new(3.2, 0.1) * 2
+      _(m.value).must_equal 6.4
+      _(m.uncertainty).must_equal 0.2
+    end
+
+    it "works with the scalar on the left, through coerce" do
+      m = 2 * Measurand.new(3.2, 0.1)
+      _(m.value).must_equal 6.4
+      _(m.uncertainty).must_equal 0.2
+    end
+
+    it "adds an exact scalar without adding uncertainty" do
+      m = Measurand.new(3.2, 0.1) + 1
+      _(m.value).must_equal 4.2
+      _(m.uncertainty).must_equal 0.1
+    end
+  end
+
+  describe "correlation" do
+    it "cancels a variable against itself: x - x is exactly zero" do
+      x = Measurand.new(5.0, 0.1)
+      difference = x - x
+      _(difference.value).must_equal 0.0
+      _(difference.uncertainty).must_equal 0.0
+    end
+
+    it "does not cancel independently constructed measurands of equal value" do
+      difference = Measurand.new(5.0, 0.1) - Measurand.new(5.0, 0.1)
+      _(difference.uncertainty).must_be_close_to 0.14142, 0.00001
+    end
+
+    it "handles 2x - x as exactly x" do
+      x = Measurand.new(5.0, 0.1)
+      result = x * 2 - x
+      _(result.value).must_equal 5.0
+      _(result.uncertainty).must_be_close_to 0.1
+    end
+  end
+
+  describe "comparison" do
+    it "is equal when value and uncertainty both match" do
+      _(Measurand.new(5.0, 0.1)).must_equal Measurand.new(5.0, 0.1)
+    end
+
+    it "is not equal when the uncertainty differs" do
+      _(Measurand.new(5.0, 0.1)).wont_equal Measurand.new(5.0, 0.2)
+    end
+
+    it "orders by value alone, looser than equality" do
+      a = Measurand.new(5.0, 0.1)
+      b = Measurand.new(5.0, 0.2)
+      _(a <=> b).must_equal 0
+      _(a == b).must_equal false
+    end
+
+    it "is Comparable by value" do
+      _(Measurand.new(3.0, 0.5) < Measurand.new(4.0, 0.1)).must_equal true
+    end
+
+    it "eql? and hash agree" do
+      a = Measurand.new(5.0, 0.1)
+      b = Measurand.new(5.0, 0.1)
+      _(a.eql?(b)).must_equal true
+      _(a.hash).must_equal b.hash
+    end
+
+    it "asks whether two measurements are consistent within error" do
+      a = Measurand.new(5.0, 0.1)
+      _(a.consistent_with?(Measurand.new(5.05, 0.1))).must_equal true
+      _(a.consistent_with?(Measurand.new(5.5, 0.1))).must_equal false
+    end
+
+    it "is consistent with itself" do
+      x = Measurand.new(5.0, 0.1)
+      _(x.consistent_with?(x)).must_equal true
+    end
+
+    it "reports overlapping intervals" do
+      a = Measurand.new(5.0, 0.1)
+      _(a.overlaps?(Measurand.new(5.15, 0.1))).must_equal true
+      _(a.overlaps?(Measurand.new(5.3, 0.1))).must_equal false
+    end
+  end
+end

data/test/Measurand/Numeric_test.rb

@@ -0,0 +1,32 @@
+# test/Measurand/Numeric_test.rb
+
+require_relative '../test_helper'
+require_relative '../../lib/Measurand/Numeric'
+
+describe Measurand::Numeric do
+  it "builds a measurand from a number with pm" do
+    m = 5.129213.pm(0.01)
+    _(m).must_be_instance_of Measurand
+    _(m.value).must_equal 5.129213
+    _(m.uncertainty).must_equal 0.01
+  end
+
+  it "aliases pm as ±" do
+    m = 5.129213.±(0.01)
+    _(m).must_be_instance_of Measurand
+    _(m.uncertainty).must_equal 0.01
+  end
+
+  it "reproduces the plusminus regression correctly" do
+    sum = 3.2.pm(0.1) + 4.5.pm(0.1)
+    _(sum.value).must_equal 7.7
+    _(sum.uncertainty).must_be_close_to 0.14142, 0.00001
+  end
+
+  it "builds an array of measurands from an Enumerable with pm" do
+    ms = [5.129, 5.132, 5.128].pm(0.001)
+    _(ms).must_be_kind_of Array
+    _(ms.map(&:value)).must_equal [5.129, 5.132, 5.128]
+    _(ms.map(&:uncertainty)).must_equal [0.001, 0.001, 0.001]
+  end
+end

data/test/Measurand/Parse_test.rb

@@ -0,0 +1,46 @@
+# test/Measurand/Parse_test.rb
+
+require_relative '../test_helper'
+
+describe "Measurand.parse" do
+  it "parses the unicode plus-minus notation" do
+    m = Measurand.parse('5.129213 ± 0.01')
+    _(m.value).must_equal 5.129213
+    _(m.uncertainty).must_equal 0.01
+  end
+
+  it "parses the ASCII plus-minus notation" do
+    m = Measurand.parse('5.129213 +/- 0.01')
+    _(m.value).must_equal 5.129213
+    _(m.uncertainty).must_equal 0.01
+  end
+
+  it "parses parenthetic CODATA/NIST notation" do
+    m = Measurand.parse('5.129213(10)')
+    _(m.value).must_equal 5.129213
+    _(m.uncertainty).must_be_close_to 0.00001
+  end
+
+  it "parses relative notation" do
+    m = Measurand.parse('5.0 ± 2%')
+    _(m.value).must_equal 5.0
+    _(m.uncertainty).must_be_close_to 0.1
+  end
+
+  it "parses an exact value" do
+    m = Measurand.parse('5.129213')
+    _(m.value).must_equal 5.129213
+    _(m.exact?).must_equal true
+  end
+
+  it "raises on unparseable input, rather than returning nil" do
+    _{Measurand.parse('not a measurand')}.must_raise ArgumentError
+  end
+
+  it "round-trips through to_parenthetic at display precision" do
+    m = Measurand.new(5.129213, 0.01)
+    reparsed = Measurand.parse(m.to_parenthetic)
+    _(reparsed.value).must_be_close_to 5.129
+    _(reparsed.uncertainty).must_be_close_to 0.010
+  end
+end

data/test/Measurand/Source_test.rb

@@ -0,0 +1,23 @@
+# test/Measurand/Source_test.rb
+
+require_relative '../test_helper'
+
+describe Measurand::Source do
+  it "is equal only to itself, never to another source of the same size" do
+    a = Measurand::Source.new(0.1)
+    b = Measurand::Source.new(0.1)
+    _(a).must_equal a
+    _(a).wont_equal b
+  end
+
+  it "keeps distinct sources distinct as hash keys" do
+    a = Measurand::Source.new(0.1)
+    b = Measurand::Source.new(0.1)
+    hash = {a => 1.0, b => 1.0}
+    _(hash.size).must_equal 2
+  end
+
+  it "stores uncertainty as a magnitude" do
+    _(Measurand::Source.new(-0.1).uncertainty).must_equal 0.1
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+# test/test_helper.rb
+
+require 'minitest/autorun'
+require 'minitest/spec'
+
+require_relative '../lib/measurand'

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: measurand
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- thoran
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Measured values with uncertainty, propagated by first-order (GUM) error
+  propagation over an automatic-differentiation graph, so that shared sources correlate
+  correctly. Quadrature done right, not linear addition. Parsing, PDG-rounded presentation,
+  and transcendentals.
+email: code@thoran.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- lib/Measurand/Format.rb
+- lib/Measurand/Math.rb
+- lib/Measurand/Numeric.rb
+- lib/Measurand/Parse.rb
+- lib/Measurand/Source.rb
+- lib/Measurand/VERSION.rb
+- lib/measurand.rb
+- measurand.gemspec
+- test/Measurand/Format_test.rb
+- test/Measurand/Math_test.rb
+- test/Measurand/Measurand_test.rb
+- test/Measurand/Numeric_test.rb
+- test/Measurand/Parse_test.rb
+- test/Measurand/Source_test.rb
+- test/test_helper.rb
+homepage: http://github.com/thoran/measurand
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Measured values with uncertainty and GUM-conformant error propagation.
+test_files: []