monotonic.rb 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02f12d8ccd007cc410e5ebeb524fd6761088aebe771409a81323fd331e479e61
-  data.tar.gz: 9bfd7ff12760b554b0921e535803c4e3e07c0c0cdb166b8133f1ab710a6a1d10
+  metadata.gz: 31e7ee27a90e0a41a51e5739b7024b16a2d7e10f71002bde23362bc90ccef9e5
+  data.tar.gz: 48b392a44f8d69bfe6ce2ecaee02b99d47645a148317c97c304188b0584ba3d8
 SHA512:
-  metadata.gz: fb3b665160980c7d6319db88518e9bd6f74a5e7eade1035a61e62c6aaa88e06110b382f02900f4e61fc7509cb7d9167084d5650c95858912c4a5b5bb2ffdcd43
-  data.tar.gz: 9c7c70bb79a05df1608516272583870cd7aab4229e13dce3d626b38fd3426a58c3529bfe2e8ddd2607f3995508c3c1cdcda287212002349db0fabea114a373b5
+  metadata.gz: 32e4581c05f382de37da5794488759f1c7206a54f79f1ad593d1809b9a53dde4407a17e4d3ab4eab8b4eaeaa18caea85dfc4300ab219db1e3291bcacb79987a9
+  data.tar.gz: 308211ccff21283d9ff5a851396ff660df6f605d3ffe607176c26c53075bfc930f3bbfacc5edfee758f11b6e702d7c5bf46de88e3b3193aa3636ef956dcd7664

data/CHANGELOG

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## 20260817
+
+0.10.0: + Monotonic::Measurement arithmetic, so that a speedup is a ratio which knows how well it is known.
+
+1. + Monotonic::Measurement#+ and #-: two intervals give an interval, their doubts combining in quadrature through Measurand rather than by addition. A duration joins as exact, having none of its own, and a bare number is refused, having no unit to be added to.
+2. + Monotonic::Measurement#*: scales by a number, the uncertainty scaling with it. Two intervals are refused, there being no unit of time squared, as Duration::Common refuses them.
+3. + Monotonic::Measurement#/: by a number it stays an interval; by another interval the units cancel and a Measurand is left, dimensionless and carrying the doubt of both. That ratio is t1/tn, and the reason for the release: a speedup stated without knowing whether it is real is worth little.
+4. + Monotonic::Measurement.from: builds from a measurand whose uncertainty has been propagated rather than measured, so that what comes back from arithmetic carries neither an instrument's floor nor a drift still to be applied a second time.
+5. ~ monotonic.rb.gemspec: /measurand >= 0.1.0/measurand >= 0.1.2/. Measurand#/ divided two integer values as integers until 0.1.2, so a ratio of two nanosecond counts came back as 0 rather than 0.8788. #/ is the point of this release and does not work below 0.1.2, which the added tests demonstrate: they fail twice against 0.1.0 and pass against 0.1.2.
+6. + test/Monotonic/Measurement_test.rb: each operator and what it refuses, and the ratio — that it is dimensionless, that it divides exactly, and that it carries the doubt of both operands.
+7. + test/gemspec_test.rb: that each runtime dependency declares a minimum, and which minimum. The existing test asserted the names alone, which is what let 5 above happen: the gemspec named measurand and said nothing about needing a measurand that works. Asserting the whole map means a minimum cannot move without the test being made to agree.
+8. ~ README.md: + the arithmetic to the Description, + a Monotonic::Measurement arithmetic section to Usage, and + a blank line after require in two examples, the other three having had one.
+9. ~ Monotonic::VERSION: /0.9.0/0.10.0/
+
+
 ## 20260816
 
 0.9.0: Use measurand gem, + Monotonic::Measurement and Monotonic::Timer.floor.

data/README.md

@@ -51,6 +51,15 @@ measurement.to_duration.to_microseconds.to_f
 
 Nothing is capped: a day resolved to a hundred nanoseconds prints every figure it has, the absurdity being the mismatch between what the instrument resolves and what was asked of it, which is better seen than rounded away. The floor is a floor and not an error bar — the tail is unbounded and one-sided, the scheduler being free to take the processor away between the two readings — so repeat and take a robust statistic where that matters.
 
+Measurements combine, and what may combine with what follows from the units. Two intervals add and subtract to an interval, their doubts going in quadrature; a duration joins in as exact, having none of its own; a bare number is refused, having no unit to be added to. Scaling by a number keeps the unit and scales the doubt with it, while multiplying two intervals is refused, there being no unit of time squared. Dividing one interval by another cancels the units and leaves a `Measurand` — dimensionless, and still knowing how well it is known, which is what a speedup is.
+
+```ruby
+serial = Monotonic::Timer.time{run_on_one}
+parallel = Monotonic::Timer.time{run_on_eight}
+serial / parallel
+# => Measurand(6.83, 0.00012), dimensionless
+```
+
 
 ## Installation
 
@@ -143,6 +152,7 @@ measurement.to_s
 
 ```ruby
 require 'monotonic.rb'
+
 measurement = Monotonic::Timer.time do |timer|
   i = 0
   500_000.times{puts i += 1}
@@ -157,6 +167,7 @@ measurement.to_s
 
 ```ruby
 require 'monotonic.rb'
+
 timer = Monotonic::Timer.new
 measurement = timer.time do
   i = 0
@@ -167,6 +178,34 @@ measurement.to_s
 ```
 
 
+### Monotonic::Measurement arithmetic
+
+```ruby
+require 'monotonic.rb'
+
+a = Monotonic::Timer.time{sleep 0.001}
+b = Monotonic::Timer.time{sleep 0.002}
+
+(a + b).to_s
+# => "3.01543 ms"
+
+(a * 3).to_s
+# => "3.04629 ms"
+
+a + Duration::Microseconds.new(500)
+# => #<Monotonic::Measurement 1.51543 ms>, a duration being exact
+
+b / a
+# => Measurand(1.97, 0.00011), dimensionless
+
+a * b
+# => TypeError: there is no unit of time squared
+
+a + 5
+# => TypeError: expected an interval or a duration
+```
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/thoran/monotonic.rb/fork )

data/lib/Monotonic/Measurement.rb

@@ -23,6 +23,16 @@ module Monotonic
     # not divide by ten.
     UNITS = [[1, 'ns'], [1_000, 'us'], [1_000_000, 'ms'], [1_000_000_000, 's']]
 
+    class << self
+      # Built from a measurand rather than from a floor, for what comes back
+      # from arithmetic: its uncertainty has been propagated rather than
+      # measured, so it is neither an instrument's floor nor has a drift left to
+      # apply a second time.
+      def from(measurand)
+        allocate.tap{|measurement| measurement.send(:build, measurand)}
+      end
+    end # class << self
+
     attr_reader :nanoseconds
     attr_reader :drift
 
@@ -51,6 +61,35 @@ module Monotonic
       measurand.uncertainty
     end
 
+    # The arithmetic is Measurand's throughout — this only decides what may be
+    # combined with what, and hands back the right kind of thing.  Two intervals
+    # add and subtract to an interval, their uncertainties going in quadrature.
+    def +(addend)
+      self.class.from(measurand + as_measurand(addend, :add))
+    end
+
+    def -(subtrahend)
+      self.class.from(measurand - as_measurand(subtrahend, :subtract))
+    end
+
+    # Scaled by a number it stays an interval, the uncertainty scaling with it.
+    # Multiplied by another interval it would be time squared, which has no unit
+    # here, so it is refused as Duration::Common refuses it.
+    def *(multiplier)
+      if interval?(multiplier)
+        raise TypeError, "can't multiply #{self.class} by #{multiplier.class}: there is no unit of time squared"
+      end
+      self.class.from(measurand * multiplier)
+    end
+
+    # Divided by a number it stays an interval.  Divided by another interval the
+    # units cancel and a Measurand is left — dimensionless, but still knowing how
+    # well it is known, which is what a speedup or a rate is.
+    def /(divisor)
+      return measurand / divisor.measurand if divisor.respond_to?(:measurand)
+      self.class.from(measurand / divisor)
+    end
+
     def unit
       @unit ||= UNITS.reverse.find{|scale, _| @nanoseconds.abs >= scale} || UNITS.first
     end
@@ -114,5 +153,24 @@ module Monotonic
       @floor = floor
       @drift = drift
     end
+
+    # An interval is anything which knows its own doubt, or any duration, which
+    # is exact.  A bare number is neither: it has no unit, so there is nothing to
+    # add it to.
+    def as_measurand(other, verb)
+      return other.measurand if other.respond_to?(:measurand)
+      return Measurand.new(other.to_nanoseconds.to_i) if other.respond_to?(:to_nanoseconds)
+      raise TypeError, "can't #{verb} #{other.class} #{verb == :add ? "to" : "from"} #{self.class}: expected an interval or a duration"
+    end
+
+    def interval?(other)
+      other.respond_to?(:measurand) || other.respond_to?(:to_nanoseconds)
+    end
+
+    def build(measurand)
+      @nanoseconds = measurand.value.round
+      @measurand = measurand
+      @floor = measurand.uncertainty
+    end
   end
 end

data/lib/Monotonic/VERSION.rb

@@ -2,5 +2,5 @@
 # Monotonic::VERSION
 
 module Monotonic
-  VERSION = '0.9.0'
+  VERSION = '0.10.0'
 end

data/monotonic.rb.gemspec

@@ -37,7 +37,7 @@ Gem::Specification.new do |spec|
 
   spec.dependencies = [
     ['duration.rb', '>= 0.4.0'],
-    ['measurand', '>= 0.1.0'],
+    ['measurand', '>= 0.1.2'],
     'sys-uptime'
   ]
 

data/test/Monotonic/Measurement_test.rb

@@ -96,6 +96,67 @@ describe Monotonic::Measurement do
     end
   end
 
+  describe "arithmetic" do
+    it "adds two intervals to an interval, the doubt going in quadrature" do
+      sum = measurement(1_000_000) + measurement(2_000_000)
+      _(sum).must_be_instance_of(Monotonic::Measurement)
+      _(sum.nanoseconds).must_equal(3_000_000)
+      _(sum.uncertainty).must_be_close_to(Math.sqrt(84**2 + 84**2), 0.0001)
+    end
+
+    it "subtracts likewise, the doubt growing rather than cancelling" do
+      difference = measurement(2_000_000) - measurement(1_000_000)
+      _(difference.nanoseconds).must_equal(1_000_000)
+      _(difference.uncertainty).must_be_close_to(Math.sqrt(84**2 + 84**2), 0.0001)
+    end
+
+    it "takes a duration as exact, it having no doubt of its own" do
+      sum = measurement(1_000_000) + Duration::Microseconds.new(500)
+      _(sum.nanoseconds).must_equal(1_500_000)
+      _(sum.uncertainty).must_equal(84)
+    end
+
+    it "refuses a bare number, which has no unit to add" do
+      _{measurement(1_000_000) + 5}.must_raise(TypeError)
+      _{measurement(1_000_000) - 5}.must_raise(TypeError)
+    end
+
+    it "scales by a number, the uncertainty scaling with it" do
+      product = measurement(1_000_000) * 3
+      _(product.nanoseconds).must_equal(3_000_000)
+      _(product.uncertainty).must_equal(252)
+    end
+
+    it "refuses to multiply two intervals, there being no unit of time squared" do
+      _{measurement(1_000_000) * measurement(2_000_000)}.must_raise(TypeError)
+      _{measurement(1_000_000) * Duration::Seconds.new(1)}.must_raise(TypeError)
+    end
+
+    it "divides by a number and stays an interval" do
+      quotient = measurement(1_000_000) / 2
+      _(quotient).must_be_instance_of(Monotonic::Measurement)
+      _(quotient.nanoseconds).must_equal(500_000)
+      _(quotient.uncertainty).must_equal(42)
+    end
+  end
+
+  describe "the ratio of two intervals" do
+    it "is dimensionless, the units having cancelled" do
+      ratio = measurement(9_579_583) / measurement(10_900_458)
+      _(ratio).must_be_instance_of(Measurand)
+      _(ratio.value.to_f).must_be_close_to(0.878824, 0.000001)
+    end
+
+    it "divides exactly rather than as integers, which measurand 0.1.2 settled" do
+      _((measurement(1_000_000) / measurement(3_000_000)).value).must_equal(Rational(1, 3))
+    end
+
+    it "carries the doubt of both, which is what a speedup is worth knowing" do
+      ratio = measurement(9_579_583) / measurement(10_900_458)
+      _(ratio.uncertainty).must_be_close_to(1.026e-05, 1e-8)
+    end
+  end
+
   describe "#to_duration" do
     it "hands the interval to duration.rb, whose business the units are" do
       _(measurement(1_500_000_000).to_duration).must_be_instance_of(Duration::Nanoseconds)

data/test/gemspec_test.rb

@@ -22,6 +22,16 @@ describe 'monotonic.rb.gemspec' do
     _(spec.runtime_dependencies.map(&:name).sort).must_equal(%w{duration.rb measurand sys-uptime})
   end
 
+  # The minimum is what makes a dependency true, and naming the gem alone does
+  # not say that it will work.  0.9.0 constrained measurand to >= 0.1.0, where
+  # #place became public; #/ then became load-bearing at 0.1.2 without the
+  # constraint following it, and Measurement#/ returned 0 against a version the
+  # gemspec called satisfactory.
+  it "declares a minimum version for each runtime dependency" do
+    _(spec.runtime_dependencies.to_h{|dependency| [dependency.name, dependency.requirement.to_s]}) \
+      .must_equal({'duration.rb' => '>= 0.4.0', 'measurand' => '>= 0.1.2', 'sys-uptime' => '>= 0'})
+  end
+
   it "declares its development dependencies" do
     _(spec.development_dependencies.map(&:name).sort).must_equal(%w{minitest minitest-spec-context rake})
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monotonic.rb
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - thoran
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: sys-uptime
   requirement: !ruby/object:Gem::Requirement