docs: document changeset generator algorithm and parameters in bench/gen.go

bench/README.md

@@ -0,0 +1,17 @@
+## Generation algorithm
+
+The changeset generator in this module is parameterized by the parameters in the `ChangesetGenerator` struct.
+Refer to the struct documentation for details on each parameter.
+
+For each version:
+
+1. calculate number of create, update, and deletion operations based on `ChangePerVersion`, `DeleteFraction`,
+   `InitialSize`, `FinalSize` and `Versions`. Essentially we want to do `ChangePerVersion` operations per version with
+   `DeleteFraction` of them being deletions and the remainder being updates. We also want to make sure there are enough create operations to progress linearly in size from
+   `InitialSize` to `FinalSize` over the course of the number of specified `Versions`.
+2. populate an empty list of the desired number of create, update, and delete operations in random order
+3. for delete operations, select a random existing key from the current set of keys in the tree
+4. for create operations, generate new keys and values randomly where the length of the key and value are generated to approximate a normal distribution conforming to `KeyMean`, `KeyStdDev`, `ValueMean`, and `ValueStdDev`
+5. for update operations, select a random existing key and generate a new value using `ValueMean` and `ValueStdDev`
+
+Note: Version 1 is special and only contains create operations to establish the initial set of keys.

bench/gen.go

@@ -5,8 +5,9 @@ import (
 	"math/rand"
 	"time"
 
-	"github.com/cosmos/iavl-bench/bench/metrics"
 	api "github.com/kocubinski/costor-api"
+
+	"github.com/cosmos/iavl-bench/bench/metrics"
 )
 
 type ChangesetIterator interface {
@@ -16,18 +17,35 @@ type ChangesetIterator interface {
 	Version() int64
 }
 
+// ChangesetGenerator are the parameters for generating a changeset iterator.
 type ChangesetGenerator struct {
-	StoreKey         string
-	Seed             int64
-	KeyMean          int
-	KeyStdDev        int
-	ValueMean        int
-	ValueStdDev      int
-	InitialSize      int
-	FinalSize        int
-	Versions         int64
+	// StoreKey is the store key to use for all nodes generated by this generator.
+	StoreKey string
+	// Seed is the seed for the random number generator.
+	Seed int64
+	// KeyMean is the average key length in bytes that the generator should aim to produce.
+	KeyMean int
+	// KeyStdDev is the standard deviation of the key length in bytes that the generator should aim to produce.
+	KeyStdDev int
+	// ValueMean is the average value length in bytes that the generator should aim to produce.
+	ValueMean int
+	// ValueStdDev is the standard deviation of the value length in bytes that the generator should aim to produce.
+	ValueStdDev int
+	// InitialSize is the number of keys at version 1.
+	InitialSize int
+	// FinalSize is the number of keys at the final version.
+	// FinalSize must be >= InitialSize, it is used together with
+	// ChangePerVersion and Versions to determine the number of create operations
+	// per version.
+	FinalSize int
+	// Versions are the number of versions to generate data for as well as the
+	// number of versions to get from InitialSize to FinalSize.
+	// The iterator will stop generating data after this many versions.
+	Versions int64
+	// ChangePerVersion is the number of creates + updates + deletes per version.
 	ChangePerVersion int
-	DeleteFraction   float64
+	// DeleteFraction is the fraction of ChangePerVersion that are deletes.
+	DeleteFraction float64
 }
 
 const byteChunkSize = 512
@@ -184,6 +202,10 @@ func (o *changesetOp) genNode(itr *ChangesetItr) *api.Node {
 func (itr *ChangesetItr) nextVersionV2() (*generatingNodeItr, error) {
 	itr.version++
 
+	// figure out the number of creates, updates, and deletes for this version
+	// deletes are a fraction of ChangePerVersion
+	// creates are determined by the growth from InitialSize to FinalSize over Versions
+	// but adjusted to account for deletes so that we end up at FinalSize at the end
 	deletes := int(itr.gen.DeleteFraction * float64(itr.gen.ChangePerVersion))
 	updates := itr.gen.ChangePerVersion - deletes
 	var creates int