Minifloats (minifloat < single-float) support for Common Lisp

cl-minifloats

* cl-minifloats

*cl-minifloats is an experiment with [[https://en.wikipedia.org/wiki/Minifloat][minifloats, floats below 16 bit width]].*

Right now, only one set of operations is supported—conversion from and
to different (8-, 6-, 4-, 3-, and 2-bit floats) formats to/from CL
(single) float.  It's unlikely there will be other operations, because
CL implemenations' float operations are FAST.  Hard to compete with
these on a custom binary format.  But who knows?

** Getting Started
*** Library user setup
If you want to use the library without hacking on it, clone the Git repository to where ASDF can find it:
#+begin_src sh
  git clone --recursive https://codeberg.org/aartaka/cl-minifloats ~/.local/share/common-lisp/source/
#+end_src

And then load ~:cl-minifloats~ in the REPL:
#+begin_src lisp
  (asdf:load-system :cl-minifloats)
  ;; or, if you use Quicklisp
  (ql:quickload :cl-minifloats)
#+end_src

Note that one hard dependency is [[https://github.com/Shinmera/float-features][float-features]]. Install it first.

*** Contributor/developer setup
In case you want to hack on cl-minifloat, all the dependencies are bundled as submodules, so you need to do a recursive clone
#+begin_src sh
  git clone --recursive https://codeberg.org/aartaka/cl-minifloats
#+end_src

After that, you can run an Emacs-friendly development server with
#+begin_src sh
  make slynk
  # or
  make swank
#+end_src

or tests with
#+begin_src sh
  make check
#+end_src

** Examples
Pre-defined (sign.exponent.significand±bias) floats are (see [[./package.lisp]] for up-to-date info):
- 1.4.3
- 1.4.3-2
- 1.3.4
- 1.3.2
- 1.2.1
- 1.1.1
- 0.2.1
- 0.1.1

And a special 1.2.1-abnormal that Wikipedia mentioned.

CL-minifloat provides conversion from specific minifloat types to CL's single-float.

#+begin_src lisp
  (cl-minifloats:1.4.3-2-to-float #b00000000)
  ;; => 0.0
  (cl-minifloats:1.4.3-2-to-float #b00001011)
  ;; => 11.0

  (cl-minifloats:1.2.1-to-float #b0010)
  ;; => 1.0 (100.0%)

  (cl-minifloats:1.2.1-abnormal-to-float #b0001)
  ;; => 0.5 (50.0%)
  (cl-minifloats:1.2.1-abnormal-to-float #b0101)
  ;; => 3.0
#+end_src

You can define new types, like 16-bit half-floats
#+begin_src lisp
  ;; Define half-floats
  (cl-minifloats:define-x->float 1 5 10)
  (1.5.10-to-float #b0000000000000000)
  ;; => 0.0
  (1.5.10-to-float #b0000001111111111)
  ;; => 6.097555e-5 (0.006097555%)
  (1.5.10-to-float #b0011110000000001)
  ;; => 1.0009766 (100.09766%)
  (1.5.10-to-float #b0111110000000000)
  ;; => #.SINGLE-FLOAT-POSITIVE-INFINITY
#+end_src

There are predefined infinity/NaN values for all the built-in (except ~1.2.1-abnormal~) and user-defined types:
#+begin_src lisp
  (cl-minifloats:1.2.1-to-float cl-minifloats:1.2.1-nan)
  ;; => #<single-float quiet NaN>

  (cl-minifloats:0.1.1-to-float cl-minifloats:0.1.1-infinity)
  ;; => #<single-float positive infinity>

  (cl-minifloats:1.4.3-to-float cl-minifloats:1.4.3-positive-infinity)
  ;; => #<single-float positive infinity>

  (cl-minifloats:1.4.3-to-float cl-minifloats:1.4.3-negative-infinity)
  ;; => #<single-float negative infinity>

  (cl-minifloats:1.4.3-to-float cl-minifloats:most-positive-1.4.3)
  ;; => 240.0

  (cl-minifloats:1.4.3-to-float cl-minifloats:most-negative-1.4.3)
  ;; => -240.0

  (cl-minifloats:1.4.3-to-float cl-minifloats:least-positive-1.4.3)
  ;; => 0.001953125 (0.1953125%)

  (cl-minifloats:1.4.3-to-float cl-minifloats:least-negative-1.4.3)
  ;; => -0.001953125 (-0.1953125%)
#+end_src

Note that arithmetic/math operations are not provided (yet?) because they are hard to get right
and will likely be slower than implementation-specific single float ops.
Conversion from minifloat to single float might be preferable for computations.
God, even mature implementation convert minifloats to 32-bit for computations!
Thus minifloats might serve as transport or storage format, not the actual computation ones.

But if you happen to know and implement fast arithmetics for minifloats, I'll be glad to accept patches!

* TODO:
- NVFP4
- FP4
- MXFP4
- MXFP6
- MXFP8
- BF16


cl-minifloats

Upstream URL

Author

License

cl-minifloats

Version:

License:

Authors:

Dependencies:

cl-minifloats/slynk

Dependencies:

cl-minifloats/swank

Dependencies:

cl-minifloats/tests

Dependencies:

Dependencies (4)

Dependents (0)