The ALFA TurbuLenZ Homepage
Download the ALFA TurbuLenZ Software V0.4.
Example input file t.inp.
**** RELEASE NOTES FOR TurbuLenZ V0.4 **** BEGIN ****


--------------------------------------------------------------------
OVERVIEW:

0: Legal Stuff and Version History
1: Requirements and Installation
2: Input and Output Files
3: Known Problems and Outlook
--------------------------------------------------------------------





--------------------------------------------------------------------
0. Legal Stuff and Version History
--------------------------------------------------------------------

0.1 Legal Stuff:
    
  - This code may be freely distributed and modified for scientific
    purposes ONLY as long as this file is distributed along with it.
    Copyright remains with Max-Planck-Institut fuer Astronomie,
    Heidelberg (c)1999-2000 and A.R. Weiss.

  - If substantial portions of this code are reused in other projects
    it must be made clear in the project's disclaimer that it is taken 
    from our code.

  - Publication based on simulations carried out by this code should
    cite it as "T. Berkefeld and A.R. Weiss, Waves in Random Media,
    2000, in preparation".

  - This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    (taken from the GNU GPL)
 
  - IDL is a trademark of RSI, Inc., Boulder, CO, USA.

0.2 Version History:

  - Versions 0.1-0.3 were non-public development versions
  - V0.1 (Oct. 1999): Direct translation of original C Code by
    A. Glindemann and T. Berkefeld.  
  - V0.2 (Nov. 1999): Heavily vectorized and accelerated version
  - V0.3 (Jan. 2000): New features were included due to a new C
    version released by T. Berkefeld in Dec. 1999 (Shack-Hartmann-
    Simulation, Fresnel propagation)   
  - First publicly available version is V0.4 (which is still a bag of
    bugs) 
  - V0.4 (Feb. 2000): Major bugs fixed

--------------------------------------------------------------------
1. REQUIREMENTS AND INSTALLATION
--------------------------------------------------------------------

1.1 Requirements:

  - Since TurbuLenZ V0.4 is a collection of IDL routines it needs a
    system with IDL installed. Several parts of the simulation make
    use of object oriented features, hence an IDL version equal or
    greater than 5.0 is required.

  - The IDL Astrolib must be installed on your system and reside in
    the IDL search path. The IDL astrolib can be obtained from the WWW
    site http://idlastro.gsfc.nasa.gov/homepage.html.

1.2 Download and Installation

  - untar the archive (tar xzf tlz0.4.tar.gz) into a single
    directory of your choice.

  - change to the directory where you unpacked the files or set your
    IDL working directory accordingly. Launch IDL. You may now invoke
    a simulation by typing "turbulence, <inputfile>" where <inputfile>
    is formatted as described in section two.

--------------------------------------------------------------------
2. INPUT AND OUTPUT FILES
--------------------------------------------------------------------

2.1 The Input File Explained:

  - The input file contains the information necessary to run the
    simulation; each line may contain exactly one number with
    subsequent comments (starting with a non-numeral) or a comment
    only (again: starting with a non-numeral character). Empty lines
    are ignored. The order of the given parameters in absolutely
    crucial and will be explainded below.

  - The first 12 (numerical) entries of the input file are always
    present and describe the genral simulation setup:
    ----------------------------------------------------------
    |entry |  description                          | example |
    ----------------------------------------------------------
    |  #1  |  Number of turbulent layers (integer) |   1     |
    ----------------------------------------------------------
    |  #2  |  Number of telescopes (integer)       |   1     |
    ----------------------------------------------------------
    |  #3  |  Number of starts (integer)           |   2     |
    ----------------------------------------------------------
    |  #4  |  Number of time steps (integer)       | 1000    |
    ----------------------------------------------------------
    |  #5  |  Pixelscale in the aperture plane     |  20.0   |
    |      |  (float)  [pixels/m]                  |         |
    ----------------------------------------------------------
    |  #6  |  Imaging wavelength (float)  [m]      |0.0000022|
    ----------------------------------------------------------
    |  #7  |  Fresnel propagation height minimum   | 2000.0  |
    |      |  [m]                                  |         |
    ----------------------------------------------------------
    |  #8  |  Phase screen storage flag            |   0     |
    |      |  1: save phase screens, 0: don't      |         |
    ----------------------------------------------------------
    |  #9  |  total imaging storage flags          |   7     |
    |      |  three bits (0:no, 1:yes):            |         |
    |      |  bit 0: save centroids/intensities    |         |
    |      |  bit 1: save speckle images           |         |
    |      |  bit 2: save aperture plane phase and |         |
    |      |         amplitude                     |         |
    ----------------------------------------------------------
    | #10  | individual layer imaging storing flags|   0     |
    |      | same as #9 (but for individual layers)|         |
    ----------------------------------------------------------
    | #11  | number of first storage filename      |   1     |
    ----------------------------------------------------------
    | #12  | Init&temporary storage flag           |   2     |
    |      | 0: don't init and store on HDD        |         |
    |      | 1: init and store on HDD              |         |
    |      | 2: init and store in RAM              |         |
    ----------------------------------------------------------
    TABLE 2.1: General Simulation Setup Entries

  - The next entries describe the turbulent layers. For each turbulent
    layer declared in entry #1 in Table 2.1 a set of six parameters
    must be set (start with the uppermost layer):
    ----------------------------------------------------------
    |entry |  description                          | example |
    ----------------------------------------------------------
    |  #1  |  decorrelation factor for this layer  |   0.0   |
    |      |  0: no decorrelation                  |         |
    |      |  >100.0: complete decorrelation       |         |
    ----------------------------------------------------------
    |  #2  |  Outer scale of turbulence [m]        |   200.0 |
    ----------------------------------------------------------
    |  #3  |  windspeed [m/timestep]               |   0.1   |
    ----------------------------------------------------------
    |  #4  |  wind direction [degrees]             |   0.0   |
    ----------------------------------------------------------
    |  #5  |  Fried parameter (atmospheric         |   0.4   |
    |      |  coherence length) [m]                |         |
    ----------------------------------------------------------
    |  #6  |  Height from ground [m]               | 10000.0 |
    ----------------------------------------------------------
    TABLE 2.2: Turbulent Layer Setup Entries
  
  - Now the telescopes must be set up. Five entries describe each
    telescope declared in entry #2 in Table 2.1. Shack-Hartman
    Simulations could also be set up here, but as they are still
    buggy, this will not be done (for your own security ;-)):
    ----------------------------------------------------------
    |entry |  description                          | example |
    ----------------------------------------------------------
    |  #1  |  aperture diameter [m]                |   3.5   |
    ----------------------------------------------------------
    |  #2  |  Pixelscale in the image plane ["/px] |   0.04  |
    ----------------------------------------------------------
    |  #3  |  size of the image [pxls]             |   200   |
    ----------------------------------------------------------
    |  #4  |  x-Offset from center [m]             |   0.0   |
    ----------------------------------------------------------
    |  #5  |  y-Offset from center [m]             |   0.0   |
    ----------------------------------------------------------
    TABLE 2.3: Telescope Layer Setup Entries
  
  - Last not least the positon of the stars have to be
    described. Since (as of V0.4) all stars have the same luminosity
    (hmmm... strange universe) only two entries are necessary:
    ----------------------------------------------------------
    |entry |  description                          | example |
    ----------------------------------------------------------
    |  #1  |  azimuthal offset from zenith ["]     |   0.0   |
    ----------------------------------------------------------
    |  #2  |  elevation offset from zenith ["]     |   0.0   |
    ----------------------------------------------------------
    TABLE 2.4: Star Setup Entries    

  - The last numerical entry in the input file MUST be 123456789. This
    serves as a check if the correct number of entries was contained
    in the file.

  - Example input file t.inp.

2.2 Names and Contens of the Output Files:

  - depending on the storage setup in the input file a great number of
    output files may be produced by the simulation

  - <prefix> in the following is the name of the input file

  - The file "<prefix>.log" contains the values of the dependent
    simulation parameters that are calculated by the simulation, like
    phase screen sizes etc.

  - Files of the form "<prefix>lXXnoYYphase.fits" contain images of
    the phase screens for layer XX and time step YY of the simulation.

  - Files of the form "<prefix>lXXtYYsZZnoUUimage|phase|ampl.fits"
    contain images of the imaging process for telescope YY, star ZZ
    and time step UU. For XX=0 these are the total images (after
    propagation through all layers), for XX<>0 these are images after
    propagation through single layers. image|phase|ampl means Speckle
    image, aperture plane phase or aperture plane amplitude image
    respectively. 

  - Files of the form "<prefix>lXXtYYsZZ" contain centroiding and
    scintillation information for star ZZ on telescope YY as an ASCII
    table. The first two columns are the x and y positions of the
    center of mass, the third column is the intensity relative to
    intensity for step 0. The rows correspond to the time steps.
    The convention for XX is the same as for images.

--------------------------------------------------------------------
3. KNOWN PROBLEMS AND OUTLOOK
--------------------------------------------------------------------
  
3.1 Known Problems:

  - The results of the IDL version of Turbulence have as of yet not
    been subject to thorough testing. So be careful with the
    interpretation of your results. However, this situation is
    improving quickly.

  - Shack-Hartmann Simulation suffers from problems and reduced
    flexibility. 

  - Imaging results (Speckle images) are NOT RIGHT. Beware. This will
    be fixed in V0.5

  - Simulation of complex situations is slow. This is unfortunate, but
    all turbulence simulation programs suffer from this problem.

3.2 Outlook:
 
  - V0.5 will be released by mid-March 2000 and will be considered the
    first relatively bug-free and stable version. It will contain a
    GUI for setting up the simulation as well as a collection of
    evaluation routines. This will also be the last version to be
    definitely compatible with the C version of this program.

  - Version numbers 0.6-0.9 will be reserved for bug fixes and
    possible improvements of the compatibility version 0.5

  - By end of March 2000, TurbuLenZ V1.0 will be released containing
    several new possibilities as compared to the former versions;
    e.g. a completly integrated GUI for setup, execution and
    evaluation of simulations; SCIDAR simulations will also be
    possible. However, V1.0 will NOT be compatible with old input
    files.


A. Robert Weiss, Heidelberg, February 28th, 2000.

**** RELEASE NOTES FOR TurbuLenZ V0.4 **** END ****