eu.bandm.music.entities

Class RandomStructs

java.lang.Object

eu.bandm.music.entities.RandomStructs

public class RandomStructs
extends Object

Wrapper class for generating random-based data structures frequently needed in algorithmic (music) composition. An instance of this class provides the generation of very different data types by (pseudo) random, i.e. the results are reproduced when the start value is identic.

Calculation is based on one particular instance of Random, the Java runtime random generator. stored in generator, and some methods are simply forwarded.

A message receiver can be used to generate a (multi lingual) protocol of all decisions, to make e.g. the genesis of a composition transparent for analysis.
FIXME config methods not yet defined.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Random	generator One single Java built-in random generator, used sequentially for all incoming requests.
(package private) @Opt String	ident Name of this instance in protocol lines.
(package private) static byte[]	masks Aux data for masking out the bit patterns generated by generator.
(package private) @Opt MessageReceiver<SimpleMessage<?>>	protocol If set, protocol lines are generated for each random selection operation.
(package private) @Opt MessageFormatter.Formandum	purpose A temporary register to integrate the purpose of a generated random value into the protocol message.
static CatalogByString	translations

Constructor Summary

Constructors

Constructor and Description
RandomStructs() Constructor without protocol generation.
RandomStructs(MessageReceiver<SimpleMessage<?>> protocol, @Opt String ident) Constructor with protocol generation.

Method Summary

Modifier and Type	Method and Description
int	integerWeighted(int[] weights) Returns by random an index into an array of relative weights.
List<Integer>	intPermutation(int limit) Calculates randomly a permutation of the integers 0 to limit-1.
BitSet	intSet(int limit) Calculate a BitSet in which the lowest "limit" bits are randomly 0 or 1.
BitSet	intSet(int limit, int min, int max) Calculate a BitSet in which the lowest "limit" bits are randomly 0 or 1, with given minimum and maximum of 1 bits.
(package private) void	log(String text, Object... args)
static long	makeSeed(String phrase) Create a 32bit value as a start seed from a human language input text.
boolean	ofOne(float p) Calculates by random a boolean with the probability of p (of one) to be true.
void	setPurpose(MessageFormatter.Formandum purpose) Set the text which describes the purpose of the very next generated random value into the protocol message.
void	setPurpose(String purpose) Set the text which describes the purpose of the very next generated random value into the protocol message.
void	setSeed(long seed) Set the starting point of the random generator, to make all results reproducable.
int	singleInteger(int limit) Calculates by random a positive integer between 0 and (limit-1).
int	singleInteger(int[] values) Selects by random one integer value from the array, all with equal probability.
int	singleInteger(int lo, int hi) Calculates by random a positive integer between lo and (hi-1).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

generator

final Random generator

One single Java built-in random generator, used sequentially for all incoming requests.

protocol

@Opt
final @Opt MessageReceiver<SimpleMessage<?>> protocol

If set, protocol lines are generated for each random selection operation.

ident

@Opt
final @Opt String ident

Name of this instance in protocol lines. Maybe == null if messages are unambiguous anyhow.

purpose

@Opt
@Opt MessageFormatter.Formandum purpose

A temporary register to integrate the purpose of a generated random value into the protocol message.

translations

public static CatalogByString translations

masks

static final byte[] masks

Aux data for masking out the bit patterns generated by generator.

Constructor Detail

RandomStructs

public RandomStructs()

Constructor without protocol generation.

RandomStructs

public RandomStructs(MessageReceiver<SimpleMessage<?>> protocol,
                     @Opt
                     @Opt String ident)

Constructor with protocol generation.

Parameters:

protocol - where to send the protocol messages

ident - to identify this instance, may be null.

Method Detail

setPurpose

public void setPurpose(MessageFormatter.Formandum purpose)

Set the text which describes the purpose of the very next generated random value into the protocol message. Is cleared immediately afterwards.

setPurpose

public void setPurpose(String purpose)

Set the text which describes the purpose of the very next generated random value into the protocol message. Is cleared immediately afterwards.

log

void log(String text,
         Object... args)

makeSeed

public static long makeSeed(String phrase)

Create a 32bit value as a start seed from a human language input text. All blanks are removed, and afterwards there must be at least twelve distinct characters. Only the lower 8 bits of all characters are considered.

setSeed

public void setSeed(long seed)

Set the starting point of the random generator, to make all results reproducable. Simply forward to generator.

singleInteger

public int singleInteger(int limit)

Calculates by random a positive integer between 0 and (limit-1). Simply forward to generator.

Returns:

an integer between 0 and (limit-1).

Throws:

IllegalArgumentException - if limit<0

singleInteger

public int singleInteger(int lo,
                         int hi)

Calculates by random a positive integer between lo and (hi-1). Forward the generation to generator.

Returns:

an integer between lo and (hi-1).

Throws:

IllegalArgumentException - if hi

ofOne

public boolean ofOne(float p)

Calculates by random a boolean with the probability of p (of one) to be true. (Inspired by the "oneOf(int)" operator in "sonic pi".)

singleInteger

public int singleInteger(int[] values)

Selects by random one integer value from the array, all with equal probability.

Returns:

an integer from the array, all with equal probability.

Throws:

IllegalArgumentException - if hi

integerWeighted

public int integerWeighted(int[] weights)

Returns by random an index into an array of relative weights. Eg. with [3,6,3] in 50% of arbitrary many tries, the index "1" will be returned, and in 25% each "0" and "2".

intSet

public BitSet intSet(int limit)

Calculate a BitSet in which the lowest "limit" bits are randomly 0 or 1. Calls Random.nextBytes(byte[]) which promises to distribute 0 and 1 randomly.

Returns:

a bit set with the lowest members set randomly

Throws:

IllegalArgumentException - if limit<0

intSet

public BitSet intSet(int limit,
                     int min,
                     int max)

Calculate a BitSet in which the lowest "limit" bits are randomly 0 or 1, with given minimum and maximum of 1 bits. Calculates first by random the number of 1-bits, then a list of random positions to be set, until this numver of set bits is reached. ATTENTION may not terminate if integer number generation is not truely random.

Parameters:

limit - the total length of the bit set

min - possible minimal count of one-bits

max - possible maximal count of one-bits, inclusive.

Returns:

a bit set with the lowest members set randomly

Throws:

IllegalArgumentException - if limit<0 or max<0

intPermutation

public List<Integer> intPermutation(int limit)

Calculates randomly a permutation of the integers 0 to limit-1. The list grows from position 0 to limit-1. The number of gaps in the set of already assigned numbers decreases with every addition. An integer is chosen by random between 0 and gaps-1, and the number at this gap is added to the list.