TurbTool User Guide
Boris P. Venet
Contents
3
Main
screen inputs: General remarks
3.2
Numerical notes and cautions
4
Main
screen inputs: Geometry
4.1
Color regions in the geometry plot
4.4
Remarks on Ground Altitude
5
Main
screen inputs: Profiles
5.3
Scattering and absorption profiles
6
Main
screen inputs: Phase screens,
Integration methods, and miscellaneous parameters
7
Main
screen outputs: Table of integrated
turbulence quantities
7.2
Integration, screens, and top of the
turbulent atmosphere
8
Main
screen outputs: Miscellaneous
10.3
Mainscreen updates upon return from
Phase Screens table
11
Configuration
file settings
12
Formulas
used by TurbTool for integratedturbulence quantities
13
Independent
use of turbulence profile subroutines..
TurbTool is a Matlab GUI application that complements the WaveTrain waveoptics simulation code. TurbTool can also be used independently of WaveTrain. TurbTool serves essentially two purposes:
(1) TurbTool allows the user to specify a propagation geometry with turbulence strength and wind profiles, and then to very quickly compute analytic approximations to important integrated turbulence quantities. Examples of such quantities are scintillation irradiance variance, Fried's wave coherence length, isoplanatic angle, and the Greenwood and Tyler frequencies. This type of calculation is useful independent of or in concert with a WaveTrain waveoptics simulation. TurbTool also provides information regarding atmospheric scattering and absorption profiles along the propagation path.
(2)
TurbTool can be used to generate a data file of
phasescreen specifications that can serve as a complete set of arguments to
WaveTrain's atmospheric specification modules.
Such data may comprise turbulence screen locations, strengths and wind speeds,
as well as absorption and scattering coefficients for companion thermal
blooming screens. If so directed,
TurbTool will save the required vectors to a *.mat file, which can later be
read into a WaveTrain runset.
Function
(1) of TurbTool allows the user to assess certain general behaviors to be
expected from a given propagation geometry, and to quickly obtain parameters
that may be used as checks on the detailed waveoptics simulation results. However, note that the integratedturbulence
formulas evaluated by TurbTool are either Rytov or geometrictheory
approximations. Therefore, one should
expect agreement between simulation results and TurbTool predictions only
within the domains of validity of the approximate formulas. The formulas used by TurbTool are specified
later in this document.
Function (2) of TurbTool can be applied in several variations, as the user finds most helpful. As noted above, TurbTool can generate a data file containing the complete information required to specify atmospheric phase screens (turbulence and thermal blooming). This file can then be read in as a unit to the WaveTrain modules that require the information. However, users may prefer to use TurbTool to compute required data vectors (e.g., screen positions and C_{n}^{2} values for AcsAtmSpec), and then to copy the data manually to various lines of a WaveTrain runset editor. While the latter procedure may involve a little more manual labor, some users may find that it provides a greater sense of user control and later readability of the runset. In any case, this is the most flexible way of using TurbToolgenerated data as WaveTrain input.
In
general, TurbTool can provide the user considerable help in generating
WaveTrain atmospheric input data.
TurbTool features include:
(1)
Availability of numerous "standard" C_{n}^{2} profiles (Clear1, HV5/7, etc.) and wind profiles used
by the community.
(2)
Computation of effective, i.e. segmentaverage, C_{n}^{2} values to be associated with discrete screens.
(3)
Several standard options for generating path
segmentation to define phase screen strengths, and to position the screens
within the corresponding segments.
(4)
Absorption and scattering data for thermal blooming
screens, where this data is derived from the validated MODTRAN and FASCODE
codes (developed at the Air Force Geophysics Laboratory).
(5)
Continuous and discrete integration options for
computing integrated turbulence quantities.
These can be used to estimate the discretization effects of the
splitstep or lumpedparameter modeling of atmospheric propagation that is
used in waveoptics simulation.
(6)
Ability to define completely userspecified discrete
profiles.
(1)
Open a Matlab session
(2)
Make the current directory
C:\Program Files\mza\wavetrain\v2007a\mfiles\turb2007.tbx
Or, ensure that turb2007.tbx is the
only turb*.tbx directory in the
Matlab search path.
If you have a custom installation, adjust the above path to turb2007.tbx accordingly.
(3)
At the Matlab prompt, type: >> turbtool
This will open the TurbTool main screen, whose appearance is shown in the
following figure. (The numerical values shown here are the default startup
values, except that Platform and Target Velocity have been altered from their
default zeros).
(4)
Depending on what other MZA software is present on your
machine, you may receive (prior to the appearance of the Turbtool main screen)
a dialog box asking whether the "pathtool" should attempt to find
"ATMTools" and add that to your Matlab search path. If you do not have the ATMTools toolbox on
your machine, then the absorption and scattering profiles will not be available
in TurbTool. However, all the
turbulence features of TurbTool will still be available.
Figure 1: Main screen of TurbTool GUI
The main TurbTool screen contains the following principal elements:
(1) An input block where the optical propagation path geometry is specified. Above this block is a graphical representation of the propagation path.
(2) An input block where profile selections and parameters are specified.
(3) An input block where phase screen and miscellaneous parameters are specified. Above this block is a graphical representation of the discrete screen strengths and locations.
(4) An output table where computed values of integrated turbulence quantities are displayed.
(5) Status and informational blocks for display of certain messages.
(6) A set of pulldown menus to access further features.
Most input fields have Windows tool tips to quickly remind the user of key points: to see the tip, place the mouse pointer over the name of the input field.
All output quantities on the main screen are immediately recomputed when any input specification is changed. After typing a revised number in an input field, the changes takes effect when the user (a) presses the <enter/return> key, or (b) places the cursor in another field.
In certain circumstances, the order of computations combined with roundoff produces a numerical singularity or a disallowed condition. An example is that the GUI sometimes reports that the minimum path altitude is below the earth's surface, even though it appears from the specified inputs that they are exactly equal. In such cases, the user is requested to slightly modify one of the inputs to avoid the singular condition. When such conditions occur, the problem should be obvious once the inputs are reinspected.
The figure panels (A) and (B) below show two examples of propagation path geometry. Note that four regions are colorcoded in the companion plot. Dark blue represents the portion below mean sea level, light brown represents the portion between mean sea level and ground level, light blue represents the portion between ground level and the top of the turbulent atmosphere, and white represents the portion above the top of the turbulent atmosphere.
(A) (B)
Figure 2: Geometry input block: two path geometry examples
By default, the top of the turbulent atmosphere is defined as 50 km above mean sea level, but the user can change this by modifying a configuration file. Paths are allowed to have arbitrary portions above the turbulent atmosphere, but for computational purposes C_{n}^{2} is set to zero there. (Note that even though C_{n}^{2} is zero, these path portions still affect certain integrated turbulence quantities, because certain effects continue to evolve after a beam exits the turbulent region). Further details and the rationale for defining a top of the turbulent atmosphere are given in the sections that discuss turbulence profiles and integrated turbulence quantities.
In the propagation geometry plot, the lines that point from the P and T locations down through the mean sea level surface are always pointing to the center of the earth, as it would appear on the given plot scale. In other words, these lines are perpendicular to the sealevel surface in real space. However, if the plot scale is substantially different in the horizontal and vertical, the T line will appear to intersect the surface at an angle quite different from 90 degrees: this occurs because angles are not preserved in a mapping that has unequal horizontal and vertical scales.
The optical propagation path is specified in terms of platform (P) and target (T) ends, where these terms have the same meaning as in WaveTrain. The significance of P(latform) and T(arget) within TurbTool and WaveTrain is:
(a) P(latform)
is assigned the coordinate z = 0.
(b) T(arget)
is assigned the coordinate z = L, where L the total
propagation distance (slant range).
(c) In
WaveTrain, outgoing waves define the +z direction, i.e., the P to T
direction,
whereas incoming waves define the z direction, i.e., the T to P
direction. In TurbTool,
"incoming" and "outgoing" tags are not used, except in
reference to WaveTrain.
(d) Coordinate
z is the slantpath linear coordinate between P (z = 0) and T (z
= L). Matching the z
orientations is significant when transferring data from TurbTool to WaveTrain
run sets. Within TurbTool alone, there
is no constraint on which path end is designated as having z = 0.
(e) P and T have no particular association with sources and sensors in TurbTool or WaveTrain (WaveTrain sources and sensors may be located at either or both P and T). Furthermore, TurbTool will automatically compute integrated turbulence quantities for both directions of propagation.
The
two Cartesian axes transverse to z (the nominal propagation axis) are
designated as the x and y axes.
The role played by x and y in TurbTool is to provide
references for specifying transverse velocities of platform, target and
atmospheric wind. Other than forming an
orthogonal triple, there is no constraint on how the user may orient the x
and y directions. The
orientation can be chosen to make the subsequent specification of x and y
components of platform, target and atmospheric wind velocities as convenient as
possible. The x,y
orientation exists only in the user's head:
the only specifications entered into TurbTool are the velocity
components themselves. The velocity
components affect some, but not all of the integrated turbulence quantities.
TurbTool
assumes a sphericallysymmetric earth model.
Input altitudes are specified along the local vertical, with respect to
mean sea level (MSL). Path elevation
angles at P or T are measured from the local horizontal (which is the line
perpendicular to the local vertical).
Allowed elevation angles are
{90
£ elev ang
£ +90 deg}. The shorthand Platform(Target) Elev Angle that appears in the GUI means the elevation angle
of the propagation path at the point P(T), with respect to the local horizontal
at P(T), as illustrated in the figure below.
In this example, the numerical value of P elev is positive, and the
numerical value of T elev is negative.
Figure 3: Range and elevation angle definitions
A propagation path is defined by entering values for Ground Altitude, and then three of the six fields {Platform Altitude, Target Altitude, Platform Elevation Angle, Target Elevation Angle, Slant Range, Ground Range}. As soon as a complete set is specified, the program calculates the remaining dependent quantities. To specify a different set of input fields from the current selections, use the check boxes on the right side to first deselect current fields, and then to select the desired fields. Only the following input combinations are allowed:

Allowed input combinations 

1 
P alt 
slant R 
T alt 
2 
P alt 
ground R 
T alt 
3 
P alt 
P elev angle 
slant R 
4 
P alt 
P elev angle 
ground R 
5 
T alt 
T elev angle 
slant R 
6 
T alt 
T elev angle 
ground R 
Table 1: Allowed geometry input combinations
Physical units for all quantities are specified on the GUI screen.
The first entry field in the GUI geometry block is Ground Altitude (with respect to mean sea level). The function of Ground Altitude in TurbTool is to cause certain adjustments in the standard turbulence strength vertical profiles. Details of this adjustment are described in the section on turbulence profiles. TurbTool assumes that the ground altitude under the propagation path is uniform.
Platform and target x and y velocities may be specified. The definition of the x and y axes is discussed in the section on coordinate systems. Platform and target velocities combine vectorially with the true wind profile to form a pseudowind profile that affects certain integrated turbulence results (the Greenwood and Tyler frequencies).
The input block where profiles are specified is shown at right. Five types of profiles are currently supported: turbulence strength, wind speed, temperature, scattering coefficient, and absorption coefficient. Turbulence and wind specifications affect the integrated turbulence quantities reported in an output table. Scattering, absorption and temperature profiles do not affect the turbulence calculations in TurbTool. The scattering and absorption profiles only determine the optical transmissions reported in another output table. Additionally, the discrete values of scattering, absorption and temperature that are stored in a TurbTool output file (if such file is requested) may later be used by a WaveTrain run set to specify thermal blooming parameters.
The Scale input fields allows the user to apply an arbitrary multiplier factor to any selected profile. That is, the named profile values are multiplied by the same Scale factor at every point along the path. Wind is a vector, and therefore has two scale factors: this is discussed further in the section on wind profiles.
TurbTool
allows the user to:
(a) select from a set of standard turbulence vertical profiles, or
(b) define a completely custom profile (discrete only).
As illustrated at right, by clicking the arrowhead at the right of the Turbulence list field, the user obtains a dropdown list of standard turbulence vertical profile names. Each of these profiles has achieved some recognition by researchers in the field of atmospheric propagation. Clicking on any profile name selects that profile. Notice that there is one profile named Constant , which implies C_{n}^{2 }= 1.0 m^{2/3} everywhere. This base value can then be scaled with the Scale factor entry.
A plot of the continuous turbulence profile may be inspected by using the menu option View  Turbulence profile (not View  Turbulence distribution ). For further background on some of the standard profiles, a good starting point is the article by Robert R. Beland, Propagation through Atmospheric Optical Turbulence, in Atmospheric Propagation of Radiation, The Infrared and ElectroOptical Systems Handbook, vol. 2, pp. 217224, F.G. Smith, ed., ERIM and SPIE Press, 1993.
A plot of the discrete turbulence distribution as represented by phase screens appears on the main GUI screen, above the phase screens input block. An illustration from TurbTool s default opening screen appears at right. Note that the plot title implies that screen strengths are defined by either an Integrated or an Average C_{n}^{2} strength, where Integrated and Average refer to the path segment that is represented by a particular screen. The average value is plotted in red, relative to the righthand axis, and the integrated value is plotted in blue, relative to the lefthand axis. The main point we wish to emphasize here is that Average C_{n}^{2} for a segment (equivalently called the screen C_{n}^{2} ), is usually not equal to the point value of the continuous C_{n}^{2} profile at the screen location. (Of course, the average is equal to the point value at some point within the segment, if the profile function is continuous). For further details, see the discussion of the phase screens input block and the phase screens table.
Depending on the path geometry inputs, TurbTool may make one potentially significant modification to the standard profiles as defined in the literature. The issue here is that many of the standard profiles were constructed from sitespecific data. These profile functions are typically defined in terms of height above mean sea level, h_{AMSL}, and the profile function is only defined for h_{AMSL} > hgnd ^{mod}, where hgnd ^{mod} is the altitude of the model ground level above MSL. The model ground level is the ground altitude at the site where the data was collected. For example, the Clear1 profile was constructed from data taken over a site on the White Sands Missile Range where hgnd ^{mod} = 1216 m AMSL. A second example is the AMOS profile, constructed from data taken over Mt. Haleakala on the island of Maui, where hgnd ^{mod} = 3038 m AMSL. In some application scenarios, we may actually be interested in those very sites. On the other hand, we are often interested in sites whose ground level is quite different from any of the standard profiles, and yet we may want to apply a turbulence profile that is like one of the standard ones. To do so, we must apply some knowledge about what controls the turbulence, so that we can appropriately shift, stretch, or otherwise map the model profile to the ground level and height domain of the propagation path. In the lower troposphere, the atmospheric turbulence is principally controlled by the interplay between ground heating/cooling and the air temperature. Thus, in the absence of more detailed physics modeling, the simplest reasonable procedure is to assign C_{n}^{2} values for the application scenario according to the following rule: if a point on the propagation path has altitude above ground level h_{AGL }, then C_{n}^{2} at that point is assigned the value that occurs at elevation (hgnd ^{mod} + h_{AGL}) in the model profile. Equivalently put, TurbTool uses the approximation of rigidly shifting any standard turbulence profile so that its model ground level translates to the ground level under the propagation path.
As far as TurbTool usage is concerned, the implication is very simple. Given any Ground Altitude and corresponding path geometry that users care to specify in the geometry block, users can subsequently select any of the standard turbulence profiles. If users want to be completely faithful to the standard profile definitions, then they can specify Ground Altitude = hgnd ^{mod} for the selected model. To assist users in this regard, selection of any turbulence model produces a message in the Info output block that specifies the numerical value of hgnd ^{mod}.
The document Turbulence profile adjustment for varying ground altitude Ver. 2 provides a somewhat more extended discussion of the above issue.
At very high altitudes, the C_{n}^{2} values assigned by the TurbTool profiles are notional at best. Typically, the standard profiles constructed from thermosonde data were measured up to about 30 km above MSL (see the previously cited Beland article). However, the functional curve fit to the data, which is what constitutes the standard profile model, is usually defined so that it extrapolates smoothly above the data limit. For reasons of continuity, TurbTool will use these extrapolated forms, if they exist, since the extrapolated values are probably a better guess than zero. Finally, TurbTool also defines a top of the turbulent atmosphere , whose default value is set to 50 km above MSL. Above this altitude, all C_{n}^{2} values are set to zero exactly. The purpose of this restriction is to allow a simple numerical integration scheme for integrated turbulence quantities that is guaranteed to be good for arbitrary path geometries. If the user wishes, the top value can be changed by manually editing a configuration file.
Creation
of a completely customized (discrete) turbulence profile involves three key
steps:
(a) Select any standard profile name from the dropdown
list
(b) Specify the number of phase screens in the phase
screens input block
(c) Use the menu option View  Phase screen list to open a subsidiary
window that contains an editable table of phase
screen properties. This table can
be edited to specify an arbitrary discrete turbulence profile.
By clicking the arrowhead at the right of the Wind list field, the user obtains a dropdown list of windspeed vertical profile names. The named profiles have been collected from miscellaneous data sources. Of the named profiles, probably the only one that has any recognition in the general open literature is the Bufton model. The other profiles were generated from sitespecific measurements in connection with various Air Force research programs.
Since the wind is a vector quantity, and the user may not always be able to orient x or y along the wind direction, the GUI provides the option of applying two overall scale factors (for x and y) to the base wind speed that is generated by the profiles. Note that a selection from the profile list generates only a wind speed magnitude at any particular altitude. Depending on how the user wishes to orient the x and y axes, the two scale factors can be used to specify the appropriate projection of the profile wind magnitude in the x and y directions. That is, TurbTool will assign an Xvelocity component equal to (namedprofile speed)*(X scale factor), and a Yvelocity component equal to (namedprofile speed)*(Y scale factor).
Just as in the case of turbulence profiles, there is a Constant wind profile. The Constant profile returns a base value of 1 m/s everywhere. This base value can then be scaled with the two scale factors.
As in the case of the turbulence distribution, a completely custom (discrete) wind distribution may be defined by using the menu option View  Phase screen list to open a subsidiary window that contains an editable table of phase screen properties. Wind customization includes the possibility of creating a wind whose direction changes with position along the propagation path (note that this is not possible using the named profiles and X,Y scale factors).
TurbTool allows the user to specify profiles of atmospheric scattering and absorption coefficients, and of temperature. These profiles have no affect on the turbulence calculations in TurbTool. The scattering and absorption profiles do determine the optical transmissions reported in an output table. Additionally, the discrete values of scattering and absorption coefficients and of temperature that are stored in a TurbTool output file (if such file is requested) may later be used by a WaveTrain run set to specify thermal blooming parameters.
Scattering and absorption each include contributions from both molecular atmosphere and aerosol, with details determined by particular model selections and options. We separate total attenuation (sometimes called extinction) into scattering and absorption because these two components affect thermal blooming in different ways. The scattering and absorption coefficients, m_{X} , for a path segment (i.e., for a blooming screen), are related to the corresponding optical intensity transmission, t_{X} , by the formula
where X represents abs, scat, or net, m_{net} = m_{abs} + m_{scat} , Dz is the thickness of the path segment, and t_{X} is the optical transmission factor (0 £t_{X} £1) through the slab for the component X. The formula implies that m_{X} is treated as an average coefficient over the path segment.
TurbTool provides three types of profiles to quantify either scattering or absorption. The lefthand panel in the illustration below shows the profile type list pulled down for "Absorption":
The three types of profiles are AFRLDE Atmos Day , Log Scaling and Modtran/Fascode . There are several options available within the classes: these options are accessed and set by pressing the "..." button to the right of the profile field. The righthand panel of the illustration shows the options for the "Log Scaling" profile type.
AFRLDE Atmos Day: This profile, constructed by directedenergy (DE) researchers at the Air Force Research Lab, is defined for only two of the predefined wavelengths in the pulldown list of the wavelength input field: (a) the Nd:YAG wavelength 1.064mm, and the COIL (chemical oxygeniodine laser) wavelength 1.31521mm (select 1.315mm in the pulldown list). This profile class has no options.
Log Scaling: This profile allows the user to specify a simple exponential altitude dependence, with a single scale height, of the form
The values of A (units of 1/m) and B (units of m) are specified by the user after pressing the "..." option button, and h is the altitude above ground level. This profile class allows the user to specify a simple, generic coefficient profile at any wavelength.
Modtran/Fascode: The code suite comprising MODTRAN and FASCODE has been developed over decades at the Air Force Geophysics Laboratory (a unit of the Air Force Research Laboratory), and represents the state of the art in computer modeling of atmospheric transmission and radiance. TurbTool includes a fairly extensive set of lookup tables derived from MODTRAN/FASCODE runs, that allow scattering and absorption profiles to be obtained quickly. The output set of FASCODE is deficient in the sense that scattering and absorption coefficients are not provided directly, even though internally the code uses the separate values. Therefore, part of the effort in constructing the lookup tables was to use a special procedure that involved code runs of MODTRAN and FASCODE with several different input options, in order to obtain outputs that allowed the separation of total attenuation into absorption and scattering coefficients. The lookup tables cover altitudes below 50 km.
The limitation of the lookup tables is that they are only valid for predetermined wavelengths, namely those listed in the pulldown list of the wavelength input field, as shown at right. This list includes several important highpower laser wavelengths: 1.030 mm = Yb:YAG, 1.064 mm = Nd:YAG, 1.315 mm = close to but not exactly the COIL wavelength of 1.31521 mm, 2.700 mm = neighborhood of HF (hydrogenfluoride), 3.800 = neighborhood of DF (deuterium fluoride). Note that for purposes of thermal blooming in atmospheric propagation, only laser devices with high average total beam power are usually of interest. On the other hand, for purposes of simple transmission calculations, it would still be useful to treat arbitrary wavelengths. As explained in the discussion of the wavelength input field, the user has the option of requesting TurbTool to calculate new lookup tables at a custom wavelength. But, since that calculation can be timeconsuming, the user also has the option to turn off scattering and absorption at a custom wavelength.
Modtran/Fascode options can be specified by the user after selecting the profile and pressing the "..." option button. The options dialog box, shown at right, has four option fields: Atm(osphere) Type , Haze , Wind and Visibility . For full definitions of these options, the user must consult Modtran/Fascode documentation, but the general meaning should be fairly intuitive. Atm Type specifies the molecular atmosphere, and Haze specifies the aerosol. Wind and Visibility options will only be available for certain Haze selections.
As in the case of turbulence and wind distributions, completely custom scattering and absorption distributions may be defined by using the menu option View  Phase screen list to open a subsidiary window that contains an editable table of phase screen properties. The absorption and scattering coefficient values may be viewed in the table, or they may be plotted by using the menu command View  Scattering/Absorption Distribution .
The specification of temperature profile has no effect on any TurbTool calculations. The temperature profile is only used if TurbTool data is transferred to a WaveTrain runset that includes thermal blooming simulation.
Optical wavelength: To specify the optical wavelength, the user must initially pull down a dropdown list of options, by clicking on the arrowhead at the right of the wavelength list box. This list contains a discrete set of wavelengths, plus the option New . New allows the user to specify an arbitrary wavelength (like the 0.500 mm illustrated above), but there is a complication. The listed discrete wavelengths have internal, precomputed lookup tables of absorption and scattering profiles derived from MODTRAN/FASCODE, which allows for fast TurbTool computation. If New wavelength is selected, a further dialog box appears. This box asks whether the user wants TurbTool to compute a new lookup table of absorption and scattering (for the new wavelength):
Computation of a new table can be a timeconsuming operation, so we recommend to answer No unless the absorption and scattering coefficients will be needed for later WaveTrain thermal blooming calculations. Absorption and scattering coefficients have no effect on the turbulence calculations and turbulence screens generated by TurbTool. While the current TurbTool session is open, the new wavelength remains available in the dropdown list.
Rec(eiver) aperture diameter: This input parameter affects only one output item in the TurbTool screen, namely the Tyler tilttracking frequency, f_{T}, in the output table of integrated turbulence quantities.
TurbTool s phase screen definitions have two purposes. One purpose is to generate screen specifications that can later be transferred to WaveTrain for waveoptics simulation runs. A second purpose is to define screens that form the basis for the discrete integration method of generating integrated turbulence quantities.
The
phase screen specifications are based on the following principles:
(a) The input # Phase Screens
specifies the number of contiguous segments into which the propagation path is
divided. Each of these segments will be
represented by a phase screen.
(b) Two builtin options are provided for segment distribution:
(b1) If input Screen Distribution is set to Equal Distance , then the propagation
path is segmented into equallength segments.
(b2) If input Screen Distribution is set to Equal Strength , then the propagation
path is segmented so that each segment has the same integrated C_{n}^{2} value.
(c) Finally, three builtin options are provided for screen placement within
their respective path segments:
(c1) If input Screen Placement is set to Midpoint , then the screen positions
are the segment midpoints.
(c2) If input Screen Placement is set to Platform Side ,
then the screen positions are at the segment ends closest to the platform
(recall that platform simply means z=0
in TurbToolWaveTrain nomenclature).
(c3) If input Screen Placement is set to Target Side ,
then the screen positions are at the segment ends closest to the target (recall
that target simply means z=SlantRange
in TurbToolWaveTrain nomenclature).
The screens plot located immediately above the phase screens input block graphically reflects all the specifications discussed in the previous paragraph. The following figure shows two examples:
The path geometry for each example is the default geometry upon opening TurbTool, the turbulence profile is HV5/7, and # Phase Screens is set to 10. In the lefthand example, Screen Distribution is set to Equal Distance , and Screen Placement is set to Platform Side . The red horizontal bars indicate the path segments, and the height of these bars relative to the rightaxis scale give the segmentaverage C_{n}^{2} value. The blue vertical bars show the screen zcoordinates. In the righthand example, Screen Distribution is set to Equal Strength , and Screen Placement is set to Midpoint . In this case, the segmentintegrated C_{n}^{2} value is, by construction, the same for all the screens.
In all cases, the segmentaverage C_{n}^{2} value is the segmentintegrated value divided by the segment length. Notice that this method of defining the screen strengths gives the discrete screen representation exactly the same totalpathintegrated C_{n}^{2} value as the continuum profile. This will be true no matter what location is specified for the screens within the segments. Therefore, at least the most fundamental pathintegrated turbulence quantity, the simple integral of C_{n}^{2}, is faithfully represented by the discrete screen numerical model.
The
final pair of screen input options, which are grayed out in the illustration at
right, allow the user to define screens for a restricted subinterval within
the propagation path interval. That is,
if the user clicks the check boxes to activate these fields, and then enters
numbers such that
0 < (Begin turb at SR) < (End
turb at SR) < SlantRange
then only the restricted interval will be segmented, and screens will be
constructed for only those segments. However,
the optical propagation path is still defined to start at z=0 and end at
z=SlantRange: this latter fact
impacts the calculation of the integrated
turbulence quantities.
The final input in the screens input block, Integration method , controls the method of calculation for results that appear in the output table of integrated turbulence quantities. TurbTool provides two choices of integration method, Continuous and Discrete . The significance of the integration method is discussed in the document section on integrated turbulence quantities.
Given
the current propagation geometry, turbulence and wind profiles, wavelength and
receiver diameter, and possibly the discrete screen specifications, TurbTool
automatically calculates five key measures of the effects of turbulence. These are
(a) Fried s wave coherence length, r_{0}
(b) Isoplanatic angle, q _{0}
(c) Normalized irradiance variance (NIV; sometimes called scintillation
index)
(d) Greenwood frequency, f_{G}
(e) Tyler tilttracking frequency, f_{T}
The values of these five quantities are reported in the output table of
integrated turbulence quantities, illustrated at right. The calculations are done for four cases:
(1) Planewave source, receiver at Platform (z = 0)
(2) Planewave source, receiver at Target (z = SlantRange)
(3) Sphericalwave source, receiver at Platform (z = 0)
(4) Sphericalwave source, receiver at Target (z = SlantRange)
The main restriction on validity of these results is that all are obtained from formulas derived using Rytov or geometrictheory approximations. So, generally speaking, the results are only valid for weak to intermediate levels of integrated turbulence. The Greenwood and Tylerfrequency formulas contain some additional approximations, which can result in significant deviations (say a factor of 2 or more) in practical cases of interest. The formulas that define the TurbTool integrated turbulence quantities are listed in a later section of the Guide. Because of the validity restrictions, corresponding results from a WaveTrain simulation run should not always match the TurbTool results. However, the TurbTool table can quickly provide a valuable guideline as to what to expect, and can indicate the turbulence regime in which the user is operating.
The fundamental integrated turbulence formulas all have the general form
where A is a factor that may depend on wavelength, L is the slant range, z is the slant coordinate along the propagation path, w(z) is a path weighting function, C_{n}^{2} and v(z) are the turbulencestrength and pseudowind profiles, and p is a constant exponent.
In the phase screens input block, the user selects Integration method = Continuous or Discrete . Integration method = Continuous means that Q is evaluated by numerical integration on a dense mesh, such that a close approximation is obtained to the continuumspace integral. In this case, the specifications of the discrete phase screens have no effect on the computation of Q.
Integration method = Discrete means that Q is evaluated using the discrete screen positions and screen C_{n}^{2} values, according to the formula
where z_{k} are the screen positions, and Dz_{k} are the segment lengths (sometimes called screen thicknesses ). Generally, Q_{discrete} is not equal to Q. The one exception is the plain integrated C_{n}^{2}, because the screen C_{n,k}^{2} values (i.e., the segmentaverage C_{n}^{2}) were explicitly constructed to preserve this equality. Unfortunately, the equality between Q_{discrete} and Q can only be preserved for one weighting function, and we have chosen the unit weight function. Q_{discrete} does corresponds exactly to replacing the continuum profile by a comblike profile whose component delta functions have strengths (C_{n,k}^{2} * Dz_{k}). Therefore, within the limits of a Rytov formula, a waveoptics simulation result should give exactly Q_{discrete}. In this sense, TurbTool can be used to investigate the effects of the discrete screen model on key integrated turbulence quantities, without doing any waveoptics simulation runs. Specifically, one could investigate the effects of different segmentation choices (number of screens and distribution), and different placement of the screens within the segments.
We have mentioned previously that TurbTool defines a top of the turbulent atmosphere by cutting off (setting to exactly 0) all C_{n}^{2} profiles at altitudes higher than 50 km above MSL. (The user can change this boundary value by modifying a configuration file.) Some named profiles may already be defined as strictly zero for lower altitudes than 50 km, but that is dependent on the particular profile definition. The general topofturbulentatmosphere cutoff that we are discussing now is additionally imposed on all profiles, and has the following motivation and consequences.
Despite the turbulence cutoff, propagation paths are allowed to have arbitrary portions above the turbulence cutoff (see the example in plot panel (B) in a previous section). The motivation for the cutoff is as follows. Given arbitrary possible path segments where turbulence is negligible, and given turbulence profiles that can change over several orders of magnitude along the propagation path, it is difficult for a single generalpurpose numerical integration routine to guarantee acceptable accuracy for all possible situations. However, by defining a limited region that can contribute to any Q integral, we can use a simple but completely robust integration method (Simpson rule with a fixed, small step size) to guarantee good accuracy, say at least two significant figures, no matter how long the total propagation path is. The preceding discussion applies specifically to the calculation of the table of integrated turbulence quantities by the Continuous integration method.
The other implication of defining a top of the turbulent atmosphere concerns phase screen generation. If a propagation path has portions (one or two) above the top of the turbulent atmosphere, then only the path interval that lies below the top of the atmosphere will be segmented and have phase screens assigned. This will be evident when inspecting the plot of screen strengths and positions. In a previous section, the example in plot panel (B) defined a path with platform (z = 0) far above the top of the turbulent atmosphere, and then we specified # Phase Screens = 10, Screen Distribution = Equal Distance , and Screen Placement = Platform Side . The resulting screen layout is shown in the plot at right. It is clear that TurbTool has assigned all screens to a subinterval of the full propagation path.
Note that if C_{n}^{2} is set to strictly zero in a subinterval to allow the restriction of the numerical integration domain of Q, the zeroturbulence subinterval still affects some integrated turbulence quantities because the path weighting function in Q is cognizant of the propagation endpoints.
Min Path Alt above Ground : For the specified ground altitude and propagation path geometry, this output field shows the minimum altitude above ground level along the propagation path. Recall that TurbTool assumes a sphericalearth geometry, and that the ground altitude is uniform under the entire propagation path. This output field is located just above the table of integrated turbulence quantities.
Status : This output block, located at the bottom of the main GUI window, displays miscellaneous error and status messages.
Info : This output block, located at the bottom of the main GUI window, displays miscellaneous informational messages. For example, the Info block displays the model ground altitudes associated with standard turbulence profiles.
Optical transmission factors, t_{X}_{ }: optical transmission factors (0 £t £1) for the full propagation path, as determined from the screen absorption and scattering coefficients and segment lengths (screen thicknesses). t_{scat}_{ } is the transmission due to atmospheric scattering alone, t_{abs} is the transmission due to atmospheric absorption alone, and t_{net}_{ } is the net transmission. In each case, molecular and aerosol contributions are present, corresponding to the models discussed in the section on scattering and absorption profiles. These profiles will determine the thermal blooming if the atmospheric description is later used for a WaveTrain simulation run that invokes blooming. If absorption and scattering profiles have been disabled for a New wavelength, the transmission results are also disabled. The absorption and scattering settings have no effect on TurbTool s turbulence calculations.
The main TurbTool GUI window offers four pulldown menus. Help  Online help opens the present document. Key functions on the other menus are as follows.
The two key functions are:
Save as : This creates a file (in *.mat Matlab format) containing data that can be read by one of WaveTrain s AcsAtmSpec "constructors" to specify the turbulent atmosphere for a WaveTrain system and runset. Specifications that can be transferred in this way include the screen positions, segment thicknesses and C_{n}^{2} values, the truewind speeds associated with each screen, and the inner and outer scale values. In brief, all the discrete data that appears in the Phase Screens Table can be transferred as a unit in this way from TurbTool to WaveTrain.
REMARKS ON DATA TRANSFER FROM TurbTool TO WAVETRAIN:
To accomplish the data transfer using TurbTool's save file, the AcsAtmSpec constructor syntax needed in the WaveTrain run set is "AcsAtmSpec(filename, Cn2factor)", where "filename" is the *.mat file created by TurbTool, and "Cn2factor" is yet another overall multiplier that may be applied within WaveTrain. See the WaveTrain User Guide for further details on AcsAtmSpec usage.
As an alternative to the data file transfer procedure, users may prefer to manually copy TurbToolgenerated data into AcsAtmSpec in a WaveTrain run set. This would involve the use of other allowed forms of the AcsAtmSpec constructor arguments, where various vectors such as screen positions and C_{n}^{2} values are explicitly entered. While the manual procedure may involve a little more labor, some users may find that it provides a greater sense of user control and later readability of the runset. In any case, this is the most flexible way of using TurbToolgenerated data as WaveTrain input.
CAUTION: there is one limitation on the completeness with which atmospheric specification data can be transferred from TurbTool to WaveTrain: the TurbTool platform and target velocities are not readable by WaveTrain. This situation exists because these velocity specifications are not part of WaveTrain s atmospheric modules, but rather are specified separately in WaveTrain by using TransverseVelocity modules. The practical significance of this is that the user who wishes to transfer TurbTool specifications to a WaveTrain runset must manually enter the appropriate platform and target velocity specifications in WaveTrain's TransverseVelocity modules. (In contrast to this, values of the true atmospheric wind, specified via the wind profile options, are attached directly to the phase screens specifications, and these truewind velocities will automatically be transferred to the WaveTrain atmospheric blocks when the constructor syntax "AcsAtmSpec(filename,Cn2factor)" is used.)
If the user wishes to transfer TurbTool savefile data into a WaveTrain system that includes thermal blooming, then WaveTrain's MtbAtmSpec constructor must be used. The extra relevant data now consists of the discrete absorption, scattering and temperature profiles. To accomplish the data transfer, the required constructor syntax in WaveTrain is "MtbAtmSpec(filename, propnxy, propdxy)", where "filename" is the *.mat file created by TurbTool, and "propnxy" and "propdxy" are the propagation mesh dimension and physical spacing. See the WaveTrain User Guide for further details on MtbAtmSpec usage.
Load : This allows the TurbTool user to load back into TurbTool a *.mat file that was previously saved using the "Save as " option.
The View menu provides several types of functions.
View  Phase Screen List brings up a subsidiary window that contains an editable table of phase screen properties.
View  Xxx Distribution creates a new plot window showing one of the following discrete distributions: absorption, scattering, turbulence, or temperature. In the case of turbulence, this plot is identical to the Screen Strength plot that appears on the main GUI screen. The only difference is that the View generated window is a separate, editable Matlab plot window. Users may find this convenient for further work or documentation purposes.
View  Turbulence Profile
creates a new plot window showing the continuous turbulence profile that was
selected in the mainscreen input block entitled Profiles
. The overall strength scale factor specified
by the user is included in the plotted profile.
The phase screens whose strengths are plotted in the Screen Strength plot are
derived from this underlying continuous profile and the specified path
segmentation, as defined elsewhere. The new plot window is an editable Matlab
plot window.
View  Wind Profile creates a new plot window showing the continuous wind profile that was selected in the mainscreen input block entitled Profiles . The plotted wind profile is the magnitude of the wind speed, including the overall x and y scale factors specified by the user. The profile shows only the true atmospheric wind, not the pseudowind that includes target and platform velocity effects.
View  Engagement Layout creates a new plot window showing the same engagement geometry plot that appears on the main GUI screen. The only difference is that the View generated window is a separate, editable Matlab plot window. Users may find this convenient for further work or documentation purposes.
The options in the Tools menu allow the user to return certain data structures to the Matlab workspace from which TurbTool was opened. The data in question is thus made available for further custom manipulation by the user.
Make ATMStruc : Stores the TurbTooldefined data in a Matlab structure that has the form of the ATMStruc data structure used in a separate code suite called ATMTools. The purpose of this option is to facilitate future interoperability or merger of TurbTool and ATMTools.
Make TurbTool Struc : Stores the TurbTooldefined data in a Matlab data structure native to TurbTool.
A table that lists all details of the phase screens can be opened by the menu action View  Phase Screen List . A sample table, for a case where # Phase Screens = 5, is shown below. This table lists all parameters of the phase screens that were defined in the main GUI window, and also contains some extra parameters that are not settable from the main window. Some columns of this table are editable, thereby allowing the user to define a completely custom set of phase screens.
The table contains one row for every propagation path segment, or equivalently for every screen. Each column refers to a different property of that segment or screen. The principles used in the path segmentation and screen generation were discussed in a previous section. Physical units are specified in the table header for all quantities.
A subset of the table columns are editable. When manual edits are entered into the table, dependent table columns update immediately. An exception to the immediateupdate rule occurs if the user enters some temporarily inconsistent data (such as overlapping segment boundaries) in the course of making more extensive changes. In that case a status warning appears until the user enters further edits that make the table numbers consistent again. Upon returning to the main TurbTool window, other updates may occur in the main window settings and outputs.
To begin editing a field, doubleclick in the desired field. The following columns in the table are editable:
Seg. Start, Seg. End, and Z: These are, respectively, the start and end z coordinates of the path segments, and the z coordinates of the screen locations.
AvgCn2: Segmentaverage C_{n}^{2} value. Manually editing this column, and the preceding coordinates columns, allows the user to specify a completely custom turbulence profile.
Vx, Vy: Wind velocity components assigned to screens. Note that this refers only to the true
atmospheric wind, not the effective (or pseudo) wind that includes the
platform and target velocities. The
velocity values assigned to a screen are the average values of the continuous
wind profile over the propagation segment corresponding to the screen. This is consistent with the manner in which
the screenC_{n}^{2} (AvgCn2
in the table) is defined.
l0, L0: Inner scale and outer scale lengths associated with the screens. These settings have no effect within TurbTool: the formulas used to compute integrated turbulence quantities within TurbTool all assume the default values of zero inner scale and infinite outer scale. However, if finite inner and outer scale values are transferred to WaveTrain, the screengenerator routines in WaveTrain do respond to these specifications.
Abs, Sct: Atmospheric absorption and scattering coefficients, m. These coefficients determine the optical transmission factors listed in the main GUI window. The key relation is that intensity transmission for a single segment k is given by
where X represents abs, scat, or net, and where m_{net} = m_{abs} + m_{scat}.
Temp: Atmospheric temperature distribution along the propagation path. This is not used by any TurbTool calculations. If the data is transferred to WaveTrain, the temperature distribution is used in setting up thermal blooming screens, if the WaveTrain model invokes thermal blooming.
dZ: Length of segment (referred to sometimes as the thickness of the phase screen)
h: Height above mean sea level corresponding to Z of screen
òCn2: Pathintegrated C_{n}^{2} for segment. Upon opening the table, this is the segmentintegrated C_{n}^{2} value obtained from the continuous profile that was specified in the Profiles block of the main TurbTool window. But, if a manual edit is made in the AvgCn2 column of the table, then òCn2 is simply reset to AvgCn2*DZ.
r0: In the mechanics of generating phase screen realizations for waveoptics simulation, screen strengths are often specified in terms of a screen r0 , instead of by the equivalent (AvgCn2, dZ) or òCn2. The r0 in question is a planewave r0 for propagation through the path segment modeled by the screen.
The main TurbTool window is locked while the Phase Screens Details table is open. To return to the main window, the user has the two table options Cancel and OK .
Pressing Cancel will cancel any edits that were made in the table, and return the user to the main TurbTool window in the same state as before the Phase Screens table was opened.
Pressing OK will return the user to the
main TurbTool window, and may cause several changes to occur in the main
window outputs and settings. The
changes in the main window are as follows:
(a) If the user edits the fields Seg.
Start , Seg. End ,
or Z , then Screen Distribution and Screen
Placement are changed to User
Spec .
(b) If the user edits the field AvgCn2
, then the field Integration Method
is changed to Discrete , since
the previously selected continuous C_{n}^{2} profile is no longer meaningful.
(c) If the user edits the field "AvgCn2",
then the Turbulence Profile
selection is changed to "User Spec",
since the previously selected continuous C_{n}^{2}
profile is no longer meaningful.
(d) In analogy with rule (c), if the user edits the fields "Vx", "Vy", "Abs", "Sct", or "Temp", then the corresponding Profile selections are changed to
"User Spec".
Pressing OK in the Phase screens table will also cause values in the output table of integrated turbulence quantities to update in accordance with any of the changes described just above.
TurbTool uses a short configuration file to establish a few basic numerical settings. The file is named GetConstants.m , and is located in the toplevel TurbTool directory. In normal operation, the user does not interact directly with this file. However, at some point the user might wish to manually edit this file (using any text editor) to adjust certain settings. As an example, the user may want to adjust the top of turbulent atmosphere setting to something other than the default 50 km AMSL altitude.
The formulas encoded in TurbTool are derived using Rytov or
geometrictheory approximations to turbulent propagation. So, generally speaking, the results are only
valid for weak to intermediate levels of integrated turbulence. The Greenwood and Tylerfrequency formulas
contain some additional approximations regarding system bandwidths, which can
result in significant deviations (say a factor of 2 or more) in practical cases
of interest. Because of these validity
restrictions, corresponding results from a WaveTrain simulation run should not
always match the TurbTool results.
The formulas in this section assume a coordinate system where the zaxis is the nominal propagation direction, the source plane is at z = 0, the receiver plane is at z = L, and the turbulence profile is given by C_{n}^{2}(z). There are two canonical cases for which analytical results are commonly given, the sphericalwave case and the planewave case. The sphericalwave formulas apply when z = 0 designates the position of a point source. The planewave formulas apply when we assume that a plane wave is the initial condition at z = 0. Note that in the sphericalwave case, a particular choice of C_{n}^{2}(z) may place the point source far outside the region of non0 turbulence: in that case the sphericalwave numerical results will approach the planewave results.
CAUTION: Integrated turbulence
quantities reported in the output table
are the results of highdensity numerical integration of the formulas below, IF
AND ONLY IF the GUI option Integration
method = Continuous is
selected. If the GUI option Integration method = Discrete is selected, then a coarser
sum is computed based on the phase screen positions and screenC_{n}^{2} values that have been defined. This distinction was previously discussed in the section on integration methods.
Fried s wave coherence length:
The transverse coherence length r_{0} is a measure of how far apart two points must be (transverse to the propagation direction) before the rms wavefront difference due to turbulence exceeds a critical value. The results reported by TurbTool are as follows:
Planewave case:
Sphericalwave case:
Normalized irradiance variance (NIV):
If I is the irradiance (W/m^{2}) at a point, then the usual measure of turbulent irradiance fluctuation is the normalized irradiance variance (NIV). NIV is the variance of I at a point divided by the square of the mean I at that point. Equivalently, if we consider the normalized irradiance J = I /(mean I) , then NIV is simply the variance of J. In the lowestorder Rytov approximation, theoretical results are actually obtained for a closelyrelated quantity, namely the variance of the logamplitude, often denoted by s _{c}^{2} in theoretical references. For weak to moderate turbulence, i.e., prior to the onset of saturation, the relation NIV = 4 s _{ c}^{2} is a good approximation. Using this approximation, the firstorder Rytov results reported by TurbTool are as follows:
Planewave case:
Sphericalwave case:
Isoplanatic angle:
The formula for isoplanatic angle q_{ 0} is the same for plane and sphericalwave cases:
(Note: as stated in the introductory paragraphs, the directional conventions for these formulas are that the source plane is at z = 0 and the receiver plane is at z = L. That is, the vertex of the isoplanatic angle referred to by the formula is at z = L.)
Greenwood and
Tyler frequencies:
The Greenwood and Tyler frequencies, f_{G} and f_{T} respectively, refer to feedback control system bandwidths required to achieve a certain performance level in rejecting atmospheric disturbances. The Greenwood frequency refers to a composite of all disturbance spatial frequencies, while the Tyler frequency refers to the tilt component only. The same formulas hold for plane and sphericalwave cases:
where is the magnitude of the effective or pseudowind transverse velocity at coordinate z. The vector pseudowind velocity may have arbitrary x and y components, but only the magnitude enters into the Greenwood and Tyler frequencies.
where D is the receiver aperture diameter over which the tilt is defined, and is again the magnitude of the effective or pseudowind transverse velocity at coordinate z .
Some users may find it useful to independently use the TurbTool subroutines that compute the standard vertical profiles of C_{n}^{2}. This would be easy to do, since each subroutine is a separate Matlab mfile. The routines are located in the subdirectory \turb under the main TurbTool directory. The routine names all have the form tp*.m : for example, the Clear1 turbulence vertical profile is defined by "tpCL1N.m". Each file consists of a wrapper routine and a subroutine that actually defines the standard C_{n}^{2} profile. Among other things, the wrapper routine handles the groundaltitude adjustment. The routines are sufficiently documented (and short enough) that any Matlab user will easily be able to run them independently.
TurbTool is a Matlab GUI application that consists of a suite of Matlab mfiles. To assist in potential future modifications and extensions of TurbTool, we provide a flowchart that shows the calling relationships among the key computational routines of the TurbTool code suite. The graphical elements of the GUI are constructed using the Matlab GUIDE environment.
For
development comments and questions, contact:
Boris Venet MZA Associates
Corp. 5052459970 venet@mza.com
Morris Maynard MZA Associates Corp. 9376844100 morris@mza.com