Hygiene and maintenance

.github/workflows/ci.yml

@@ -12,27 +12,34 @@ env:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     steps:
 
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: 1.8
+          version: 1.10.5
 
       - name: Install Latex Dependencies
         run:
           sudo apt update && sudo apt install -y pdf2svg texlive-latex-base texlive-binaries texlive-latex-extra texlive-luatex
 
+      - name: Install SymPy
+        run: 
+          pip3 install sympy
+
       - name: Instantiate Packages
         run: |
           julia --project -e 'using Pkg; Pkg.instantiate(); Pkg.build();'
+          julia --project -e 'using Pkg; Pkg.add(url="https://github.com/PoorvaGarg/IRTools.jl", rev="loop-break-patch"); Pkg.add("SymPy");'
 
       - name: Unit Tests
         run:
           julia --project --check-bounds=yes --depwarn=yes -e 'import Pkg; Pkg.test(; coverage=true)'
 
-      # - name: Codecov Upload
-      #   run:
-      #     julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder());'
+      - name: Codecov Upload
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        run:
+          julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder());'

.gitignore

@@ -23,4 +23,5 @@ docs/site/
 # environment.
 Manifest.toml
 
-scratch/
+scratch/
+support*

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "julia.executablePath": "/usr/local/bin/julia"
+}

Project.toml

@@ -4,24 +4,33 @@ authors = ["Guy Van den Broeck <[email protected]>"]
 version = "0.1.0"
 
 [deps]
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CUDD = "345a2cc7-28d8-58b2-abdf-cff77ea7d7f1"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 DirectedAcyclicGraphs = "1e6dae5e-d6e2-422d-9af3-452e7a3785ee"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 IRTools = "7869d1d1-7146-5819-86e3-90919afe41df"
 Jive = "ba5e3d4b-8524-549f-bc71-e76ad9e9deed"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+SymPy = "24249f21-da20-56a4-8eb1-6a02cf4ae2e6"
+SymbolicNumericIntegration = "78aadeae-fbc0-11eb-17b6-c7ec0477ba9e"
+Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 
 [compat]
 CUDD = "0.3"
 DataStructures = "0.18"
 DirectedAcyclicGraphs = "0.1.1"
 Distributions = "0.25"
 Graphs = "1"
-IRTools = "0.4.11"
 Jive = "0.2"
 MacroTools = "0.5"
 PrecompileTools = "1"
 julia = "1.8,1.9"
+
+[sources.IRTools]
+rev = "loop-break-patch"
+url = "https://github.com/PoorvaGarg/IRTools.jl"

README.md

@@ -1,35 +1,122 @@
-# Dice.jl
+# HyBit
 
 [![Unit Tests](https://github.com/Juice-jl/Dice.jl/workflows/Unit%20Tests/badge.svg)](https://github.com/Juice-jl/Dice.jl/actions?query=workflow%3A%22Unit+Tests%22+branch%3Amain)  [![codecov](https://codecov.io/gh/Juice-jl/Dice.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/Juice-jl/Dice.jl)
 
-A Julia prototype implementation of the Dice probabilistic programming language.
-See [https://github.com/SHoltzen/dice](https://github.com/SHoltzen/dice)
-
+`HyBit` is a bit blasting based probabilistic programming system for discrete-continuous probabilistic programs. It is built on top of another probabilistic programming language Dice See [https://github.com/SHoltzen/dice](https://github.com/SHoltzen/dice).  
 
 ## Installation
 
-Install Julia 1.7 or higher using [these instructions](https://julialang.org/downloads/platform/).
+Install Julia 1.8.5 or higher using [these instructions](https://julialang.org/downloads/platform/).
+
+Then, install SymPy and IRTools using the following command:
+
+```bash
+pip3 install sympy
+```
+
+Next, clone the repository and start julia in project mode for current folder:
 
-Clone the repository and start julia in project mode for current folder:
 ```bash
 cd Dice.jl
 julia --project
 ```
 
-Install Dice and update dependencies (one can also use `precompile` or `build`):
+In Julia REPL, then use the following command to install all the needed dependencies
+
+```julia
+using Pkg; Pkg.instantiate()
+```
+
+Once the Dice Julia package is instantiated, its inference algorithm and HyBit is ready to use.
+
+## Quick Start
+
+### Example: Discrete
+
+Let's first start with a discrete probabilistic program. Imagine you have two coins `a` and `b` with probability of landing on heads as 0.4 and 0.6 respectively. You flip both the coins and see that one of them has landed heads. What is the probability that `a` lands heads?
+
+```julia
+using Dice
+code = @dice begin
+    a = flip(0.4)
+    b = flip(0.6)
+    observe(a | b)
+    return a
+end
+@show pr(code)
+```
+
+We have this example written up in the file `examples/example1.jl`. It can be run as follows:
+
+```bash
+julia --project examples/example1.jl
+```
+
+And it should print the result as following showing that `a` is true with probability `0.526316`:
 
+```bash
+DataStructures.DefaultOrderedDict{Any, Any, Float64} with 2 entries:
+  true  => 0.526316
+  false => 0.473684
 ```
-] up
+
+### Example: Discrete-Continuous
+
+To see the use of HyBit to write discrete-continuous probabilistic programs, consider the following example. Here, we compute the probability of a random variable `a` being less than 0.
+
+```julia
+using Dice, Distributions
+DFiP = DistFix{6, 2}
+code = @dice begin
+            a = bitblast(DFiP, Normal(0, 1), 4, -8.0, 8.0)
+            b = a < DFiP(0.0)
+            b
+end
+pr(code)
 ```
 
-Press CTRL-C or backspace to exit from the pkg terminal and return to Julia REPL.
+We have this example written up in the file `examples/example2.jl`. It can be run as follows:
+
+```bash
+julia --project examples/example2.jl
+```
+
+And it should print the result as following:
+
+```bash
+DataStructures.DefaultOrderedDict{Any, Any, Float64} with 2 entries:
+  true  => 0.5
+  false => 0.5
+```
+
+The Julia package Dice makes available the following constructs
+
+* `@dice` macro that encapsulates the probabilistic program
+* `observe()` to condition on a Boolean random variable being true.
+* `DistFix{W, F}` as types to represent fixed point numbers with `W` bits, `F` bits being after the binary point. If the floating point numbers passed as an argument to `DistFix{W, F}` are outside the range $$[-2^{W - F - 1}, 2^{W - F - 1} - 2^{-F}]$$, one would encounter an error.
+* `bitblast` to bitblast continuous density functions using linear pieces with the following signature.
 
-One can now run a program from the Julia REPL:
 ```julia
-include("examples/graph_reachability.jl")
+function bitblast(::Type{DistFix{W,F}}, dist::ContinuousUnivariateDistribution, 
+                  numpieces::Int, start::Float64, stop::Float64) where {W,F}
 ```
 
-Or from the command line:
+* 'general_gamma' to bitblast general gamma densities $$x^{\alpha}e^{\beta x}$$ soundly with the following signature
+
+```julia
+function general_gamma(::Type{DistFix{W, F}}, alpha::Int, beta::Float64, ll::Float64, ul::Float64) where {W, F}
 ```
-julia --project examples/graph_reachability.jl
-```
+
+It also offers different probabilistic inference queries such as the following:
+
+* `pr(code)` that computes the probability distribution of the returned types of `code`.
+* `expectation(code)` computes the mean of the value returned by `code`
+* `variance(code)` computes the variance of the value returned by `code`.
+
+## More Examples
+
+More examples can be found at the following directories:
+
+* `test/` directory contains unit test cases for all the functions and data types implemented.
+* `examples/` contains simple examples to get started with using Dice Julia package to write probabilistic programs.
+* `benchmarks/` contains discrete-continuous probabilistic programs to get started with using bit blasting.