Package 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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    RandomStructs.TextFields
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final Random
    generator
    One single Java built-in random generator, used sequentially for all incoming requests.
    (package private) final @Opt String
    ident
    Name of this instance in protocol lines.
    (package private) static final byte[]
    masks
    Aux data for masking out the bit patterns generated by generator.
    (package private) final @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
    Description
    RandomStructs()
    Constructor without protocol generation.
    RandomStructs(MessageReceiver<SimpleMessage<?>> protocol, @Opt String ident)
    Constructor with protocol generation.

  • Method Summary

    Modifier and Type
    Method
    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.
    static int
    nth(BitSet bitset, int number)
    Finds the nth set bit (zero-based!) Returns -1 when number too large.
    boolean
    ofOne(float p)
    Calculates by random a boolean with the probability of p (of one) to be true.
    Integer
    select(BitSet bitSet)
    Picks one of the set bit positions.
    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 Details

    • 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 Details

    • 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 Details

    • 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<lo

    • 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<lo

    • 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.

    • select

      public Integer select(BitSet bitSet)
      Picks one of the set bit positions. DOCME

    • nth

      public static int nth(BitSet bitset, int number)
      Finds the nth set bit (zero-based!) Returns -1 when number too large.