##############################################################################

 README for FFT_FGN

 author:    Christian Schuler
            Research Institute for Open Communication Systems
            GMD FOKUS, Hardenbergplatz 2, D-10623 Berlin, Germany
            Phone : ++49 / (0)30 / 254 99 - 295
            email : schuler@fokus.gmd.de
            URL: http://www.fokus.gmd.de/nthp/employees/chs.signature.html

##############################################################################
Version: 
   revision:  1.2, 5.1.96

##############################################################################
Description:

   Generation of Fractional Gaussian Noise by the FFT-Algorithm proposed by
   Vern Paxson, "Fast Approximation of Self-Similar Network Traffic",
   Berkeley 1995
   Info:
   "http://town.hall.org/Archives/pub/ITA/html/contrib/fft-fgn.html"

   The program is a conversion from the original code written in the AT&T 
   'S'-Language to standard 'C'. The original version was fft-fgn-1.0.

##############################################################################
Requirements and Installation:

   The source code was compiled and tested successfully on a SUN Sparc10,
   running Solaris (SunOS 5.4) using the cc compiler, and on a SUN IPX
   running SunOS 4.1.4 using gcc 2.7.0.  It requires an ANSI C compiler.

   The source code of 'C' implementation consists of 3 parts:

   1) The algorithm, file "fft_fgn.c"

   2) A library of pseudo random routines, files "ranlib.c", "com.c",
     "linpack.c" and "ranlib.h"

      Source: ftp@hpux.ask.uni-karlsruhe.de

      This library contains the two random functions used in "fft_fgn.c":
      genexp() and ranf().  The code is written in 'FORTRAN' style with
      lots of goto's, additional information is in README.ranlib.  There are
      probably better libraries on the net, but I didn't know where ...
  
   3) A FFT function, file "fft_rif.c", source: PTOLEMY simulator.

   The complete program should be compiled and linked by typing: "make".
   You may want to first adjust the definitions of CC, CFLAGS, and CC_LD in
   the Makefile.

##############################################################################
Acknowledgements:

      author: Christian Schuler
              Research Institute for Open Communication Systems
              GMD FOKUS, Hardenbergplatz 2, D-10623 Berlin, Germany
              Phone : ++49 / (0)30 / 254 99 - 295
              email : schuler@fokus.gmd.de

##############################################################################
Restrictions:    
  

Copyright (c) 1995 The Regents of the University of California.
All rights reserved.

This code is derived from software contributed to Berkeley by
Vern Paxson.

The United States Government has rights in this work pursuant
to contract no. DE-AC03-76SF00098 between the United States
Department of Energy and the University of California.

Redistribution and use in source and binary forms are permitted
provided that: (1) source distributions retain this entire
copyright notice and comment, and (2) distributions including
binaries display the following acknowledgement:  ``This product
includes software developed by the University of California,
Berkeley and its contributors'' in the documentation or other
materials provided with the distribution and in all advertising
materials mentioning features or use of this software.  Neither the
name of the University nor the names of its contributors may be
used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.

-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This basically says "do whatever you please with this software except
remove this notice or take advantage of the University's (or the author's)
name".

In particular, you are free to redistribute the software, sell it,
modify it, etc., provided you abide by the terms above.

##############################################################################
Documentation:

  The parameters are handled by command line interface. To get an overview,
  type: "fft_fgn -h". You should see:

>fft_fgn -h
#################################################################
fft_fgn: Generation of Fractional Gaussian Noise by FFT-Algorithm
Usage:
        -h            this page
        -H <value>    Hurst parameter, default 0.7
        -M <value>    output mean value, default 0.0
        -V <value>    output variance, default 1.0
        -c            generate integer output by ceil(), default rint()
        -f            generate integer output by floor(), default rint()
        -e            apply final exponential transform
        -o <filename> output data file (stdout is default)
        -m <mode> set output:
                        0: estimated power spectrum
                        1: randomized power spectrum
                        2: complex power spectrum
                        3: complex power spectrum, re/im form
                        4: output inverse fourier transform, re/im form
                        5: real sample path (default)
                        6: integer sample path
        -n <value>    number of sample points (power of 2), default 4096
        -s <value>    integer seed of random number generator
        -v <level>    verbose level
Warning: output mode 6 and parameter -e might destroy the
         self-similar statistical properties of the output !
 
         GMD FOKUS fft_fgn 1.2 96/01/05



  If a parameter is omitted, appropriate default values are applied.
  Example 1:

> fft_fgn -o default.output -v 2
before variance adjustment: mean -0.000000 variance 4136.625011
before mean adjustment:     mean -0.000000 variance 1.000000
fft_fgn: Fractional Gaussian Noise
Hurst parameter:                 0.700000
number of sample points:         4096
seed of random number generator: 31
mean parameter:                  0.000000
variance parameter:              1.000000
output mean value:               -0.000000
output variance:                 1.000000
output data:                     Real Sample Path



  Example 2:


>  fft_fgn -v 2 -o fft_fgn.data -V 100.0 -M 10.0 -H 0.89 -m 6 -e -n 262144
before exp transformation:  mean 0.000000 variance 0.924077
before variance adjustment: mean 1.583141 variance 3.683319
before mean adjustment:     mean 8.248974 variance 100.000000
fft_fgn: Fractional Gaussian Noise
Hurst parameter:                 0.890000
number of sample points:         262144
seed of random number generator: 31
mean parameter:                  10.000000
variance parameter:              100.000000
output mean value:               10.000252
output variance:                 100.094963
output data:                     Integer Sample Path
truncated by rint()
exponential transformation applied !
 
  (Calculation time on a SUN Sparc10: about 40 sec. , 
   Size of Output File "fft_fgn.data" 613944 Bytes)

##############################################################################
Limitations:

    The transformation of the inverse fourier transform to an integer output
    is done by the rint(), ceil() or floor() function. This will probably change
    the statistical properties of the output sample path. The same applies to
    the -e - Parameter, which can be used to eliminate negative values in the
    output signal.