**** 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 ****