Added MFPUtils submodule

Author: goualard-f

Project.toml

@@ -1,7 +1,7 @@
 name = "MicroFloatingPoints"
 uuid = "6e0295d3-a2ae-4d9e-ab31-7b55fc0f4333"
 authors = ["Frédéric Goualard <[email protected]>"]
-version = "1.1.0"
+version = "1.2.0"
 
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

README.md

@@ -16,7 +16,7 @@ julia> inexact()
 true
 ```
 
-<!-- Disabling this section pending approval in the general registry.
+
 ## Installation
 
 The package can be installed with the Julia package manager. From the Julia REPL, type `]` to enter the Pkg REPL mode and run:
@@ -30,7 +30,9 @@ Or, equivalently, via the Pkg API:
 ```julia
 julia> import Pkg; Pkg.add("MicroFloatingPoints")
 ```
--->
+
+Note that the `matplotlib` Python package must be available through `PyCall`.
+
 
 ## Documentation
 

docs/make.jl

@@ -2,16 +2,16 @@ using Documenter, Random
 using MicroFloatingPoints
 using MicroFloatingPoints.MFPRandom
 using MicroFloatingPoints.MFPPlot
+using MicroFloatingPoints.MFPUtils
 
-DocMeta.setdocmeta!(MicroFloatingPoints, :DocTestSetup, :(using MicroFloatingPoints, MicroFloatingPoints.MFPRandom, MicroFloatingPoints.MFPPlot); recursive=true)
+DocMeta.setdocmeta!(MicroFloatingPoints, :DocTestSetup, :(using MicroFloatingPoints, MicroFloatingPoints.MFPRandom, MicroFloatingPoints.MFPPlot, MicroFloatingPoints.MFPUtils); recursive=true)
 
 makedocs(
     sitename="The MicroFloatingPoints Documentation",
     authors = "Frédéric Goualard",
     modules = [MicroFloatingPoints, MicroFloatingPoints.MFPRandom, MicroFloatingPoints.MFPPlot],
     format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
     pages = ["Home" => "index.md"
-             "Installation" => "installation.md"
              "A Guided Tour" => "guided-tour.md"
              "Manual" => "manual.md"
              "Developer Documentation" => "developer.md"

docs/src/guided-tour.md

@@ -9,9 +9,10 @@ CurrentModule = MicroFloatingPoints
 # A guided tour
 
 
-The `MicroFloatingPoints` package is organized into three modules:
+The `MicroFloatingPoints` package is organized into four modules:
 
 - `MicroFloatingPoints`: the main module containing the definition of the parameterized type `Floatmu` and the associated methods;
+- `MicroFloatingPoints.MFPUtils`: a module providing miscellaneous utility functions for the `Floatmu` type;
 - `MicroFloatingPoints.MFPPlot`: a module offering various graphical ways to display `Floatmu` floating-point numbers;
 - `MicroFloatingPoints.MFPRandom`: the module overloading [`Random.rand`](https://docs.julialang.org/en/v1/stdlib/Random/#Base.rand) to produce `Floatmu` random values.
 

docs/src/index.md

@@ -4,6 +4,8 @@ The `MicroFloatingPoints` package allows to manipulate small [IEEE 754](https://
 
 The library may serve to exemplify the behavior of IEEE 754 floating-point numbers in a systematic way through the use of very small formats.
 
+## Presentation
+
 At its core, the package defines a new type `Floatmu` parameterized by two integers:
 
 - `szE`, the number of bits used to represent the exponent;
@@ -43,3 +45,20 @@ It is also possible to emulate more established formats such as:
 - Pixar's PXR24: `Floatmu{8,15}`
 - and many more…
 
+## Installation
+
+The package can be installed with the Julia package manager. From the Julia REPL, type `]` to enter the Pkg REPL mode and run:
+
+```julia
+pkg> add MicroFloatingPoints
+```
+
+Or, equivalently, via the Pkg API:
+
+```julia
+julia> import Pkg; Pkg.add("MicroFloatingPoints")
+```
+
+Note that the `matplotlib` Python package must be available through `PyCall`.
+
+

docs/src/installation.md

@@ -3,6 +3,7 @@ DocTestSetup = quote
 	using Distributions, Random
     using MicroFloatingPoints
 	using MicroFloatingPoints.MFPPlot, MicroFloatingPoints.MFPRandom
+	using MicroFloatingPoints.MFPUtils
 end
 CurrentModule = MicroFloatingPoints
 ```
@@ -259,6 +260,18 @@ true
 
 Note that, in the first example, the result of the computation needed rounding, while in the second example, the output is representable but one of the intermediary computation needed rounding. 
 
+## The `MicroFloatingPoints.MFPUtils` module
+
+```@meta
+CurrentModule = MicroFloatingPoints.MFPUtils
+```
+
+The `MicroFloatingPoints.MFPUtils` module offers some utiliy functions to be used either by other modules of the `MicroFloatingPoints` package or directly by the end user.
+
+```@docs
+vertical_popcount(T::Vector{Floatmu{szE,szf}}) where {szE,szf}
+```
+
 
 ## The `MicroFloatingPoints.MFPRandom` module
 
@@ -356,3 +369,24 @@ savefig("realline_Floatmu23b.svg"); nothing # hide
 <img src="./realline_Floatmu23b.svg" alt="Floatmu{2,3} finite and infinite values" />
 </div>
 ```
+
+```@docs
+bits_histogram(T::Vector{Floatmu{szE,szf}}) where {szE,szf}
+```
+
+```@setup bits-histogram-example
+using MicroFloatingPoints, MicroFloatingPoints.MFPPlot, PyPlot
+plt.figure()
+```
+
+```@repl bits-histogram-example
+T=collect(FloatmuIterator(Floatmu{3,5},0.0,1.0,2.0^-6));
+bits_histogram(T)
+savefig("bits_histogram.svg"); nothing # hide
+```
+
+```@raw html
+<div style="text-align: center">
+<img src="./bits_histogram.svg" alt="Floatmu{3,4} bits histogram in [0, 1]" />
+</div>
+```

docs/src/manual.md

@@ -22,8 +22,10 @@ module MFPPlot
 
 using PyPlot
 using ..MicroFloatingPoints
+using ..MicroFloatingPoints.MFPUtils: vertical_popcount
 
 export real_line
+export bits_histogram
 
 """
     real_line(start::Floatmu{szE,szf}, stop::Floatmu{szE,szf};
@@ -33,17 +35,22 @@ export real_line
               ticks = true, 
               fpcolorsub = "purple", fpcolornorm = "blue",
               fpcolorinf="orange") where {szE,szf}
+    real_line(T::Vector{Floatmu{szE,szf}};
+                   ticks = true, fpcolorsub = "purple", fpcolornorm = "blue",
+                   fpcolorinf="orange") where {szE,szf}
+
+Draw floats on the real line.
 
 The first version draws the real line between `start` and `stop` and displays all floating-point
 numbers with `sze` bits exponent and `szf` bits fractional part. The second version draws all finite 
 floating-point for the format `Floatmu{szE,szf}` and adds the infinities where the next/previous 
-float would be with the format `Floatmu{szE+1,szf}`.
+float would be with the format `Floatmu{szE+1,szf}`. The third version draws all floats in the 
+vector `T`.
 
+In the first version, both parameters `start` and `stop` must be finite. An `ArgumentError` exception
+is raised otherwise. The same goes for all values in `T` for the third version.
 
-Both parameters `start` and `stop` must be finite. An `ArgumentError` exception
-is raised otherwise.
-
-Both versions return the figure used for the plot.
+All versions return the figure used for the plot.
 
 The figure may be customized through the named parameters:
 - `ticks`: if `true`, draws a vertical line for each float and adds the value below. If
@@ -57,30 +64,73 @@ The figure may be customized through the named parameters:
 ```@repl
 real_line(-floatmax(Floatmu{2,2}),floatmax(Floatmu{2,2}));
 real_line(Floatmu{2,2});
+real_line(Floatmu{2,2}[-3.5,0.25,1.5,2.0])
 ```
 """
 function real_line end
 
+
+function real_line(T::Vector{Floatmu{szE,szf}};
+                   ticks = true, fpcolorsub = "purple", fpcolornorm = "blue",
+                   fpcolorinf="orange") where {szE,szf}
+    all(isfinite,T) || throw(ArgumentError("parameters must be finite"))
+    (lmost, rmost) = extrema(T)
+    normal_height = 0.04*(convert(Float64,rmost)-convert(Float64,lmost))
+    subnormal_height = .8*normal_height
+    plt.axis("off")
+    fig=plot([lmost,rmost],[0,0],"k-")
+    for v in T
+        if issubnormal(v)
+            if ticks
+                plot([v,v],[-subnormal_height,subnormal_height],"-",color=fpcolorsub)
+                text(v,-normal_height,string(v),fontsize=8,ha="center",va="top",
+                     rotation=90,color=fpcolorsub)
+            else
+                plot(v,0,marker=".",color=fpcolorsub)
+            end
+        else
+            if ticks
+                plot([v,v],[-normal_height,normal_height],"-",color=fpcolornorm)
+                if v == 0.0
+                    text(0,-1.1*normal_height,L"\pm 0",fontsize=8,ha="center",va="top",
+                         rotation=90,color=fpcolornorm)
+                else
+                    text(v,-1.1*normal_height,string(v),fontsize=8,ha="center",va="top",
+                         rotation=90,color=fpcolornorm)
+                end
+            else
+                plot(v,0,marker=".",color=fpcolornorm)
+            end
+        end
+    end
+    return fig
+end
+
+
 function real_line(start::Floatmu{szE,szf}, stop::Floatmu{szE,szf};
                    ticks = true, fpcolorsub = "purple", fpcolornorm = "blue") where {szE,szf}
+    # This version could be rewritten as:
+    # `real_line(collect(FloatmuIterator(start,stop)))`
+    # but is not to benefit from the on-demand generation of floats with
+    # the FloatmuIterator, which avoids creating a potentially large vector.
     (isfinite(start) && isfinite(stop)) || throw(ArgumentError("parameters must be finite"))
 
     normal_height = 0.04*(convert(Float64,stop)-convert(Float64,start))
     subnormal_height = .8*normal_height
     plt.axis("off")
-    fig=plot([start,stop],[0,0],"k-",color="black")
+    fig=plot([start,stop],[0,0],"k-")
     for v in FloatmuIterator(start,stop)
         if issubnormal(v)
             if ticks
-                plot([v,v],[-subnormal_height,subnormal_height],"k-",color=fpcolorsub)
+                plot([v,v],[-subnormal_height,subnormal_height],"-",color=fpcolorsub)
                 text(v,-normal_height,string(v),fontsize=8,ha="center",va="top",
                      rotation=90,color=fpcolorsub)
             else
                 plot(v,0,marker=".",color=fpcolorsub)
             end
         else
             if ticks
-                plot([v,v],[-normal_height,normal_height],"k-",color=fpcolornorm)
+                plot([v,v],[-normal_height,normal_height],"-",color=fpcolornorm)
                 if v == 0.0
                     text(0,-1.1*normal_height,L"\pm 0",fontsize=8,ha="center",va="top",
                          rotation=90,color=fpcolornorm)
@@ -102,12 +152,43 @@ function real_line(::Type{Floatmu{szE,szf}};
     posInf = nextfloat(Floatmu{szE+1,szf}(floatmax(Floatmu{szE,szf})))
     negInf = prevfloat(Floatmu{szE+1,szf}(-floatmax(Floatmu{szE,szf})))
     fig = real_line(-floatmax(Floatmu{szE,szf}),floatmax(Floatmu{szE,szf}),ticks=ticks,fpcolorsub=fpcolorsub,fpcolornorm=fpcolornorm)
-    plot([negInf,posInf],[0,0],"k-",color="black")
+    plot([negInf,posInf],[0,0],"-",color="black")
     plot(negInf,0,marker="o",color=fpcolorinf)
     text(negInf,.02,L"-\infty",ha="center",va="bottom",fontsize=8,color=fpcolorinf)
     plot(posInf,0,marker="o",color=fpcolorinf)
     text(posInf,.02,L"\infty",ha="center",va="bottom",fontsize=8,color=fpcolorinf)
     return fig
 end
 
+
+                   
+"""
+    bits_histogram(T::Vector{Floatmu{szE,szf}};
+                   signcolor = "magenta",
+                   expcolor = "darkolivegreen",
+                   fraccolor = "blue") where {szE,szf}
+
+Draw an histogram of the probability of each bit of the representation of a float
+to be `1` in the sample `T`.
+"""
+function bits_histogram(T::Vector{Floatmu{szE,szf}};
+                        signcolor = "magenta",
+                        expcolor = "darkolivegreen",
+                        fraccolor = "blue") where {szE,szf}
+    occurs = vertical_popcount(T)
+    floatsz = length(occurs)
+    occurs = 100*(occurs ./ length(T))
+    plt.bar(0,occurs[floatsz],color=signcolor)
+    plt.bar(1:szE,occurs[(floatsz-1):-1:(floatsz-szE)],color=expcolor)
+    plt.bar((szE+1):(floatsz-1),occurs[(floatsz-szE-1):-1:1],color=fraccolor)
+    plt.yticks(0:10:100,[string(i) for i in 0.0:0.1:1.0])
+    ticks = [collect(0:10:(floatsz-1));floatsz-1]
+#    plt.gca().invert_xaxis()
+    plt.xticks((floatsz-1) .- ticks, map((x)->string(x),ticks))
+    plt.xlabel("Binary representation",fontdict=Dict("size"=>20))
+    plt.ylabel("Probability to be 1",fontdict=Dict("size"=>20))
+    return nothing
+end
+
+
 end # Module

src/MFPPlot.jl

@@ -0,0 +1,63 @@
+# MFPUtils --
+#
+#	Copyright 2019--2021 University of Nantes, France.
+#
+#	This file is part of the MicroFloatingPoints library.
+#
+#	The MicroFloatingPoints library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation; either version 3 of the License, or (at your
+#	option) any later version.
+#	
+#	The MicroFloatingPoints library is distributed in the hope that it will be useful,
+# but	WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+#	or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+#	for more details.
+#	
+#	You should have received copies of the GNU General Public License and the
+#	GNU Lesser General Public License along with the MicroFloatingPoints Library.
+# If not,	see https://www.gnu.org/licenses/.
+
+module MFPUtils
+
+import ..MicroFloatingPoints: Floatmu
+
+export vertical_popcount
+
+"""
+    vertical_popcount(T::Vector{Floatmu{szE,szf}}) where {szE,szf}
+
+Return a vector `R` of size `1+szE+szf` where `R[i]` is the number of times
+the `i`-th bit of the values in `T` was equal to `1`. 
+
+For this function, the rightmost bit of the binary representation of a `Floatmu` has index `1` and not `0` as usual.
+
+# Examples
+
+```jldoctest
+julia> join(string.(reverse(vertical_popcount(Floatmu{2,2}[1.5])))) == bitstring(Floatmu{2,2}(1.5))
+true
+```
+Note that, in the preceding example, we have to revert the array obtained from `vertical_popcount` because the number of times bit `i` is `1` is saved at position `i`. As a consequence, the value for the rightmost bit of a `Floatmu` appears at the leftmost position of the counting array.
+
+```jldoctest
+julia> println(vertical_popcount(Floatmu{2,2}[0.25,1.5,3.0]))
+[1, 2, 1, 1, 0]
+```
+"""
+function vertical_popcount(T::Vector{Floatmu{szE,szf}}) where {szE,szf}
+    count = zeros(Int,1 + szE + szf)
+    for x in T
+        v = x.v
+        pos = 1
+        while v != 0
+            count[pos] += Int(v & 1)
+            v >>= 1
+            pos += 1
+        end
+    end
+    return count
+end
+
+
+end # Module

src/MFPUtils.jl

@@ -29,10 +29,14 @@ export eligible_step
 
 include("Floatmu.jl")
 
+# Submodule MFPUtils
+include("MFPUtils.jl")
+
 # Submodule MFPPlot
 include("MFPPlot.jl")
 
 # Submodule MFPRandom
 include("MFPRandom.jl")
 
+
 end # module