librand: spec + all 9 milestones complete (rand/i754rand + 4 adapters + Saloon +rand-ray + docs)

libmath/desk/lib/fixed.hoon

@@ -189,6 +189,23 @@
       (~(sun rs %n) (abs:si s))
     (~(mul rs %n) .-1 (~(sun rs %n) (abs:si s)))
   (~(div rs %n) fs (~(sun rs %n) (bex b.prec)))
+::    +from-rd: [@rd prec] -> @
+::
+::  Quantize a double-precision IEEE float to fixed-point, rounding the
+::  scaled value f * 2^b to the nearest integer (ties to even).
+::  Out-of-range results wrap (s-to-twoc).  Mirrors +from-rs at double
+::  precision -- added for /lib/i754rand's distribution-to-fixed-point
+::  composition (librand's rand-spec.md section 12.1: "sample at @rd,
+::  quantize round-to-nearest").
+::    Examples
+::      > (from-rd .~1.5 [8 8])
+::      0x180
+::  Source
+++  from-rd
+  |=  [f=@rd =prec]
+  ^-  @
+  =/  i=@s  (need (~(toi rd %n) (~(mul rd %n) f (~(sun rd %n) (bex b.prec)))))
+  (s-to-twoc:(ng prec) i)
 ::    +neg: [@ prec] -> @
 ::
 ::  Two's-complement negation of a fixed-point number at its own width.

libmath/desk/lib/math.hoon

@@ -70,9 +70,9 @@
     ::  Returns the value 1/sqrt(2) (OEIS A010503).
     ::    Examples
     ::      > invsqt2
-    ::      .70710677
+    ::      .0.70710677
     ::  Source
-    ++  invsqt2  .70710677
+    ++  invsqt2  .0.70710677
     ::    +log2:  @rs
     ::
     ::  Returns the value log(2) (OEIS A002162).

libmath/desk/tests/lib/fixed.hoon

@@ -106,4 +106,13 @@
     %+  expect-eq  !>(`@rs`.-1.5)   !>((to-rs:fixed n1-5 q88))      ::  -1.5
     %+  expect-eq  !>(`@`0x180)     !>((from-rs:fixed (to-rs:fixed 0x180 q88) q88))  ::  round-trip
   ==
+::
+::  +from-rd: mirrors +from-rs at double precision (added for librand's
+::  /lib/i754rand-to-fixed-point composition, rand-spec.md section 12.1).
+::  No +to-rd counterpart exists (not asked for), so no round-trip check.
+++  test-rd-bridge  ^-  tang
+  ;:  weld
+    %+  expect-eq  !>(`@`0x180)     !>((from-rd:fixed .~1.5 q88))    ::  1.5
+    %+  expect-eq  !>(`@`0x1.fdc0)  !>((from-rd:fixed .~-2.25 q88))  ::  -2.25
+  ==
 --

libmath/desk/tests/lib/math-constants.hoon

@@ -0,0 +1,56 @@
+::::  /tests/lib/math-constants -- tau/pi/phi/sqt2/invsqt2 at all four
+::::  precisions (@rs/@rd/@rh/@rq).
+::
+::  Regression for a real bug caught while building librand's /lib/complexrand
+::  adapter: /lib/math's @rs +invsqt2 was written `.70710677` (missing the
+::  leading `.0.` before the fractional digits), which Hoon parses as the
+::  INTEGER 70,710,677.0, not 0.70710677 -- every other precision (rd/rh/rq)
+::  had the correct `int.frac` form, so this only affected @rs. Nothing
+::  exercised +invsqt2:rs:math until then. Expected bits below are ship-
+::  verified (dojo `@ux` casts), not hand-derived.
+::
+/+  *test, math
+|%
+++  test-tau  ^-  tang
+  ;:  weld
+    %+  expect-eq  !>(`@`0x40c9.0fdb)                                  !>(tau:rs:math)
+    %+  expect-eq  !>(`@`0x4019.21fb.5444.2d18)                        !>(tau:rd:math)
+    %+  expect-eq  !>(`@`0x4648)                                       !>(tau:rh:math)
+    %+  expect-eq  !>(`@`0x4001.921f.b544.42d1.8469.898c.c517.01b8)    !>(tau:rq:math)
+  ==
+::
+++  test-pi  ^-  tang
+  ;:  weld
+    %+  expect-eq  !>(`@`0x4049.0fdb)                                  !>(pi:rs:math)
+    %+  expect-eq  !>(`@`0x4009.21fb.5444.2d18)                        !>(pi:rd:math)
+    %+  expect-eq  !>(`@`0x4248)                                       !>(pi:rh:math)
+    %+  expect-eq  !>(`@`0x4000.921f.b544.42d1.8469.898c.c517.01b8)    !>(pi:rq:math)
+  ==
+::
+++  test-phi  ^-  tang
+  ;:  weld
+    %+  expect-eq  !>(`@`0x3fcf.1bbd)                                  !>(phi:rs:math)
+    %+  expect-eq  !>(`@`0x3ff9.e377.9b97.f4a8)                        !>(phi:rd:math)
+    %+  expect-eq  !>(`@`0x3e79)                                       !>(phi:rh:math)
+    %+  expect-eq  !>(`@`0x3fff.9e37.79b9.7f4a.7c15.f39c.c060.5cee)    !>(phi:rq:math)
+  ==
+::
+++  test-sqt2  ^-  tang
+  ;:  weld
+    %+  expect-eq  !>(`@`0x3fb5.04f3)                                  !>(sqt2:rs:math)
+    %+  expect-eq  !>(`@`0x3ff6.a09e.667f.3bcd)                        !>(sqt2:rd:math)
+    %+  expect-eq  !>(`@`0x3da8)                                       !>(sqt2:rh:math)
+    %+  expect-eq  !>(`@`0x3fff.6a09.e667.f3bc.c908.b2fb.1366.ea95)    !>(sqt2:rq:math)
+  ==
+::
+::  +invsqt2:rs is the arm the bug above lived in -- checked against its
+::  IEEE-754 value directly (0.7071067690849304 as a float32), not just
+::  bit-equality with a value that could itself be wrong.
+++  test-invsqt2  ^-  tang
+  ;:  weld
+    %+  expect-eq  !>(`@`0x3f35.04f3)                                  !>(invsqt2:rs:math)
+    %+  expect-eq  !>(`@`0x3fe6.a09e.667f.3bcd)                        !>(invsqt2:rd:math)
+    %+  expect-eq  !>(`@`0x39a8)                                       !>(invsqt2:rh:math)
+    %+  expect-eq  !>(`@`0x3ffe.6a09.e667.f3bc.c908.b2fb.1366.ea95)    !>(invsqt2:rq:math)
+  ==
+--