This User Guide is designed to serve as a tutorial introduction to WaveTrain for new users, and a reference for more experienced users.  The User Guide attempts to be as comprehensive as possible in documenting the scope, usage rules, and assumptions of the WaveTrain code.  In doing so, we may occasionally digress into short tutorials on topics in optical propagation theory and adaptive optics, but for detailed theory background we refer the reader to the standard literature.  WaveTrain is a complex code, and its pieces have been constructed and assembled by numerous contributors at MZA Associates (and some contributors elsewhere).  Generation of documentation is an ongoing effort, and the elements of WaveTrain are not all documented at the same level of detail.  When users have questions regarding WaveTrain, we ask them to proceed as follows.  First, search the present User Guide, the MZA web-site update material, the index to all WaveTrain documents, and the individual module documentation in the WaveTrain Components and Effects Library.  If this fails to resolve the question, feel free to contact MZA by email or phone.

WaveTrain is built atop tempus, a general-purpose simulation tool also created by MZA Associates.  tempus provides the visual programming environment, the software architecture, and all the basic mechanisms that support model-building and simulation.  WaveTrain adds a component library for modeling optical systems and effects, and several application-specific GUI components.  The latter comprise a tool for setting up wavefront sensor and deformable mirror geometries, a tool for specifying turbulence distribution along an optical propagation path, and a tool for setting up and executing parameter studies.  The GUI tool for wavefront-sensor and DM configuration also has associated Matlab routines for a variety of AO tasks, such as computing reconstructor matrices.  The GUI tool for specifying turbulence distributions also performs a variety of useful calculations of integrated turbulence quantities based on theoretical formulas; these can be used as a starting point for initially estimating or bounding answers to be obtained from the wave-optics simulation. 

Guide to the User Guide

To get a quick idea of what WaveTrain can do and how one can use it, start with our quick tour (this should take less than 10 minutes). 

For a more detailed introduction (a few hours), work through one or more of our step-by-step tutorials, particularly the Guide section on Assembling and running a WaveTrain model - Tutorial.  After these introductory exercises, there will undoubtedly still be many details that are fuzzy to the new user.  We suggest that the best procedure at that point is:
(a)  skim the rest of this User Guide to get a sense of the organization and contents;
(b)  attempt construction of original simple systems, based on what you have learned from the "Assembling" section and auxiliary tutorials;
(c)  as conceptual and procedural questions then arise, dive into the remaining detailed documentation chapters of this User Guide as needed.

By way of preview, we mention the following details chapters:
(*)  For physics-oriented issues and usage details regarding important specific WaveTrain library systems, users should consult the chapter Modeling details.
(*)  For details regarding data entry in the two editor windows, users should consult the chapter Data entry in subsystem parameters and inputs, and in the Run Set Editor.
(*)  For details regarding TrfView, trf files (recorded outputs) and the extraction of trf data, users should consult the chapter Inspecting and post-processing WaveTrain output:  *.trf files, TrfView, and Matlab.
(*)  For details regarding the construction of user-defined WaveTrain subsystems, users should consult the chapter Creating user-defined WaveTrain components.

WaveTrain documentation and updates on the Web

Improvement of the WaveTrain documentation is an ongoing project.  For the most recent version of the WaveTrain User Guide and allied documentation, the user should refer to MZA's web site:
http://www.mza.com/Default.aspx#productstab-wtdocs, then click on "WaveTrain User Guide" under the Index. 
Here the user will always find the most recent version of the User Guide, as well as material that has not yet found its way into the general Guide.  The latter material may include auxiliary documentation on special topics, extra tutorials not accessible through the User Guide, and WaveTrain bug notes, discussions, and patches. 

In addition, some auxiliary documentation relevant to WaveTrain may be found under the "tempus" heading at MZA's web site: for a list of those documents, see:
http://www.mza.com/Default.aspx#productstab-tempus.

Index to all WaveTrain Documents

Index to all tempus Documents

General references

J. Goodman, Statistical Optics, Ch. 8, Wiley-Interscience, 1985

V. Tatarski, Wave Propagation in a Turbulent Medium, McGraw-Hill, New York, 1961

A. Ishimaru, Wave Propagation and Scattering in Random Media, Chs. 16-20, IEEE Press/Oxford U. Press, reissued 1997 (original pub. Academic Press, 1978)

R. Tyson, Principles of Adaptive Optics, Academic Press, New York, 1991

M.C. Roggeman and B. Welsh, Imaging through Turbulence, CRC Press, 1996.

J. Hardy, Adaptive Optics for Astronomical Telescopes, Oxford University Press, 1998

L. C. Andrews and R.L. Phillips,  Laser Beam Propagation through Random Media, SPIE Optical Engineering Press, 1998.

R.E. Hufnagel, "Propagation through Atmospheric Turbulence", in The Infrared Handbook, Ch. 6, Environmental Research Institute of Michigan and Office of Naval Research, rev. ed.,  1985. 

R.R. Beland, "Propagation through Atmospheric Optical Turbulence", in Atmospheric Propagation of Radiation, vol. 2 of The Infrared and Electro-Optical Systems Handbook, SPIE Press, 1993.

User Guide Contents

Introduction

    Guide to the User Guide

    WaveTrain documentation and updates on the web

    Index to all WaveTrain documents

    Index to all tempus documents

    General references

A quick tour of WaveTrain

WaveTrain step-by-step tutorials

Assembling and running a WaveTrain model - Tutorial

    Create a new WaveTrain system model

    The WaveTrain component libraries

    Copy components from one System Editor window to another

    Saving systems, opening existing systems

    Component parameters, inputs, and outputs

    Display/hide graphical elements

    Set component parameters

    Verify component parameters

    Connect WaveTrain components

    Create a new run set for the WaveTrain system

    Run the simulation

    View simulation results 

    Additional tutorial topics

    Further WaveTrain details - next steps

Modeling details 

    Connecting WaveTrain components   

    Physical units and nomenclature

    Spatial coordinates and direction nomenclature

    Discrete mesh specifications

    Modeling of optical systems in "object space"

    Sign and phasor conventions for tilt, focus and general OPD

    Sensor timing and triggering

    Sensor timing, CW sources and pulsed sources

    Transverse (x,y) displacement and motion (TransverseVelocity and Slew)

    How tilt is modeled

    Transverse displacement and size of propagation mesh

    Transverse displacement and size of phase screens

    Longitudinal (z) displacement and motion

    Optical propagators in WaveTrain

    Choosing mesh settings for optical propagation

    Setting up Fresnel propagations

    Using the PropagationController

    Using atmospheric turbulence models

    Atmospheric modeling using TurbTool or PropConfig

    Using atmospheric thermal blooming models

    Basic sensor modules:  TargetBoard, SimpleFieldSensor and Camera

    Sensor modules:  the Camera

    Spatially integrating WaveTrain sensor outputs

    Interference of polychromatic fields

    Splitting and combining optical paths

    Using Polarizers to separate light from different sources

    Zernike components

    Adaptive optics models (wavefront sensors, deformable mirrors, tilt trackers)

    How point sources are modeled

    Optically-rough reflectors, and modeling of speckle

    Components for data-type conversion

    How to use spatial filters and absorbing boundaries

    Using WaveHolder to avoid performing redundant propagations

Data entry in subsystem parameters and inputs, and in the Run Set Editor

    Introduction

    Summary of data types

    "Include" setup in Run Set

    Special constants

    C-language syntax for expressions and basic math functions

    Loop indices

    Specifying output recording

    Procedures for entering vectors, arrays and "Grids"

    Procedures for modifying vectors, arrays, and "Grids"

    The functions "gwoom" and "GridGeometry"

    Miscellaneous special functions and operators

    "Obsolete" warnings

    Status bulbs and status checking

    Miscellaneous rules and tips for Run Set and System Editors

Inspecting and post-processing WaveTrain output: *. trf files, TrfView, and Matlab

    Introduction

    Run index (run number)

    TrfView

    Loading trf data into Matlab without TrfView

    trf data structure

    Key commands for working with trf data in Matlab

Creating user-defined WaveTrain components

    Introduction

    Creating a new component by composing existing library modules

    Creating a new atomic component from a Matlab m-file (m-system)

    Creating a new atomic component - general

    How WaveTrain works at the source code level

    WaveTrain "starter systems" for constructing new atomic systems

Using WaveTrain models to gain understanding of the modeled systems

    How to set up and execute parameter studies

    Example system models

    Given a model of an adaptive optics system, obtaining comparable diffraction-limited and open loop results

    Averaging over stochastic effects 

A quick tour of WaveTrain

Step 1 -  Assembling and connecting the WaveTrain components:

For example, suppose we want to look at the optical effects of propagation through atmospheric turbulence.  We might assemble a basic model like that shown below:

Figure: WaveTrain's System Editor, showing the WtDemo propagation model

The window in the above picture is called the System Editor window (equivalently, the Block Diagram Editor), and is used for assembling the optical model from library components.  The present model consists of eight components (also called subsystems, or modules) connected together.  All of the subsystems shown can be found in the WaveTrain component library, and all of the connections in this particular model represent optical interfaces.  (Connections that correspond to electronic or general data signals are also available).  Starting at the far right, we have a Point Source, a TransverseVelocity, an AtmoPath, another TransverseVelocity, a Telescope, and an IncomingSplitter, which splits the incoming light and sends part to a Camera and part to a SimpleFieldSensor.  The PointSource represents an idealized point source, radiating uniformly in all directions. The two TransverseVelocities can be used to model source and detector  transverse motion, and/or a true wind velocity.  The AtmosphericPath module is a complex module that represents two processes: (a) the optical effects of turbulence using multiple discrete phase screens distributed along the propagation path, and (b) the diffractive propagation of light along the propagation path.  By assigning screen motions, AtmosphericPath can also model transverse wind velocities that vary spatially along the propagation path.  In between the phase screens the optical wavefronts are propagated using a two-step FFT propagator.  The Telescope applies an aperture and a focus adjustment to the incoming light.  The IncomingSplitter duplicates the incident beam and sends it out into two branches.  The SimpleFieldSensor records the complex field - amplitude and phase - at the aperture plane.  The.Camera brings the light to a focal plane (using a Discrete Fourier Transform) and records the intensity pattern in that focal plane. 

This relatively simple model can be assembled by a novice user in an hour or so - see our step-by-step tutorials - and it is not a toy; it can do serious calculations. 

Step 2 -  Setting the numerical parameters of all components:

After assembling and connecting the system components, the user must assign all the necessary parameter values.  These include source powers, aperture diameters, propagation distances, propagation mesh dimensions, turbulence phase screen parameters, sensor spatial and timing parameters, etc.  Setting all these parameter values is done partly in the System Editor window illustrated above, and partly in a second editor window, called the Run Set Editor.  A sample Run Set window for the preceding system is shown below (in the window title, "TRE" stands for the full name "tempus Run Set Editor"):

Figure: WaveTrain's Run Set Editor - a run set for the WtDemo propagation model

Step 3 -  Running the simulation:

After specifying all the parameter values, the user initiates execution of the simulation with a few button clicks in the Run Set Editor.  Upon completion of the execution, WaveTrain's output - a combination of sensor images, complex field data, and/or electrical signal data - is stored to data files in a form that can be conveniently accessed for visualization and post-processing.

Step 4 -  Inspecting and post-processing the WaveTrain outputs:

Visualization and limited post-processing of outputs can be accomplished using the TrfView viewer that is part of WaveTrain suite.  Typical outputs might be the instantaneous wave amplitude and phase maps in the "telescope1" pupil plane of the above WtDemo model.  These particular outputs are based on the complex optical field sensed by the "simplefieldsensor1" component in the model.  Sample outputs as displayed in TrfView are shown in the following figure:

Figure:  WaveTrain sample outputs - amplitude (left), and phase (right) maps in the telescope pupil of the WtDemo system, as displayed in WaveTrain's TrfView viewer

WaveTrain is designed to be useful to scientists, engineers, teachers, and students engaged in the design and development of advanced optical systems, or in the study of propagation through turbulence and associated adaptive optical systems.  It is equally well-suited for simple models, like the example shown above, for intermediate complexity models such as are typically used in concept exploration, and for the kind of detailed engineering models necessary for accurate performance prediction, design refinement, and trouble-shooting.  We are continually adding new components and features, and making improvements, often in response to customer feedback.  If you need or want a feature that we don't yet offer, please let us know.  Alternatively, WaveTrain is designed to be extensible, so you can create your own components to supplement the WaveTrain library, as described in creating your own WaveTrain components. 

WaveTrain step-by-step tutorials

The User Guide chapter immediately following the present one provides an introductory tutorial to assembling and running WaveTrain models.  That tutorial is a compromise between constructing the simplest possible first system, and constructing one that is still fairly simple yet will be physically interesting to most WaveTrain users.  A new user can work through that tutorial in a few hours.

We also provide here several links to other tutorial briefings that have been used by MZA personnel when leading WaveTrain training sessions or short courses.  Slight drawbacks of those documents may be that:  (i) they may use some illustrations or procedures from older versions of WaveTrain, resulting in occasional confusion, (ii) since the briefings were meant to be used in a trainer-led class, some explanatory sentences may be missing from the briefing charts.  Despite those warnings, users may still find the extra tutorials useful.  These tutorial briefings may be found on the WaveTrain documentation page on MZA's website.  These extra tutorials are accessible from the following links on that web page;  roughly in order of complexity, they are 
(a)  "WaveTrain User's Quick Start"
(b)  "WaveTrain Tutorial (March 2008)"
(c)  "The Whiteley Tutorial model".

Note that the most recent version of the present WaveTrain User Guide may also be found on the same web page, at the link WaveTrain User's Guide.

WaveTrain Examples Library

After working through the introductory tutorial, and in conjunction with the construction of original WaveTrain systems, users may find it useful to inspect some of the example systems in the WaveTrain Examples Library.  The examples library comprises WaveTrain systems and run sets which are delivered with WaveTrain.  The purpose of the examples is to provide working systems which involve application of WaveTrain concepts and to give users a start on building more complex systems.  The example systems are distributed with standard WaveTrain installations, and may be found in the subdirectory "wavetrain\examples\" of the WaveTrain installation directory.  (Disclaimer:  it should not be assumed that the examples provided there are fully valid for any particular user application).

Assembling and running a WaveTrain model - Tutorial

We suggest that new users begin their WaveTrain study by working through the following tutorial.  The tutorial has the following goals:
(a)  To lead a new user step by step through the construction and execution of a WaveTrain simulation.
(b)  To introduce a new user to several of the key WaveTrain components that are needed for most WaveTrain systems.
(c)  To introduce the user to some of the specialized nomenclature that is used in the WaveTrain program.
(d)  To introduce the user to TrfView, which is WaveTrain's utility for quick inspection and plotting of simulation results.

Create a new WaveTrain system model

To start the WaveTrain user interface, double-click the Wavetrain desktop shortcut, or use the typical Windows menu sequence, 'Start - Programs - MZA Associates Corp - WaveTrain'.  The desktop shortcut and start group should have been generated during the WaveTrain installation process.

Starting WaveTrain as above simply brings up a small toolbar with the title "TVE".  TVE stands for Tempus Visual Editor, which is the overall graphical interface program through which the user interacts with WaveTrain.  A picture of the TVE toolbar is shown at right.

To begin the setup process for a new system, go to the TVE toolbar and left-click on the System Editor button.  This brings up a blank System Editor window, as shown below:

--------------------
For WaveTrain Ver. 2010A and later:

In the File menu of the editor window, execute the sequence File - New - New System.
This changes the window title to "NewSystem", instead of "no system loaded" as shown in the above illustration.  The window is now ready to accept the insertion of components to build a new system. 
--------------------
--------------------
For WaveTrain Ver. 2009A and earlier:

The blank Sytem Editor window opens already in the "NewSystem" state, ready for insertion of components to build a new system.
--------------------

At this point, you are ready to begin creation of a WaveTrain system by copying the components you desire from the WaveTrain libraries into the NewSystem window.  There are several methods for inserting library components into a new system:

(1)  You can open a second System Editor window, and in that window open an iconic representation of the WaveTrain library.  Then you can copy and paste individual components from the library into your new system.  This is a good method for comprehensively browsing the available library systems, particularly when you are still unfamiliar with the library contents.

(2)  It is also possible to insert components by
     (a) inserting them directly from a library directory listing, or
     (b) copying and pasting components or groups of components from existing systems.  
We will discus some of these alternate methods later in the present chapter.

In the remainder of this tutorial, you will use the basic method (1) to create a new system.

The WaveTrain component libraries

You will now insert components into a new system, using the basic Method (1) above.

--------------------
For WaveTrain Ver. 2010A and later:

(1)  Start WaveTrain, and press the TVE toolbar System Editor button (already done in the above subsection).
(2)  In the File menu of the editor window, execute the sequence File - Open - Master Library.
This causes a second, separate System Editor window to open, and after a few seconds of loading time you will see a display of icons as in the following screen snapshot.  These icons comprise the WaveTrain "component libraries":

Figure:  Contents of the WtLib library

--------------------
--------------------
For WaveTrain Ver. 2009A back to Ver. 2008:

--------------------
--------------------
For WaveTrain Ver. 2007 and earlier:

(1)  Start WaveTrain, and press the TVE toolbar System Editor button (already done in the above subsection).
(2)  Press the TVE toolbar System Editor button again to open a second System Editor window.
(3)  In the second System Editor window, go to the menu bar and execute the sequence File - Open - Browse.
(4)  Navigate to your wavetrain\wtlib\ directory.
(5)  Open the file WtLib.tsd.
You will then see a set of six icons representing "component sub-libraries", as shown in the following figure: .

Figure:  The WaveTrain component library, in WaveTrain Ver. 2007 and earlier

--------------------

All WaveTrain versions:

Maximum allowed number of TVE System Editor windows

Above you opened two separate System Editor windows.  In general, TVE allows you to open a maximum of three separate System Editor windows, which you can use for purposes of system inspection and editing.

Nomenclature note

In some places in the WaveTrain program suite and documentation, the "System Editor" may be called the "Block Diagram Editor (BDE)".

Copy components from one System Editor window to another

Now you will begin constructing your new WaveTrain system, by copying components from the WtLib library into your new system window.  The order in which you copy the components make no difference, but it seems logical to start with a source.  In the above System Editor window that contains the six sub-libraries, double-left-click the icon entitled SourceLib.  This causes you to "descend" into the sub-library, so that you now see (in the same window) a variety of individual WaveTrain source modules (components) which have been collected for convenience into the sub-library.  The window should look similar to the picture below, although the exact arrangement of the icons may differ.  Note that in the picture below, the window size chosen for the illustration hides some of the individual components.

Figure:  Contents of SourceLib (a sub-library of WtLib)

Note the toolbar button that is marked with the red arrow in the above figure.  This button has Windows' standard "up-directory" icon:  in the System Editor context, this signifies going up one level in a system hierarchy.  If you left-click that button, you will return to the level that shows the six sub-libraries.  Alternatively, you can go up one level by right-clicking on blank space in the editor window, then selecting "up one level" from the context menu.  Double-left-click again on the SourceLib icon to descend again.

Now begin your system construction by copying the PointSource component into your blank new system window.  The steps are:
(1)  Find PointSource in the SourceLib window.
Select PointSource by moving the cursor over the icon and left-clicking.  Notice this outlines the icon in red. 
(2)  Use the window's menu bar to execute Edit - Copy PointSource. 
(3)  Move to the other System Editor window where you are building the new system.  In that window, go to the menu bar and execute Edit - Paste PointSource. 
(4)  When first pasted, the icon may be jammed into the upper left hand corner of the System Editor window.  By left-clicking the icon and dragging it, you can move it to any desired location within the window. 

To select and paste additional components, simply repeat the copy-paste procedure for the additional components.  In order to follow along with the illustrations and exercises in the remainder of this chapter, you should now copy and paste the remaining components in the following picture (you are building the same system as in the WtDemo system that was shown in the quick tour):

Appearance of the component icons

Do not be concerned if your component icons look somewhat different than the ones in the above figure:  the icon pictures have occasionally changed during WaveTrain development cycles.  However, the names of the systems in the title bars at the bottom of the icons should be identical!  In fact, the icon pictures come in various flavors and color schemes, as well as various orientations.  Later we explain how to modify the icons for aesthetic reasons, if desired.

The icon pictures should be interpreted loosely, and not taken too literally.  For example, in the above picture the IncomingSplitter has the splitting interface oriented in the "wrong" direction for sending light to the SimpleFieldSensor.  Such icon details have no functional effect whatsoever in the WaveTrain interface: it is only the connections that you will make between component blocks that determine where the light goes.  Any component icon picture could be replaced by an arbitrary new picture with no effect whatsoever on system function.

Deleting a component

If you make a mistake, or are just experimenting, you can remove a component from your system by selecting it (left-click on the icon), and using the window menu sequence Edit - Delete.  Alternatively, after selecting, right-click to get a context-sensitive menu that also presents a Delete option.

Alternate copy-paste procedures

As usual in graphical interfaces, there are alternate procedures available for copying and pasting.  For example, once you have selected a component by left-clicking, then instead of using Edit - Copy from the menu bar, you can immediately right-click and obtain a context-sensitive menu that also offers the Copy command.  Then, to paste the copied component into the new system window, you can right-click on blank space in the new window and obtain a context-sensitive menu that offers the Paste option. 

It is also allowed to select more than one component at a time, using <Ctrl>-left-click to select the second, third, etc. components.  The selected ones can all be copied at once and then pasted at once.  When first pasted, they may all appear in the upper-left corner, stacked on top of each other.  You can then drag them individually to their desired locations.

Saving systems, opening existing systems

Saving

At this stage, save your new system before proceeding to the next stage of system construction.  A system can be saved at any stage; no particular level of completeness needs to be achieved before saving .  To save the new system, the steps are:
(1)  In the System Editor window menu bar, left-click File - Save As.
(2)  Navigate to any directory where you want to store your system.
(It would be preferable to not use any tempus or WaveTrain subdirectories).
(3)  Specify a system (file) name of your choice, and press Save.  The file extension .tsd (tsd = "tempus system definition") will be automatically appended to the name you specify.

In older versions of WaveTrain, File - Save As may first place you in a WaveTrain library directory:  you do not want to save your system there.  Wherever you choose to save it, it is usually good practice to store each new WaveTrain system in its own directory, because the process of building the system, the runset and then executing the runset will generate numerous files associated with one system. 

Once the new system has been saved for the first time, subsequent changes can be saved by using just File - Save.

Opening an existing system

Suppose that you wish to work with a system that has been previously saved, but is currently not open in a System Editor window.  To do this, the steps are:
(1)  Open a new System Editor window from the TVE toolbar.
(2)  In the editor window menu bar, left-click File - Open - Browse.
(3)  In the resulting directory window, navigate to the directory where the system of interest is stored.
(4)  Select the .tsd file that bears the system name you want, and press Open (or just double-left-click the .tsd file name).

(*)  As an alternative to File - Open - Browse, the menu sequence File - Recent systems is also useful:  this presents you a quick list of systems that you've recently opened.

The present TVE environment allows a maximum of three separate System Editor windows to be open at one time. 

Next steps in building your system

After you have copied or added the desired subsystems into your new or working system window, you will need to set their parameters, and connect them together.  In general, these steps can be done in either order. 

Component parameters, inputs and outputs 

After you copy or add components (subsystems), you will need to assign values to their "parameters", and possibly to some of their "inputs".  These two terms are used in a specialized sense in WaveTrain:  they are both inputs in a generic sense, but the distinction is that "parameters" are fixed in time, whereas "inputs" may or may not change with time. 

A typical component "parameter" might be an aperture diameter, a source power, or a mesh spacing. 

A typical component "input" might be a "wavetrain" (WaveTrain's data structure that carries the optical field information).  The data in a wavetrain incident on a component usually changes as the simulation time advances.  On the other hand, timing parameters that define sensor exposures are also "inputs", even though most of these do not change with time.

A typical component "output" might be a wavetrain, or a time-integrated sensor exposure map.

A component may have any number of parameters, inputs and outputs.  A parameter must be assigned a value.  An input usually receives its value by being connected to the output of another block, but sometimes an input is assigned a value explicitly.  Outputs are usually connected to the inputs of other components; in some cases, outputs are not graphically connected to anything, but may just be recorded.  These options will become clearer as you continue with the construction of the tutorial system.

In the subsequent sections of this introductory tutorial, you will see many examples of parameters, inputs, and outputs.  We will refer to them without quotes from now on; it should be clear from the context whether "input" is meant in the specialized WaveTrain or the generic sense.

Display/hide graphical elements

Before actually setting any parameters or connecting inputs and outputs, you must become familiar with certain mechanics of the graphical user interface (GUI) related to displaying and hiding of the component graphical elements.  Notice that, in the copy-paste operations you performed above, the component (subsystem) icons consisted of a picture, a miniature toolbar beneath the picture, and a component name bar below that. 

Displaying/hiding the components parameters, inputs and outputs 

Due to the finite display space available, it is frequently useful (or necessary) to hide various graphical elements.  Of course to initially set the parameters and to connect the inputs and outputs, these items must be displayed.  To display or hide, you will use one of the toolbars buttons in the System Editor window, and also the miniature toolbars located underneath the component icons.  The master control for displaying and hiding is the toolbar button indicated by the red arrow in the picture at right.  In the new system window in which you have been assembling your system, left-click the indicated button.  That pulls down the palette which you see in the picture at right.  This palette contains six rows of buttons: for now we are just interested in the last four rows, each of which consists of three or four small buttons.  The first of these rows is labeled "SN" in the picture, and controls display of System Names.  The second row, labeled "I" in the picture, controls display of Inputs.  The third row, labeled "O", controls display of Outputs.  The fourth row, labeled "P", controls display of Parameters. 

Global display/hide:  As an initial exercise, after pulling down the palette, left-click on the leftmost "I" button:  in your new system window, you should now see that the inputs of all your components are now displayed.  The display may be messy because the icons are too close to each other for present purposes.  Grab one or two of the icons and move them to see everything for those icons.  The palette buttons are all "toggles", so click the same button again to hide the inputs.  The leftmost button in the "O" row serves the same function for component outputs, and the leftmost "P" button serves that function for the component parameters.  Any combination of I,O, and P may be displayed.  Finally, note that the leftmost "SN" button allows you to turn off/on the display of component (system) names; these take less room, so usually there is not much point in hiding the names. 

Individual component display/hide:  Instead of applying the display/hide toggles to all components at once, it is often very helpful to apply the toggles to one component at a time.  To do this, simply select (left-click) the icon of interest, and then press the above-discussed palette buttons.

Miniature toolbar under component icon:  From inspection of the above picture, you will see a miniature toolbar directly below the component icon, above the component name.  The mini-toolbar has symbols that look exactly like the buttons in the left column of the palette.  Once you have used the palette to set the display/hide properties of the t, n, v elements to your liking, then you can more quickly display/hide the SN, I, O, P rows by just left-clicking the mini-toolbar buttons.  Note that clicking the mini-toolbar buttons preserves the t, n, v settings that you have chosen with the palette.

Set component parameters

Now that you have mastered the displaying and hiding of display elements, you are ready to set the parameters.  In your new system, select the SimpleFieldSensor component, and display all the I, O, and P elements to follow along.  After you've copied SimpleFieldSensor from WtLib, and you've displayed all the elements, it should look like the illustration at right.
Note:  Depending on the age of your WaveTrain version, there may be some differences in the contents of the rightmost "value" column.

We now want to enter desired values in the value fields (rightmost column) of the parameter block (light grey) and the input block (light blue).  In WaveTrain, we use the term "setting expression" to denote the expression entered in a value field.  Note that in this example all the value fields are already filled in with some default setting expressions.  This will not be the case with all components: sometimes the value fields are initially blank.  In either case, these initial settings are usually not what you want in your new system. 

Note that some setting expressions in the picture are simple numbers ("1.0e-3"), some are symbols ("wavelength", "propdxy"), some are boolean expressions ("true"), and some are algebraic expressions  ("apdiam / propdxy").  After you finish the introductory tutorial, you can obtain full details on the expressions and functions that are allowed in setting expressions by referring to the detail chapter on Data Entry.

The simplest method of assigning a setting expression is to enter a number.  If you enter a number and press <return>, you are completely done with that parameter.  However, this is often undesirable for two possible reasons:
(a)  You may want to link the value to that of another parameter value.
(b)  You may want to vary the value later at the level of the WaveTrain Runset Editor (to be discussed later in this chapter).
To handle issues (a) or (b), you must assign a symbolic name or algebraic expression as the setting expression.

Parameters sub-window:

Before proceeding with the setting expressions for other components, you should now become aware of a sub-window of the System Editor.  Using the System Editor View menu, execute the menu commands View - Parameters.  This makes visible a sub-window within the System Editor, which we call the Parameters Panel, as shown in the following picture:

The Parameters Panel contains a listing of all the symbols that you have defined so far:  "wvln", "apdiam", and "propdxy" all appear.  If undesired symbols still appear in the list (e.g., from some experimentation you might have done), you can (and should) delete those by left-clicking in their row, and pressing the button at the top right of the Parameters Panel.

For now, let's ignore the "Default value" and "Description" columns in the Parameters Panel.  You can toggle the Parameters Panel display on and off, as convenient, using View - Parameters.

Help pages for individual WaveTrain components

In this tutorial, we guide you by giving you valid setting expressions to enter for all parameters and inputs.  Naturally, when you eventually do this on your own, you will need reminders of the meaning of, and valid possible settings for, the many component parameter and input names.  This information can be obtained for each component by left-clicking the question-mark button, , at the bottom right of any component icon. 

Enter setting expressions for remaining components:

(Note that the PointSource parameter named "power" is poorly named:  this parameter is actually the Watts/steradian produced by PointSource).

Enter setting expressions for TransverseVelocity (first instance named transversevelocity, and second instance named transversevelocity2):

You will assign the parameter values to represent a uniform atmospheric wind speed, transverse to the propagation path, with stationary source and receiver.  (Picture the three velocities with respect to an earth frame, which is considered inertial).
     (*)  Change the default settings to match those in the pictures below:

Notice that we have entered "vWindX" in one motion module and "- vWindX" in the other.  To understand the physical meaning of these settings (after completing the present tutorial), you can consult the User Guide detail sections for further information about the specification of transverse displacement and transverse motion in WaveTrain.

Enter setting expressions for AtmoPath:

Enter setting expressions for Telescope:

This component performs two functions: (a) it applies a binary aperture (in general, annular), and (b) it undoes the wavefront curvature acquired due to propagation from a point source to the telescope.  Function (b) works together with the Camera module that follows.   

Parameter name "range":
Here you simply enter the distance to an OBJECT plane whose image you want to generate in the focal plane of a subsequent Camera module:
     (*)  The desired setting expression in the value field, "range", is already present by default, and you have previously registered this symbol.  No further action is required.

Parameter names "apertureRadius" and "annulusRadius":
     (*)  These already have the desired setting expressions entered by default, and the symbol "apdiam" has been registered previously.  No further action is required.
Note the mixed nomenclature: "apertureRadius" signifies the outer radius of the annular aperture, while "annulusRadius" signifies the inner radius, all in MKS units (i.e., meters).

Enter setting expressions for Camera:

     (*)  Edit the setting expressions in Camera's parameter value fields to match the picture below.

You have now completed the entry of setting expressions for all your component parameters.  At this point, you should verify that the settings are complete, and furthermore, syntactically consistent.  The mechanism provided by WaveTrain to perform this check is the pair of status bulbs at the bottom right of the System Editor window

Status bulbs

At the bottom right of the System Editor window, you will see the two status indicators    and  .  The two colored bulbs can be either red, yellow or green, indicating various levels of missing or inconsistent information in the parameter and input setting expressions.  The "System status" bulb refers to the system level currently displayed in the Editor window: this is the one of present interest.

If the status bulbs are not green, it means that one or more problems have been detected by the TVE.  In the system you are constructing, left-click on the "System status" bulb, which should be green at this point.  A message box will pop up, telling you that no problems are detected at this time. 

Connect WaveTrain components

Now that you have completed the setting expressions for all the components of your tutorial system, the next step is to connect the components together.  This step is very simple:  to connect the output of one component to the input of another component, you must:
(a)  Make sure you display the inputs and outputs of the components you want to connect.
(b)  Place the cursor on the arrowhead of a dark-blue output bar: the arrowhead should turn red when you are over the sensitive region.
(c)  Left-click and drag to the connection triangle at the end of the desired light-blue input bar, and release:  a connection line will appear.

Carry out steps (a)-(c) to make the connections shown in the following figure:

In producing the above layout, we've used several GUI features to improve the visual presentation:
(a)  You can spread out the component icons to give more room, either by dragging the individual icons, or by pressing the "unpack"( ) and "pack" () buttons in the System Editor toolbar.
(b)  You can introduce bends in a connecting line, by left-clicking on a line and dragging (right-click and "delete vertex" to undo).
(c)  The connection triangles or arrowheads of inputs and outputs may be flipped from one side to the other of the colored bars.  To do so, place the cursor on a colored bar and double-left-click.  Alternatively, place the cursor on a bar and right-click to get a context-sensitive menu, then "Flip".
(d)  The horizontal and vertical layout of components is completely immaterial to their functionality:  only the connections control which way light is going.  (A later Guide section explains details of coordinate and direction conventions).

After all components are connected and setting expressions defined, you may want to hide all inputs,outputs and parmaeters, leaving just the connecting lines showing.  In that case, your completed system could be compacted as follows:

Note that all your connecting lines are single-headed arrows:  that is because light is only going in one direction in this tutorial system.  In many systems, you will have light going in both directions ("incoming" and "outgoing", in WaveTrain nomenclature).

At this stage, you can always redisplay the inputs, outputs, or parameters of individual components as needed.

Execute the menu commands File - Save

Of course you can do this at any time during the above work, but make sure you do so before proceeding to the next stage of construction.

Create a new run set for the WaveTrain system

Now that you have completed assembly of your WaveTrain system in the System Editor, you must create a "run set" for it.  After the run set is created, you will be able to compile and run the simulation with two button clicks. 

To create a run set for your system model, go to the System Editor file menu and
   (*)  execute File - New - Runset;
   (*)  in the input box that pops up, enter a name of your choice (say, "A") for your new run set;
   (*)  press "OK". 

Notice there are two panels in the Run Set Editor:
(a)  the Run Variables panel, currently blank;
(b)  the System Parameters panel:  notice that the parameter names that appear here are precisely those symbols that you defined when you entered them previously in the component setting expressions of the system editor window.  You can verify that the name list here exactly matches the comprehensive name list that appears when you View - Parameters in the System Editor window.

You must now do the following four things in the Run Set Editor before you can finally run your simulation:
(a)  Assign numerical values (or file sources) to the System Parameters
(b)  Possibly define some Run Variables
(c)  Enter a simulation Stop Time
(d)  Specify one or more variables for recording.

Assign numerical values to System Parameters and Run Variables:

(*)  Left-click and type in the "Value" fields of the System Parameters panel, and assign the values shown in the modified picture below.
(*)  Press <Enter> to accept a value setting before moving to another entry field

Physical units:  inputs, outputs and parameters in WaveTrain are in MKS units.  One caution on units: phase or OPD inputs/outputs can be a little tricky, in that different components may assume meters or radians, which will be specified by the help page for the individual components.

(*)  Parameter name "nscreen" needs a special adjustment:
This adjustment is required due to a deficiency in the WaveTrain interface.  We include this bit of ugliness in the tutorial because it will appear in practically every atmospheric propagation model, and you must get used to it.

Execute the menu commands File - Save:

In the Run Set Editor window, execute the menu commands File - Save.  Proceed with saving despite the resulting "incomplete" warning. 

Enter a simulation Stop Time:

Specify variables for recording:

When you execute the simulation, WaveTrain records no results by default.  You must specify precisely which outputs you want to record. 

(*)  In the Run Set Editor, press the Recorded Outputs button in the toolbar, where indicated by the red arrow in the following figure:

A new window will pop up, entitled "Output Recording" as shown below, which contains a listing of all the component outputs that are available for recording. 

(*)  Click on both check boxes:  this will cause recording of the camera and field sensor output maps (one map for each exposure window in each sensor)
(*)  Note that below the check boxes, the radio button "When changed" is selected".  This is the usual choice;  leave all other boxes unchecked.

(*)  Press "OK" to accept your selections and to close this window.

Notice that the "Output Recording" button in the Run Set Editor toolbar now has the anotation "(2)", indicating that two output variables have been selected for recording.
Notice also that the status bulbs at the bottom of the Run Set Editor are now both green, implying that all required settings have been filled in, insofar as the Editor can determine.

Execute the menu commands File - Save:

In the Run Set Editor window, execute the menu commands File - Save. 

Further WaveTrain details

After completing the above tutorial, new users will no doubt still have many questions about the usage of specific WaveTrain components, system assembly, data entry in setting expressions, and inspecting and post-processing WaveTrain results.  Details of these subjects are treated in the remaining chapters of this User Guide. 

After the introductory tutorial, several alternatives for further WaveTrain learning are as follows:
(a)  Users can attempt to construct their own simple systems from scratch.
(b)  Users may attempt to add embellishments or make modifications in the tutorial system, which is already a physically interesting and non-trivial system.
(c)  Users may wish to move on to study the BLAT system, which is included in the WaveTrain examples directory.  This example system can introduce the reader to usage of WaveTrain's adaptive-optics components.  The BLAT model is also accessible from a link on MZA's web site,

However users proceed, we recommend at this point that they
(a)  Skim the rest of the User Guide to get a notion of the contents and organization
(b)  Dive into the details as they are needed for the user's future WaveTrain work.

The remaining detail sections in the User Guide are grouped into the following categories:
(*)  For physics-oriented issues and usage details regarding important specific WaveTrain library systems, users should consult the chapter Modeling details.
(*)  For details regarding data entry in the two editor windows, users should consult the chapter Data entry in subsystem parameters and inputs, and in the Run Set Editor.
(*)  For details regarding TrfView, trf files (recorded outputs) and the extraction of trf data, users should consult the chapter Inspecting and post-processing WaveTrain output:  *.trf files, TrfView, and Matlab.
(*)  For details regarding the construction of user-defined WaveTrain subsystems, users should consult the chapter Creating user-defined WaveTrain components.

Modeling details

Connecting WaveTrain components

Each WaveTrain component has inputs and outputs, and by connecting inputs to outputs we define which subsystems interact with one another, and how.  Connecting the components of a WaveTrain system and setting the parameters can be performed in any order, and interspersed at will.

WaveTrain is based on tempus, a general purpose simulation tool, and in tempus a connection between two subsystems can represent any kind of interaction at all - forces, control signals, sensor outputs, message packets, whatever.  Of course, in WaveTrain, many connections between components represent optical interfaces, and we designed a C++ class, WaveTrain specifically for that purpose; that is the origin of the name for the overall tool.  A single connection of type WaveTrain can describe all the light crossing a given plane in a given direction, from any number of sources, coherent or incoherent, polarized or unpolarized.

Most WaveTrain subsystems have one or more inputs and/or outputs of type WaveTrain; light sources, like lasers, typically have a single WaveTrain output, while light sensors, like cameras, typically have a single WaveTrain input. Two-way optical components, like mirrors and lenses, generally have two WaveTrain inputs and two WaveTrain outputs, one of each for each propagation direction.  By convention, when a component has just a single WaveTrain input it is named incident, while if it has a just a single WaveTrain output, it is called transmitted.  Note that transmitted waves may correspond to physical reflection, refraction or diffraction:  "transmitted" is used in a generic sense simply to indicate the wave or waves that emerge from the component in question. 

The WaveTrain inputs for a two-way optical component are named incomingIncident and outgoingIncident, while the corresponding outputs are called incomingTransmitted and outgoingTransmitted.  The terms "incoming" and "outgoing" are used only to distinguish between the two inputs and the two outputs, and indicate which is related to which.  The effects of some components are direction-independent (e.g. Aperture) but for many components that is not true.  For further details regarding WaveTrain's directional nomenclature and coordinate systems, see the section on "Spatial coordinates and direction nomenclature". 

Basics of connecting inputs and outputs

Subsystem inputs can be
(a)  connected to an output of some other subsystem, or
(b)  assigned a setting expression (possibly by default) and left unconnected.
It is also allowed for an input to have a setting expression and be connected to another system's output:  in that case, the output will supersede the setting expression, if an output is available at a particular virtual simulation instant. 
In more advanced work, you will also find it useful to connect an input to an input of the composite system that contains it.

To connect an input to an output, the procedure is very simple:
(a)  place the cursor on the arrowhead of a dark-blue output bar: the arrowhead should turn red when you are over the sensitive region;
(b)  drag to the connection triangle at the end of a light-blue input bar, and release:  a connection line will appear.

For inputs of data type WaveTrain, the default value is generally set to the value WaveTrain(), which is equivalent to saying that there is no incident light.  This means that it is generally OK to leave these inputs unconnected.  A typical example is when only "incoming" light exists in the system.  In that case, all the outgoingIncident inputs are left unconnected.  Notice that this is the situation in the system you constructed in the tutorial of the previous chapter.

In order to connect an output and input, they must have the same data type.  In the system pictured above, all the connected quantities were of type WaveTrain, which you can verify by displaying the type fields.  An attempt to connect incompatible data types will be automatically refused by the GUI (i.e., no connecting line will appear). 

Multiple output connections

A subsystem output of data type WaveTrain may be either left unconnected, or connected to exactly one input of type WaveTrain of a different subsystem.  If you attempt to connect an output of type WaveTrain to a second input, you will receive an error message.  In more advanced work, you will also find it useful to connect a WaveTrain-type output to one output of type WaveTrain of the containing system.

Although you cannot connect one WaveTrain-type output to two inputs, you will frequently want to model an optical system in which the same wave or waves are seen by two or more different sensors, or sent through two or more different optical paths.  The mechanism provided for this purpose is a special component called a Splitter, which has one WaveTrain input and two WaveTrain outputs.  Similarly, if you want to combine the light from two or more sources and send it through the same optical path you must use another special component called a Combiner, which has two WaveTrain inputs and one WaveTrain input.  All splitting and combining can be done with these, but for convenience we also provide a number of other closely-related components:  IncomingSplitter,  IncomingSplitter6, OutgoingSplitter,  IncomingCombiner, OutgoingCombiner.  For more information, see Splitting and combining optical paths.

Outputs of data type other than WaveTrain can be connected to any number of subsequent inputs, without special splitting mechanisms.  Examples of such outputs are fpaImage of Camera (data type Grid<float>) and fld of SimpleFieldSensor (data type Grid<Complex>).

Managing connections and the display

As a practical matter, you will find that when making connections it helps to have some "elbow room", enough space between subsystem to make it easy to see what is connected to what.  If the subsystem icons are close together, when you display the subsystem inputs and outputs they will often overlap one another, as shown, making the diagram very hard to read.  You could simply spread the subsystems further apart by dragging them, but unless you do that only a few a time the total diagram can become too large to fit in the window.  How to proceed in this context is largely a matter of user preference, but another mechanism is provided to help cope with space issues.  The System Editor window toolbar has two buttons whose icons are (Expand block diagram) and (Pack block diagram).  Clicking on increases the distance between all subsystems by a factor of two.  When we are done making connections, we can hide the inputs and outputs if desired, and use the pack button to return to the original diagram scale.  If we hide the inputs and outputs, the connections are simply indicated by single- or double-headed arrows between the icons:

In the above diagram we have only single-headed arrows because light is only propagating in one direction in this system.

Other useful display manipulations:  Particularly when we desire to leave inputs and outputs displayed, the connecting lines are often at unpleasant angles, or passing behind other icons, or generally forming a jumble that impedes the clear display of the logical connections.  Two manipulations are provided to help clean up the diagram:

(a)  The connection triangles or arrowheads on inputs and outputs may be flipped from one side to the other of the input or output colored bars.  To do so, place the cursor on a colored bar and double-left-click.  Alternatively, place the cursor on a bar and right-click to get a context-sensitive menu that offers the "Flip" option.  This option is very useful for preventing the obscuration of connecting lines.

(b)  If you left-click anywhere on a connecting line and drag, you will see that a new vertex is created, leaving you with a connecting polygon instead of a single line segment.  This allows you to create more-horizontal or vertical connecting paths, and generally move lines so that they are more visible.  Also, if you place the cursor on an existing connecting line or vertex and right-click, you will get a context-sensitive menu with related options, such as deleting a vertex.

Physical units and nomenclature

Units

Unless an explicit statement to the contrary is given, all numerical quantities used in WaveTrain are expressed in MKS (meter-kilogram-second) units, and all angles are expressed in radians.  The documentation for individual library subsystems is usually explicit about the physical units for inputs, parameters and outputs.  (The individual-system documentation is the html page that appears when one clicks the "?" symbol below a subsystem icon in the System Editor window).  However, if a unit specification has been omitted, the user should feel confident in assuming MKS units.  This applies particularly to WaveTrain data that is saved in .trf files:  .trf data does not have physical units information explicitly indicated in the .trf file.   

One potential ambiguity that arises is the physical unit of wavefront optical path difference (OPD).  "MKS" in this case could refer either to absolute length (meters) or to radians of phase.  In WaveTrain, OPD is almost always expressed in meters.  The documentation of individual subsystems should be explicit in this regard.

Time in WaveTrain is always expressed in units of seconds. 

Physical nomenclature

There are several important optics quantities for which no universally consistent nomenclature exists.  We mention several key items here, and compare commonly used names with the names that were adopted in WaveTrain.

Irradiance, intensity:  These terms are often used interchangeably for the quantity whose MKS units are W/m².  "Irradiance" is the term recommended by specialists in radiometry and by the standards committees, but the use of "intensity" has a long history in physics texts.  In the WaveTrain documentation and system modules, these two terms will also appear interchangeably.

Exposure, integrated intensity:  The term "exposure" is often used for the product  (irradiance)*(exposure length), whose MKS units are (W/m²)*sec= J/m².  In WaveTrain modules, this quantity is almost always referred to as "integrated intensity", where "integration" in this case refers to the time dimension.  "Integrated intensity" is the standard output of all WaveTrain intensity- or energy-type optical sensors. 

Integrated complex field:  This is an unphysical quantity which appears in at least one important WaveTrain sensor module.  WaveTrain's SimpleFieldSensor module was provided to make the complex optical field directly accessible to the user.  For reasons of coding uniformity with respect to the other temporally-integrating sensors, it was originally decided to define the output of the field sensor as (complex field)*(exposure length), with units of (W/m²)^1/2 * (sec).  Of course, physically this is not a meaningful quantity, and does not scale sensibly with exposure length. 

The user must apply the appropriate scale factor to renormalize SimpleFieldSensor's output to a physically meaningful quantity.  Suppose icf denotes SimpleFieldSensor's integrated complex field output.  Then, in order to obtain the physically sensible integrated intensity in J/m², one must compute in post-processing the quantity
     integrated_intensity = |icf|² / exposure_length .

     (Note that |icf|² / exposure_length = |c_field*exposure_length|² / exposure_length
                                                              = |c_field|² * exposure_length
                                                              = integrated_intensity ).

Spatial coordinates and direction nomenclature

WaveTrain assumes that all optical beams propagate at small angles relative to the z axis.  Beams may propagate in the (+z) or (-z) directions.  Any physical sequence of optical components that fold or refract light through large angles (such as steering mirrors) should be visualized in terms of an unfolded path, as far as the WaveTrain model is concerned.  Every WaveTrain module (subsystem) has a local (x,y,z) coordinate system, and characteristics such as aperture support and source module beam profiles are defined with respect to their respective local coordinate origins.  In the absence of explicitly imposed transverse displacements, each module (subsystem) in a WaveTrain system has its local coordinate origin on the z axis of a conceptual global coordinate system.  We emphasize the word conceptual, because WaveTrain does not actually assign global z coordinates:  the only z distances actually input into WaveTrain are propagation distances, |Dz|, between modules.  More precisely, these |Dz| are the distances between the local origins of two modules.  The direction (positive or negative) associated with |Dz| is specified by "outgoing" and "incoming" tags as described below. 

Propagation distances |Dz| are specified in the inputs or parameters of propagation modules such as AtmoPath or VacuumProp.  As will be explained soon, it is also typical in wave-optics modeling to have many optical-system components with zero separation.  Zero separation between neighboring modules is assumed, whenever no |Dz| is explicitly specified.

When constructing WaveTrain models, users must clearly understand some specialized directional nomenclature used by WaveTrain.  Three key pairs of terms are used everywhere in WaveTrain with specialized meanings.  These terms are "Incident/Transmitted", "Outgoing/Incoming" and "Platform/Target".

"Incident" and "Transmitted" tags

As explained above, the physical sequence of optical components modeled in WaveTrain should be visualized in terms of an unfolded path.  Any beam that enters a WaveTrain module is called "Incident", and any beam that exits a module is called "Transmitted".  In particular, a WaveTrain "Transmitted" beam can refer to light that was physically reflected, transmitted or internally generated (by a source).  For examples of incident and transmitted tags, see the input/output bars (the light and dark blue bars) in the System Editor picture below.

"Outgoing" and "Incoming" tags: orientation of +z

Positive- and negative-z directions are defined in WaveTrain via the "outgoing" and "incoming" tags that appears in the input/output lists of various propagator and other modules.  The (+z) direction is identified with the "outgoing" direction tag, and the (- z) direction is identified with the "incoming" direction tag.  For example, the figure below shows two separate systems consisting of a PointSource source and a TargetBoard sensor connected via the AtmoPath module.  

In system (A), the wave emerging from PointSource is connected to the "outgoingIncident" input of AtmoPath.  Consequently, the wave traveling from PointSource to TargetBoard is defined to be traveling in the (+z) direction.  Usually, it is acceptable to think of PointSource as located at z=0 and TargetBoard as located at z=+L, although this is not literally what WaveTrain does internally.  As stated previously, WaveTrain only works with z differences between or across modules.  The absence of an absolute 0 of z is significant if one works with a WaveTrain system that contains several (i.e, more than one) concatenated atmospheric modules.  In that case, the z-coordinates of phase screens within each atmospheric module refer to relative positions within that atmospheric module only.

In system (B), the wave emerging from PointSource is connected to the "incomingIncident" input of AtmoPath.  Consequently, the wave traveling from PointSource to TargetBoard is defined to be traveling in the (- z) direction.  We can think of TargetBoard as located at z=0 and PointSource as located at z=+L, with the caution mentioned above.  In general, both outgoing and incoming waves can be present in a single system. 

The visual layout (right-left, top-bottom) of the subsystems in the System Editor has absolutely nothing to do with establishing (+z) and (-z) directions.  The only thing that matters are the "outgoing" and "incoming" tags established by certain of WaveTrain's subsystems.  In the above example systems (A) and (B), we positioned components so that an outgoing wave (+z) points to the right, and an incoming wave (-z) points to the left, but that was solely to help in human visualization.

In the above examples, AtmoPath provided the outgoing/incoming assignments.  If AtmoPath is not included in a WaveTrain system, there will usually be some other module that establishes the assignments "outgoing" (+z) and/or "incoming" (-z).  However, not all WaveTrain modules that deal with wave inputs or outputs need to designate the input/output as outgoing or incoming.  For example, we see in the preceding picture that PointSource simply generates a wave designated as "transmitted", without specifying whether that means outgoing or incoming.  Whether a module needs to know that a wave is outgoing or incoming depends on the mathematical operation that module will perform on the complex field. 

Side remark regarding GUI manipulation:  In the preceding diagram, notice that in system (A) the inputs all have their triangle connectors on the left sides of the modules, whereas in system (B) the input connectors are all on the right sides of the modules.  The output connectors stand in an analogous relation.  This flipping of inputs or outputs is accomplished by right-clicking on a module, and then choosing the "Flip inputs(outputs)" command (double-clicking on the input or output bar does the same thing).  Flipping is not necessary to make the system function, but it greatly improves the graphical readability.

"Platform" and "Target"

As described above, the system connections to "outgoing" and "incoming" input/output boxes are the only determinants of positive and negative z direction.  Additionally, at many places in the WaveTrain documentation, the terms "platform" and "target" are used in the following specialized directional sense:
     "Target" means the more-positive z end of the system (the destination of "outgoing" waves or the source of "incoming" waves), while
     "Platform" means the more-negative z end of the system (the destination of "incoming"  waves or the source of "outgoing" waves).

The user should realize that the terms "platform" and "target" never appear in any of the objects that are manipulated in WaveTrain's System Editor window.  The only directional specifications that the user directly designates when building a system are "outgoing" and "incoming".  "Platform" and "target" ends can both contain sources, sensors or reflectors: there is no restriction in that regard.  The additional "platform-target" terminology may initially seem redundant or confusing, and may conflict with what is really the physical target of a beam in a particular application.  However, this terminology is now thoroughly ingrained in WaveTrain documentation and usage. 

X and Y axes

WaveTrain's x and y axes are two Cartesian axes transverse to the z axis,  where the latter is always the nominal propagation direction.  There is no intrinsic relation between WaveTrain's (x,y,z) directions and any earth-connected coordinate system.  There is no intrinsic association with up, down, right, left, horizontal or vertical.  Each WaveTrain module has its local x-y coordinate system, and the defining characteristics of the module (e.g., aperture boundary, focus aberration curvature factor, position offset, etc.) are all defined relative to that local x-y coordinate system.  The local z axes (or x-y origins) of different modules are either colinear with each other or transversely offset from each other, as determined by the insertion (or not) of a TransverseVelocity module.  The important topic of transverse displacement and transverse motion is discussed in further detail in a later section. 

In many WaveTrain modules, there is no explicit specification of how the defining characteristic (e.g., Aperture boundary) is offset with respect to the local x-y origin.  If there is no explicit specification, the user should assume that the characteristic in question is centered with respect to the local x-y origin. 

Transformation of outgoing to incoming waves

As stated previously, mirror-like deflections in WaveTrain are modeled in terms of an unfolded optical system.  Typical examples would be a beam incident on a Tilt module or on a  BeamSteeringMirror module.  For example, if a wave is fed to the "outgoingIncident" input of a Tilt module (see panel (A) of the following diagram), then the corresponding output beam is obtained from the "outgoingTransmitted" output of the Tilt module.  An incoming wave ("incomingIncident" and "incomingTransmitted" may also be controlled by the same Tilt block, as represented by the dashed arrows in (A).  This models a common situation in a laser beam projection system, where the same steering mirror might affect a projected laser beam heading toward a target, as well as beacon light returning from the target.  What is not allowed is the operation shown in panel (C):  one may not transform the outgoing beam to an incoming beam simply by making the connections illustrated in (C).

This restriction applies to all WaveTrain modules, but there are a few specialized reflector components that may appear to transform outgoing to incoming waves (or vice-versa).  Among these are the rough-reflector modules like CoherentTarget, IncoherentReflector, or PartiallyCoherentReflector.  Panel (B) of the above figure illustrates this idea.  The decision to connect CoherentTarget's "transmitted" output to AtmoPath's "incomingIncident" input seems logical, since most often we want the reflected ("transmitted" in WaveTrain terminology) beam from this component to propagate back in the opposite direction through the same atmospheric screens that the incident beam saw (possibly displaced in x or y, of course).  Thus, CoherentTarget and similar modules have the apparent capability of transforming {outgoing ↔ incoming}.  However, what such modules are really doing is acting as both "sensors" and "sources": one should think of the module's "transmitted" wavetrain as being a new wavetrain that was generated by a source.  Therefore, this type of module's "transmitted" wavetrain can be connected to either a subsequent "incoming" or "outgoing" tag.  For example, if the CoherentTarget in panel (B) was meant to model a transmissive ground-glass plate, with subsequent propagation through a second atmospheric path, then it would make sense to add a second AtmoPath module to the right of CoherentTarget, and to connect CoherentTarget's "transmitted" output to the "outgoingIncident" input of that second AtmoPath.

Discrete mesh specifications

The optical quantities that we model using WaveTrain are usually described analytically in terms of continuum (x,y,z) coordinates.  For computer modeling we must represent a continuum quantity by a sampled function on a discrete lattice, or mesh of points. 

Nomenclature note:  the term "grid" is often used in the general literature in a sense equivalent to "lattice" or "mesh".  However, in WaveTrain the term "grid" has been appropriated to designate a data type that comprises the combination of a mesh of points together with function values defined on that mesh.  We will attempt to maintain consistent terminology in the documentation:  we will try to use "mesh" or "lattice" when we mean just a mesh of points, and to reserve "grid" for its specialized WaveTrain meaning.

Grid spacing, dimension and offset

In the present section, we introduce several important facts about the WaveTrain meshes used for physical (Fresnel) propagation, for phase screens, for detector sample points and other purposes.  Later sections of the User Guide provide further details and sample usages, in the context of specific WaveTrain subsystems or of specific functions used to define meshes.  The purpose of the present section is to gather in one place some general properties of and key facts about the WaveTrain meshes.  Almost all the meshes used in WaveTrain are uniform rectangular meshes aligned with the x and y axes.  The dx and dy spacings and the nx and ny dimensions may be allowed to differ, although for many applications equal x and y parameters are appropriate. 

There are several variations in the data entry format, but WaveTrain meshes are almost always specified in terms of the parameter set (nx, ny, dx, dy), or a notation like (nxy, dxy) to specify a square mesh using just two parameters.  In the following discussion we will use the notation (x, nx, dx) for brevity to refer to either dimension.  In addition to (nx,dx), the remaining specification required to completely determine the mesh coordinates is the offset from x=0.  The offset determination can be somewhat confusing in Wavetrain, so we now discuss this in some detail.

Most situations can be satisfactorily modeled with two options:  either the mesh is forced to have a point at x=0 or the mesh is symmetrically disposed with respect to x=0.  At the WaveTrain code level, these mesh types are constructed using functions named "gwoom" (= "grid_with_origin_on_mesh") and "GridGeometry".  The two examples in the following diagram define the offset convention for the case nx = even:

The key rules for nx = even are:
(1) In the gwoom mesh, the nxy/2 point (counting from 0) lies at x=0.
(2) In the GridGeometry mesh, the points are symmetrically positioned relative to x=0.

The following two examples define the offset convention for the case nx = odd:

Note that when nx = odd, the two mesh-defining functions produce identical meshes.

The WaveTrain user is not always allowed to choose whether a gwoom or GridGeometry mesh will be used.  In many WaveTrain library modules, the user is simply asked to enter (nx,dx), but is not asked to specify whether a gwoom or GridGeometry mesh should be used.  In such cases, the mesh type will be a gwoom, unless module documentation explicitly specifies otherwise.  As an example, consider the TargetBoard system in the left panel of the following picture.  The parameter list calls for the specification nxy with no option to specify the grid type: this will be a gwoom mesh.  The same situation holds for the sensor meshes in the SimpleFieldSensor and Camera sensors.  An exception to the more common pattern is the HartmannWfsDft sensor module:  again the user is just allowed to specify (nx,dx) parameters in the sensor plane, but this time a GridGeometry type of mesh is used. 

In other library modules, the user is allowed to specify the choice of gwoom or GridGeometry in addition to the (nx,dx) specification.  An example is the SensorNoise block shown in the right-hand panel of the above figure.  In this case, the data type of the input parameter (left-most column) is itself named GridGeometry:  that is the signal that the user must enter a setting expression in the value field (right-most column) which is written in terms of either the function gwoom(...) or the function GridGeometry(...).  An example using the GridGeometry function is shown in the figure.  Further details of the allowed input syntax for gwoom(...) and GridGeometry(...) is given in the User Guide chapter on data entry.

New feature as of WaveTrain 2010A:  To help the user verify exactly what the mesh-point coordinates were in a WaveTrain run, a new feature has been added as of WaveTrain 2010A.  For all recorded variables of WaveTrain type "Grid", WaveTrain automatically saves companion recorded variables that record the mesh-coordinate information.

Propagation mesh

The propagation mesh, i.e, the mesh on which Fresnel propagation calculations are performed, has some special restrictions.  This mesh is specified in PropagationController, AtmoPath, or analogous subsystems.  In order to use highly optimized FFT (Fast Fourier Transform) routines, WaveTrain requires that nx for a propagation mesh be a power of 2.  (Even if the user enters a non-power-of-2, WaveTrain will round up to the nearest power.) 

In addition to the power-of-2 restriction, there are other constraints on the propagation mesh (nx, dx) that should be observed in order to avoid DFT (Discrete Fourier Transform) aliasing and wrap-around effects.  These issues are discussed in a separate section.  The propagation mesh is a gwoom, unless explicitly specification to the contrary is allowed in a propagation module. 

Phase screen mesh

The mesh on which phase screens are defined is specified in AtmoPath, GeneralAtmosphere or analogous modules.  To allow for relative transverse motion of the screens, sources and sensors, without repeating the screens, one may specify screens that are much longer in one dimension than another.  The screens are also computed using FFT routines, but there is no power-of-2 constraint in this case.  The screens must only be computed once, at the beginning of a WaveTrain run, so it is acceptable to be non-optimally efficient here.  Another slight difference in the way phase screen meshes are specified is this:  the spacing dx is still an input parameter, but instead of nx the user must specify the span of the screen in meters.

Further explanation of the phase mesh specifications, and how these interact with the transverse motion specifications, is deferred to a separate section. 

Interpolation

When one WaveTrain module operates on the discrete complex field or other output of the preceding module, it is often necessary to interpolate the preceding output onto the mesh of the current module.  This is frequently necessary even if we set those mesh items under our direct control so that the meshes are registered as much as possible.  For example, suppose we have a simple static system consisting of a source, an AtmoPath module, and a TargetBoard sensor.  In this case, (nx,dx) specs are requested in AtmoPath to define the propagation mesh and phase screen mesh, and in TargetBoard to define the points at which the final irradiance will be sampled.  Since all these meshes are gwooms as described above, if we specify a common dx value then the mesh points of all the modules coincide and no interpolation is necessary.  However, if we introduce any relative displacement in the system, such as wind, target motion or just static displacements, then it will frequently happen that the displacement for a simulation time step is not a whole number of mesh points.  In that case, WaveTrain must internally interpolate to pass the optical data from some modules to others.  No special action is required by the user to effect this:  WaveTrain takes care of this matter internally.  However, the user should be aware that interpolation is frequently occurring, because there are occasionally surprising artifacts that arise from the interpolation.  These artifacts are more likely to occur when the complex field must be interpolated as opposed to a real irradiance map. 

Modeling of optical systems in "object space"

The subsystems of a WaveTrain model can typically be grouped into functional groups that represent either propagation channels or optical system groups.  The latter might represent transmitters, targets, or receivers.  The optical system groups share one critical characteristic:  it is often desirable, in wave-optics modeling, to ignore physical propagation between the components of an optical system group.  All the components of a single optical system group can be modeled as operating in a space of common transverse magnification, which is usually taken as having the same transverse scale as the propagation channel.  Equivalently, this transverse scale would correspond to the entrance pupil in case of a pure receiver or the exit pupil in case of a pure transmitter.  For brevity in this documentation we refer to this space as the "object" space.  In this modeling approach, which considerably simplifies the model bookkeeping, we specify the parameters of each optical component transversely scaled to the object space, and we usually place all the optical components in a common z plane, with zero separation between the components.  In this approach, the optical system component parameters are immediately related to the turbulence and propagation parameters of the propagation medium.  A wide variety of phase and amplitude map manipulation, beam splitting, detection processes and adaptive-optics feedback loops can still be accurately modeled in such a collapsed model of the optical system.  The order of operations carried out by various elements (splitting, attenuating, tilting, sensing, etc.) corresponds to the order in which the WaveTrain blocks are connected, and this must be consistent with the actual order in the physical system.  With one exception, in most WaveTrain modeling there is no reason to carry out physical-optics propagation using Fresnel propagators within the optical system.  The one exception is computation of the far-field image in (or near) a focal plane, which is carried out in WaveTrain's Camera and HartmannWfsDft (wavefront sensor) modules.  In these special case, the diffractive effects of the entrance pupil are accounted for by far-field propagations embedded in the modules.  Defocused sensor planes can be accounted for as well in this framework.  The omission of diffractive propagation between most elements of the optical system is consistent with the usual optical analysis of composite systems:  the effects of diffraction are for practical purposes completely represented by one physical propagation from pupil to sensor plane.

The following figure shows a simple detector system that illustrates the above points.

Consider the receiver optics group.  Within this group, there are no subsystem inputs or parameters that specify separations between any of the subsystems.  Consider first the receiver actions comprising truncation by Aperture, "splitting" or more accurately "copying" of the beam by Splitter, discrete sampling on a sensor mesh by TargetBoard, and the application of a quadratic phase by Focus.  All these mathematical operations are applied to the incident complex field in the same z-plane, namely the z-plane of the aperture.  The order of the operations is faithful to the connection arrows in the picture.  Now the physical system that is being modeled will of course have non-0 separations between the receiver elements, and may in fact include various reimaging and demagnification stages.  For example, the targetboard may model a CCD sensor on which is physically impinging a demagnified image of the physical aperture plane.  As long as diffractive effects due to the reimaging optics are negligible, accurate modeling can be done by projecting the mesh spacing of the physical CCD sensor to the aperture plane.  This projection to the "object space" is the usual way that optical systems (both transmitters and receivers) are simplified for modeling in WaveTrain (or any other wave-optics code) .

The Camera module in the receiver group does internally incorporate a key physical propagation.  The action of Camera is to compute the diffractive far-field (Fraunhofer) irradiance corresponding to whatever input complex field is presented to Camera.  In this case, diffraction by the receiver group's Aperture has a dominant effect on the irradiance distribution in the Camera sensor plane, and this diffraction is completely accounted for by the internal computations of Camera.  The particular combination of geometric and physical (diffractive) propagation outlined here is very typical in the analysis and numerical modeling of optical systems.  If the combination of projections to object space plus far-field Cameras is insufficient to accurately model a given optical system, then it is possible to construct a system that actually computes physical propagations between numerous optical elements.  The key difficulty is properly generating the widely varying propagation mesh spacing required as the optical beam undergoes a sequence of possibly large compressions or expansions.  This will usually require understanding and use of the "spherical reference wave" feature of WaveTrain's Fresnel propagator modules.

Side remark: The Focus system in the above receiver group illustrates a secondary point.  A typical application of Focus in a receiver group is to allow a Camera focal plane to be the image plane conjugate to a finite (rather than infinite) distance.  The composite WaveTrain module called Telescope may also be used for this purpose.  See "Using the Camera module" for further discussion.

Complete systems with 0 total propagation distance

For testing purposes, it is often very useful to construct a complete WaveTrain system that has no propagation distance anywhere in the system (except possibly inside a Camera module).  The only caution to be observed here is that one must be careful to actually specify the mesh on which the optical field is defined.  In a typical WaveTrain system this might be accomplished by the propnxy and propdxy parameters in the AtmoPath subsystem.  However, in the absence of any propagator module, the recommended procedure is to insert a PropagationController subsystem to define the mesh parameters on which the optical field is generated.  Normally, one or more PropagationControllers are automatically present because they are subsystems of propagation modules such as AtmoPath.  See the section devoted to PropagationControllers for further discussion. 

The following figure shows an example of a complete system with 0 total propagation distance:  the system tests the operation of a wavefront sensor by presenting it with a perfect plane wave of variable tilt and focus.

Note that WaveTrain sources such as UniformWave and GaussianCwLaser make sense when the total propagation distance is 0, but the action of WaveTrain's PointSource is ill-defined if we have no propagation distance.

Sign and phasor conventions for tilt, focus, and general OPD

There are two (linked) aspects of sign and phasor conventions that may be important to the user:

(1)  For WaveTrain input purposes, the most important issue is whether positive or negative signs of tilt parameters cause beams to be deflected up or down, and whether positive or negative signs of focus parameters cause beams to converge or diverge.  This is defined in the first section below ("sign conventions").

(2)  A secondary issue is how signs are defined in phasor expressions that mathematically represent tilt, focus, or general transverse OPD.  When defining WaveTrain inputs and parameters, the user does not usually need to know these details.  However, if recorded outputs of the SimpleFieldSensor module are used to inspect complex fields, then the user may wish to know all the sign conventions used by WaveTrain for the phasors.  This is discussed in the second section below ("phasor conventions").

In reading the documentation on sign and phase conventions, we recommend that the user first focus on the essential issue number (1), and just refer back to the explanations of issue (2) as needed.

Sign conventions for tilt, focus, and general OPD

Tilt 

WaveTrain has several modules (notably Tilt, Slew and BeamSteeringMirror) that apply a tilt-angle increment to an incident wave.  In these modules, one inputs a tilt angle (Dq_x,Dq_y), in units of radians of angle.  The sign convention for tilt angle in WaveTrain is motivated by the geometric picture of beam deflection as shown in the following figure.  The picture is drawn in unfolded form as if deflection is effected by a prism, in accordance with WaveTrain's "incident-transmitted" treatment of waves as discussed above.

The diagram shows the meaning of the tilt sign when combined with the two possible z-directions of propagation.  The rule is:

(a)  Positive Dq_y means that the beam is steered towards positive y.
(b)  Negative Dq_y means that the beam is steered towards negative y.
(c)  Statements (a) and (b) hold for both outgoing and incoming incident waves.  This is consistent with the fact that, if outgoing and incoming beams are affected by the same element, then they are both steered toward -y or both toward +y.  The interpretation of Dq_x of course follows the identical pattern.

The representation of tilt in WaveTrain has a twist that users must understand to work effectively.  Tilts applied by modules like Tilt and BeamSteeringMirror can either be
(1) carried separately in computation from the residual complex field, or 
(2) incorporated into the complex field, by multiplying the incident field by a phasor factor. 
At present, we only alert the reader to the existence of this feature:  the reasons for and various implications of this dual representation are quite important, and are discussed more fully in a later section that discusses how tilt is modeled internally.

Focus

WaveTrain's Focus module applies a quadratic phase increment (a focus or defocus) to an incident wave.  The Focus module requires a signed input value called "focusDistance", for which we here used the symbol f.  The WaveTrain sign convention for focusDistance is:

(a)  Positive f causes the incident wave to become more convergent.
(b)  Negative f causes the incident wave to become more divergent.  
(c)  Statements (a) and (b) hold for both outgoing and incoming incident waves.  

The sign convention for f corresponds to what is called "power" in first-order optical design:  positive power or f tends to converge an incident wave, and negative power or f tends to diverge an incident wave, regardless of the propagation direction.

Phasor conventions for tilt, focus, and general OPD

As noted in the introduction to the previous section on signs, WaveTrain's internal phasor conventions are only significant to users when they wish to inspect the complex field output of the SimpleFieldSensor module.

Tilt

If a tilt-generating module is instructed to "put the tilt into the complex field" (see the section on how tilt is modeled), then the complex field incident on the module is multiplied by the phasor 

     OUTGOING waves:   exp[ +i(2p/l)(Dq_x x + Dq_y y) ]
     INCOMING  waves:   exp[  -i(2p/l)(Dq_x x + Dq_y y) ]  ,
     where we recall from above that Dq_x and Dq_y may themselves be positive or negative.  

The critical reader may question the consistency of WaveTrain's tilt-angle phasor convention.  For the purpose of background understanding, consider the following.  Suppose we write the fundamental vectorial representation of a plane wave phasor using the "-iwt" convention:  

      exp[ i(k*r  - wt) ]  =  exp[ i(k_xx + k_yy + k_zz  - wt) ]  ,

where the bold quantities indicate vectors, k is the wave vector and w is the optical angular frequency.  The relevant point here is this: as t advances, positive k_z forces a constant-phase surface to move toward +z (what we call "outgoing"), while negative k_z forces a constant-phase surface to move toward -z ("incoming").  Likewise, regardless of the sign of k_z, the sign of k_y determines whether the wave moves upward or downward along y, and similarly for x.  Now it would be logical to define the tilt angle via the relation  k_y = (2p/l)(Dq_y), that is, to assign the same sign to k_y and to Dq_y.  However, we see that the WaveTrain tilt-phasor convention violates this relation, since an extra (+/-) factor has been inserted depending on (outgoing/incoming) status.  The WaveTrain convention evidently conflicts with the exp[i(k*r  - wt)] representation; in fact the WaveTrain convention can be viewed as switching between "-iwt" and "+iwt" conventions depending on whether outgoing or incoming waves are being represented.  Nevertheless, no contradictions arise within the allowed operations of WaveTrain.  Certain signs in the propagators are defined consistently with the wave phasor signs.  Additionally, a critical fact is that WaveTrain's splitter/combiner modules never allow outgoing and incoming waves to be combined for possible complex superposition on a field sensor.  It is only possible to compute the complex superposition of several outgoing or of several incoming waves.  Under this restriction, the WaveTrain conventions will give correct interference results.

Focus

WaveTrain's Focus module applies a quadratic phase increment (a focus or defocus) to an incident wave.  The complex field incident on Focus is multiplied by the phasor

     OUTGOING waves:      exp[ - i(2p/l) (x² + y²)/(2f) ] 
     INCOMING waves:       exp[ +i(2p/l) (x² + y²)/(2f) ]  ,

where f is a signed input value called "focusDistance" in the Focus module.  As discussed in the previous section, the sign convention for f is:

     positive f causes the incident wave to become more convergent,
     negative f causes the incident wave to become more divergent,
     where this holds for both outgoing and incoming incident waves.  

WaveTrain's focus phasor sign convention has a consistency issue analogous to that discussed in the preceding tilt section.  But as outlined there, no contradictions arise within the presently allowed operations of WaveTrain.

General OPD

A general, transversely-varying phase function can be represented by 

     f(x,y)     or     (2p/l)d(x,y)

where the transverse OPD function is in radians of phase (f) or in meters (d).  WaveTrain has several modules (e.g., OpdMap and FixedOpdMap) which allow the multiplication of an incident wave (complex field) by a phasor created from a discrete input array d(x_i, y_j).  The phasor factor is defined as 

     OUTGOING waves:      exp[ +i(2p/l)d(x,y) ] 
     INCOMING waves:       exp[ - i(2p/l)d(x,y) ]  .

For example, in light of the previous focus discussion, an input { d(x_i, y_j) = - |a| y_j² } should generate a phasor factor that adds a positive-f (converging) cylinder focus factor to both outgoing and incoming waves. 

Absolute phase

WaveTrain does not keep track of absolute phase in its propagation modules.  That is, a complete Fresnel propagation operator from plane 1 to plane 2 includes a factor exp[i(2p/l)Dz₂₁], but this factor is omitted in WaveTrain propagations.  

Sensor timing and triggering

All sensors in WaveTrain are temporally-gated integrating sensors.  For any simulation, the user specifies a sequence of exposure windows during which a sensor will accumulate light, and this sequence is the key specification that controls the number of propagation calculations that is performed during the simulation run.  Successful setup of a WaveTrain simulation requires understanding of several peculiarities of the WaveTrain timing system.

The sensor exposure windows are specified by a combination of two types of inputs:

(1)  Sensor modules like TargetBoard, Camera, or SimpleFieldSensor all have a set of inputs named "on", "exposureInterval", and "exposureLength".  The "exposureLength" is the length (in seconds) of a single exposure window, and the "exposureInterval" is the time interval (in seconds) between the start of successive exposure windows. 
CAUTION:  most sensors also have an additional input named "sampleInterval", which has a different meaning than "exposureInterval".

(2)  An output of the module called SquareWave can be connected to the "on" input of a sensor, to control the start time of the exposure window sequence.

The inputs "exposureInterval" and "exposureLength" define the underlying periodicity of a sensor's exposure scheduling.  The parameters of SquareWave control the start time of the first active exposure window, and can also be used to modulate the underlying gate window repetition sequence.  The meaning of modulation in this context is illustrated in example 2 below.  If no SquareWave trigger module is attached to the sensor, then the sensor's "on" input must have its value set to "true" to activate the sensor.  In that case, the first active exposure window starts at time t=0. 

With an exception to be explained below, WaveTrain only works with time values t >=0.  A simulation run always formally begins at t=0, but propagations only occur at those times and intervals required to produce the specified sensor exposures.  WaveTrain operates in "event-driven" fashion, so if there are long time gaps between events there is no impact on wall-clock execution time.

Propagation delay

WaveTrain accounts for time-of-flight delay in the propagation of light.  Suppose a user's timing parameters specify that a sensor exposure window opens at time t_k.  If the z-distance from source to sensor is L, and the speed of light is c, then a wavefront would have to leave the source at time t_k' = t_k -(L/c) in order to arrive at the sensor at t_k.  Depending on L and t_k, it is possible that t_k'  is negative.  What happens in that case depends on how the source module was coded.  WaveTrain source modules are not consistent in this regard: some are capable of answering a "request" for emission prior to t=0, but others are not.  In order to avoid surprises, we recommend that the user define sensor and trigger inputs so that no exposure windows require light that must be emitted prior to t=0.  However, violating this guideline is usually not catastrophic:  the sensor may simply report 0 output for those exposure windows that need emissions prior to t=0.

Integration over one "exposureLength", and number of propagations in one "exposureLength"

We stated above that WaveTrain sensors are "integrating" sensors.  Now we discuss more precisely what this means in WaveTrain. 

The default behavior of sensors is as follows.  If an exposure window opens at t_k, then:
(1)  A wavefront is generated at the source at the advanced time t_k' , and this wavefront is propagated with physical delays through the intermediate system planes.  (These intermediate planes might, e.g., contain moving phase screens, each of which will be positioned at its appropriate transverse locations as the wavefront reaches it).
(2)  If "exposureLength"=T_exp, then at  t_k^out = t_k+T_exp , an intensity sensor will report an output value defined by  output = (sensor irradiance in W/m²)*(T_exp) = (exposure in J/m²).  The nomenclature that was adopted in WaveTrain uses the term "integrated intensity" for the quantity whose units are J/m².

Note that the default integration procedure defined in the preceding paragraph (2) assumes that the irradiance at the sensor remains constant during "exposureLength".  Note also that the default procedure requires only one propagation series for each exposure window.  A propagation series refers to the set of propagations and phasor multiplications that are needed to propagate one wavefront from a source, through all phase screens and optics, to a sensor.  

If the default integration procedure is not acceptable for the modeling task in question, then an optional sensor behavior can be invoked by explicitly setting the input named "sampleInterval", which appears in all the sensor modules.  The default setting is 0.0, which produces the default integration behavior defined above.  Changing the setting to a non-0 value (but smaller than T_exp) causes WaveTrain to subdivide each exposure window and propagate several wavefronts, at intervals of "sampleInterval".  The individual sensor irradiances are then multiplied by sampleInterval and added,  thereby still yielding a single reported exposure (integrated intensity) for a given exposure window.

When output from a sensor is recorded in a .trf file, the .trf file contains a vector of times and a corresponding set of exposure maps, one map for each time.  The recorded times are the ends of the exposure windows, denoted above as t_k^out.  The logic for recording the end times is that they represent the times when the outputs are actually available from the physical sensor.  In fact, some sensor modules have an optional processing delay parameter (e.g., see Camera).  In that case, the recorded .trf times are the ends of the exposure windows plus the processing lag.

Example 1

Consider the following WaveTrain system:

The propagation distance L=100km has been specified in the AtmoPath module.  The SquareWave bool-type output is connected to (and triggers) the TargetBoard bool-type input named "on".  
The SquareWave timing parameters are
     startTime = 100E3 m / speedOfLight  (the constant speedOfLight is an internally
                                                                       defined symbol in WaveTrain)
     pulseLength = 1.0E6 sec
     pulseInterval = 1.0E6 sec
The TargetBoard timing parameters are
     exposureInterval = 1.0E-3 sec
     exposureLength = 1.0E-4 sec
     sampleInterval = 0.0
Suppose also that the simulation stopTime (specified in the Run Set  editor) is 3.0E-3 sec.

The specified SquareWave startTime defines the beginning of the first sensor exposure window, and exposureInterval defines the interval between the beginning of successive exposures.  Given the simulation stopTime, the following diagram shows the three exposure windows for which propagations will be generated by the above timing specifications.  The exposure windows defined by the TargetBoard parameters are indicated by thin black lines, the SquareWave timing pulse is indicated by the heavier green lines, and the simulation Stop Time is the heavy black line:

Since sampleInterval was 0.0, one propagation series will occur for each exposure window, timed so that the wavefront arrives at the sensor at the beginning of the corresponding window.

Notice that the sensor startTime of  (100km)/(speedOfLight)  means that the wavefront that arrives at the sensor at startTime must be generated by the source exactly at t=0.  This is not a requirement for the emission of the first wavefront of the simulation: any time >= 0 is always acceptable.

In the Example 1 system diagram, we entered the timing parameters as numerical values in the value fields of the subsystem blocks.  However, we would often prefer to enter variables in the value fields, and elevate these variables to the level of the Run Set  editor before assigning specific numbers.

In Example 1, SquareWave's pulseLength and pulseInterval have no effect because they extend beyond the simulation stopTime.  Example 2 shows how these parameters can be used to modulate the timing pattern.

Example 2

The following diagram shows how the SquareWave pulseLength and pulseInterval can be used to modulate the sequence of sensor exposure windows that are active.  The active exposure windows are those that fall during the high part of the SquareWave signal.  The demand for such timing sequences is not particularly high in WaveTrain practice, but the following special case is often useful.  We may often include a diagnostic sensor in a system, and it may be sufficient to record just a few data frames at the beginning or perhaps the end of the simulation run.  Suitable combinations of startTime, pulseLength and pulseInterval can conveniently achieve this.  Note that a pulseInterval or a pulseLength that extends beyond the stopTIme of the simulation is a legal specification (this feature was already used in Example 1).  The simulation stopTime, specified in the Run Set  editor, always cuts off the simulation at that designated instant.

Sensor timing, CW sources and pulsed sources

In the above discussion of sensor timing and triggering, we implicitly assumed that the WaveTrain source modules were of the continuous-wave (CW) type.  Of course as a numerical code WaveTrain only computes wavefronts at discrete instants.  The meaning of "CW" here is that a CW source can emit a wavefront whenever required by the sensor timing and triggering parameters.  Key CW sources in WaveTrain are UniformWave, GaussianCwLaser and PointSource.  In previous discussion of sensors and timing, we noted two key facts:
(1)  setting sensor timing parameters causes the so-called CW sources to emit a wavefront at corresponding discrete times (accounting for propagation delay);
(2)  sensor output is always a temporally-integrated quantity (such as J/m²), over a sensor exposureLength. 
From these two facts, it follows that a pulsed source can be easily represented by WaveTrain's so-called "CW" sources.  We need only specify the correct combination of source strength and sensor exposureLength, so that the total energy emitted by the source during exposureLength is the desired pulse energy.  This technique is an important alternative in WaveTrain to the use of an explicitly pulsed source (it may be, for example, that a source module with desired characteristics does not exist in pulsed form).

Nevertheless, WaveTrain does provide a number of source modules that, in certain respects, explicitly represent physically pulsed sources.  An example is the module PulsedPointSource.  The module names can unfortunately be a bit confusing, because (1) the names of the pulsed-source modules do not always parallel the CW modules, and (2) the names sometimes but not always contain the word "Pulsed" (just as CW sources only sometimes contain the word "CW") .  The user should scan SourceLib for the current list of available modules.

When a pulsed source module is used, the user must still set up sensor timing and triggering parameters exactly as explained in connection with the CW sources.  The only really new feature is that timing parameters may be specified so that a source pulse may not be entirely contained within an exposure window.  The pulsed-source modules are not designed to accurately model various temporal envelopes of pulses.  In all pulsed-source modules, the intensity profile of each pulse is modeled as triangular in time, and symmetric.  For example, the intensity of a one-microsecond pulse rises linearly from zero to its peak over the first half microsecond, then falls linearly to zero over the second half microsecond.  As long as the entire pulse falls within the exposure window, all of its energy will be deposited on the detector.  If a pulse arrival should overlap the beginning or end of an exposure window, only the corresponding portion of its energy will be detected (based on area under the triangle envelope).  If no part of a pulse overlaps an exposure window for a given sensor, then the sensor will report zero energy for that exposure window. 

Pulsed sources all contain a pair of parameters named "pulseInterval" and "pulseLength", and an input named "on".  (For an example, see PulsedPointSource).  The meaning of "pulseInterval" and "pulseLength" is self-explanatory.  The input "on" has the same triggering functionality as the "on" input in sensor modules.  That is, "on" can either:
(1)  be assigned the value "true", which turns the source on at t=0, or
(2)  be connected to a SquareWave module, which can then be set to trigger the first source pulse at an arbitrary start time.  The section on sensor timing and triggering illustrates more fully the use of SquareWave for triggering.  The triggering principles are the same whether applied to sensors or pulsed sources.

Although the extra functionality provided by the pulsed-source modeling is fairly restricted, the user may find it a convenient way to explicitly model the time multiplexing in physical source systems.  The user should be aware, though, that this can always be done with WaveTrain's CW sources.  Pulse energy can be represented as discussed in the introductory paragraph, and some adjunct procedures can be used to control which sensors see which sources.  These adjunct methods include spectral filters and "polarization" tags.  The use of "polarization" tags in WaveTrain is discussed in using Polarizers to separate light from different sources.  We put "polarization" in quotes here because in WaveTrain the specified polarization state is just a numerical tag that allows one to differentiate two beams of the same wavelength.  The main point we want to emphasize is that the choice between using a CW or a pulsed source is generally a matter of user experience or procedural preference, rather than strict WaveTrain necessity.

Transverse (x,y) displacement and motion (TransverseVelocity and Slew)

A variety of interesting WaveTrain simulation studies can be performed without explicitly modeling any relative motion of the subsystems.  This type of simulation has the following structure:
(1)  Using one value of a random number seed, define one realization of a sequence of phase screens between source(s) and sensor(s).  The seed would be entered, for example, in the AtmoPath module.
(2)  Propagate the optical beam(s) to obtain one statistical realization of the field(s) at all sensors.  This constitutes one "run", as recorded in the .trf file.
(3)  Using the looping capability in the Run Set  Editor, change the random number seed and generate a new (independent) realization of the sequence of phase screens, and propagate the optical beam(s) once more.
(4)  Repeat N times.
This type of simulation produces N statistically independent sample results from each sensor, and is useful for certain types of statistical studies of turbulence effects. 

Side remark:  In the above type of statistical study, the simulation Stop Time parameter should be set so that only one sensor exposure is recorded for any run, given the exposureInterval of the sensor.  Otherwise, one "run" in the .trf file will contain identical repetitions of the sensor results for a given screen set realization.  The duplicate results would all be correct, but execution time and storage would be wasted.

Although the type of statistical study described above is important, a more general scenario involves simulating the relative transverse motion of subsystems, while sampling the optical beams at specified rates.  The key modeling assumption is that the phase screens, which are generated at the beginning of a run, move relative to sources and sensors according to the frozen-flow concept.  Any study that involves rates of temporal evolution, such as calculation of the effectiveness of turbulence compensation and adaptive optics, is of this type.  In such studies, the WaveTrain system must contain one or more subsystems that define relative motion between various parts of the system.  In this case, one "run" of the simulation, as defined by the recorded .trf data, consists of sensor results for a designated number of time steps.  The number of time steps is determined by sampling rates defined in sensor subsystems together with the simulation Stop Time.  The entire simulation may consist of only one "run" that lasts the designated time.  Alternatively, using the loop capability in the Run Set  Editor, the entire simulation may consist of several statistically independent runs of the same temporal length, that differ only in the seed used to generate the phase screens set.  For any given run, a given phase screen set is generated, and subsequently the appropriate translations cause the optical beams to interact with different portions of the screens as the subsystem positions evolve in time.

As discussed in the preceding sections on sensor timing, WaveTrain always makes use of the concept of propagation delay (finite light speed) when computing the optical field that impinges on a sensor at any time t.  This has a number of consequences when we construct WaveTrain systems and define parameters that specify transverse motion.  The following sections discuss in detail how transverse motion is specified in WaveTrain, and how one handles the related effects of propagation delay.

Methods of implementing relative transverse motion

WaveTrain provides the following procedures for specifying the relative motion of sources, sensors and turbulent medium:

(1)  The WaveTrain module TransverseVelocity specifies a transverse offset between modules located on the negative-z and positive-z sides (incoming and outgoing sides) of TransverseVelocity.  The transverse offset may be static or time-varying.  TransverseVelocity blocks can be used to model uniformly moving platforms and/or targets, and/or a uniform atmospheric wind.  Some examples and details of TransverseVelocity and Slew usage are given below.

(2)  Frequently, it is also necessary to use a Slew module in conjunction with TransverseVelocity, in order to keep beam(s) centered on sensor entrance pupils, and to keep focal spots at a fixed field angle on camera focal planes.  This corresponds physically to tilting a transmitter or receiver system in order to stay pointed at the nominal position of a target or source.  However, the need for Slew depends on the type of source and sensor being used. 

(3)  When a TransverseVelocity block is present, WaveTrain internally computes the implied relative displacement of each phase screen and any propagating beams.  But in addition, extra transverse velocities may be explicitly assigned to the individual phase screens by using input arguments in the AcsAtmSpec function.  AcsAtmSpec is typically used in a setting expression in AtmoPath or similar modules.  The velocities entered in AcsAtmSpec are usually reserved to represent a true atmospheric wind which varies along the propagation path.  As noted in paragraph (1), a uniform atmospheric wind can be modeled using just the TransverseVelocity modules.

The combination of procedures (1), (2) and (3) allows the WaveTrain user to input rather general motion specifications for platform, target and true atmospheric wind in a natural way.  By "natural", we mean that target and platform velocities would be specified in TransverseVelocity modules, and true atmospheric wind velocities would be entered as arguments of AcsAtmSpec in AtmoPath or analogous modules.  As noted above, in the special case where the true atmospheric wind is uniform, it may be easier to combine the true wind with the platform and target velocities in TransverseVelocity blocks.  Examples below will illustrate this.  Another alternative, if the user wishes to exercise it, is to manually calculate the net pseudo-wind velocity that characterizes the motion of each phase screen relative to the beam(s).  Algebraic expressions for these velocities could then be applied to the screens in AcsAtmSpec, and one could dispense with the TransverseVelocity module completely.  This is a common procedure in wave-optics simulation, but in the WaveTrain world the usual practice is to use the combination of methods (1), (2) and (3) outlined above. 

The principal restriction on WaveTrain motion specifications is uniformity, i.e., constant linear and angular velocities.  This is really no defect since, over the time scales that are practical for most wave-optics simulation, practical platform and target systems will not appreciably change velocity.  Jitters induced by atmospheric turbulence and by platform or target base jitter are not contrained by the uniformity assumptions under discussion here.

Use of the TransverseVelocity module

As we see from the picture at right, the TransverseVelocity module takes two pairs of parameter specifications, named (x0, y0) and (vx, vy).  The pair (x0, y0) defines an initial offset at t=0.  This offset is the displacement of the local (x,y) coordinate origin on the negative-z side of TransverseVelocity with respect to the (x,y) origin on the positive-z side of the module.  The pair (vx, vy) defines the velocity (signed) of the (x,y) coordinate origin on the negative-z side of the module with respect to the (x,y) origin on the positive-z side of the module.  As we will see below, a WaveTrain system often contains two TransverseVelocity modules to model the motion of Platform and Target groups relative to the turbulent medium and to each other.  In general, there is no limitation on the number TransverseVelocity blocks that may be inserted to produce offsets among the blocks of a system.

In the special case (vx, vy) = (0,0), TransverseVelocity can be used to define a static offset between the modules on the negative and positive sides of the TransverseVelocity block.  If (vx,vy) is not (0,0), then a time-varying offset between the local origins on either side of TransverseVelocity is generated.  The offset of the negative-z relative to the positive-z side will be
     xoff = x0 + vx · t ,  yoff = y0 + vy · t ,
where t is the simulation virtual time.

As mentioned in the section on spatial coordinate systems, the fields and mathematical support regions of sources, sensors, apertures, apodizers, and other such modules are defined with respect to each module's local (x,y) coordinate origin.  The origins of all the local (x,y) coordinate systems are then related by the following rule:  the local (x,y) origin of any module "lines up" with the origin of its neighboring module, unless the modules are separated by a TransverseVelocity block that generates an offset (static or dynamic).  In a few cases, e.g., PointSource, a module may itself provide static decentering parameters with respect to the local module origin, but in most cases transverse offsets must be achieved using a TransverseVelocity block placed between modules.  When a WaveTrain system contains more than one TransverseVelocity block, the offsets add vectorially.

The internal workings of WaveTrain do not define any global (x,y) origin.  However, the user will probably find it clearest to mentally set up the problem in terms of a global coordinate system, usually fixed with respect to the earth.  Then, the expressions for the relative velocities and positions required by the WaveTrain modules can be derived fairly simply.  As an example, consider the following motion specifications which form the basis for the WaveTrain examples to be diagrammed in the remainder of this section.
Example motion specification:
(1)  A global coordinate system fixed with respect to the earth.
(2)  A global z axis (nominal propagation direction) along a specified elevation angle. 
(3)  A uniform horizontal atmospheric wind, with velocity  v = (vx, vy) = (0, wy)  with respect to the global coordinate system.  (Bold symbols in this section denote vectors).  Remember that x and y axes can be any two orthogonal directions transverse to z.  By defining v = (0, wy), we have associated y with the horizontal direction that is perpendicular to our propagation direction z.
(4)  A source with velocity v = (vx, vy) = (0, 0)  with respect to the global coordinate system.
(5)  A receiver subsystem whose velocity v = (vx, vy) = (vRx, vRy)  with respect to the global coordinate system.

In the following System Editor screenshot, we begin to build a WaveTrain system that incorporates the above motion specifications.  We will build the system incrementally, and we will consider some variations in behavior related to the type of source we use.  We begin by using a PointSource, a pair of TransverseVelocity blocks sandwiched around an AtmoPath propagator block, and a receiver group consisting of a Telescope and Camera.  (Side remark:  Alhough not essential for present purposes, the user may wish to better understand the functions of Telescope and Camera in the WaveTrain system.  Briefly, WaveTrain's Telescope is simply a combination of a Focus and an Aperture.  The focus is used to force Camera's focal plane to be conjugate to something other than infinity.  See "Using the Camera module" for details). 

The block i/o connections designate the wave emanating from the source to be "outgoing".  Consequently, in WaveTrain terminology, this source is at the "platform" end (negative-z end) of the propagation path, while the receiver group is at the "target" end (positive-z end).  As defined earlier, the platform-target orientation is significant when defining the signs of parameters in TransverseVelocity.  Now, given the global motion specifications (1)-(5), and the direction conventions just reviewed, we define the input parameters of the TransverseVelocity modules in terms of the following relative velocities:
(a)  Velocity of PointSource with respect to AtmoPath (i.e., the air medium):  v01 = (0, -wy)
(b)  Velocity of AtmoPath (the air medium) with respect to Telescope (and to all other receiver modules):  v02 = (-vRx, +wy - vRy).  
The System Editor diagram shows the components of v01 and v02 inserted into the (vx, vy) value fields of the TransverseVelocity parameter lists.  Users should study this example carefully and understand how the v01 and v02 relative velocities are consistent with the definitions stated earlier for the TransverseVelocity (vx, vy) parameters.  A user who understands the above basic example will be able to generate any elaborations, such as adding a non-zero velocity for the source. 

In the preceding example, the t=0 offsets in both TransverseVelocity blocks have been set to zero: (x0, y0)=(0,0) in each block.  That is, at t=0, the local z axes of all modules are exactly colinear.  These specifications were not explicitly defined in the original global specs (1)-(5).  Depending on problem details, the user may wish to key the initial offsets (x0,y0) to the propagation delay time (prop distance)/c.  For example, one may wish the detector center to be at a specific transverse location at the time the first light (emitted at t=0) reaches the detector:  in that case, the values of the (x0,y0) parameters must be expressed in terms of the transverse speed and the delay time.

Uniform atmospheric wind:

In the above example, note a key point regarding the uniform atmospheric wind specification.  It was possible to model the uniform wind, plus the effects of platform and target motion, all using the TransverseVelocity blocks.  That is, to model uniform atmospheric wind, it is not necessary to enter any wind specifications in the AcsAtmSpec function (recall the overview of transverse motion methods).  The velocities entered in AcsAtmSpec are usually reserved to represent a true atmospheric wind which varies along the propagation path, although the preferred modeling practice is up to the user.

Use of the Slew module

Consider again the WaveTrain system defined in the preceding System Editor picture.  The drawing at right shows the local coordinate axes of the platform (P) and the target (T) at two time instants.  Because the parameters (x0,y0) = (0,0) in both TransverseVelocity blocks, the local z axes are colinear at t=0.  However, at later times, the telescope/camera's z axes get progressively further displaced from the source's z-axis.  The drawing at right shows the situation in the y-z plane.  Now, the PointSource module has a special property relative to any other source type in WaveTrain.  In particular, regardless of the transverse offset between PointSource and a sensor, the WaveTrain machinery will always compute a propagated field whose support is centered at the origin of the sensor's effective pupil plane.  To put it simply, PointSource operates in such a fashion that it always "points" at a sensor, regardless of the sensor local origin's transverse offset.  This behavior is not obligatory for numerical calculation, but it is certainly consistent with the typical interpretation of "point source".

Slewing the transmitter:

By way of contrast, suppose that we replace PointSource in the above system by GaussianCwLaser (or UniformWave, or in general any "extended" source module available in WaveTrain).  In that case, the phase in the exit plane of the source gives the source wave a uniquely defined direction, which is usually nominally parallel to the local z axis of the source module.  Since such a beam has a finite extent, within diffraction, it is then possible that the beam can miss the sensor if the transverse displacement is large enough.  If that effect is what the user is trying to model, then nothing further needs to be done.  However, the more usual physical situation is that the transmitter is slewing at a fixed angular rate, in order to track the target.  That is, within the perturbations caused by turbulence, we want to keep the transmitted beam pointed so that its centerline moves with the target.  The modified WaveTrain system in the following picture shows how this is done.  We have modified the previous system by replacing PointSource with GaussianCwLaser, and by adding a Slew module immediately after the source:

The velocity parameters that were already specified in the TransverseVelocity blocks now dictate the angular rates and the initial (t=0) offsets that we must enter in the Slew block parameters.  The velocity of the target relative to the transmitter is vrel = (vRx-0, vRy-0), independent of the uniform wind wy.  Therefore, the Slew block will cause the transmitted beam to (nominally) track the target if we specify the following angular rates:
     (xtiltDot, ytiltDot) = (vRx / Range, vRy / Range) rad/s,
where Range is the propagation range.  (The variable Range is also a parameter entry in the AtmoPath block in the above system, but those parameters are not pulled for viewing in the present pictures).  This angular rate specification keeps the beam slewing at the same rate as the target.

Additionally, we also wish to center the beam on target (strictly speaking, on the local coordinate origin of the target's entrance pupil).  Recall that in the two TransverseVelocity blocks, we specified both t=0 offsets (x0,y0)=(0,0).  This means that the local z axes of source and receiver pupil are colinear at t=0.  Consequently, to make the emitted beam's centerline strike the center of the receiver pupil, the Slew must allow for propagation delay by pointing ahead of the present receiver position by the following angles:
     (xtilt0, ytilt0) = (vRx / speedOfLight, vRy / speedOfLight) rad.
Note that the Slew block parameters (xtilt0, ytilt0) are not the lead-ahead angles per se, but rather are defined as the Slew angles at t=0.  Because we had set (x0,y0)=(0,0) in both TransverseVelocity blocks, we have the simple situation that the initial offset slew angles (xtilt0, ytilt0) are numerically equal to the lead-ahead angles.

Slewing the receiver, for different types of WaveTrain sensor:

The modified system that we just created keeps the GaussianCwLaser beam pointed at the target, and centered on the target's entrance pupil.  However, the Camera subsystem still has its local z axis parallel (though offset) to the local z axis of the source laser.  Therefore, the focal-plane intensity spot reported by Camera will march progressively more and more off-axis as time proceeds, and may go entirely off the focal-plane sensor, depending on the specified size of that sensor.  If the modeling intent is to keep the Camera z-axis pointed at the source as the motion proceeds, then another Slew module must be added just in front of the Telescope subsystem.  The angular rate parameters of that Slew module would need to be
     (xtiltDot, ytiltDot) = (-vRx / Range, -vRy / Range) rad/s.  
With this additional Slew module at the receiver, the Camera focal plane spot will stay centered (within atmospheric turbulence) on the Camera sensor plane local origin.  The final system, with two Slew blocks, is shown in the following figure:

In addition to Camera, the other two principal WaveTrain sensor modules are TargetBoard and SimpleFieldSensor.  The user should understand the effect of receiver slewing in each case.  If the receiver in the above system consisted of a TargetBoard, instead of the Telescope-Camera combination, then slewing the receiver would have no effect.  In the case of TargetBoard, the sensor just measures irradiance of the propagating beam in the plane of the target-board, and that is essentially unaffected by the range of offset angles that one can treat in WaveTrain.  We expand on this point in the following paragraph.

If the receiver consisted of a SimpleFieldSensor, instead of the Telescope-Camera combination, then slewing the receiver would have no effect on the irradiance, but it would have an effect on the sensor's output phase.  In the case of SimpleFieldSensor, the sensor outputs the complex field of the propagating beam, in the plane of the sensor.  The irradiance formed from the complex field output should behave just like the output of TargetBoard, hence is unaffected by the receiver slew.  However, the phase computed from the output of SimpleFieldSensor is sensitive to typical offset angles modeled in WaveTrain.  As an example, suppose the local origin of the target plane is offset by 1 mrad (a very large angle for most WaveTrain purposes) from the transmitter local origin.  Suppose further that the optical wavelength is 1 mm, the sensor transverse span is 10 cm, and the beam phase is roughly planar and perpendicular to the line from source to sensor.  Then, if the sensor were precisely parallel to the x-y plane, it should see a phase difference of (1E-4m/1 mm)=100 waves across the 10 cm of sensor span.  On the other hand, if a compensating Slew of (-1) mrad were inserted just prior to the sensor, then the sensor would report zero waves of phase difference across the sensor span (in the plane-wave approximation).  In contrast to the phase dependence, the irradiance projection factor is for all practical purposes 1.0 with or without the receiver slew. 
(Side remark:  Actually, the irradiance projection factor is completely ignored by WaveTrain.  This is really not a defect, because other modeling limitations in WaveTrain would be exceeded long before the irradiance projection became measurable).

We introduced the functions of the Slew module only after switching from PointSource in the original system example to GaussianCwLaser in the second system example.  We chose that order of presentation because we wanted to treat transmitter slewing before receiver slewing.  Near the beginning of the slew section, we explained that PointSource is coded in such a way that slewing the transmitter is not necessary.  But now, based on the above sequence of examples, the reader can probably see that receiver slewing is still necessary for PointSource, if we use the Camera sensor and we wish to keep the image point centered on Camera's focal plane.

Slew and Tilt:

In terms of the internal workings of WaveTrain, the Slew subsystem is simply a (uniformly) time-varying Tilt subsystem.  To understand modeling limitations, the WaveTrain user should have some basic understanding of how tilt is implemented in WaveTrain: this is discussed in the section "How tilt is modeled".

TransverseVelocity, Slew and Tilt for counterpropagating beams:

The above example has only an outgoing optical wave, but more complicated systems can simultaneously have outgoing and incoming waves.  Notice that the TransverseVelocity and Slew (or more basically, Tilt) modules have input/output connections for both directions of waves.  Suppose that, after setting up the velocity and slew parameters in the above system based on consideration of the outgoing wave, we now decide to add an incoming wave, by adding a source at the original target end, and a sensor at the platform end.  The WaveTrain sign conventions are consistent in the sense that the existing transverse velocity and slew specifications are still appopriate: we need not go through that setup procedure twice.

Slew tilts the wave, not the sensor:

In order to thoroughly understand and apply the WaveTrain rules and conventions regarding slew and tilt, it will be helpful for the user to understand the following.  In the internal workings of WaveTrain, the receiver-end slew added to the above system acts on the propagating wave, not on the sensor per se.  While it is acceptable to think of the slew as causing the central line of sight of the sensor to rotate at the rate (xtiltDot, ytiltDot), what is actually happening at the code level is that the tilt parameter associated with the passing wave is adjusted by the specified angle or angular rate.  In this connection, we must remember WaveTrain's sign convention for tilt, which also governs the Slew module signs.

An apparent paradox related to transverse motion and wavefront tilt

When a simulation involves relative motion, we have the possibility of analyzing the problem from the point of view of different reference frames.  This can lead to some apparent paradoxes involving the numerical value of wavefront tilt measured by a sensor.  As we have seen in the preceding sections on sensor timing and transverse motion, WaveTrain combines the following two concepts:  (a)  propagation delay (finite light speed) is always applied when computing the optical field that impinges on a sensor at any time t;  (b)  coordinate and velocity transformations between reference frames are assumed to obey the Galilean model.  Additionally, the propagation delay is approximated by (L/c), where L is the z-separation of source and sensor local origins.  Reasoning based on the preceding concepts, exemplified in the preceding discussions of transverse motion and slew, is generally adequate in the regime where transverse velocities of sources, targets and medium are small compared to the speed of light, c, and where the transverse offsets are small angles.

Despite the general adequacy of the {delay + Galilean transformations} model, it is possible to generate an apparent paradox with this reasoning, regarding an offset in the observed value of wavefront tilt.  We mention the issue in this Guide because several WaveTrain users, both external and internal to MZA, have been puzzled by it.  Consider the following simple propagation problem:  (a) a receiver detects waves emitted by a point source, in the absence of atmospheric turbulence;  (b) there is relative transverse motion with uniform velocity, and the transverse offset between local coordinate origins is 0 (local z axes colinear) at time t = L/c.  First, consider the situation in the rest frame of the receiver.  The following sketch shows the transmitter position at several instants, and shows the "first light" wavefront striking the receiver pupil (assuming emission begins at WaveTrain's usual t=0):

From this sketch, we conclude that tilt of the received wavefront at t=L/c is ytilt' = -V_y/c  (the minus sign is consistent with the WaveTrain tilt sign conventions).  If the corresponding WaveTrain system is constructed with PointSource, AtmoPath, and SimpleFieldSensor or Camera blocks, the user can confirm that this is the tilt answer reported by WaveTrain.  In fact, the reasoning related to the delay time from the point of view of the sensor that led to the above sketch and conclusion is exactly what WaveTrain does internally.

Now the paradox arises as follows.  Let us consider the situation in the rest frame of the source.  The following sketch shows the receiver position at several instants.  From this point of view, the

wavefronts anywhere along the z axis are perpendicular to z, so at the instant t=L/c it appears that the receiver should report ytilt = 0.  This clearly contradicts the result inferred from the first approach.  In an auxiliary document, we discuss this paradox at greater length, from several other points of view, and we argue that the first result (the WaveTrain result) is the correct one.

Transverse and longitudinal motion

All the commentary in this section applied to transverse motion.  Issues relating to longitudinal motion are of a different character, and are discussed in a separate section.

How tilt is modeled

In order to work confidently with offsets, slews and other tilt-related modules, the user should have a basic understanding of how overall tilt is internally represented in WaveTrain.  Some WaveTrain modules that add tilts to a wavefront offer the user a choice of methods for representing the tilt, while other modules offer no choice, using one method only.  Consider the basic Tilt module, whose i/o and parameters are shown below left.

Notice the boolean (type "bool") parameter named "applyToField", which can be assigned the values "true" or "false".  This offers the user a choice in how to internally represent the tilt angle that Tilt applies to the passing optical wave.  If "applyToField" is set to "true", then the module will multiply the incident complex field by a phasor of the form exp[ ± i(2p/l)(Dq_x x + Dq_y y) ].  If "applyToField" is set to "false", then Tilt will not apply the tilt phasor, but rather will add the present tilt increment to the so-called "tilt register" for the wave in question.  Unless the user's application explicitly requires otherwise, the normal setting for "applyToField" should be "false" (note this is the default setting when the module is initially added to a system):  it is almost always preferable to carry overall tilt information separately from the remaining complex field array.

The difficulty that arises when "applyToField" is "true", is that modest tilts can cause impractical sampling requirements for the numerical propagation mesh.  In a general WaveTrain diffractive propagation module, the incident complex field array (part of the "wavetrain") is input to a Fresnel propagation operator.  Suppose now that we wanted to explicitly apply a tilt of 100 mrad to the phase of a plane wave of wavelength 1 mm, prior to applying the propagation operator.  As shown in the sketch at right, to sample the initial tilted wavefront with even marginal adequacy would require a mesh spacing as small or smaller than dy = (l/2)/q = 5 mm.  This spacing may be considerably denser than required by the other sampling constraints;  furthermore, tilt angles of interest for WaveTrain problems can easily exceed this 100 mrad example.  To avoid potentially severe sampling difficulties of this type, WaveTrain exploits a known mathematical property of the Fresnel propagation operation.  If one applies the Fresnel propagator (along z) to a wavefront with a specified tilt factor, the resulting complex field is exactly equal to that obtained by propagating the tilt-removed field, shifting that result transversely, and finally applying a tilt phasor.  The latter method is what WaveTrain uses when "applyToField" = "false" in Tilt and similar modules.

By way of contrast to Tilt, there are some closely related modules where the user is given no choice regarding the internal tilt representation.  For example, the Slew module, which is illustrated on the right side of the previous diagram, is at the WaveTrain code level simply a time-varying Tilt.  However, from the i/o and parameter lists, we see that Slew provides no "applyToField" option:  WaveTrain automatically uses the concept "applyToField" = "false" in Slew.  The following section further discusses the connection between tilt representation and the required size of the numerical propagation mesh.

Transverse displacement and size of propagation mesh

An important feature of WaveTrain is that the required size of the optical propagation mesh is, in one important aspect, decoupled from the transverse displacement or motion of sources and sensors.  This feature is closely connected with WaveTrain's methods of modeling overall wavefront tilt.  Before continuing with the present section, the reader should quickly review the previous section on tilt modeling, whose essentials form the background for the present section. 

Consider again one of the WaveTrain systems used previously to illustrate transverse motion and slew.  Suppose that:
(a)  the transmitter-receiver z-separation is 100 km, and the receiver velocity relative to the transmitter is vRy = +100m/s;
(b)  the aperture radii of both the Gaussian laser and the receiver telescope are 0.5 m;
(c)  at t = 0, the receiver and transmitter local origins have zero transverse offset (x0 = 0 = y0 in both TransverseVelocity modules); 
(d)  we wish to simulate the receiver signals until t = 0.1s .
At the end of this time interval, the target subsystem center will have a y-offset of 10 m and 100 mrad relative to the source center.  In accordance with WaveTrain's modeling of overall wavefront tilt, the transmitter-end Slew module does not multiply the exiting complex field by a tilt phasor.  Therefore, it is not necessary for the optical propagation mesh to sample the 100 mrad initial tilt or to contain the 10-m final offset between source and sensor.  It is only necessary for the propagation mesh to satisfy the sampling requirements of the zero-offset geometry.  The zero-offset mesh equirements are influenced by the transmitter and receiver aperture diameters, the propagation distance, the wavelength, the integrated turbulence strength, and the spatial spectrum of the initial complex field, but not by the motion-induced offsets in the system.  The time-varying offsets are all handled internally by appropriate transverse shifts, and by application of tilt phasors just prior to sensing, if the sensor type requires it.   

Notice in the preceding sentences that we said the propagation mesh requirements are influenced by the spatial spectrum of the initial complex field.  In particular, if for some reason the initial complex field contains a large overall tilt, then the mesh must be dense and large enough to be able to adequately sample this field for input to the propagator.  But, the point is that WaveTrain's method of handling motion offsets and slew is designed to avoid the impractically large propagation mesh dimensions that would be needed if the associated tilt factors were always represented in the pre-propagation complex field.

CAUTION:  WaveTrain's "applyToField"="false" method cannot by itself solve all tilt-related sampling problems.  We stated above that the tilt carried in the so-called "tilt register" is finally put into the complex field just before sensing occurs.  Now if the sensor is of a type that is sensitive to the incident phase in the sensor pupil (e.g., SimpleFieldSensor or Camera), then of course inadequate sampling of that phase will produce incorrect phase results.  However, this problem is usually easy to circumvent, because a pre-sensor Slew can be used to orient the sensor so that the pupil plane is more or less parallel to the incident tilt.  This issue was already discussed in a somewhat different form in one sub-section of the transverse-motion and slew introduction.

Transverse displacement and size of phase screens

Atmospheric turbulence models and the specification of turbulence phase-screen strengths and positions is discussed in another section.  However, the desired size of the phase screens is more closely related to transverse motion, so we discuss that subject now.

The specification of the turbulence phase screen mesh parameters (dimension and spacing) is a separate step from, though logically related to, the propagation mesh specification.  Desired screen mesh parameters are linked to the propagation mesh as well as to the transverse displacement of transmitter, receiver and air mass during the simulation time span.  The screen mesh parameters are specified via parameters in one of the propagator modules such as AtmoPath or GeneralAtmosphere.  These two modules are shown below, with their i/o and parameter lists pulled down. 

The concepts by which the screen meshes are specified in the various propagator modules are identical, but the parameter name notation and grouping differs slightly from one module to the next.  Once the user understands the concepts, the naming variations should not cause any confusion.  We will explain the key ideas in terms of the AtmoPath nomenclature.  The relevant parameters in AtmoPath (see above figure) are the two groups {xp1, xp2, yp1, yp2} and {xt1, xt2, yt1, yt2}, plus the parameter screenDxy.  The index numbers "1" and "2" should be understood as "min" and "max":  thus, the coordinates {xp1, xp2, yp1, yp2} define a rectangular region at the platform (p) side of AtmoPath, while the coordinates {xt1, xt2, yt1, yt2} define a rectangular region at the target (t) side of AtmoPath.  The sketch at right illustrates the y dimension.  (Note that the parameter values entered in the above AtmoPath diagram (third column in the parameter list) are merely the default values that are presented when one initially pastes AtmoPath into a user system.) 

Once the user specifies values for the p-side and t-side rectangular regions, WaveTrain conceptually connects the endpoints by straight lines (dashed lines in the sketch), forming in two dimensions a rectangular frustrum.  Finally, at the designated z coordinates of the phase screens (zs_k in the sketch), WaveTrain creates phase screens that span the interior of the frustrum (as indicated one-dimensionally in the sketch).  The rectangular frustrum algorithm is a general method for more or less optimizing the required sizes of the successive phase screens.  In sum, by specifying rectangular x-y regions at the platform and target ends of the propagator module, the user implicitly specifies the size of all phase screens that will be used in that propagator module.

How large should the p-side and t-side rectangular regions be?  The rectangles at the two ends must be at least as large as the propagation meshes used, and frequently should be larger, for two reasons.  First, as the transverse positions of platform, target, and air mass evolve (assuming there is motion), the optical beams sample different portions of the phase screens.  Ideally, the size of the p-side and t-side rectangular regions would be chosen so that at a given screen z the screen spans the entire width swept by the beam during the simulation.  In practice this may not be feasible for long simulation times, so WaveTrain has the following provision.  If the user-specified size of a screen is insufficient to span the area required by transverse motion, then WaveTrain automatically wraps the screen.  Equivalently stated, whatever the user-specified size of the screen, WaveTrain will treat that screen as a periodic function whose period is the screen "size" specified by the user.  As a result, any optical beam will always have some phase perturbation to sample, although that perturbation may repeat itself in time at a particular screen location.  After we illustrate screen setup with a numerical example, we will discuss further how to avoid overall periodicity of the propagation results when we specify undersized rectangular regions.

There is also a second reason for making screen sizes bigger than the propagation mesh, which has nothing to do with motion.  The issue here is a defect of the conditioned-white-noise method of generating 2D random functions.  We discuss this second issue a bit more in a later section on screen details.

Numerical example of screen width specification based on motion 

Let us consider a numerical example to illustrate the screen mesh specification.  Consider again one of the WaveTrain systems used previously to illustrate transverse motion and slew.  We repeat the system diagram here:

Suppose that:
(a)  The transmitter-receiver z-separation is 100 km
(b)  The platform velocity relative to earth is (0, 0)
(c)  The receiver velocity relative to earth is (vRx, vRy) = (-20, +100)m/s
(d)  The true-wind velocity relative to earth is (0, wy) = (0, +10 m/s)
(e)  At t = 0, the receiver and transmitter local origins have zero transverse offset (x0 = 0 = y0 in both TransverseVelocity modules) 
(f)   We wish to simulate the receiver signals until t = 0.1s (= Tsim)
(g)  The propagation mesh parameters propnxy (dimension) and propdxy (spacing) have been specified as discussed elsewhere, and for brevity we define DXYprop = propnxy * propdxy.  (The x and y specifications of the propagation mesh are not required to be equal, but that is a common case).  Suppose that DXYprop = 4 m has been specified.

We discussed in a previous section how the motion specifications (b)-(e) translate into the (vx,vy) and (x0,y0) value specifications that have been entered in the third columns of the two TransverseVelocity blocks.  We are now in the process of determining the turbulence screen parameter values to be entered in AtmoPath.  The key facts are:
(1)  At the platform (z=0), the total displacement of the source modules relative to the atmosphere during the simulation time is (DXp, DYp) = (0, -wy*Tsim) = (0, -1.0) m. 
(2)  At the target end, the total displacement of the atmosphere relative to the target modules during the simulation time is (DXt, DYt) = (-vRx*Tsim, [wy-vRy]*Tsim) = (2.0, -9.0) m.  
(3)  The propagation mesh spans (DXYprop, DXYprop) = (4.0, 4.0) m.  As explained elsewhere, because of WaveTrain's motion/wavefront-tilt procedures, we can think of the propagation mesh as having zero offset at all times despite the transverse motions.

Combining the maximum motion offsets with the size of the propagation mesh, i.e, the facts (1)-(3), we can fix phase screen sizes (regardless of their z locations) by specifying the following rectangular regions in AtmoPath:
(A)     (xp1, xp2) = (-DXYprop/2, DXYprop/2)                               = (-2.0, 2.0) m
          (yp1, yp2) = (-DXYprop/2, DXYprop/2 + | wy*Tsim |)         = (-2.0, 3.0) m
          (xt1, xt2)   = (-DXYprop/2,  DXYprop/2 + | vRx*Tsim |)        = (-2.0, 4.0) m
          (yt1, yt2)   = (-DXYprop/2,  DXYprop/2 + | wy-vRy |*Tsim)  = (-2.0, 11.0) m.
For each pair of coordinates, we have added the absolute value of the relevant motion displacement to the upper bound of the zero-offset propagation mesh.  Adding the magnitudes in this way is not the only viable approach, but it has one significant advantage.  First, note that the screen periodicity discussed earlier means that (xp1, xp2) and the other pairs can be extended in either direction:  it is not obligatory to extend the rectangular regions in the actual direction of motion.  The principal advantage of using the absolute value method illustrated in (A) is that the algebraic combinations remain valid if one later changes the signs of the various velocities when executing parameter studies of the system behavior. 

The alternative method, which might initially seem more straighforward, is illustrated by the following specification:
(B)     (yp1, yp2) = (-DXYprop/2 - wy*Tsim, DXYprop/2)
If wy = +10 m/s, as in the original numerical specification, then the yp1 assignment in (B) explicitly accounts for the fact that a screen located at the platform would move towards +y by the amount DY = wy*Tsim, relative to the platform.  But now a potential problem arises:  suppose we defined yp1 algebraically as in (B), elevating the wy variable up to the runset where a numerical value is assigned.  Suppose further that at some later time we are exploring parameter variations and we decide to assign a negative value to wy.  Inspection of the (B) format shows that an error occurs unless we move the wy*Tsim contribution from the yp1 to the yp2 term.  Similarly, in the term (wy-vRy) a net sign change can occur depending simply on whether wy is less or greater than vRy.  As a general principle, it is inconvenient and error-prone to set up the system and runset so that changing the numerical value of a runset parameter requires us to make some compensating setting change lower down in the system hierarchy.  For some system properties it may become too involved to maintain complete generality in this respect, but for the screen specifications the absolute value method (A) provides an easy solution.

In the specifications (A), we concluded with numerical values to give a sense of typical numbers.  However, we would generally want to enter the algebraic setting expressions in AtmoPath, and to elevate variables like wy, vRy, etc. to the runset level:  that makes it easy to perform parameter variations by just changing a few numbers in the runset.  Detailed syntax rules and elevating procedures are discussed in other chapters; to conclude the present discussion we just point out one pertinent detail, namely that |x| must be entered in WaveTrain setting expressions as fabs(x).

Actual screen dimensions, computation time and memory requirements:

Thus far, the present section has concentrated on specifying the physical span of the turbulence phase screens.  The final parameter required to specify the discrete screens is the mesh spacing, which in AtmoPath is called screenDxy.  Typically, we set screenDxy equal to the propagation mesh spacing designated in some previous expressions as propdxy.  Strict equality of screenDxy and propdxy is not obligatory, but is usually a reasonable choice.

Once the user has specified the spans (xp2 - xp1), ..., and the screenDxy, then the screen meshes are fully specified as far as the user is concerned.  However, WaveTrain makes some further internal adjustments.  At present, WaveTrain generates phase screens by starting with an uncorrelated random process in the frequency domain, spectrally conditioning that power spectrum, and then inverse transforming to obtain the space-domain screen realization.  Since the Fast Fourier Transform (FFT) algorithm is used, WaveTrain adjusts the ratio (xp2 - xp1)/screenDxy upward to the nearest integer having a "nice" factorization for evaluating the FFT.  Thus the screen dimension will actually be slightly bigger than implied by the precise user specifications. 

Screens are only generated once per atmospheric realization, so that even very large screens may have small impact on simulation execution time.  Propagation and motion evolution requires Fresnel propagation from source to first screen, then from screen to screen, then finally from last screen to sensor, for each time step of the simulation, but all with a single pre-computed set of screens (a single atmospheric realization).  Therefore, even if the screens are much larger than the propagation mesh, it is often the case that execution time is dominated by the propagation calculations, and is only slightly affected by the initial generation of the screens.  Of course the screens are used at each propagation step, but after the screens are generated by using the spectral conditioning method then each screen application during propagation is only a simple array multiplication. 

On the other hand, required memory is strongly affected by the specified screen size.  We cannot give specific limits on screen dimensions for various computer configurations, but we can give a few examples of dimensions that have been used with no ill effects.  In the numerical example of screen specification given several paragraphs ago (at the (A) marker), the target-end rectangular region spanned 6x13 m in the XxY dimensions.  Supposing that screenDxy=2 cm, that would imply (prior to the WaveTrain adjustment) a screen dimension at the target end of 300 x 650 points.  This is a modest requirement in terms of modern personal computers.  If we increased Tsim from 0.1s to 1.0 s, then the 6x13 m becomes 24x94 m, or a screen dimension of 1200x4700 points.  This is still doable on a modern PC, but may be approaching the danger zone depending on the user's PC configuration.

Avoiding overall periodicity by various means

We noted above that WaveTrain's phase screens effectively scroll periodically if relative motion requires an optical propagation operation to sample a phase screen beyond its nominal edge.  If all the phase screens repeated with the same frequency, then the optical results at a sensor would repeat exaclty with that frequency, making runs longer than that period useless.  If there is a need to accumulate statistics over longer periods, several approaches can be considered. 

The brute-force approach is to make the screens longer in the direction of motion, but as discussed above this has practical computer limits.

A simple approach would be to do repeated runs with different random number seeds for the screen set.  The repeated runs cannot be joined end to end in post-processing because discontinuous jumps in results would occur at the joints.  However, the method is perfectly satisfactory for accumulating certain types of statistics.

Another possibility is to note that overall periodicity can be mitigated significantly if the screens have different lengths or different transverse speeds.  In that case, even though each screen is repeating periodically, the combined turbulence effect would only repeat over a much longer period, namely the least common multiple of the individual periods.  Although some violation of nature is involved here, for most statistical purposes the approximation is probably quite good.

Longitudinal (z) displacement and motion

WaveTrain has no facility for representing longitudinal motion comparable to the modules provided for representing transverse motion.  In most WaveTrain applications of interest, the longitudinal component of motion does not produce any noticeable change to the measured quantities of interest: it is only the transverse components of the physical velocities that generate the turbulence-related time dependences of modeling interest.  The longitudinal components are insignificant because of the combination of the relatively large propagation distances involved, and the relatively short time spans over which we need to perform the wave-optics simulation.  These approximations are tied to the conventional way in which the frozen turbulence approximation is applied to optical turbulence calculations.

There are several limitations to this physical model.  The first limitation has nothing to do with turbulence, but arises simply because various magnification factors change if the distance changes significantly during the simulation time.  A second limitation is that, as the motion progresses, phase screens nearest the target or platform should drop out of the problem when that part of the air mass is no longer between the platform and target.  Modeling such changes may become important, for example, in simulating a long-enough engagement against a nearby missile moving more or less directly at the platform.  At present, if such effects are important in a WaveTrain simulation, the user must break up the problem into time segments such that the z-range can be treated as approximately constant during each segment.

Despite the absence of longitudinal-motion library modules, there is a significant aspect of longitudinal motion that can be modeled in WaveTrain.  Depending on the range and time scales involved, the principal effect of longitudinal motion may be a Doppler shift.  A physical example is the problem of remote Doppler vibrometry through a turbulent medium.  In problems of this type, we can model the longitudinal motion in terms of temporally-varying phase shifts.  This produces effects such as walking fringes, for example, and WaveTrain does contain modules that can generate these effects.  An auxiliary document contains a detailed explanation of how to model such effects in WaveTrain.  The auxiliary document also discusses in general the extent to which the interference of polychromatic fields can be modeled in WaveTrain.

Optical propagators in Wavetrain

The numerical implementation of wave-optical (i.e., diffractive) propagation is a large subject.  Here in this User Guide, our intent is to specify a few key formulas that outline the concepts and numerical algorithms used by WaveTrain to propagate optical fields from one transverse plane to another.  The discussion here will not fully justify the reasons for choosing one numerical procedure over another, nor will it fully explore the details of the numerical algorthms used in WaveTrain.  What we hope to accomplish in this User Guide discussion is:
(1)  To give the user who has some acquaintance with scalar diffraction theory (and its Fourier-transform representations) a clear general idea of which propagator formulas are used in core WaveTrain propagation modules
(2)  To use the knowledge in item (1) to make the user comfortable with the terminology and logic involved in setting mesh and distance parameters in core WaveTrain propagation modules
(3)  To give the user an overview of WaveTrain's ability to model non-monochromatic versus monochromatic propagation.

One can group WaveTrain diffractive-propagation modules into two categories:
(1)  Fresnel-propagation modules that propagate an optical field from one transverse plane through some arbitrary distance to another transverse plane
(2)  Fraunhofer-propagation modules that take an incident optical field, and then propagate to (or perhaps near) the focal plane of an assumed lens.

The most commonly-used modules that set up or perform Fresnel propagation are PropagationController, AtmoPath, and VacuumProp.  The PropagationController does not actually carry out any propagations, but it can be used for setting key propagation parameters.  AtmoPath is a complicated component that contains phase screen action as well as multiple, sequential Fresnel propagation action.  VacuumProp is more basic in the sense that it carries out one propagation over a single specified distance. 

The most commonly-used module of the Fraunhofer group is Camera.  Another important Fraunhofer-propagation module is HartmannWfsDft, which models a Shack-Hartmann (or plain Hartmann) wavefront sensor.

Theoretical background

Mathematical representation of the optical field

The core WaveTrain propagation procedures apply directly to scalar, monochromatic, paraxial optical fields.  The general mathematical representation of such a field is

(Eq. 1)          Y(x,y,z,t) = U(x,y,z)· exp[ i (kz - wt) ]

where k = 2p/l, w = ck, z is the nominal propagation direction, U is complex, and U(...,z) is slowly varying compared to kz.  Any WaveTrain propagator module operates on an input complex field given in some plane z₁, of the form

(Eq. 2)          U₁(x,y) = A₁(x,y) · exp[ i·f₁(x,y) ]

The output of the propagator module is the corresponding complex field, U₂(x,y), in the specified final plane of constant z₂.  Of course, WaveTrain actually works only with samples of U_1,2 on discrete transverse meshes (x_1i,y_1j)_, (x_2i,y_2j).  The terminology "nominal propagation direction" implies that small tilts or beam spreading around the z direction are supported by the WaveTrain propagation machinery: i.e., WaveTrain makes paraxial approximations.  WaveTrain also contains special provisions for modeling the paraxial region of point-source and rough-reflector optical fields, which would normally spread far outside the paraxial regime. 

In the initial paragraph, we stated that WaveTrain's propagators work, strictly speaking, with monochromatic fields.  WaveTrain can treat the propagation of multiple discrete wavelengths and, to various levels of approximation, the propagation of beams whose optical spectrum has finite (continuous) width.  The subsection on "Non-zero optical bandwidth", located later in the present "Theoretical background" section, outlines some general concepts and procedures that allow WaveTrain to be applied to fields that are not strictly monochromatic. 

The degree to which finite optical bandwidth is supported, as well as the limitations of the scalar, paraxial approximations are complex subjects which are not fully explored in this User Guide.  The WaveTrain limitations are due to analytical approximations in the fundamental formulas, as well as to practical sampling limitations in the numerical discrete spatial meshes and time steps.  By scanning the contents of the User Guide, readers will find other sections that also contain information pertinent to these issues.  But, to a large extent, WaveTrain users must take the description of the wave propagation and sensing methods given in this Guide, and then apply their own physics understanding to determine whether a WaveTrain model can accurately represent a problem of interest.  Sometimes, a bit of specially-directed numerical experimentation will be helpful.  Also, consultation with MZA is available for general help on such questions. 

Excellent general references for the underlying theory of scalar, paraxial, diffractive propagation are
(1)  Goodman, Introduction to Fourier Optics, McGraw-Hill, 1968
(2)  Saleh and Teich, Fundamentals of Photonics, Wiley, 1991.

Fresnel propagation

Propagation in the Fresnel regime between planes  z₁ and z₂ can be expressed in the space domain or the spatial-frequency domain.  WaveTrain's core numerical propagator works in the spatial-frequency domain.  This fundamental propagator formula, to be found in standard texts, is

(Eq. 3):         

The vector denotes the x and y components of spatial frequency (cycles/m), and the overbar notation is used as a shorthand for the (-i) Fourier transform.  In words, this propagator acts in three stages:  (i) compute the Fourier transform of the space-domain complex field at z₁,  (ii) multiply by a quadratic-phase distance-propagation factor in the frequency domain,  (iii) compute the inverse Fourier transform to obtain the space-domain complex field at z₂.

For numerical propagation, WaveTrain uses a modification of this formula wherein a "reference curvature" phasor is factored off from U.  That is, we define the related quantity V, where

(Eq. 4)         

and where z_R is the "reference focus" distance (directed).  (z_R may be set to infinity, in which case V=U).  Substituting (Eq. 4) into (Eq. 3) and regrouping terms yields the propagator formula 

(Eq. 5)        

where the "magnification" factor M = (z_R - Dz) / z_R = 1 - (Dz / z_R).  M may be less than or greater than 1, depending on the sign of z_R.  When M=1, (Eq. 5) reduces to the original (Eq. 3).  The following figure shows why M is called the "magnification". 

The logic in the above paragraph is predicated on the space-frequency mesh constraints of the Discrete Fourier Transform.  The specific computational algorithm used to evaluate DFTs in WaveTrain is the so-called Fast Fourier Transform (FFT). 

Specifying the reference focus in WaveTrain components

The reference curvature factor, or equivalently the mesh magnification factor M, is specified in WaveTrain propagator components via the reference focus distance (directed) z_R.  For example, the key PropagationController or AtmoPath components contain parameters named xReferenceFocus and yReferenceFocus.  Typically, one would set the two to the same value, but WaveTrain allows separate Mx and My specifications in case of highly asymmetric problems.  To use M=1,  x{y}ReferenceFocus should be set to 0.0.  The value 0.0 is a flag here that is interpreted as infinity focus, and this is always the default value in the WaveTrain propagator components.

We emphasize that many (perhaps most) WaveTrain applications can use the M=1 specification.  Particularly if we propagate a beam in the atmosphere for a few hundred meters or kilometers or more (depending on the aperture size), there is no possibility of a greatly reduced focal spot.  In many such cases, there is no need to deviate from an M=1 mesh.  Additionally, there are other factors besides diffraction that need to be considered to determine the mesh sample spacing.  For example, suppose we have a beam that is diverging, but is propagating through significant turbulence along the whole path.  In that case, we probably want to keep the mesh spacing constant as we propagate from turbulence screen to screen.  . 

Fraunhofer propagation

Components like Camera or HartmannWfsDft propagate an incident complex field U₁ to the focal plane of an assumed lens of focal length f.  The propagation formula used in these cases is the space-domain Fraunhofer-regime formula

(Eq. 6):         

As in the Fresnel case, the exp(ikf) factor is neglected.  The DFT (implemented with the FFT) is again used to numerically evaluate the Fourier transform in (Eq. 6);  the implications for the space mesh on which U₂ appears are different than for the Fresnel propagator discussed previously.  These mesh consequences and choices are discussed in the User Guide sections devoted to the camera sensor and the wavefront sensor.

Overall tilt and optical propagation

In a previous User Guide section, we discussed how overall tilts are typically modeled in WaveTrain.  We explained there that large tilts introduced by tilt modules and sensor-source relative displacements are generally tracked separately by WaveTrain, and not incorporated into the propagating U(x,y) as a tilt phasor factor.  This is done to avoid overly stressing sampling requirements in the numerical propagators.  At a sensor, the separately-tracked tilt is finally inserted into the field or irradiance map by using the shift-invariance properties of the propagator. 

Multi-frequency propagation and non-zero optical bandwidth

First, let us emphasize that any number of monochromatic beams of arbitrarily separated wavelengths can be propagated in a single WaveTrain system and run.  To give a physical example of interest in adaptive optics:  it is a simple matter (in terms of the multi-wavelength specifications) to study the performance degradation when a different wavelength is used for wavefront sensing than is used for the science imaging or laser beam projection.  When propagating beams of different wavelengths, key questions are whether these beams interact at all, and if so, whether they add coherently or incoherently at a sensor.  The answer depends (i) on whether a sensor is allowed to see multiple beams, and (ii) on the WaveTrain rules built into the sensor module. 

WaveTrain has been validly used for many situations which go well beyond the strictly monochromatic regime.  Depending on the problem, different approaches and justifications are used.  Without going into details, we list a few concepts and procedures applicable to non-monochromatic cases:
(1)  Accept a completely monochromatic model, realizing that many turbulence and diffraction effects do not change that rapidly with wavelength.  This is completely satisfactory for many narrow-band propagation problems.
(2)  Model a finite-bandwidth beam as a superposition of discrete-wavelength, closely-spaced, but incoherent monochromatic beams.
(3)  Explicitly introduce a slowly-varying envelope function to rigorously model either a finite optical bandwidth, or the dynamic interference between closely-spaced discrete frequencies. 
(4)  Model an extended incoherent source plane in terms of many spatially-separated point sources, whose intensity maps will be added incoherently at a sensor.
(5)  Combine a monochromatic WaveTrain source with specialized WaveTrain rough-reflector models.  Several reflector models in WaveTrain contain features that mock up a finite bandwidth of the illuminating source, to various levels of fidelity.  (I.e., some rough-reflector models in WaveTrain act as specialized "secondary" sources).

Choosing mesh settings for optical propagation

The previous User Guide section on optical propagators gave background information on the propagation formulas used in WaveTrain.  In the present section we complete that discussion by giving guidelines for specifying the discrete propagation mesh parameters that must actually be entered in WaveTrain model setup.  Most prominently, these are the spacing of the mesh and the span (or dimension) of the mesh.

The size and spacing of the propagation mesh must be chosen very carefully; the spacing must be neither too large nor too small, and the mesh size must be large enough to capture the effects of interest, but making it too large can slow the simulation drastically.  To a first approximation the execution time of most WaveTrain models varies roughly as the square of the propagation mesh dimension, so using 512x512 meshes takes roughly four times as long as using 256x 256 meshes.

To choose the mesh size and spacing correctly, there are a number of factors that must be taken into account, including 

• the wavelength(s) of interest, 
• the propagation distance,
• the horizontal extent of the regions of interest at both ends of the propagation path,
• whether a planar or spherical reference wave is used,
• the turbulence strength and its distribution along the path,
• the use of spatial filters and/or absorbing boundaries,
• the physical dimensions and configuration, in "output space", of the sensors used,
• the FFT (fast Fourier Transform) package used.

**********
UPDATE:  An updated, revised and generalized discussion of the mesh selection guidelines that appear below is available in a separate document.  Also, the guidelines in that document have been incorporated in the auxiliary PropConfig tool that is part of the WaveTrain 2010A release.  Users who run the PropConfig tool as part of WaveTrain model building will find a PropConfig tab where suggested mesh specifications are computed, based on the user-supplied propagation scenario and the analysis in the just-referenced document.

**********

There are two main requirements:  First, the mesh spacing must be small enough to adequately sample the variations in phase of both the wavefront and the quadratic phase factors applied by the Fourier optics propagator. To be specific, the phase difference between adjacent mesh points should never exceed half the wavelength.  Second, the mesh extent must be large enough to capture all the propagated light, otherwise, as a consequence of the periodicity of Fourier transform, the light leaving one side of the mesh will reappear on the other side of the mesh;  this effect is known as "wraparound". The two requirements are interrelated, because(1)  the mesh spacing governs the maximum spatial frequency (and hence the maximum propagation angle) which can be represented on the mesh, (2) the sampling requirement for the quadratic phase factor increases linearly with the size of the region of interest, and (3) the mesh extent at each end should generally be at least twice as big as the region of interest at that end.  The propagation distance and the choice of reference wave both affect the magnitude of the quadratic phase factors, and with a spherical reference wave the mesh extent and mesh spacing vary linearly along the path.  Turbulence introduces additional phase perturbations - see How turbulence is modeled - and these enter into the phase sampling requirement.  In some cases it is possible to mitigate wraparound effects, and thereby relax the requirement on mesh extent to some degree using spatial filters and/or absorbing boundaries - see How to use spatial filters and absorbing boundaries.  The physical dimensions and configuration of the sensors used can generally be ignored, because WaveTrain will automatically interpolate the mesh at the entrance pupil as needed; however if you wish to avoid interpolation error you can choose the mesh spacing and offset accordingly.  The FFT package governs what mesh dimensions are permitted, and WaveTrain can be used with several different FFT packages; some allow only powers of two, while others allow any integer which factors into powers of small primes, e.g. 2, 3, 5, and with at least on factor of two.  For the Windows implementation of WaveTrain the FFT package used for optical propagation (provided by Intel) requires that the mesh dimension be a factor of two.   A separate FFT package, more general but less efficient, is used for generating phase screens, but that those dimensions are set automatically anyway.   Whatever the mesh dimension is, for a mesh of dimensioned n x n, by default the (n/2+1, n/2+1) point is assumed to fall on the optical axis.

We've spoken of the "regions of interest" at either end of the propagation path without precisely defining what we meant.  For an optical system, the effective region of interest is closely related to the system aperture, but generally somewhat larger, to account for scattering effects.  For example, when modeling the light incident on the aperture from a point source, we cannot model all of the light emitted by the point source, given the finite size of our meshes, so instead we model only that portion of the light which contributed to the wavefront received at the aperture.  But with turbulence light will be scattered both into and out of the aperture; and with a true point source equal amounts would be scattered in and out on average.  To match this in simulation we must consider a region containing the system aperture, and with enough of a margin on all sides that the light scattered out at the edges will not affect the average intensity across the aperture.  For more details see  modeling point sources.  Similar considerations apply when modeling the light from an extended incoherent source, or a coherent reflection off an optically rough surface.  At the other end of the path it is much the same, except that the physical extent of the object being imaged and/or illuminated plays the same role as the system aperture.

Consider the simplest case, where (1) we would use a planar reference wave, (2) the quadratic phase factors applied by the propagator dominate the phase sampling requirement, and (3) neither spatial filters nor absorbing boundaries are used.  In this case the mesh requirements can be computed easily.  Let l be the wavelength, z be the propagation distance, D the maximum extent of the regions of interest at the two ends,  nx the mesh dimension,  and dx the mesh spacing.  For a given l and dx, the minimum and maximum propagation angle are  -l/dx and l/dx, implying that light from any point on the mesh could expand to fill a region of size lz/dx after propagating a distance z.  To avoid wraparound, the mesh extent should be at least twice that:

nx*dx >= 2lz/dx

This can be put in the form of an inequality for dx in terms of nx, or vice versa:

dx >= sqrt(2lz / nx)

nx >= 2lz / dx²

If D corresponds to the diameter of the aperture of an imaging system, l/D is the classical resolution limit for the system.  Generally, dx should be no larger than lz/D, the projection of that angle over the propagation distance.  Putting that value in for dx in the inequality for nx gives us the minimum permissible nx, given our assumptions. 

 nx_min = 2lz / (lz / D)² = 2D² / (lz)

For example, if l=10^-6m, z=50km, and D=1.0m, 

nx_min = 2*1.0*1.0 / (10^-6*50,000) = 40

However, in order to use that nx, we must use the maximum value allowed for  dx: 

dx_max = lz/D = (10^-6*50,000)/1.0 = 0.05m = 5cm.  

Also, with those choices for nx and dx the mesh extent is just twice the aperture diameter.   For many cases of interest that will not be acceptable, because a denser mesh will be required to properly sample turbulence effects, and because we must consider a region of interest larger than the aperture, as discussed previously.  To decrease dx, we must increase nx, and it goes as the inverse square, so to halve dx, to 2.5cm in this case, we must quadruple nx, to 160.  That would double the mesh extent, from 2.0m (40*5cm) to 4.0m (160*2.5cm), allowing us to enlarge the region of interest.  For most cases involving propagation through turbulence, if we choose a mesh spacing sufficient to adequately to sample the turbulence effects, then choose nx to satisfy nx >= 2lz / dx²; that will give us more than enough room for the region of interest.  Bear in mind that nx must be a valid dimension for the FFT package being used.

So the question arises, how should one pick dx, given the range, wavelength, and turbulence distribution?  There is no hard and fast answer, because it depends on the degree of accuracy required, but as a general rule the maximum permissible dx will vary in proportion to the coherence length, which characterizes the spatial variation of the phase of a wavefront which has been propagated across the  path of interest.  For a planar reference wave we recommend that dx should be no greater than one fourth the minimum of the two plane wave coherence lengths, one computed in each direction.  For a spherical reference wave we recommend that the dx at each end should be no greater than one fourth the plane wave coherence length computed in the corresponding direction.  But for maximum surety, when modeling a propagation scenario different from those you've modeled previously, it is always a good idea to double-check that the dx you have picked is small enough.  To do this, pick a few of the more stressing cases you plan to model, and run simulations both using the dx you hope will work, and also using a smaller dx, with a correspondingly larger nx.  Compare the results - whatever results are relevant to your application - and use the differences between the corresponding runs to estimate the margin of error.  As an example, below are shown the aperture plane intensity and phase obtained using three different choices of nx and dx for the same propagation scenario.  

Incidentally, these results were generated using WtDemo, the system model created in the course of our step-by-step tutorial.  The case we used approximates typical conditions at the  Airborne Laser Advanced Concepts Testbed (ABL ACT) atop North Oscura Peak, on the White Sands Missile Range, in New Mexico.

When using a spherical reference wave the requirements pertaining to mesh extent and mesh spacing are much the same, but you now have an additional degree of freedom, the placement of the point to which the reference wave is converging to or diverging from, and that can sometimes be useful, especially when the region of interest is much larger at on end of the propagation path than it this at the other.  But the sampling requirements must still be satisfied, and the mesh spacing increases in direct proportion to the mesh extent, so that will often be the limiting factor.  Also, it is important to remember that since the reference wave is now curved, the phase difference between the reference wave and a wavefront with similar curvature is reduced, which tends to ease the sampling requirements, but the phase difference is increased for wavefronts that are basically flat or of the opposite curvature.  It can be shown that the reference wave which minimizes the mesh dimension required to adequately sample spherical waves propagating in both directions is precisely that which projects the region of interest at one end to that at the other.  Unfortunately there is no similarly simple criteria to ensure that turbulence effects are adequately sampled, but, as with planar reference waves, you can make an educated guess, based on the coherence length in each direction, then double-check. 

WaveTrain supports rectangular propagation meshes - ny need not be equal to nx.  Both, however, must satisfy all sampling requirements, but the requirements for the two axes may differ, because the extent of one or both regions of interest may be greater in one direction than in the other.  At this time the spacing in both directions must be the same (i.e., dx = dy).  Rectangular meshes may be used with either planar or spherical reference waves, the latter subject to the above caveat.  It would be straightforward to add support for differing spacings in the two directions, and we could also add support for reference waves with different curvatures in x and y, both of which may be useful in modeling imaging and/or illumination of objects much longer in one direction than the other.  If you think those capabilities might be important for your application, please contact us.

Once you have determined the mesh dimensions and spacing you wish to use, you need to put that information into your system model.  This can be done using either of two components  AtmoPath (the component usually used  to model propagation through turbulence), or PropagationController, which gives you more detailed control.  AtmoPath actually contains two PropagationControllers, inside it, one for each propagation direction, but most of their parameters have been hardwired, to make AtmoPath simpler to use.  The reference wave is planar, the propagation mesh is square, and no spatial filtering or absorbing boundaries are used.  The default modeling approaches for both point sources and speckle are used, both of which make use of the parameters superApDiameter and edgeSigma, which the user can specify.  For details, see How point sources are modeled and How speckle is modeled.  When AtmoPath is used, all propagations in both directions are modeled using all the same modeling parameters.  Because of these simplifications, only four optical modeling parameters remain to be set: 

propnxy                        the mesh dimension (same in x and y) 

propdxy                        the mesh spacing (same in x and y) 

superApDiameter      used in modeling point sources and/or speckle

edgeSigma                used in modeling point sources and/or speckle

Note: the other parameters of AtmoPath relate to modeling atmospheric turbulence, and their use is described in How turbulence is modeled.

Setting up Fresnel propagations

In the previous section on specifying propagation mesh settings, we discussed the selection of numerical values for a Fresnel propagation mesh.  There are several types of WaveTrain library components that accept propagation mesh parameters and compute propagations, and these systems may be used in various combinations.  The ways in which the combinations are used may be somewhat confusing to new WaveTrain users, so in the present section we illustrate the basic combinations.  Subsequent sections give more details on the input and parameter specifications for the individual WaveTrain components.

The principal confusion that may arise is that some components, in particular AtmoPath and its derivatives, accept both propagation mesh and atmospheric turbulence specifications.  On the other hand, in more advanced WaveTrain work, it may be desirable for users to insert separate components to specify propagation mesh as opposed to atmospheric specifications.  Without further ado, the following figure illustrates several different combinations of WaveTrain library components that could be used to specify the propagation mesh and atmospheric (or vacuum) parameters. 

Bear in mind that, to make complete WaveTrain systems out of the above combinations, one must add source and sensor components.  Now we make some general comments on each of the combinations (A-C):

(A):  The single component AtmoPath can provide complete specification of both the propagation mesh parameters and the atmospheric turbulence parameters.  We recommend that new WaveTrain users start with option (A).  Notice that propagation in both directions ("incoming" and "outgoing") through the same specifications is supported.  Note that AtmoPath subdivides the total specified propagation length into propagation segments between the turbulence phase screens.

(B):  Option (A) can be used to model non-turbulent propagation ("vacuum propagation"), by setting phase screen strengths to zero.  However, for clarity, users may instead wish to use the explicit VacuumProp component.  But, VacuumProp takes only a propagation distance specification, not a complete propagation mesh specification.  Therefore, one or two PropagationController components must be joined to the propagation module.  If propagation will be only one way, then only one PropagationController is needed.

(C):  Option (C) is actually very similar (but not identical) to option (A).  If we descend into the  AtmoPath component, we will see that AtmoPath is actually a "composite" WaveTrain system that consists of two PropagationControllers sandwiching a GeneralAtmosphere component.  That is almost exactly like option (C), except that option (C) allows different propagation mesh specifications in the Controllers for the two propagation directions.  This can be an important degree of freedom for some WaveTrain modeling.  The GeneralAtmosphere is used to provide the turbulence phase screen specifications.

(D):  This is not illustrated in the above figure.  For two-way propagation, another option is to use two completely separate AtmoPath components, one for each direction. 

For certain modeling situations, necessity dictates one or another of the options listed above.  However, in other situations the choice is a matter of user preference. 

Using the PropagationController

As an introduction to the present section, users should review the previous overview section on setting up Fresnel propagations.

PropagationController is a library subsystem that defines the Fresnel propagation mesh, in addition to several other propagation-related parameters.  Every WaveTrain system should contain at least one PropagationController for outgoing waves, and at least one for incoming waves (if the respective waves are present).  However, some commonly-used library systems that specify atmospheric turbulence already contain two PropagationControllers (one for each direction).  The prime example is AtmoPath, which is a composite system consisting of GeneralAtmosphere and two PropagationControllers.  Therefore, it may be unnecessary for the user to explicitly add PropagationControllers to the overall system.  If the options provided in AtmoPath or analogous modules are sufficient for the user's purposes, then no extra controllers are required. 

If a PropagationController is explicitly inserted, it can be placed anywhere along the path between the source and sensor to which it should apply.  A situation that always requires explicit insertion of a PropagationController is a test system that has zero total propagation distance, and therefore contains no AtmoPath or analogous module.  Such a system will usually be a test system used to investigate the behavior of a portion of a full propagation system.  Multiple controllers in a system are also allowed:  this is explained further in a later subsection.

Parameters of PropagationController

The picture below shows the interface of PropagationController.  As we see from the single input and output, one PropagationController applies to one wavetrain (possibly containing numerous separate waves) traveling in one direction, either incoming or outgoing.  We now discuss some of the parameters that must be set.

targetGrid:  this parameter is set by using a WaveTrain library function that defines meshes.  The user should change only the (nxy,dxy) symbols that are arguments of the function:  these define the dimension and spacing of the propagation mesh.  General considerations and restrictions regarding WaveTrain meshes are explained elsewhere.  As usual in WaveTrain when setting parameter values, (nxy,dxy) can be replaced by numerical values right here or the symbols can be elevated (promoted) up the hierarchy.  The argument syntax (nxy,dxy) may be replaced by  (nx,ny,dx,dy) if the user wishes to use an asymmetric mesh.  However, it is important to remember that a "long" mesh dimension is NOT required merely because there is transverse motion in the simulation (the implications of transverse motion for propagation and phase-screen meshes were discussed previously).

x{y}ReferenceFocus:  these parameters allow selection of a planar or spherical reference wave for the Fresnel propagation operations.  Each Focus is a directed distance in meters.  Infinity focus, which is specified to the code by setting Focus=0.0, specifies a planar reference wave.  The subject of reference waves is discussed in more detail in the User Guide section on optical propagators and on the  selection of propagation parameters.

oneTimeSpatialFilter, spatialFilter, absorbingBoundary:  these are advanced options that can be used to specify certain anti-aliasing or wrap-around measures in the Fresnel propagation FFT calculations.  A few further remarks on these subjects may be found in the User Guide section on selection of propagation parameters.  The NullFilter() settings shown in the above picture disables these options.  User desiring further details of the available settings should contact MZA.

pointSourceModel:  this setting only pertains to the operation of WaveTrain's PointSource (and derivative) source modules.  The discrete numerical modeling of propagation from a point source poses special problems, and the general issues are discussed in a separate section.  In brief, WaveTrain offers two methods of modeling point sources, and the desired method is selected by setting the value of the pointSourceModel parameter.  For most purposes, we recommend the setting DEFAULT_PSM, as shown in the above illustration (note that PSM = Point Source Model).  This selects MZA's back-propagation method of modeling the point source.  If DEFAULT_PSM is used, then the associated parameters superApDiameter and edgeSigma also come into play. 

superApDiameter:  the diameter, in meters, of the "super-aperture" used in the  back-propagation method of modeling point sources (pointSourceModel = DEFAULT_PSM).  The super-aperture diameter should be somewhat larger than the diameter of the actual receiver aperture.  There is no exact rule, but a factor of 1.5 is typically satisfactory.

edgeSigma: a roll-off width parameter, in meters, that modifies the "super-aperture" used in the  back-propagation method of modeling point sources.  A non-zero Gaussian rolloff is added to the radius of the uniform-amplitude region that is back-propagated to form the "point" source.  There is no exact rule, but a typical setting would be edgeSigma =  several times the propagation mesh spacing.

speckleModel:  this setting only pertains to the operation of the rough-surface reflector modules, such as CoherentTarget, IncoherentReflector, and PartiallyCoherentReflector.  The discrete numerical modeling of propagation from an optically-rough reflector poses special problems, and the general issues are discussed in a separate section.  The setting options for speckleModel are: (a) DEFAULT_SM,  (b) DELTA_CORRELATED_SM.  We recommend the option DEFAULT_SM (note that SM = Speckle Model):  this setting applies a super-aperture back-propagation concept to the wave propagated from a rough reflector.  This means that the parameters superApDiameter and edgeSigma are also relevant to light emanating from rough reflectors, if DEFAULT_SM is selected.

useDispersion:  this setting, whose allowed values are true or false, determines whether a wavelength dispersion model will be applied to the atmospheric propagation.  The true setting is only applicable if at least two different wavelengths are present in the simulation system.  If dispersion is applied, then nominal propagation axes will be appropriately "bent" so that beams of different colors sample slightly different portions of the atmospheric turbulence screens.  The path "bending" is done relative to one of the system wavelengths, which the user specifies as the nominalWavelength

nominalWavelength:  see the useDispersion parameter. 

Use of multiple PropagationControllers

For reasons of convenience or user preference in building systems, it is allowed for a WaveTrain system to contain more than one PropagationController (counting the ones inside AtmoPath or analogous modules) for a given direction of propagation.  If there are multiple controllers for a given direction, then the one closest (downstream) to a source overrides the settings in the others.  Sometimes redundant controllers are inserted simply as a matter of user preference, but it might also happen that one wants to use different meshes or other settings to propagate different sources.  The following figure gives an example:  

In the model shown above, propagation from pointsource and pointsource2 is controlled by the PropagationController inside AtmoPath, but propagation from pointsource3 is controlled by the extra explicitly inserted PropagationController.  All this follows from the rule "controller closest (downstream) to the source".

Using atmospheric turbulence models

WaveTrain models the optical effects of atmospheric turbulence using a standard wave optics technique, called in some references the "split-step" method.  The procedure is:

(1) Divide the propagation path into a number of subintervals.

(2) For each subinterval, compute the integrated turbulence strength based on a model of the continuous turbulence strength profile.

(3) For each subinterval, generate a "phase screen" whose optical path difference map, OPD(x,y), is a statistical realization that, in the mean, corresponds to the integrated turbulence strength.

(4) Position each screen at some point within its subinterval.

(5) Using Fresnel propagator formulas, propagate the optical beam from an initial plane to the first screen, apply that phase-screen distortion, propagate the result to the second screen, apply that phase-screen distortion, and repeat until the desired final plane is reached.

The time evolution of atmospheric turbulence is assumed to obey the Taylor frozen-flow hypothesis.  Thus, in addition to the above algorithm steps, we add the following:

(6) Model the time evolution of the turbulent propagation by shifting the phase screens relative to sources and sensors, by amounts consistent with the various transverse motion specifications that WaveTrain accepts.

As discussed previously, the Fresnel propagator used by WaveTrain is the spatial-frequency-domain form of the propagator.  Fast Fourier Transform algorithms are used to evaluate the two transform operations required by the propagator. 

Propagation time delay effects are thoroughly and consistently accounted for:  all propagation time lags between screens are incorporated.  The various screens receive the wavefront in precise accord with the physical propagation time lag from screen to screen.  Thus, once given a full-path turbulence realization (a set of screens), all temporal and spatial correlations have correct contributions due to propagation lags between screens.

The phase distortion applied by any phase screen is expressed by

     u'(x,y) = u(x,y)*e^i*k*OPD(x,y).

where u(x,y) is the complex field incident on the screen,  k is the wavenumber (2p / wavelength),  OPD(x,y) is the screen OPD in units of meters, and  u'(x,y) is the field exiting the screen.

The statistical realizations of the screens are generated in such a way as to reproduce the Kolmogorov statistics that describe locally homogeneous turbulence in the so-called inertial range.  In a later subsection, we discuss the algorithm for screen generation in somewhat more detail.  As a modification to the basic Kolmogorov statistics, the screen generation mechanism has options to impose an explicit inner or outer scale rolloff.  The inner scale modeling uses the "Hill bump" form of the turbulence spectrum. 

Any number of phase screens may be used, but in practice the maximum used is typically 10 to 20.  WaveTrain allows arbitrary spacing of the screens;  uniform spacing or equal-strength spacing are frequently-used special cases.  Equal-strength spacing means that the full propagation distance is divided into subintervals whose nominal integrated-turbulence strengths are equal;  in this case, the lengths of the subintervals are unequal, unless the continuum strength profile is completely uniform. 

WaveTrain has various options for specifying the phase screen strengths.  Usually the screen strengths are specified in terms of equivalent C_n²  values for the subintervals.  In general, C_n²  refers to the standard refractive-index structure parameter, which in WaveTrain always has the MKS units of m^-2/3. 

(Background note:  The C_n²  parameter is that constant which is defined by the Kolmogorov formula for the structure function of the refractive-index fluctuations:

     mean{ [n(r₁) - n(r₁+r)]² } = C_n² · r^2/3

 where n = refractive index, and r = separation of two points in the random medium.)

Specifying effective C_n²  values for WaveTrain phase screens

For wave-optics simulation, we typically know a model profile, C_n²(z), along the propagation path.  This may be uniform for near-horizontal paths, or may vary over orders of magnitude for a ground to high altitude path.  Several model profiles have been developed to describe the typical variation of C_n²  with vertical altitude, h, in the earth's atmosphere.  Some commonly used profiles are known by the names Hufnagel-Valley 5/7, Clear 1 Night, and SLC.  (For a discussion of these and profiles in general, see the review article by Beland). 

A phase screen represents the integrated C_n²  strength over the distance corresponding to one subinterval.  This is indicated pictorially in the following diagram, where the symbol  IC_n²  represents the integrated turbulence strength.

Based on the integrated C_n² , we define an effective screen C_n² as the path-averaged value:

     ( effective screen C_n,k² ) = IC_n,k² / (z_k - z_k-1)

Whenever the WaveTrain user employs an input format that requests explicit values of screen C_n² , the values are interpreted in the effective, or path-averaged sense just defined.  In other words, what Wavetrain does is to take an input value of screen C_n² , and multiply it by the corresponding subinterval length (or screen "thickness") to obtain the integrated quantity that actually determines the screen OPD strength. 

Phase-screen r₀ values

Readers who are familiar with optical turbulence theory will realize that  IC_n²  is closely related to the plane-wave r₀ (Fried coherence length) quantity.  In fact, WaveTrain has one input format for specifying screen strengths that requests screen-r₀ values.  Users who are familiar with this way of specifying screen strengths may prefer this input format to the C_n²-based formats.

Position of phase screens within the subintervals

In some WaveTrain input formats, the user can place the individual screens at arbitrary positions within their respective subintervals.  The best choice depends on the physical problem being modeled, and the turbulence path-weighting functions that are most important to the problem at hand.  Since several different weighting function are often significant in a physical problem, it is not always obvious what the optimum discrete positioning choice is.

In other WaveTrain input formats, the code internally decides where to place the screens within the designated subintervals.

Other phase screen parameters

In addition to the previously discussed strength and position parameters, the phase screen specifications contain numerous optional parameters.  Examples are screen transverse velocities, inner and outer scale lengths, and intensity transmission factors.  The availability and syntax of various options is documented in the section on the AcsAtmSpec function.  The remainder of the present section contains general remarks on several of the options.

Transverse velocities

Transverse velocities associated directly with the screens in the AcsAtmSpec function can be used in two ways.  If the velocities of target and platform motion are all specified by using TransverseVelocity library modules, then additional velocities specified explicitly as "screen velocities" should be interpreted as true-wind velocities.  WaveTrain will form the appropriate vector sums to obtain the relative motion of the nominal beam line with respect to the air mass.

There is a different approach to handling transverse velocity, which may be preferred by users who have some previous experience with "home-brewed" wave-optics simulation.  In many systems, one could dispense with WaveTrain's TransverseVelocity procedures, and simply precompute by hand the effective velocities with which the screens should be dragged, accounting for all target, platform, and true-wind velocities.  Then, these net pseudo-wind velocities could simply be inserted as the "screen velocities" in the AcsAtmSpec function.  These alternate approaches to handling transverse motion have been discussed at somewhat greater length in previous sections.

Inner and outer scales of turbulence

The optional inner and outer scale roll-offs are modifications to the pure Kolmogorov power-law spectrum of refractive index fluctuations.  The functional form and length of the outer scale depends in complicated ways on boundary conditions.  Modelers usually use a simple empirical rolloff known as the vonKarmann form, in which the Kolmogorov power law bends over and asymptotes to a constant at low spatial frequency.  The break point on a radian frequency scale is (1 / L₀), where L₀ is called the outer scale (see Andrews and Phillips, pp. 53ff.).  If desired, L₀ can be specified on a screen-by-screen basis in AcsAtmSpec.  In many modeling problems, the outer scale is sufficiently larger than aperture or beam sizes so that L₀ is effectively infinite.  If no outer scale specification is entered in AcsAtmSpec, it will be treated as infinite.

The inner scale modification of the Kolmogorov power spectrum is on a firmer theoretical and experimental footing than the outer scale.  When analysts explicitly include inner scale, it is often represented as a Gaussian rolloff factor at high spatial frequency, of the form
exp[-(K/K_m)²], where K is radian spatial frequency, and the inner scale length is
l₀ = 5.92/K_m.   Although this form is more tractable for analytic calculations, the modern literature has established that a more accurate form of the spectral modification is the so-called "Hill bump" form (see Andrews and Phillips, pp. 53ff.).  In simulation, this functional form can be encoded with little extra trouble, and this option is available in the AcsAtmSpec function.  If desired, inner scale length can be specified on a screen-by-screen basis in AcsAtmSpec.  If no inner scale is specified, it will be treated as zero.  There is a practical limitation due to the discrete simulation mesh:  the propagation mesh spacing effectively determines an inner scale even though no explicit factor is entered into the spectrum formula from which the screens are constructed.

Transmission factors

Screen "transmission" implies intensity transmission to be associated with that screen or subinterval.  For most WaveTrain work, the screen transmission options are not used:  the library also provides overall transmission-factor modules, so it is unnecessary to decompose the transmission by screen.  The exception to this is if the WaveTrain thermal blooming capability is used, but then one must use a different input function anyway (MtbAtmSpec).

WaveTrain library modules used to specify turbulence

The WaveTrain subsystems used to model the optical effects of turbulence are AtmoPath or GeneralAtmosphere.  If the user prefers to get WaveTrain subsystems via the "sub-libraries", the two subsystems just named can be found inside the AtmosLib sub-library.  As far as turbulence specification is concerned, there is no difference between AtmoPath and GeneralAtmosphere.  AtmoPath is a composite system that consists of GeneralAtmosphere plus two PropagationControllers.  For new WaveTrain users, we suggest the use of AtmoPath, which simplifies matters by automatically setting certain options.  The circumstances under which one wants to separately invoke GeneralAtmosphere and PropagationControllers are discussed in another Guide section.

In the present tutorial section, we explain the turbulence inputs in the context of the AtmoPath module.  The specifications are essentially the same in GeneralAtmosphere, when the user graduates to that level.  The diagram at right shows the interface of AtmoPath.  The module has a wavetrain input and a wavetrain output for each propagation direction.  Additionally, there are many parameters, and the ones directly relevant to turbulence specification are bracketed by the red bars.

The first parameter, named atmSpec, has a unique data type, AcsAtmSpec.  This parameter carries all the information regarding the turbulence strength and distribution: the number of phase screens, their locations, strengths, inner scales, outer scales, and so forth.  In the sample at right, this information is entered in a setting expression that uses a special function from the WaveTrain library:
     AcsAtmSpec(...)
The name of the function should be entered just as shown, and the ellipsis replaced by a sequence of input arguments that has numerous options.  Several of the most useful argument syntax options of AcsAtmSpec are documented in detail in the next subsection.  From time to time, new options are added, and the more experienced and bold WaveTrain user may benefit from inspecting the source code file that contains all the options. 

The second parameter, atmoSeed, is the random number seed used to initialize the sequence of phase screen statistical realizations.  This can be any allowed integer value.  This parameter allows the user to exactly reproduce a particular set of turbulence screens:  in this way, we can vary some overall system parameters while using exactly the same turbulence realizations.

The next relevant group of parameters stretches from xp1 to yt2.  These parameters specify the transverse spans of the phase screens.  As the system evolves, there may be relative motion between sources, medium, and sensors, causing the beams to sample different portions of the phase screens.  The relative motion of the screens is carried out internally by WaveTrain, based on transverse motion specifications defined by the user.  The "rectangular region"  (xp1,xp2, yp1,yp2)  defines the size of a screen at the platform end (should a screen be exactly at that z), while  (xt1,xt2, yt1,yt2)  defines the size of a screen at the target end (should a screen be exactly at that z).  The indices "1" and "2" here signify "min" and "max", respectively.  The sizes of screens at intermediate z locations are determined by linear interpolation from the "rectangular regions" at the two ends.  In previous sections on transverse motion, we explained in detail how the transverse motion during the full simulation is used to determine appropriate values for the screen "rectangular regions".  The numerical values entered as setting expressions in the above picture derive from an example discussed in that previous section.  The link just referenced should be reviewed in conjunction with the present one for full coverage of phase screen specifications. 

The final turbulence parameter is screenDxy.  This is the mesh spacing of the phase screens.  We have set this spacing equal to the propdxy value, which is a typical choice, though not obligatory.  Based on screenDxy, WaveTrain may make some adjustment to the screen size because of FFT (Fast Fourier Transform) constraints.  For example, to determine one of the actual dimensions of the phase screen mesh,  (xp2-xp1)/screenDxy  will be rounded up to the nearest convenient integer for the FFT routines, so that the screens will usually be somewhat bigger than the user specifications (xp1,...).  

Use of AcsAtmSpec to specify turbulence parameters and path geometry

To enter turbulence specifications into a WaveTrain simulation, one uses the AcsAtmSpec function in a setting expression in AtmoPath or GeneralAtmosphere.  The mechanism was illustrated in the first parameter line in the preceding picture.  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, between official WaveTrain releases, 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 positions (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 (TRE)).
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.

Table of basic cases

Atmospheric modeling using TurbTool or PropConfig

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 Matlab path to turb2007.tbx accordingly.

(3)  At the Matlab prompt, type:  >> PropConfig
This will open the PropConfig main screen, whose appearance is shown in the figure below.  The PropConfig GUI is relatively intuitive, but for the details there is a separate PropConfig Tutorial.

(4)  Depending on installed versions of certain graphics support libraries, the text and numbers of graphics panels in the PropConfig screen may display improperly.  If you observe display problems, try the following:
   a) exit from PropConfig
   b) at the Matlab prompt, type  >> opengl software 
   c) restart PropConfig.
If necessary later, to return Matlab to previous conditions, type >> opengl hardware .

CAUTION:  dxyDetector in Camera has the following potentially confusing aspect. If dxyDetector is coarser than dxy_FT, then WaveTrain's reported fpaImage values are simply point-interpolated from the original |transform|² values on the dxy_FT mesh.  This is NOT equivalent to spatially integrating the irradiance over physical pixels whose size is dxyDetector.  Depending on the physical system, such a spatial integration may be critical to a physically valid model of camera output.  Spatial integration of that sort must be accomplished with an extra WaveTrain component.

In this section, we identify and discuss several of the key Zernike components, and we explain the  index ordering, normalization and physical units conventions.  WaveTrain's Zernike components are located in the ProcessingLib library that is accessible from the master library. 

Basic Zernike Components

Browsing the ProcessingLib reveals a variety of components related to Zernike manipulations.  The two basic operations are:

(1)  To create a map  f(x_i,y_j) = S_k a_k*Z_k(x_i,y_j) , from coefficients a_k and Zernike basis functions Z_k, i.e., to create a superposition of Zernike basis functions, use the component
   ZernikeCompose.
Key inputs and parameters are the coefficient vector, a_k, and the (x,y) mesh specification.  The output is a Grid<float> variable that contains the f(x_i,y_j) data.  Notice that ZernikeCompose does not directly create a wavetrain (i.e., a complex field) as output.  Typically (but not always), one would want to insert f(x_i,y_j) as the phase map of a wave at some point in a WaveTrain propagation system.  The picture below shows a simple example, wherein Zernike phase aberrations are added to a plane wave:

(2)  To decompose a given function map  f(x_i,y_j)  into its a_k Zernike coefficients, use the component
   ZernikeDecompose.
This function is the inverse of ZernikeCompose.  Notice that ZernikeDecompose does not accept a wavetrain (i.e., a complex field) as input:  the input is simply the real function f(x_i,y_j) that is to be decomposed.   

Ordering conventions

WaveTrain's Zernike ordering and normalization options are described rather confusedly in the html help pages of the individual components.  In the following two subsections, we attempt to clarify the key points.

Each Zernike basis function is a product of a radial and an angular function.  As with other orthogonal expansions in 2D, the "natural" indexing to specify a particular basis function uses two indices.   However, R.J. Noll wrote an influential paper applying Zernikes to atmospheric turbulence, and in this paper Noll introduced a mapping to a one-dimensional Zernike index.  This type of 1D index is used to specify the input or output coefficient vectors, a_k, in the Zernike components.  A variation (still 1D) of the Noll ordering, used by Malacara, is also available in the WaveTrain components.  Malacara's ordering differs from Noll's in the order of the azimuthal terms within each radial order. 

Note that in the i/o of the basic routines, the
   ZernikeCompose  input vector "coefficients"
   ZernikeDecompose  output vector "ZernikeCoefs"
are ordered in the 1D convention of Noll or Malacara.  Noll order is specified by setting parameter "orderingScheme"=1, and Malacara order is specified by setting "orderingScheme"=2.

The piston term (constant with respect to x,y) is omitted from all the basic WaveTrain Zernike components.  The coefficients vectors start with tilt.  The following picture shows image plots of WaveTrain's first 10 Zernike functions (Z₁ to Z₁₀) in the Noll ordering convention.  Note that +x is vertically down in each subplot.  Terms 1 and 2 are tilt, term 3 is quadratic focus, terms 4 and 5 are astigmatism, terms 6 and 7 are coma, terms 8 and 9 are triangular astigmatism, and term 10 is balanced spherical aberration and focus:

REFERENCES:
1)  Noll, Robert J.,  "Zernike Polynomials and Atmospheric Turbulence", J. Opt. Soc. Am., Vol. 66, No. 3, pp. 207-211, 1976.
2)  Malacara, D., and S.L. DeVore, "Interferogram evaluation and wavefront fitting":  pg. 465, Ch. 13 of Optical Shop Testing, 2^nd. ed.,  D. Malacara, ed., Wiley, 1992.

Normalization conventions

Several normalization conventions for the Zernikes may be found in the optical literature.  The WaveTrain components all have a choice of normalization conventions, specified by the parameter "normalization".  Two of the WaveTrain normalization choices are useful:

"normalization" = 0:  The numerical value of each Z_k(x,y) peaks at +1 at one or more points on the circle whose radius is the "Zernike radius".

"normalization" = 3:  The rms deviation of each Z_k(x,y), over the disk whose radius is the "Zernike radius", is equal to 1.  Therefore, the numerical coefficient value a_k will be the rms value of the product  a_k*Z_k(x,y).  Furthermore, in a sum of several terms, .f(x_i,y_j) = S_(k=1,N) a_k*Z_k(x_i,y_j), the spatial variance of f  will be the sum of the variances of the individual terms, i.e., var(f) = a₁²+...+a_N² .  (This norm is called the "Noll/Malacara norm" in the component help pages).

Other values of "normalization" (which are described in the help pages for individual Zernike components) remain in the routines for historical reasons, but are not recommended.

The "Zernike radius"

The main significance of the "zernikeRadius" parameter has already been indicated in the preceding subsection on normalization conventions.  In ZernikeCompose, the extra parameter "applyAperture" allows the generated Zernike terms to be set to zero or not, as desired, for (x,y) coordinates outside the "zernikeRadius".

Physical units

The mesh coordinates (x_i,y_j) and the Zernike radius, as with all lengths in WaveTrain, must be specified in meters.  The Z_k quantities themselves are unitless.  Finally, the units in which a_k, and thus f(x_i,y_j) = S_k a_k*Z_k(x_i,y_j), should be specified depend on how f(x_i,y_j) will be used by WaveTrain.  A typical WaveTrain procedure would be to input f(x_i,y_j) into an OpdMap module, in order to apply f(x_i,y_j) as a phase perturbation on a passing wave (see the picture in Basic Zernike Components).  In this case, since OPDmap interprets its input as an OPD in meters, the a_k coefficients must be provided in meters.  But of course a Zernike sum f(x_i,y_j) could be used in other ways, where f  has different physical significance and different units..

The ZernikeCompose/ZernikeDecompose routines explained in Basic Zernike Components should be considered the first choices in WaveTrain system construction requiring Zernike manipulations.  However, in the course of WaveTrain development and application, a slightly different set of Zernike-related routines was also created.  This alternate set of routines shares some but not all features and conventions of ZernikeCompose/ZernikeDecompose. 

The "PhaseZernikeXXX" component group:

The component PhaseZernikeOPD is conceptually equivalent to ZernikeCompose.  That is, its principal purpose is to accept a set of input coefficients, and then output the sum f(x_i,y_j) = S_k a_k*Z_k(x_i,y_j), on a specified (x_i,y_j) mesh.  The principal differences are:
(i)   To produce an output f  in meters, PhaseZernikeOPD requires input coefficients in radians of phase at a specified reference wavelength.  The output, in meters, is then appropriate for input into the OpdMap module, exactly as was done in the ZernikeCompose illustration in Basic Zernike Components. 
(ii)  PhaseZernikeOPD  requests a Zernike diameter (which is simply called "aperture diameter"), whereas  ZernikeCompose requests a Zernike radius.
(iii) PhaseZernikeOPD has parameters named "m_vec" and "l_vec" that allow extra selection freedom by specifying that only certain subsets of the input coefficient vector elements be used when composing the Zernike sum.
In other respects, the ordering and normalization convention options for the coefficient input vector are identical in PhaseZernikeOPD and ZernikeCompose . 

There are several other special-purpose Zernike-related components whose i/o conventions match PhaseZernikeOPD.  The most important are PhaseZernikeDM, and PhaseZernikeSlopes:

PhaseZernikeDM takes an input vector of Zernike coefficients, internally composes the sum function f, and generates corresponding deformable-mirror (DM) commands which are organized as required for input into the WaveTrain DM component.

PhaseZernikeSlopes takes an input vector of Zernike coefficients, internally composes the sum function f,  and generates the corresponding wavefront-sensor (WFS) slopes, corresponding to Shack-Hartmann subapertures whose geometry is specified according to the WaveTrain WFS procedures.

There are two separate setup steps required to enable the use of HartmannWfsDft.  The first setup step is to specify a set of scalar parameters that define certain subaperture dimensions and computational controls on the subaperture spot patterns.  The HartmannWfsDft parameters in question are the set subapWidth, focalDistance, detectorPlaneDistance, magnification, dxyDetector, overlapRatio, and nxyDetector.  The setting rules are rather involved, and the procedure has a number of subtleties that require careful attention.  This setup step is discussed in the following subsections. 

The second setup step is the specification of the 2D layout of the subapertures.  The 2D layout is summarized in two vectors that contain the x-coordinates and the y-coordinates of the subaperture centers.  The tool provided to create these vectors is a graphical MATLAB helper program called AOGeom.  Usage of this tool is explained in the Adaptive Optics Configuration Guide.  The two coordinate vectors that are created and saved by AOGeom must be read into the HartmannWfsDft parameters xSubap and ySubap.  The Adaptive Optics Configuration Guide illustrates the setting-expression syntax that can be used for that purpose. 

When the "object-space" approach is applied to the modeling of a Camera subsystem, the key modeling requirement is that the focal-plane sensor pixels subtend the desired angle in object space.  In this approach, the numerical values of the focal length and sensor pixel width specified in the Camera module are arbitrary, as long as their ratio is the correct object-space angle.  Frequently, WaveTrain modelers assume a standard focal length of 1m for this purpose.  Now, when modeling a Shack-Hartmann WFS, which is really a collection of side-by-side cameras, we usually use the same general principle of "object-space" modeling.  However, in the case of the WFS, the simplest (without loss of generality) modeling approach involves an extra constraint on the equivalent focal length: in this case, the standard choice of 1m is not the best, because it introduces an extra complication which must be handled by means of the somewhat peculiar  magnification  parameter that appears in the HartmannWfsDft parameter list.  The following subsections contain a detailed explanation of the suggested parameter-setting procedures for HartmannWfsDft. 

In many simulation exercises, the physical dimensions
          {D_sub, f_sub, p, M_pup}                     (Spec "S1.1")
may not be known, because there is no actual optical system design yet.  In such cases, which are typical of generic AO system modeling, there are various combinations that one could use to define the WFS system.  One option is to specify the set
          {D_sub,0 , q_snspix,0 , p0}                (Spec "S1.2") 
as the fundamental input specifications, with only the picture of Figure (A) in mind.  
Note 1:  instead of p₀ directly in "S1.2", the most meaningful spec may be the "number of sensor pixels per subaperture", i.e., the ratio N_{pix_per_sub} = D_sub,0 / p₀ .
Note 2:  the  D_sub,0  value would generally chosen on the basis of an expected atmospheric Fried-r0 value.
Note 3:  q_snspix,0  is independent of D_sub,0 , but there is the following constraint.  Since the subaperture diffraction lobe width is l / D_sub,0 , one wants to select values of q_snspix,0  that allow reasonable sensitivity to at least a wave or more of tilt-induced spot motion.
Note 4:  One wave of tilt across the full subaperture corresponds exactly to a spot-center angle displacement of l / D_sub,0 .  Note that the boundary of the subaperture occurs at an angle equal to
(0.5*D_sub,0 / f_sub,0) = (0.5*D_sub,0) * q_snspix,0 / p₀.

The set "S1.2" in conjunction with Figure (A) is a complete and consistent specification, as proven by the preceding analysis.  However, the HartmannWfsDft module requires a  focalLength  specification, and this must be simply  f_sub,0 = p₀ / q_snspix,0.

Summary of HartmannWfsDft parameters thus far:

The preceding analysis has explained how to set the HartmannWfsDft parameters  subapWidth  and focalDistance.  Usually, we also set  detectorPlaneDistance = focalDistance.  If one wants to study the effects of defocus on the WFS operation, one can set  detectorPlaneDistance  to a value of interest different from focalDistance. 

Next, we discuss the HartmannWfsDft parameters  dxyDetector, overlapRatio, and nxyDetector. 

The parameters  dxyDetector and  overlapRatio  control the numerical propagation mesh used by the Discrete Fourier Transform (DFT), when a given subaperture spot diffraction pattern is computed.  Given the complex optical field incident on its lenslet plane (see Figure A).  HartmannWfsDft first extracts that portion of the field incident on a given subapWidth, interpolates the incident field onto a desired (usually finer) mesh, pads that with a certain band of zeros, and finally performs a DFT to obtain the sensor-plane spot intensity pattern for the given subaperture.  This operation is performed separately for each subaperture. 

The two parameters  dxyDetector  and  overlapRatio  determine the DFT numerical mesh as follows.  First,  dxyDetector  specifies the spacing of the mesh on which HartmannWfsDft will report its integrated_intensity output map.  The numerical value  dxyDetector  should be selected so that the diffraction-limited spot is reasonably well sampled:  this means at least two samples per (wavelength/subapWidth)*focalDistance. 

The more mysterious parameter is  overlapRatio:  this specifies the total width of the computational mesh for a single subaperture spot pattern.  Physically, diffraction causes the spot pattern to have unlimited width; for numerical computation one must decide where to cut this off.  overlapRatio specifies the cutoff in terms of the subapWidth, as follows:  overlapRatio = 0  means that the mesh on which the spot pattern is computed in the sensor plane spans exactly one subapWidth;  overlapRatio = 1  means that the mesh spans out to one subaperture width on each side of the saubaperture in question, etc; fractional values are allowed.  If overlapRatio > 0  is specified, HartmannWfsDft will eventually add the overlapping intensity contributions in order to produce its net integrated_intensity sensor-plane output map. 
(For a fixed  dxyDetector, larger values of  overlapRatio  of course require longer numerical computation times.  Given that some thresholding is usually applied later when computing the spot centroids, overlapRatio = 0  is often satisfactory). 

Finally, parameter  nxyDetector  specifies the total width of the mesh (in number of mesh points) on which HartmannWfsDft produces the net integrated_intensity output map.  This should be specified large enough to contain all the subapertures in the 2D layout.  A typical setting would be
          nxyDetector = (D_sub,0 / dxyDetector) * N_max,sub + 1 ,
where  N_max,sub  is the number of subapertures across the maximal dimension of the 2D layout.

Remaining parameters of HartmannWfsDft

To complete the discussion of Approach 1 to setting WFS parameters, we now explain the remaining parameters.

magnification:  In approach 1, the  magnification  parameter should be set to 1.  This means it will have no effect on the computations.  This modeling parameter is NOT the pupil magnification M_pup that played a prominent role in Figures A-B and the related discussion.  magnification  is only needed if we use Approach 2 to defining WFS parameters.

dxyPupil, nxyPupil:  These parameters are only used if the "wavesharing" feature is invoked in Wavetrain propagations.  "Wavesharing" is an advanced, not fully-debugged feature of WaveTrain.  For most WaveTrain use, dxyPupil  and  nxyPupil  should be set to dxyprop and nxyprop, respectively.  (Unless "wavesharing" is invoked, the numerical values are actually never used). 

xslope0, yslope0:  These are the initial values of the slopes, prior to any sensor information being generated in the WaveTrain simulation.  The values are usually set to 0.0.

slopes output:  high-resolution and recomputed slopes

integrated_intensity:  this is a composite integrated-intensity map of all the subaperture spots, at all the specified sensor output times.  It is recorded on the spatial mesh {dxyDetector, nxyDetector}.

The "high-resolution" slopes generated as discussed above are intended to be an idealized computation of the subaperture tilts.  To more accurately model the centroids computed from an actual 2D array sensor placed in the lenslet focal plane, one should add the WaveTrain components  SensorNoise and HartmannWfsProcessing. 
SensorNoise would take as an input the integrated_intensity output of HartmannWfsDft.  SensorNoise serves two functions:
(i)  SensorNoise allows the spatial integration of the high-resolution integrated_intensity pattern into physical-pixel powers.  The "physical pixel" width is the p₀ parameter discussed earlier.  Note that we used a mental picture of the desired p₀ while defining the HartmannWfsDft parameters, but the sample mesh in the sensor plane was actually the finer dxyDetector.
(ii) SensorNoise allows the inclusion of various kinds of sensing noise. 
Finally, HartmannWfsProcessing can take as input the physical-pixel powers (more precisely, the discretized "detector counts") output of SensorNoise, and perform new centroid (and slopes) calculations.  The latter slopes will include the discretization errors that result from applying a centroid algorithm to the measurement results from the physical sensor pixels.

WFS modeling - details of "Approach 2" (using magnification ≠ 1)

Approach 1 made a simple and physically clear modeling choice about the {p , p₀} transverse scaling.  In that approach, p/p₀  is exactly the same as the pupil magnfication D_sub/D_sub0.  The pictorial representation of the model is Figure A-B.  As a consequence, we saw that the longitudinal ratio  f_sub / f_sub,0  had to scale as the square of the pupil magnification.  In Approach 1, The HartmannWfsDft parameter called magnification, which is NOT the pupil magnification, is set to 1 (i.e., the parameter is inactive).

A different approach is also possible.  This alternate "Approach 2" has been used in a variety of WaveTrain applications, including the important example system BLAT.  Approach 2 is somewhat more convoluted, and requires a peculiar "magnification" operation that is implemented by the HartmannWfsDft parameter called  magnification. 

Approach 2 is based on setting  f_sub,0 (focalDistance) equal to the arbitrary reference value 1 m.  The motivation for the choice  focalDistance = 1  was briefly reviewed in the introductory section on WFS modeling in object space.  After this choice, Approach 2 completes the specifications by also choosing D_sub,0  and  q_snspix,0 .  A consistent model can be built on this basis, but it requires an extra adjustment.  The problem is that the combination  {f_sub,0 = 1m, q_snspix,0 }  contradicts the intuitive scaling choice p/p₀ = D_sub/D_sub0.  As we noted before, this is not wrong, but it requires an extra adjustment to the center-center  separations of the subaperture regions in the sensor plane.  This adjustment factor is what is generated by setting magnification ≠ 1.  For an example of the actual setting expression assignments, we refer the user to the WaveTrain distribution's BLAT example system.

As a final comment on the use of  magnification ≠ 1, we note the following peculiar property.  The diffraction lobe of a subaperture has the width
(wavelength/subapWidth) * focalDistance = (wavelength/subapWidth) * (1m),  unaffected by magnification , but the center-center separation of the neighboring subaperture diffraction patterns is the subaperture separation multiplied by  magnification.

In the present section, we have reviewed procedures for setting the key scalar parameters in HartmannWfsDft.  As noted previously, in order to complete the specification of the 2D layout of the WFS subapertures, use of the AOGeom tool is also required.  The Adaptive Optics Configuration Guide explains how to use this tool to create subaperture 2D-layout data for input into the HartmannWfsDft parameters xSubap and ySubap.

When an optically rough surface is illuminated by a monochromatic beam, the phase differences across a surface of the exiting wave are still constant in time, although the phasefront becomes extremely rough.  The assumption used in the basic theoretical treatment is that, in an exit plane after reflection, the phase of the exiting beam is uncorrelated from point to point, and has a standard deviation much greater than 1 wave (or equivalently, the mod-2p phase is practically uniformly distributed over 2p radians).  In accordance with this concept, CoherentTarget works by initially defining a spatially uncorrelated exit phase map, and propagating the resulting beam though the remainder of the WaveTrain system.  In addition to internally generating the random-phase map, f(x,y), CoherentTarget allows the user to specify an intensity reflectance map, R(x,y), where (x,y) is transverse to the nominal propagation direction.  R(x,y) allows the user to specify a target of arbitrary shape and non-uniform reflectance strength across the target. .

Occasions arise in WaveTrain model assembly where it seems physically logical to connect one component's output to another component's input, but the data types of the output and input have unfortunately been defined differently.  This could be as simple, e.g., as the output being single precision (type "float"), and the input being double precision ("double").  Another example that may crop up is integer ("int") versus boolean ("bool").  Conversions such as these can be done using components from WaveTrain's ConvertLib library, inserted into the WaveTrain system in the System Editor.  The figure at right shows an example of such a component, named cItoF, which take an integer ("int") input and converts it to the corresponding single precision ("float") value.  The library also provides more complicated conversion components, involving vectors and grids, that may be useful.

There is one other special type-conversion requirement that sometimes occurs in WaveTrain model assembly.  This is the conversion of a "float" to a "recallableFloat".  This is accomplished with a special function syntax in a setting expression, as opposed to the insertion of a conversion component.
 

The available function can be used to input a Grid<Complex> by reading the real and imaginary array parts from two separate plain-text files.  The setting expression syntax is:
     FileGridC(char* reFile, char* imFile,
            int nx, int ny, double dx, double dy)

where  reFile  (imFile)  should contain a tab-delimited array of numbers corresponding to the real (imaginary) part of the Grid values, and where nx,ny,dx,dy specify the mesh dimensions and physical spacing (MKS units).  x should correspond to the first dimension (i.e., down-column).  The FileGridC function would be used in the same context where the function mliLoadG("matFilePath", "matStrucName", Complex()) could be used (as illustrated in the section dedicated to reading from *.mat files).

From time to time, further functions for loading data from text files may be added to the WaveTrain capabilities.  Users can check the file TempusInitializers.h in their WaveTrain installation to see if any new read syntaxes have been added since the User Guide was updated.

The alternate function name grid_with_origin_on_mesh(...) may be used instead of gwoom(...);  the first letters of the expanded name also explain the source of the "gwoom" name.

The above example, involving the function "recallableFloat",  illustrated a situation where data-type conversion is required in setting expressions.  There are analogous situations where it is physically logical to connect a component's output to another component's input, but the data types of the output and input have unfortunately been defined differently.  This could be as simple, e.g., as the output being single precision (type "float"), and the input being double precision ("double").  Another example that may crop up is integer ("int") versus boolean ("bool").  Conversions such as these must be done using components from WaveTrain's ConvertLib library, inserted into the WaveTrain system in the System Editor.  This procedure differs from the previous recallableFloat example, where a conversion function was inserted in a setting expression; however, the concept is similar insofar as both procedures satisfy the need to occasionally mate different data types in the System Editor. 
 

"Obsolete" warnings

There are several situations in which the System Editor or Run Set Editor issue "obsolete" warnings. 

(1)  Obsolete components

When an existing system is opened in the System Editor, it may happen that one or more components appear with the notation "obsolete" above the component icon.  The figure at right shows an example.  This typically indicates that the component in the user's Wavetrain installation has been updated in some way with respect to the component in the opened system.  In the vast majority of cases, there is no real conflict implied by this:  the user should simply execute the System Editor menu sequence Edit -- Update Obsolete Subsystems, selecting all the subsystems to be updated in the list that is presented.

Potentially, if a major change was made to the component interface (inputs, outputs or parameters were changed, added or removed), then the containing WaveTrain system might no longer work after updating.  However, this is very unlikely:  if a WaveTrain component were changed that significantly, it would be much more likely that a modified component would be added to the Wavetrain libraries (unless perhaps the old component had been discovered to produce out-and-out wrong results).  By far the most likely scenario is that the change is insignificant to the user.  At present, there is no simple way for the user to discover exactly what the change is that triggered the "obsolete" warning.  As noted above, the default recommendation is to update.

(2)  Obsolete runsets

A completely different "obsolete" situation occurs when the user makes changes in a system that affect the runset.  This will occur relatively frequently in normal WaveTrain practice.  This was discussed in several spots in the introductory tutorial.  for completeness, we repeat the principal paragraph below.

Suppose that you have already created a run set for a WaveTrain system, and then you subsequently edit the system in the System Editor.  Many such changes will temporarily render the run set invalid, and you must execute Edit - Update in the Run Set Editor window to continue working there.  There should be no confusion as to whether you need to do this:  the condition is signalled by the message "Obsolete" in the status bar at the bottom of the Run Set Editor, and by the inability to access various grayed-out menu options.

If a run set is not open when you edit its system, then the "Obsolete" message will appear when you next open the run set.  There is no possibility of incorrectly executing the simulation run due to forgotting to perform this synchronization step.

Status bulbs and status checking

Method (2), loading of WaveTrain output data into Matlab:
(2a)  Exporting from TrfView:  TrfView has an export capability, which allows data to be quickly loaded and inspected within TrfView, and then exported to a Matlab command window for arbitrary manipulations with the full power of Matlab.  (TrfView also supports export to other destinations such as Microsoft Excel or plain ASCII files.)
(2b)  Direct loading of trf data into Matlab:  This method is more involved, but is more general than exporting from TrfView.  Exporting from TrfView requires the manual selection of each data file and each variable within a file from TrfView menu lists.  If, however, a user wants to construct and run batch processing functions that load and analyze a prespecified set of variables names from trf files, then it will be necessary to learn the "old-fashioned" method of loading trf data directly into Matlab.  This means using a (small) set of Matlab functions, provided by the WaveTrain code suite, to load trf data directly into a Matlab session.  Another advantage of the direct-loading method is that the full Matlab GUI integrated-development environment is available.  By contrast, the Matlab window opened by a TrfView export is only the command-window portion of Matlab's IDE. 

In the remainder of this chapter, we discuss
   (1)  The trf file naming convention
   (2)  The grouping of trf data by "run index (run number)"
   (3)  The usage of TrfView, including its export features
   (4)  The Matlab functions needed to import trf data directly into Matlab, without TrfView
All WaveTrain users should understand items (1)-(3).  Regular users will eventually want to progress to item (4) as well.

trf file naming convention

Further remarks on K:  each time a given Run Set name is executed, (usually with some modification in parameter values or system specification), a new trf file is generated.  The name of the trf file is identical except for the sequentially-increasing K value, which is assigned automatically by the program.

The following caution applies to WaveTrain versions 2009A or earlier:
CAUTION:  Actually, column 4 only lists the probable space dimensions of each data variable.  The "probable" qualifier obviously requires some explanation.  Consider a multi-dimensional data variable such as the irradiance array I(ix, iy, it), where (ix, iy) are spatial indices and (it) is the time index.  Let (nx, ny, nt) be the physical dimensions of the recorded data.  For historical reasons, such an array is actually recorded in the trf file as a 2-D array, of dimensions (m=nx*ny, nt).  Unfortunately, the trf file does not automatically record the values of nx and ny, so there is no foolproof automated method of reshaping the (m) values for plot purposes.  TrfView makes a reasonable guess at (nx,ny), and these are the values that are first reported in Column 4.  The guess is formulated as follows:
(a) If sqrt(m) is an integer, TrfView reports that (nx, ny) = (sqrt(m), sqrt(m)).
(b) If sqrt(m) is not an integer, TrfView reports that (nx, ny) = (m, 1).
This guess is the most reasonable one, because square sensor arrays are the most common configuration, but of course that will sometimes be wrong.  If the spatial data is not square, the user must manually tell TrfView what the correct dimensions are by pressing the "..." button at the right of column 4 and entering the correct dimensions.  Note that in Wavetrain, "x" « dimension 1, and "y" « dimension 2. 

Selecting runs within a run set

In the main TrfView window illustrated above, note the tool bar located just below the menu bar.  The item "Runs in File: 1" in the illustration indicates that this run set and trf file contain one "run" in the specialized WaveTrain sense explained earlier in this chapter.  If there had been more than one run in the trf file, then the adjacent list "Select Run" could be pulled down to select any desired run number within the trf file.  All the variable listings in columns 1-4 would stay the same, but the data values would of course usually change if we change run number. 

Plotting and inspecting the data in TrfView

TrfView provides good quick-plot and data-inspection capabilities, and a limited number of post-processing options.  To perform custom plotting, add arbitrary plot annotations, or do arbitrary post-processing, the user must either export the data from TrfView to Matlab, or load the trf data directly into Matlab:  those procedures are explained in subsequent sections.

The menus and options for plotting within TrfView are fairly self-explanatory.  To briefly illustrate, let us return to the previous figure showing a TrfView main window.  Suppose we want to plot the variable named "... pt_diag_cam.fpaImage" (5th name in the variable list, which happens to be highlighted in the figure).  From knowledge of the WaveTrain system, this variable happens to corresponds to the integrated intensity map seen by a camera sensor.  Column 4 of the TrfView window shows the spatial dimensions of this data to be 256x256.  To plot the integrated intensity map,  we can either
(a) left-click on the variable to select it, then use the menu command "Variable  -  Plot Variable"; or,
(b) right-click the variable name, and select "Plot Variable".
This causes TrfView to generate a separate plot window as illustrated in panel (A) of the following figure:

Below the plot itself, the plot window in panel (A) has a time index entry field: by entering a different index number, or clicking on the neighboring arrow buttons, we can see the 2-D map at any of the recorded times.  The actual simulation time, in seconds, to which the data corresponds, is also listed.  (Recall that column 3 of the main TrfView window also specified how many time steps were recorded.)  The plot window also has button (see panel(A)) that plays an animation of the full time-sequence of 2-D maps.  The color bar has a numerical scale that quantifies the map values.

In the case of a vector variable, TrfView plots a line-plot of the vector elements versus element index.  Consider the variable named "... zernikeCoeffs" in our example TrfView window (3rd variable in the list).  At any time index, this particular 10x1 vector happens to contain the values of Zernike expansion coefficients that were used to represent a wavefront.  Applying the plot command on that variable yields the plot shown in panel (B) of the above figure. 
Note 1:  Vector element indices span 0,1,...,N-1 in accord with C/C++ conventions, hence the data point locations in panel (B).
Note 2:  As we see in panel (B), the default axis scales created by TrfView for line plots are often somewhat inconvenient.  In panel (B), it would obviously be preferable to have scale number 0,1,...,9 or 10.  The user can adjust the axis scale values to some extent by right-clicking on the plot, and selecting the option "Set scale to default".  In the present example, that produces nicer scale numbers. 
Note 3:  As we see in panel (B), the horizontal and vertical axes of a line plot are always labeled "X" and "Y", even though these axes typically have nothing to do with spatial directions.

Other plot-view options:  other useful font and graph display options can be accessed by
(a) right-clicking on the plot to bring up a context menu
(b) pulling down the "View" menu in the plot figure window.
Note that the options provided under (a) and (b) are not the same.

Zooming:  To magnify (zoom in on) a section of a plot, we can left-click and drag to outline the section that we want to magnify.  To undo the zoom, we right-click in the plot and select "Unzoom".

There is another plot-control  window also generated by TrfView as soon as the first plot is created.  This window is illustrated in the following figure, after we have created two plot windows (the ones in panels (A) and (B) above):

This control window contains a listing of all the plot figures currently open, and the user can select any figure in the list by left-clicking it.  Depending on the nature of the selected plot (line or image), a number of other plot (or analysis) options then become available on the right side of the window.  Perhaps the most useful of these is the line-plot button that says "Plot an X against time":  in connection with the previous panel (B) example, pressing this button allows the creation of a line plot of one of the Zernike coefficient values versus the time index.

Inspecting data numerical values:  if we want to do better than visually reading off the plot scales, TrfView provides several options:
(a) In an image or line plot:  the menu command "View - Data" toggles on and off a small sub-window that displays the array or vector numerical values.
(b) In a line plot such as panel (B): right-clicking on the plot brings up a context menu that contains the option "Show point values":  after that option is selected, hovering with the cursor over a data point causes that point's coordinate values to appear.

Archiving (saving) plots

Usually, one wants to save some plotted results in a presentation (e.g. PowerPoint) or word-processing file.  TrfView provides several options for saving plots, among which are:
(a) In a TrfView plot window, use the menu command "Edit  -  Copy to clipboard" to copy the window to the Windows clipboard.  (This is the same as using Windows' traditional "Alt-PrtScrn").
(b) Right-click on a TrfView plot, select "Save figure as ...".
(c) In a TrfView plot window, use the menu command "File  -  Export to ...".  For example, one option is to export to PowerPoint:  this has the effect of adding a new slide to a user-designated PowerPoint file, and copying the plot to that slide.  

Another TrfView archiving option is the automatic creation of an AVI movie file.  This feature is accessed through the menu sequence "File  -  Export To  -  AVI file" in a TrfView plot window.

Exporting data from TrfView to Matlab (or other analysis environments)

As noted previously, TrfView does not provide arbitrary plot customization or post-processing analysis.  To accomplish such tasks, we must either (a) export the trf data from TrfView to Matlab (or other analysis environment), or (b) bypass TrfView completely and read trf data directly from Matlab.  We discuss option (b) later in this chapter. 

Exporting data from TrfView to Matlab is very simple.  Consider again the TrfView main window figure illustrated earlier.  To export the data for variable "... fpaImage", we can either
(a) left-click on the variable to select it, then use the menu command "Variable  -  Send to Matlab workspace"; or,
(b) right-click the variable name, and select "Send to Matlab workspace".

Assuming that we have a working installation of Matlab on the same computer, and WaveTrain's environment settings have been told the Matlab path, actions (a) or (b) will cause a Matlab command session to open, and will cause a Matlab variable corresponding to "... fpaImage" to appear in that session.  The following figure is a screen capture of the Matlab command window, after we have added a few Matlab commands. 

In the above Matlab window, the sequence of events and their motivation was as follows. 
(1)  Immediately after we issued the data export command in TrfView, the Matlab command window opened blank.
(2)  We entered the first Matlab command,
>> whos
Matlab reports that a variable named "PDatmNPt__platform_pt_diag_cam_fpaImage" is present in Matlab's workspace:  this is the data exported by TrfView.  Furthermore, Matlab reports the dimensions of the variable to be 10x65536.  Back in the TrfView main window, the variable data was designated as having 10 time steps, with (x,y) dimensions of 256x256.  Note that 256² = 65536.  This explains the dimensions 10x65536 of the Matlab variable.  Note that all 10 recorded images, one for each time step, have been imported into a single Matlab array variable. 
(3)  For subsequent processing, it is an inconvenience that the variable was imported as 10x65536, rather than the more natural 256x256x10.  This has to do with the early history of WaveTrain and trf files.  It is almost always more convenient to reshape the array data to the natural 256x256x10 dimensions.  We accomplish this with the next Matlab command,
>> fpaImage = reshape(PDatmNPt__platform_pt_diag_cam_fpaImage', 256,256,10);
Notice that the original variable is transposed (using the ' operator) before the reshape is actually applied.  Users of Matlab will understand this command syntax.  Another
>> whos
command confirms the desired shape of the renamed variable. 
(4)  At this point, the data is in convenient form for arbitrary Matlab plotting or processing.  For example, the last command in the window,
>> figure; imagesc(fpaImage(:,:,1)); ...
generates a Matlab plot of the image for time index 1. 

Exporting to other analysis or display environments: 

TrfView supports the export of trf data to the Microsoft Excel spreadsheet program, and to CSV (comma-separated values) text files.  These export features are accessed from a TrfView plot window, by using the menu sequence "File  -  Export To...".  The resulting listing presents the currently-supported export destinations.  Note that the Excel program allows a maximum of 65536 rows, but only 256 columns:  this limits the array size that can exported from TrfView.

In general, importing Wavetrain results into analysis environments other than Matlab is not as well supported as the Matlab interface.  Specifically, the WaveTrain suite does not provide read routines for direct import of trf-file data into environments other than Matlab.

Parameters tab

The above discussion of TrfView has all been related to the tab labelled "Variables" in the main TrfView window.  Inspection of the window also shows a second tab, called "Parameters".  The "Variables" tab referred to outputs that the user requested WaveTrain to record, by  selecting variable names for recording in the Output Recording menu of the Run Set Editor (TRE).  On the other hand, the "Parameters" tab contains auxiliary information that was recorded by WaveTrain by default in the trf file.  This auxiliary information comprises the values of the Run Variables and System Parameters that were specified in the Run Set Editor (TRE) prior to execution.  This information is not needed for TrfView plotting purposes, but obviously constitutes valuable documentation of the parameter settings used for the Wavetrain runs contained in the trf file.