                        RANDY v0.3 MANUAL

Randy  is  a  configurable random number generator created to aid
those playing the game of CoreWar. It works by reading a template
file and generating a bunch of output files (randries) by replac-
ing specially marked fields with random numbers.

RANDOM VARIABLES
    Random variable specifiers are of the form

                      (!<Type> <Low> <High>!) .

    <Low> and <High> specify the range of  the  random  variable.
    Specifiers  cannot be nested. Available types of random vari-
    ables are:

    U   Uniform.   Uniformly   distributed   in   the    interval
        [<Low>, <High>].

    Lu  Unsigned log-uniform.  Ln(x)  is uniformly distributed in
        the interval  [Ln <Low>,  Ln <High>].  Equivalently, pro-
        bability density is  1 / Abs(x)  in the interval  [<Low>,
        <High>] and 0 elsewhere. <Low> and <High> must be greater
        than zero.

    Ls  Signed  log-uniform.  Same  as  the unsigned version, but
        with random signs.

    E   Enumerated. In random mode, values are generated  sequen-
        tially,  wrapping  around  the  [<Low>, <High>] range. In
        single variation mode, all values in the [<Low>,  <High>]
        range  will be generated exactly once. Equivalent to uni-
        form in other modes.

    F   From file. Values from a specified file  are  used.  File
        format  is one value per line. Line numbering starts from
        1. In single variation mode, all  values  in  the [<Low>,
        <High>] range will  be  selected  exactly  once. In other
        modes, values are selected sequentially, wrapping  around
        the [<Low>, <High>] range.

CONFIG PARAMETERS
    Randy reads the parameters from an ini-style file config.ini.
    All string parameters must be enclosed in "" quotation marks.

    PathIn
        Path to the input template file.

    PathOut
        Path to the output directory.

    PathConsts
        Path to the file with predefined constants.

    N [Integer > 0]
        Determines the number of randries and depends on mode:

        +----------------------------------------------+
        | MODE                MEANING OF N             |
        +----------------------------------------------+
        |LHC      total number of randries             |
        |Random    --"--                               |
        |Single   number of randries per variable      |
        |Paired   number of randries per variable pair |
        +----------------------------------------------+

    Start [Integer >= 0]
          Zero-padded 8-digit randry file names will  start  from
          this index.

    Brackets [either 'Yes' or 'No']
          Whether  to  enclose  generated random numbers in round
          brackets.

    Mode  Specifies mode of operation:

          Random
              All variables are  sampled  randomly  and  indepen-
              dently,  except  for the enumerated and file types.
              They are generated  sequentially,  wrapping  around
              their bounds.

          LHC Latin  Hypercube (LHC) sampling is a technique hav-
              ing superior efficiency  compared  to  random  sam-
              pling. N samples of each random variable are gener-
              ated using stratified sampling. Their  combinations
              from  N  randries.  During the stratified sampling,
              probability density  function  is  divided  into  N
              equally  probable regions and one value is randomly
              generated in each region. Advantage of the LHC mode
              in CoreWar optimization scenarios  may  in  fact be
              very  small.  However,  Randy uses LHC designs with
              good spacefilling properties,  so it is expected to
              be  more  reliable.   Time  complexity   is   about
              N^3 * D^2, where D is the number  of  random  vari-
              ables,  which  means  that  generating  large  LHCs
              will take a long time. Switch to the random mode if
              LHC generation takes too long.

          Single
              Single variation mode.  For every random  variable,
              generate N randries with all other variables set to
              0. Stratified sampling is employed to ensure better
              uniformity.  For the enumerated and file-type vari-
              ables, all  their  possible  values  are  generated
              exactly once.

          Paired
              Paired  variation  mode.   For every pair of random
              variables, generate N randries with all other vari-
              ables set to 0. Variable pairs are sampled using 2D
              LHCs. Total number of randries is

                             N * (N - 1) * D / 2.
    Extension
          File extension of the randries.

USAGE NOTES
    You may use Randy  however  you  see  fit.  However,  it  was
    designed with a couple of specific methods in mind.

  Initial constant generation
    Suppose  that  you  do  not have a good initial guess for the
    values of the constants. Select the LHC mode and specify uni-
    formly  distributed  variables  in the template. For stone or
    scan steps, use constants from  file  generated  by  programs
    such  as  Optima  or  CoreStep. Applicable step lists for the
    most popular coresizes, sorted from best steps to worst,  are
    included in the 'Steps' folder.  Minimal recommended N is the
    square root of CORESIZE.

  Optimization of existing constants
    Select single or paired variation mode. Append

                       +(!Ls 1 CORESIZE / 2!),

    CORESIZE / 2 replaced  by  actual  value,  to  each  constant
    requiring  optimization.  Scan and stone steps may be handled
    differently by specifying a file-type variable and an  appro-
    priate file. Minimal recommended N is

                      2 * Log2 (CORESIZE / 2).

    Run  the  benchmarks  and  select the best randry. Repeat the
    process until there is no significant  improvement  or  until
    you're bored.

    Paired  variation  mode  requires a potentially  much  larger
    number of randries, but accounts  for  variable  interaction.
    Thus it is recommended to  start  with the  single  variation
    mode, and when it fails to produce an improvement,  switch to
    the paired variation.

    The process is essentially a local search, with neighbourhood
    defined as a set of numbers different in only one or two val-
    ues.  Signed log uniform density generates very large as well
    as  very  small  deviations,  providing  the  exploration   /
    exploitation balance. Described method is designed to achieve
    rapid convergence to reasonably good constants with  a  rela-
    tively small number of randries.

CHANGE LOG
    0.3:   2015.05.01   + Unsigned log-uniform variable type
                        + Range checks of variable parameters
    0.2:   2014.10.06   + Option to use constants from file
    0.1:   2014.10.05   + Latin hypercube sampling
                        + Paired variation mode
                        + Starting number and brackets options
    0.0:   2014.09.24   + Initial version

CONTACT
    Send any suggestions or bug reports to:

                      reoser (at) mail (dot) ru

    Happy redcoding,
    inversed
