From 4de72e27ddd717daeee12f7e51614954f5f633bb Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Thu, 8 Dec 2016 19:14:24 -0600
Subject: [PATCH 1/8] Add zipf benchmark with efficient random ID permutations

---
 bench/permutations.go        |  66 +++++++++++++++++++
 bench/zipf.go                | 122 +++++++++++++++++++++++++++++++++++
 cmd/pilosactl/main.go        |   3 +
 cmd/pilosactl/zipfspawn.json |  10 +++
 4 files changed, 201 insertions(+)
 create mode 100644 bench/permutations.go
 create mode 100644 bench/zipf.go
 create mode 100644 cmd/pilosactl/zipfspawn.json

diff --git a/bench/permutations.go b/bench/permutations.go
new file mode 100644
index 000000000..4f4a78961
--- /dev/null
+++ b/bench/permutations.go
@@ -0,0 +1,66 @@
+package bench
+
+// A PermutationGenerator provides a way to pass integer IDs through a permutation
+// map that is pseudorandom but repeatable. This could be done with rand.Perm,
+// but that would require storing a [Iterations]int64 array, which we want to avoid
+// for large values of Iterations.
+// It works by using a Linear Congruence Generator (https://en.wikipedia.org/wiki/Linear_congruential_generator)
+// with modulus = Iterations,
+// c = an arbitrary prime,
+// a = computed to ensure the full period.
+
+// relevant stackoverflow: http://cs.stackexchange.com/questions/29822/lazily-computing-a-random-permutation-of-the-positive-integers
+
+type PermutationGenerator struct {
+	a int64
+	c int64
+	m int64
+}
+
+func NewPermutationGenerator(m int64, seed int64) *PermutationGenerator {
+	// figure out 'a' and 'c', return PermutationGenerator
+	a := LCGmultiplierFromModulus(m, seed)
+	c := int64(22695479)
+	return &PermutationGenerator{a, c, m}
+}
+
+func (p *PermutationGenerator) Next(n int64) int64 {
+	// run one step of the LCG
+	return (n*p.a + p.c) % p.m
+}
+
+func LCGmultiplierFromModulus(m int64, seed int64) int64 {
+	// LCG parameters must satisfy three conditions:
+	// 1. m and c are relatively prime (satisfied for prime c != m)
+	// 2. a-1 is divisible by all prime factors of m
+	// 3. a-1 is divisible by 4 if m is divisible by 4
+	// Additionally, a seed can be used to select between different permutations
+	factors := primeFactors(m)
+	product := int64(1)
+	for p := range factors {
+		// satisfy condition 2
+		product *= p
+	}
+
+	if m%4 == 0 {
+		// satisfy condition 3
+		product *= 2
+	}
+
+	return product*seed + 1
+}
+
+func primeFactors(n int64) map[int64]int {
+	// Returns map of {integerFactor: count, ...}
+	// This is a naive algorithm that will not work well for large prime n.
+	factors := make(map[int64]int)
+	for i := int64(2); i <= n; i++ {
+		div, mod := n/i, n%i
+		for mod == 0 {
+			factors[i] += 1
+			n = div
+			div, mod = n/i, n%i
+		}
+	}
+	return factors
+}
diff --git a/bench/zipf.go b/bench/zipf.go
new file mode 100644
index 000000000..0a45fcf8a
--- /dev/null
+++ b/bench/zipf.go
@@ -0,0 +1,122 @@
+package bench
+
+import (
+	"fmt"
+
+	"flag"
+	"io/ioutil"
+
+	"context"
+	"math/rand"
+	"time"
+)
+
+// ZipfSetBits sets bits randomly and deterministically based on a seed, according to the Zipf distribution
+type ZipfSetBits struct {
+	HasClient
+	BaseBitmapID    int64
+	BaseProfileID   int64
+	BitmapIDRange   int64
+	ProfileIDRange  int64
+	Iterations      int // number of bits that will be set
+	Seed            int64
+	BitmapExponent  float64
+	BitmapOffset    float64
+	ProfileExponent float64
+	ProfileOffset   float64
+	DB              string // DB to use in pilosa.
+
+}
+
+func (b *ZipfSetBits) Usage() string {
+	return `
+zipf-set-bits sets random bits according to Zipf distribution
+
+Usage: zipf-set-bits [arguments]
+
+The following arguments are available:
+
+	-base-bitmap-id int
+		bits being set will all be greater than BaseBitmapID
+
+	-bitmap-id-range int
+		number of possible bitmap ids that can be set
+
+	-base-profile-id int
+		profile id num to start from
+
+	-profile-id-range int
+		number of possible profile ids that can be set
+
+	-iterations int
+		number of bits to set
+
+	-seed int
+		Seed for RNG
+
+	-db string
+		pilosa db to use
+
+	BitmapExponent  float64
+	BitmapOffset    float64
+	ProfileExponent float64
+	ProfileOffset   float64
+
+	-client-type string
+		Can be 'single' (all agents hitting one host) or 'round_robin'
+`[1:]
+}
+
+func (b *ZipfSetBits) ConsumeFlags(args []string) ([]string, error) {
+	fs := flag.NewFlagSet("ZipfSetBits", flag.ContinueOnError)
+	fs.SetOutput(ioutil.Discard)
+	fs.Int64Var(&b.BaseBitmapID, "base-bitmap-id", 0, "")
+	fs.Int64Var(&b.BitmapIDRange, "bitmap-id-range", 100000, "")
+	fs.Int64Var(&b.BaseProfileID, "base-profile-id", 0, "")
+	fs.Int64Var(&b.ProfileIDRange, "profile-id-range", 100000, "")
+	fs.Int64Var(&b.Seed, "seed", 1, "")
+	fs.IntVar(&b.Iterations, "iterations", 100, "")
+	fs.StringVar(&b.DB, "db", "benchdb", "")
+	fs.Float64Var(&b.BitmapExponent, "bitmap-exponent", 1.01, "")
+	fs.Float64Var(&b.BitmapOffset, "bitmap-offset", 1, "")
+	fs.Float64Var(&b.ProfileExponent, "profile-exponent", 1.01, "")
+	fs.Float64Var(&b.ProfileOffset, "profile-offset", 1, "")
+	fs.StringVar(&b.ClientType, "client-type", "single", "")
+
+	if err := fs.Parse(args); err != nil {
+		return nil, err
+	}
+	return fs.Args(), nil
+}
+
+// Run runs the ZipfSetBits benchmark
+func (b *ZipfSetBits) Run(ctx context.Context, agentNum int) map[string]interface{} {
+	rnd := rand.New(rand.NewSource(b.Seed + int64(agentNum)))
+	bitmapRng := rand.NewZipf(rnd, b.BitmapExponent, b.BitmapOffset, uint64(b.BitmapIDRange))
+	profileRng := rand.NewZipf(rnd, b.ProfileExponent, b.ProfileOffset, uint64(b.ProfileIDRange))
+	bitmapPerm := NewPermutationGenerator(b.BitmapIDRange, b.Seed)
+	profilePerm := NewPermutationGenerator(b.ProfileIDRange, b.Seed)
+
+	results := make(map[string]interface{})
+	if b.cli == nil {
+		results["error"] = fmt.Errorf("No client set for ZipfSetBits agent: %v", agentNum)
+		return results
+	}
+	s := NewStats()
+	var start time.Time
+	for n := 0; n < b.Iterations; n++ {
+		// generate IDs from Zipf distribution
+		bitmapIDOriginal := bitmapRng.Uint64()
+		profIDOriginal := profileRng.Uint64()
+		// permute IDs randomly, but repeatably
+		bitmapID := bitmapPerm.Next(int64(bitmapIDOriginal))
+		profID := profilePerm.Next(int64(profIDOriginal))
+
+		query := fmt.Sprintf("SetBit(%d, 'frame.n', %d)", b.BaseBitmapID+int64(bitmapID), b.BaseProfileID+int64(profID))
+		start = time.Now()
+		b.cli.ExecuteQuery(ctx, b.DB, query, true)
+		s.Add(time.Now().Sub(start))
+	}
+	AddToResults(s, results)
+	return results
+}
diff --git a/cmd/pilosactl/main.go b/cmd/pilosactl/main.go
index 6408794df..41bcec7fd 100644
--- a/cmd/pilosactl/main.go
+++ b/cmd/pilosactl/main.go
@@ -1162,6 +1162,8 @@ func (cmd *BagentCommand) ParseFlags(args []string) error {
 			bm = &bench.DiagonalSetBits{}
 		case "random-set-bits":
 			bm = &bench.RandomSetBits{}
+		case "zipf-set-bits":
+			bm = &bench.ZipfSetBits{}
 		case "multi-db-set-bits":
 			bm = &bench.MultiDBSetBits{}
 		case "random-query":
@@ -1208,6 +1210,7 @@ The following arguments are available:
 	subcommands:
 		diagonal-set-bits
 		random-set-bits
+    zipf-set-bits
 		multi-db-set-bits
 		random-query
 		import
diff --git a/cmd/pilosactl/zipfspawn.json b/cmd/pilosactl/zipfspawn.json
new file mode 100644
index 000000000..2d9320357
--- /dev/null
+++ b/cmd/pilosactl/zipfspawn.json
@@ -0,0 +1,10 @@
+{
+    "CreatorArgs": ["-type", "local", "-serverN", "3", "-replicaN", "1"],
+    "Agents": { "Type": "local" },
+    "Benchmarks": [
+        {
+            "Num": 3,
+            "Args": ["zipf-set-bits", "-iterations", "30000", "-profile-id-range", "1000000", "-bitmap-id-range", "1000000", "-seed", "2345", "-client-type", "round_robin", "-bitmap-exponent", "1.5", "-profile-exponent", "1.5"]
+        }
+    ]
+}

From 30436bd5730ece6f2fa458d54b9addf546755f1a Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Thu, 8 Dec 2016 19:18:34 -0600
Subject: [PATCH 2/8] Update usage message

---
 bench/zipf.go | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/bench/zipf.go b/bench/zipf.go
index 0a45fcf8a..d8db2ffbe 100644
--- a/bench/zipf.go
+++ b/bench/zipf.go
@@ -57,10 +57,17 @@ The following arguments are available:
 	-db string
 		pilosa db to use
 
-	BitmapExponent  float64
-	BitmapOffset    float64
-	ProfileExponent float64
-	ProfileOffset   float64
+  -bitmap-exponent float64
+    zipf exponent parameter for bitmap IDs
+
+  -bitmap-offset float64
+    zipf offset parameter for bitmap IDs
+
+  -profile-exponent float64
+    zipf exponent parameter for profile IDs
+
+  -profile-offset float64
+    zipf offset parameter for profile IDs
 
 	-client-type string
 		Can be 'single' (all agents hitting one host) or 'round_robin'

From bc4c32e02795f0559dcd504c17948cc1da55890c Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Mon, 12 Dec 2016 15:53:31 -0600
Subject: [PATCH 3/8] Put tabs in usage string

---
 bench/zipf.go | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/bench/zipf.go b/bench/zipf.go
index d8db2ffbe..9ac87dd9b 100644
--- a/bench/zipf.go
+++ b/bench/zipf.go
@@ -57,17 +57,17 @@ The following arguments are available:
 	-db string
 		pilosa db to use
 
-  -bitmap-exponent float64
-    zipf exponent parameter for bitmap IDs
+	-bitmap-exponent float64
+		zipf exponent parameter for bitmap IDs
 
-  -bitmap-offset float64
-    zipf offset parameter for bitmap IDs
+	-bitmap-ratio float64
+		zipf probability ratio parameter for bitmap IDs
 
-  -profile-exponent float64
-    zipf exponent parameter for profile IDs
+	-profile-exponent float64
+		zipf exponent parameter for profile IDs
 
-  -profile-offset float64
-    zipf offset parameter for profile IDs
+	-profile-ratio float64
+		zipf probability ratio parameter for profile IDs
 
 	-client-type string
 		Can be 'single' (all agents hitting one host) or 'round_robin'

From 741ee7c8672721ab685095d47973227b372062ce Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Mon, 12 Dec 2016 15:55:32 -0600
Subject: [PATCH 4/8] Move stuff to Init

---
 bench/zipf.go | 72 +++++++++++++++++++++++++++++++++++----------------
 1 file changed, 49 insertions(+), 23 deletions(-)

diff --git a/bench/zipf.go b/bench/zipf.go
index 9ac87dd9b..dce592a05 100644
--- a/bench/zipf.go
+++ b/bench/zipf.go
@@ -7,6 +7,7 @@ import (
 	"io/ioutil"
 
 	"context"
+	"math"
 	"math/rand"
 	"time"
 )
@@ -14,18 +15,23 @@ import (
 // ZipfSetBits sets bits randomly and deterministically based on a seed, according to the Zipf distribution
 type ZipfSetBits struct {
 	HasClient
-	BaseBitmapID    int64
-	BaseProfileID   int64
-	BitmapIDRange   int64
-	ProfileIDRange  int64
-	Iterations      int // number of bits that will be set
-	Seed            int64
-	BitmapExponent  float64
-	BitmapOffset    float64
-	ProfileExponent float64
-	ProfileOffset   float64
-	DB              string // DB to use in pilosa.
+	BaseBitmapID   int64
+	BaseProfileID  int64
+	BitmapIDRange  int64
+	ProfileIDRange int64
+	Iterations     int // number of bits that will be set
+	Seed           int64
+	BitmapRng      *rand.Zipf
+	ProfileRng     *rand.Zipf
+	BitmapPerm     *PermutationGenerator
+	ProfilePerm    *PermutationGenerator
+	DB             string // DB to use in pilosa.
 
+	// TODO remove these - but theyre needed in ConsumeFlags
+	BitmapExponent  float64
+	BitmapRatio     float64
+	ProfileExponent float64
+	ProfileRatio    float64
 }
 
 func (b *ZipfSetBits) Usage() string {
@@ -85,9 +91,9 @@ func (b *ZipfSetBits) ConsumeFlags(args []string) ([]string, error) {
 	fs.IntVar(&b.Iterations, "iterations", 100, "")
 	fs.StringVar(&b.DB, "db", "benchdb", "")
 	fs.Float64Var(&b.BitmapExponent, "bitmap-exponent", 1.01, "")
-	fs.Float64Var(&b.BitmapOffset, "bitmap-offset", 1, "")
+	fs.Float64Var(&b.BitmapRatio, "bitmap-ratio", 0.25, "")
 	fs.Float64Var(&b.ProfileExponent, "profile-exponent", 1.01, "")
-	fs.Float64Var(&b.ProfileOffset, "profile-offset", 1, "")
+	fs.Float64Var(&b.ProfileRatio, "profile-ratio", 0.25, "")
 	fs.StringVar(&b.ClientType, "client-type", "single", "")
 
 	if err := fs.Parse(args); err != nil {
@@ -96,14 +102,34 @@ func (b *ZipfSetBits) ConsumeFlags(args []string) ([]string, error) {
 	return fs.Args(), nil
 }
 
+func getZipfOffset(N int64, exp, ratio float64) float64 {
+	// Offset is the true parameter used by the Zipf distribution, but the ratio,
+	// as defined here, is a simpler, readable way to define the distribution.
+	// Offset is in [1, inf), and its meaning depends on N (a pain for updating benchmark configs)
+	// ratio is in (0, 1), and its meaning does not depend on N.
+	// it is the ratio of the lowest probability in the distribution to the highest.
+	// ratio=0.01 corresponds to a very small offset - the most skewed distribution for a given pair (N, exp)
+	// ratio=0.99 corresponds to a very large offset - the most nearly uniform distribution for a given (N, exp)
+
+	z := math.Pow(ratio, 1/exp)
+	return z * float64(N-1) / (1 - z)
+}
+
+func (b *ZipfSetBits) Init(hosts []string, agentNum int) error {
+	rnd := rand.New(rand.NewSource(b.Seed + int64(agentNum)))
+	bitmapOffset := getZipfOffset(b.BitmapIDRange, b.BitmapExponent, b.BitmapRatio)
+	b.BitmapRng = rand.NewZipf(rnd, b.BitmapExponent, bitmapOffset, uint64(b.BitmapIDRange-1))
+	profileOffset := getZipfOffset(b.ProfileIDRange, b.ProfileExponent, b.ProfileRatio)
+	b.ProfileRng = rand.NewZipf(rnd, b.ProfileExponent, profileOffset, uint64(b.ProfileIDRange-1))
+
+	b.BitmapPerm = NewPermutationGenerator(b.BitmapIDRange, b.Seed)
+	b.ProfilePerm = NewPermutationGenerator(b.ProfileIDRange, b.Seed+1)
+
+	return b.HasClient.Init(hosts, agentNum)
+}
+
 // Run runs the ZipfSetBits benchmark
 func (b *ZipfSetBits) Run(ctx context.Context, agentNum int) map[string]interface{} {
-	rnd := rand.New(rand.NewSource(b.Seed + int64(agentNum)))
-	bitmapRng := rand.NewZipf(rnd, b.BitmapExponent, b.BitmapOffset, uint64(b.BitmapIDRange))
-	profileRng := rand.NewZipf(rnd, b.ProfileExponent, b.ProfileOffset, uint64(b.ProfileIDRange))
-	bitmapPerm := NewPermutationGenerator(b.BitmapIDRange, b.Seed)
-	profilePerm := NewPermutationGenerator(b.ProfileIDRange, b.Seed)
-
 	results := make(map[string]interface{})
 	if b.cli == nil {
 		results["error"] = fmt.Errorf("No client set for ZipfSetBits agent: %v", agentNum)
@@ -113,11 +139,11 @@ func (b *ZipfSetBits) Run(ctx context.Context, agentNum int) map[string]interfac
 	var start time.Time
 	for n := 0; n < b.Iterations; n++ {
 		// generate IDs from Zipf distribution
-		bitmapIDOriginal := bitmapRng.Uint64()
-		profIDOriginal := profileRng.Uint64()
+		bitmapIDOriginal := b.BitmapRng.Uint64()
+		profIDOriginal := b.ProfileRng.Uint64()
 		// permute IDs randomly, but repeatably
-		bitmapID := bitmapPerm.Next(int64(bitmapIDOriginal))
-		profID := profilePerm.Next(int64(profIDOriginal))
+		bitmapID := b.BitmapPerm.Next(int64(bitmapIDOriginal))
+		profID := b.ProfilePerm.Next(int64(profIDOriginal))
 
 		query := fmt.Sprintf("SetBit(%d, 'frame.n', %d)", b.BaseBitmapID+int64(bitmapID), b.BaseProfileID+int64(profID))
 		start = time.Now()

From cbd7b2ff370613702726027412b91117ea82961a Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Mon, 12 Dec 2016 15:55:52 -0600
Subject: [PATCH 5/8] Add comments

---
 bench/zipf.go | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/bench/zipf.go b/bench/zipf.go
index dce592a05..d1dfc4628 100644
--- a/bench/zipf.go
+++ b/bench/zipf.go
@@ -12,7 +12,12 @@ import (
 	"time"
 )
 
-// ZipfSetBits sets bits randomly and deterministically based on a seed, according to the Zipf distribution
+// ZipfSetBits sets random bits according to the Zipf-Mandelbrot distribution.
+// This distribution accepts two parameters for both bitmaps and profiles:
+// Exponent in (1, inf), default 1.001 - "sharpness" of the distribution.
+// Ratio in (0, 1), default 0.25 - maximum variation of the distribution (the relative probability of the least likely ID to the most likely ID)
+//
+// It also uses PermutationGenerator to permute IDs randomly.
 type ZipfSetBits struct {
 	HasClient
 	BaseBitmapID   int64

From 587d4259a1b2978b24a5a3069ca6db28eafd9907 Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Mon, 12 Dec 2016 16:11:23 -0600
Subject: [PATCH 6/8] Add good defaults for zipf config

---
 cmd/pilosactl/zipfspawn.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/cmd/pilosactl/zipfspawn.json b/cmd/pilosactl/zipfspawn.json
index 2d9320357..6dda5a283 100644
--- a/cmd/pilosactl/zipfspawn.json
+++ b/cmd/pilosactl/zipfspawn.json
@@ -3,8 +3,8 @@
     "Agents": { "Type": "local" },
     "Benchmarks": [
         {
-            "Num": 3,
-            "Args": ["zipf-set-bits", "-iterations", "30000", "-profile-id-range", "1000000", "-bitmap-id-range", "1000000", "-seed", "2345", "-client-type", "round_robin", "-bitmap-exponent", "1.5", "-profile-exponent", "1.5"]
+            "Num": 1,
+            "Args": ["zipf-set-bits", "-iterations", "10000", "-profile-id-range", "100", "-bitmap-id-range", "100", "-seed", "2345", "-client-type", "round_robin", "-bitmap-exponent", "1.001", "-bitmap-ratio", ".9", "-profile-exponent", "1.001", "-profile-ratio", ".3"]
         }
     ]
 }

From 2968c15a379558bbf1a9b8aa7057b774e071b679 Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Tue, 13 Dec 2016 13:25:31 -0600
Subject: [PATCH 7/8] Improve comment formatting and update usage

---
 bench/permutations.go | 16 +++++++---------
 bench/zipf.go         | 12 +++++++-----
 cmd/pilosactl/main.go |  2 +-
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/bench/permutations.go b/bench/permutations.go
index 4f4a78961..9c1ba8b6a 100644
--- a/bench/permutations.go
+++ b/bench/permutations.go
@@ -1,16 +1,14 @@
 package bench
 
-// A PermutationGenerator provides a way to pass integer IDs through a permutation
+// PermutationGenerator provides a way to pass integer IDs through a permutation
 // map that is pseudorandom but repeatable. This could be done with rand.Perm,
 // but that would require storing a [Iterations]int64 array, which we want to avoid
 // for large values of Iterations.
 // It works by using a Linear Congruence Generator (https://en.wikipedia.org/wiki/Linear_congruential_generator)
-// with modulus = Iterations,
+// with modulus m = Iterations,
 // c = an arbitrary prime,
 // a = computed to ensure the full period.
-
 // relevant stackoverflow: http://cs.stackexchange.com/questions/29822/lazily-computing-a-random-permutation-of-the-positive-integers
-
 type PermutationGenerator struct {
 	a int64
 	c int64
@@ -29,12 +27,12 @@ func (p *PermutationGenerator) Next(n int64) int64 {
 	return (n*p.a + p.c) % p.m
 }
 
+// LCG parameters must satisfy three conditions:
+// 1. m and c are relatively prime (satisfied for prime c != m)
+// 2. a-1 is divisible by all prime factors of m
+// 3. a-1 is divisible by 4 if m is divisible by 4
+// Additionally, a seed can be used to select between different permutations
 func LCGmultiplierFromModulus(m int64, seed int64) int64 {
-	// LCG parameters must satisfy three conditions:
-	// 1. m and c are relatively prime (satisfied for prime c != m)
-	// 2. a-1 is divisible by all prime factors of m
-	// 3. a-1 is divisible by 4 if m is divisible by 4
-	// Additionally, a seed can be used to select between different permutations
 	factors := primeFactors(m)
 	product := int64(1)
 	for p := range factors {
diff --git a/bench/zipf.go b/bench/zipf.go
index d1dfc4628..23eac3a1c 100644
--- a/bench/zipf.go
+++ b/bench/zipf.go
@@ -13,10 +13,7 @@ import (
 )
 
 // ZipfSetBits sets random bits according to the Zipf-Mandelbrot distribution.
-// This distribution accepts two parameters for both bitmaps and profiles:
-// Exponent in (1, inf), default 1.001 - "sharpness" of the distribution.
-// Ratio in (0, 1), default 0.25 - maximum variation of the distribution (the relative probability of the least likely ID to the most likely ID)
-//
+// This distribution accepts two parameters, Exponent and Ratio, for both bitmaps and profiles.
 // It also uses PermutationGenerator to permute IDs randomly.
 type ZipfSetBits struct {
 	HasClient
@@ -41,7 +38,12 @@ type ZipfSetBits struct {
 
 func (b *ZipfSetBits) Usage() string {
 	return `
-zipf-set-bits sets random bits according to Zipf distribution
+zipf-set-bits sets random bits according to the Zipf distribution.
+This is a power-law distribution controlled by two parameters.
+Exponent, in the range (1, inf), with a default value of 1.001, controls
+the "sharpness" of the distribution, with higher exponent being sharper.
+Ratio, in the range (0, 1), with a default value of 0.25, controls the
+maximum variation of the distribution, with higher ratio being more uniform.
 
 Usage: zipf-set-bits [arguments]
 
diff --git a/cmd/pilosactl/main.go b/cmd/pilosactl/main.go
index 41bcec7fd..26e15fa5f 100644
--- a/cmd/pilosactl/main.go
+++ b/cmd/pilosactl/main.go
@@ -1210,7 +1210,7 @@ The following arguments are available:
 	subcommands:
 		diagonal-set-bits
 		random-set-bits
-    zipf-set-bits
+		zipf-set-bits
 		multi-db-set-bits
 		random-query
 		import

From 9ae006908a7e1718026d885389655076a33bfb8c Mon Sep 17 00:00:00 2001
From: Alan Bernstein <alan@pilosa.com>
Date: Mon, 19 Dec 2016 13:56:06 -0600
Subject: [PATCH 8/8] Improve comment formatting

---
 bench/permutations.go |  4 ++--
 bench/zipf.go         | 15 +++++++--------
 2 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/bench/permutations.go b/bench/permutations.go
index 9c1ba8b6a..cbe4162e4 100644
--- a/bench/permutations.go
+++ b/bench/permutations.go
@@ -48,9 +48,9 @@ func LCGmultiplierFromModulus(m int64, seed int64) int64 {
 	return product*seed + 1
 }
 
+// Returns map of {integerFactor: count, ...}
+// This is a naive algorithm that will not work well for large prime n.
 func primeFactors(n int64) map[int64]int {
-	// Returns map of {integerFactor: count, ...}
-	// This is a naive algorithm that will not work well for large prime n.
 	factors := make(map[int64]int)
 	for i := int64(2); i <= n; i++ {
 		div, mod := n/i, n%i
diff --git a/bench/zipf.go b/bench/zipf.go
index 23eac3a1c..b3f443706 100644
--- a/bench/zipf.go
+++ b/bench/zipf.go
@@ -109,15 +109,14 @@ func (b *ZipfSetBits) ConsumeFlags(args []string) ([]string, error) {
 	return fs.Args(), nil
 }
 
+// Offset is the true parameter used by the Zipf distribution, but the ratio,
+// as defined here, is a simpler, readable way to define the distribution.
+// Offset is in [1, inf), and its meaning depends on N (a pain for updating benchmark configs)
+// ratio is in (0, 1), and its meaning does not depend on N.
+// it is the ratio of the lowest probability in the distribution to the highest.
+// ratio=0.01 corresponds to a very small offset - the most skewed distribution for a given pair (N, exp)
+// ratio=0.99 corresponds to a very large offset - the most nearly uniform distribution for a given (N, exp)
 func getZipfOffset(N int64, exp, ratio float64) float64 {
-	// Offset is the true parameter used by the Zipf distribution, but the ratio,
-	// as defined here, is a simpler, readable way to define the distribution.
-	// Offset is in [1, inf), and its meaning depends on N (a pain for updating benchmark configs)
-	// ratio is in (0, 1), and its meaning does not depend on N.
-	// it is the ratio of the lowest probability in the distribution to the highest.
-	// ratio=0.01 corresponds to a very small offset - the most skewed distribution for a given pair (N, exp)
-	// ratio=0.99 corresponds to a very large offset - the most nearly uniform distribution for a given (N, exp)
-
 	z := math.Pow(ratio, 1/exp)
 	return z * float64(N-1) / (1 - z)
 }