DiffractGUI™

User’s Guide
Graphical User Interface
for

DIFFRACT™ 7.7, 7.9, 8.1, 8.2, 8.3, 8.4

A.V. Cazan
January 2007

DiffractGUI User Guide

2

Table of Contents
1
INSTRUCTIONS TO SET UP AND RUN SIMPLE SIMULATIONS WITHINDIFFRACT’S GRAPHICAL USER INTERFACE (GUI)
7
2

INSTALLING DIFFRACTGUI

18

3

INTRODUCTION

18

3.1

Model Files

19

3.2

Start Up

19

3.3

Edit Bar21

3.4

Tool Bar22

3.5

Handling Length Units

23

3.6

Configurations

24

3.7

Fonts

24

THE LOGGERVIEW

25

4.1

25

4

5

6

LoggerView Options

WORKBENCH

25

5.1

Control Elements

26

5.2

Options for Workbench

27

5.3

Create a new object
5.3.1 ChooseObject dialog
5.3.2 Command Panel

28

5.4

Delete an object

29

5.5

Cut, Copy, Paste

29

5.6

Change the order of objects

29

5.7

Change DIFFRACT-parameters of an object

30

5.8

User-Defined Columns

34

5.9

$commands editor

36

SCRIPTVIEW

38

6.1

ScriptWizard

39

6.2

Creating a new DIFFRACT menu command block39

DiffractGUI User Guide3

6.2.1
6.2.2

7

8

Using the CommandPanel
Typing from the keyboard

6.3

Deleting a DIFFRACT menu command block

42

6.4

Changing parameter values of DIFFRACT’s command blocks

43

6.5

$commands

44

GEOSYSVIEW

46

7.1

Orientation and Zoom

47

7.2

Scene options

47

7.3

GeoSysView Options

48

7.4

Creating a new surface
7.4.1 Using ChooseObject dialog
7.4.2 Using SurfacePanel

48

7.5

Deleting a surface

49

7.6

Changing the order of surfaces

50

7.7

Changing surface parameters7.7.1 Using Edit DIFFRACT parameters dialog
7.7.2 Using the keyboard

50

7.8

Ray Tracing
7.8.1 Changing the Initial Rays
7.8.2 Thickness Dialog Box
7.8.3 Hits on Surfaces

51

7.9

View the Y Z-section of a Geometric-optical_System

58

7.10

Importing GEOP Surfaces from External File
7.10.1 File syntax
7.10.2 Examples
7.10.3 Import of Zemax (*zmx) files

59

7.11

Modify Surface Parameters with the Mouse-Wheel

66

SIGNALVIEW

69

8.1

Handling Signal Data

69

8.2

Changing the Curves

72

8.3

Changing the Display

73

8.4

Zooming and Panning

74

DiffractGUI User Guide

4

8.5

Save and Load Display Configurations

74

9

BITMAPVIEW75

10RELIEFVIEW

87

10.1

Loading a file for ReliefView

87

10.2

Scene options

88

10.3

Orientation and zoom

90

10.4

Picking data values

90

11

SESSIONVIEW

94

12LAUNCHING DIFFRACT

97

13

CLEANING UP WORKING DIRECTORY

99

14

IMPORT / EXPORT OF ZERNIKE COEFFICIENTS

101

14.1

The File Format

101

14.2

Units for Anm and Bnm

106

15

MASK DATA-FILES USED AS PHASE/AMPLITUDE OBJECTS

107

15.1

Importing distributions in WYKO file formats (*.asc, *.sdf)

120

15.2

Expected format of WYKO *.asc files

121

15.3

Storing data in DIFFRACT’s distribution file format (*.dst)

123

15.4

User-defined apertures

123

15.5

Phase-unwrapping to remove 2π phase discontinuities

125

15.6

Resizing data arrays

125

15.7

Extracting Zernike coefficients from phase distributions

127

15.8

Arithmetic Parser Inside the MaskEditor

132

15.9

Scripts in the Mask-Editor

133

15.10

Exporting Single Mask-Plots as Bitmaps

135

15.11

Exporting Single Mask-Plots as ASCII data-matrices

136

15.12

Importing Data from Bitmaps

137

15.13

Importing Data from Custom ASCII Files

141

DiffractGUI User Guide

5

16

17

COORDINATE ANALYZER

151

16.1

Mirror151

16.2

Multilayer

154

DISK EDITOR

156

17.1

Introduction

156

17.2

Launching the DiskEditor

157

17.3

The Main DiskEditor Window

159

17.4

Disk Surface Structures

163

17.5

Edit Structures Graphically

166

17.6

Vertical Cross Section

168

17.7

3D View

169

BEAM EDITOR

172

18.1

Introduction

172

18.2

Launching the BeamEditor

173

18.3

The Main BeamEditor Window

174

18.4

BEAM Parameters

178

18.5

Edit Parameters Graphically

181

18.6

Vertical Cross Section

183

18.7

3D View184

WORKFLOW EDITOR

186

19.1

The Script Editor

188

19.2

The Workflow Scripting Language
19.2.1 Variables and Constants
19.2.2 Expressions, Functions and Statements
19.2.3 Control Structures

190

19.3

Tutorial

194

DiffractGUI User Guide

6

18

19

1 Instructions to set up and run simple simulations within
DIFFRACT’s Graphical User Interface (GUI)The following instructions will help you install the Graphical User Interface of
DIFFRACT on your computer, then experiment with several simple
simulations. At the outset you must familiarize yourself with the buttons on themenu bar. Hold the cursor over each button and wait a second until the name of
the button appears on the screen. If you need additional information about aspecific button, click on the Help button first. A question mark (?) will appear
next to the cursor. With the question mark still attached to the cursor, drag the
cursor and click on the desired menu bar button. The corresponding help file
will open, allowing you to read the relevant information.

1. Start by running SETUP.EXE from your distribution disk and specify as target
a directory on your hard disk, say C:\DiffractGUI. After installation yourdirectory C:\DiffractGUI will contain several files and subdirectories (orfolders). One of the files is DiffractGUI.exe, on which you must double-click inorder to start the program. One of the folders within C:\DiffractGUI is<Diffract>. Inside C:\DiffractGUI\Diffract you should see the files Diffract.exe
and Settings.log, as well as several working subdirectories, <Work01>,<Work02>, <Work03>, etc. (Note: By double-clicking on Diffract.exe’s icon you
can launch DIFFRACT, version 8.2, without its Graphical User Interface. It is,therefore, recommended that you do NOT invoke this program, but instead run
DiffractGUI.exe from its home directory C:\DiffractGUI.) Within eachworking subdirectory, namely, C:\DiffractGUI\Diffract\Worknn, you will find atest run called Command.dat. The procedures described below will guide you
in a step-by-step fashion to run DIFFRACT and its GUI from these Command.dat
files. Once you are familiar with these test runs, you should be able to set up
your own simulations and run them under DIFFRACT and its Graphical User
Interface.

DiffractGUI User Guide

7

2. Return to the C:\DiffractGUI directory and double-click on DiffractGUI.exe.
After the title screen, you will see the main Window of DiffractGUI on yourmonitor. From the menu bar choose File_Open, then select the file
C:\DiffractGUI\Diffract\Work01\Command.dat and double-click on thefilename. A dialog box will open to inform you of the wavelength λ chosen forthis particular simulation (in units of cm, mm, µm, or nm).

Say OK to this dialog box. At this point another Window, Workbench, opens
up to show the diagram of the simulated system. (This diagram will be referred
to as the Workbench).

3. Once the Command.dat file of the optical system is opened and the
Workbench window is showing the corresponding Workbench, click on themenu bar item DIFFRACT and select Settings.

DiffractGUI User Guide

8

A dialog box will show the location and the name of DIFFRACT’s executable,
the working subdirectory, and some of the initial parameters that must be
handed over to DIFFRACT upon launching. (The parameters NDIM and NDSP thatappear in this dialog box specify, respectively, the mesh dimension used in thesimulation and the dimension of the display mesh used for various plots within
DIFFRACT.) Although these parameters are set automatically by DiffractGUI,
the user can also modify them, if need be, within the DIFFRACT_Launch_
Settings dialog box.
4. To get a better view of the system displayed in the Workbench Window,
click the mouse outside the box that confines the system diagram (i.e., outside
the Workbench), then use the ← ↑ → ↓ arrows from the keyboard to move theWorkbench, or hold down the Ctrl key while pressing the ← ↑ → ↓ keys tochange the perspective. You may apply the same operations to the individual
elements of the system by clicking the left mouse button on each object (i.e.,
selecting the object), then using the arrow keys (with or without holding down
the Ctrl key) to move and/or rotate the selected object.

DiffractGUI User Guide9

5. To observe the parameter values chosen for each object on the Workbench,double-click on the object. The Edit_DIFFRACT_Parameters dialog box will
open, and you can see the various parameter values chosen for the object. You
may edit these parameters simply by clicking the left mouse button on them andeither selecting or entering the desired new values. In the language of
DIFFRACT, the Edit_DIFFRACT_Parameters dialog box shows the corresponding
command block for the selected object, be it BEAM, LENS, MASK, PLOT, or any
other object available from DIFFRACT’s menu. Notice that the free-space
wavelength λ of the simulation is specified at the top of the command blockwithin the Edit_DIFFRACT_Parameters dialog box. By changing the units of λ(say, from mm to µm) you will notice that all length parameters within the
dialog box will automatically change accordingly. This feature allows the user
to set the units of length at the top of the command block, then enter all thelength parameters in his desired units (e.g., cm, mm, µm, nm, or even units oflambda, which means that all lengths are entered in normalized form, divided
by the free-space wavelength λ of the light source.)

6. By double-clicking in the Workbench window outside the Workbench (orinside the Workbench away from any object) you will open the
Choose_Object_to_edit dialog box. Here again you can select an object and edit
its parameters, or Shift Up or Shift Down selected objects using the buttons at
the bottom of the dialog box.

DiffractGUI User Guide

10

A new object may be added to the simulated system (i.e., the Workbench) byselecting any object on the Workbench, then selecting the NewObject
buttonon the menu bar. A list of available objects appears and, when you select one byclicking on its icon, the selected object will be inserted after the object that you
had initially selected on the Workbench.
7. Use the menu bar buttons Inflate, Deflateand Align_to_top
tochange the size of the Workbench and/or to move it to the upper left corner ofthe screen. You can also grab the box with the cursor and drag it through the
Workbench Window. Move or rotate any of the objects, then use theReposition button on the menu bar to observe the modified object reverting to
its initial position/orientation.
8. If you make a change to the system on the Workbench, you should use thebutton of the menu bar to save the corresponding Command.dat file.
Save
Observe the entire Command.dat file by clicking on the View_Command.datof the menu bar. When the Command.dat opens, you will see thebuttonlength parameters for each command block in units that are specified by theexpression (units = xx) in the upper right-hand corner of that command block.
(You may change your preferred units within the Edit_DIFFRACT_Parameters
dialog box. Then, the next time that you click on View_Command.dat, you will
see the new units at the top of the corresponding command block.)

DiffractGUI User Guide

11

9. You may insert new objects into the Workbench by first selecting an object
button of thefrom the Workbench, then clicking on the Command_Panelmenu bar. A Table of all available objects will appear, and you can pick any
object from the Command_Panel for insertion into the Workbench immediately
after the selected object on the Workbench.

This is the easiest method of inserting new objects into the simulated system. In
fact, you can build a brand new system simply by opening a new file (byclicking on File_New from the menu bar), then clicking the desired objects one
by one from the Command_Panel into the new file. You can then proceed to
double-click on each new object on the Workbench, and enter the relevant setof parameters into the corresponding command block as it appears in the EditDiffract_Parameters dialog box.

DiffractGUI User Guide1210. While in the Workbench environment, you may also look for the$commands inserted here and there within the Command.dat file. These$commands allow for looping operations within the Command.dat; they refer tocertain line numbers within various command blocks. The line numbers are
assigned by the user to each line and are placed at the end of the line
immediately after the # sign. Look for some of these line numbers on the rightmargin of the Command.dat file following the # signs. Whether Tagging aparticular item on a given line, or asking the program to Increment the value ofa particular item on a given line, or asking the program to Jump to a new line
within the Command.dat file, the $commands provide a powerful tool-set forof thecreating loops inside the Command.dat file. The $commands_editor
menu bar allows the user to insert these $commands at various locations within
the Command.dat file. All the user has to do is select the object before which
the $command(s) are to be inserted, type the first few letters of the $commandat the desired location, then press Enter. The $commands_editor of DiffractGUI
automatically inserts the correct $command at the specified location, thenallows the user to replace the unknown parameters of this $command (marked
by the place-holder ?) with specific values.

11. Once the system is constructed on the Workbench and its parameters are
specified, the user must save the Command.dat file (using the Save
buttonof the menu bar), then proceed to launch DIFFRACT using either theor the Launch_Diffract (Step)
buttons from theLaunch_Diffract (Zoom)
menu bar. In the ZOOM mode DIFFRACT goes through the entire Command.dat
file and stops only after the simulation is completed. In the STEP mode,
DIFFRACT goes through the Command.dat file in step-by-step fashion,
displaying the program’s input and output parameters one page at a time, thenwaiting for the user to press the Enter key to continue its operation. Launchingin the STEP mode allows the user to check the simulation and verify that the
DiffractGUI User Guide

13

various steps have been correctly implemented. Launching in the ZOOM mode isfor simulations that have been checked thoroughly, and should now be executedwithout any interaction with the user. In particular, when looping commands areinserted into the Command.dat file, the user may submit the job to the
Launch_Diffract (Zoom) and walk away for the duration of the simulation.
12. At the end of the simulation all the graphic files, the Session.dat file, and (ifapplicable) the Signals.dat file will be stored within the working subdirectory.
At this point the user can select any of the PLOT objects from the Workbenchbutton to see the desired plots in bitmap.
and click on the View_Bitmap(PLOT objects are used to display Intensity, Log_Intensity, Phase, Polarization,or Geometric-optical Ray distributions at various cross-sections of the system.)
Clicking on these bitmap images with the right mouse button causes a list ofavailable options to appear. Using this list, the user can choose to display thebitmap image in color or in gray-scale, can ask for a 3D plot, or inverted colors,
etc. Similarly, the user can select a PLOT object on the Workbench, then clickon the View_Relief
button to see a 3D plot of the corresponding distribution.

DiffractGUI User Guide14

If the Signals.dat file happens to have been created during a simulation – this is
generally the case when the Process_Signals object is used to compute a
combination of Detector signals and print the output to the Signals.dat file –then clicking on the View_Signals
button of the menu bar will display
plot(s) of the computed signal(s). A right mouse click on the Signals Windowshows the available options for this plotting routine.

DiffractGUI User Guide

15

Every simulation produces a text file called Session.dat within the working
subdirectory. Clicking on the View_Session.dat
button of the menu bar
displays this file, allowing the user to look for the numerical values of all input
parameters of the simulation as well as several key output parameters.
,
13. Using the remaining buttons on the menu bar (View_GEOP, and Scale_Down), you can manipulate theTrace_rays , Scale_Up
Geometric-optical Systems (GEOP), display them either in 3D or in 2D crosssection, specify a number of rays that would go through the system, then tracethese rays and observe the landing sites of the rays on various surfaces, etc. An
example of a simple Geometric-optical_System is given in Test_run3 (locatedin the working directory C:\DiffractGUI\Diffract\Work03).
Open the COMMAND.DAT file in folder <Work03> and observe a Geometricoptical_System (GEOP object) on the Workbench. Click the left-mouse-button
to openon the GEOP object, then click on the View GEOP button
GeoSysView. Inside this view, the four glass surfaces of this GEOP system will
be displayed in their proper (relative) positions and dimensions (as specified in
the GEOP object’s command block).
and ScaleDown
buttons, or simply the mouse wheel, may
The ScaleUp
be used to inflate/deflate the system in this GeoSysView. You may also use themouse cursor (with or without holding down the Ctrl key) to reposition/reorient
the system: press the left mouse button down somewhere on the windows
background, hold it down and move the mouse cursor. When necessary, use theReposition button

DiffractGUI User Guideof the EditBar to realign the system.

16

Double-click on any GEOP surface, and the Edit DIFFRACT Parameters dialog
box corresponding to that surface will open, where the parameter values may bechanged, if necessary. Double-clicking on the windows background will open
the ChooseObject to Edit dialog box for the entire GEOP. Again you may choose
any surface from the menu, and proceed to modify its parameter values as
desired. While in GeoSysView, click the right-mouse-button anywhere in thewindow for the pop-up menu to appear, then choose 2D View to observe across-sectional diagram of the GEOP system in the YZ-plane. Use the pop-up
menu again, but this time click on 3D View to revert to a 3D view of thesystem.

The pop-up menu (opened with a right-mouse click) offers several options,among them Initial Rays. Click on this option, and a dialog box will appear.
Choose some arbitrary values for dx, dy, dz, dθ, dφ (say, 0.2, 0.2, 0, 0, 0), thenclick the Add button a few times to generate several initial rays for tracing
through the system. Click the right-mouse button again, and this time choose theTrace Rays option. The traced rays will be displayed. (The same task may be
accomplished with the Trace Rays buttonof the EditBar.) You may now
select any of the GEOP surfaces, bring up the pop-up menu (with a right-mouseclick), and View Hits on that surface.1

1

The Limited Edition of DIFFRACT does not allow the RAYS option; this option normally
produces a set of rays from an incident beam on a Geometric-optical System. As such, theLimited Edition does not allow tracing of wavefronts through a GEOP. The user may thus
create an isolated GEOP within DiffractGUI, observe it in full 3D view or in cross-section(2D view), and analyze a few selected rays traced through it. Such a GEOP, however, cannot
become an object in a complete simulation that requires wavefront-tracing through the
GEOP, a feature reserved for DIFFRACT’s General and Student Editions.

DiffractGUI User Guide

17

2 Installing DiffractGUITo Install DiffractGUI on your hard disk, switch to the distribution CD-ROM, and click on
the icon for DiffractGUI’s directory. Once inside this directory, double-click on Install.bat
and follow the instructions. You will have to choose a home directory for DiffractGUI on
your hard disk, say, C:\DiffractGUI. The Install routine will transfer all the necessary files
and folders to this directory and prepares the executables for running under Windows™. The
installed folder should contain the following files and subfolders:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•

<Diffract> Contains Diffract.exe, Settings.log, and several working sub-directories.
<GeoModels77> Contains 4 files, similar naming style.
<GeoModels79> Contains 4 files, similar naming style.
<GeoModels81> Contains 4 files, similar naming style.
<GeoModels82> Contains 4 files, similar naming style.
<GeoModels83> Contains 4 files, similar naming style.
<GeoModels84> Contains 4 files, similar naming style.
<Manuals> Contains the UserGuide.
<Models77> Contains 31 files, named Mnn_xxxx.m3d.
<Models79> Contains 35 files, named Mnn_xxxx.m3d.
<Models81> Contains 35 files, named Mnn_xxxx.m3d.
<Models82> Contains 35 files, named ABCD_xxxx.m3d.
<Models83> Contains 35 files, named ABCD_xxxx.m3d.
<Models84> Contains 35 files, named ABCD_xxxx.m3d.
<Rainbow> Contains the Hard_key driver Setup.exe and Readme.doc.
<TestRuns77> Contains several command.dat files as demo-files.
<TestRuns79> Contains several command.dat files as demo-files.
<TestSystems> Contains several geometric-optical systems as demo-files.
DiffractGUI.cnt. Table of content of the help-file.
DiffractGUI.exe. The one and only executable.
DiffractGUI.hlp. The help-file.
Logfile.txt. Session’s log file.
ReadMe.txt. Last-minute information for the user.
Uninst.isu. Information needed to uninstall DiffractGUI.

Invoke DiffractGUI.exe (DIFFRACT’s Graphical User Interface) by double-clicking its icon.

3 Introduction
DiffractGUI has been developed to facilitate working with DIFFRACT. It primarily deals
with DIFFRACT’s COMMAND.DAT file. DiffractGUI can display and change in various
ways the contents of COMMAND.DAT. Furthermore, it can show and change in a 3D-mannergeometric-optical systems and it can draw as bitmaps or as 3D-reliefs DIFFRACT’s output
data-files. All output files created by DIFFRACT during a session can be visualized within
DiffractGUI’s environment.
The program is designed as an MDI-Application, able to run under Windows 98, 2000, NT,
and ME. This means that there may be more than one COMMAND.DAT file (hereinafterreferred to as “document”) opened simultaneously inside DiffractGUI. To each such

document are attached eight view-windows, which can be hidden or shown independently ofeach other. Some of these views show (in different modes) the content of the
COMMAND.DAT document, while others can open and display the contents of DIFFRACT’s
output files.
The eight available view-windows are: LoggerView, Workbench, ScriptView,
GeoSysView, SignalView, ReliefView, SessionView, and BitmapView, which will be
described in detail in this guide.

3.1 Model Files
When loading a COMMAND.DAT file, DiffractGUI splits the file internally into one or more
blocks of text. Each such block contains a DIFFRACT menu command (e.g., BEAM, LENS,
PLOT, etc.) together with the associated list of parameter values, which will be referred to as
DIFFRACT parameters. DiffractGUI’s interpreter must know what menu commands aredefined and, for each command, the order, magnitude, and type of DIFFRACT parameters. In
order to keep DiffractGUI flexible to changes in future versions of DIFFRACT, thisinformation is stored externally in so-called model files. There must be one model file foreach DIFFRACT menu command. All model files have the extension m3d and must residewithin a single folder. The name and location of this folder is arbitrary, but the user must set
this in DiffractGUI by using the Workbench Options-dialog. By default this folder is assumed
to be C:\Diffract\Modelsnn, where nn depends on the configuration (for DIFFRACT 7.7,
7.9, 8.1, 8.2, or 8.3). At the time of creation of a new document, DiffractGUI scans all thefiles within the model folder and then proceeds to update the COMMAND.DAT interpreter
accordingly.
In similar fashion, a folder must exist that contains model files for each surface-type inside a
Geometric-optical_System. (Presently there are four such surfaces: Aperture, Glass,Mirror, and Destination Plane.) When opening and displaying a Geometric-optical_System,
this folder is used to load the information needed by the GeoSys interpreter of DiffractGUI.
The folder, which is treated similarly to model folders described earlier, is assumed bydefault to be C:\Diffract\GeoModelsnn. If the name and/or location of this folder is to bechanged, the user must inform DiffractGUI by invoking the GeoSysView Options-dialog.

3.2 Start Up
When starting DiffractGUI, a small splash window is blended on the screen for a few seconds
before the main window appears. The splash window may be closed by clicking the mouseover it, by pressing return, or simply by waiting a few seconds. The following picture shows
the start-up view (with no documents opened) and the main visual elements of DiffractGUI.

DiffractGUI User Guide

19

Caption Text

Dock bar of
Edit Bar

Tool Bar

Edit Bar

Status Bar

To work in this environment, the user must either open an existing document (using FileOpen from the menu), or create a new, empty document (using File-New). When finishedcreating or modifying a document, it should be saved using File-Save or File-SaveAs menu
options.
The Tool Bar, Edit Bar, and Status Bar can be enabled and disabled by the menu items ViewToolBar, View-EditBar, and View-StatusBar. The Tool Bar and the Edit Bar may be
moved from their original position and docked on an arbitrary window side or simply left as
floating windows, by pressing the left mouse button over the dockbar and dragging to thedesired target location.

DiffractGUI User Guide20

3.3 Edit Bar
The EditBar contains shortcut buttons for frequently used commands from the Edit menu.
Icon

Menu command

Description

Edit Create

Creates and inserts a new object or surface

Edit Reposition

Redraws the screen display

Edit ScaleUp

Increases the scale-factor

Edit ScaleDown

Decreases the scale-factor

Edit Inflate

Increases display size of objects

Edit Deflate

Decreases display size of objects

Edit Align To Top

Places drawing in the upper left corner of screen

Trace Rays

Performs ray-tracing in GeoSysView

View-Settings-GeoSys

Options for GeoSysView

View-SettingsWorkbench

Options for WorkbenchView-Settings-Logger

Options for LoggerView

DiffractGUI User Guide21

3.4 Tool Bar
The ToolBar contains shortcut buttons for frequently used DiffractGUI menu commands.
Icon

Menu command

Description

File New

Creates a new empty document

File Open

Opens a file from disk

File Save

Saves currently open file

Edit Cut

Cuts selection from the view

Edit Copy

Copies selection to clipboard

Edit Paste

Pastes clipboard content into the view

File Print

Prints the active view

DIFFRACT- Launch (ZOOM)Starts DIFFRACT in ZOOM mode

DIFFRACT- Launch (STEP)

Starts DIFFRACT in STEP mode

DIFFRACT- Edit Parameters

Invokes Edit DIFFRACT Parameters dialog

DIFFRACT- $commands

Invokes $commands editor

MASK Editor

Invokes the MASK editor

View-Command Panel

Opens the command panel

View- Surface Panel

Opens the surface panel

View- WorkbenchOpens Workbench viewer

View- GeoSys

Opens GeoSysView

View- Bitmap

Opens BitmapView

View- Relief

Opens Relief View

View- Signals

Opens SignalView

View- Script

Opens active COMMAND.DAT fileView- Error Logger

Opens LogView

View- Session

Opens SESSION.DAT file-Context-sensitive help

Help-About

Displays version and serial number.

DiffractGUI User Guide

22

3.5 Handling Length Units
Earlier versions of DIFFRACT (7.7, 7.9, 8.1) expect all specified lengths to be normalized by
the wavelength. In practice, this might lead to plenty of computations if one simulates asystem whose length parameters are given in other units. To avoid these complications,DiffractGUI offers the possibility to handle lengths in centimeters (cm), millimeters (mm),micrometers (um), or nanometers (nm).
Every time a new COMMAND.DAT file is opened or created, the user is asked to specify awavelength – in cm, mm, um, or nm – that will be used to normalize all length parameters.
When saving the COMMAND.DAT file, all lengths will be normalized, then saved in unitsof the wavelength. As long as the wavelength remains unchanged during a given session, theCOMMAND.DAT file will not be affected by these manipulations.

DiffractGUI stores the specified wavelength in the header area of the Command.dat file (theheader area is generally ignored by DIFFRACT). Upon reloading this Command.dat file, thevalue of the wavelength is taken from the header area and offered as default.

The wavelength can be changed during a session by choosing the Diffract–Wavelength
menu option. In this case all length parameters will be normalized by the new wavelength.
This option should be used whenever a given physical system of fixed dimensions needs tobe examined at a different wavelength.
Beginning with DIFFRACT 8.2, which accepts the length parameters not only in wavelengths
but also in metric units, the above formalism has become obsolete, but it is retained in
DiffractGUI for compatibility with previous versions.

DiffractGUI User Guide23

3.6 Configurations
DiffractGUI can be configured to the specifications of DIFFRACT 7.7, 7.9, 8.1, 8.2, and 8.3.
The desired configuration can be specified with the menu Configuration. This menu is only
accessible when no document is loaded into DiffractGUI.

When a new configuration is selected, DiffractGUI displays the following message:

After closing this message box with the OK button, DiffractGUI stops (and must be restarted
by the user). All settings used internally are stored for each configuration in separate entriesof the registry, which means that, if you change the configuration, you should verify (uponrestarting DiffractGUI) the various internal settings such as the model-path, path to
DIFFRACT’s executable, and so on.

3.7 Fonts
The main menu command (View-Settings-Font...) opens a ChooseFont dialog box, allowing
to change the font. The selected font will be used for the View that is open when the menu
command is invoked. Not all Views allow the change of font, in which case the menu
command will be made gray (i.e., disabled). Views that do allow the font modification are:ScriptView, SignalView, SessionView, and LogView. This feature is not implemented forthe other Views (Workbench, GeoSysView, and ReliefView), where there is not much text
to be displayed. (Note: The ScriptView needs a “fixed_pitch” font type to work properly.
Hence, when you open the ChooseFont dialog box to change the font of the ScriptView,
only the fixed_pitch fonts are displayed in the available fonts list. Usually, there are not manysuch fonts installed on PCs, so the fonts list is shorter than in the ChooseFont dialogs of theother Views.)

4 The LoggerView
At start-up, DiffractGUI creates (in the background) a new text file that will contain error
reports and other information for all documents opened during the session. Since DiffractGUI
may handle multiple documents in each session, but there is only one logfile, the LoggerView
offers the possibility of seeing only those messages that are related to the currently active
document. The logfile will be overwritten in each new session of DiffractGUI, so if the user
wants to preserve this file, it must be renamed or transferred to another directory after closing
a DiffractGUI session.

4.1 LoggerView Options
The dialog is invoked by selecting from the menu View-Settings-Errorlogger. The user can
specify a new path and a new name for the log-file. If the dialog is closed by OK, the new
settings will be saved in the registry. DiffractGUI then attempts to open the specified file. If
the file exists, it will be overwritten. If opening fails, DiffractGUI displays an error message
and stops logging. In this case, you should verify (using Windows Explorer) that the specified
folder exists or that the specified file is not marked ‘read-only’.

5 Workbench
Inside this view-window a 3D-object is displayed for each DIFFRACT menu item containedin the loaded COMMAND.DAT file. The objects are arranged in the same order in which
they appear in COMMAND.DAT, and are aligned along a straight line. The first object on
this line is either BEAM or READ. When the visual interpreter encounters another BEAM or

READ, it constructs a new line of objects placed below the previous line. The direction ofeach line is given by the orientation of the BEAM or READ object at the head of that line.
The distance between objects is constant (default value = 100 pixels).
The various features of each object are stored in an associated model-file. DiffractGUI
assigns a unique name to each object, which will be displayed on the Status Bar when theuser moves the mouse over the object. Clicking over an object causes the object to be
selected. The selected object’s name appears on the Status Bar and remains there until
another object is selected.

5.1 Control Elements
Inside the Workbench, an object may be selected by a left-click over its icon. A left doubleclick will open the Edit_DIFFRACT_Parameters dialog box, allowing the user to modify theparameter values associated with the selected object. This is the only way in which the user
can change the Command.dat file.
A right double-click over an object activates the associated ScriptView and selects the
DIFFRACT menu command for that object. The selection can be skipped from one object tothe next by pressing the TAB or Shift+TAB keys.
The arrow keys (←, ↑, →, ↓) translate the objects by 10 pixels. Holding down the Ctrl-key
while pressing the arrow keys will rotate the objects by 10°. If an object is selected, only that
object will be translated or rotated, otherwise the entire group of objects will be translated or
rotated.

DiffractGUI User Guide

26

Using the menu items Edit-Inflate and Edit-Deflate one can increase or decrease the size ofthe selected object (or of the entire group of objects, if no one in particular is selected) by afixed amount (20% of actual size). The menu item Edit-Normal Size will redraw all objects
in their original size specified in model-files.
If the overall size of a system exceeds the display area, one can use the menu item EditFitToScreen to fit the object into the available screen. If an object (or group of objects)
disappears from the left-side or from the top of the display area, one should use EditAlignToTop from the menu to bring the object(s) into view. (All these operations act on theviewing area only; they do not affect the COMMAND.DAT file.)

5.2 Options for Workbench
The menu View-Settings-Workbench invokes this dialog box

The model path must point to the folder containing the model-files; otherwise DiffractGUI
will not be able to interpret the contents of COMMAND.DAT. The default distance between
the displayed (and aligned) 3D-objects may be varied (for aesthetic reasons), but it must
always be greater than zero. These options will be saved in the Windows registry when the
OK button is clicked, and remain active in subsequent DiffractGUI sessions.
For the Workbench, a background color may be specified, with the same functionality as in
the ReliefView and GeoSysView: When the BackColor button is unchecked, background color
is taken from the Windows settings (usually white). If BackColor is checked, the userspecified color is displayed.
To choose another background color, click on the colored rectangle located to the right of the
BackColor button.
When a user-defined color is chosen as background color, the window is displayed with a
top-down gradient. This is valid for all three Views mentioned: Workbench, ReliefView and
GeoSysView, as illustrated in the above picture and in the pictures on the next page.
The Workbench can be rotated by dragging with the left-mouse button and zoomed with thescroll-wheel of the mouse, similar to ReliefView and GeoSysView. Additionally, Workbenchicons can be translated by holding down the middle-mouse button (usually the scroll wheel)
while (simultaneously) moving the mouse-cursor.
The Workbench displays to the right a list of all commands used in the command.dat. It is a
textual counterpart of the graphical Workbench display and it behaves similarly. A left click
marks the item as selected and a left double-click opens the Edit_DIFFRACT_Parameters
dialog box.
DiffractGUI User Guide

27

The command list is useful especially when the Edit_DIFFRACT_Parameters dialog box isopen, which hides the objects of the Workbench. In this case, the command list can be used to
select other objects for editing without the need to close or move the
Edit_DIFFRACT_Parameters dialog box (in order to access the graphical display).

5.3 Create a new object
There are two ways to create and insert a new object into an existing system, as described
below. Both methods allow the user to create the desired object type and insert it behind aselected object. If no object has been selected, the new object will be appended to the end of
the existing sequence of objects. Initially the object parameters will be assigned default
values. However, once the new object is inserted and displayed, the user can modify its
parameter values using the Edit-DIFFRACT-parameters dialog.

5.3.1 ChooseObject dialog
The ChooseObject dialog is invoked by selecting the menu item Edit-Create. Upon selecting
one of the listed models (each model corresponds to a DIFFRACT menu command) andclicking OK, a new object will be created and inserted into the system.

5.3.2 Command Panel
The Command Panel offers a fast way to create new objects, by simply clicking the mouseover the desired object’s icon. The Command Panel can be enabled (or disabled) by selecting
the menu item View-CommandPanel. The first time you invoke the Command Panel its
icons will be constructed; a few seconds might elapse before the Command Panel takes its
final form. The Command Panel is accessible within Workbench or from the ScriptView.
The number of displayed icons is determined by the number of model-files found in the
Models folder. The various features of each icon are determined by the information stored in
the corresponding model-file.

DiffractGUI User Guide28

5.4 Delete an object
Select the object to be deleted, then press the Delete key on the keyboard, or select Edit-Cut
from the menu. If no objects are selected, a ChooseObject-dialog will appear, prompting theuser to mark an object for deletion.

5.5 Cut, Copy, Paste
Inside Workbench, a copy of the selected object may be placed on the Windows Clipboard by
the menu command Edit-Copy. The clipboard content will be overwritten. When deleting an
object with Edit-Cut, a copy of that object is posted to the clipboard prior to deletion. Thatmeans, in the case of accidentally deleting, the object may be reconstructed with Edit-Paste.
Edit-Paste imports a new object (or a chain of objects) from the clipboard. If there is aselected object in Workbench then the new object will be inserted after the selected object. If
there is no object selected, the new object will be appended to the end of the object line.
The objects are handled on the clipboard as lines of text. This allows the import/export of
DIFFRACT command blocks from/to any external text editor. When pasting from clipboard,
DiffractGUI examines the text content of the clipboard. If the first character of the first lineof text is not a ‘!’ or a ‘$’, then the clipboard content is considered erroneous and rejected.
This is important only in case you want to copy new objects from an external text editor: justensure the first character of the first copied line is a ‘!’ or a ‘$’, otherwise DiffractGUI will
not do the requested paste.

5.6 Change the order of objects
The sequential order of the objects can be changed inside the ChooseObject-Dialog. The
simplest way to invoke the ChooseObject-dialog is to double-click the mouse on the
background or to select the DIFFRACT-Edit Parameters menu item without selecting an
object. Once opened, select an object from the displayed list and use the Shift Up or Shift
Down keys to move the selected object up or down through the list. Another possibility is to
use the Cut and Paste feature: cut an object from its old position and paste it into the desired
location.

DiffractGUI User Guide29

5.7 Change DIFFRACT-parameters of an object
This is done with the Edit DIFFRACT parameters dialog, which may be invoked bydouble-clicking on an object, or by selecting the menu item DIFFRACT-Edit parameters.
The content of the list box depends on the type of the object being edited; the list is
constructed from the information available in the model-file of the object. The example
below shows the dialog box for an object of type LENS, PFOC. The first column of this box
contains guiding information similar to the comments in COMMAND.DAT files. Since eachline in a COMMAND.DAT file contains up to three parameter values plus an optional label
number (between 00 and 99), four columns P1, P2, P3 and ## appear in this dialog box.

The parameters highlighted in yellow are lengths, and are displayed in the units that are
selected in the units-combo-box. (In versions 7.7, 7.9 and 8.1 the length parameters will benormalized by the specified free-space wavelength before being transferred to DIFFRACT.
This conversion uses the value of the wavelength specified at the start of the session or at the
top of the COMMAND.DAT file). In the edit box at the top of the dialog box, a number ofcomment lines may be included for the edited object. These lines will be saved in theCommand.dat just above the command block corresponding to the object, as shown below.
!Some comment lines about this lens may be put here.
#!The lines will be stored inside the COMMAND.DAT#!Ensure that each line does not contain more then 73 characters#$#
Lens: LENS
(Units=lambda)#
Type: PFOC#
LCX,LCY: 0.00000000 0.00000000#44
NA,FL: 0.85000000 5000.0000#
Aberrations: None#
Scalar/Quasi-vector: QV#
Calculation method: APRX#
Propagation distance: 5000.0000#$#

DiffractGUI User Guide

30

You may change the displayed units by selecting another unit inside the units-combo-box:

The above selection would lead to:

The length values are not changed by this selection, only the displayed numerical values. The
suffix [mm] also changes to [um]. When you select “lambda” as the unit of length, all lengths
will be displayed normalized by the free-space wavelength:

Notice that no suffix (e.g., [lambda]) is appended in this case to the numerical values of thelengths, but they remain highlighted in yellow as a reminder that they are length values.
DiffractGUI User Guide

31

Furthermore, notice that the numerical value of the free-space wavelength has changed to 1,
indicating that it is the measurement unit for the various length parameters.

By a left mouse click over a parameter value, an edit box (see the picture above) or a combo
box (see the picture below) will open, allowing the user to make modifications. The edit box
or the combo box can be closed by a left mouse click over another parameter value inside thelist box. The type of box that appears depends on the type of the corresponding parameter: anumerical or filename value leads to an edit box, while a parameter that allows only a few
options produces a combo box. The list in the combo box can be expanded, offering all
possible options for the selected parameter. The edit box accepts only numbers (integer or
floating-point) if the corresponding value is numerical, while a filename-edit-box accepts
only correct filenames (that is, a four-letter name plus an appropriate extension).

When you are finished editing a parameter, click on some other part of the parameter list orpress ENTER, TAB or Shift + TAB. (When TAB or Shift + TAB is used, either the next or
the previous parameter will automatically open for editing.)

DiffractGUI User Guide32

If the edited parameter is a length, you may specify the units of that length by appending thesuffix mm, um, or nm to the specified value. As an example, to set the focal length of the lens(FL) in the above dialog to 780 micrometer simply type in:and press ENTER. The result will be:

If the suffix mm, um, or nm is omitted, then DiffractGUI will assume the units specified in
the units-combo-box. (In the above example this would be mm.)
A convenient feature of this dialog box is its resizeability. To change the size, move themouse cursor on the border of the dialog window until the cursor changes its shape, then dragthe box to desired size. To keep the modified parameter values, close the dialog box with the“OK” button or with the ENTER key. If closed with the “Cancel” button, all modifications
will be discarded.
Note: DiffractGUI does not check the parameter values of the object entered by the user. For
example, one could set the NA parameter of a lens to -137, which certainly makes no sense,
but DiffractGUI will accept it. The user is responsible for entering correct parameter values.

DiffractGUI User Guide33

5.8 User-Defined Columns
The command-list in Workbench and GeoSysView contains by default only two columns:
Object and Nr. However, it is possible to add new columns, which are entirely user-defined,
as exemplified in the picture below.

For each column, a title and one or more parameter names may be specified in one of two
possible ways: (i) direct input of the specification strings; (ii) from the Edit DIFFRACT
Parameters dialog box, using the mouse.
The first way is initiated by holding down the Ctrl button on the keyboard and performing aleft click anywhere on the header of the command list. The following dialog box will appear:

The user-defined columns can now be specified by typing lines of text. Each line defines a
new column in the command list. The individual token-strings must be separated by asemicolon ‘;’. Each line starts with the column title followed by one or more parameternames. This means that each column-description line must contain at least two tokens torepresent a valid column definition. Empty spaces (blanks) are ignored. The defining text canbe saved into a text-file with the Save… button; the Load… button allows to read the text
back from previously stored text files.
The column title is arbitrary and will appear later in the header of that column inside thecommand-list, but the parameter tokens should represent valid parameter names. DiffractGUI
uses these parameter-names behind the scenes during a session, hence, typically their names
are not known at the first approach. Fortunately, there is a second way to generate the userdefined columns which does not require knowledge of the parameter names. This way makes
use of the Edit DIFFRACT Parameters box, so this box must be opened first, as for example:

DiffractGUI User Guide

34

Usually, the Edit DIFFRACT Parameters (EDP) box is used to modify the displayed values,
which is initiated by a left-click on the value that is to be edited. If the Ctrl key is held down
during the click, then no edit is performed, instead, the parameter is added to the user-definedcolumns.
Before explaining the insertion mechanism in detail, it must be pointed out that, from all
existing user-defined columns, a single one can be marked as selected by a left-click oncolumn header. If the column happens to be selected already, it will be deselected, and viceversa. The selected column header is displayed embraced by ‘<’ and ‘>’, as illustrated below.

Upon a left-click in the EDP box (while holding down the Ctrl key) the following happens:
If there is a selected column, the parameter will be added to the parameter-list of that column(if not already present). If no user-defined column is selected, first it is verified if theparameter name appears in any of the existing user-defined columns. If it does appear,nothing happens. If it does not appear, then a new user-defined column is appended, having
the header named identically as the parameter.
To remove a user-defined column hold down the Ctrl and the Shift keys and click on thecolumn header. Alternatively, open the columns-text-editor (hold down Ctrl and left-click on
the header), remove the corresponding defining line and click OK.
When the list is populated with values, for each user-defined column and for each commandobject the parameter list of the column is parsed and only the first-found parameter isdisplayed. If none of the specified parameters is found, the list-cell is left empty.

DiffractGUI User Guide35

5.9 $commands editor$commands are an important feature of DIFFRACT, which provide a simple yet powerfuland flexible tool for creating loops within the COMMAND.DAT file. The $commands
editor of DiffractGUI allows the insertion and/or manipulation of these $commands in the
COMMAND.DAT file. The $commands editor may be invoked by clicking
ToolBar, or by selecting the menu option DIFFRACT-$commands.

on theAs seen in the above picture, the $commands editor maintains three lists. The list on the lefthand side, the objects-list, displays all objects on the Workbench (corresponding tocommand blocks in the command.dat file). A “virtual” QUIT object is appended to the end of
the list in order to specify $commands inserted just before the end of the file after the lastcommand block. Attached to each object is a list of all labels that exist inside thecorresponding command block.
When you select an item from the objects-list, the corresponding command block appears in
the upper-right-hand pane of the dialog box; this is referred to as the EDP-list (EDP stands
for Edit DIFFRACT_Parameters). The EDP-list, an enhanced Edit DIFFRACT Parameters
dialog, displays the command block as well as all the associated $commands, allowing
insertion/removal/modification of $commands.
The lower-right-hand pane of the $commands editor window, the commands-list, contains
all $commands within the command.dat file under consideration. Each $command isfollowed by one or two lines showing the (labelled) target lines for that $command. Whenyou select a line from this commands-list, the selected object is automatically highlighted in
the objects-list and its parameters appear in the EDP-list.
The EDP-list is the only place within the $commands editor where the user can modify the$commands; the objects-list and commands-list are exclusively for navigation andinformation. Empty $-lines can be inserted by a click over the Insert! label inside the EDP-

DiffractGUI User Guide36

list. To delete a $-line, click on the associated Remove! label. (Since each command blockmust be preceded by at least one empty $-line, the last $-line cannot be removed. Whileloading a command.dat file, DiffractGUI’s interpreter automatically inserts an empty $-line if
a command block without a preceding empty $-line is detected.) The deletion of a $-line
occurs instantly when Remove! is clicked, without further notice to the user. Some care,
therefore, is required when clicking on this element of the EDP-list.
The content of $-lines may be changed in ways similar to changing other parameters, by aclick over the desired line within the EDP-list. An edit box will replace that line, receiving
keyboard input. You do not have to type-in the complete $command; typically, the first one
or two letters of the $command followed by the numerical values of the relevant parameters
are sufficient. (It is also not necessary to input the leading $-sign.) For example, to insert thecomplete $command “$TAGS#12,ITEM1_15,ITEM1,” you can simply type T12,1,15,1,
then press the Enter key; DiffractGUI will do the rest. Missing data, if any, will show up asquestion marks (?) within the inserted $command.
Some $commands (e.g., INCREMENT, JUMP) require a control value after the colon (:)
sign, which may be edited as any other parameter value. Depending on the length units usedin the (labelled) target line of the $command, the specified control parameter should be
followed by its proper units (i.e., mm, um, nm). If the targeted parameter is not a length,
however, no units need be specified.
The $-lines may be moved around the EDP-list by drag-and-drop. Place the mouse cursor
over the line, press-and-hold the right-mouse-button while moving the cursor to the desired
location, then release the button.
After making changes to the EDP-list, it is important to click the Refresh button or to press
Enter. Subsequently, the objects-list and the commands-list will be updated to reflect thechanges. Any errors (e.g., duplicate or missing labels) will be reported in the commands-list.

DiffractGUI User Guide37

6 ScriptView
The ScriptView is a text editor that shows the content of the document (i.e., theCommand.dat file), in a readable way familiar to DIFFRACT users. It also offers thepossibility of making changes to this document. In the background of the ScriptView, aroutine called ScriptWizard detects syntax errors typed in by the user and corrects them.

The text is logically divided into a header and a number of command blocks. The first lines oftext constitute the header block (or header area). The end of the header area is marked by aline filled with ‘!’ signs. The header is followed by one or more command blocks, one foreach DIFFRACT menu object. Each block starts with a $-sign in an otherwise empty line,
followed by a line that contains a DIFFRACT menu command (here referred to as a keyword
and shown in bold green letters), and a parameter area. If there are comment lines in between
the $-lines (or between parameter-lines), they will be collected and placed together before thefirst $-line of the block. In the above picture, lines 21-23 constitute the “comment block”
associated with the BEAM object, lines 24, 25 form the $-area of BEAM, and lines 26-35 are
the command block for the BEAM.
Some keywords, such as LENS, require a subkey, e.g. PFOC, COLL, etc. The line containing
the subkey immediately follows the line containing the keyword.
Within DiffractGUI, a 3D-object (as seen in Workbench) is associated with each command
block. The only exception to this rule is the last command block of the document, the QUITblock, which is always present but has no associated 3D-object.
The main purpose of ScriptView is to display the active document exactly as it is passed to
DIFFRACT, giving the opportunity to verify the content and to make last-minute changes
before launching DIFFRACT.
Note: In DIFFRACT versions 7.7, 7.9, and 8.1 the text block ‘(Units = xx)’ has no
significance in the ScriptView and may be ignored by the user, as all lengths appearing in the
ScriptView are normalised by the free-space wavelength. However, when EditDIFFRACT_Parameters is invoked, this text block is used to display the length parameters inthe same units as initially entered by the user.

DiffractGUI User Guide38

6.1 ScriptWizard
The ScriptWizard is a COMMAND.DAT interpreter that is automatically activated whenever
the text caret moves from one line to another and text changes are detected. As long as the
caret stays on the same line, one may perform any number of changes within a single line oftext without being disturbed by the ScriptWizard.
When invoked, the ScriptWizard interprets the text and transfers all valid changes to the
document. It deletes or creates new command blocks if necessary. If the text contains errors,
the ScriptWizard restores the corresponding command block from the document. The first 25
characters of a line constitute a “comment section,” which is ignored by the ScriptWizard,
unless the very first character is a $-sign, in which case the corresponding $-command is readand interpreted.

6.2 Creating a new DIFFRACT menu command block
6.2.1 Using the CommandPanel
The CommandPanel offers a quick way to create new objects by a simple mouse click overthe desired object type. It is enabled by selecting the menu View-CommandPanel. At thevery first drawing of the CommandPanel, the icons are constructed, so it might take a few
seconds before the CommandPanel takes its final form. The CommandPanel is accessible
from within Workbench and ScriptView. When an icon from CommandPanel is selected, a
new command block is automatically inserted into the document immediately after the blockthat contains the text caret. The parameters of the new block are initialised with default
values from the corresponding model-file.
Example: Consider the picture below, and suppose the user wants to insert PROP between
LENS and PLOT objects. To this end, the user should place the text caret somewhere in theline range 41-47, then open the Command Panel with a click on the

DiffractGUI User Guide

icon of the Toolbar.

39

Clicking on the PROP icon from the Command Panel will result in:

The user may subsequently proceed to modify the parameter values of the inserted command
block.

6.2.2 Typing from the keyboard
To create a new DIFFRACT menu command block from the keyboard, the corresponding
keyword must be typed in the non-comment area of a parameter line, overwriting an existing
parameter. As soon as the caret is moved to another line, the ScriptWizard will go to work: it
restores the overwritten line, then inserts the new command block defined by the presently
entered keyword. The new block will be appended to the block containing the modified line.
If the keyword happens to require a subkey (for unique identification), the subkey must beentered following the keyword in the same line of text, separated by at least one blank fromthe keyword (e.g., LENS PFOC or LENS COLL).
Example: Consider once again the situation examined in the preceding section, and suppose
the user wants to insert a Collimator LENS between Positive-focusing LENS and PLOT
objects. To this end, the user may overwrite the last parameter (in line 47) of the positive
focusing LENS with “LENS COLL”

DiffractGUI User Guide40

then press the ↓ key to move the cursor to line 48. The result will be:

Again, the user should proceed to modify the default parameter-values that appear in theinserted command bock.

DiffractGUI User Guide

41

6.3 Deleting a DIFFRACT menu command block
A command block may be deleted by changing its keyword to an undefined key (e.g.,changing BEAM to BExAM), then moving the caret to another line. Subsequently, theScriptWizard removes the entire command block associated with the undefined keyword.
Example: To delete the LENS COLL object inserted in the previous example, modify theword LENS to something like LExNS. The ScriptWizard warns the user that it does notrecognise the modified keyword by changing the word’s color.

If you now move the text caret away from line 49, the entire command block associated withLENS COLL will be removed from the script.

DiffractGUI User Guide42

6.4 Changing parameter values of DIFFRACT’s command blocks
Upon pressing the TAB key (or SHIFT+TAB keys) on the keyboard, the caret jumps fromone value to the next, downward (or upward) through the text. Furthermore, the nearest value
string will be selected, so the changes can be made more readily. Once the text caret moves toanother line, the ScriptWizard takes control and interprets the modified line. If the changes
are compliant with DIFFRACT’s rules and the values are intelligible, ScriptWizard will
accept them, otherwise it restores the entire command block containing the line from theprevious set of valid data. When this happens, it might be useful to open the LoggerView andlook for information as to why the ScriptWizard has rejected the change(s).
In versions 7.7, 7.9 and 8.1, all length parameters will be displayed in wavelength units toreflect the exact content of the COMMAND.DAT file under consideration. To make life easier,however, Script Wizard recognizes the length units (mm, um, nm) when it interprets thecommand lines.
Example: Assume the focal length of LENS PFOC in the following command block should
be set to 1.5mm. To do this, simply type “1.5mm” as the parameter value (with no blanks
between 1.5 and mm):If the text caret is now moved to another line, ScriptWizard will take control, yielding:

Notice that the 1.5mm length has been normalized by the free-space wavelength, which, inthe present example, is λ = 780nm. The same result could have been obtained by typing“1500um” or “1.5e6nm” instead of “1.5mm”.

DiffractGUI User Guide

43

6.5 $commands
Note: The $commands-editor is a more convenient tool than ScriptView-editing for the$commands. Please read the chapter entitled $commands editor if you intend to work
extensively with the $commands.
Upon pressing the Enter key, a new line is inserted in the $-area of the command block that
presently contains the text caret. (Note: $commands cannot be inserted within the parameter
block.) The new line begins with ‘$’ and ends with ‘#’. The user may type the first one or two
letters of the desired $command in this empty $-line immediately after the $-sign. Once thetext caret is moved to another line, the ScriptWizard will identify the $command and expand
it to full size, using question marks (?) as place-holders for the unknown parameters. (The $line will remain empty if the typed $command is unknown to the Wizard.) The user will thenhave to replace the question marks with meaningful values. (Presently, the ScriptWizard does
not check the validity of the numerical values inside a $-command.)Line labels can be added to almost all lines of the COMMAND.DAT file (exceptions are thelines that contain keywords or subkeys). This is done by typing a number between 00 and 99
immediately after the # sign at the end of the line. (Labels outside the above range will berejected.) A $command line can be removed by selecting the entire line and pressing the
BackSpace key. A quick method of selecting a line is to click the mouse cursor over thecorresponding line number on the left side of the ScriptView area.
ExamplesTo insert a $TAGS#44,ITEM1_44,ITEM2 command, place the text caret somewhere in
the parameter area …

… and press Enter. A new, empty $-line will be inserted above the command block:

You may now type the following:

DiffractGUI User Guide

44

Moving the caret away from the line will signal to the ScriptWizard to complete the$command as follows:

The ScriptWizard replaces unknown parameter values with one or more question marks (?).
For example, if you type …

… the inserted $TAGS command will appear as follows:

To delete a $-line from the script, you may delete the $-sign in the beginning of the line …

… then move the caret to another line:

DiffractGUI User Guide45

7 GeoSysView
Inside this view, a Geometric-optical_System can be displayed in a 3D manner. The GEOP
block within an active COMMAND.DAT file or an external sys-file may be used as the source
for GeoSysView. The sys-file must meet the requirements specified in DIFFRACT’s manual.

PopUp menu, opened
by a mouse right-click

Geometric-optical surfaces are drawn as 3D surfaces and placed at the position given by(VCX, VCY, VCZ) coordinates of the surface. The coordinate system is shown as a 3D clusterof three coloured arrows (red/green/blue for X/Y/Z-axes). Orientation of each surface is
specified by the angles (Theta, Phi) as described in DIFFRACT’s manual.
If the active COMMAND.DAT file loaded into DiffractGUI happens to have a GEOP-object,
the user may visualize it in two steps: first select the GEOP-object on the Workbench, thenselect the View-GeoSys menu item. DiffractGUI proceeds to display the selected GEOPobject in the GeoSysView window; all subsequent changes (including loading a new systemfrom an external sys-file) will be acted upon. However, to ensure that changes to the GEOPobject associated with the GeoSysView take effect, it is recommended to close the
GeoSysView after finishing the changes.
When opening View-GeoSys, if there is no GEOP selected on the Workbench, no Geometricoptical_System will be displayed; GeoSysView will remain open as an empty window. The
user may then open within GeoSysView (using File-Open) an external sys-file for
examination or modification.
GeoSysView works similar to Workbench, but with some differences and additional features.
Geometric-optical surfaces are always drawn at positions determined by DIFFRACT

DiffractGUI User Guide46

parameter values using a proportionality factor, the distance scale. Edit-ScaleUp and EditScaleDown may be used to change this proportionality factor. (The scale may also be
modified using the mouse wheel.) The system as a whole may be rotated on the screen usingdrag-and-drop with the left mouse button; translation is achieved by holding down the CTRL
key, then dragging.

7.1 Orientation and Zoom
The Orientation_and_Zoom dialog box will open when the popup menu command
Orientation and Zoom is invoked, as illustrated below:

Usually, the orientation of the scene should be changed by dragging with the mouse on thescreen (press and hold the left mouse button, then move the mouse cursor). By specifying
values for the X angle and Y angle (and clicking on Apply or pressing Enter) the displayed
surfaces will also be rotated on the screen. Six predefined angle sets of general interest can beapplied directly with the XY, -XY, XZ, -XZ, ZY and –ZY buttons. They will position the
viewpoint on one of the three coordinate axes. To obtain a better view, it is recommended toswitch on the Ortho option, when these view positions are selected.
The system can be translated on the screen by holding down the CTRL key and dragging withthe mouse cursor. However, this will work only if the Centred option is disabled. A
subsequent checking of Centred will place the system back to the center of the screen,
discarding any preceding translations.
The size of the rendered image is determined by the Scale value. It can be changed stepwise
by a click on the UP and DOWN buttons, by direct input of a value in the edit box (and aclick on Apply or a hit on the Enter key) or, more practically, by rotating the mouse wheel.

7.2 Scene options
The Scene dialog box will open when the popup menu command Scene is invoked.
The picture to the left shows the appearance of the Scene dialog box; thefollowing options are available:•

Ortho: Changes from perspective projection to orthographic projection.
The main difference between the two modes is that in orthographic modethe depth information is not considered.

•Transparency: When checked, the various surfaces of the geometric
optical system will be drawn transparent.

•

Light: To increase the contrast of the drawing, this light source (notdirectly visible) may be activated. When the light source is activated, thecolor intensity of each facet of the displayed surfaces is changed inproportion to the angle between the facet normal and the vector from thefacet to the source.

DiffractGUI User Guide

47

•

Coord. Axes: Allows to hide or show the incident coordinate axes tripod on thescreen (x-axis red, y-axis green, z-axis blue).

•

Centred: If checked, the origin of the incident axis tripod is placed in the middle of
the window and any translation operation is disabled.

•

Axis size: Here the length of the coordinate axes may be specified. By default, thelength is 1.0 mm. However, this might appear too small or too large on the screen,
depending on the particular optical system displayed. To change the size of the axes,
type in an appropriate value, then press Enter. If the Ortho option is enabled,knowing the axis length is useful for estimating the size of the objects on the screen.

•

BackColor: If checked, the background color of the GeoSysView window will bechanged to the color displayed in the rectangle under the BackColor button. With aclick on the colored rectangle, a standard ChooseColor dialog box will open, allowing
the user to select another color as background. If unchecked, the default operating
system background color will be used.

7.3 GeoSysView Options
Angular orientation and translation steps will be taken in handling user’s translation and/or
rotation requests. The distance scale is used to scale the dimensions to screen pixels. Thisvalue can be changed by the Edit-ScaleUp and Edit-ScaleDown menu items.

When the Set As Default button is clicked, the angular and translation steps, as well as thescale are saved to the registry; any subsequent new GeoSysViews will use these values atinitialization. If the button is not clicked, only the GeoSysView invoked from within the
dialog will use those parameters. The path to the folder containing the model-files for various
surfaces should be specified here. When closing with the OK button, the model path isalways saved to the registry, whether or not the Set As Default button has been clicked.

7.4 Creating a new surface
There are two ways to create and insert a new surface in the Geometric-optical_System,
ChooseModel dialog and SurfacePanel, as described below. Both methods allow the user toselect the desired surface type, then insert the newly created surface after the currently
DiffractGUI User Guide48

selected surface. If no surface has been selected, the new surface will be appended to the endof the list. The new surface will be positioned in the middle of the line connecting theselected surface to the surface that follows. The orientation angles (θ, φ) will be set equal tothe angles of the preceding, selected surface. Initially, the surface will be assigned default
parameter values. Once the new surface is inserted and displayed, the user should set thedesired parameter values with the Edit-DIFFRACT_Parameters dialog.

7.4.1 Using ChooseObject dialog
The ChooseObject dialog is invoked by selecting the menu item Edit-Create. By selecting
one of the listed models (each model stands for a DIFFRACT surface type) and clicking OK,
a new surface is created and inserted in the system.

7.4.2 Using SurfacePanel
The SurfacePanel offers a fast way to create new surfaces, by a simple mouse click over thedesired surface icon. It can be enabled by selecting the menu item View-SurfacePanel. At
the very first drawing of the SurfacePanel, the icons are constructed, so it might take a few
seconds before the SurfacePanel takes its final form. Afterwards the SurfacePanel isaccessible from within GeoSysView. The number of model-files found in the GeoModels
folder determines the number of icons displayed. The shapes of the icons are determined by
the information stored in the corresponding model-file.

7.5 Deleting a surface
Select the surface to be deleted, then press the Delete key on the keyboard, or select the EditCut from the menu. If no surfaces are selected, a ChooseObject-dialog will be displayed,allowing the user to select surfaces for deletion. For multiple selections, hold down the Ctrl
key and add with mouse clicks the desired surfaces to the selected list.

DiffractGUI User Guide49

7.6 Changing the order of surfaces
The order of geometric-optical surfaces can be changed inside the ChooseObject-dialog. The
simplest way to invoke the ChooseObject-dialog is to double-click on the free background, orto select the DIFFRACT-Edit Parameters menu option without a selected surface. Once
opened, select a surface from the displayed list and use Shift Up and Shift Down buttons tomove the object up and down through the list.

Caution: DIFFRACT expects the sequence of surfaces encountered by the rays to be definedby the Next_if_Hit and Next_if_Miss ID numbers associated with each surface. DiffractGUI
does not check to see if the surface sequence is logically arranged.

7.7 Changing surface parameters7.7.1 Using Edit DIFFRACT parameters dialog
This feature works similar to the Workbench; see the corresponding section in the chapterthat describes the Workbench.

7.7.2 Using the keyboard
Inside GeoSysView some keys (from the keyboard) may be used to change simultaneously
the DIFFRACT parameters of the surface and its appearance on the screen. These are:
•
•
•
•
•

X or x will decrease or increase the VCX parameter of the surface.
Y or y will decrease or increase the VCY parameter of the surface.
Z or z will decrease or increase the VCZ parameter of the surface.
T or t will decrease or increase the THETA angle of the surface.
F or f will decrease or increase the PHI angle of the surface.

DiffractGUI User Guide50

If the CTRL key is held down while pressing the x, y, z, t or f keys, the parameters of theselected surface and all surfaces that follow the selected surface will be changed. At each key
hit, the values are increased/decreased always by the amount specified in the Angular stepand Translation step of the Options dialog box.

7.8 Ray Tracing
Inside the GeoSysView DiffractGUI offers the possibility to trace an arbitrary number of rays
through a Geometric-optical_System. The ray coordinates are taken with respect to thecoordinate axes of the Geometric-optical_System. Each ray is traced until it reaches thedestination plane or until it lies outside the aperture of the considered surface. All rays are
sketched on the screen (with a color specified in the GeoSysOptions-dialog). Ray-tracing ispossible only when Enable ray-tracing is activated. If the option Trace Rays When
Regenerating Draw is active, DiffractGUI will perform ray-tracing each time Regenerate
Drawing is chosen. In case of many rays and a long computation time, this option should bedeactivated. A ray tracing may then be initiated with the pop-up menu command Trace rays.

7.8.1 Changing the Initial Rays
Invoking the Initial Rays dialog from the pop-up menu enables one to define (or change) the
set of initial rays. By default only one ray having coordinates (x, y, z, θ, φ) = (0, 0, 0, 0, 0)
exists when the dialog is opened for the first time.

One or more rays can be selected from the upper list. The Delete key removes only selectedrays (if any). If all the rays are to be deleted, then they must all be selected before pressing
the Delete key. New rays can be added to the list by specifying values for x, y, z, θ, φ. The
added ray will bear the coordinates of the selected ray plus x, y, z, θ, φ. If no ray is selected,
the new ray will be appended to the list. If one or more rays are selected, then, after eachselection, a new ray will be inserted. Finally, it is possible using the Store and Load buttons
to save and read back the list of rays. The ray list is stored in a human-readable ASCII file.

DiffractGUI User Guide

51

This dialog box might be kept open during the GeoSysView session, which means that you
may return to the GeoSysView, perform any changes and switch back to InitialRays without
closing it. However, when GeoSysView is deactivated (by switching to the LoggerView, forinstance) this dialog box will be closed automatically.
An initial ray may be specified by its start point and either its polar angles (θ, φ) or a second
point in space with coordinates (x2, y2, z2). The radio-buttons Theta, Phi and X2, Y2, Z2
allow to switch between these representations.

Note that the edit boxes Theta and Phi are replaced by x2 and y2, and a new box entitled z2
will appear in the X2, Y2, Z2 mode. They may be used in the same way as Theta, Phi boxesin the Theta, Phi mode.
When an initial ray is selected in the upper list and a ray trace is performed, the intersectionsof that ray with the various surfaces among the path are tabulated in the lower list of the
dialog box. This list is not editable, but two rays from the list may be selected with a left- orright-mouse click. The identification of the selected rays is shown in the two fields named
Ray 1 and Ray 2. Once both rays are specified (the left-click specifies Ray 1, the right-click
Ray 2), DiffractGUI computes the angle between them and their point of intersection (if any).
The results are displayed in the box on the right-hand side of the dialog box.
Each ray within the Ray_List may be colored with its own individual color. Clicking the Set
color… button will open a ChooseColor dialog box, which allows the user to specify a color.
This color will then be assigned to the previously selected rays (or to all rays, if no ray has
been selected prior to clicking the Set color… button).
The Clear button will remove all duplicated rays and rays that do not hit the first surface ofthe geometric-optical system. (Note: The rays must have been traced previously through thesystem, otherwise the Clear function will remove all the rays from the list.)

DiffractGUI User Guide

52

Generate… and Import… will open dialog boxes that help to generate multiple fans of rays,
or to import initial rays from external files (like ray-plot files generated by DIFFRACT™).
More details will be given later in this chapter.
Delete will remove all selected rays (or none, if no ray is selected from the list). To empty thecomplete ray list (regardless of any eventually selected rays), click on the ALL button locatedto the right of the Delete button.
The Set and Change buttons allow to modify specific parameters of the selected rays in thelist. Again, if no rays are selected, the complete set will be affected. Before using thesebuttons, you must specify what parameters shall be modified by checking one or more of thex, y, z, Theta, Phi (or x, y, z, x2, y2, z2 in the X2, Y2, Z2 representation) parameters, thenentering values in the corresponding edit fields. Set will assign the chosen values to thetargeted rays, whereas Change will add the chosen values to the current values of the rays.
The next picture shows an example of ray-tracing with two sets of rays, colored red and blue.

The import-rays dialog box, invoked by the Import… button, permits to import a set of rays
that are specified only by the dx, dy, and dz components of their direction vectors.

The filenames may be chosen arbitrarily, but this dialog box is used especially to import raysfrom a set of three files (RXnn, RYnn and RZnn) generated by DIFFRACT™ with the PLOT
–RAYS command. Typically, this plots can be generated immediately after the conversionto-rays command inside the command.dat file. The DIFFRACT Plot ID: button will generate
automatically the filenames for the working directory from the entered ID number. For
completeness, the “…” buttons allow to browse for other files.

DiffractGUI User Guide

53

The rays will be distributed uniformly over a rectangle in the XY-plane, located at position Z
with the extensions given by the XMIN, XMAX, YMIN and YMAX fields. The First Surf
Aper button will fill in these fields to cover the aperture of the first surface in the system.
To avoid overfill, the number of imported rays is limited to the values specified in theMax.rays field. Note that the real number of imported rays may differ, because reduction
occurs by skipping rays. Increasing the number of skipped rays ensures that the limitation is
not violated, but it cannot ensure that the number of imported rays is exactly the same as thatspecified. The color of the rays can be specified with a click on the colored button in thelower right-hand side of the dialog box. Once all the desired features have been specified,import can be initiated with the Import button.

The ray-generator dialog box, opened upon clicking Generate… in the Initial_Rays dialog
box, allows to define a ray fan that emerges from a plane with a given position andorientation. The fields XMIN, XMAX, YMIN, YMAX, THETA, PHI and Z0 specify the
emerging plane. The rays will be distributed over the plane rectangle, either in a rectangularmanner or in concentric circles. The picture above shows the settings for a quadratic shape,
having 20 rows and 20 columns. If the DIVERGENCE X and Y values (in degrees) are set to0, the rays will be parallel to each other; a positive (negative) value will generate a diverging(converging) fan. Divergence angles for x and y directions may be specified independently.

A circular distribution of rays may be generated when the Elliptical option is checked, as
illustrated above. In this case, the Progressive option is available. If it is checked, the numberof rays of a given ring will be twice the number of rays of the preceding (inner) ring,otherwise the number of rays per ring will be the same for all rings.
The Append option prevents the Initial Rays dialog (which manages the collection of rays) to
be cleared before generating a new fan. With this option, therefore, multiple fans can beeasily generated. The color of the rays can be chosen with a click on the colored rectangle tothe left of the Append button.

DiffractGUI User Guide

54

The First Surf Aper button will fill the XMIN, XMAX, YMIN, YMAX values to cover theaperture of the first surface in the system. While entering numbers in the XMIN field, the
XMAX, YMIN, YMAX fields are continually updated. Hence, if you want to use nonquadratic shapes enter the XMIN value first, otherwise it will over-rule the previous choices
for the XMAX, YMIN, YMAX values.
Finally, with the Generate! button the fan of rays is created and placed in the Initial_Rays listof GeoSysView.

7.8.2 Thickness Dialog Box

The Thickness of a surface in DiffractGUI is the distance from the vertex of the surface tothe vertex of the immediate following surface. Within this dialog box, invoked with the popup menu command Thickness, the user may view and change this distance by specifying
displacements in the x-, y- and z-directions. To change the thickness, modify the dx, dy, dz
displacement values, then select Apply changes. Note that only the thickness of the surface
displayed in the title of the box (Glass_8 in the above example) will change. As aconsequence, all the following surfaces will be translated ‘en block’ such that their
thicknesses remain unchanged. This dialog box may be left open (i.e., it is ‘modeless’); its
contents are automatically refreshed for each new selected surface.

7.8.3 Hits on Surfaces
For each surface of the Geometric-optical_System, the rays that intersect the surface (within
the specified aperture of the surface) may be visualized with the Hits dialog. It is invoked by
selecting the pop-up menu command View Hits On.
The mouse wheel may be used to zoom in or out the graph of the Ray_Hits dialog box.
Dragging with the middle mouse button (usually the wheel) will pan the graph. A left doubleclick will restore its original extent. A right double-click will assign a quadratic shape (that is,
Xmin = Ymin, Xmax = Ymax), which covers all the rays. This is especially useful when thehits on the Destination Plane are displayed, since the Destination plane has no aperture thatcan be used to determine the default extensions of the graph.
The shape and size of the dots that mark the ray hits can be specified in the fields located in
the lower left-hand side of the dialog box.
By default, the dialog box display automatically the hits on the selected surface of the system.
Enabling the Lock Surface check button will over-rule this feature, so the dialog will always
display the hits of the surface that was selected when Lock Surface was checked, regardlessof the currently selected surface. Furthermore, in this mode the graph limits are not reset at

DiffractGUI User Guide

55

each update, which makes it possible to view and track sub-areas of the aperture without theneed to re-zoom and/or re-pan the display after each ray-trace.

The circle represents the aperture of the surface. The length units can be specified with the
combo box (micrometers in the above example); all angles are in degrees. Using drag-anddrop inside the surface graph, one can specify a zooming rectangle, which will expand upon
releasing the mouse button. If the graph is already zoomed, it will be restored to normal size.
DiffractGUI User Guide56

If the surface under consideration happens to be DOE-coated, the DOE’s polynomial
function, F(r ) or F(x, y), can be displayed as a coloured background bitmap by activating the
DOE F option (as shown in the previous as well as the following picture). The function’snumerical value at the position of the cursor is also displayed during the cursor movement.
By activating the frac option, only the fractional part of the DOE coating thickness is
displayed, as illustrated in the picture below.

Since this dialog box is “modeless,” you may return to the GeoSysView without closing the
dialog box. If another surface within the Geometric-optical_System is selected (e.g., bypressing the TAB key), the dialog window will display the ray_hits on the new surface.

DiffractGUI User Guide

57

7.9 View the Y Z-section of a Geometric-optical_System
When the pop-up menu command 2D View is invoked, GeoSysView displays the crosssection of the Geometric-optical_System in the YZ-plane.

In this representation, the system can still be rotated, like a plane sheet of paper. Initially, thecoordinate axes are orientated as in the right-hand-side picture above, namely, the Z-axis
points from left to right, while the Y-axis points from bottom to top. The 2D View shows theintersections of the various surfaces with the YZ-plane. If, for a given surface, the center
coordinates or the surface normal do not lie in the YZ-plane, then that surface will be drawn
as a 3D object.
Another feature of the 2D View is that the space between two adjacent surfaces will beshaded grey if the index of refraction between these surfaces departs from unity (indicating
the presence of a medium other than free space).
The various features of GeoSysView, such as ray-tracing, changing system parameters, etc.,
remain valid in the 2D View as well.

DiffractGUI User Guide

58

7.10

Importing GEOP Surfaces from External File

Within the GeoSysView in DiffractGUI, the user has the option of importing one or more
surfaces from an external file. To use this feature, open the pop-up menu with a right-mouseclick and select Import surfaces. (The imported surfaces will be inserted immediately after
the currently selected surface. When no surface is selected, the imported surfaces will beappended at the end of the current surface list.) Each newly created surface will assume theparameter values specified in a corresponding row from the external file.

7.10.1File syntax

The external file must be a text-file containing several lines of text; the accompanying
ZoneLens.TXT file is a typical example. Each line contains a number of elements (real-valued
numbers), separated by blanks or Tab-characters. The first line of text (i.e., the first row, or
the Table Header) specifies the associated columns as follows:•

The first element of the Table Header must be the four-letter word ZONE or the five-letter
word BLOCK. DiffractGUI ignores all lines of text until it encounters the ZONE or
BLOCK keyword as the first element of a line. Subsequently, this line will be regarded as
the Table Header until another ZONE or BLOCK keyword is encountered. The number oflines that follow each ZONE or BLOCK header is unlimited.

•

Beginning with the second column, the elements of the Table Header should be valid
parameter names for surfaces of type Glass, Mirror, Aperture, and Destination Plane. For
an aspheric Glass surface, for example, these may be the vertex coordinates VCX, VCY,
VCZ, orientation angles for the surface normal at the vertex, THETA, PHI, radius ofcurvature RC, conic constant K, aspheric coefficients A1 through A21, aperture radii
Rmin, Rmax, the index of refraction NREFRACT, and so on.

For each line following the Table Header, DiffractGUI inserts into the GEOP_System a Glasssurface, a Mirror surface, an Aperture, or a Destination Plane. Each line must contain at least
the same number of elements as the Table Header, otherwise no surface will be created forthat line. (If a line contains more elements than there are in the Table Header, the additional
elements will be ignored.)
The Table’s first column (i.e., that under the Header ZONE or BLOCK) may contain anarbitrary text, but DiffractGUI takes only the first character into consideration as follows: G
for a Glass surface, M for a Mirror surface, A for an Aperture, and D for a Destination Plane.
If the first character of the first element of a given line is ‘!’ that line will be considered acomment line and will subsequently be ignored by DiffractGUI.
When DiffractGUI is configured for use with DIFFRACT 7.7 or 7.9, the ‘ZONE’ and‘BLOCK’ keywords have the same meaning. However, when configured for use with
DIFFRACT 8.1 or greater, the surfaces of a ZONE-group will differ from those of a BLOCKgroup in the way they are linked together with Hit and Miss parameters. The surfaces listed
under BLOCK will have Miss = 0, while their Hit parameter automatically points to the next
surface. The surfaces listed under ZONE will have Miss pointing to the next surface and Hit
pointing to the first surface after the corresponding ZONE-group. (Note that Hit and Miss are

DiffractGUI User Guide

59

the only surface parameters whose values are not explicitly assigned; these values are implicitin the grouping and sequential arrangement of the surfaces within the import file.)
The parameter names listed in the Table Header instruct DiffractGUI to read the values fromthe corresponding column and assign them to the various surfaces. The following parameternames may be specified:A column named SSHAPE enables DiffractGUI to determine what kind of surface to create.
Such a column shall contain no numerical values, but one of the following keywords: Flat,
Spherical, Conical, Aspherical, Cylindrical, or Axiconical. The keyword-recognition iscase-sensitive and the keywords shall not be abbreviated.
VCX, VCY, VCZ, THETA, PHI specify the position and orientation of each surface.
Alternatively, DiffractGUI can use the DeltaZ or Thickness parameters (see below) tocompute the position and orientation for each new surface based on the values of the firstsurface in the imported file. By inserting columns labeled VCX, VCY, VCZ, THETA, PHI in
the import file, however, the specification based on DeltaZ or Thickness will be overridden(i.e., surfaces will be positioned regardless of the specified DeltaZ or Thickness values).
DeltaZ specifies the distance along the Z-axis between the vertex of the surface underconsideration and the vertex of the first surface within the ZONE or BLOCK group that
contains this surface. DeltaZ is not a surface parameter in DIFFRACT, but, if defined,
DiffractGUI computes the VCX, VCY, VCZ, THETA and PHI parameters of the surface basedon the specified value of DeltaZ. For the first surface of a new ZONE or BLOCK group,
DeltaZ specifies the distance to the first (leading) surface of the previous ZONE or BLOCK
group. If there is no such group, then DeltaZ will be considered the distance along the Z-axis
from the origin of the coordinate system.
Thickness specifies the distance from the vertex of the surface under consideration to thevertex of the following surface. Like DeltaZ, Thickness is not a surface parameter in
DIFFRACT, but, if defined, DiffractGUI computes the VCX, VCY, VCZ, THETA and PHIparameters of the next surface based on the Thickness value of the present surface.
Rc, K specify the radius of curvature and the conic constant of Glass and Mirror surfaces.
A1, A2, A3, …, A21 specify the aspheric constants of Glass and Mirror surfaces.
In case of a cylindrical surface, the cylinder-axis PHI and LA parameters should be specified
in columns named LPHI and LLA.
In case of an Axiconical surface, the Axicon's half-angle should be specified in a column
named AXIANGLE.
MEDIUM is the title of a column that contains one of the following keywords: Free, Homoor Grin. As in the case of SSHAPE, the user must remember the case-sensitivity of these
keywords and also refrain from abbreviation.
NREFRACT specifies the refractive index of a homogeneous medium that follows a Glasssurface.
NI, KI specify the complex index of refraction (n, k) for a Mirror surface.

DiffractGUI User Guide

60

For GRIN media additional columns entitled OX, OY, OZ, GTHETA, GPHI, N0, R0, Z0, Q1
through Q6 and W1 through W12 must be specified. The type of GRIN can be set with
GrinType, only values of 1 or 2 are allowed.
Coating may be specified with the keyword TCOAT (for glass surfaces) or RCOAT (formirrors). Valid options are AR, DOE, BARE, No (same as BARE) or Yes (same as AR). The
DOE coating parameters can be specified with DOEORDER, DOELAMBDA, DOEXPHI,
the DOE-coefficients for non-flat surfaces with B01, B02, B03 through B21 and the DOEcoefficients for flat surfaces with B1x0, B0x1, B2x0, B1x1, B0x2, B3x0, B2x1, B1x2, B0x3,
B4x0, B3x1, B2x2, B1x3, B0x4, B5x0, B4x1, B3x2, B2x3, B1x4, B0x5, B6x0, B5x1, B4x2,
B3x3, B2x4, B1x5 and B0x6.
Rmin, Rmax specify the lower and upper limits on the radius of aperture. The Rmax column
must always be present. Rmin, however, may be omitted, in which case its value will be set tozero. (In DIFFRACT 7.7 and 7.9 the Rmin value, if specified, will be ignored.)
The parameters of each surface in an imported ZONE or BLOCK may be assigned default
values by placing within the Table a line of text beginning with the keyword DEFAULT
followed by an arbitrary number of assignments of the type Name = Value. For instance, if
all Glass surfaces in a ZONE or BLOCK have the same refractive index, then the following
line will set the default value for the index of refraction:
DEFAULT NREFRACT=1.567
This option obviates the need for an additional column (named NREFRACT in the present
example), which would contain the same value in all rows. The assignment statement shall
NOT contain any blanks or Tab-characters. (For example, DEFAULT NREFRACT= 1.567 iswrong because it contains a blank after the = sign.) Blanks or Tabs are reserved for separating
one assignment from another.
Notes:••••All length units are assumed to be in mm.
It is not necessary to specify values for all parameters of a new surface. DiffractGUI
assigns the same default values as those used when inserting a new surface from theSurfacePanel.
If a column title happens to be an unknown parameter name, then the value(s) found inthat column will be ignored. This allows importing groups of surfaces that containdifferent surface types.
An import file may be created with any spreadsheet program such as the Microsoft
EXCEL. (Select the ‘Save as *.txt’ option when saving the spreadsheet.)

DiffractGUI User Guide61

7.10.2

Examples1. The following listing demonstrates a possible usage of BLOCK and Thickness.
! All surfaces have spherical shape
DEFAULT SSHAPE=Spherical! ===============================================================! This surface will be placed always at the position (0,0,20)
BLOCK Rc
Thickness NREFRACT Rmax THETA PHI VCX VCY VCZ
G1
340.785 6.5
1.517
42
0
0
0
0
20
! ===============================================================BLOCK Rc
Thickness NREFRACT Rmax THETA PHI
G2-375.235 36
1
42
0
0
G3
-120.616 8
1.517
42
0
0
! ===============================================================BLOCK Rc
Thickness Rmax THETA PHI NI
KI
M4-215.82 -8
42
0
0
0
1
! ===============================================================BLOCK Rc
Thickness NREFRACT Rmax
DEFAULT THETA=180
PHI=90G5
120.616 361
42G6
375.235 6.5
1.517
26
G7
-340.785 4
1.517
26! =========================================================BLOCK Rc
Thickness Rmax THETA PHI NI KI
M81316.482 -4
26
180
90 0 1! =========================================================BLOCK Rc
Thickness NREFRACT Rmax
DEFAULT THETA=0 PHI=0G9340.785 6.5
1.517
26
G10
-375.235 33
1
26
G11
41.443 3
1.517
16
G12
-120.616 8
1.517
16
G13
-215.82 2
1.728
14
G14
379.752 6.783
114! =========================================================! the destination plane. Since the 'Thickness' of G14 is 6.783,! it will be placed 6.783 mm beyond G14
BLOCK
D15
! ===========================================================

The above listing creates the following Geometric-optical_System (2D-View):

DiffractGUI User Guide62

2. The following listing demonstrates the usage of ZONE and DeltaZ.
! Set refractive index of the zoned lens to 1.54056
DEFAULT NREFRACT=1.54056! ===========================================================! The first zone will be placed at (0,0,3), because DeltaZ=3
ZONE Rmin Rmax
DeltaZ
Rc
K
A4
00.000 0.733 3.00000E+00 2.10100 -0.50000 3.92000E-04
10.733 0.957 -1.33722E-03 2.10147 -0.50000 3.91700E-04
20.957 1.081 -2.67444E-03 2.10194 -0.50000 3.91400E-04
31.081 1.171 -4.01166E-03 2.10240 -0.50000 3.91100E-04
41.171 1.243 -5.34888E-03 2.10287 -0.50000 3.90800E-04
51.243 1.303 -6.68611E-03 2.10334 -0.50000 3.90500E-04
61.303 1.355 -8.02333E-03 2.10381 -0.50000 3.90200E-04
71.355 1.401 -9.36055E-03 2.10428 -0.50000 3.89900E-04
81.401 1.442 -1.06978E-02 2.10474 -0.50000 3.89600E-04
91.442 1.480 -1.20350E-02 2.10521 -0.50000 3.89300E-04
101.480 1.514 -1.33722E-02 2.10568 -0.50000 3.89000E-04
111.514 1.546 -1.47094E-02 2.10615 -0.50000 3.88700E-04
121.546 1.576 -1.60467E-02 2.10662 -0.50000 3.88400E-04
131.576 1.722 -1.58003E-02 2.10654 -0.80000 4.11592E-03
141.722 1.851 -2.18773E-02 2.10868 -0.80000 4.10477E-03
15
1.851 1.956 -2.79543E-02 2.11081 -0.80000 4.09362E-03
16
1.956 2.045 -3.40314E-02 2.11294 -0.80000 4.08247E-03
172.045 2.122 -4.01084E-02 2.11507 -0.80000 4.07131E-03
18
2.122 2.191 -4.61854E-02 2.11721 -0.80000 4.06016E-03!===============================================================! G19 will be placed 2.21 mm after zone 0! G20 will be placed 1.74 mm after G19
BLOCK Rmax
DeltaZ Thickness
Rc
K
A4
MEDIUM
DEFAULT NREFRACT=1G191.866 2.21
1.74
-8.45
0 -0.016020000 Free
! ==============================================================! Note that NREFRACT as table header overrides the default
BLOCK SSHAPE Rmax
Thickness MEDIUM NREFRACT
G20
Flat
1.866
0.6
Homo
1.5798200
G21
Flat
1.866 -2.25
Free
1! =============================================================
BLOCK
Destination

The above listing creates the following geometrical optical system (2D-View):

DiffractGUI User Guide63

7.10.3

Import of Zemax (*zmx) files

GeoSysView offers the possibility to import Zemax™ files into DIFFRACT’s GEOP option.
The user must open the GeoSysView, then select the File-Open command from the menu:

Within the File-Open dialog box, select the “Zemax files *.zmx” file type, then select thedesired filename and click Open (or press ENTER).

Upon this, an intermediate Zemax_Import dialog box will appear, as shown in the next
picture. Importing a Zemax™ file is a two-stage process:1. LOADING: First the zmx-file is loaded into the Zemax_Import dialog box, whichdisplays its contents, allowing the user to recognize surface types that cannot be imported,unknown glass types and other details, without destroying the existing GEOP. This first stepis performed with the Load button.
2. IMPORTING: To convert the loaded Zemax™ surfaces into DIFFRACT™ surfaces, click
the Import button. As a result, the existing DIFFRACT™ surfaces of the current GeometricOptical System (GEOP) will be discarded and the GEOP is filled with the new surfaces.
For correct loading and importing, DiffractGUI must have access to the same glass
catalogues as used in the zmx-file. For this the path to the folder containing the glass
catalogue files (typically something like “C:\Zemax\Glasscat\”) must be specified. Inside thisfolder, only the *.agf files are necessary for loading (the *.bgf files will not be considered).

DiffractGUI User Guide

64

File info
Info line

Cat list

Glass list

Surface dataLog output

With the two “…” buttons you may browse for another *.zmx file, or for the path to the glass
catalogues (Cat list). During loading, the Cat list is filled with the glass catalogues used in the*.zmx file. Selecting one will fill the Glass list with all glasses contained in that catalogue.
When a glass is selected, its index of refraction for the primary wavelength is computed anddisplayed in the text box. This is useful to verify directly if the indices of refraction
correspond. Glass indices specified by MIL numbers are not handled by DiffractGUI.
Only the primary wavelength of the *.zmx file is considered. The lengths will always be
converted to millimeters, according to the unit used in file.
All surfaces found in the *.zmx file will be displayed in the Surface data list, which has asimilar appearance as the list used in the Zemax™ lens editor, except that it does not offer
editing capabilities. When a surface from the Surface-Data_List is selected, the Info line will
display the Extra Params of that surface (there is no room for them in the Surface_Data_List).
The coordinates and orientation of all surfaces specified in the *.zmx file are converted in the
GEOP system and listed in the Log output.
Clicking the Import button will initiate the conversion of the *.zmx-surfaces into GEOP
surfaces. The Log output will track warnings or errors that may occur during this process. For
the example shown in the previous picture, the results may look as shown below:

DiffractGUI User Guide

65

Generally, the first surface is skipped, since in Zemax™ it represents an object which has nocorrespondence in DIFFRACT™. Also skipped are surfaces that have semi-diameter (SemiD) set to zero. The last surface is generally converted to the GEOP’s Destination plane.
Standard, Tilted surf, Odd Asphere and Even Asphere surfaces are imported without
restrictions. Toroidal surfaces are imported correctly as cylindrical surfaces only if their Rx
parameter as well as their aspheric coefficients are zero. (If these parameters are non-zero, thetoroidal surface is ignored during the import process, but a warning is issued.) Alternate Even
and Alternate Odd surfaces are regarded as Even Asphere and Odd Asphere types, after
issuing a warning. All other surface types will be imported as Standard surfaces, andappropriate warnings will be issued. For use in DIFFRACT™, the radius of aperture of each
imported surface will be set equal to the semi-diameter of the corresponding Zemax™
surface. Vignetting, various types of aperture masks and all other Zemax™-specificparameters will be ignored.

7.11 Modify Surface Parameters with the Mouse-Wheel
The Edit_DIFFRACT_Parameters dialog box is useful for changing single surfaces, but it is
not very practical when multiple surfaces need modification, e.g., when a block of surfaces is
to be translated simultaneously. For such situations, a special dialog box, the Modifier dialog,
is implemented in GeoSysView. It may be invoked with the Modifier… command of the
popup menu, as shown in the following picture. The modifier dialog box holds a list oftargets that can be subsequently modified either by rotating the mouse-wheel or by enteringvalues in the list, similar to the Edit_DIFFRACT_Parameters dialog box. At each click of themouse-wheel, starting from the existing target values, new target values are computed by thefollowing rules:
NewValue = OldValue · ( (Factor – 1) · WheelFactor + 1 ) + Offset·WheelFactor
or
NewValue = ( OldValue – Offset·WheelFactor ) / ( (Factor – 1) · WheelFactor + 1 )DiffractGUI User Guide66

depending on the wheel’s rotation direction. The modifier dialog has tree operation modes:•••

Common Targets. Initiated by checking the Common Targets button.
Individual Targets. Initiated by checking the Individual Targets button.
Deactivated. Requires un-checking both Common Targets and Individual Targets
buttons.

When the dialog box is deactivated, the mouse-wheel can be used again for zooming the
GeoSysView display.

In the Common Targets mode, the modifier displays a list of different surfaces and the nameof a parameter that is to be changed for them (like VCX, VCY, VCZ, etc.). Notice that in thismode, for all surfaces of the target list only one parameter (namely the common one) can bechosen. The name of this common parameter can be selected with the predefined THETA,
PHI, VCX, VCY, or VCZ check-buttons. If the User Def: button is checked, other parameternames (like NREFRACT) may be entered directly in the edit field. The Factor and Offset canbe modified by entering new values in the corresponding edit fields. Click the Update button(or press Enter) to activate the input.
The Translate among normal option will force the target surfaces to be translated along theirindividual surface normal vectors at each wheel-click. Note that in this mode only the Offset
is considered; the Factor is meaningless. A click on the Reverse surface normal button willchange the normal vector orientation of the target surfaces by 180 degrees, keeping the vertex
position coordinates unchanged.
The parameter values of the target surfaces are continuously updated in the list. By a left
double-click in the list, the user can enter different values. However, after doing so, the Set
button has to be clicked for the modified values to be effectively transferred to the target
surfaces of the GEOP system, otherwise, at the next update, the old values will be restored in
the list. Surfaces may be removed from the target list with the Remove button. Both buttons,

DiffractGUI User Guide

67

Set and Remove apply only on the selected target surfaces, if any; otherwise they apply to theentire list.
Any GEOP surface may be added to (or removed from) the common_target_surface_list of
the modifier dialog by holding down the Ctrl key and clicking on the desired surface directlyin the GeoSysView (or on the SURFACE LIST to the right of the GeoSysView). Each surface
that is a member of the common_target_list will be displayed in the GeoSysView with asuperposed yellow mesh, its name embraced by < and > in the SURFACE LIST.
Another simple way to set up the common_target_surface_list is dragging a rectangle in the
GeoSysView scene with the right mouse button (hold down the button and move the mouse
cursor). By this action, the common target list is built up from all surfaces touched by the
dragged rectangle. (If no surfaces are touched, the common target list will be emptied.
Dragging a small rectangle on the background of the GeoSysView scene thus provides aconvenient means of clearing the common target list.)
In the Individual Targets operating mode, illustrated in the next picture, more generality isallowed in the sense that, for each surface in the list, a different parameter can be chosen. In
contrast to the Common Targets mode, a surface may appear multiple times in the list, thus
allowing literally to change all parameters of the same surface simultaneously. Finally, foreach of the target parameters, an individual Factor and Offset can be specified.
The target list is initially empty. To add a new target open the Edit DIFFRACT parameters
dialog box for the desired surface (e.g., with a left mouse double-click on the surface, or on
its name in the SURFACE LIST), hold down the Ctrl key and left click on the desired
parameter in the Edit DIFFRACT parameters dialog box. In the example picture below, theradius of curvature and the refractive index of Glass_15 have been added to the target list
using the method just described.

The Factor and the Offset are set by default to 1 for all target parameters. To change them,click on the list entry and enter a new value in the edit field that will appear. In the same way
the parameter value or the parameter name can be modified. As in the Common Targets
mode, the Individual Targets list is continuously updated, so if you want to apply the values
entered manually you should click on the Set button after making the desired changes,
otherwise they may be overwritten at the next update. Furthermore, if invalid parameternames are specified, they will be rejected from edit.
Similar to the Common Targets mode, the Remove button may be used to discard all or only
the selected parameters (if any) from a target list.
DiffractGUI User Guide

68

8 SignalView
In this view the content of DIFFRACT’s SIGNALS.DAT file is graphically displayed. Eachsignal is extracted and drawn as a curve. The various aspects of the display and of each curve
can be readily changed with a wide range of available options. When opening the
SignalView, DiffractGUI attempts to open a SIGNALS.DAT file from the directory in which
the currently active COMMAND.DAT file resides. If such a file is not found, the user isinformed about this and some default data is drawn.

PopUp menu,
opened by amouse right-click

A new SIGNALS.DAT file can be opened at any time using the menu option File-Open
while SignalView is active. (The imported filename may differ from SIGNALS.DAT.) The
content of the SIGNALS.DAT file cannot be changed, but new data sets can be generated or
added from other SIGNALS.DAT files. Any number of curves may be displayed. Associatedwith each curve are two data sets corresponding to the x– and y–values of the curve. The user
may assign all available data sets to various displayed curves.
The pop-up menu, invoked by a mouse right-click, offers the opportunity to view the signals
as numerical tables, or to change the display parameters. By choosing the Curves option of
the pop-up menu, the user can add new curves to the display, or change the various aspects ofthe existing curves. It is also possible to save the Curves data to a file.

8.1 Handling Signal Data
This dialog window is opened when the user clicks on Signals in the pop-up menu. The
extracted signals are listed on the right-hand side, of which the user can select one for further
examination. The data values of the selected signal are displayed on the left, together with theassociated tag(s).

A quick preview graph is displayed in the lower-left side of the window. Each data-set
displayed in the List-box (on the right-hand side) is automatically assigned a name, such as
Sig1_1. (By double-clicking on the name of a data-set, the user can change this name,
although the name must remain unique within the list.) Sig1_1 means: ‘Signal with ID 1
loaded from the first imported SIGNALS.DAT file.’ Using the Import SIGNALS.DAT
button, the user may load other SIGNALS.DAT files into the pool of imported data-sets.
It may happen that the SIGNALS.DAT file contains a large number of signals (up to 100) but
only few of them are needed. Signals (i.e., data-sets) that are not used may be removed fromthe list by selecting them (multiple selections are allowed), then clicking on Remove Signal.
The signals will be removed only from the list; the source SIGNALS.DAT file will NOT be
affected.
For each Signal (i.e., data-set) displayed in the list, there exist two satellite data-sets that are
not posted to the list. These are Tag1Ofxxxx and Tag2Ofxxxx, where xxxx stands for thename of the displayed data-set. Sig1_1 data-set, for example, is associated with
Tag1OfSig1_1 and Tag2OfSig1_1.
In the lower-right-hand side of the dialog window there appears an input box for the
ExpressionParser. With the help of this parser, new data-sets may be generated from theexisting ones using algebraic expressions. To generate a new Signal, type into the parser’s
input box an expression of the general form:
Left_Expression = Right_Expression
Here Left_Expression stands for the name of the new data set to be generated and RightExpression may be any valid algebraic formula. Inside this formula you may use as variables
the names of the Signals displayed in the List-box. Append to the name an index range

DiffractGUI User Guide70

(enclosed in brackets) if you want to specify only portions of the corresponding data-set.
Click on Parse_Expression or press ENTER to generate the new data-set.
Within the Right_Expression you may use the following mathematical functions: sin, cos,tan, asin, acos, atan, dsin, dcos, dtan, sinh, cosh, tanh, exp, pow(x,y), ln, log, sqrt. (Thefunctions dsin, dcos and dtan are the same as sin, cos and tan, but they expect their argument
in degrees, not radians.) Additionally, you may use the words PI and EULER for themathematical constants π and e. The expression is evaluated point-by-point, beginning withthe first index in a loop process. The parser will replace the word “Index” automatically withthe current index of the loop.
Warning: ExpressionParser is case-sensitive, meaning, for instance, that Sin instead of sin,index instead of Index or Cos instead of cos would lead to syntax errors!

Examples:SumSig = Sig1_1 + Sig2_1 + Sig3_1 + Sig4_1 produces a new Signal named SumSig whose
values are the sum of the Signals from Sig1_1, Sig2_1, Sig3_1, and Sig4_1.
ConstSig[25] = 1.23 produces a new Signal named ConstSig containing 25 data elements, all
set to 1.23.
MyIndex[5] = Index produces a new Signal named MyIndex containing five values:
0, 1, 2, 3, 4.
XLissajous[360] = sin(Index*PI/180) produces a new Signal named XLissajous containing
360 values of the sine-function over the interval (0, 360°).
YLissajous[360] = cos(2*Index*PI/180) produces a new Signal named YLissajous
containing 360 values of the cosine-function over the interval (0, 720°).
SineOfSig1=sin(Sig1_1) produces a new Signal named SineOfSig1 containing the same
number of values as Sig1_1. Each value of SineOfSig1 is the sine of the corresponding valueof Sig1_1.
CopyOfSig2 = Sig2_1 produces a new Signal named CopyOfSig2 containing the same valuesas Sig2_1.

DiffractGUI User Guide71

8.2 Changing the Curves

The dialog box on the left-hand-side above is opened when Curves is chosen from the popup menu; all displayed curves are listed here. When one of these curves is selected, thefollowing operations become available:•

Options. This opens the Curve Options dialog box (shown on the right-hand-side above)
where certain aspects of the curve as well as its x- and y-data sets can be modified.

DiffractGUI User Guide

72

•

Remove. This removes a curve from the display without changing the corresponding
data-set. If no curve is selected, all curves will be deleted.

•

AddNew. A new default curve is appended to the list, and the associated Curve Options
dialog box is opened to give the user an opportunity to configure the new curve.

•

Save. The data-set of the selected curve is exported to a text file as pairs of numbers.

8.3 Changing the Display
The various properties of the display may be changed with the pop-up menu command
Display options…

With the check-buttons LogX and LogY, the display options dialog box offers the possibility
to specify logarithmic scaling for each axis independently of the other, as illustrated below.
However, each such option is over-ruled if Xmin ≤ 0 or Ymin ≤ 0; the display will thenautomatically revert to linear scaling. (Making Xmin and/or Ymin greater then 0 will reactivate the affected log option.)DiffractGUI User Guide73

8.4 Zooming and PanningThis feature can be used only if the checkbox "Compute min/max automatically" in the
DisplayOptions dialog box is deactivated. When this box is checked, none of the user input
described below will work (i.e., DiffractGUI overrides it by min/max automation). A brief
description follows:- To zoom, press-and-hold the left mouse button, then move the mouse cursor on the screen.
A rectangle will be displayed during the mouse cursor movement. When you release themouse, the min/max values of the axes will be set to those of the rectangle. Also the old
min/max values are kept internally and restored when you simply click on the graph with theleft mouse button, without moving the mouse cursor. After the first zoom, you may continue(making zoom in zoom, etc.), but you can restore only to the min/max values of the firstzoom in the chain.
- You may also use the scroll-wheel of the mouse to zoom in or out the graph. The center ofthe zoom will always be the center of the screen, so you may want to pan the display to thedetails you want to see.
- To pan, hold down the CTRL key and drag with the left mouse button (press-and-hold theleft mouse button). Another, simpler way to pan is to drag with the middle mouse button (thisis the scroll-wheel on your mouse: do not rotate it, but press it as if it were a mouse button).
- A left-double-click on the mouse sends DiffractGUI to automatically recompute themin/max values. This is useful to restore the screen after many zoom or pan operations.

8.5 Save and Load Display Configurations
When you load Signals from a SIGNALS.DAT file into the SignalView, DiffractGUI
automatically generates some curves based on the Signals found. You can then proceed tochange certain aspects of the displayed curves, import new Signals from other SIGNALS.DAT
files, generate new Signals by evaluating algebraic expressions, and so on. Upon closing the
SignalView, however, these changes will be lost, and the curves will have to be reproduced
from scratch if you need to view them again. To avoid these complications, DiffractGUI
allows you to save the frames in configuration files and reload them in later sessions. The
Save Configuration and Load Configuration commands of the pop-up menu can be used toperform these functions.
DiffractGUI saves all relevant parameters concerning the signals displayed in SignalView(i.e., curves, data-sets, expressions) into a user-specified file. It is important to realize that
actual Signals (or data-sets) are NOT stored in these files, but only reference information
about them (e.g., Signal ID, source file, generating expression) is saved. Upon reloading,
DiffractGUI evaluates this information and reconstructs the original display.

DiffractGUI User Guide74

9 BitmapView
This view offers the possibility to convert files containing rows of numbers into a colorcoded or grey-scale bitmap picture. Within the file, the numbers must be separated by at least
one blank. The width of the bitmap (in pixels) is given by the number of elements in the firstrow, the height by the number of rows. All rows should contain the same number of elements
as the first row; any additional numbers will be truncated, while missing numbers will beassumed to be 0.
Some output data files produced by DIFFRACT meet these criteria, especially files with a.dat extension (e.g., IXnn.dat, IYnn.dat, etc.). Click on View-Bitmap button
from the
ToolBar to open the corresponding window, then select File-Open, and load the desired datafile. More than one file can be loaded at a time. The active document (COMMAND.DAT) willremain unchanged during these operations.

PopUp menu, opened
by a mouse right-click.

When the BitmapView is invoked from the Workbench and it happens that a PLOT or a
DISK object from the Workbench is selected, then the corresponding data-files areautomatically loaded from the directory of the active COMMAND.DAT file. (This, of course,
occurs only if DIFFRACT has been run previously and the relevant data-files already residein the working directory.) In this case DiffractGUI is able to determine the physicaldimensions of the drawing(s) in millimeters from the parameters of the selected PLOTobject.
With the option Show only this of the pop-up menu, the user can display one bitmap at atime; this is useful when several bitmaps are in use. To return to viewing all bitmaps, the user
must select the Show All option from the pop-up menu.
DiffractGUI User Guide

75

The Combine dialog box, opened with a click on the Combine… popup menu option, allows
to generate new plots or to modify existing ones based on any valid mathematical expression.

When entering the expression in the edit field, use the exact names of any of the loaded plots
as a variable name, as illustrated in the above picture. The expression must be of the form
name = formula, were name is the name of the plot to be modified. (If the specified plot
does not exist, it will be created, but it must be saved subsequently if you desire to keep it.)
Upon clicking the OK button (or pressing ENTER) the expression is evaluated. If no errors
occur, the expression will be attached to the combo-list and re-used later. The list ofpreviously used expressions will be preserved between DiffractGUI sessions. Furthermore, it
can be cleared with the Clear Combo button, saved into and loaded from a text file (similar to
the expression list of the MaskEditor). Errors are reported in the (non-editable) edit field
below the combo-box, which can be cleared with the Clear Log button. The combination
bitmap data is built from the data sets specified in the formula. If the combination bitmap
does not exist, a new one will be created in the memory. Since no disk file is affected or
created by this operation, the user must use the pop-up menu entry Save data or Save
picture to store the results. Save data will write the data as a human-readable ASCII file(same as in DIFFRACT). Save picture will save the data as a Windows bitmap file.
When the pop-up menu option Profiles is enabled, at each mouse left-click, the x- and ycross-sections of the displayed distribution at the cursor position will be drawn. These crosssections may be stored to disk by selecting the Save profile option of the pop-up menu.

DiffractGUI User Guide76

For better visualization of the x-y cross-sections of the plots, two satellite graph windows are
implemented, as shown in the next picture. These graphs contain both cross-sectional curves
and appear automatically when at least one of the plots has the Profiles option enabled. (Thesatellite windows are closed automatically when none of the plots calls for this option.) Like
any ordinary window, the satellite windows may be resized or moved around the screen.
Although they may be closed temporarily, they will reappear upon the next mouse click on aplot that has the Profiles option enabled. If more than one displayed plot has the Profiles
feature enabled, the cross-section(s) of the plot that was last clicked will be displayed.

256 grey (colour) levels are used to display each bitmap picture; white (red) represents thehighest and black (blue) the lowest value in the corresponding data set. Selecting the Invert
option of the pop-up menu will invert this relationship, creating a ‘negative’ image.

In the above picture the bitmap in the middle has the Colors option enabled, while therightmost bitmap has both Colors and Invert enabled. The picture also illustrates the use ofDiffractGUI User Guide

77

various length units: each plot may have its own length units specified. To align them all at
once to a specific unit, use the Units–Apply to all popup menu command.
The Show as 3D option will open the ReliefView Window (see the next section), loads intothat window the data-file associated with the bitmap image under the cursor, then generates a
3D plot of the data within the ReliefView Window.
Finally, the Update plots! command will force the BitmapView to reload all plots from theexternal files. When, during a session, several DIFFRACT™ runs occur, this feature spares
the necessity to manually reload each file independently.
The plot list on the right-hand side of the BitmapView is useful mainly when the View is set
to display a single plot (that is, the popup menu option Show only this is activated). The list
contains all plots currently loaded into BitmapView and available for display. Selecting an
item from the list forces BitmapView to display that plot. Each plot is drawn in accordancewith its various associated parameters, e.g., profile flags, color legend type, zmin − zmax
extension, etc. Since the plot list allows multiple selections, more than one plot can be
modified through the plot list. A right-click on a listed item will pop-up the same menu as aright-click within BitmapView. Hence, for example, to place more than one plot in the grayscale mode, select the plot names in the list, right-click on one of the selected names, thenselect Grayscale from the popup menu. (To select more than one name from the list use theCtrl or Shift keys of the keyboard in the typical Windows way.)

ZOOM AND PAN. When the BitmapView is in the single-plot mode, it offers the possibility
to zoom and pan the plot. To zoom, use the mouse’s scroll-wheel. To pan in the X-direction,
hold down the Shift key and turn the mouse wheel. To pan in the Y-direction, hold down the
Ctrl key and turn the mouse wheel. A left double-click on the displayed plot will restore thedefault dimensions. (Note: it is not possible to shrink the plot below its initial size; the zoom
feature is intended as a kind of magnifying glass, as illustrated in the picture below.)

DiffractGUI User Guide78

TrackerRectangle

TRACKER-RECTANGLE. Another feature available in the single-mode of BitmapView isa resizable rectangle, which can be used to pick up the data points within its borders. The
picked-up data can then be moved along and copied onto another region of the same plot, ortransferred (as an ASCII value matrix) to the Windows clipboard for subsequent pasting into
a text-editor, into other plots, or into the MaskEditor of DiffractGUI.
By default, the Tracker-Rectangle is deactivated and made invisible. To activate it, holddown the Ctrl key on the keyboard, press and hold the left mouse button, and move themouse cursor (while holding down the left button). During this operation the TrackerRectangle is displayed as a rubber-band. Upon release of the left mouse button, the TrackerRectangle will be drawn as exemplified in the above picture. Its size can be modified by
dragging the small black rectangles located on its corners and borders. The TrackerRectangle’s position can be modified by placing the cursor inside the rectangle and dragging
with the left mouse button, but it cannot be moved outside the plot borders.
The Tracker-Rectangle is initially empty, that is, it contains no data. In this state, it is drawn
transparent and is resizable. To fill the Tracker with data, place the mouse cursor over it andclick the middle mouse button (usually the mouse wheel). A second click on the middle
button will remove the data from the Tracker, making it empty again. Each click of the
middle mouse button toggles the Tracker between “filled” and “empty” states.

DiffractGUI User Guide

79

The above picture shows the Tracker’s appearance when it is filled with the underlying plotdata. The only visible difference in this state is that the Tracker-Rectangle is no longer
resizable, as indicated by the absence of the small black rectangles on its borders; zooming
the plot is also prohibited in the “filled” state. However, panning the plot and moving theTracker is allowed, so the Tracker may be placed at any other position inside the plot
boundaries.
Once the Tracker is filled, its contents may be copied into the plot at other locations, simply
by holding down the Ctrl key and clicking the middle mouse button on the Tracker.
(Warning: This operation will overwrite the plot-data in an irreversible way, without
prompting for confirmation.) The Tracker remains in the filled state after copying, thus
allowing the same content to be copied to other places as well. (Note: The Tracker-Rectangle
is also available in the MaskEditor, making it possible to create repeated features andperiodic structures on the mask.)
The Tracker-Rectangle can be switched off and removed from the screen by holding down
the Ctrl key and performing a left-click on the plot (the same action as used to initiate it).
To export fragments of a given plot from the BitmapView to the MaskEditor, copy thecontents of the Tracker-Rectangle to the clipboard (using the Edit-Copy menu command),then Paste the data to the MaskEditor. The following pictures illustrate the Copy and Paste
features of the Tracker-Rectangle. The Copy command is available when the Tracker is in thefilled state, whereas the Paste command is available only when the Tracker is switched off(i.e., not drawn on the screen).

DiffractGUI User Guide

80

COLOR LEGEND. The color legend used to build plot-bitmaps from the plot-data can be
modified for each plot with the popup menu command Legend… which opens the color
legend dialog box, as illustrated below. By default, the min-max values of the color legend
are automatically set equal to the min-max values of the plot-data. To deactivate thismechanism, deselect the Use default check-button, then enter the desired min-max values
into the corresponding edit-fields of the dialog box. This dialog box is modeless, meaningthat it does not have to be closed and reopened if you want to modify more than one plot.
Simply leave the dialog box open and select another plot-name from the list to the right of the
BitmapView; the dialog box will be automatically updated for the selected plot. Upon
entering new min-max values, the Redraw button must be clicked for changes to take effect.

DiffractGUI User Guide

81

The next picture shows the appearance of the color legend dialog box when the Use default
option is checked. The edit fields are seen to be grayed out and filled with the min-max
values of the plot-data. (This functionality may be used to determine the lowest and highest
values of the plot-data.) Any min-max values entered previously by the user are not lost; they
will reappear in the edit-fields whenever the Use default option is unchecked. All suchsettings are lost, however, when the BitmapView is closed.
From the list to the right of the dialog box, the color table can be chosen as “Rainbow colors”
or “Grayscale.” This has the same effect as using the popup menu commands “Colors” and“Grayscale.” The color legend can be inverted by checking the Invert button, which is thesame as the popup menu command Invert.

DiffractGUI User Guide

82

With the buttons and edit-fields to the right of the BitmapView (above the plot list), the minmax values of individual plots can be over-ruled, so that the same min-max values apply toall plots. To accomplish this, check the Use Common Legend button. As in the case of thecolor legend dialog box, the Use default min max button may be used to switch between
user-defined global min-max values and the min-max values taken over all plots.
Using a common legend for all the plots is useful when you use the MakeMovie feature tocreate a movie clip from the plots loaded into BitmapView. Before starting, you should selectfrom the plot list the names of the desired plots to include in the movie. (If no specific plots
are chosen, all available plots will be used.) Upon clicking on MakeMovie, DiffractGUI asks
for a filename (by default the file extension is set to *.avi, but it may be changed), then forthe compression method to be used, offering a list of available options. (This being a systemmessage, the language will be the same as that installed on your PC.)

Because MakeMovie uses the installed video capabilities of the system, this option-list mayvary on different machines. Furthermore, not all installed video codecs may be able togenerate video files being fed with the bmp-format used in BitmapView. (When in doubt, try
various formats from the list, or use the uncompressed classical avi-files format, which has
the typical disadvantage of ending up in a fairly large video file.)
The [Xmin : Xmax, Ymin : Ymax] values of each plot displayed in the BitmapView orReliefView can be modified arbitrarily with the Extents dialog box.

This dialog is invoked with the Extent… command of the popup menu. For the BitmapView,
upon closing, it applies to all plots that are found to be selected in the plot-list displayed to
the right of the BitmapView. If no plots are selected there, only the extents of the plot for
which the popup menu was initially opened will be modified.
When the metric unit is changed, the X-Min, X-Max, Y-Min, Y-Max values in the Extents
dialog box are automatically rescaled, but the metric unit used in the plot does not change.
When X-Min is modified, the X-Max, Y-Min, Y-Max values follow automatically. (If you
need non-quadratic extents for a plot, always modify the X-Min value first.)

DiffractGUI User Guide

83

The Copy and Paste buttons allow to transfer the extents via the Windows Clipboard. This isespecially useful when you need to set the extents given in the session.dat file. To this end,
open SessionView and select the lines of text containing the Length_Units and the Xmin,
Xmax, Ymin, Ymax values, as shown below:
PLOTTING ROUTINE****************
Length Units: um________________
Intensity distribution___________________________________________
Xmin= -0.500000E+01 Xmax= 0.500000E+01
Ymin= -0.500000E+01 Ymax= 0.500000E+01___________________________________________
IXmin= 0.5254E-05
IYmin= 0.8776E-14

IXmax= 0.3102E-01
IYmax= 0.9728E-08

Inside SessionView, copy the text block to the clipboard (with Ctrl+C), then return to the
BitmapView, open the Extents dialog box and click on the Paste button. The paste function of
the Extents dialog will parse for the Length Units:, Xmin=, Xmax=, Ymin=, and Ymax=
entries, then extracts the values attached to these entries. (There are no stringent requirementson the syntax or the length of the pasted text. A blank, however, is expected in front of the
Xmin=, Xmax=, Ymin=, Ymax= keywords to avoid confusion with the IXmin=, IXmax=,
IYmin=, IYmax= that may appear in the text.) Needless to say, the cut and paste functionality
may be used to export/import extents to/from other external text-files as well.
The BitmapView assigns to each plot a quadratic display area which is suitable for all plotsthat have identical extensions in the x-and y-directions. However, if the x and y extensions aredifferent, the plot will be distorted. To eliminate this distortion, the Iso-XY option of the
popup menu should be selected, as illustrated below. Both plots in the picture have the same x
and y extensions, but the plot on the right-hand side has the Iso-XY option disabled. Note that
the Iso-XY option is available only for plots that have metric units attached to them. The
same is valid for the Axes option.

DiffractGUI User Guide

84

Within BitmapView and MaskEditor the plots may be configured to display the outline-sketchof any photo-detector specified in the currently open command.dat. The picture below
illustrates this for the BitmapView (the MaskEditor implementation is identical).

The popup menu entry Overlay will expand a submenu that offer several commands related
to this feature, the most important being an actualized list of all photo-detectors (DTCT)

DiffractGUI User Guide85

defined in the command.dat. Each of them may be attached/detached from the overlay list of
the plot under consideration by a left-button click on these menu-list entries. If a photodetector is displayed on the plot, its name is checked in the popup menu. For practicalreasons, the maximum number of photo-detector entries displayed in the menu is restricted to
20. If the command.dat file happens to contain more than 20 detectors, only the first 20 willappear in the menu.
The Add all and Remove all commands will attach/detach all photo-detectors, even those notdisplayed in the menu (in case more then 20 are defined). The Update command will reattach all photo-detectors currently overlaid on the plot. This is particularly useful to actualize
the drawing when one or more photo-detector(s) have been modified in the Workbench.
The List… command will open the following dialog box:

This dialog box may be used (as menu entries) to attach/detach detectors to/from the overlay
list of the plot by a left-button mouse click on its name in the displayed list-box. An attacheddetector is displayed with gray background.
For each of the listed detectors, two colors can be specified: one used to draw the detector
outline over a plot displayed using a rainbow-colors map (Color-Mode column), the second isused when the plot is displayed with gray-levels (Gray-Mode column).
Initially, all Color-Mode colors are black and all Gray-Mode colors are red. A left-click on
one of the colored rectangles displayed in the list-box will open a standard ChooseColors
dialog box, allowing the user to modify each color individually. The colors attached to eachphoto-detector will be stored automatically in a file named pd_overlay_colors.txt located in
the same folder as the log-file. From there, the colors are reloaded automatically each time acommand.dat is opened in DiffractGUI. Note that if the load or store process fails, nowarnings or errors are issued, but the default colors are used instead.

DiffractGUI User Guide86

10 ReliefView
ReliefView
is similar to BitmapView, but it displays the data as a 3D graph. Clickon View-Relief from the DiffractGUI menu to open the corresponding window. If, at thistime, it happens that a PLOT, SAVE, READ, DISK or MASK is selected in the Workbench,
then ReliefView automatically loads the attached data-file. Otherwise, or if the file cannot be
opened, the user will be prompted to specify a file to load.

PopUp menu, opened
by a mouse right-click.

The above picture shows the general appearance of ReliefView. With a right-mouse-click, a
popup menu appears, offering features to change the display options or to analyze the data.

10.1 Loading a file for ReliefView
Within DiffractGUI’s ReliefView, one can load and view not only ASCII matrix files
containing data created by DIFFRACT’s PLOT option, but also files stored by the SAVE
command (i.e., beam distribution files, *.dst), external MASK data files, and files generatedby DIFFRACT’s export FDTD feature.
When the ReliefView is open, use the DiffractGUI menu command File-Open to select a file
type and file name for viewing. The following image illustrates how to select the file typefrom the File Open dialog box.

DiffractGUI User Guide

87Generally, first specify the type of file (ASCII matrix, BEAM, MASK or FDTD) then selectthe desired file from the file list and press Enter. Note that only one file can be displayed at atime. When a new file is loaded, the old data is discarded. Furthermore, the loaded datacannot be changed with the ReliefView. As a consequence, there is no possibility to saveanything back on the disk from here.

10.2 Scene options
The Scene dialog box will open upon invoking the popup menu command Scene.

The three pictures above show the appearance of the Scene dialog box for various types ofdata (from left to right: PLOT, BEAM or MASK, FDTD source). In contrast to a simple

DiffractGUI User Guide

88

ASCII matrix generated by PLOT, the BEAM, MASK or FDTD files contain more then one
data matrix that can be displayed. The BEAM (*.dst) and MASK files bear an amplitude anda phase, while the FDTD files have for each component of the E- and H-fields an amplitude
and a phase. From the list displayed at the bottom of the Scene dialog box, the desired data
matrix can be selected for drawing.
The following options are available in the Scene dialog:•

BackColor: If checked, the background color of the ReliefView window will bechanged to the color displayed in the rectangle at right of the BackColor button. Witha click on the colored rectangle a standard ChooseColor dialog box will be opened,allowing to select another color as the background. If unchecked, the default operating
system background color will be used.

•

Centered: If checked, the graph is displayed always in the middle of the window andany translation request is ignored.

•

Axes: Enables to hide or show the coordinate axes tripod on the screen (x-axis = red,y-axis = green, z-axis = blue).

•

Wires: Changes the drawing from solid to a wire-frame representation and vice versa.
However, if the mesh is too dense, there will be not much difference between the
representations.

•

Ortho: Changes from perspective projection to orthographic projection. The maindifference between the two is that in orthographic mode the depth information is notconsidered.

•

Frame: A parallelepiped frame surrounds the 3D-graphic object. It should not be
confused with the grid that also surrounds the relief pattern. The Frame option willshow or hide the frame on the screen.

•

Grid: This option will switch on or off the grid lines around the data. The grid lines
are drawn at the same levels as the ticks on the x, y, z-axes. It should be noted that thez-axis tick marks are the same as those on the color legend.

•

Legend: Instructs the ReliefView to show or hide the color legend bar on the left ofthe screen.

•

Light: To increase the contrast of the displayed graph, a light source (not directly
visible) may be activated. If the light source is activated, the color intensity of eachfacet of the displayed surface is changed in proportion to the angle between thenormal to the facet and the vector from the facet to the light source.

•

Labels: The labels of the three axes may be removed from the drawing. If the option
is unchecked, none of the x, y, z labels will be drawn. If the option is checked, thelabels of the x, y, z-axes can be selected independently by the X, Y and Z buttons.

DiffractGUI User Guide89

•

S vectors: This feature is relevant only for FDTD data. The ReliefView computes
from the E and H components of the electromagnetic field the Poynting vector foreach point of the data matrix. If this option is checked, the surface is always displayed
flat, with the S−vectors pointing out and displayed as gray lines. The Max size
parameter sets the length of the S−vector with the largest magnitude. Only the Svector for each Period point of the matrix is displayed.

10.3 Orientation and zoom
The Orientation and Zoom dialog box will open when the popup menu command
Orientation and Zoom is invoked. Its appearance is shown in the following image:

Usually, the orientation of the scene on the screen is changed by dragging with the mouse(press and hold the left-mouse-button, then move the mouse cursor). However, by specifying
values for the X angle and Y angle (and clicking on Apply or pressing the Enter key) the
displayed surface may also be rotated. Six predefined angle sets of general interest can be
invoked directly with the XY, -XY, XZ, -XZ, ZY and –ZY buttons. These will position the
viewpoint on one of the three coordinate axes. To obtain a better view, it is recommended toswitch on the Ortho option, when these view positions are selected.
The surface can be translated on the screen by holding down the CTRL key and dragging
with the mouse cursor. However, this will work only if the Centered option is disabled. A
subsequent checking of Centered will place the graph back to the center of the screen,
discarding any preceding translations.
The size of the graph is determined by the Scale parameter. It can be changed stepwise by aclick on the UP and DOWN buttons, by direct input of a value in the edit box (and a click on
Apply or a hit on the Enter key) or, more practically, by rotating the mouse wheel.
For large data matrices, where the drawing of the scene might require a considerable amountof time (more the ~100ms), the matrix is drawn coarser during the drag operation, in order toreduce the reaction time. Once the rotation operation is finished, the surface will be displayedin full resolution.

10.4 Picking data values
For a more precise inspection of the represented data, single x, y, z-values may be extracted
from the surface. The simplest method is to place the mouse cursor on the desired point andclick on the middle button of the mouse. If the mouse has a wheel, then press the wheel (notrotate), since on most mouse devices the wheel has the same functionality as the middle
button. If neither a wheel nor a middle button is present, then hold down the SHIFT key andclick with the left mouse button on the surface.

DiffractGUI User Guide90

As a result, the x, y, z values will be shown on the scene, as in the next picture. Additionally,a pair of perpendicular cross-sectional lines, following the surface contour, will be displayed.
Another possibility for retrieving the z-value at a given x,y-position on the surface is to use
the Z-Value command of the popup menu. A dialog box will appear, where the x, y
coordinates can be specified. Each time the Enter key is pressed or the OK button is clicked,
the z-value for the given (x, y) is displayed in the dialog’s Z-box.
Since the displayed data is extracted from a discrete matrix, it should be noticed that the zvalues for all (x, y) locations are not available. The ReliefView adjusts the requested (x, y)
coordinates to the next available point on the mesh.

The x, y, z values are printed on the status bar at the bottom of the frame window (see thepicture above). As an additional piece of information, the row and column numbers
corresponding to the point within the internal data matrix will appear on the status bar.
The extracted x, y, z values as well as the cross-sectional lines may be removed from thescreen by selecting (x, y) coordinates that lie outside the displayed area.

DiffractGUI User Guide

91

The color legend dialog box of the ReliefView is invoked by the Legend… command of the
popup menu, as displayed below. Since it works similar to the color legend dialog box of the
BitmapView, please refer to the corresponding manual section for further details.

The Margins dialog box, which is specific to ReliefView, is invoked by the Margins…
command of the popup menu that appears upon a right mouse click (see the next picture).
Within this dialog, the x-y-z extensions of a confining grid may be specified by enteringvalues for Xmin, Xmax, Ymin, Ymax, Zmin and Zmax. A click on the Redraw button will
force ReliefView to take the entered values and to redraw the scene. If the Clamp option ischecked, the surface will be truncated by the grid, otherwise it will be drawn fully, even if it
overflows the borders of the specified grid-box.
To restore the initial extensions, use the Reset button in conjunction with the small X, Y, andZ check-buttons above it; see the picture below. This operation restores only those extensions
whose check-buttons have been checked; in other words, Reset will have no effect if none of
the X, Y, Z buttons are checked.

DiffractGUI User Guide

92

The following picture shows the same scene as above, but with the Clamp option disabled.

DiffractGUI User Guide93

11 SessionView
The SessionView

provides quick access to DIFFRACT’s output file SESSION.DAT.

When invoked, SessionView displays the content of the SESSION.DAT file located within
the same directory as the currently active Command.dat file. (If the file is not found, thedisplay remains blank.) From the menu File-Open any other text-file may be loaded anddisplayed (e.g., SESSION.001). Text files may only be loaded and viewed within the
SessionView; there is no Save option.
The following rules determine the color of the text:•

A line containing all asterisks (*) as well as a line that immediately precedes this line aredisplayed in red.

•

A line containing ‘-’ will change the text color to green. This color persists until either
another line of ‘-’ or an empty line is encountered.

If the SessionView contains a growing Session.dat file (i.e., during a DIFFRACT run), thedisplay will be periodically updated.

DiffractGUI User Guide

94

Similar to ScriptView, the SessionView displays to the right a small control panel with a list
and two buttons: Select and Search. The list has two operating modes: index and search,
controlled by the state of the Search button. When the Search button is unchecked (asdisplayed above), the list is in the index-mode and displays all lines that are underlined byasterisks (‘************’). The search mode is illustrated in the next picture.
In both modes, when any list entry is selected, SessionView automatically displays thecorresponding block of text. Note that, as visible in the above picture, list entries may point toempty lines which are usually the beginning of some relevant output message blocks (startingand ending with a line of asterisks) inside the session.dat file. Even if the list entry does notcontain text for those lines, it will still work properly when it is selected, jumping to thecorresponding position in the session.dat file.
In the SessionView, lines of text can be selected or unselected with mouse left-clicks. In
conjunction with the Ctrl and Shift keys of the keyboard, other lines can be added or
removed from the selection list. The modus operandi is similar to other Windows
applications, e.g. the standard Windows Explorer program. Since SessionView is not an
ordinary text-editor, the selection is restricted to full lines, that is, fragments of a line cannot
be selected. The selected lines can be posted as text to the Windows clipboard with thestandard Edit-Copy menu command (or by using Ctrl-C) for subsequent pasting into any text
editor.
For convenience, a Select option is implemented, as shown in the above picture. When thisoption is enabled, each click in the index list would select automatically the corresponding
block of text, adding it to existing (i.e., previously selected) blocks without removing theprevious selections.

DiffractGUI User Guide95

To enter the search mode, type the desired text in the search edit box, then click the Searchbutton. Upon this click, the list will display all lines of text found to contain the specified
search-text. To refine the search, deselect the Search button and click it again.
Also for convenience, a left double-click or a right click on a list item will copy the text fromthe list directly to the search edit box, but only if the list is in the index-mode. Furthermore,
the right-click will switch the list into search mode and will initiate the search.

DiffractGUI User Guide

96

12 Launching DIFFRACT
Before invoking DIFFRACT, one should save the document as a file named
COMMAND.DAT within the desired working subdirectory. DIFFRACT can be started fromthe ToolBar using DIFFRACT_Launch (ZOOM) or DIFFRACT_Launch (STEP). The
STEP mode is recommended during the build process of COMMAND.DAT, when you may
want to check the validity of the simulation parameters. (Refer to DIFFRACT’s manual forfurther information concerning ZOOM and STEP modes). The name of the working
subdirectory, the values of the parameters NDIM and NDSP, and the Enable/Disable
Ray_Tracing feature are passed to DIFFRACT directly through the command line. You may
verify/change these parameters in DIFFRACT_Launch_Settings dialog box.

Options for DIFFRACT launcher

The menu item DIFFRACT_Settings invokes the above dialog. The path must terminate
with a backslash, and DIFFRACT executable’s name must be specified without the .exe
extension. On failure, an error message will be displayed.
ClassName is a parameter used to identify DIFFRACT’s main window. Usually the caption
text of a window is used to identify the window, but occasionally this may not be sufficient.
For example, if the explorer is open in the background and, by coincidence, its caption text
happens to be "Diffract", then DiffractGUI will erroneously activate the explorer window
instead. One way to avoid this problem is to include the ClassName of DIFFRACT’s main
window. The ClassName should be something like DIFFRACT77FRAME, but it may varydepending on the operating system and the name given to the executable file. In summary,
the ClassName is only needed if one encounters problems like the above 'explorer dummy
launch', otherwise it should be left empty. If the ClassName is not left empty, it must be thecorrect ClassName of DIFFRACT’s main window, without which DiffractGUI cannot find
DIFFRACT’s main window.
DIFFRACT executable’s path and filename, the name of the Working directory, the values of
NDIM and NDSP, and the Enable/Disable Ray_Tracing feature are set automatically eachtime the active document (i.e., a COMMAND.DAT file) is saved from (or loaded into)
DiffractGUI in accordance with the following rules:

DiffractGUI User Guide97

•The name of the Working directory is extracted from the path to the active
COMMAND.DAT file. For example, if the active document is C:\DiffractGUI\Diffract\Work\Command.dat, the launcher extracts Work as the name of the Working
directory. Nevertheless, the path of the Working directory should also be entered into
registry, in case the program fails to extract a valid path from the document’s address.
•

The path of DIFFRACT’s executable is also extracted from the fully-qualified path of theloaded/saved active document (i.e., the active COMMAND.DAT file). In the above
example, the extracted path would be C:\DiffractGUI\Diffract\. This is the location
where DiffractGUI expects to find DIFFRACT’s executable file.

•

The NDIM parameter value is extracted from the active COMMAND.DAT file by parsing
through all command blocks and comparing all the values found for NMAX and NMAY;
the maximum value thus found will determine the value of NDIM in
DIFFRACT_Launch_Settings.

•

The Enable ray-tracing box will be checked only when command blocks of the type
RAYS or FDTD_Export are found inside the loaded/saved COMMAND.DAT file.

The NDSP parameter is not modified by DiffractGUI and left to the discretion of the user.
In most cases the above choice of parameter values will be appropriate for DIFFRACT
Launch_Settings. However, you can over-rule DiffractGUI and pass another set ofparameters to DIFFRACT, simply by changing the values in the DIFFRACT
Launch_Settings dialog box. You must then close the dialog box and launch DIFFRACT
immediately, i.e., before performing another file save or load operation. (Launch parameters
are overwritten whenever a COMMAND.DAT file is saved/loaded. It is important, therefore,
to avoid any file save/load after closing the dialog box and before launching DIFFRACT.)
Notes:•Do not start DIFFRACT in the interactive mode because, in this mode, it will rename the
COMMAND.DAT file.

•

Always save the active COMMAND.DAT file in a subdirectory of the folder that contains
DIFFRACT’s executable file (i.e., where DIFFRACT.EXE resides). After a successful
launch, DiffractGUI automatically passes this file to DIFFRACT.

••Close DIFFRACT after every run, otherwise you may run into memory problems.
While DIFFRACT is computing, you may work with DiffractGUI, but NOT with the
COMMAND.DAT file that is being used by DIFFRACT. You may change other files, butchanging an active COMMAND.DAT file will have unpredictable consequences.

DiffractGUI User Guide98

13 Cleaning Up Working Directory
During a typical work session with DIFFRACT, several simulation runs are performed and,each run generates several output-files. Some of them are overwritten from run to run, someare copied and renamed for archiving purposes while others are generated new.
To avoid an excessive accumulation of such files, the CleanUp command may be used toremove them from the current working directory.

Upon a click on the Clean up … command, the Clean up dialog box appears, giving theopportunity to choose one or more of the following groups of files that are to be removed.
All Plot files: all files that match ?n??.dat, ?n??.bmp or ?n??.tif , where ? stands for any
character or digit and n for one of the letters X, Y, Z, S, L, T or P.
Old session files: all files that match session.???, where ? stands for any character or digit.
For safety, session.dat is explicitly rejected and NOT deleted.
Old command files: all files that match command.???, where ? stands for any character ordigit. For safety, command.dat is explicitly rejected and NOT deleted.
Old signals files: all files that match signals.???, where ? stands for any character or digit.
For safety, signals.dat is explicitly rejected and NOT deleted.
Custom file specifier: all files that match the filter specified in the edit box. Wildcard
characters ‘?’ and ‘*’ may be used to specify the filter. For example, ‘*.txt’ would match for
all files with the extension txt and ‘test.???’ would delete all files that have up to 3 arbitrary
characters in the extension or no extension at all.
CAUTION
The removed files cannot be recovered. Especially the custom-file filter option offers the
chance to delete also valuable files that may have been placed by other programs inside theworking directory, so this feature should be used only with precaution. For example, the filter‘*.*’ or ‘*’ would attempt to delete ALL files from the working directory. In this case, awarning message is issued, giving the chance to cancel the deletion.
As an additional measure, the files command.dat, session.dat and signals.dat are NEVER
deleted by the CleanUp feature. For all the other files, if the deletion attempt fails (forDiffractGUI User Guide99

whatever reason, for example, if some file is marked as read-only or locked by foreign
applications) it will not be re-attempted to delete that file, so it will survive the deletion.
All deletion steps will be traced in the LogView, and can be inspected once the CleanUp isfinished.

DiffractGUI User Guide100

14 Import / Export of Zernike Coefficients
DiffractGUI allows importing and exporting of the Zernike coefficients wherever they aredefined in DIFFRACT. This can be done from within the ‘Edit DIFFRACT parameters’
dialog box or from the $-commands editor box. The user must select the aberration type
‘Zernike’ from the list of object parameters, then double-click with the right mouse button
somewhere in the list. A popup menu appears with the following command options:•••

Import Zernike coefficients – Loads new values for coefficients from an external file.
Export Zernike coefficients – Writes current values of coefficients to an external file.
Erase all Zernike coefficients – Resets all the coefficients to zero.

14.1 The File Format
Zernike polynomials Wnm may be written as pure cosine expressions or as mixed sine-cosine
terms; see Eqs. (1a) and (1b) below. In the first case, which is used by DIFFRACT, the user
identifies for each polynomial the coefficients Cnm and Φnm; in the second case, thecoefficients Anm (for cosine terms) and Bnm (for sine terms) are specified.

W nm = C nm ⋅ f ( r ) ⋅ cos( m ⋅ (Φ − Φ nm ))(1a)

Wnm = Anm ⋅ f ( r ) ⋅ cos( m ⋅ Φ ) + Bnm ⋅ f ( r ) ⋅ sin( m ⋅ Φ ))(1b)

DiffractGUI can import both data formats. When importing the second type of coefficients(Anm, Bnm), DiffractGUI computes the equivalent Cnm, Φnm values as follows:

DiffractGUI User Guide101⎛ Bnm ⎞ 1⎟⎟ ⋅Φ nm = arctan⎜⎜⎝ Anm ⎠ m
Cnm = A + B
2
nm

2
nm

(2)

Each line of the file shall contain the data for one coefficient only. The line is divided into
two halves, separated by the character #; empty spaces are not counted. If the # sign is
missing, if more then one # sign is present in the line, or if one or both half-lines are empty,
the line is skipped and ignored by the interpreter. As a consequence of this rule, a line
beginning with the # sign may be regarded as a comment line.
The first half of the line shall contain one or more numbers, separated by empty spaces. Only
the last number is considered to be the value of a coefficient. The second half of the line mustspecify the kind of coefficient placed in that line. This is achieved by reading the keyword
immediately to the right of the # sign. If the keyword has the form Cnm or PHInm (where nand m stand for 0, 1, 2, 3, 4, 5, …), then the first representation of the Zernike polynomials is
assumed and the coefficient Cnm or Φnm is taken directly from that line. If, on the other hand,
the keyword has the form Anm, Bnm, or an explicit expression for f ( r ) cos( mΦ) orf ( r ) sin( mΦ), then the second representation is assumed and Cnm and Φnm are computed
using the aforementioned formulas in Eq. (2).
Notes:
•
•
•
•
•

•
•

There is no difference between the Zernike file formats in DIFFRACT 7.7, 7.9, 8.1, 8.2,
and 8.3, so the list of coefficients may be ported from one version to another.
The interpreter is case-sensitive. The keywords must be present exactly as shown in thethree example lists below (the bold-type text).
The keywords must follow immediately after the # sign. They might be followed by any
arbitrary comment (see examples).
The order of the coefficients is arbitrary (as in the second and third lists below).
In a file containing parameters of the second type, each Anm is usually accompanied by
the corresponding Bnm and vice-versa (not necessarily in adjacent lines). The exceptions
to this rule are coefficients A20, A40, A60, and A80. If some Anm does not have thecorresponding Bnm (or vice versa), then the missing coefficient will be assumed to be
zero.
The list of Zernike coefficients within a file may be incomplete, in which case thecoefficients not appearing in the Import_File will be set to zero.
DiffractGUI always exports the coefficients in the first format, that is, as Cnm, PHInm.

DiffractGUI User Guide102

An exemplary Import_File containing Zernike coefficients of the first type is shown below.
DiffractGUI recognizes only the listed keywords. For instance, an unacceptable coefficientsuch as C74 would instruct DiffractGUI to skip the line. The interpreter ignores the index
numbers appearing in the beginning of each line. The format in the following file is also
used when exporting the Zernike coefficients to a file.
# (DIFFRACT) Export from C:\Diffract81\MaskTest.dat# Zernike coefficients (Mask_1)# Index Value
Coefficient
01 -0.116068000000# C11
02 -13.2968000000# PHI1103 -0.353276000000# C20
04 0.814565000000# C22
05 -35.2386000000# PHI2206 0.105213000000# C31
07 -21.7444000000# PHI3108 0.0870823000000# C33
09 19.9486000000# PHI33
10 -0.00279300000000# C40
11 0.0758357000000# C42
12 34.1537000000# PHI42
13 0.0443355000000# C44
14 -21.3194000000# PHI44
15 0.0108659000000# C51
16 3.80460000000# PHI51
17 -0.00144002000000# C53
18 29.9072000000# PHI53
19 -0.0100861000000# C55
20 8.86905000000# PHI55
21 -0.000188000000000# C60
22 0.00332505000000# C62
23 8.69706000000# PHI62
24 -0.00887984000000# C64
25 -17.8045000000# PHI64
26 -0.00948549000000# C66
27 14.4036000000# PHI66
28 0.0141526000000# C71
29 33.8046000000# PHI71
30 0.0140322000000# C73
31 -21.6941000000# PHI73
32 0.00613673000000# C75
33 9.99418000000# PHI75
34 0.000235332000000# C77
35 11.9860000000# PHI77
36 -0.00716300000000# C80
37 0.00591692000000# C82
38 -15.9344000000# PHI82
39 0.000000000000# C84
40 0.000000000000# PHI84
41 0.000000000000# C86
42 0.000000000000# PHI86
43 0.000000000000# C88
44 0.000000000000# PHI88

DiffractGUI User Guide103

An exemplary Import_File containing the second type of Zernike coefficients is shown
below. The list of bold-type keywords appearing in this file is complete, containing all that is
actually recognized by DiffractGUI.
#Index Coefs(microns) Equation
1-0.112956 # rcos(t) (X Tilt)
2
0.026695 # rsin(t) (Y Tilt)
3-0.353276 # 2r^2-1 (Focus)
40.272212 # r^2cos(2t) (0 Astigmatism)
5-0.767735 # r^2sin(2t) (45 Astigmatism)6
0.097727 # (3r^2-2)rcos(t) (X Coma)7-0.038978 # (3r^2-2)rsin(t) (Y Coma)8-0.002793 # 6r^4-6r^2+1 (Spherical)
90.043744 # r^3cos(3t)100.075298 # r^3sin(3t)110.028031 # (4r^2-3)r^2cos(2t)120.070465 # (4r^2-3)r^2sin(2t)130.010842 # (10r^4-12r^2+3)rcos(t)140.000721 # (10r^4-12r^2+3)rsin(t)15-0.000188 # 20r^6-30r^4+12r^2-1
160.003650 # r^4cos(4t)17-0.044185 # r^4sin(4t)18-0.000007 # (5r^2-4)r^3cos(3t)19-0.001440 # (5r^2-4)r^3sin(3t)20
0.003173 # (15r^4-20r^2+6)r^2cos(2t)210.000994 # (15r^4-20r^2+6)r^2sin(2t)220.011760 # (35r^6-60r^4+30r^2-4)rcos(t)230.007874 # (35r^6-60r^4+30r^2-4)rsin(t)24-0.007163 # 70r^8-140r^6+90r^4-20r^2+1
25-0.007213 # r^5cos(5t)26-0.007050 # r^5sin(5t)27-0.002859 # (6r^2-5)r^4cos(4t)28
0.008407 # (6r^2-5)r^4sin(4t)29
0.005912 # (21r^4-30r^2+10)r^3cos(3t)30-0.012726 # (21r^4-30r^2+10)r^3sin(3t)31
0.005025 # (56r^6-105r^4+60r^2-10)r^2cos(2t)32-0.003124 # (56r^6-105r^4+60r^2-10)r^2sin(2t)33-0.000592 # r^6cos(6t)34-0.009467 # r^6sin(6t)35
0.003947 # (7r^2-6)r^5cos(5t)36
0.004699 # (7r^2-6)r^5sin(5t)370.000025 # r^7cos(7t)380.000234 # r^7sin(7t)39
0# (28r^4-42r^2+15)r^4cos(4t)40
0# (28r^4-42r^2+15)r^4sin(4t)41
0# (8r^2-7)r^6cos(6t)42
0# (8r^2-7)r^6sin(6t)430# r^8cos(8t)440# r^8sin(8t)DiffractGUI User Guide104

As an alternative to the (long) keywords in the above list, DiffractGUI recognizes thefollowing (much shorter) aliases in a one-to-one correspondence with the preceding list:#Index Coefs(microns) Equation
1-0.112956 # A11 (X Tilt)
2
0.026695 # B11 (Y Tilt)
3-0.353276 # A20 (Focus)
40.272212 # A22 (0 Astigmatism)
5-0.767735 # B22 (45 Astigmatism)6
0.097727 # A31 (X Coma)7-0.038978 # B31 (Y Coma)8-0.002793 # A40 (Spherical)
90.043744 # A33
10
0.075298 # B33
110.028031 # A42
120.070465 # B42
130.010842 # A51
140.000721 # B51
15-0.000188 # A60
160.003650 # A44
17-0.044185 # B44
18-0.000007 # A53
19-0.001440 # B53
20
0.003173 # A62
210.000994 # B62
220.011760 # A71
23
0.007874 # B71
24-0.007163 # A80
25-0.007213 # A55
26-0.007050 # B55
27-0.002859 # A64
28
0.008407 # B64
29
0.005912 # A73
30-0.012726 # B73
310.005025 # A82
32-0.003124 # B82
33-0.000592 # A66
34-0.009467 # B66
35
0.003947 # A75
36
0.004699 # B75
370.000025 # A77
38
0.000234 # B77
39
0
# A84
40
0
# B84
41
0
# A86
42
0
# B86
43
0
# A88
44
0
# B88

DiffractGUI User Guide105

14.2 Units for Anm and Bnm
The following units of measure may be specified for the Anm, Bnm coefficients:[cm] [mm] [um] [nm] centimeter millimeter micrometer nanometer micron
Each line of the Zernike import file, including comment lines, is first searched for one of thelisted unit-keywords. If one of them is found, that unit is assumed for that line and all thefollowing lines, until another line containing a valid unit-keyword is encountered. Taking that
unit under consideration, all Anm, Bnm and Cnm coefficients will be subsequently normalized
by the free-space wavelength specified in DiffractGUI, before applying the formulas ofEq.(2).
The unit-keywords shall not appear before the # sign within a given line. The keywords must
be in the form of a continuous string (i.e., no blanks or white-spaces allowed), and theabbreviated version of the keywords must be embraced by [ and ] brackets. The unitkeywords may occur at any position; both upper-case and lower-case letters are allowed. In
the following line, for example, the unit micron will be recognized.
# somecommentMicRonsnm another comment
Note that the substrings nm and mm are not recognized as units, because they are notembraced by [ and ]. The following line has no valid keywords, because the micron
characters are not contiguous:# somecommentM I c Ronsnm another comment
Multiple unit-keywords in one line should be avoided.
Note: DiffractGUI exports the Zernike coefficients always in microns.

DiffractGUI User Guide106

15 Mask Data-files used as Phase/Amplitude Objects
DIFFRACT’s External Phase/Amplitude Object (XOBJ) feature allows the user to importexternal data-files (ASCII or Binary) for insertion into the optical path as phase/amplitude
masks. These external data-files are typically created in advance, then saved as *.DAT files
to the hard disk within DIFFRACT’s working directory. Although the XOBJ feature itself has
provisions for creating such data-files (in Create mode), the user is generally free to employ
any software means to create external data-files, so long as these files adhere to the rigid
format required by XOBJ.
The External_Mask editor of DiffractGUI enables the user to build (ASCII or Binary)external data-files for later importation to DIFFRACT via the XOBJ feature. The
Mask_Editor can import a beam’s cross-section created in DIFFRACT (saved as a *.DSTfile) for use as a starting point, upon which a mask data-file is then built. Similarly, theMask_Editor can start by importing a previously created mask data-file stored in the *.DAT
format (ASCII or Binary) of data-files conforming to the XOBJ requirements; such mask
data-files are then modified within the Mask_Editor and saved as new XOBJ-compatible
data-files. Alternatively, the user can specify the desired phase/amplitude pattern of a maskusing mathematical formulas allowed by the Mask_Editor, then save the mask to the harddisk in the form of an XOBJ-compatible data-file. Irrespective of whether the initial
phase/amplitude pattern of a mask is imported from a *.DST or *.DAT file, or based upon auser-specified mathematical formula, the end result of invoking the Mask_Editor is always
the same, namely, the creation of an XOBJ-compatible *.DAT file for later importation to
DIFFRACT via the XOBJ feature.
The External_Mask editor of DiffractGUI may be invoked in one of the following ways:•

With the mask-icon from the toolbar•

With the menu command DIFFRACT – Edit external mask•

Within the Edit DIFFRACT Parameters dialog box when editing XOBJ, using either
the EDIT button or a right-mouse-click in the parameters list area.

DiffractGUI User Guide

107

Mask_Editor Dialog Box. Like any other window, the Mask_Editor dialog box (shown
below) is resizable and may span the entire screen.

Note: The Mask_Editor must NOT be closed before one can continue to work withDiffractGUI.
The Mask_Editor maintains the following six internal matrices, each having NX columns andNY rows:• Sliced Amplitude• Amplitude• Sliced Phase• Phase• Temp1• Temp2
These can be viewed only one pair at a time, by using the Amplitude, Phase and Temp
buttons. Displayed pairs are: (Amplitude, Sliced Amplitude) , (Phase, Sliced Phase) and(Temp1, Temp2). The default pair (Phase : Sliced phase) is always displayed at start-up. The

DiffractGUI User Guide108

relationships between Amplitude (A), Phase (Φ), Real (Re), and Imaginary (Im) parts of the
primary as well as sliced distributions are:

A = Re 2 + Im 2

Re = A ⋅ cos( Φ )Φ = arctan(Im/ Re)(1)

Im = A ⋅ sin( Φ )The Temp1 and Temp2 maps are intended for intermediate data storage during scriptexecution, or for initial containment of data when loading from bitmaps or custom files.
Temp1 and Temp2 can be viewed by clicking the “Temp” button at the top of the
MaskEditor; they can be manipulated like any other plot, except for slicing, which is notallowed in the case of Temp1 and Temp2.
All six matrices are initially filled with random numbers (ranging from 0 to 1). There areseveral different ways of filling these matrices with data.
•

Use the Clear button to fill the Amplitude matrix with 1’s and the Phase matrix with 0’s.
The two primary matrices will then be copied into their sliced counterparts.

•

Use the Load Beam button to load data from a previously stored distribution file (*.DST)
into Amplitude and Phase matrices (see DIFFRACT’s Manual for information on *.DST
files). The two primary matrices (Amplitude, Phase) will then be copied into their sliced
counterparts. All matrices will be resized to NX, NY values found in the loaded file.

•

Use the Load Mask button to load data from a previously stored external mask file(*.DAT) into Amplitude and Phase matrices (see DIFFRACT’s Manual for information
on External Phase/Amplitude Objects). The primary matrices will then be copied into
their sliced counterparts. All matrices will be resized to the NX, NY values found in theloaded file.

•

Use one of the Fill buttons to create matrices based on any desired formula (which has tobe typed into the expression-box above the Fill buttons). The computed data based on theuser-defined formula will then fill the displayed destination matrix. Detailed descriptionof the Fill feature will be given later in this Appendix.

The size of the matrices (NX, NY) may be increased or decreased by a factor of 2 with theaid of Double size and Half size buttons (factors other than 2 are not allowed). Increasing thematrix size adds zeros around the existing frame, while keeping it at the center of the new,enlarged frame. Decreasing the matrix size shrinks the existing frame at the periphery, while
keeping its central part intact. The maximum (minimum) allowed matrix size is 2048 (32) for
NX and NY, whichever is larger (smaller).
Warning: Upon decreasing the matrix size, the stripped-off data will be lost.
In addition to the NX, NY values, the Mask_Editor displays the values of the parameters LX,
LY, and FRQMAX, which typically accompany the loaded distribution (*.DST or *.DATfile). Changing the number of pixels NX, NY of the matrices with Double size and Half size
buttons automatically adjusts the physical size of the mesh LX, LY. The user can also set LX,
LY by typing the desired values of these parameters into the corresponding boxes, thenpressing Enter. The estimate of the maximum spatial frequency of the mask (FRQMAX), a
real number in the interval [0, 1], may also be set by the user.
DiffractGUI User Guide

109

Clicking the Save button causes the Amplitude and Phase matrices to be written into an
external data-file (*.DAT) or a beam distribution (*.DST) suitable for later importing to
DIFFRACT via the XOBJ command or via the READ command. This file may be stored in
ASCII or Binary formats by the appropriate selection in the File Open dialog box; see thepicture below. The Save Sliced Data button does the same thing for the Sliced Amplitude andPhase matrices.

In contrast to the two primary matrices (Amplitude and Phase), which can be filled with data
in various ways, the sliced matrices can be created by copying the data from the primarymatrices through a slicing operation. To create sliced matrices, open the Slice Control andselect (up to 20) slicing levels, then click on the Slice! button. Slice Control can be opened byclicking on one of the Amplitude, Phase buttons, depending on which matrix is being
displayed at the time. A right-mouse-click over a displayed plot opens a pop-up menu,
offering options for changing various aspects of the plot. The Slice entry in the pop-up menu
also opens Slice Control (same as clicking on Amplitude or Phase buttons). Slice control
offers the following options:•

To insert a new level-marker click the left mouse button inside the colored channel bar.
(Up to 20 markers can be created within the Slice Control.)•To delete an existing level-marker, perform a right-mouse-click on the marker.

•

To change the position of a level-marker, drag it with the mouse cursor. A marker can be
moved only in the range between its adjacent neighbors.

•

The Slice Control is resizable. Thus, when the number of levels is large, the user canstretch the Slice Control to enhance readability.

•

If no level-markers are defined when the Slice! operation is invoked, the existing primarymatrix (Amplitude, Phase) will be copied directly (with no changes whatsoever) into the
Sliced matrix.

•

Mask_Editor maintains two Slice Controls (associated with Amplitude and Phase). While
the Mask_Editor remains active, each Slice Control can be closed and re-opened without

DiffractGUI User Guide

110

losing the corresponding level-markers. When opening for the first time, each SliceControl is displayed without level markers.
•

The minimum and maximum values of the Slice Control are actualized only when SliceControl is opened. Hence it is recommended to keep the Slice Control closed while
manipulating the matrices otherwise.

The picture below shows an example of the Mask_Editor with opened Slice Control and popup menu. The (primary) phase matrix displayed on the left-hand side has been loaded from a
distribution file created (and saved) previously by DIFFRACT. The sliced phase plot on theright-hand side is the result of slicing the primary phase matrix at levels indicated within the
Slice Control.

Fill Function and Arithmetic Interpreter. A powerful feature of DiffractGUI’s Mask
Editor is the Fill function, invoked by clicking one of the Fill buttons of the Editor or by
selecting the popup-menu entry Fill!. This function submits an arithmetic expression, written
in the expression-box above the Fill buttons, to an arithmetic interpreter. The interpreter thenevaluates the expression and replaces the content of the target matrix with the result of its
computation.
The interpreter recognizes the basic arithmetic operators /, *, +, – . Parentheses ( ) can be usedin their standard role as arithmetic delimiters with unlimited concatenation levels.
Additionally, the following operators are recognized (a and b are numbers):
•
•
•
•
•
•
•

| (Logical OR):a | b returns 0 if a and b are 0; returns 1 otherwise.
& (Logical AND): a & b returns 1 if a and b are non-zero; returns 0 otherwise.
= (Comparison):a = b returns 1 if a equals b; returns 0 otherwise.
^ (Raise to Power): a ^ b returns a raised to the power of b.
< (Less Than):a < b returns 1 if a is less then b; returns 0 otherwise.
> (Greater Than): a > b returns 1 if a is greater then b; returns 0 otherwise.
% (Modulo):
a % b returns remainder of a/b; works only with integer a, b.

DiffractGUI User Guide

111

The argument-less function rand( ) generates a random number between 0 and 1.
The following one-argument functions may be used in arithmetic expressions: sin, cos, tan,sinh, cosh, tanh, dsin, dcos, dtan, atan, asin, acos, exp, ln, log, sqrt, abs, not, sgn, floor,ceil. For all trigonometric functions the argument angle must be in radians, except for dsin,
dcos, dtan, which accept their argument in degrees (hence the letter d in the function name).
Returned angles from the inverse trigonometric functions are in radians. ln is the natural
logarithmic function while log is the base 10 logarithmic function. not returns 1 if theargument is 0, and returns 0 otherwise. sgn is the signum function, returning 0 if theargument is 0, 1 if the argument is positive, and –1 if the argument is negative. floor returns
the largest integer less than its argument, while ceil returns the smallest integer greater thanits argument.
The following two-argument functions may be used in arithmetic expressions: and, or, xor,
mod, pow, max, min. The logical functions and, or, xor return the values 0 or 1, dependingon their arguments. An argument that is 0 is interpreted as FALSE, otherwise it is considered
to be TRUE. mod is the modulo function, returning the remainder after dividing the firstargument by the second. In contrast to the % operator, the mod function operates on nonintegers and integers alike. pow is the same as the ^ operator, returning the value obtained byraising the first argument to the power of the second (the second argument is not required to
be an integer). max and min return the larger and smaller of their two arguments,
respectively.
The arithmetic interpreter also recognizes the three-argument function cond(a, b, c). Thisfunction evaluates the first argument; if it is non-zero the function returns the second
argument, otherwise it returns the third. In conjunction with the predefined variables (seebelow), this function is very useful for changing only restricted areas of the matrix.
Additionally, the following general-purpose functions are implemented:
atan(y,x) : computes arctangent (y/x), returns a value between 0 and 2π.
atan180(y,x) : computes arctangent (y/x), returns a value between −π and π.
dist(x,y) : computes √x2 + y2.
J0(x), J1(x), Jn(x) : Bessel functions of the first kind: orders 0, 1, and n, respectively.
Y0(x), Y1(x), Yn(x) : Bessel functions of the second kind: orders 0, 1, and n, respectively.
sinc(x) : computes sin(x)/x; returns 1 for x = 0.
Jinc(x) : computes J1(x)/x; returns ½ for x = 0.
factorial(n) : computes n!
gamma(x) : computes the gamma-function Γ(x)erf(x) : computes the error-function

DiffractGUI User Guide

2

x

−t
∫ e dt2

π 0112

erfc(x) : computes the complementary error-functionbeta(x,y) : computes the beta-function as

2

∞

−t
∫ e dt2

π x

Γ( x ) ⋅ Γ( y )Γ( x + y )⎛n⎞n!
bincoe(n,k) : computes the binomial coefficient ⎜⎜ ⎟⎟ =⎝ k ⎠ k!⋅(n − k )!
The interpreter recognizes PI as π (3.1415927…), EULER as the base of the natural
logarithm e (2.71….), true as 1, and false as 0. Also the following predefined variables may
be used (instead of numbers) in arithmetic expressions:•

I (or ROW) refers to a row, while J (or COL) refers to a column of the matrix.

•

X, Y refer to the x- and y-coordinates of the plot.

•

R, PHI refer to the radius and the azimuthal angle φ of the plot. R is distance from thecenter. PHI is the angle between the radius and the x-axis. Measured counterclockwisefrom the x-axis, the value of PHI [0 : 360°] is generally specified in degrees.

•

V refers to the actual value of the matrix element (before evaluating the expression).

•

VMAX, VMIN refer to the maximal and minimal values of the matrix.

•

A refers to the actual value of the amplitude matrix.

•

P refers to the actual value of the phase matrix.

•

SA refers to the actual value of the sliced amplitude matrix•

SP refers to the actual value of the sliced phase matrix
Warning: The arithmetic interpreter of the Mask_Editor is case-sensitive.

For unit-conversions the following constants are available:

mm : 1um or µm : 10−3
nm : 10−6
cm : 10degree : π /180
radian : 180/ π

DiffractGUI User Guide

113

The mm, um (or µm), nm, and cm constants have been implemented to facilitate lengthconversions. DiffractGUI stores all lengths internally in mm, hence to convert, for instance,
123 um to mm, simply type 123*um. To convert, 12.34 mm to um, type 12.34/um. Similarly,
the degree and radian constants offer a convenient way to convert from degrees to radiansand vice-versa. To convert 10 degrees to radians, type 10*degree; to convert 1.23 radians todegrees, type 1.23*radian. Using these constants will also shorten the parsing time of a given
expression.
No other constants or variables should be defined for use in arithmetic expressions. Any suchattempts will result in an “unknown parameter” error message.
After successful parsing of an arithmetic expression, the expression is added to the list of the
combo-box, so it can be retrieved and reactivated later on. Once the Mask_Editor is closed,
however, the expression-list will be discarded. The expression list may be stored to disk andreloaded later in subsequent runs with the Save expressions and Load expressions buttons.
The following examples demonstrate the use of the Fill function of the Mask_Editor forseveral cases of general interest. To fill the matrix with a number or a range of numbers,
simply type the number (or one of the aforementioned predefined variables) in theexpression-box, then click one of the Fill buttons, as shown in the pictures below. (The popup menu entry Fill! may be used instead of the buttons.)

DiffractGUI User Guide

114

DiffractGUI User Guide115

In the above examples the entire matrix was filled in every case, but it is also easy to generate
simple shapes using the comparison operators (>, <, =). The following examples should help
explain the method. Note that in these examples the regions outside the shapes are filled with0’s. Similar methods may be used to clip portions of already-filled matrices.

DiffractGUI User Guide

116

Another common situation arises when some region of an already-filled matrix (or the matrix
in its entirety) needs to be modified. This could be done with the predefined variable V andthe function cond. Suppose the matrix is initially filled with PHI (see the above examples)
and the user wants to modify a circular region of radius 0.5mm around the center, leaving therest of the matrix unchanged. The following examples illustrate how to achieve this goal. In
the example on the left-hand side below, the value 55 is added to the central region, while on
the right-hand side the central region is filled with the value 90. In both cases, the matrix
outside the central circle remains unchanged.

In the next example, we demonstrate the creation of a phase-mask based on Zernike
polynomials (3, 1) and (4, 0). The matrix is first filled with the (3, 1) polynomial, as shown in
the picture on the left, then the (4, 0) polynomial is added to create the desired mask. HereC31 = 0.567, φ31 = 15°, and C40 = 0.234; the mask is confined to a circular region of radius
R = 1.

DiffractGUI User Guide

117

Starting with the above amplitude, let us fill now an exemplary phase mask. Suppose wewant to have a phase of 15° placed inside the regions with the lowest amplitude (that is thedark-blue region of the SlicedAmplitude in the following picture) and 77° outside.

First, we notice that the sliced amplitude value inside the respective region is –0.405398, thenwe click on the Phase button, to display the phase matrix on the screen. The phase matrix
may contain arbitrary values at this point, but it can be filled as shown below:

DiffractGUI User Guide

118

Now we place a phase of 25° in the green area of the sliced amplitude, but leave the phasevalues outside that region unchanged. Notice that the sliced amplitude value inside thespecified area is 0.0942283.

It is important to notice that we did not use the comparison operator (=) because the value
0.0946575 is rounded. The real value may range between 0.09422825 and 0.09422835, but
we use the coarser limits 0.0942282 and 0.0942285 for simplicity. Similarly, the phase matrix
can be filled for all other amplitude regions. Finally, we may set the phase outside the radius
R = 1 to 0, leaving it unchanged for R < 1.

DiffractGUI User Guide

119Before storing the mask to disk with a click on the Save Mask button, we must copy thesliced amplitude to the amplitude matrix (click on Fill Amplitude):

Alternatively, we could copy (with the same method) the phase matrix into the sliced phasematrix, then click on the Save Sliced Mask Button.

15.1 Importing distributions in WYKO file formats (*.asc, *.sdf)
To import such foreign files, click on the Load Beam button of the MaskEditor. The
following File-Open dialog box will appear:

DiffractGUI User Guide

120

Within this dialog box, select the desired file type (*.sdf in the above example), select thedesired filename from the list, then press Enter to close the box. In the case of *.asc and *.sdf
files, the MaskEditor loads data from the imported file into the internal phase matrix,(amplitude values will be set to unity), making both phase and amplitude matrices available
for subsequent manipulation by available MaskEditor features (Fill-function, slicing, etc.). If
the selected file is a DIFFRACT distribution file, *.dst, then both amplitude and phaseprofiles will be extracted from the file. In all cases, following importation, both amplitude
and phase matrices are copied into the corresponding sliced matrices.
WYKO format files are expected to contain a header, followed by a data array. The following
paragraphs describe the format expected by DiffractGUI when importing such files, giving
details about the relevant parameters.

15.2 Expected format of WYKO *.asc files
As an authentication check, DiffractGUI looks in the first line of text for the string “Wyko
ASCII”. If it is not found at the first position of the line, the file is rejected. The following
lines will be first split into tokens. A token is a character sequence bordered by spaces, e.g.
the space-character is taken as the delimiting character. If less then 3 tokens are found in aline, the line is ignored and skipped by the interpreter. All lines of the header are parsed
mainly for the occurrence of “X Size” and “Y Size” as the first tokens of the line. When thishappens, the values that follows “X Size” and “Y Size” will be read and assigned to NMAX
and NMAY, respectively. If the first token of a line is “OPD”, the end of the header isassumed, and the following NMAX lines are regarded as containing data values. Each ofthese lines is expected to contain NMAY values, separated by a TAB-character. Missing
values will be replaced by 0 and additional ones will be ignored. After importing the “OPD”
block, the interpreter stops, regardless of any additional lines or arrays of data that may bepresent in the imported file.

Expected format of WYKO *.sdf files
The sdf-files may be imported as either ASCII or binary files. DiffractGUI determines automatically the type, based on the first 4 bytes of the file under consideration. If these bytes arefound to be “aBCR” then the ASCII format is assumed, otherwise the file is considered to bein binary format.

DiffractGUI User Guide

121

Binary *.sdf files
The expected header must have the following structure:
8 characters – the first 4 characters must be “aBCR”
10 characters – ManufacID (value ignored)
12 bytes – Create Date (value ignored)
12 bytes – ModDate (value ignored)
2 bytes – NumPoints, this value will be set to NMAX
2 bytes – NumProfiles, this value will be set to NMAY
8 bytes – XScale (value ignored)
8 bytes – YScale (value ignored)
8 bytes – Zscale (value ignored)
8 bytes – Zresolution (value ignored)
1 byte – Compression (value ignored)
1 byte – DataType (value ignored)
1 byte – CheckType (value ignored)
Immediately after the header, the data is expected (one byte per data point). Hence,
DiffractGUI reads NMAX × NMAY bytes following the header. It is assumed that the first
NMAX bytes contain the first row, the next NMAX bytes the second row, and so on.

ASCII *.sdf files
These files are parsed line by line, starting with the second line. (The first line must have its
first 4 bytes set to “aBCR”, otherwise DiffractGUI assumes it to be a binary *.sdf file.)
The header is expected to be structured as follows:
aBCR????
ManufacID = characters
CreateDate = value
ModDate = value
NumPoints = value
NumProfiles = value
Xscale = value
Yscale = value
Zscale = value
Zresolution = value
Compression = value
DataType = value
CheckType = value*
During parsing, each line is split into tokens using the space-character as delimiter. If the firsttoken is “NumPoints” or “NumProfiles” then the value-token is set to NMAX or NMAY,
respectively. If the first token is an asterisk character ( * ), the end of the header is assumed,and DiffractGUI attempts to read the following NMAX × NMAY lines as data lines. Each ofthese data lines must contain a single value-token, which is read by DiffractGUI as a doubleprecision, floating-point value. (The interpreter ignores all other names used as the first token
in a header line.)

DiffractGUI User Guide122

15.3 Storing data in DIFFRACT’s distribution file format (*.dst)
This is achieved with the Save or Save Sliced Data buttons of the MaskEditor. The following
File-Save dialog box will open:

Select the desired kind of file as indicated in the above picture, type a new filename (ABCD
in the example) or select an existing file to be overwritten, then click on Save or press Enter.

15.4 User-defined apertures
As shown in the picture below, the MaskEditor allows the user to define a circular or an
elliptical aperture for each data matrix. The aperture may be used as a delimiting region for
the Fill-function or the Slice-function, or simply as a means of adjusting the matrix size (i.e.,setting NMAX, NMAY to arbitrary values).
Ry

CenterRx

DiffractGUI User Guide

123

Each aperture is defined by the three parameters Rx, Ry, and Center, which can be adjusted/
modified only with the mouse cursor. To change these parameters, position the mouse cursor
on the corresponding small rectangle (see the picture above), press and hold the left-mousebutton while moving the cursor, and release the button when finished. The popup-menu,
opened with a right-mouse-click on a plot, contains the Aperture submenu, which offers thefollowing options:
•
•
•
•
•

Elliptical – enables elliptical shape for the aperture, that is, Rx and Ry may be set
independently.
Synchronize – when this flag is set, the sliced aperture will follow automatically allchanges performed on the aperture of the non-sliced map (and vice-versa).
Hide – selecting this feature prevents the aperture circle (or ellipse) from being
displayed.
Center! – invoking this command sets the aperture center to (0, 0), the mid-point of
the map.
Values – opens the following dialog box, which allows to specify or read out theaperture parameters.

One application of the aperture is to define the area over which the Fill-function willsubsequently act. The available options are: All (aperture is ignored), Inside (only points
inside the aperture circle or ellipse are affected by the Fill function), and Outside (only points
outside the aperture are affected). The following pictures illustrate the Inside and Outside
filling modes; the map shown in the previous picture served as the initial map before fillingthe inside/outside of the selected aperture with 0 values.

The same functionality is also available for the Slice operation. Usually the apertures of thesliced and non-sliced maps are the same if the synchronize-flag is set (which is the default). If
the synchronize-flag is not set, the slicer will consider only the aperture of the non-sliced map(the map on the left-hand-side of the MaskEditor screen).
DiffractGUI User Guide

124

15.5 Phase-unwrapping to remove 2π phase discontinuities
Due to the periodicity of trigonometric functions (and the fact that light amplitude
distributions are stored as complex numbers), the phase values are typically confined tovalues between –180° and +180°. Hence, the phase maps of wavefronts having moderate orstrong aberrations contain lines of discontinuity (jumps between –180° and +180°), as shownin the following picture on the right-hand-side. These phase discontinuities may beeliminated with the popup-menu command Unwrap, as shown in the left-hand-side of thefollowing picture. (Only the Phase-map can be unwrapped; the Unwrap menu option will begrayed for amplitude maps.) The unwrap function will fail if the chosen resolution is toocoarse (e.g., small values of NMAX, NMAY), that is, if the phase oscillates too rapidly witha magnitude greater than 360°.

15.6 Resizing data arrays
Not all imported files contain a square data matrix, that is NMAX is not always equal to
NMAY. Additionally, only a small area of the imported files may be relevant for further
processing with DIFFRACT. Although DIFFRACT can deal with beam profiles having
NMAX ≠ NMAY, it may be desirable, for instance, to set both these parameters equal to a
power of 2 before saving the imported data into a DIFFRACT distribution file (*.dst) or
XOBJ file (*.dat). DiffractGUI’s MaskEditor allows reshaping the matrix size (i.e., the valuesof NMAX, NMAY) with two functions, implemented with the StripAper and AdjustPow2
buttons. (Warning: these functions act immediately upon a mouse click and cannot be
undone, so they require judicious usage.)

StripAper
All data matrices will be replaced by sub-matrices defined by the rectangular region that
confines the circular (or elliptical) aperture of the non-sliced map (i.e., the map on the lefthand side). NMAX and NMAY will be set to new values, and all data points lying outside
this rectangular region will be removed and lost forever.

DiffractGUI User Guide

125

For example, when starting with the maps shown in the above picture, the results of theStripAper command are displayed in the following picture.

AdjustPow2
This command increases the size (NMAX, NMAY) of all data matrices to the next power of
2, filling the new regions around the existing maps with 0’s. For example, the preceding
phase maps, upon invoking the AdujstPow2 command, will be transformed to the maps in
the following picture.

DiffractGUI User Guide

126

15.7 Extracting Zernike coefficients from phase distributions
Upon clicking on the Zernike command of the pop-up menu, a ‘modeless’ dialog box opens,
as shown in the picture below. This feature of DiffractGUI’s MaskEditor offers thepossibility of modifying or analyzing Phase arrays using Zernike’s circle polynomials.

The first 91 Zernike polynomials (numbered 1 through 91), defined by the following
formulas, are available:

DiffractGUI User Guide

127

m

Z = 2 ⋅ (n + 1) ⋅ R (r ) ⋅ cos(m ⋅ϑ )Z = 2 ⋅ (n + 1) ⋅ R (r ) ⋅ sin(m ⋅ϑ )Z = (n + 1) ⋅ R (r ) (m = 0)even _ jnmodd _ jn(m ≠ 0)( m ≠ 0)m

jn

The radial polynomial are defined as follows:mRn (r ) =( n−m ) / 2∑
s =0(−1) s ⋅ (n − s )!
⋅ r n−2 s! (n − m) / 2 − s ]!
s![(n + m) / 2 − s ][The index j uniquely identifies each Zernike function; each j has an associated pair of (n, m)values, which defines the corresponding radial polynomial. The dialog box displays these
indices in the right-hand column of the list box, together with the more familiar identifiers
such as Anm, Bnm. (DIFFRACT uses the more practical identifiers of Zernike polynomials,
Cnm, PHInm, instead of the Anm, Bnm coefficients. The above dialog box switches between
these two representations upon clicking the Display C, PHI button.)
The left-hand column of the dialog’s list box displays the coefficient aj associated with eachof the available 91 Zernike functions. The numerical value may be edited manually byclicking twice (not a double-click!) on the desired entry of the list box.
The Clear All button sets all aj coefficients in the list to 0.
Using the Export and Import buttons, the aj coefficients may be exported to or imported
from an external file in one of the formats described in Section 13 of this manual (Import/
Export of Zernike Coefficients).
[Note: In the Zernike dialog-box of the MaskEditor, the Z1 function (piston, a simple phaseoffset) is available, even though DIFFRACT does not use this coefficient. Since the primary
purpose of the Import/Export functions of the MaskEditor is to pass the Zernike coefficientsto DIFFRACT, the Z1 coefficient is omitted during these import/export operations. If needed,
Z1 must be written manually into the list.]
The Generate Phase Map button may be used to fill the Phase array within a predefined
aperture. For each point having polar coordinates ri and θi inside the aperture, the phase value
Φi (in degrees) will be computed as follows:91Φ i = ∑ a j ⋅ Z j (r i ,ϑ i ) ⋅ 360
j =1

with the aj coefficients taken from the dialog list box. Outside the aperture the phase will be
set to 0°. The aperture does not have to be centered in the middle of the mesh, nor does it
have to be circular. The ri values for each pixel will be normalized by the radius of theaperture, which, for an elliptical aperture, is the largest of the two radii Rx and Ry. As an
example consider the picture on the previous page, which shows the phase profile producedwith the Generate Phase Map button when the coefficient a8 is set to 1.0 (A31 = 1.0), while
all other coefficients are set to 0.

DiffractGUI User Guide

128

For an arbitrary Phase map, the Compute Coefficients button extracts the aj coefficients that
describe the closest surface to the existing Phase map inside the defined aperture. The
algorithm is based on a least-squares fit over the aperture (data points outside the aperture are
ignored). All Zernike coefficients ranging in index from 1 to that specified in the up to edit
box will be computed. (Note: The algorithm needs, for each extracted coefficient, atemporary data array containing all the points inside the aperture. Due to this memory
consumption, it is recommended to limit the highest coefficient’s index with the up to entry.)
As an example, the results of coefficient extraction applied to the Phase map generated in theprevious example are shown in the following picture.
In the dark-gray rectangle located above the Zernike list the absolute values of all Zernike
coefficients are displayed graphically, as a spectrum of vertical black lines. This fulfills twotasks: first, it makes it easier to evaluate the contribution of each coefficient with respect tothe others; second, it allows to specify a threshold value (the red dotted line) for clamping all
coefficients below the threshold to zero. Its usage will be described in the next example.

To illustrate one application of the spectrum control, let’s start with a more complex phase
distribution, as shown in the following picture.

DiffractGUI User Guide129

In this situation, start by setting all coefficients to zero with the Clear All button. Since the
distribution needs to be unwrapped before computation, select the Unwrap phase before
computation button, then initiate the computation with the Compute coefficients button.
The result is displayed in the following picture. Most of the coefficients in this example havefairly small values, but three of them clearly stand out.

To keep only these coefficients and set the rest to zero, place the red threshold line properly
using the mouse cursor. (Press the left-mouse-button, then move the mouse cursor. The
threshold line will follow the cursor until the button is released.) All coefficients with anabsolute value below this threshold will be displayed in red, which makes them readily
recognizable. With the threshold placed at the desired level, perform a double-click on theleft-mouse-button over the spectrum in order to clear all coefficients below the threshold. The
result is displayed in the next picture.

DiffractGUI User Guide130

It should be noted that the accuracy of the extraction algorithm is strongly related to theradius of aperture and to the number of sample points inside the computational region. For
best results, the aperture must be circular and have exactly the same radius as the distribution.
Furthermore, since a least-squares method is used to extract the Zernike coefficients, theextracted coefficients will not describe exactly the distribution under consideration, but rather
the best possible fit to it. This is separate from any numerical round-off errors, which, ofcourse, contribute additionally to any inaccuracy in the estimated values.
Inside the MaskEditor, as in the BitmapView, the Length_Units and the Iso-XY option can bechosen for each plot individually, as depicted below.

Also, Tracker-Rectangles may be used to move around parts of the mask or to copy and paste
data to or from the clipboard. The next picture shows the ability to modify the color legend

DiffractGUI User Guide

131

and to create rectangular apertures. Please refer to the BitmapView section for more details
about the usage of the Tracker-rectangle and the Iso-XY option.

If the Rectangular option is checked and Elliptical option unchecked, the aperture shape will
always be forced to be quadratic. To rotate the aperture, type in the tilt angle in the Aperture
dialog box (see the previous picture) and press Enter. Alternatively, you may position themouse cursor over the dot in the center of the aperture and rotate the mouse-wheel.
The color legend dialog box and the Tracker-Rectangles work similarly to those described in
the BitmapView; for more details consult the corresponding chapter. The various maps of the
MaskEditor can be zoomed and panned in the same way as those in BitmapView, which may
be particularly useful when one needs to manipulate small details.

15.8 Arithmetic Parser Inside the MaskEditor
In addition to the general-purpose functions listed above, inside the MaskEditor scripts or
expression parsing, the arithmetic parser offers the following pre-defined additional variables
and functions: NMAX – NMAY – LMAX – LMAY – WAVELENGTH
Note that WAVELENGTH always returns the wavelength expressed in millimeters (mm).
Similarly, LMAX and LMAY are returned in mm. You may convert them easily to otherunits by dividing with the predefined constants um, nm and cm.
The functions A(n,m), P(n,m), SA(n,m), SP(n,m), T1(n,m), T2(n,m) return the value in row
n, column m of the respective plot (Amplitude, Phase, SlicedAmplitude, SlicedPhase, Temp1
and Temp2). Conversely, A(n,m,x), P(n,m,x), SA(n,m,x), SP(n,m,x), T1(n,m,x), T2(n,m,x)
place the value x in row n, column m of the respective plot.

DiffractGUI User Guide132

15.9 Scripts in the Mask-Editor
For a moderate ability to manipulate the data, a simple script language has been implemented
in the MaskEditor. In conjunction with the functions of the arithmetic parser, this featureallows direct access to each individual value of the plot maps. The ability to create simple
loops, conditional structures, and variables provides a convenient means of performing tasks
that would otherwise be difficult if not impossible. The direct way to use Scripts is to open
the MASK_Script dialog box with a click on the Script… button of the MaskEditor. Scripts
may also be used during the import of external files.

As can be seen in the above picture, the MASK_Script dialog box contains a main text input
window, where the script may be typed in (or loaded from a file), a small output window, anda combo box containing the most recent used files (MRU). The Load and Save As… buttons
prompt for a filename before loading or saving scripts, while the Save! button overwrites(without prompting) the file displayed in the MRU box. This is useful during development,but otherwise should be used with caution.
The Execute button starts the execution of the script by passing it to an internal interpreter.
The basic syntax rules are simple: each line must begin with one of the command-keywords(described below) followed by one or more required parameters. The ‘;’ character isinterpreted as an end of line, hence multiple commands can be placed in one line byseparating them with ‘;’. The keywords and the parameters must be separated by one or more
blanks (empty spaces). Empty lines or lines that begin with ‘// ’ are ignored; therefore, the ‘//’pair may be used to insert comment lines. Generally, the interpreter is case-sensitive.
The following keywords may appear at the beginning of each line (sequences embraced by
opening and closing brackets, [ and ], are optional):var

name1 [, name2, name3, ...]

DiffractGUI User Guide

133

Defines and initializes with 0 one or more variables. All variables that are to be used later inany regular arithmetic expression inside the Script must be declared first with this command.
The names of the variables must begin with a letter and should contain only alphanumericcharacters (e.g. a-z, A-Z, and 0-9).
To assign a value to a variable use the form variablename(value). For example, var myvar,
hisvar define two variables called myvar and hisvar. To set myvar to a value of, say 1.23,
type myvar(1.23). To increase the value of myvar by, say 1.5, type myvar(myvar+1.5).
Another important property of this construct is that it returns the actual value of the variable(like an ordinary function), which makes it easy to program loops, as it will be shown below.
Generally, all variables contain double-precision, floating point numbers. Use the ceil( ) or
floor( ) functions to convert them to integer values.
kill name1 [, name2, name3, …]This command will remove the variables name1, name2, name3… from the Script.
stopThis command stops the interpreter, and Script execution terminates immediately.
print token token …

This command prints (in the output window) the specified tokens. A token may be anarithmetic expression, in which case the expression is evaluated and the result printed out, ora simple text delimited by “ and ”, in which case the text is printed out without modification.
The tokens MUST be separated from each other by blanks. For this reason, tokens that arearithmetic expressions cannot contain blanks.
Examples:print “Hello World” will print out Hello World
print “PI = ” PI will print out PI = 3.14159265359
print A(3,8) will print out the value of the Amplitude map in row 3 and column 8
if expression…other command lines …
else…other command lines…
endif

or

if expression…other command lines …
endif

The arithmetic expression is evaluated and the if-branch traversed if the result is non-zero. If
the result is zero, the else-branch, if present, will be executed.
Example:var jj; jj(3); if jj=3; print “jj is three!”;DiffractGUI User Guideelse; print “jj is not three.”; endif;

134

Note the mandatory ‘;’ as separator between the commands. The same code can be written
without ‘;’ as follows:
var jjjj(3)if jj=3
print “jj is three!”else
print “jj is not three.”
endif
begin
…other command lines …
until expression

while expression…other command lines …
endwhile

The begin-until construct will repeat the command sequence between begin and until aslong as the evaluation of expression returns zero. The while-endwhile construct will repeat
the command sequence between while and endwhile as long as the evaluation of expression
returns non-zero values. Loops may be nested in unlimited levels, but they shall not beinterspersed.
For_loops have not been implemented directly, but they may be constructed with one of theabove begin-until or while-endwhile constructs.

Examples of a loop starting at 5 and terminating at 10:
var loopvar; loopvar(4);while loopvar(loopvar+1)<11
print “loopvar is “ loopvar
endwhile

var loopvar; loopvar(5);begin
print “loopvar is “ loopvar
until loopvar(loopvar+1)>10

A special command is the plot-map assignment. Its general format is
plotmap_identifier = expression

As plotmap_identifier one of the mnemonics A, P, SA, SP, T1, T2 (standing for Amplitude,
Phase, SlicedAmplitude, SlicedPhase, Temp1, Temp2) may be used. When this command isencountered, the expression is evaluated for each of the destination plot-map’s values, similar
to the formula-parser. Hence, all special variables described there (like I, J, R, X, Y, etc.) may
be used inside the expression. This makes the plot-map command more versatile compared toother commands where these variables are not available.
As an ultimate emergency break, the Escape key on the keyboard may be used to stop the
Script immediately.

15.10 Exporting Single Mask-Plots as Bitmaps
As indicated in the following picture, exporting Mask_Plots as bitmaps can be achieved bydisplaying the plot intended for exportation, opening the popup menu with the right mouse
cursor, then choosing the Save as BMP… command.

DiffractGUI User Guide135

In this example the SlicedPhase plot is saved as a bitmap-file. Bitmaps created in this way
may be imported back with the bitmap importing facility described later in this section.

15.11 Exporting Single Mask-Plots as ASCII data-matrices
As the following picture demonstrates, exporting as an ASCII data-matrix may be achieved
by first displaying the plot intended to export, then opening the popup menu with the rightmouse cursor, and finally choosing the Save data… command from the menu.

The values of the plot will be stored as a data-matrix, similar to the files generated by the
PLOT command of DIFFRACT. Among other possibilities, the files thus exported from the
MaskEditor may be loaded and displayed later in the BitmapView or in the ReliefView.

DiffractGUI User Guide

136

15.12 Importing Data from Bitmaps
To load data from a bitmap file, click the Load… button of the MaskEditor, then select fromthe File-Open dialog box that pops up the file type “Bitmaps *.bmp”, as illustrated below.

Select the desired filename and click the Open button. Upon this, the Bmp_Import dialog
box will open, as shown in the following picture.

At this point, the bitmap file is loaded (and displayed) only in the dialog box window; all theplot-maps of the MaskEditor remain unchanged. It is also important to note that only bitmaps
with up to 256 colors (or grey-levels) can be imported; true-color bitmaps are automaticallyconverted to 256-color bitmaps, which changes the colors slightly, thus altering the actual
content of the bitmap file.
The framework associates a numerical value to each color in the color-palette of the bitmap,
and transfers that value to the destination map (for each bitmap-pixel of the associated color),
when the Fill Map! button is clicked. These color-value pairs are stored in the Color Map;
the numerical values can be modified individually for each color present in the bitmappalette, but the colors cannot be changed.

DiffractGUI User Guide

137

The bitmap can be translated on the screen by dragging with the left-mouse button, and thedisplayed area can be zoomed in or out by rotating the mouse-wheel.
The Bmp_Import dialog box offers the following command buttons:
Destination: Choose from this combo box the specific plot which should be filled with thebitmap data (only one plot may be chosen at any given time).
File… : Use this button to replace the currently loaded bitmap with another bitmap from anexternal file.
Fill Map! : A click on this button fills the selected destination plot, overwriting any data thatmight exist in the destination plot. This operation cannot be undone.

The RED, GREEN, and BLUE check-buttons of the Init map values group determine how
the numerical value attached to each color is computed. Considering that any color iscomposed of red, green, and blue values (each ranging from 0 to 255), the following formula
has been used:value=

3⋅ rflag⋅ red + 2 ⋅ gflag⋅ green+ bflag⋅ blue3⋅ rflag⋅ 255+ 2 ⋅ gflag⋅ 255+ bflag⋅ 255

where rflag, gflag and bflag are 0 or 1, depending on which one of the RED, GREEN, BLUEbuttons is checked (flag = 0) or unchecked (flag = 1). The resulting value thus ranges
between 0 and 1.
If none of the RED, GREEN, or BLUE buttons is checked, DiffractGUI determines the value
based on the rainbow-color series, as it is used in all bitmaps exported from DiffractGUI. Not
all colors that can be represented by the R, G, B values are part of the rainbow-spectrum; themapping routine thus tries to find a closest-match for those colors, but this may result in
multiple colors associated with the same value. For best results, use this option only forimporting bitmaps that where exported from the BitmapView of DiffractGUI.
Transparency: When this check-button is enabled, all colors marked as transparent (seebelow for details) will be prevented from drawing, and any subsequent Fill Map! command
will leave the destination plot unchanged in places that correspond to a transparent color. If
disabled, the transparent property of each color is not considered and the bitmap is fully
displayed.
Clear transparent map: Removes the transparent property from all colors. Note that theresulting visual effect is the same as that obtained with the Transparency check-button,
namely making the bitmap to be displayed opaque, but the important difference is that here
the transparent flags are permanently removed; the transparency must be specified explicitly
for each color in this case.
Color Map … : Opens a small dialog box containing the associated value-color pairs. Within
this box the map values may be modified and colors may be specified as transparent or not.

The following picture shows the result of the Fill Map! action when Temp1 is chosen as
destination.

DiffractGUI User Guide

138

The destination plot is sketched in the display area of the Bmp_Import dialog box as arectangle. Its center is marked with a cross, which cannot be moved but always appears at thecenter of the display area. In contrast, the imported bitmap can be translated around thescreen by dragging with the left-mouse button.
Initially, the center of the destination plot and the center of the bitmap coincide. (A doubleclick on the left-mouse button restores this alignment after any arbitrary translations of thebitmap.) Only a one-to-one pixel-to-cell transfer (from bitmap to destination plot) is possible.
In other words, a plot having NMAX columns and NMAY rows can be filled only by abitmap having at least NMAY × NMAX pixels. Each pixel is transferred to exactly one cellof the plot, and no stretching is allowed. Those plot cells that are not covered by the bitmap(or are covered by transparent colors) will be left unchanged.
The following two pictures demonstrate the effect of making a color transparent; in thisexample, it is the black background color of the loaded bitmap that is made transparent.

Holding down the Ctrl key and clicking the left-mouse button on the bitmap, toggles thetransparency of the color under the mouse cursor. This is a quick way to specify thetransparency for each of the visible colors. If the Transparency option is enabled, this will
be reflected immediately on the screen. The next two pictures illustrate the effect.

DiffractGUI User Guide139

By opening the “Palette colors” dialog box with the Color Map … button, it is possible tomodify (manually) the values attached to the colors. The value-color pairs may be stored in
an external text-file and reloaded later with the Save and Load buttons. However, a stored
value-color map would be useful only for bitmaps with exactly the same color palette. Hence,
when numerical values are needed that deviate from the default values (generated
automatically by the framework) it is necessary to store for each used bitmap thecorresponding value-color pairs that match the color-palette of the bitmap.
A left-mouse click on the numerical value in the list (displayed with gray background) will
open an edit box where the value can be modified. A click on one of the colored rectangles
inside the list will toggle the transparency flag. Entries of transparent colors have an
overstrike to indicate that they are not visible in the bitmap. Entries can be displayed in an
undefined order or sorted by various parameters. Note that the displaying order by no meansaffects the appearance of the bitmap or the import itself.
Finally, it should be remarked that not all colors that are present in the palette also exist in thebitmap, but every color used in the bitmap will be present in the color palette. In any case,DiffractGUI will assign for each color found a numerical value.

DiffractGUI User Guide14015.13 Importing Data from Custom ASCII Files
This feature enables the user to import data from ASCII files created by other programs,
which do not match DIFFRACT’s specifications for external mask or distribution files. The
main requirement is that the (mandatory) data and the (optional) header must comprisedistinct blocks within the data-file (this is usually the case). The data is expected to begrouped in cells, each cell containing either a simple value or a complex structure such as the(real-value, imaginary-value) pair. Since in practice widely different formats exist, some“training” might be necessary before DiffractGUI can import the data from a specific filetype. This will be clarified by the following examples.
To start, click the Open… button of the MaskEditor and select from the File-Open dialog
box, one of the three “Custom files” options that appear, as indicated below.

The three “Custom files” entries have the same functionality; later, each may be programmed
to read different preferred file types, hence it is convenient to have multiple entries: it spares
the need to re-program the import-filter each time that one changes the file type.
At this stage it is not important which file is selected. To continue, select any file or type any
characters in the edit-box and click Open. The new dialog box, Custom_file_specifications,will open, as illustrated below.
Generally, the import process is done in the following order:
1.
2.
3.
4.
5.

Run the Init-script
Parse the file header (optional)
Run the Post-Header script
Parse the data values
Run the Final-script

The Custom_file_specifications dialog allows the user to modify each of these steps
individually. The picture below shows this as an example.

DiffractGUI User Guide

141

The “Type” and “Filter” labels may be changed arbitrarily and they will appear in the initialFile-Open dialog box in subsequent invocations. Additionally, the “filter” will determine todisplay only the specific files with the indicated extension, as it is common usage underWindows. There is nothing else special to them.
The File… button allows to select another file from which data shall be imported, without
returning to the MaskEditor. The filename may be changed also directly in the edit box. The
Preview button opens a small text-viewer and displays the content of the selected file, whichis convenient during preparation for import (or, in case of trouble, for debugging, to see if theimport specifications match).
There are three scripts that may be used during import. Since there is only one edit box
foreseen for all three, the Init, Post-Header and Final check-buttons allow to choose one ofthem for visualization and editing. Execute_script will perform the selected script
immediately, without launching the whole import process. With some limitations, as with thePreview option, this is useful during preparations or debugging.
Usually, programming of the import facility occurs in the following order. First the header
and data formats are specified. This is followed by the writing of the scripts, if desired.

Example 1
In this example, we program the import process to read wave-front map files as generated by
the Zemax™ program.
First, click on Preview and select the complete header area. Click the right mouse button andselect Copy, to place it on the clipboard, as indicated below.

DiffractGUI User Guide

142

Now, click on the (empty) “Header” edit box, and paste the previously stored header from the
clipboard, as illustrated on the next picture. This header will serve as a template to extract
specific numerical values, such as NMAX or NMAY, from the file. Each of these values may
be stored in a variable that can be used in one of the scripts run during import. The
framework offers the following variables: NMAX, NMAY, LMAX, LMAY,WAVELENGTH, HVAR1, HVAR2, HVAR3, HVAR4 and HVAR5. The variables HVAR1
to HVAR5 are general-purpose and may be used to store other specific values.

In the next step, each numerical value to be scanned from the header must be replaced by oneof the aforementioned variable names, embraced by < and >, as shown in the next picture
where the locations of NMAX, NMAY and WAVELENGTH are marked by replacing thevalues by <NMAX>, <NMAY> and <WAVELENGTH>, respectively.

DiffractGUI User Guide

143

Additionally, the “Peak to valley” value is read into <HVAR5>, just for demonstration. The
Skip header check-button may be used to specify whether or not a header is present in thedata file. Since in the present example a header is present, this button must remain
unchecked. (If the Skip header button is checked, the effect would be the same as if the
Header template box is left empty.)
It is important to leave leading and trailing spaces before and after each <variable> entry.
These blanks instruct DiffractGUI to accept any arbitrary number of blanks between theitems in the imported file, thus increasing the flexibility of the format.
At this point the header preparations are finished and the data format should be specified.
First, we must specify at what position inside the file the data area begins. The following
options are available:-

Data starts in a specific line
Data starts in the first line that has more then a specified number of cells
Data follows the header immediately

Line numbering starts at zero. When counting the lines, one must remember that empty lines(or lines containing blanks only) are skipped automatically and, therefore, are not counted by
the import routine. From the Preview we see that the data-block begins immediately after theheader, hence the corresponding button should be checked, as in the following picture.
Once the start of the data block has been specified, the data layout must be chosen. Fourlayouts are available:
•
•
•
•

table
resizing tablethread (row-wise)
thread (column-wise)

The table and resizing table are basically the same. The only difference is that the resizing
table will automatically resize all mask plots to match exactly the number of rows andDiffractGUI User Guide

144

columns found in the file, while the table layout will fill them starting always at (row = 0,column = 0) without resizing. If the destination plots have more columns or rows than foundin the data-block, they will be filled only partially. Conversely, any extra rows and/orcolumns found in the data-block will be ignored.

Both, table and resizing table layouts expect the data to be arranged as
Cell 0,0
Cell 1,0
Cell 2,0………

Cell 0,1 Cell 0,2 …
Cell 1,1 Cell 1,2 …
Cell 2,1 Cell 2,2 …
………
………

Each line must contain exactly one row. In contrast, the thread (row-wise) layout expects thedata also to be ordered by rows, but every line of the file may not necessarily contain allcolumns of the matrix. In the extreme case, there might be only one value per line, like
Cell 0,0
Cell 0,1
Cell 0,2…..
Cell 0, NMAX-1
Cell 1,0
Cell 1,1….
….
Cell NMAY-1, NMAX-1

As the name indicates, the thread (column-wise) layout is similar to the thread (row-wise),but it expects the data to be arranged by columns:
Cell 0,0
Cell 1,0
Cell 2,0

DiffractGUI User Guide

145

….
Cell NMAY-1, 0
Cell 0,1
Cell 1,1….
Cell NMAY-1, NMAX-1

In the chosen example, as seen in Preview, the table or resizing table layouts would match.
Finally, for data specification, cell layout must be declared. In this example, each cell consistsof a single data value. The Cell formatting edit box may be used to specify the cell layout
and, importantly, which one of the six available plots of the MaskEditor are to be filled withdata. For single cells separated by blanks (as is the case in the present example), simply type
< A >, < P >, < SA >, < SP >, < T1 > or < T2 > to indicate that during import the data should
be sent to Amplitude, Phase, SlicedAmplitude, SlicedPhase, Temp1, or Temp2 frames,
respectively. In the following picture, the Phase plot is chosen to be filled with data.

It is important to place blanks (empty spaces) in front and at the end of the cell format text,(not visible in the example pictures). The separator characters may also be specified in thisbox. For example, if the data values are separated by ‘,’ (comma) and not blanks (as in thepresent example), then specify<P>,

instead of < P >. Notice the blank between the ‘>’ and ‘,’. The next example illustrates thecell-formatting for more complex cells.
The last preparation step before importing the file will be the writing of the three scripts.
Note that it is not mandatory to use them; if no scripting is desired the script-text should beleft empty, or use “stop” as the first script command.
The Init-script is the best place to initialize the plots. In this example it is set to

DiffractGUI User Guide146

A = 1;
P = 0;

which means the Amplitude plot_map is filled with 1 and the Phase plot_map is filled with 0.

The Post-Header script is best used to verify the data imported from the header. In our
example, we verify if NMAX and NMAY are less then 64.
if (NMAX<64)
abort
endif
if (NMAY<64)
abort
endif

If an error occurs during the run of a Script, the import process stops. Hence, if you would
like to stop the import process deliberately, write some meaningless Script (such as theunknown command “abort” in the above example). The generated syntax-error automaticallystops the process.
It is important to note that all the variables declared newly (with the “var” command) in a
Script will be passed to the Scripts that follow. For example, all the variables declared in the
Init-Script will be available in the Post-Header and Final-Script too, but the variables
declared in the Final-Script will not be available in the Init or Post-Header Scripts.

DiffractGUI User Guide

147

The Final script might be used for any closing activities. For example
SP = P;
SA = A;WAVELENGTH(WAVELENGTH*um);
print “
NMAX=” NMAX
print “NMAY=” NMAY
print “ WAVELENGTH=” WAVELENGTH
print “ Peak to valley=” HVAR5 “ waves”

will copy the Phase map into to SlicedPhase map, the Amplitude map into the
SlicedAmplitude map and will printout the values of some of the variables.
Having completed the preparations, click the Load file button to start the import process. The
framework will keep you informed about the import-status in the (grayed) edit box on thelower right-hand side of the dialog box, as can be seen in the above picture. The complete
output is listed below.
For convenience, each variable encountered during the scanning of the file-header is printed
out together with the value found in the header at that place.

DiffractGUI User Guide

148

Start loading
C:\DiffractRoot\Diffract83\BOWTIE\ZemaxWellenfront.TXT
Performing initial script ...
Scanning header ...
WAVELENGTH(0.405);
HVAR5(0.0101);
NMAY(64);NMAX(64);
Scanning for first data line ...
Performing post-header script ...
Scanning data values (layout=0) ...
Performing final script ...
NMAX=
64
NMAY=
64
Wavelength= 0.000405
Peak to valley=
0.0101 waves
Import succeeded.
File closed.
The Custom_file_specifications dialog box is modeless and resizable, meaning that, after
import, the dialog box does not have to be closed in order to return to the MaskEditor. It will
be automatically closed, however, when the MaskEditor is closed. Upon closing the
MaskEditor, all the settings will be stored in the registry and preserved for future sessions.

Example 2This second example illustrates the import of ASCII mask files, as used by DIFFRACT™ in
the XOBJ command. As a main difference with the previous example, note that the data cells
consist of complex numbers written as (real, imaginary) pairs, as shown below in the File
Preview window.

The header is fairly simple, since it contains no other alphanumeric characters, except thevalues of NMAX, NMAY, LMAX and LMAY. Notice the blanks between the variables.
Since one cell consist now of two values, the data format must be specified withDiffractGUI User Guide

149

( <T1> , <T2> )which tells DiffractGUI to store the first value of each cell into the Temp1 map and thesecond into Temp2 map. Furthermore, DiffractGUI expects now the cells to be embraced by‘(’ and ‘)’, having the two values separated by a comma ‘,’.
To illustrate this point again, if, for example, the data format of the external file happens to be{value; value} {value; value} …. then the cell format must be specified as{ <T1> ; <T2> }Note the blanks inserted between the tokens; they instruct DiffractGUI to ignore any numberof blanks between the tokens too. Generally, a cell may contain more then two values, whichmust be then specified in the cell format. However, all cells of the data block must have thesame pattern, otherwise the scan will fail. It is also recommended to fill each value of a cell
into a different plot-map, otherwise (some of the data) may be lost.
The Init and Post-Header scripts in the present example are identical to those of the firstexample, but the Final script has been changed to compute the amplitude and phase from thereal and imaginary parts of the complex values, stored in Temp1 and Temp2. The resulting
values are stored in the Amplitude map and Phase map.
A = sqrt(T1*T1+T2*T2);
P = atan180(T2,T1);

DiffractGUI User Guide150

16 Coordinate Analyzer
The CoordinateAnalyzer is a graphic window that helps visualize the spatial orientation ofvarious objects described in terms of the Euler angles. (See DIFFRACT’s manual for a
detailed description of the Euler angles.) Certain DIFFRACT commands (such as MIRR and
MLYR) require a (θ, φ) or (θ, φ, ψ) set of angles to specify the orientation of the incident
beam, the emergent beam, and the object itself. The CoordinateAnalyzer, which may be
invoked in conjunction with commands such as MIRR and MLYR, helps the user to verify
that the specified Euler angles match their intended usage.

The above picture illustrates how the CoordinateAnalyzer may be invoked from the Edit_
DIFFRACT_parameters dialog box. Click on the Angles button to open the Coordinate
Analyzer window. The relevant angles will be passed on to the Coordinate Analyzer, where
they can be modified in various ways (from the keyboard or with the mouse wheel). These
modified angles may then be incorporated into the command block or discarded, depending
on how the Coordinate Analyzer is closed. The CoordinateAnalyzer may thus be used tofamiliarize the user with the Euler angles of DIFFRACT, ensuring that the selected angles areappropriate for the intended application. Various features of the CoordinateAnalyzer aredescribed in the following sections.

16.1 Mirror
The following picture shows the appearance of the CoordinateAnalyzer invoked for a
Mirror (MIRR) object. Before starting a detailed description of each control that appears in
the window, we mention that these controls may be grouped logically in two categories:•

Controls that modify the display only; most of these are placed in the horizontal bar at
the top of the window.

•

Controls that modify the parameters of the DIFFRACT command; these are aligned
vertically on the left-hand border of the window.

DiffractGUI User Guide

151

The CoordinateAnalyzer displays three tripods of Cartesian coordinates labeled
INCIDENT, MIRROR, and EMERGENT. The x-axis is displayed in red, the y-axis in green,
and the z-axis in blue. The three tripods are displayed with different line styles and withdifferent lengths, so they can be discerned even when they overlap. The Incident Beam isrepresented by a yellow arrow, and the (computed) Emergent Beam by a brown arrow. The
Mirror Object itself is the gray rectangular frame attached to the MIRROR tripod.
For better visualization, the incident beam (i.e., the yellow ray), the MIRROR-tripod, and the
EMERGENT-tripod may be removed from the display individually by checking/unchecking
the Incident Beam, Emergent, and Mirror buttons. The INCIDENT tripod is always
displayed and cannot be removed from the screen, since it is the reference system for all otherdisplayed components. The orientation of the scene can be changed by changing the X-angle
and Y-angle values (then pressing Enter) or, more practically, with the aid of the mouse:
position the mouse cursor somewhere on the black background, hold down the left-mousebutton and keep it down while moving the mouse.
The origin of the INCIDENCE tripod is usually at the center of the window, but it can betranslated with the mouse (hold down the CTRL key, then perform the dragging operation
described above). In any event, since the scene is always rotated around the mid-point of theCoordinateAnalyzer window, the INCIDENT tripod or the entire scene may happen todisappear from the screen. Double-clicking on the left-mouse-button removes any translationfrom the INCIDENT tripod and returns its origin to the mid-point of the window.
The global dimensions of the scene can be specified by changing the scale value and pressing
the Enter key, or by using the mouse wheel.

Using the mouse wheel
Within the CoordinateAnalyzer, various orientation angles can be changed with the mousewheel. Since the mouse has one wheel only, a selection mechanism is implemented with the
Theta, Phi, Psi buttons located in the edit controls of the window. To change a specificDiffractGUI User Guide

152

value, check the associated Theta, Phi, or Psi button, then turn the mouse wheel. Only one
value can be changed at a time; therefore, when a button is checked, all other relevant buttons
will be automatically unchecked.
As an alternative method, the desired angle can be selected for modification by a left-mouseclick on a tripod-axis. Depending on the axis hit, the following values may be selected:
MIRROR z-axis: Mirror Theta
MIRROR x-axis: Mirror Phi
MIRROR y-axis: Mirror Psi
EMERGENT z-axis: Emergent Theta
EMERGENT x-axis: Emergent Phi
EMERGENT y-axis: Emergent Psi
Yellow incident beam: Incident Beam’s Theta
Brown emergent beam: Incident Beam’s Phi
If no angle value is attached to the mouse wheel (that is, all selection buttons are unchecked)
then the scale value will be changed upon a wheel rotation. Of course, if the mouse does nothave a wheel, the above features cannot be used and all parameters have to be modified bytyping in the desired value followed by Enter. The step size for each wheel impulse received
from the mouse can be adjusted with the Wheel Sensitivity slider, located on the top-leftcorner of the window. The button Clear All will set all angles to 0.

Display Options
The scene can be modified by the following options, each of which may be selectedindependently of all the others:•

Ortho determines the scene to be drawn in orthographic projection. If disabled, themore realistic perspective projection is used. The only difference between the two
projection modes is that in orthographic projection the depth information is notconsidered. In other words, in orthographic projection an object’s size does notdepend on how far or how near the camera it is located; it always has the same size.

•

Labels can be used to hide or display the INCIDENT, MIRROR, and EMERGENT
labels attached to the axis-tripods.

•

Explode may be used to disperse the positions of the origins of MIRROR and
EMERGENT tripods for a better view. If this option is not checked, all tripods will bedrawn with a common origin (usually in the middle of the screen).

•

Rigid. When this option is selected, the EMERGENT tripod will be fixed to the(computed) emergent beam and its orientation can no longer be changed manually.
However, if the direction of the incident beam is changed, the emergent (reflected)
beam will change accordingly, at which point the emergent tripod will automaticallyfollow the emergent beam.

DiffractGUI User Guide

153

Closing the CoordinateAnalyzer
There are two ways to close the CoordinateAnalyzer window:•

Using the ×-button in the upper right corner of the window (like closing any otherwindow). Any changes made during the session will then be discarded, and control
returns to the (unchanged) Edit DIFFRACT parameters dialog box.

•

Using the Apply and Close button. In this case the selected values of (Theta, Phi, Psi)
will be passed to the Edit DIFFRACT parameters dialog box before the Coordinate
Analyzer is closed. The selected values will be incorporated into the command blockcurrently under consideration.

16.2 Multilayer
The following picture shows the appearance of the CoordinateAnalyzer when it is invoked
for a Multilayer (MLYR) object.

DiffractGUI User Guide

154

The basic functionality remains the same as described earlier in conjunction with the Mirror(except the Mirror label has been replaced with Multilayer), but new controls specific to the
MLYR command of DIFFRACT appear on the screen.
As in the case of the Mirror object, the Multilayer is displayed as a gray frame. When thecompression/decompression options happens to be spectrum, as in the above example, twosmaller rectangular frames will be used to represent the (planar) entrance and emergent
surfaces. (Refer to the DIFFRACT manual for more information about these options.)
The incident beam, represented by a yellow arrow, is split into a reflected ray (brown) and atransmitted ray (yellow), regardless of the selected Mode (i.e., Reflect or Transmit). All rays
are bent according to Snell’s law as they traverse a surface.
When the Rigid option is checked, the EMERGENT tripod will be attached to the reflectedor transmitted ray, depending on whether the selected Mode is Reflect or Transmit.
The various indices of refraction used to compute the ray-segments in the scene can bechanged similarly to the Euler angles (Theta, Phi, Psi), by the mouse wheel or by typing in
the values then pressing Enter. The following picture should clarify how the indices are used
to compute the ray paths.

At the end, if the CoordinateAnalyzer is closed with the Apply and Close button, allindices of refraction, the Emergent and Multilayer orientation angles, as well as the Mode,
Compress incident and Decompress emergent options will be passed to the calling Edit
DIFFRACT parameters dialog box.

DiffractGUI User Guide155

17 Disk Editor
17.1 Introduction
As the name suggests, the DiskEditor permits one to set up and modify various types of
optical disks, as used in the DIFFRACT™ DISK command.
The following picture shows the appearance of the main DiskEditor window containing a
Writable disk type.

New disks can be generated from scratch and the current design can be saved to or loaded
from external files or by using the Windows clipboard. The latest option allows to easily copy
disk structures from DiffractGUI into the DiskEditor and to paste back the modified disks
into DiffractGUI.
The various structures and parameters of the disk under edit can be modified either
graphically or by typing in the desired values. The resulting disk surface is shown
immediately in the graphic window. Both methods will be described later in this chapter.
Currently, the DiskEditor supports only disks as specified in the DIFFRACT™ version 8.4
manual. Please refer to it for more detailed information.
The graphic display can be zoomed with the scrolling wheel of the mouse device and pannedby dragging with the left button of the mouse. Dragging means: hold the left mouse button
down and move the mouse cursor.

DiffractGUI User Guide156

17.2 Launching the DiskEditor
The DiskEditor can be started in three different ways: from the menu (1), by a click on the
DiskEditor icon of the Control Bar (2) or, if the Edit DIFFRACT Parameters dialog box
happens to contain a DISK command, by a click on the EDIT button of the Edit DIFFRACT
Parameters dialog box (3).
Methods 1&2: Launch from the Menu or from the Control Bar Icon

Methods 1&2: Launch from the Control Bar Icon attached to a previously selected DISK

DiffractGUI User Guide157

If the DiskEditor is started with method 1 or 2 while a DISK object is selected in the
Workbench, than the DiskEditor is initialized with the data of that particularly selected DISK.
If no DISK object was selected, the DiskEditor remains un-initialized and the DiskEditor may
be used as an independent module to create/load/modify/save disk script files. In this case thetwo bottommost buttons on the left will read Close and OK (see above picture).
If the DiskEditor is initialized with the data of a previously selected DISK command, the twobottommost buttons on the left will read Close and Apply. Additionally, the name of the DISK

will appear in the caption bar of the DiskEditor and the DISK command block remains
attached to the DiskEditor. Apply will transfer back the data to that DISK of the Workbench.
Close will close the DiskEditor without data transfer (e.g. discarding all modifications done
since the last invocation of Apply).
Method 1 and 2 will launch the DiskEditor as a modeless window, which means, other
DiffractGUI commands can be executed while the DiskEditor is open. When the attached
DISK is removed from the Workbench during the DiskEditor session, then the DiskEditor
remains opened, but the Apply button has no effect anymore. Furthermore, more than one
DiskEditor instance can be opened (and kept open) for one and the same DISK. In this case,each click on Apply will overwrite the previous DISK data.
Method 3: Launching from the Edit DIFFRACT Parameters dialog box

When launched in this way, the only difference is that the DiskEditor is opened as a modal
window. This means, to continue working, the DiskEditor must be closed either by theCancel or by the Apply&Close button. (the closing x-button on top-right of the window has
the same effect as Cancel).
Regardless of the method used to start the DiskEditor, all control elements described in thischapter will work in the same way.

DiffractGUI User Guide

158

17.3 The Main DiskEditor Window
The main DiskEditor window contains the following control elements:

Display – offers the possibility to add X-Y-axes, a labeled frame, and two kind of grids to thegraphic output. The option Fit will adjust the x-min, x-max, y-min and y-max of the graphic
display to cover all surface structures. The parameters of the disk itself are not affected byany of these options.
New – will generate a new disk of the specified type (RO, WR, MO or DP) and will placesome structures on its surface, which may help for further processing.
Caution: before inserting the new disk, this command will erase the content of the DiskEditor
without any notification message; hence all previous changes will be lost.
RO, WR, MO or DP – this button indicates the current type of disk under edit and, more
important, it allows one to change the disk-type. However, these changes should be madewith precaution, since disk structures may be eliminated during this operation. For example,
if a WR disk happens to bear grooves and it is converted to a RO disk, the grooves will be
removed automatically because RO-disks do not support groove structures. Please note thatthe eliminated structures are lost forever, that is, remaining at the above example, when the
RO-disk is converted back to the initial WR-disk, the eliminated grooves will NOT be
inserted back automatically.

Units – this button will indicate the currently used length units and allows one to change
them arbitrarily. Of course, this operation will affect only the numerical values of parametersthat represent lengths, leaving unchanged the others. Furthermore, the graphic display will
modify its labels to reflect the new values. The wavelength value is displayed in the sameunits.

DiffractGUI User Guide

159

Note: when waves are selected as length units, the wavelength box will consequently always
display the value 1.

The wavelength can be specified by typing in a new value in the corresponding edit box andpressing the Enter key or clicking on the OK button.
Save and Load – allows one to save the current disk into a file or send it to the clipboard, or
to load a disk from an external file or from the clipboard. Generally, the DiskEditor deals
with two formats, both being ASCII text files: DIFFRACT scripts and Disk scripts.

The DIFFRACT script format is the most useful one, illustrated in the text box below.
$________________________________________________________________________ ##Vacuum wavelength (um): 0.600000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Optical disk surface: DISK
(Length_Units: um) #Type of medium: WR#
SCX,SCY,RA:
0
0
100
#
(Incidence medium) Ninc:
1#
Pregrooved media (Y/N): Y#
A,B,C:
535.734139.9772#
D,ZETA:
63.7126
20#
Reflection coeffs. RL,RG:
1
0.5#
THETA,GCX,GCY:
45
3.77929-3.02343#
Wobble (Sine,Blip,None): Sine#
Central wobble A0,P0,Q0:5
80143.652#
Adjacent wobble A1,P1,Q1:
580
31.3761#
Marks (bumps/pits): Y#
Number of marks: 2#
Mark # 01:
MCX,MCY:-43.6399-19.9368#
THETA:
45#
Round or Flat: R#
Length, Width, Height:
40
10
5
#
Ratio:
0.5#
Reflection coefficient:
1#Mark # 02:
MCX,MCY:
8.14879
32.1663#
THETA:
45#
Round or Flat: R#
Length, Width, Height:
40
10
5
#
Ratio:
0.5#
Reflection coefficient:
1#
Inspect surface pattern: Y#
Xmin,Xmax:
-100
100
#
Ymin,Ymax:
-100
100
#
Color or Gray-scale: C#
Save data file (Y/N): Y#
File identifier: 1#
Propagation distance:
10#
Propagation regime: DFRNL
#
Smax:
0
#

The disk exported in this format can be inserted directly into a command.dat file, or viceversa, copied directly from command.dat files and read into the DiskEditor.
For this reason, the main DiskEditor window always exports to the clipboard in this format.
Since in this format, the specifications of DIFFRACT™ V8.4 are strictly respected, pleaserefer to the DIFFRACT™ manual for more detailed descriptions and examples.

DiffractGUI User Guide

160

The second supported format, the Disk script, can be used only with the DiskEditor. It should
be used to archive the disks, since it offers more robustness for modifications in futureversions. Such a file must begin with the mandatory keyword disk parameter script followedby blocks of text delimited by the key-line generating_name=structure_name. Here,structure_name indicates a type of structure that is to be applied to the disk surface. The
individual parameters of the structure can be specified within the corresponding text-block (inany order) in the form parameter_name = value units, where units are optional and shall be
used only for length-parameters to mark them as such. However, they will be ignored whenassigned to non-length parameters.
The following text boxes illustrate the Disk script format.
disk parameter script
wavelength=0.600000000000 um
nviron=1.0000000
length_units=um
disk_type=WR
generating_name=Aperture
RA=100 um
SCX=0 um
SCY=0 um
Ninc=1
propagation_distance=10 um
propagation_regime=DFRNL
Smax=0
generating_name=WRWobbles
A=5 um
B=35.7341 um
C=39.9772 um
D=63.7126 um
ZETA=20 um
THETA=45
GCX=3.77929 um
GCY=-3.02343 um
A0=5 um
P0=80 um
Q0=143.652
A1=5 um
P1=80 um
Q1=31.3761
RL=1
RG=0.5generating_name=WRMark
MCX=-43.6399 um
MCY=-19.9368 um
theta=45
round_or_flat=round
length=40 um
width=10 um
height=5 um
ratio=0.5
reflection_coeff=1
generating_name=WRMark
MCX=8.14879 um
MCY=32.1663 um
theta=45
round_or_flat=round
length=40 um
width=10 um
height=5 um
ratio=0.5
reflection_coeff=1
generating_name=Plot
Xmin=-100 um
Xmax=100 um
Ymin=-100 um
Ymax=100 um
save_to_file?=yes
color_or_gray?=color
file_id=1

When the DiskEditor imports a disk from the clipboard, it checks for the disk parameter
script keyword, and if present, it assumes Disk script format, otherwise it expects data
specified in the DIFFRACT™ script style. Consequently it is able to import both formats.
However, when exporting to the clipboard from the main DiskEditor window, the disk data ispassed in the DIFFRACT™ format.

DiffractGUI User Guide

161

Saving disk surface as plot
With the Save – Plot command, the boundary surface between the layers can be exported as amatrix of numbers, similar to the PLOT files exported by DIFFRACT™. These files can beimported later and visualized in the BitmapView or in the ReliefView of DiffractGUI.
After invoking the Save-Plot command, a small dialog box is opened first, allowing one to
specify the desired rows (NY) and columns (NX) of the plot matrix. Additionally, one may
choose to clip the disk structures outside the disk aperture and choose a scaling factor, which
will be used to multiply the data before writing in the plot-file.

It should be noted that this feature needs a Plot and an Aperture structure to be defined. The
Aperture is needed internally, even if the Clip Aperture option is not chosen. The picture
below, shows a possible result, viewed in the BitmapView of DiffractGUI.

In case of a multi-layered DP-disk, a separate plot file will be generated for each layer. The
corresponding filenames will be generated by adding the extension “_layer_n”, where nstands for the layer number. Finally, it should be considered that the magnetic domains will
not be contained in these plots, since they do not affect the thickness of the layer where they
are embedded.
DiffractGUI User Guide

162

17.4 Disk Surface Structures
The individual disk structures can be inspected and modified with the Structures dialog box.
It is opened with a click on the Structures… button of the main DiskEditor window.

The dialog box is divided into three main areas:•••on the left, a set of control elements that allow one to insert, remove, scale, translate
or rotate structures.
in the middle, a structure-list that permits one to select specific structures and tocontrol each structure in regards to whether it is visible or not in the graphic output of
the main DiskEditor window.
to the right, an edit box that list the parameters of a single structure (the focusedstructure, see below) and an edit box that allows one to assign specific parameters
globally to all selected structures.

Within the structure-list, none, one, or more structures may be selected, but exactly one of
the structures has a special hierarchical meaning. This structure will be referred as thefocused structure in the following way. In the list, the focused structure is always surrounded
by a dotted rectangle and the parameters edit box (to the right of the dialog window) will
always display the parameters of this focused structure.
A left button click on a structure in the list will always mark that structure as focused,regardless of the state of the Ctrl and Shift keys. If neither the Ctrl key nor the Shift key isheld down during the click, the structure is also marked as selected and all other structures
are marked as unselected. If the Ctrl key is held down, then the selection status of the clicked
DiffractGUI User Guide

163

structure is toggled (that is, if it was selected, it will become unselected and vice-versa), but
the selection status of all other structures is left unchanged. If the Shift key is held down, then
the whole range of structures between the previous focused structure and the newly focusedstructure will be selected and all structures that lie outside this range will be unselected.
Please note that this selection mechanism is similar to that used in the File-Explorer of theWindows operating system. Also, note that it is not necessary to also select the focusedstructure.
A click on the Yes or No text in the visible column will toggle the visibility of that structure in
the graphic window. If the visible column header is clicked, the visibility flags of ALL
structures are toggled. If, during the click, the Ctrl key is hold down, all structures are marked
as visible and if the Shift key is hold down, all structures are marked as not visible.
Finally, it should be remarked that the selected structures that are displayed in the graphic
view will be drawn with a thicker pen, to reflect their selection status.
When the focused-state of a structure is entered, the DiskEditor generates the parameters listof that structure and displays it in the Parameters edit box (to the right of the dialog window).
When the focused-state of a structure is switched off, the content of the Parameters edit box
is used to actualize the structures parameters. The same happens if the OK button of theStructures dialog box is clicked.
This means that any modifications made by the user in the Parameters edit box will bepassed back to the focused structure upon a click on OK or by focusing a different structurein the structure list. It should be noted that units are considered (cm, mm, um, nm or waves)and the value is converted always to the unit specified in the main DiskEditor window.
Among the control elements located on the left side of the dialog window, the most important
are the Remove and Insert buttons. The Remove button eliminates the focused structure fromthe disk. However this happens in a selective manner, that is, not all structures can beremoved. For example, the Aperture is mandatory for all disk types, so it cannot be removed.
Furthermore, in the case of DP disks, the MarkSet structure that marks the beginning of a setof marks (i.e. bumps/pits) cannot be removed until all marks have been previously removed.
New structures can be inserted to the disk with the Insert button. It offers the following
options:

Based on the type of disk and on the type and number of already existing structures, the insert
command enables only those structure options that make sense for the current configuration.
DiffractGUI User Guide

164

For example, if a WR-disk has already a groove-structure, it will be not possible to insert asecond (unsupported) groove structure.
The new structure is always inserted at the dedicated position in the list of structures.
Typically, the focused structure is not considered, but there are situations where this isnecessary, and then it will be considered. For example, in the case of a DP-disk that has morethen one set of marks, when a new mark (bump/pit) is created and the focused structure is oftype Mark, then the new mark will be inserted after the focused mark. This functionality
allows one to control which set of marks the new bump/pit will be added to. If, in thissituation, the focused structure is not of type Mark, then the new mark will be appended to
the last existent set of marks. If no set of marks is defined yet, a new set of marks is inserted,
containing the new mark.
The Scale, Translate and Rotate control elements act on all selected structures. If no structure
is selected, then ALL structures of the disk are affected.
For scaling, one parameter needs to be specified in the edit box below the “Scale” label. The
S+ button will multiply all lengths of the selected structures, while the S- command will
divide the lengths by the scaling parameter (reverting the effect of S+)
For translation, two parameters are needed: the X and Y translation step, which can be
specified in the edit boxes labeled with X and Y. A translation step is performed with a clickon the T+ button or a click on the T- button, which translates in the opposite direction.
For rotation, three parameters can be specified: the coordinates of the center of rotation(Xc,Yc) and the angle of rotation (in degrees). Similarly to scaling and translation, R+
performs the rotation step and R- rotates opposite to R+.
Generally, these transformations modify only the parameters that represent physical lengths.
The translation and rotation parameters are in fact also lengths, but they do not suffer any
modification when the main length units are changed, so some attention should be paid tothem before using the T+, T-, R+ or R- buttons in this case.
The last two remaining buttons, Group edit and Edit are useful during the edit of thestructures and will be described next.

The Copy selection option will copy the selected structures to the clipboard (in the Disk
Script format, see description above) and the Cut selection will do the same, but will remove
them from the disk subsequently. Paste will take any text from the clipboard, interpret it as a
Disk Script and try to construct disk structures from it, inserting them in the existing structure
list. If, during this process, structures are encountered that are not allowed for the current
disk type, they will be rejected and not inserted.

DiffractGUI User Guide165

17.5 Edit Structures GraphicallyThis kind of operation is best done with the Structures dialog box opened simultaneouslywith the main DiskEditor window, as displayed below.

Each structure displayed in the graphic window can be put in a special operating mode, theedit-mode, by holding down the Ctrl key and performing a click with the left button of themouse over the desired structure. Alternatively, the edit-mode for the focused structure canbe entered from the Structures dialog box by a click on the Edit-Graphically button. This isparticularly useful for structures like grooves or structures that overlap, and thus cannot be
accessed in the graphic window.
The following pictures illustrate the edit-mode for a mark and a wobbled groove.
D,Q0
A1,P1

length, width

A0,P0
CX,CY

C,Q1
THETA

B
A

THETA
CX,CY

The obvious difference for this mode is the presence of a certain number of additionalfeatures in the drawing (most of them being small rectangles). These features will be referred

DiffractGUI User Guide166

to as edit nodes. Each of these edit nodes is attached to one or more parameters of thestructure.
The shape of the node indicates, at some degree, the type of the attached parameters:•••a cross indicates the center of the structurea circle indicates that the node is attached to an orientation angle
a rectangular shape is used for all other parameters

Regardless of their shape, all edit nodes operate identically. To modify the parametersattached to a node, position the mouse cursor on that node, press and hold down the left
mouse button and move the mouse cursor to a different position. As the mouse cursor moves,
the edit node will follow the cursor and the parameters attached to that edit node will change
correspondingly. During the mouse movement, the modifications will also be reflected in the
Parameters edit box of the Structures dialog box, so the exact numerical values can befollowed.
To exit the edit mode, click anywhere outside any of the displayed edit nodes, or enter
another structure in the edit mode (by any of the methods described above).
Only one structure can be put in the edit mode at the same time. However, more then one
structure can be modified simultaneously, when the Group edit button of the Structures
window is checked. In this case, the changes generated by dragging one of the edit nodes will
apply to all selected structures.
For example, to translate a group of marks over the disk surface, select the marks to betranslated, check the Group edit button, put one of the marks (it does not matter which one)in the edit mode and drag the center node (attached to the CX, CY parameters) with themouse. All selected marks will coherently follow the changes. Of course, the same will
happen if the angle theta, or the length and width of the edited mark are modified.
It should be noted that this feature works only for structures of similar type (typically groups
of marks).
The Plot and Aperture structures can be entered in the edit mode by a click on the perimeterof their drawing (and holding down the Ctrl key), in contrast to the marks, where the click
can be performed anywhere inside the mark. This restriction is necessary because theAperture and Plot extend over the complete active area of the disk, and hence would cover allother, smaller structures, making impossible to select them.
The central point of the grooves (CX, CY) is always displayed as a cross in the graphic
window. The grooves can be put in the edit mode by a click on this cross (and, of course,
hold down the Ctrl key).
It should be considered that the modifications performed by graphical editing suffer a certain
granularity, due to the pixel structure of the display. Hence for very precise values it isnecessary to use the Parameters edit box of the Structures window.
The Assign to selected edit box allows one to assign identical values to specific parameters of
the selected structures. To do this, select the structures to be modified, specify the list ofparameters in the form parameter_name = value and click on Assign to selected. This feature
DiffractGUI User Guide

167

may also be helpful to align marks horizontally or vertically, by assigning identical values to
the CX or CY parameters.

17.6 Vertical Cross Section
The Section… option on the main DiskEditor window allows one to visualize arbitrary
vertical z-sections through the disk under construction. Furthermore, in case of more then one
layer, it allows to modify graphically the thickness of each layer.
Upon a click on the Section… button, two things happen: the Section dialog box is opened
and the main DiskEditor graphic window will display a yellow line across which the zsection will be computed and displayed in the Section dialog box.

Position indicator

Section line

Thickness of Layer 3

Xc,Yc

Angle

The section line can be specified with the parameters Xc, Yc and Angle. These parameters
can be modified directly in the Section dialog box, followed by a click on the Refresh button,
or graphically, similar to the graphical editing of the other disk structures. Similarly, to enter
the graphical editing for the section-line, hold down the Ctrl key and perform a left mouseclick on the yellow section line. Two edit nodes appear, which may be used to modify thesection-line parameters as indicated in the above picture. As the parameters of the sectionline vary, the content of the Section dialog box is continuously updated. It should be notedthat the cross-section is computed only inside the plot area of the disk, hence a plot structure
must be defined prior of using this feature.
In addition to the cross-section through the various layers, the Section dialog box also
displays the boundary line between the layers. A selected layer is displayed with bold lettersand lines. Its thickness can also be edited graphically, as indicated in the previous picture. By
using the visible flag in the structure list of the Structures dialog box, each layer can beremoved from the Section display. The Points parameter will specify the granularity of thecross-section curve.

DiffractGUI User Guide168

As the mouse cursor moves inside the Section graphic, a Position indicator cross is displayed
and moved along the section-line in the main DiskEditor graphic window, to indicate the(x,y)-location of the z-section point.

17.7 3D View
For completeness, with the View 3D… button of the main DiskEditor window, the layerboundaries can be visualized in a 3D manner.

Initially, the display contains only the three coordinate axes. To display the layer boundaries,
click on Refresh, which will generate the internal data matrices for each layer. Due to therelatively large time need to generate and render the data, the display will not follow
automatically to possible changes made in the main DiskEditor, Structures or Section
windows, hence the Refresh button must be used also in these cases to update the 3D view.
The granularity of the data-mesh can be chosen with NX and NY. However, it should beconsidered that large values may lead to prohibitive rendering time, and should be used only
if extremely small structures must to be made visible on the displayed surfaces.
Basically, Redraw will repaint the screen, but if necessary, it automatically performs a
Refresh (for example if NX or NY have been modified)DiffractGUI User Guide

169

Z-Scale is a magnifying factor for the z-coordinate only, and allows one to make better
visible structures with small heights.
Tilt, Offset and Zoom are parameters that specify the orientation of the disk and refer solely
to the display. Generally, none of the disk parameters can be modified in this 3D viewer.
The Tilt values represent angles and can be modified simply by dragging with the left mousebutton over the 3D graphic. The Offset-values can be modified similarly, but holding the Ctrl
key down during the dragging. Note that only two offset-values will be modified by thismethod. Which of them are modified depends on the Tilt-angles. The zoom can be modified
by rotating the scroll-wheel of the mouse. Of course, the Tilt, Offset and Zoom values can be
typed in directly in the corresponding edit boxes, but then Redraw has to be clicked after.
Fit will modify the display parameters such that the complete disk becomes visible.

A Grid-Box can be attached, as displayed above, and the coordinate axes arrows can beremoved with the Axes check button. The surfaces can be made semi-transparent with theTransparent button and the rendering mode can be switched from orthographic toperspective with the Ortho button. The background color can be chosen as the Windows
default color, or user defined with the Back button. For esthetic reasons, a color gradient may
be applied with the Grad button. The image can be rendered only inside the disk aperture
with the Clip aperture button and the surfaces can be displayed as wire-frames with the
Wireframe button.

DiffractGUI User Guide170

As for the other features of the DiskEditor, it is necessary to define an Aperture and a Plot
structure for the disk under edit, otherwise error messages will be displayed.
Individual layer surfaces can be hidden by choosing the visible flag No in the structure list of
the Structures dialog box.

DiffractGUI User Guide

171

18 Beam Editor
18.1 Introduction
As the name suggests, the BeamEditor permits one to set up and modify various types of
optical BEAMs, as used in the DIFFRACT™ BEAM command. The following picture
shows the appearance of the main BeamEditor window containing a HermiteGaussian
BEAM type.

New BEAMs can be generated from scratch and the current design can be saved to or loaded
from external files or by using the Windows clipboard. The latest option allows to easily copy
BEAMs from DiffractGUI into the BeamEditor and to paste back the modified BEAMs into
DiffractGUI.
The various parameters of the BEAM under edit can be modified either graphically or bytyping in the desired values. The resulting BEAM surface is shown immediately in thegraphic window. Both methods will be described later in this chapter.
Currently, the BeamEditor supports only beam distributions as specified in the DIFFRACT™
version 8.4 manual. Please refer to it for more detailed information.
The graphic display can be zoomed with the scrolling wheel of the mouse device and pannedby dragging with the left button of the mouse. Dragging means: hold the left mouse button
down and move the mouse cursor.

DiffractGUI User Guide

172

18.2 Launching the BeamEditor
The BeamEditor can be started in three different ways: from the menu (1), by a click on the
BeamEditor icon of the Control Bar (2) or, if the Edit DIFFRACT Parameters dialog box
happens to contain a BEAM command, by a click on the EDIT button of the Edit DIFFRACT
Parameters dialog box (3).
Methods 1&2: Launch from the Menu or from the Control Bar Icon

Methods 1&2: Launch from the Control Bar Icon attached to a previously selected BEAM

If the BeamEditor is started with method 1 or 2 while a BEAM object is selected in the
Workbench, than the BeamEditor is initialized with the data of that particularly selected
DiffractGUI User Guide

173

BEAM. If no BEAM object was selected, the BeamEditor remains un-initialized and the
BeamEditor may be used as an independent module to create/load/modify/save BEAM script
files. In this case the two bottommost buttons on the left will read Close and OK (see above
picture).
If the BeamEditor is initialized with the data of a previously selected BEAM command, thetwo bottommost buttons on the left will read Close and Apply. Additionally, the name of the
BEAM will appear in the caption bar of the BeamEditor and the BEAM command block
remains attached to the BeamEditor. Apply will transfer back the data to that BEAM of the
Workbench. Close will close the BeamEditor without data transfer (e.g. discarding all
modifications done since the last invocation of Apply).
Method 1 and 2 will launch the BeamEditor as a modeless window, which means, other
DiffractGUI commands can be executed while the BeamEditor is open. When the attached
BEAM is removed from the Workbench during the BeamEditor session, then the BeamEditor
remains opened, but the Apply button has no effect anymore. Furthermore, more than one
BeamEditor instance can be opened (and kept open) for one and the same BEAM. In thiscase, each click on Apply will overwrite the previous BEAM data.
Method 3: Launching from the Edit DIFFRACT Parameters dialog box

When launched in this way, the only difference is that the BeamEditor is opened as a modal
window. This means, to continue working, the BeamEditor must be closed either by theCancel or by the Apply&Close button (the closing x-button on top-right of the window has
the same effect as Cancel). Regardless of the method used to start the BeamEditor, all control
elements described in this chapter will work the same way.

18.3 The Main BeamEditor Window
The main BeamEditor window contains the following control elements:

DiffractGUI User Guide

174

Display – offers the possibility to add X-Y-axes, a labeled frame, and two kind of grids to thegraphic output. The option Fit will adjust the x-min, x-max, y-min and y-max of the graphic
display to cover all beam mesh. The parameters of the BEAM itself are not affected by any ofthese options.
New – will generate a new BEAM of the specified type (UB, SG, GG, LG, HG or LD) andwill assign some default values to it.
Caution: before inserting the new BEAM, this command will erase the content of the
BeamEditor without any notification message; hence all previous changes will be lost.
UB, SG, GG, LG, HG or LD – this button indicates the current type of BEAM under edit
and, more important, it allows one to change the BEAM-type. However, these changes
should be made with precaution, since BEAM parameters may be eliminated during thisoperation. For example, if a UB (Uniform) BEAM happens to have specified aberrations andit is converted to a LD (Laserdiode) BEAM, the aberration values will be removed
automatically because LD-BEAMs do not accept aberrations. Please note that the eliminatedvalues are lost forever, that is, remaining at the above example, when the LD-BEAM isconverted back to the initial UB-BEAM, the eliminated aberration values will NOT be
inserted back automatically.

Units – this button will indicate the currently used length units and allows one
to change them arbitrarily. Of course, this operation will affect only thenumerical values of parameters that represent lengths, leaving unchanged theothers. Furthermore, the graphic display will modify its labels to reflect the
new values. The wavelength value is displayed in the same units.
Note: when waves are selected as length units, the wavelength box will consequently always
display the value 1.

The wavelength can be specified by typing in a new value in the corresponding edit box andpressing the Enter key or clicking on the OK button.
On the left-bottom side of the main BeamEditor window, a group of checkbuttons are displayed. They allow to specify how to build up the backgroundbitmap.
Ampl and Phas : specify if the amplitude or the phase of the beam distribution
shall be displayed. If none of these check-buttons are checked, no backgroundbitmap is generated.

DiffractGUI User Guide

175

B&W : used to toggle between gray or color representation.
Leg : used to show or hide the color legend bar.
Wrap : this button applies only when the phase is displayed and aberrations are added.
Aberrations (Zernike or Seidel) are always converted into phase values. If Wrap is checked,
these values are adjusted to values between –180° and +180°.
Inv : when checked, the color legend values get swapped. This means that the maximum
values are displayed black (blue) instead of white (red).
Ix, Iy : used to select the component that is to displayed. Depending by the state of the Ampl,
Phase and Int buttons, the text label of the Ix,Iy buttons may change to Ex,Ey or Px,Py toreflect better the displayed entity.
Clip : if checked, the displayed values outside the specified aperture are set to zero.
Int : applies only when the amplitude of the distribution is displayed. If Int is checked, theelectrical amplitude is squared, otherwise not.
Save and Load – allows one to save thecurrent BEAM into a file orsend it to the clipboard, or to load a BEAM
from an external file or from the clipboard.
Generally, the BeamEditor deals with twoformats, both being ASCII text files: DIFFRACT scripts and BEAM scripts.

The DIFFRACT script format is the most useful one, illustrated in the text box below.
$________________________________________________________________________ ##Vacuum wavelength (mm): 0.000650000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Initial distribution: BEAM
(Length_Units: mm) #TYPE: UB/SG/GG/LG/HG/LD: HG#
BCX,BCY,POWER(mW):001#Order parameters (Nx,Ny):
45#
Base 1/e radii RX0,RY0:
1.82
2.145
#
RA,THETA:
6.5
35#
Aberrations: None#
Polarization RHO,ETA:
33
22#
NMAX,NMAY:
256
256
#
LMAX,LMAY:
65
65#

The BEAM exported in this format can be inserted directly into a command.dat file, or viceversa, copied directly from command.dat files and read into the BeamEditor.
For this reason, the main BeamEditor window always exports to the clipboard in this format.
Since in this format, the specifications of DIFFRACT™ V8.4 are strictly respected, pleaserefer to the DIFFRACT™ manual for more detailed descriptions and examples.
The second supported format, the BEAM script, can be used only with the BeamEditor. It
should be used to archive the BEAMs, since it offers more robustness for modifications infuture versions. Such a file must begin with the mandatory keyword beam parameter script

DiffractGUI User Guide

176

followed by blocks of text delimited by the key-line generating_name=set_name. Here,
set_name indicates a set of parameters of the BEAM. The individual parameters of the set canbe specified within the corresponding text-block (in any order) in the form parameter_name= value units, where units are optional and shall be used only for length-parameters to markthem as such. However, they will be ignored when assigned to non-length parameters.
The following text box illustrates the BEAM script format.
beam parameter script
length_units=mm
wavelength=0.65 um
beam_type=HG
generating_name=BeamMesh
NMAX=256
NMAY=256
LMAX=65 mm
LMAY=65 mm

generating_name=BeamGeometry_HG
BCX=0 mmBCY=0 mmPower_mW=1
Nx=4
Ny=5
RX0=1.82 mm
RY0=2.145 mm
RA=6.5 mm
THETA=35
generating_name=Polarization
RHO=33
ETA=22

When the BeamEditor imports a BEAM from the clipboard, it checks for the beam
parameter script keyword, and if present, it assumes BEAM script format, otherwise it
expects data specified in the DIFFRACT™ script style. Consequently it is able to import bothformats. However, when exporting to the clipboard from the main BeamEditor window, theBEAM data is passed in the DIFFRACT™ format.
Saving BEAM distribution as plot
With the Save – Plot command, the displayed background map can be exported as a matrix of
numbers, similar to the PLOT files exported by DIFFRACT™. These files can be imported
later and visualized in the BitmapView or in the ReliefView of DiffractGUI.
After invoking the Save-Plot command, a small dialog box is opened first, allowing one to
specify the desired rows (NY) and columns (NX) of the plot matrix. Additionally, one may
choose to clip the BEAM distribution outside the BEAM aperture and choose a scaling
factor, which will be used to multiply the data before writing in the plot-file.

The plot is build always over the entire displayed area, and not over the mesh-area given by
LMAX and LMAY. The picture below, shows a possible result, viewed in the BitmapView
of DiffractGUI.

DiffractGUI User Guide

177

18.4 BEAM Parameters
The individual BEAM parameters can be inspected and modified with the Parameters dialog
box. It is opened with a click on the Parameters… button of the main BeamEditor window.

DiffractGUI User Guide

178

The dialog box is divided into three main areas:•••on the left, a group of control elements that allow one to insert or remove sets ofparameters, or to scale, translate or rotate geometric shapes like aperture and meshrectangle.
in the middle, a set-list that permits one to select specific sets of parameters and tocontrol each in regards to whether it is visible or not in the graphic output of the main
BeamEditor window.
to the right, an edit box that list the parameters of a single parameter-set (the focusedset, see below).

For convenience, the parameters of a BEAM are grouped into several sets, each set
containing distinct parameters. The following sets are available:

BeamMesh : contains LMAX, LMAY, NMAX and NMAY. Common to all BEAM types.
BeamGeometry_XX : this set is built up by different parameters for each BEAM-type andcontains all relevant parameters that made up the corresponding distribution and aperture. XX
can be one of the UB, SG, GG, HG, LG or LD mnemonics.
Polarization : contains the RHO and ETA polarization parameters. Common to all BEAM
types.
Seidel and Zenike : these optional sets, optionally available to all BEAM-types (except
Laserdiode-type LD), encapsulate the Seidel or Zernike aberration coefficients.

DiffractGUI User Guide

179

Within the set-list, none, one, or more set may be selected, but exactly one of the sets has a
special hierarchical meaning. This set will be referred as the focused set in the following
way. In the list, the focused set is always surrounded by a dotted rectangle and the parameters
edit box (to the right of the dialog window) will always display the parameters of this focusedset.
A left button click on a set in the list will always mark that set as focused, regardless of thestate of the Ctrl and Shift keys. If neither the Ctrl key nor the Shift key is held down during
the click, the set is also marked as selected and all other sets are marked as unselected. If the
Ctrl key is held down, then the selection status of the clicked set is toggled (that is, if it was
selected, it will become unselected and vice-versa), but the selection status of all other sets isleft unchanged. If the Shift key is held down, then the whole range of sets between theprevious focused set and the newly focused set will be selected and all sets that lie outside
this range will be unselected. Please note that this selection mechanism is similar to that usedin the File-Explorer of the Windows operating system. Also, note that it is not necessary toalso select the focused set.
A click on the Yes or No text in the visible column will toggle the visibility of that set in thegraphic window. If the visible column header is clicked, the visibility flags of ALL sets aretoggled. If, during the click, the Ctrl key is hold down, all sets are marked as visible and if
the Shift key is hold down, all sets are marked as not visible.
Finally, it should be remarked that the selected sets that are displayed in the graphic view will
be drawn with a thicker pen, to reflect their selection status.
When the focused-state of a set is entered, the BeamEditor generates the parameters list ofthat set and displays it in the Parameters edit box (to the right of the dialog window).
When the focused-state of a set is switched off, the content of the Parameters edit box is used
to actualize the set parameters. The same happens if the OK button of the Parameters dialog
box is clicked.
This means that any modifications made by the user in the Parameters edit box will bepassed back to the focused set upon a click on OK or by focusing a different set in the set-list.
It should be noted that units are considered (cm, mm, um, nm or waves) and the value isconverted always to the unit specified in the main BeamEditor window.
Among the control elements located on the left side of the dialog window, the most important
are the Remove and Insert buttons. The Remove button eliminates the focused set ofparameters from the BEAM. However this happens in a selective manner, that is, not all sets
can be removed. For example, the BeamGeometry parameter set is mandatory for all BEAM
types, so it cannot be removed.
New sets of parameters can be inserted to the BEAM with the Insert button. It offers thefollowing options:Typically, this feature is most useful to add aberration parameter
sets (Seidel or Zernike). The framework takes care to prevent theinsertion of both types simultaneously. To change the type of an

DiffractGUI User Guide

180

existing aberration set from Seidel to Zernike (and vice-versa), first delete the existing set(with the Remove button) then insert a new one with the Insert button.

The Scale, Translate and Rotate control elements act on all selected sets. If no set is selected,
then ALL sets of the BEAM are affected.
For scaling, one parameter needs to be specified in the edit box below the “Scale” label. The
S+ button will multiply all lengths of the selected sets, while the S- command will divide thelengths by the scaling parameter (reverting the effect of S+)
For translation, two parameters are needed: the X and Y translation step, which can be
specified in the edit boxes labeled with X and Y. A translation step is performed with a clickon the T+ button or a click on the T- button, which translates in the opposite direction.
For rotation, three parameters can be specified: the coordinates of the center of rotation(Xc,Yc) and the angle of rotation (in degrees). Similarly to scaling and translation, R+
performs the rotation step and R- rotates opposite to R+.
Generally, these transformations modify only the parameters that represent physical lengths.
The translation and rotation parameters are in fact also lengths, but they do not suffer any
modification when the main length units are changed, so some attention should be paid tothem before using the T+, T-, R+ or R- buttons in this case.
The last remaining button Edit is useful during the edit of the structures and will be described
next.
The Copy selection option will copy the selected sets to the clipboard (inthe BEAM Script format, see description above) and the Cut selection
will do the same, but will remove them from the BEAM subsequently.
Paste will take any text from the clipboard, interpret it as a BEAM Script
and try to construct BEAM sets from it, inserting them in the existing set
list. If, during this process, sets are encountered that are not allowed forthe current BEAM type, they will be rejected and not inserted.

18.5 Edit Parameters GraphicallyThis kind of operation is best done with the Parameters dialog box opened simultaneouslywith the main BeamEditor window, as displayed below.

DiffractGUI User Guide

181

RY0

THETA

RX0

RA

BCX,BC

Each set displayed in the graphic window can be put in a special operating mode, the editmode, by holding down the Ctrl key and performing a click with the left button of the mouseover the desired structure. Alternatively, the edit-mode for the focused structure can beentered from the Parameters dialog box by a click on the Edit-Graphically button. This isparticularly useful for structures like grooves or structures that overlap, and thus cannot be
accessed in the graphic window.
The obvious difference for this mode is the presence of a certain number of additionalfeatures in the drawing (most of them being small rectangles). These features will be referred
to as edit nodes. Each of these edit nodes is attached to one or more parameters of thestructure.
The shape of the node indicates, at some degree, the type of the attached parameters:•••a cross indicates the center of the shapea circle indicates that the node is attached to an orientation angle
a rectangular shape is used for all other parameters

Regardless of their shape, all edit nodes operate identically. To modify the parametersattached to a node, position the mouse cursor on that node, press and hold down the left
mouse button and move the mouse cursor to a different position. As the mouse cursor moves,
the edit node will follow the cursor and the parameters attached to that edit node will change
correspondingly. During the mouse movement, the modifications will also be reflected in the
Parameters dialog box, so the exact numerical values can be followed.
To exit the edit mode, click anywhere outside any of the displayed edit nodes, or enter
another set in the edit mode (by any of the methods described above).
Only one set can be put in the edit mode at the same time.

DiffractGUI User Guide

182

The BeamMesh set can be entered in the edit mode by a click on the perimeter of its drawing(and holding down the Ctrl key), in contrast to the marks, where the click can be performed
anywhere inside the mark.
The central point of the shapes is always displayed as a cross in the graphic window. The
corresponding sets can be put in the edit mode by a click on this cross (and, of course, holddown the Ctrl key).
It should be considered that the modifications performed by graphical editing suffer a certain
granularity, due to the pixel structure of the display. Hence for very precise values it isnecessary to use the Parameters edit box of the Parameters window.
A third way to modify the parameters is by using the mouse-wheel. To use this feature, place
the text caret in the Parameters edit box inside the text line that contains the desired
parameter, hold down the CTRL key and turn the wheel. Under this circumstances, at eachclick of the wheel the parameter value is modified by a certain percentage. The percentage
amount that is used can be specified with the Wheel sensitivity slider on top-left of thewindow between 0.1 % and 10 %. It should be noted that this feature would not modify zero
values. For this cases, hold down the CTRL and the SHIFT keys simultaneously, which will
ADD (instead multiplying) the specified percentage value (between 0.001 and 0.1, dependingon the Wheel sensitivity setting) as a constant to the parameter.

18.6 Vertical Cross Section
The Section… option on the main BeamEditor window allows one to visualize arbitrary
vertical z-sections through the BEAM distribution under construction. Upon a click on the
Section… button, two things happen: the Section dialog box is opened, and the main
BeamEditor graphic window will display a yellow line across which the z-section will becomputed and displayed in the Section dialog box.
The section line can be specified with the parameters Xc, Yc and Angle. These parameters
can be modified directly in the Section dialog box, followed by a click on the Refresh button,
or graphically, similar to the graphical editing of the other BEAM structures. Similarly, toenter the graphical editing for the section-line, hold down the Ctrl key and perform a left
mouse click on the yellow section line. Two edit nodes appear, which may be used to modify
the section-line parameters as indicated in the above picture. As the parameters of thesection-line vary, the content of the Section dialog box is continuously updated. It should be
noted that the cross-section is computed only inside the computational mesh area (specified
with LMAX and LMAY parameters of the BeamMesh set) of the BEAM.

DiffractGUI User Guide

183

Position indicator

Section line
Angle
Xc,Yc

The Points parameter specifies the granularity of the cross-section curve.
As the mouse cursor moves inside the Section graphic, a Position indicator cross is displayed
and moved along the section-line in the main BeamEditor graphic window, to indicate the (x,y)-location of the z-section point.
The graphic of the Section dialog box can be zoomed in and out arbitrarily with the scrollwheel of the mouse. Additionally, if during the turning of the wheel the CTRL key is holddown, then only the x-axis is zoomed and if the SHIFT key is hold down, then only the y-axis
is zoomed, allowing thus arbitrary zooming areas. Please note that this is valid for thegraphics of the Main BeamEditor window too.

18.7 3D View
For completeness, with the View 3D… button of the main BeamEditor window, thedistribution can be visualized in a 3D manner. Initially, the display contains only the threecoordinate axes. To display the distribution, click on Refresh, which will generate theinternal data matrices for each layer. Due to the relatively large time need to generate andrender the data, the display will not follow automatically to possible changes made in themain BeamEditor, Parameters or Section windows, hence the Refresh button must be usedalso in these cases to update the 3D view.
The granularity of the data-mesh can be chosen with NX and NY. However, it should beconsidered that large values may lead to prohibitive rendering time, and should be used only
if extremely small structures must to be made visible on the displayed surfaces.
Basically, Redraw will repaint the screen, but if necessary, it automatically performs a
Refresh (for example if NX or NY have been modified)

Z-Scale is a magnifying factor for the z-coordinate only, and allows one to make better
visible structures with small heights.

DiffractGUI User Guide

184

Tilt, Offset and Zoom are parameters that specify the orientation of the BEAM and refersolely to the display. Generally, none of the BEAM parameters can be modified in this 3D
viewer.
The Tilt values represent angles and can be modified simply by dragging with the left mousebutton over the 3D graphic. The Offset-values can be modified similarly, but holding the Ctrl
key down during the dragging. Note that only two offset-values will be modified by thismethod. Which of them are modified depends on the Tilt-angles. The zoom can be modified
by rotating the scroll-wheel of the mouse. Of course, the Tilt, Offset and Zoom values can be
typed in directly in the corresponding edit boxes, but then Redraw has to be clicked after.

Fit will modify the display parameters such that the complete BEAM becomes visible.

A Grid-Box can be attached, as displayed above, and the coordinate axes arrows can beremoved with the Axes check button. The surface can be made semi-transparent with theTransparent button and the rendering mode can be switched from orthographic toperspective with the Ortho button. The background color can be chosen as the Windows
default color, or user defined with the Back button. For esthetic reasons, a color gradient may
be applied with the Grad button. The image can be rendered only inside the BEAM aperture
with the Clip aperture button and the surface can be displayed as wire-frames with the
Wireframe button.

DiffractGUI User Guide

185

19 Workflow Editor
The $-command-lines, as implemented in DIFFRACT™, are very versatile for implementing
various kind of loops and other control structures. However, for large command.dat files orfor more complex program flow they are somewhat hard to maintain up to date duringchanges of the DIFFRACT™ commands. To overcome this difficulties and to allow a larger
exploit of all the capabilities of the $-command-lines, DiffractGUI offers the Workflow
Editor feature. Within the Workflow Editor it is possible to declare the control structures as alittle program written in a high-level C-like language, which is then mechanically translated
into $-command-lines inside the command.dat by an integrated mini-compiler. The Workflow
Editor offers a development environment for this language, which will be called workflow
scripting language in the following, and encapsulates the cross-compiler that translates
programs written in this language into a specific command.dat.
With this tool, there is no need anymore to edit and adapt each $-command-line individuallyto the current parameters of the DIFFRACT™ commands, the workflow-script compiler will
do this. All that’s necessary is to write a workflow-script program and let the Workflow
Editor do the work and translate it into $-command-lines that will be properly inserted into
the command.dat. Typically, this should be the last step before launching DIFFRACT™ for agiven simulation setup.
This chapter will explain the Workflow Editor, the syntax of the workflow scripting
language and will give some introductory simple examples.

The Workflow Editor can be launched either by the menu
command DIFFRACT – Workflow editor… or by a click on the
shortcut icon in the command-bar, as illustrated in the pictures.

DiffractGUI User Guide

186

The following picture shows the opened Workflow Editor ready for use. It consists of four
windows:-

to the left, a command list containing all DIFFRACT commands that are present in
the current command.dat. Within this list one command can be selected with themouse.
in the middle, a parameters list of the selected command.
to the right, the most important window, a small text-editor for the workflow script.
at the bottom, a log-output which will display various messages or errors during thecompilation of the script.

The buttons on top of the window have the following meaning:

Close – hides the Workflow Editor. Please notice that the content of the Workflow Editor is
not destroyed by this operation. Has the same effect as a click on the standard right-top xbutton of the window.
Refresh – populates the command list with the current commands of the workbench. Should
be used to bring the list up to date upon modifications of the workbench.
Commands – this check button can be used to hide/show the command list and the parameter
list. If they are hidden, the Script window extends to the whole window width.
Log – works similar to the Commands button, but applies to the Log-window. Both buttons
should be used during editing larger scripts when more space is needed for the Script
window.

DiffractGUI User Guide

187

Init – will create and insert a text block in the Script window. The block will be build up by
the content of the command list.
Clear – will remove all $-command-lines from the current command.dat.
Check – will interpret and examine the current workflow-script throwing appropriate
messages in the Log window. It works similar to Compile, but the command.dat is notchanged by this operation. Intended to verify if the current script is error-free.
Compile – this is the most important feature. It translates the script into $-command-lines andinserts them into the command.dat. Reports error or success in the Log window.
Load and Save – as the names suggests this buttons serve to load scripts from external textfiles or to save the current content of the Script window to an external file. The Workflow
Editor saves automatically the content of the Script window into a special file always named
workflow_script.txt and load it back from there when opened later. Hence, it is not necessary
to make use at all of the Load and Save buttons. However, they are useful for archiving
intermediary or different versions of the script.
Use – this check-button will enable or disable the usage of the workflow script. Generally, it
is not good (but possible) to use the $-command editor and the Workflow Editor
simultaneously so one has to decide which of them is to be used. On demand, before
launching DIFFRACT™, DiffractGUI compiles the workflow script into the command.dat,
thus overwriting all hand-written $-command-lines eventually present here. To avoid this, theUse button must be unchecked, telling DiffractGUI this way to ignore it in the preparations
before the DIFFRACT™ launch. Another subtle difference is the dealing with length units: if
the Use button is checked, the $-commands-editor will NOT consider and convert length
units because it is the job of the Workflow Editor to do this. If the Use button is not checked,
the $-commands-editor will convert length units again, as if the Workflow Editor would not
be present.

19.1 The Script Editor
The Script window is a small text editor, with some advanced editing facilities. The text is
formatted and colorized automatically to indicate special meanings of the tokens.
Green letters indicate a comment area. Blue bold letters indicate that the token is a reserved
keyword of the workflow script language. Words displayed with red bold letters indicatethat they are placeholder-names of valid DIFFRACT™ commands present in thecommand.dat currently loaded in the Workbench of DiffractGUI. Finally, gray bold cursive
letters indicate that the word is a also a DIFFRACT™ command, but bound inside anenhanced variable name (see following chapters). Since it is not much room for confusions,the length units are displayed in same gray bold cursive letters.
A text block can be selected in the usual way, with the mouse cursor or by holding down the
SHIFT key and pressing any of the cursor-arrows of the keyboard. The full text can beselected with CTRL+A. A complete line can be selected with a simple click on the line
number displayed to the left of the editor window. The selected text can easily be moved by
dragging with the mouse (left-click inside the selected text area, hold down the mouse button
DiffractGUI User Guide

188

and move the mouse). To copy (instead of moving) the selected area to another location
within the script, hold down the CTRL key during the drag operation.
CTRL+C will copy the selected text to the clipboard, and CTRL+V will paste any existing
text from the clipboard at the current text-caret position, replacing the current selection, if
any.
The workflow script language accepts so-called enhanced variables, as a specifier forindividual parameters of DIFFRACT™ commands. They are build up from the name of a
DIFFRACT™ command, followed by a dot ‘.’, followed by the name of the parameter. For
example, “Beam_Source_1.Na” refers to the parameter “Na” of the “Beam_Source_1”
command. Since, for a given command, there may be very many different parameter names,
the script editor offers some help here. During typing of an enhanced variable, each time
when the dot ‘.’ is typed, the script editor pops up a combo box offering for selection one of
the available parameters, as illustrated below.

Alternatively, the combo box can be opened by placing the text caret immediately before thedot (between the end of the DIFFRACT™ command name and the dot) and by pressing
CTRL+SPACE on the keyboard.
A second help in building up enhanced variable names is offered by the Commands andParameters list boxes. To insert a new enhanced variable, place the text caret at the position
where the new enhanced variable shall be inserted then select in the Commands list thedesired command. The Parameters list will be populated with the parameters of thatcommand. Upon a left double-click performed over one of the parameters displayed in the
Parameters list, the complete enhanced variable name for that parameter is generated andinserted automatically in the script editor.
Finally, it should be remarked that when the Workflow Editor is closed, the content of thescript editor is always stored into a text file named workflow_script.txt inside the working
directory. This file is created new when necessary or simply overwritten if already existent.
At startup, the script editor is filled with the content of the workflow_script.txt, if found,
otherwise it is left empty. This functionality gives the freedom to use different scripts fordifferent working directories and one does not have to take care to save the current modified
script. However, one has to take care not to name any file manually as workflow_script.txt,
because the next closing of the Workflow Editor will overwrite automatically its contents.

DiffractGUI User Guide

189

19.2 The Workflow Scripting Language
The language recognized by the workflow compiler is a reduced subset of the common C
language. It has been chosen because of the widespread use of C, and also because it wasconsidered to be easy to learn and understandable for readers who have no knowledge of C.
The implemented workflow scripting language has the following reserved token-commands:{, }, }@, for, else, break, goto, if, continue, do, while, tags, until
Additionally, the compiler understands the following length units:

mm, um, nm, cm, waves
and it accepts the names of the DIFFRACT™ commands defined in the current
command.dat, for which the script applies. Such a DIFFRACT™ command must be typed asa stand-alone token followed by a semicolon. It is not allowed to use DIFFRACT™
commands as part of any other expression, but only as stand-alone statements.
First, some general rules:
A script consists of statements (like a=b+1;) and control structures (like if (a<b) c=3; etc.) If
not otherwise advised in this documentation, each statement must be terminated by asemicolon ‘;’. Multiple statements can be placed in one line, but usually the scripts are better
readable if each line contains only one or two statements. Furthermore, a statement can
extend over more then one line, if necessary.
The curly brace ‘{‘ denote the begin and ‘}’ the end of a block of statements.
The script must begin with ‘{‘ and end with the special token ‘}@’, which is the ‘end of
program’ marker. This token terminates the compilation, regardless of any other input textthat may follow it. The Workflow Editor framework checks if the first character is a ‘{‘ andthe last two characters are ‘}@’ if not, it adds them internally to the text before passing thescript to the compiler.

19.2.1

Variables and Constants

Constants are simple numbers, like 112, -0.123, 1.2e-5 etc. They can be followed by a length
unit (cm, mm, um, nm or waves), so for example ‘100 um’ is different to ‘100 cm’. It should
be noted that length units may be used only for constants and are not allowed for variables orother constructs.
There are two kind of variables: ordinary and enhanced. An ordinary variable is simply
specified by any alphanumeric name (the name must begin with a letter and should not be oneof the reserved keywords). Examples: I, j, k, Abc, var1, var2 etc.

DiffractGUI User Guide

190

The enhanced variables are placeholders for DIFFRACT™ command parameters. They are
specified ascommand_name . parameter_nameNotice the very important separating dot ‘.’ between the parameter name and the command
name. command_name must be the name of a valid DIFFRACT™ command andparameter_name must specify a valid parameter of the command. Please refer to the previous
description of the script editor for more information about how to generate this kind of valid
variables.
In contrast to other languages, ordinary variables need not to be declared before using.
Instead, they are allocated the first time when they appear in the script. Generally their value
will be initialized with zero.
It should be noted that all variables and constants are treated as floating point numbers andthis is the only data type accepted in the script.

19.2.2

Expressions, Functions and Statements

Expressions are build up from one or more variables or constants optionally embraced byround brackets and separated by operators. Valid operators are the algebraic operators +, -, *or / , the boolean operators && (logical AND), || (logical OR) or the comparison operators== (equal), <=, >=, <, > or != (not equal).
Inside expressions, the sin, cos, tan and exp functions may be used. With exception of thetags function, these are the only functions accepted by the Workflow Editor. The tags
function can appear in two forms:

tags( variable ) or tags( variable_1, variable_2 )The first form is the same as tags(variable, variable)
It is not allowed to use this function inside any expression, it must be used in a stand-alonestatement liketags( variable ); or tags( variable_1, variable_2 );and its only purpose is to determine the compiler to insert a $TAGS command in thecommand.dat at the location encountered in the script. The variables may be ordinary or
enhanced.
Statements are of several forms, but roughly, they can be divided into two groups:
assignments and control structures. The assignment statements have all the general form
variable_name assignment_operator expression ;where variable_name denotes an ordinary or enhanced variable, assignment_operator can beone of the =, +=, *=, -= or /= and expression represents any valid expression. Please notice
the mandatory terminating semicolon. The assignment operators need some extra
explanation. First, the operator = is obvious but it shall not be confused with the comparison== operator.

DiffractGUI User Guide191

To emphasize the difference, suppose the variable a has the value 3. Upon executing a=1, thevariable a will have the value 1, but after the execution of a==1, the variable a will still havethe value 3. Instead, the expression a==1 evaluates to false.
The other assignment operators are best explained by examples:a += expression ; is a replacement for
a -= expression ; is a replacement fora *= expression ; is a replacement for
a /= expression ; is a replacement fora = a + expression ;a = a - expression ;a = a * expression ;a = a / expression ;Wherever possible, it is recommended to use the short replacement form, because it generates
shorter sequences of $-command-lines.
There are two more assignment operators: ++ and --. When appended to a variable namethey will increase (++) or decrease (--) the variable value by 1. For example, if the variable a
has the value 3, then after executing a++; the variable will have the value 4 and after
executing a--; the variable will have the value 2.

19.2.3Control Structures

If – else conditional execution can be implemented in one of the following way:
if ( expression ) single_statement
if ( expression ) { if_block }if ( expression ) { if_block } else { else_block }If the expression evaluates to a value different of zero, then the if_block (or single_statement)
is executed, otherwise the else_block, if present.
Loops can be implemented in several ways:

while ( expression ) { while_block }First, the expression is evaluated. If it is not zero the while_block is executed and theexpression is re-evaluated. This sequence continues as long expression gives non-zero results.
If expression evaluates to zero the program execution jumps to the statement that follows thewhile_block.

do { while_block } while ( expression );This while-loop works similar here, but the while_block will be performed in any case at least
once.

DiffractGUI User Guide192

do { until_block } until ( expression );The until_block is executed as long as expression evaluates to zero. In other words,
until_block is performed until expression is not zero, but at least once.
The most complex and versatile statements are the for-loops:for ( assignment_1 ; expression ; assignment_2 ; ) single_statementfor ( assignment_1 ; expression ; assignment_2 ; ){ loop_block }Their functionality is best described and understood by the following pseudo-code:
1. execute assignment_1
2. evaluate expression
3. if expression is zero (this means false) then terminate loop and continue with the next
statement that follow the loop_block4. if expression is non-zero (this means true) then perform loop_block orsingle_statement
5. execute assignment_2
6. continue with step 2.
The following example illustrates a typical for-loop that performs the do_something block 4
times, with i=3,4,5 and 6.

for ( i = 3; i < 7; i = i + 1; ) { … do_something … }Within any of the loop structures described above, a break or continue statement is accepted.
A break will terminate immediately the loop and the program flow continues with thestatement that follows the loop. In contrast, the continue will execute immediate the next
loop iteration without terminating the currently executed loop block.
For completeness, the compiler recognizes a simple goto jump-statement:

goto label_name;where label_name represents an unique jump-target label build up from alphanumericcharacters. As in the case of variable-names, the first character must be a letter, the label
should be unique within the program and must not be one of the reserved keywords. A targetlabel can be specified by its name followed by a colon ‘:’ (instead of the typical semicolon).
Example of use:
… code …
if (a<4) goto mylabel;… more code …
mylabel:… even more code …

DiffractGUI User Guide193

19.3 Tutorial
The following short tutorial should help to set up and run simple workflow scripts. As a basic
startup, we consider a simple command.dat containing a hermite-gaussian BEAM and two
PLOT commands (one for the intensity and one for the phase), as listed below.
$________________________________________________________________________ ##Vacuum wavelength (mm): 0.000650000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Initial distribution: BEAM
(Length_Units: mm) #TYPE: UB/SG/GG/LG/HG/LD: HG#
BCX,BCY,POWER(mW): 0.00000000 0.00000000 1.0000000#
Order parameters (Nx,Ny): 4 5#
Base 1/e radii RX0,RY0: 1.8200000 2.1450000#
RA,THETA: 6.5000000 35.000000#
Aberrations: None#
Polarization RHO,ETA: 33.000000 22.000000#
NMAX,NMAY: 256 256#
LMAX,LMAY: 65.000000 65.000000#$#$________________________________________________________________________ ##Vacuum wavelength (nm): 650.000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Plot distribution: PLOT
(Length_Units: ) #Type: Intensity#
Logarithmic SCALE: 9.0000000#
Xmin,Xmax: -10000.000 10000.000#
Ymin,Ymax: -10000.000 10000.000#
Color or Gray-scale: C#
Z-component: N#
Save data files (Y/N): Y#
File identifier: 0#$#$________________________________________________________________________ ##Vacuum wavelength (nm): 650.000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Plot distribution: PLOT
(Length_Units: ) #Type: Phase#
Logarithmic SCALE: 4.0000000#
Xmin,Xmax: -10000.000 10000.000#
Ymin,Ymax: -10000.000 10000.000#
Color or Gray-scale: C#
Z-component: N#
Save data files (Y/N): Y#
File identifier: 1#

In this example, the requirement shall be to develop a workflow script which will generate a
set of plots for each combination of Nx = 0,1,3,4 and Ny=0,1,2,4 of the BEAM. Notice thatcombinations with Nx=2 or Ny=3 are omitted. Furthermore, the name each plot-file shall be
set to Ixnm.dat and Pxnm.dat, where n=Nx and m=Ny.
To start, open the Workflow Editor, ensure that the Use button is checked, and click on theInit button. Upon this, the script editor window will be filled with the following skeletontext:{
Beam_Source_1;
Plot_1;
Plot_2;}@

Notice that the Beam_Source_1, Plot_1 and Plot_2 are listed in the same order as they
appear in the command.dat (as displayed in the command list). This condition is importantand must be always fulfilled.

DiffractGUI User Guide

194

Modify the skeleton-script as follows (indentation, spaces and comments are optional):{for ( nx=0; nx<5; nx++; ) // begin of the loop over nx{
if ( nx == 2 ) continue; // skip nx = 2
for ( ny=0; ny<5; ny++; ) // begin of the loop over ny{
if ( ny == 3 ) continue; // skip ny = 3
Beam_Source_1.Nx = nx; // assign nx to the Nx parameter of Beam_Source_1
Beam_Source_1.Ny = ny; // assign ny to the Ny parameter of Beam_Source_1
Beam_Source_1;
Plot_1.FileID = 10*nx + ny; // assign proper FileID of Plot_1
Plot_1;
Plot_2.FileID = 10*nx + ny; // assign proper FileID of Plot_2
Plot_2;} // end of the ny-loop} // end of the nx-loop}@

Again, very important to notice that the order of the Beam_Source_1, Plot_1 and Plot_2
did not change. Click now on the Check button, to verify the script. If the syntax is error-free,the Log-window should display, among other information messages, the message----------

workflow-script check succeeded --------------,

otherwise, an error message is displayed and the verifying process stops.
At this point, the command.dat is still left unchanged. To insert $-command-lines in thecommand.dat, click on the Compile button. Similar to Check, the Log-window should display----------

workflow-script compilation succeeded --------------

if no errors are present. Now, the command.dat is ready to use, save it and launch
DIFFRACT™. Optionally, one could skip the Check, Compile and save steps and launch
DIFFRACT™ immediately after finishing the script. Before executing the launch command,
if the Use button is checked, DiffractGUI asks always to compile the workflow script if it
detects changes in command.dat or changes in the script. Just answer with a click on the Yes
button in the displayed message boxes. If compilation errors arise in this case, the launchcommand is canceled and an appropriate message box is shown.
It is possible to view and modify the generated $-command-lines and labels with the $commands-editor or with other editing facilities of DiffractGUI. However, almost every
modification may lead to unpredictable results, hence it is strongly advised NOT to modify ordelete any of the $-command-lines or line-labels created by the workflow script compiler.
For completeness, the following script lists the full command.dat as it is passed to
DIFFRACT™

$VALUE: 0$VALUE: 1$VALUE: 0$VALUE: 0$VALUE: 0$MAKE#06,ITEM1=#04,ITEM1:$VALUE: 0

DiffractGUI User Guide

#01
#03
#04
#05
#06
#
#11

195

$JUMP#12_IF#06,ITEM1.GE.: 5#$JUMP#14_IF#06,ITEM1.NE.: 2#$JUMP#13_IF#03,ITEM1.EQ.: 1#$VALUE: 0#14$MAKE#05,ITEM1=#04,ITEM1:#$VALUE: 0#15$JUMP#13_IF#05,ITEM1.GE.: 5#$JUMP#18_IF#05,ITEM1.NE.: 3#$JUMP#17_IF#03,ITEM1.EQ.: 1#$VALUE: 0#18$MAKE#09,ITEM1=#06,ITEM1:#$MAKE#09,ITEM2=#05,ITEM1:#$________________________________________________________________________ ##Vacuum wavelength (mm): 0.000650000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Initial distribution: BEAM
(Length_Units: mm) #TYPE: UB/SG/GG/LG/HG/LD: HG#
BCX,BCY,POWER(mW): 0.00000000 0.00000000 1.0000000#
Order parameters (Nx,Nx): 1 1#09
Base 1/e radii RX0,RY0: 1.8200000 2.1450000#
RA,THETA: 6.5000000 35.000000#
Aberrations: None#
Polarization RHO,ETA: 33.000000 22.000000#
NMAX,NMAY: 256 256#
LMAX,LMAY: 65.000000 65.000000#$VALUE: 10#19$MAKE#19,ITEM1=#04,ITEM1:#$INCREMENT#19,ITEM1...BY: 10#$MAKE#19,ITEM1*#06,ITEM1:#$MAKE#19,ITEM1+#05,ITEM1:#$MAKE#08,ITEM1=#19,ITEM1:#$________________________________________________________________________ ##Vacuum wavelength (nm): 650.000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Plot distribution: PLOT
(Length_Units: ) #Type: Intensity#
Logarithmic SCALE: 9.0000000#
Xmin,Xmax: -10000.000 10000.000#
Ymin,Ymax: -10000.000 10000.000#
Color or Gray-scale: C#
Z-component: N#
Save data files (Y/N): Y#
File identifier: 0#08$VALUE: 10#20$MAKE#20,ITEM1=#04,ITEM1:#$INCREMENT#20,ITEM1...BY: 10#$MAKE#20,ITEM1*#06,ITEM1:#$MAKE#20,ITEM1+#05,ITEM1:#$MAKE#07,ITEM1=#20,ITEM1:#$________________________________________________________________________ ##Vacuum wavelength (nm): 650.000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #Plot distribution: PLOT
(Length_Units: ) #Type: Phase#
Logarithmic SCALE: 4.0000000#
Xmin,Xmax: -10000.000 10000.000#
Ymin,Ymax: -10000.000 10000.000#
Color or Gray-scale: C#
Z-component: N#
Save data files (Y/N): Y#
File identifier: 1#07$________________________________________________________________________ #Vacuum wavelength (nm): 650.000000000
NVIRON: 1.0000000 #_________________________________________________________________________ #$VALUE: 0#17$INCREMENT#05,ITEM1...BY: 1#$JUMP#15_IF#03,ITEM1.EQ.: 1#$VALUE: 0#13$INCREMENT#06,ITEM1...BY: 1#$JUMP#11_IF#03,ITEM1.EQ.: 1#$VALUE: 0#12
End of session: QUIT#@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@The next simple example illustrates the use of metric units based on a command.dat withfollowing commands:{
Beam_Source_1;
SaveDistribution_1;

DiffractGUI User Guide

196

Read_Distribution_1;
Propagate_in_environment_1;
Plot_1;}@

The goal is to increase the propagation distance from a given start distance to an end distancein equidistant steps and to generate a plot output for each intermediary distance values.
The following script will achieve this:{// example for metric units// propagate a beam from z=5 mm to 10 mm in 1 mm steps// save a plot for each intermediary step
Beam_Source_1;
SaveDistribution_1;
Plot_1.FileID = 20; // plot-IDs shall start at 20
for (z=5 mm; z<=1 cm; z += 1000 um; ){ // beginn of the loop over z
if (Plot_1.FileID>99) break; // terminate loop if plot-ID exceeds limits
Read_Distribution_1;
Propagate_in_environment_1.distance = z; // assign distance
Propagate_in_environment_1;
Plot_1;
Plot_1.FileID++; // increment plot ID} // end of loop over z}@

This example will vary the propagation distance between 5 mm and 10 mm in 1 mm steps.
The first plot will have the FileID=20, the next 21, etc. until the end-distance of 10 mm isreached. Here, the last plot will have the FileID=25, but if the distance steps are madesmaller, the last FileID will increase and may exceed the value 99 (which is the highest ID
possible). To prevent this, and as an example for the break statement, the if-statement within
the loop will terminate when the ID exceeds 99.
Notice that through the script the units must not be one and the same as the unit used for theindividual DIFFRACT™ commands.
Also, very important to notice that the order of the DIFFRACT™ commands used in thisscript is the same as the order in which they are listed in the command.dat, which is a general
requirement for workflow scripts.
It is not necessary to use a for-loop statement to accomplish the task. The following scripts
shall illustrate the usage of the other loop-constructs. They work all identically to theprevious listed script, but they use different loop types. For a better readability, only the loops
are changed.
Script that uses a while-loop:{// example for metric units// propagate a beam from z=5 mm to 10 mm in 1 mm steps// save a plot for each intermediary step
Beam_Source_1;
SaveDistribution_1;
Plot_1.FileID = 20; // plot IDs shall start at 20z = 5 mm; // assign start distance to z
while ( z <= 1 cm ){ // beginn of the loop over z
if (Plot_1.FileID>99) break; // terminate loop if plot ID exceeds limits
Read_Distribution_1;
Propagate_in_environment_1.distance = z; // assign distanceDiffractGUI User Guide

197

Propagate_in_environment_1;
Plot_1;
Plot_1.FileID++; // increment plot ID
z += 1000 um; // increment z by 1 mm
} // end of loop over z}@

Script that uses a do-while-loop:{// example for metric units// propagate a beam from z=5 mm to 10 mm in 1 mm steps// save a plot for each intermediary step
Beam_Source_1;
SaveDistribution_1;
Plot_1.FileID = 20; // plot IDs shall start at 20z = 5 mm; // assign start distance to zdo{ // beginn of the loop over z
if (Plot_1.FileID>99) break; // terminate loop if plot ID exceeds limits
Read_Distribution_1;
Propagate_in_environment_1.distance = z; // assign distance
Propagate_in_environment_1;
Plot_1;
Plot_1.FileID++; // increment plot ID
z += 1000 um; // increment z by 1 mm
} // end of loop over z
while ( z <= 1 cm )}@Script that uses a do-until-loop:{// example for metric units// propagate a beam from z=5 mm to 10 mm in 1 mm steps// save a plot for each intermediary step
Beam_Source_1;
SaveDistribution_1;
Plot_1.FileID = 20; // plot IDs shall start at 20z = 5 mm; // assign start distance to zdo{ // beginn of the loop over z
if (Plot_1.FileID>99) break; // terminate loop if plot ID exceeds limits
Read_Distribution_1;
Propagate_in_environment_1.distance = z; // assign distance
Propagate_in_environment_1;
Plot_1;
Plot_1.FileID++; // increment plot ID
z += 1000 um; // increment z by 1 mm
} // end of loop over z
until ( z > 1 cm )}@The next listing illustrates the usage of the && - operator (logical AND) inside the boolean
expression of the while-statement (underlined):{// example for metric units// propagate a beam from z=5 mm to 10 mm in 1 mm steps// save a plot for each intermediary step
Beam_Source_1;
SaveDistribution_1;
Plot_1.FileID = 20; // plot IDs shall start at 20z = 5 mm; // assign start distance to z
while ( ( z <= 1 cm ) && ( Plot_1.FileID <= 99 ) ){ // beginn of the loop over z
Read_Distribution_1;
Propagate_in_environment_1.distance = z; // assign distanceDiffractGUI User Guide

198

Propagate_in_environment_1;
Plot_1;
Plot_1.FileID++; // increment plot ID
z += 1000 um; // increment z by 1 mm
} // end of loop over z}@

Notice that the extended Boolean expression makes obsolete the if-break line used in theprevious scripts within the loop, so it can be removed without lack of functionality.

DiffractGUI User Guide

199