patterns

README

Patterns

This package contains functions that generate n-dimensional patterns (in tensors) based on various algorithms, typically for use as inputs to neural network models or other such learning systems. It also has some routines for helping manage collections of such patterns.

In general the tensorfs system is used to manage a "vocabulary" of such patterns. The tensor.RowMajor API is used to organize a list (rows) of patterns.

Permuted Binary and FlipBits

The PermutedBinary* functions create binary patterns with a specific number of "on" vs. "off" bits, which can be useful for enforcing a target level of activity.

The FlipBits* functions preserve any existing activity levels while randomly flipping a specific number of bits on or off.

Mixing patterns

The Mix function acts a bit like a multi-track mixer, combining different streams of patterns together in a higher-dimensional composite pattern.

Managing rows

Some misc functions help managing rows of data:

• SplitRows: split out subsets of a larger list.
• ReplicateRows: replicate multiple copies of a given row.
• Shuffle: permuted order of rows.

Random seed

A separate random number source can be established, using the randx package.

Usage examples

Permuted Binary

	a := dir.Float32("A", 6, 3, 3) // 6 rows of 3x3 patterns
	nOn := patterns.NFromPct(0.3, 9) // 30% activity
	nDiff := patterns.NFromPct(0.4, nOn) // 40% max overlap
	patterns.PermutedBinaryMinDiff(a, nOn, 1, 0, nDiff) // ensures minimum distance

Replicate, assemble, and split rows

	ctx1 := dir.Float32("ctxt1")
	patterns.ReplicateRows(ctx1, a.SubSpace(0), 6) // 6x first row of 'a' above
	ab := dir.Float32("ab", 0, 3, 3)
	ab.AppendFrom(a) // add a patterns
	ab.AppendFrom(b) // add b patterns

	// split 12 items into 3 sets of 4
	patterns.SplitRows(dir, ab, []string{"as", "bs", "cs"}, 3, 3) 

Mix patterns

	mix := dir.Float32("mix")
	patterns.Mix(mix, 12, a, b, ctx1, ctx1, empty, b) // make 12 rows from given sources
	mix.SetShapeSizes(12, 3, 2, 3, 3) // reshape to 3x2 = "outer" dims x 3x3 inner

Documentation

Overview

Package patterns contains functions that generate patterns, typically based on various constrained-forms of random patterns.

Index

• Variables
• func FlipBits(tsr tensor.Values, nOff, nOn int, onVal, offVal float64)
• func FlipBitsRows(tsr tensor.Values, nOff, nOn int, onVal, offVal float64)
• func Mix(dest tensor.Values, rows int, srcs ...tensor.Values) error
• func NFromPct(pct float64, n int) int
• func NOnInTensor(trow tensor.Values) int
• func NameRows(tsr tensor.Values, prefix string, nzeros int)
• func NewRand(seed int64)
• func PctActInTensor(trow tensor.Values) float32
• func PermutedBinary(tsr tensor.Values, nOn int, onVal, offVal float64)
• func PermutedBinaryMinDiff(tsr tensor.Values, nOn int, onVal, offVal float64, minDiff int) error
• func PermutedBinaryRows(tsr tensor.Values, nOn int, onVal, offVal float64)
• func ReplicateRows(dest, src tensor.Values, nCopies int)
• func RestoreSeed()
• func SetRandSeed(seed int64)
• func Shuffle(src tensor.Values) *tensor.Rows
• func SplitRows(dir *tensorfs.Node, src tensor.Values, names []string, rows ...int) error

Variables

var (
	// RandSource is a random source to use for all random numbers used in patterns.
	// By default it just uses the standard Go math/rand source.
	// If initialized, e.g., by calling NewRand(seed), then a separate stream of
	// random numbers will be generated for all calls, and the seed is saved as
	// RandSeed. It can be reinstated by calling RestoreSeed.
	// Can also set RandSource to another existing randx.Rand source to use it.
	RandSource = &randx.SysRand{}

	// Random seed last set by NewRand or SetRandSeed.
	RandSeed int64
)

var MinDiffPrintIterations = false

MinDiffPrintIterations set this to true to see the iteration stats for PermutedBinaryMinDiff -- for large, long-running cases.

Functions

func FlipBits

func FlipBits(tsr tensor.Values, nOff, nOn int, onVal, offVal float64)

FlipBits turns nOff bits that are currently On to Off and nOn bits that are currently Off to On, using permuted lists.

func FlipBitsRows

func FlipBitsRows(tsr tensor.Values, nOff, nOn int, onVal, offVal float64)

FlipBitsRows turns nOff bits that are currently On to Off and nOn bits that are currently Off to On, using permuted lists. Iterates over the outer-most tensor dimension as rows.

func Mix

func Mix(dest tensor.Values, rows int, srcs ...tensor.Values) error

Mix mixes patterns from different tensors into a combined set of patterns, over the outermost row dimension (i.e., each source is a list of patterns over rows). The source tensors must have the same cell size, and the existing shape of the destination will be used if compatible, otherwise reshaped with linear list of sub-tensors. Each source list wraps around if shorter than the total number of rows specified.

func NFromPct

func NFromPct(pct float64, n int) int

NFromPct returns the number of bits for given pct (proportion 0-1), relative to total n: just int(math.Round(pct * n))

func NOnInTensor

func NOnInTensor(trow tensor.Values) int

NOnInTensor returns the number of bits active in given tensor

func NameRows

func NameRows(tsr tensor.Values, prefix string, nzeros int)

NameRows sets strings as prefix + row number with given number of leading zeros.

func NewRand

func NewRand(seed int64)

NewRand sets RandSource to a new separate random number stream using given seed, which is saved as RandSeed -- see RestoreSeed.

func PctActInTensor

func PctActInTensor(trow tensor.Values) float32

PctActInTensor returns the percent activity in given tensor (NOn / size)

func PermutedBinary

func PermutedBinary(tsr tensor.Values, nOn int, onVal, offVal float64)

PermutedBinary sets the given tensor to contain nOn onVal values and the remainder are offVal values, using a permuted order of tensor elements (i.e., randomly shuffled or permuted).

func PermutedBinaryMinDiff

func PermutedBinaryMinDiff(tsr tensor.Values, nOn int, onVal, offVal float64, minDiff int) error

PermutedBinaryMinDiff uses the tensor.RowMajor view of a tensor as a column of rows as in a [table.Table], setting each row to contain nOn onVal values, with the remainder being offVal values, using a permuted order of tensor elements (i.e., randomly shuffled or permuted). This version (see also PermutedBinaryRows) ensures that all patterns have at least a given minimum distance from each other, expressed using minDiff = number of bits that must be different (can't be > nOn). If the mindiff constraint cannot be met within 100 iterations, an error is returned and automatically logged.

func PermutedBinaryRows

func PermutedBinaryRows(tsr tensor.Values, nOn int, onVal, offVal float64)

PermutedBinaryRows uses the tensor.RowMajor view of a tensor as a column of rows as in a [table.Table], setting each row to contain nOn onVal values with the remainder being offVal values, using a permuted order of tensor elements (i.e., randomly shuffled or permuted). See also PermutedBinaryMinDiff.

func ReplicateRows

func ReplicateRows(dest, src tensor.Values, nCopies int)

ReplicateRows adds nCopies rows of the source tensor pattern into the destination tensor. The destination shape is set to ensure it can contain the results, preserving any existing rows of data.

func RestoreSeed

func RestoreSeed()

RestoreSeed restores the random seed last used -- random number sequence will repeat what was generated from that point onward.

func SetRandSeed

func SetRandSeed(seed int64)

SetRandSeed sets existing random number stream to use given random seed, starting from the next call. Saves the seed in RandSeed -- see RestoreSeed.

func Shuffle

func Shuffle(src tensor.Values) *tensor.Rows

Shuffle returns a tensor.Rows view of the given source tensor with the outer row-wise dimension randomly shuffled (permuted).

func SplitRows

func SplitRows(dir *tensorfs.Node, src tensor.Values, names []string, rows ...int) error

SplitRows splits a source tensor into a set of tensors in the given tensorfs directory, with the given list of names, splitting at given rows. There should be 1 more name than rows. If names are omitted then the source name + incrementing counter will be used.