Copyright © 1995-2010 MZA Associates Corporation
This document summarizes a few aspects of the creation and use of atmospheric turbulence and thermal blooming models in WaveTrain. This document essentially duplicates several sections of the WaveTrain User Guide, in particular sections relating to turbulence specification and thermal blooming specifications. Users should refer to the comprehensive User Guide for the latest and most complete treatment. The present document is being preserved for the time being, for reasons of continuity, but will no longer be updated after Jan 2010.
Setup of a WaveTrain simulation usually involves the specification of an atmospheric turbulence profile and the reduction of that profile to a set of discrete phase screens. Also, prior to performing a wave-optics simulation, it is generally desirable to estimate various integrated turbulence and performance measures from approximate closed-form formulas. The WaveTrain code suite contains two helper applications that can assist users with the above issues and others. These helper applications are Matlab programs, whose graphical user interfaces (GUIs) must be started at a Matlab prompt (i.e., outside of WaveTrain). In WaveTrain versions 2009A and earlier, there was one helper application, called TurbTool. In WaveTrain version 2010A, there are two separate applications, called TurbTool and PropConfig, respectively. In future WaveTrain versions, TurbTool will be phased out in favor of PropConfig. PropConfig is a reworked version of Turbtool, which can do essentially everything that TurbTool does, and also has significant additional capabilities. MZA will continue to support TurbTool for the present, for the benefit of existing users. However, new users should learn PropConfig, and ignore TurbTool.
Turbtool and PropConfig can be used completely independently of WaveTrain (e.g., to simply compute integrated-turbulence quantities), or they can be used additionally to generate input vectors for the WaveTrain AcsAtmSpec function.
AcsAtmSpec is the function used in "setting expressions", in the WaveTrain Run Set Editor or System Editor, for the purpose of inputting atmospheric path turbulence specifications. Required inputs for the various allowed argument forms of AcsAtmSpec can be generated independently by the user. However, many users will find the preliminary exercise of TurbTool or PropConfig to be helpful in generating the required input arguments, and more generally in scoping out the propagation problem of interest. In sum, use of AcsAtmSpec is mandatory for any WaveTrain simulation involving atmospheric turbulence; use of TurbTool or PropConfig is optional but very likely helpful. The key issue in usage of AcsAtmSpec is understanding the many options one has in specifying the function's input arguments. The usage instructions contained in the present document duplicate the material on AcsAtmSpec contained in the overall WaveTrain User's Guide.
MtbAtmSpec is the function used in WaveTrain Run Set Editor or System Editor "setting expressions" for the purpose of inputting atmospheric thermal blooming specifications. As in the case of AcsAtmSpec, preliminary exercise of TurbTool or PropConfig can be helpful in generating the required input arguments.
TurbTool is a Matlab GUI application that complements the WaveTrain wave-optics 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 wave-optics 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 phase-screen 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 wave-optics simulation results. However, note that the integrated-turbulence formulas evaluated by TurbTool are either Rytov- or geometric-theory 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 Cn2 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 TurbTool-generated 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� Cn2 profiles (Clear-1, HV5/7, etc.) and wind profiles used by the community.
(2) Computation of effective, i.e. segment-average, Cn2 values to be associated with discrete screens.
(3) Several standard options for generating path segmentation to define phase screen strengths, and for positioning 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 �split-step� or �lumped-parameter� modeling of atmospheric propagation that is used in wave-optics simulation.
(6) Ability to define completely user-specified discrete profiles.
Further details of TurbTool capabilities and usage instructions are given in the WaveTrain User Guide and the TurbTool User Guide.
As noted in the introduction, PropConfig is intended to be a replacement for TurbTool. PropConfig is a reworked version of Turbtool, which can do essentially everything that TurbTool does, and also has significant additional capabilities. Further details of PropConfig capabilities and usage instructions are given in the WaveTrain User Guide and the PropConfig Tutorial.
To enter turbulence specifications into a WaveTrain simulation, one uses the AcsAtmSpec function in "setting expressions" in AtmoPath or GeneralAtmosphere. Th mechanism is illustrated in more detail in relevant sections of the WaveTrain User Guide. AcsAtmSpec has many different allowed sets of arguments. (At the C++ code level, these options are referred to as different "constructors" or initialization functions.) The following table documents several of the most useful syntax options. From time to time, new options are added by WaveTrain programmers to handle new special cases that are judged convenient or necessary. The more experienced and bold WaveTrain user may benefit from inspecting the source code file that contains all the options. After some of the cases documented below have been digested, the user can probably understand the multitudinous other allowed formats by inspecting the argument lists in the referenced source code file.
General rules
There are some general rules that apply to all argument list options (or at least to all cases where the item appears):
(1) In the table below, the data types of the arguments are prefixed to the arguments. The purpose of doing this in the table is just to clarify whether the arguments are scalars or vectors: when the user actually enters the setting expression in WaveTrain, the data type designators should be omitted.
(2) Argument lambda
refers to a reference wavelength.
CAUTION: the wavelength in question here may be, but is not necessarily, the
wavelength of the propagating beam. In the listed syntax options where it
appears, lambda is the
reference wavelength at which the r0s of the screens are defined.
The effective r0 of a screen will then depend on the propagating wavelength, but
we want to define the screens only once, at some reference wavelength.
(3) Argument pathLength refers to the total propagation range from platform end to target end of the atmospheric module. Note that screens are not necessarily located at the endpoints, so pathLength is frequently greater than the distance between first and last screens.
(4) The position (z) coordinates of screens, are defined with respect to WaveTrain's z-coordinate conventions. The key facts are that z=0 is the platform end and z=L(propagation range) is the target end of the atmospheric propagation module into which AcsAtmSpec is inserted.
(5) Arguments that specify inner and outer scales, screen
velocities, and screen transmissions have obvious default values. The
defaults are: inner scale = 0.0, outer scale = infinity, velocities
= 0.0, and transmissions = 1.0.
To obtain the default values, the user should simply omit these arguments from
the setting expression. BUT, note that only a contiguous set of trailing arguments in a list may be
omitted.
"Transmission" here implies intensity transmission to be associated with
that screen or subinterval. For most WaveTrain work, the screen
transmission options are not used, because the library also provides overall
transmission-factor modules.
(6) Some syntax options have height specifications, usually encoded as hPlatform and hTarget. In these cases the user can specify the turbulence strength in terms of a named turbulence profile, such as Clear-1, Clear-2, or HV57. In these cases, h should be interpreted as height above mean sea level (AMSL), because the named Cn2 profile options such as "Clear-1" have their Cn2(h) functional forms defined in terms of height AMSL. Additionally, when using the named profiles, the user must understand that the Clear-1 and Clear-2 profile functions are only defined for h ≥ 1230 m AMSL, where that height represents (approximately) the ground level altitude at the site where Clear-X data was collected. If the user wishes to apply Clear-X to a physical problem where the ground altitude is different, then a reasonable approach would be to enter h_AMSL values into WaveTrain such that the altitude above ground level is preserved between the physical problem and the simulation specs.
(7) Particularly in the case of vector arguments, the user
will find it most convenient to enter symbolic names for the arguments, elevate
the arguments up the system hierarchy, and
assign values to the vectors at that
top level (i.e., in the Run Set Editor).
Actually, this holds for most scalar arguments as well: the atmospheric
specifications in general are quantities that we often wish to vary when
exploring performance, so it is best to elevate those quantities to the Run Set
level before assigning numerical values.
(8) As elsewhere in WaveTrain, physical units are MKS, unless explicitly specified otherwise.
| Usage Case | Setting Expression for atmoSpec | |
| 1 | General screen positions and strengths, with strengths expressed as screen-r0 values |
AcsAtmSpec(float lambda, float pathLength, Vector<float> positions, Vector<float> screenr0s, Vector<float> vxs, Vector<float> vys, Vector<float> l0is, Vector<float> l0os, Vector<float> transmissions) *************** Notes: positions = z-coordinates of the screens. vxs, vys = x,y velocity components of screens. l0is = inner scales; l0os = outer scales. Default values for transmissions are 1.0. |
| 2 | General screen positions and strengths, with strengths expressed as screen-Cn2 values |
AcsAtmSpec(float lambda, Vector<float> positions, Vector<float> screenCn2s, Vector<float> thicknesses, float pathLength, float l0i, float l0o, float vX, float vY) *************** Notes: screenCn2s are the effective Cn2 discussed above, thicknesses are the subinterval widths associated with them, and positions are the z-coordinates of the screens. In contrast to the previous syntax option, the inner/outer scale and screen velocities, if used, must be the same for all screens. |
| 3 | Named Cn2 profile, with uniformly-spaced screens |
AcsAtmSpec(int profileNumber, float lambda, int nScreens, float turbFactor, float hPlatform, float hTarget, float pathLength, float l0i, float l0o, float vX, float vY) *************** Notes: profileNumber: 1 Clear-1; 2� Clear-2; 3� HV57. The first screen is placed at z=0, the screen spacing is dz=pathLength/nScreens, and the last screen is at z=(pathLength - dz). turbFactor is an arbitrary uniform multiplier that may be applied to the profile Cn2 strength. CAUTION (see item (6) in the General Rules
above): Clear-1 and -2 profile functions are only defined for h≥1230m,
where that number is approximately the ground altitude above mean sea level
at the geographic site where Clear-X data was collected. |
| 4 | Scaled Clear-1 profile, with uniformly-spaced screens |
AcsAtmSpec(float lambda, int nScreens, float clear1Factor, float hPlatform, float hTarget, float pathLength, float l0i, float l0o, float vx, float vy) *************** Notes: essentially same as previous syntax option 3, but restricted to only the Clear-1 profile, scaled by the uniform multiplier clear1Factor. CAUTION (see item (6) in the General Rules above): The Clear-1 profile function is only defined for h≥1230m, where that number is approximately the ground altitude above mean sea level at the geographic site where Clear-1 data was collected. |
| 5 | Read turbulence parameters from a file (e.g., used with TurbTool) |
AcsAtmSpec(char* filename, float Cn2factor) *************** Notes: This syntax is primarily meant for loading turbulence data generated by TurbTool, which is a WaveTrain helper application. However, the user could also independently generate data files with the right content and read those. TurbTool is a Matlab GUI application, and generates *.mat () files. |
MtbAtmSpec is the function used in WaveTrain Run Set Editor or System Editor "setting expressions" for the purpose of inputting atmospheric path thermal blooming specifications. When thermal blooming is to be included in the propagation simulation, the MtbAtmSpec function is used in addition to the AcsAtmSpec function (the latter is still used to specify the turbulence parameters). For further details, see the relevant sections of the WaveTrain User Guide.