ASAP Reference Guide - Breault Research Organization, Inc.
12.07.2015 • Views
Share Embed Flag

ASAP Reference Guide - Breault Research Organization, Inc.

ASAP Reference Guide - Breault Research Organization, Inc.

ASAP Reference Guide - Breault Research Organization, Inc.

SHOW MORE
SHOW LESS
ePAPER READ
DOWNLOAD ePAPER
breault.com

You also want an ePaper? Increase the reach of your titles

YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.

START NOW

<strong>ASAP</strong> <strong>Reference</strong> <strong>Guide</strong>

<strong>ASAP</strong> | Contents | 2Contents<strong>ASAP</strong> <strong>Reference</strong> <strong>Guide</strong> Introduction................................................................... 13Achieving Optimal Performance in <strong>ASAP</strong>...........................................................14Setting the Working Directory..............................................................................15Commands and Macros (A).................................................................................. 16a,b,c... (<strong>ASAP</strong> Command Argument).................................................................................................................16ABEL (<strong>ASAP</strong> Command).................................................................................................................................. 17ABERRATIONS (<strong>ASAP</strong> Command).................................................................................................................17ABG (<strong>ASAP</strong> Command).................................................................................................................................... 19$ABORT (<strong>ASAP</strong> Macro)................................................................................................................................... 20ABSORB (<strong>ASAP</strong> Command Argument)........................................................................................................... 21ACCURACY (<strong>ASAP</strong> Command)...................................................................................................................... 21ACTIVITY (<strong>ASAP</strong> Command Argument)........................................................................................................ 22AFOCAL (<strong>ASAP</strong> Command).............................................................................................................................23ALIGN (<strong>ASAP</strong> Command)................................................................................................................................ 24ALLOWED (<strong>ASAP</strong> Command).........................................................................................................................25ALTER (Edge Modifier) (<strong>ASAP</strong> Command).................................................................................................... 26ALTER (Lens Modifier) (<strong>ASAP</strong> Command).....................................................................................................27ALTER (Surface Modifier) (<strong>ASAP</strong> Command)................................................................................................ 28ANALYZE (<strong>ASAP</strong> Command)..........................................................................................................................29ANGLES (<strong>ASAP</strong> Command Argument)........................................................................................................... 29ANGLES (<strong>ASAP</strong> Command).............................................................................................................................30APPEND (<strong>ASAP</strong> Command)............................................................................................................................. 30ARC (<strong>ASAP</strong> Command).................................................................................................................................... 31$ARGS (<strong>ASAP</strong> Macro)...................................................................................................................................... 31ARRAY (<strong>ASAP</strong> Command)...............................................................................................................................32ARRAY NONLINEAR (<strong>ASAP</strong> Command)...................................................................................................... 33ARROWS (<strong>ASAP</strong> Command)............................................................................................................................35ASCALE (<strong>ASAP</strong> Command)............................................................................................................................. 35$ASK (<strong>ASAP</strong> Macro).........................................................................................................................................36ASYM (<strong>ASAP</strong> Command)................................................................................................................................. 36AVERAGE (<strong>ASAP</strong> Command)..........................................................................................................................37AXICONIC (<strong>ASAP</strong> Command)......................................................................................................................... 38AXIS (<strong>ASAP</strong> Command)................................................................................................................................... 39Commands and Macros (B)...................................................................................41BEAMS (<strong>ASAP</strong> Command)...............................................................................................................................41$BEEP (<strong>ASAP</strong> Macro)....................................................................................................................................... 41BEND (<strong>ASAP</strong> Command)..................................................................................................................................42BEZIER (<strong>ASAP</strong> Command)...............................................................................................................................42BIC (<strong>ASAP</strong> Command)......................................................................................................................................43BICONIC (<strong>ASAP</strong> Command)............................................................................................................................ 44BILATERAL (<strong>ASAP</strong> Command)...................................................................................................................... 45

<strong>ASAP</strong> | Contents | 3BIN (<strong>ASAP</strong> Command)......................................................................................................................................46BOUNDS (<strong>ASAP</strong> Command)............................................................................................................................ 46BRANCH (<strong>ASAP</strong> Command)............................................................................................................................47BSDFDATA (<strong>ASAP</strong> Command)........................................................................................................................48Commands and Macros (C).................................................................................. 52CADEXPORT (<strong>ASAP</strong> Command).....................................................................................................................52CARTOVAL (<strong>ASAP</strong> Command).......................................................................................................................53$CASE (<strong>ASAP</strong> Macro).......................................................................................................................................54CHARACTER (<strong>ASAP</strong> Command).................................................................................................................... 54CHROMATICITY (<strong>ASAP</strong> Command).............................................................................................................. 55SOM Option Matrix for CIE-CHROMATICITY Commands............................................................... 57CIE (<strong>ASAP</strong> Command)...................................................................................................................................... 58SOM Option Matrix for CIE-CHROMATICITY Commands............................................................... 59$CLEAR (<strong>ASAP</strong> Macro)....................................................................................................................................60CLIP (<strong>ASAP</strong> Command Argument).................................................................................................................. 60CLIP (<strong>ASAP</strong> Command)....................................................................................................................................60COARSEN (<strong>ASAP</strong> Command).......................................................................................................................... 62COATINGS LAYERS (<strong>ASAP</strong> Command)........................................................................................................62COATINGS MODELS (<strong>ASAP</strong> Command).......................................................................................................63COATINGS PROPERTIES (<strong>ASAP</strong> Command)................................................................................................65COLLECTION (<strong>ASAP</strong> Command)....................................................................................................................65COLORS (<strong>ASAP</strong> Command Argument)........................................................................................................... 66COLORS (<strong>ASAP</strong> Command).............................................................................................................................68COMBINE (<strong>ASAP</strong> Command).......................................................................................................................... 69COMPOSITE (Edge Modifier) (<strong>ASAP</strong> Command)...........................................................................................70COMPOSITE (Lens Modifier) (<strong>ASAP</strong> Command)........................................................................................... 71CONDUIT (<strong>ASAP</strong> Command)...........................................................................................................................71CONIC (<strong>ASAP</strong> Command)................................................................................................................................ 72CONSIDER (<strong>ASAP</strong> Command).........................................................................................................................73CONTOUR (<strong>ASAP</strong> Command)......................................................................................................................... 74$COPY (<strong>ASAP</strong> Macro)...................................................................................................................................... 75CORNER (<strong>ASAP</strong> Command)............................................................................................................................ 75CPE (<strong>ASAP</strong> Command)..................................................................................................................................... 76CRYSTAL (<strong>ASAP</strong> Command Argument)......................................................................................................... 78CUTOFF (<strong>ASAP</strong> Command)............................................................................................................................. 78CVF (<strong>ASAP</strong> Command).....................................................................................................................................79Commands and Macros (D).................................................................................. 81$DATIM (<strong>ASAP</strong> Macro)....................................................................................................................................81$DBG (<strong>ASAP</strong> Macro)........................................................................................................................................ 81DECOMPOSE (<strong>ASAP</strong> Command).................................................................................................................... 81DEFORM (<strong>ASAP</strong> Command)............................................................................................................................83DIMENSIONS (<strong>ASAP</strong> Command).................................................................................................................... 84DIRECTIONAL (<strong>ASAP</strong> Command)..................................................................................................................85$DISP (<strong>ASAP</strong> Macro)........................................................................................................................................ 85DISPLAY (<strong>ASAP</strong> Command)............................................................................................................................86DMAP (<strong>ASAP</strong> Command)................................................................................................................................. 88$DO (<strong>ASAP</strong> Macro)...........................................................................................................................................88DOMACROS (<strong>ASAP</strong> Command)...................................................................................................................... 89DOME (<strong>ASAP</strong> Command).................................................................................................................................90DOPL (<strong>ASAP</strong> Command).................................................................................................................................. 90DOUBLET (<strong>ASAP</strong> Command).......................................................................................................................... 91DRAWING (<strong>ASAP</strong> Command)......................................................................................................................... 92

<strong>ASAP</strong> | Contents | 4DUMP (<strong>ASAP</strong> Command)................................................................................................................................. 93Commands and Macros (E)...................................................................................94$ECHO (<strong>ASAP</strong> Macro)......................................................................................................................................94EDGES/CURVES (<strong>ASAP</strong> Command)...............................................................................................................94$EDIT (<strong>ASAP</strong> Macro)........................................................................................................................................94ELLIPSE (<strong>ASAP</strong> Command)............................................................................................................................. 95ELLIPSOID (<strong>ASAP</strong> Command)........................................................................................................................ 96EMITTING (<strong>ASAP</strong> Command)......................................................................................................................... 97EMITTING BOX/SPHEROID (<strong>ASAP</strong> Command)........................................................................................... 98EMITTING CONE/PYRAMID (<strong>ASAP</strong> Command)..........................................................................................98EMITTING DATA (<strong>ASAP</strong> Command).............................................................................................................99EMITTING DISK/RECTANGLE (<strong>ASAP</strong> Command).................................................................................... 101EMITTING ENTITY or OBJECT (<strong>ASAP</strong> Command)................................................................................... 102EMITTING EULUMDAT (<strong>ASAP</strong> Command)................................................................................................103EMITTING FILAMENT (<strong>ASAP</strong> Command)..................................................................................................103EMITTING HELIX (<strong>ASAP</strong> Command).......................................................................................................... 104EMITTING IES (<strong>ASAP</strong> Command)................................................................................................................ 105EMITTING RAYS (<strong>ASAP</strong> Command)........................................................................................................... 106ENCLOSED (<strong>ASAP</strong> Command)......................................................................................................................107END (<strong>ASAP</strong> Command).................................................................................................................................. 107ENTITIES (<strong>ASAP</strong> Command)......................................................................................................................... 108$ERR (<strong>ASAP</strong> Macro)....................................................................................................................................... 109EULUMDATFILE (<strong>ASAP</strong> Command)............................................................................................................109$EVAL (<strong>ASAP</strong> Macro).................................................................................................................................... 110$EXIT (<strong>ASAP</strong> Macro)......................................................................................................................................111$EXP (<strong>ASAP</strong> Macro)....................................................................................................................................... 112EXPLICIT (<strong>ASAP</strong> Command).........................................................................................................................112EXPLODE (<strong>ASAP</strong> Command)........................................................................................................................ 113EXTEND (<strong>ASAP</strong> Command)...........................................................................................................................114EXTREMES (<strong>ASAP</strong> Command)......................................................................................................................114Commands and Macros (F).................................................................................116FACETS (<strong>ASAP</strong> Command)............................................................................................................................116$FAST (<strong>ASAP</strong> Macro)..................................................................................................................................... 116$FCN (<strong>ASAP</strong> Macro)....................................................................................................................................... 117$FF (<strong>ASAP</strong> Macro).......................................................................................................................................... 118FFAD (<strong>ASAP</strong> Command)................................................................................................................................ 118FFT (<strong>ASAP</strong> Command)....................................................................................................................................119FIELD (<strong>ASAP</strong> Command)............................................................................................................................... 120FIELDBPM (<strong>ASAP</strong> Command).......................................................................................................................124FIELDSUM (<strong>ASAP</strong> Command).......................................................................................................................126FITTED (<strong>ASAP</strong> Command).............................................................................................................................127FLUX (<strong>ASAP</strong> Command)................................................................................................................................ 129FMAP (<strong>ASAP</strong> Command)................................................................................................................................129FOCUS (<strong>ASAP</strong> Command)..............................................................................................................................130FOLD (<strong>ASAP</strong> Command)................................................................................................................................ 132FORM (<strong>ASAP</strong> Command)............................................................................................................................... 133FRESNEL (<strong>ASAP</strong> Command)......................................................................................................................... 133FTSIZE (<strong>ASAP</strong> Command)..............................................................................................................................135Commands and Macros (G)................................................................................ 136GAUSSIAN (<strong>ASAP</strong> Command)...................................................................................................................... 136

<strong>ASAP</strong> | Contents | 5GENERAL (<strong>ASAP</strong> Command)........................................................................................................................ 137GET (<strong>ASAP</strong> Command)...................................................................................................................................140$GO (<strong>ASAP</strong> Macro)......................................................................................................................................... 142$GRAB (<strong>ASAP</strong> Macro)....................................................................................................................................143GRAPH (<strong>ASAP</strong> Command)............................................................................................................................. 143GRID DATA (<strong>ASAP</strong> Command).................................................................................................................... 144GRID ELLIPTIC (<strong>ASAP</strong> Command).............................................................................................................. 145GRID HEX (<strong>ASAP</strong> Command)....................................................................................................................... 146GRID OBJECT (<strong>ASAP</strong> Command).................................................................................................................147GRID POLAR (<strong>ASAP</strong> Command).................................................................................................................. 148GRID RECT (<strong>ASAP</strong> Command)..................................................................................................................... 149GRID WINDOW (<strong>ASAP</strong> Command).............................................................................................................. 150GRIN (<strong>ASAP</strong> Command Argument)............................................................................................................... 151GROUP (<strong>ASAP</strong> Command)............................................................................................................................. 151$GUI (<strong>ASAP</strong> Macro)........................................................................................................................................152GUM (<strong>ASAP</strong> Command)................................................................................................................................. 156Commands and Macros (H)................................................................................ 159HALT (<strong>ASAP</strong> Command)................................................................................................................................159HARVEY (<strong>ASAP</strong> Command).......................................................................................................................... 160HEADER (<strong>ASAP</strong> Command).......................................................................................................................... 161HELIX (<strong>ASAP</strong> Command)...............................................................................................................................162$HELP (<strong>ASAP</strong> Macro).....................................................................................................................................163HISTOGRAM (<strong>ASAP</strong> Command)...................................................................................................................163HISTORY (<strong>ASAP</strong> Command)......................................................................................................................... 164HORN (<strong>ASAP</strong> Command)............................................................................................................................... 168Commands and Macros (I)..................................................................................170IDEAL (<strong>ASAP</strong> Command)...............................................................................................................................170IESFILE (<strong>ASAP</strong> Command)............................................................................................................................ 171$IF (<strong>ASAP</strong> Macro)........................................................................................................................................... 173$IF THEN (<strong>ASAP</strong> Macro)............................................................................................................................... 174IMAGE Curve/Edge (<strong>ASAP</strong> Command)......................................................................................................... 175IMAGE (Global Point) (<strong>ASAP</strong> Command)..................................................................................................... 175IMAGE (Ray Positions) (<strong>ASAP</strong> Command)................................................................................................... 176IMMERSE (<strong>ASAP</strong> Command)........................................................................................................................ 176IMPORT (<strong>ASAP</strong> Command)............................................................................................................................177INTERFACE (<strong>ASAP</strong> Command).....................................................................................................................178INTERFACE POLARIZATION (Polarization Modifiers) (<strong>ASAP</strong> Command)...............................................179INTERFACE REPEAT (<strong>ASAP</strong> Command).................................................................................................... 181INVERT (<strong>ASAP</strong> Command)............................................................................................................................182$IO (<strong>ASAP</strong> Macro)...........................................................................................................................................182IRRADIANCE (<strong>ASAP</strong> Command).................................................................................................................. 184ISOMETRIC (<strong>ASAP</strong> Command)..................................................................................................................... 185$ITER (<strong>ASAP</strong> Macro)......................................................................................................................................186Commands and Macros (JKL)............................................................................188JONES (<strong>ASAP</strong> Command)...............................................................................................................................188KCORRELATION (<strong>ASAP</strong> Command)............................................................................................................189LAMBERTIAN (<strong>ASAP</strong> Command).................................................................................................................190LCC (<strong>ASAP</strong> Command)...................................................................................................................................190$LEAVE (<strong>ASAP</strong> Macro)..................................................................................................................................193LENSES (<strong>ASAP</strong> Command)............................................................................................................................193

<strong>ASAP</strong> | Contents | 6LEVEL (<strong>ASAP</strong> Command)..............................................................................................................................194LIGHTS (<strong>ASAP</strong> Command)............................................................................................................................ 195LIMITS (<strong>ASAP</strong> Command)............................................................................................................................. 195LINE (<strong>ASAP</strong> Command)..................................................................................................................................197LIST (<strong>ASAP</strong> Command).................................................................................................................................. 197LIST ELLIPSE (<strong>ASAP</strong> Command)................................................................................................................. 198LIST INTEGER (<strong>ASAP</strong> Command)................................................................................................................199LIST (Parabasal Ray Data) (<strong>ASAP</strong> Command)...............................................................................................199LIST RAYS (<strong>ASAP</strong> Command)...................................................................................................................... 199$LOC (<strong>ASAP</strong> Macro).......................................................................................................................................200LOCAL (<strong>ASAP</strong> Command)............................................................................................................................. 201LSQFIT (<strong>ASAP</strong> Command)............................................................................................................................. 203Commands and Macros (M)................................................................................204MANGIN (<strong>ASAP</strong> Command).......................................................................................................................... 204MAP (<strong>ASAP</strong> Command)..................................................................................................................................205MATRIX (<strong>ASAP</strong> Command)...........................................................................................................................206MEDIA (<strong>ASAP</strong> Command)..............................................................................................................................207MEDIA Command Coefficients...........................................................................................................209MEDIA ABSORB (<strong>ASAP</strong> Command)............................................................................................................ 210MEDIA BIAXIAL (<strong>ASAP</strong> Command)............................................................................................................211MEDIA CRYSTAL (<strong>ASAP</strong> Command).......................................................................................................... 212MEDIA GRIN (<strong>ASAP</strong> Command).................................................................................................................. 213MEDIA SCATTER (<strong>ASAP</strong> Command)...........................................................................................................215$MENU (<strong>ASAP</strong> Macro)................................................................................................................................... 216MESH (<strong>ASAP</strong> Command)................................................................................................................................216MICROSTRUCTURE (<strong>ASAP</strong> Command)...................................................................................................... 216MINIMIZE (<strong>ASAP</strong> Command)........................................................................................................................218MINMAX (<strong>ASAP</strong> Command Argument)........................................................................................................ 220MIRROR (<strong>ASAP</strong> Command)...........................................................................................................................220MISSED (<strong>ASAP</strong> Command)............................................................................................................................221MODEL (<strong>ASAP</strong> Command Argument)........................................................................................................... 221MODELS (<strong>ASAP</strong> Command).......................................................................................................................... 222MODIFY (<strong>ASAP</strong> Command)...........................................................................................................................223MOVE (<strong>ASAP</strong> Command)...............................................................................................................................224MOVE PARABASALS (<strong>ASAP</strong> Command)....................................................................................................225MOVE TO FOCI (<strong>ASAP</strong> Command)..............................................................................................................226MOVE TO PLANE (<strong>ASAP</strong> Command).......................................................................................................... 226MOVE TO POINT (<strong>ASAP</strong> Command)........................................................................................................... 226MOVE TO SPHERE (<strong>ASAP</strong> Command)........................................................................................................ 227$MSGS (<strong>ASAP</strong> Macro)....................................................................................................................................227MUELLER (<strong>ASAP</strong> Command)........................................................................................................................227MULTIPLE (<strong>ASAP</strong> Command).......................................................................................................................229Commands and Macros (N-O)............................................................................ 231$NEXT (<strong>ASAP</strong> Macro).................................................................................................................................... 231NONLINEAR (<strong>ASAP</strong> Command)................................................................................................................... 231NORMALIZE (<strong>ASAP</strong> Command)................................................................................................................... 234NUMBERS (<strong>ASAP</strong> Command)....................................................................................................................... 234OBJECT (<strong>ASAP</strong> Command)............................................................................................................................235OBLIQUE (<strong>ASAP</strong> Command)......................................................................................................................... 236OFFSET (<strong>ASAP</strong> Command)............................................................................................................................ 237OPDMAP (<strong>ASAP</strong> Command)..........................................................................................................................237OPTICAL (<strong>ASAP</strong> Command)..........................................................................................................................238

<strong>ASAP</strong> | Contents | 7OVAL (<strong>ASAP</strong> Command)................................................................................................................................240OVERLAY (<strong>ASAP</strong> Command Argument)...................................................................................................... 240Commands and Macros (P).................................................................................242$PAGE (<strong>ASAP</strong> Macro).................................................................................................................................... 242PARABASAL (<strong>ASAP</strong> Command)...................................................................................................................242PARAMETERIZE (<strong>ASAP</strong> Command)............................................................................................................ 243PARTICLES (<strong>ASAP</strong> Command)..................................................................................................................... 244PATCHES (<strong>ASAP</strong> Command).........................................................................................................................245$PATH (<strong>ASAP</strong> Macro).................................................................................................................................... 246PATHS (<strong>ASAP</strong> Command)..............................................................................................................................246PERFECT (<strong>ASAP</strong> Command)..........................................................................................................................248PHYSICAL (<strong>ASAP</strong> Command)....................................................................................................................... 249PICTURE (<strong>ASAP</strong> Command).......................................................................................................................... 249PIXELS (<strong>ASAP</strong> Command Argument)............................................................................................................250PIXELS (<strong>ASAP</strong> Command)............................................................................................................................. 250PLACE (CURve/edge) (<strong>ASAP</strong> Command)......................................................................................................251PLACE (Global Coordinate) (<strong>ASAP</strong> Command)............................................................................................ 251PLACE (Relative to Entity) (<strong>ASAP</strong> Command)..............................................................................................252PLANE (<strong>ASAP</strong> Command)..............................................................................................................................253PLANE NORMAL (<strong>ASAP</strong> Command)........................................................................................................... 254PLANE POINTS (<strong>ASAP</strong> Command)...............................................................................................................254$PLAY (<strong>ASAP</strong> Macro).................................................................................................................................... 255Plotting Commands...........................................................................................................................................255PLOT3D (<strong>ASAP</strong> Command)............................................................................................................................256PLOT BEAMS (<strong>ASAP</strong> Command)..................................................................................................................257PLOT CURVES (<strong>ASAP</strong> Command)................................................................................................................257PLOT EDGES (<strong>ASAP</strong> Command).................................................................................................................. 258PLOT ENTITIES (<strong>ASAP</strong> Command)..............................................................................................................259PLOT FACETS (<strong>ASAP</strong> Command).................................................................................................................259PLOT LENSES (<strong>ASAP</strong> Command).................................................................................................................261PLOT LIMITS (<strong>ASAP</strong> Command).................................................................................................................. 262PLOT LOCAL (<strong>ASAP</strong> Command).................................................................................................................. 262PLOT MESHES (<strong>ASAP</strong> Command)................................................................................................................263PLOT POLARIZATION (<strong>ASAP</strong> Command).................................................................................................. 264PLOT RAYS (<strong>ASAP</strong> Command).....................................................................................................................265PLOT SURFACES (<strong>ASAP</strong> Command)........................................................................................................... 265PLOT (<strong>ASAP</strong> Command Argument)............................................................................................................... 266$PLOT (<strong>ASAP</strong> Macro).....................................................................................................................................267POINTS (2D) (<strong>ASAP</strong> Command)....................................................................................................................267POINTS (3D) (<strong>ASAP</strong> Command)....................................................................................................................268POLARIZ (<strong>ASAP</strong> Command)..........................................................................................................................270POLARIZ K (<strong>Reference</strong> Ray Direction) (<strong>ASAP</strong> Command)..........................................................................271POLARIZ MODE (<strong>ASAP</strong> Command).............................................................................................................272POLARIZ (Polarization Vector) (<strong>ASAP</strong> Command).......................................................................................272POLARIZ RANDOM (<strong>ASAP</strong> Command).......................................................................................................273POLARIZ TREF (Transverse <strong>Reference</strong> Direction) (<strong>ASAP</strong> Command)........................................................ 274POLYNOMIAL/TRINOMIAL/BINOMIAL (<strong>ASAP</strong> Command)....................................................................275PostScript File Utility (PSCRIP) (<strong>ASAP</strong> Command)...................................................................................... 277PRINT (<strong>ASAP</strong> Command)............................................................................................................................... 278PRINT (Polarization Models) (<strong>ASAP</strong> Command)...........................................................................................282PROFILES (<strong>ASAP</strong> Command)........................................................................................................................ 283PUT (<strong>ASAP</strong> Command)................................................................................................................................... 284

<strong>ASAP</strong> | Contents | 8Commands and Macros (R)................................................................................ 287RACETRACK (<strong>ASAP</strong> Command)...................................................................................................................287RADIAL (<strong>ASAP</strong> Command)............................................................................................................................287RADIANT (<strong>ASAP</strong> Command).........................................................................................................................288$RAN (<strong>ASAP</strong> Macro)...................................................................................................................................... 290RANGE (<strong>ASAP</strong> Command).............................................................................................................................290RAWDATA (<strong>ASAP</strong> Command)...................................................................................................................... 291RAY (<strong>ASAP</strong> Command).................................................................................................................................. 291RAYS (<strong>ASAP</strong> Command)................................................................................................................................293RAYSET (<strong>ASAP</strong> Command)........................................................................................................................... 293$READ (<strong>ASAP</strong> Macro)....................................................................................................................................295RECTANGLE (<strong>ASAP</strong> Command)...................................................................................................................295REDEFINE (<strong>ASAP</strong> Command)....................................................................................................................... 296REDUCE (<strong>ASAP</strong> Command)...........................................................................................................................297$REG (<strong>ASAP</strong> Macro).......................................................................................................................................297REMOVE (<strong>ASAP</strong> Command)..........................................................................................................................298RENDER (<strong>ASAP</strong> Command)...........................................................................................................................298RENORM (<strong>ASAP</strong> Command)..........................................................................................................................299REPEAT (<strong>ASAP</strong> Command)............................................................................................................................300REPLICATE (<strong>ASAP</strong> Command)..................................................................................................................... 301REPLOT (<strong>ASAP</strong> Command)............................................................................................................................301RESET (<strong>ASAP</strong> Command).............................................................................................................................. 302RESTRICT (<strong>ASAP</strong> Command)........................................................................................................................303RETURN (<strong>ASAP</strong> Command)...........................................................................................................................303REVERSE (<strong>ASAP</strong> Command).........................................................................................................................303REVOLUTION (<strong>ASAP</strong> Command).................................................................................................................304REVOLUTION (Fitted) (<strong>ASAP</strong> Command)....................................................................................................305RIGHT (<strong>ASAP</strong> Command).............................................................................................................................. 305RMS (<strong>ASAP</strong> Command).................................................................................................................................. 306ROOF (<strong>ASAP</strong> Command)................................................................................................................................307ROTATE (<strong>ASAP</strong> Command)...........................................................................................................................307ROUGHNESS (<strong>ASAP</strong> Command)...................................................................................................................308ROUNDED (<strong>ASAP</strong> Command)....................................................................................................................... 310RPM (<strong>ASAP</strong> Command).................................................................................................................................. 311RRM (<strong>ASAP</strong> Command)..................................................................................................................................312Commands and Macros (S)................................................................................. 315SAG (<strong>ASAP</strong> Command)...................................................................................................................................315SAMPLED (<strong>ASAP</strong> Command)........................................................................................................................ 316SAMPLED (Cylindrical) (<strong>ASAP</strong> Command).................................................................................................. 318SAVE (<strong>ASAP</strong> Command)................................................................................................................................ 319SAWTOOTH (<strong>ASAP</strong> Command).................................................................................................................... 319SCALE (<strong>ASAP</strong> Command)..............................................................................................................................320SCALE FROM (<strong>ASAP</strong> Command)................................................................................................................. 321SCATTER (<strong>ASAP</strong> Command Argument)....................................................................................................... 322SCATTER RANDOM or MODEL (<strong>ASAP</strong> Command).................................................................................. 322SCATTER REPEAT (<strong>ASAP</strong> Command).........................................................................................................323SCATTER RMS/BSDF (<strong>ASAP</strong> Command).................................................................................................... 324$SCR (<strong>ASAP</strong> Macro)....................................................................................................................................... 325SEARCH (<strong>ASAP</strong> Command)...........................................................................................................................326$SEARCH (<strong>ASAP</strong> Macro)............................................................................................................................... 328SECTION (<strong>ASAP</strong> Command)..........................................................................................................................328SEED (<strong>ASAP</strong> Command).................................................................................................................................329

<strong>ASAP</strong> | Contents | 9SEGMENTS (<strong>ASAP</strong> Command)......................................................................................................................330SELECT (<strong>ASAP</strong> Command)............................................................................................................................ 330SEQUENCE (<strong>ASAP</strong> Command)......................................................................................................................333SET (<strong>ASAP</strong> Command)................................................................................................................................... 334SHAPE (<strong>ASAP</strong> Command)..............................................................................................................................335SHIFT (<strong>ASAP</strong> Command)................................................................................................................................337SHOW (<strong>ASAP</strong> Command)...............................................................................................................................338$SHOW (<strong>ASAP</strong> Macro)................................................................................................................................... 339SINGLET (<strong>ASAP</strong> Command).......................................................................................................................... 339SKEW (<strong>ASAP</strong> Command)............................................................................................................................... 340SMOOTH (<strong>ASAP</strong> Command)..........................................................................................................................341SOLID (<strong>ASAP</strong> Command)...............................................................................................................................341SOURCE (<strong>ASAP</strong> Command)...........................................................................................................................342SOURCE POLYCHROMATIC (<strong>ASAP</strong> Command)....................................................................................... 343SOURCE WAVEFUNC (<strong>ASAP</strong> Command)................................................................................................... 346SPECTRUM (<strong>ASAP</strong> Command)......................................................................................................................347SPLINE, EXPLICIT 2D (<strong>ASAP</strong> Command)................................................................................................... 348SPLINE, GENERAL 3D (<strong>ASAP</strong> Command).................................................................................................. 348SPLIT (<strong>ASAP</strong> Command)................................................................................................................................349SPOTS (<strong>ASAP</strong> Command)...............................................................................................................................351SPREAD (<strong>ASAP</strong> Command)........................................................................................................................... 353$STAMP (<strong>ASAP</strong> Macro)..................................................................................................................................354STATS (<strong>ASAP</strong> Command).............................................................................................................................. 355STATS TRACE (<strong>ASAP</strong> Command)................................................................................................................ 356$STO/$RCL/&STO (<strong>ASAP</strong> Macro).................................................................................................................356STORE (<strong>ASAP</strong> Command)..............................................................................................................................357SUBSET (<strong>ASAP</strong> Command)............................................................................................................................357SUM (<strong>ASAP</strong> Command)..................................................................................................................................358SUPERCONIC (<strong>ASAP</strong> Command)..................................................................................................................358SURFACES/FUNCTIONS (<strong>ASAP</strong> Command)............................................................................................... 359SWEEP (<strong>ASAP</strong> Command)..............................................................................................................................360$SYS (<strong>ASAP</strong> Macro)....................................................................................................................................... 361SYSTEM (<strong>ASAP</strong> Command)...........................................................................................................................361Commands and Macros (T).................................................................................363TABLE (<strong>ASAP</strong> Command)..............................................................................................................................363TELESCOPE (<strong>ASAP</strong> Command).................................................................................................................... 363TERRAIN (<strong>ASAP</strong> Command)......................................................................................................................... 364TEST (<strong>ASAP</strong> Command)................................................................................................................................. 365TEXT (<strong>ASAP</strong> Command Argument)...............................................................................................................366TEXTFILE (<strong>ASAP</strong> Command)........................................................................................................................ 367THRESHOLD (<strong>ASAP</strong> Command)...................................................................................................................369$TIC (<strong>ASAP</strong> Macro)........................................................................................................................................ 369TITLE (<strong>ASAP</strong> Command)................................................................................................................................370TORUS (<strong>ASAP</strong> Command)..............................................................................................................................370TOWARDS (<strong>ASAP</strong> Command).......................................................................................................................371TRACE (<strong>ASAP</strong> Command)..............................................................................................................................373TRANSPOSE (<strong>ASAP</strong> Command)....................................................................................................................375TREE (<strong>ASAP</strong> Command).................................................................................................................................375TUBE (<strong>ASAP</strong> Command)................................................................................................................................ 376Commands and Macros (U)................................................................................ 378UNITS (<strong>ASAP</strong> Command)...............................................................................................................................378$UNVAR (<strong>ASAP</strong> Macro).................................................................................................................................379

<strong>ASAP</strong> | Contents | 10UPDATE (<strong>ASAP</strong> Command)...........................................................................................................................379USERAPOD (<strong>ASAP</strong> Command)......................................................................................................................379USERAPOD ANGLES (<strong>ASAP</strong> Command).....................................................................................................381USERAPOD BOTH (<strong>ASAP</strong> Command)......................................................................................................... 382USERBSDF (<strong>ASAP</strong> Command)...................................................................................................................... 384USERCURVE (<strong>ASAP</strong> Command)...................................................................................................................386USERFUNC (<strong>ASAP</strong> Command)......................................................................................................................387USERSAG (<strong>ASAP</strong> Command)........................................................................................................................ 389UVSPACE (<strong>ASAP</strong> Command)........................................................................................................................ 390Commands and Macros (V)................................................................................ 392VALUES (<strong>ASAP</strong> Command)...........................................................................................................................392VANES (<strong>ASAP</strong> Command)............................................................................................................................. 392VARIABLES (<strong>ASAP</strong> Command).................................................................................................................... 393VCAVITY (<strong>ASAP</strong> Command).........................................................................................................................394VERSION (<strong>ASAP</strong> Command)......................................................................................................................... 395VIEW (<strong>ASAP</strong> Command)................................................................................................................................ 395$VIEW (<strong>ASAP</strong> Macro).................................................................................................................................... 396VIOLATION (<strong>ASAP</strong> Command).....................................................................................................................397VOXELS (<strong>ASAP</strong> Command)...........................................................................................................................397VUFACETS (<strong>ASAP</strong> Command)...................................................................................................................... 398Commands and Macros (W)............................................................................... 400$WAIT (<strong>ASAP</strong> Macro).................................................................................................................................... 400WARNINGS (<strong>ASAP</strong> Command)..................................................................................................................... 400WAVELENGTH(S) (<strong>ASAP</strong> Command)..........................................................................................................400WEDGE (<strong>ASAP</strong> Command)............................................................................................................................ 401WIDTHS (<strong>ASAP</strong> Command)........................................................................................................................... 402WINDOW (<strong>ASAP</strong> Command)......................................................................................................................... 403WRITE (<strong>ASAP</strong> Command)..............................................................................................................................404Commands and Macros (XYZ)...........................................................................406XEQ (<strong>ASAP</strong> Command).................................................................................................................................. 406XMEMORY (<strong>ASAP</strong> Command)......................................................................................................................406XY[Z] and Other Plot Window Overrides (<strong>ASAP</strong> Command Argument)...................................................... 408ZERNIKE (<strong>ASAP</strong> Command)..........................................................................................................................408Building Your System.......................................................................................... 411Achieving Optimal Performance in <strong>ASAP</strong>...................................................................................................... 411Setting the Working Directory......................................................................................................................... 412Building the Geometry..................................................................................................................................... 412Define/Modify Entities or Single Entity Objects.................................................................................412Define/Modify Curve/Edge Entities..................................................................................................... 413Define/Modify Surface/Function Entities.............................................................................................414Define/Modify Lens Entities................................................................................................................ 416Create/Modify Media, Coatings, Scatter Models.................................................................................417Create/Modify Objects..........................................................................................................................418Object Creation..................................................................................................................................... 420Building the Source.......................................................................................................................................... 420Create Rays/Beams............................................................................................................................... 420Verifying the System and Sources...................................................................................................................421Setup Plots and Verify System............................................................................................................ 421

<strong>ASAP</strong> | Contents | 11Standard Plot Options...........................................................................................................................422Setup Beam Creation............................................................................................................................423Modify Ray/Beam Data........................................................................................................................423Tracing the Rays Overview..............................................................................................................................424Tracing a Group of Rays or Beams..................................................................................................... 425Setup Trace........................................................................................................................................... 425Ray Tracing Data Saved by <strong>ASAP</strong>......................................................................................................425Trace Ray and Beams...........................................................................................................................426Analyzing the Data........................................................................................................................................... 426Analyze Ray/Beam Data...................................................................................................................... 427Modify or Use Internal Ray/Beam Data as Input................................................................................427Calculate Diffraction/Propagation Effects............................................................................................427Save or Recover System Data and Control Execution........................................................................ 428Display/Modify Data Distributions...................................................................................................... 428Kernel Capabilities Overview..............................................................................431Command Scripting.......................................................................................................................................... 431Examples of Command Scripts........................................................................................................................ 432Command Usage...............................................................................................................................................432Command Comment Strings............................................................................................................................ 433Command Description Notation.......................................................................................................................433Entries Repeated and <strong>Inc</strong>remented...................................................................................................................433Distribution Data Files Overview.................................................................................................................... 434Distribution Data Files Display........................................................................................................................434Distribution File Structure................................................................................................................................435File Naming Conventions in <strong>ASAP</strong>.................................................................................................................436Files Produced by <strong>ASAP</strong>..................................................................................................................................437File Structure of <strong>ASAP</strong>.................................................................................................................................... 439General Input Techniques.................................................................................................................................439Input Records....................................................................................................................................................441Mathematical Functions Supported.................................................................................................................. 441Mathematical Operators....................................................................................................................................443Registers for Storing Arithmetic Results......................................................................................................... 444Single- and Double-Precision Numbers........................................................................................................... 445Specifying Complex Numbers..........................................................................................................................445Variables............................................................................................................................................................445Variable Substitution............................................................................................................................ 445Externally Named Variables.................................................................................................................446Internally Named Variables..................................................................................................................446Quick <strong>Reference</strong> <strong>Guide</strong>........................................................................................ 448<strong>ASAP</strong> Syntax - Quick <strong>Reference</strong>.....................................................................................................................448Optical System Model - Quick <strong>Reference</strong>....................................................................................................... 448Verifying Optical System Model - Quick <strong>Reference</strong>.......................................................................................449Source Models - Quick <strong>Reference</strong>................................................................................................................... 450Verifying Source Model - Quick <strong>Reference</strong>.................................................................................................... 451Ray Tracing and Analysis - Quick <strong>Reference</strong>................................................................................................. 453Miscellaneous Useful Commands - Quick <strong>Reference</strong>..................................................................................... 453Macro Formatting - Quick <strong>Reference</strong>.............................................................................................................. 453Building Your System.......................................................................................... 455Achieving Optimal Performance in <strong>ASAP</strong>...................................................................................................... 455Setting the Working Directory......................................................................................................................... 456

Building the Geometry..................................................................................................................................... 456Define/Modify Entities or Single Entity Objects.................................................................................456Define/Modify Curve/Edge Entities..................................................................................................... 457Define/Modify Surface/Function Entities.............................................................................................458Define/Modify Lens Entities................................................................................................................ 460Create/Modify Media, Coatings, Scatter Models.................................................................................461Create/Modify Objects..........................................................................................................................462Object Creation..................................................................................................................................... 464Building the Source.......................................................................................................................................... 464Create Rays/Beams............................................................................................................................... 464Verifying the System and Sources...................................................................................................................465Setup Plots and Verify System............................................................................................................ 465Standard Plot Options...........................................................................................................................466Setup Beam Creation............................................................................................................................467Modify Ray/Beam Data........................................................................................................................467Tracing the Rays Overview..............................................................................................................................468Tracing a Group of Rays or Beams..................................................................................................... 469Setup Trace........................................................................................................................................... 469Ray Tracing Data Saved by <strong>ASAP</strong>......................................................................................................469Trace Ray and Beams...........................................................................................................................470Analyzing the Data........................................................................................................................................... 470Analyze Ray/Beam Data...................................................................................................................... 471Modify or Use Internal Ray/Beam Data as Input................................................................................471Calculate Diffraction/Propagation Effects............................................................................................471Save or Recover System Data and Control Execution........................................................................ 472Display/Modify Data Distributions...................................................................................................... 472<strong>ASAP</strong> | Contents | 12

<strong>ASAP</strong> | <strong>ASAP</strong> <strong>Reference</strong> <strong>Guide</strong> Introduction | 13<strong>ASAP</strong> <strong>Reference</strong> <strong>Guide</strong> IntroductionThis technical publication is for use with <strong>ASAP</strong> ® 2013 V1R1. The contents are derived from selected topics in <strong>ASAP</strong>Help. To access associated example scripts or related topics, please refer to the <strong>ASAP</strong> Help file (<strong>ASAP</strong>_Help.chm).For technical support or technical information about other BRO products, contact: <strong>Breault</strong> <strong>Research</strong> <strong>Organization</strong>,<strong>Inc</strong>., Tucson, Arizona, USAUS/Canada 1-800-882-5085Outside US/Canada +1-520-721-0500Fax +1-520-721-9630E-Mail:Technical Customer ServiceGeneral InformationWeb Sitesupport@breault.cominfo@breault.comhttp://www.breault.com<strong>Breault</strong> <strong>Research</strong> <strong>Organization</strong>, <strong>Inc</strong>., (BRO) provides this document as is without warranty of any kind, eitherexpress or implied, including, but not limited to, the implied warranty of merchantability or fitness for a particularpurpose. Some states do not allow a disclaimer of express or implied warranties in certain transactions; therefore, thisstatement may not apply to you. Information in this document is subject to change without notice.Copyright © 2008-2013 <strong>Breault</strong> <strong>Research</strong> Corporation, <strong>Inc</strong>. All rights reserved.broman0128_reference.pdf

<strong>ASAP</strong> | Achieving Optimal Performance in <strong>ASAP</strong> | 14Achieving Optimal Performance in <strong>ASAP</strong>When determining your computer requirements, BRO encourages you to select an operating system that supportsoptimal performance for <strong>ASAP</strong>, and uses processor resources intensively for its computation, analysis, and graphicaloutput.In particular, if you are running <strong>ASAP</strong> on Windows 7 operating systems with 64-bit versions, you can achieveoptimal performance from <strong>ASAP</strong> by adding as much memory as your budget allows. These operating systemsautomatically cache the virtual.pgs file in RAM up to the available amount of RAM memory. The virtual.pgs filecontains the rays used in the simulation. This is the file that <strong>ASAP</strong> uses to read and write rays during ray tracing, andit accesses this file for other analyses requiring ray data.As a general rule, each ray of an incoherent extended source uses approximately 64 bytes of memory. If you knowthe number of rays in your source, you can use this simple relationship to estimate the size of the virtual.pgs file. Forexample, if you create 70 million rays, <strong>ASAP</strong> uses approximately 4.5 GB of available memory. If your initial sourcesize exceeds the available memory, <strong>ASAP</strong> uses the hard disk space, which is considerably slower and consequentlyaffects certain performances. Similarly, some simulations such as deterministic stray light analyses create rays andadd to the size of the virtual.pgs file.The Windows operating system in 32-bit versions limits the memory available to 2 GB, regardless of the totalinstalled RAM. The operating system also requires memory of its own. A system with 2 GB of RAM typically canmake, at most, slightly over 1 GB of RAM available for ray data, before forcing <strong>ASAP</strong> to switch to a virtual.pgs fileon disk.For faster speed, you may want to consider using SSD (solid-state drive) disks, regardless of the Windows operatingsystem, instead of traditional magnetic disks such as hard disk drives (HDDs). If <strong>ASAP</strong> runs out of available systemmemory, it uses disk storage. Therefore, <strong>ASAP</strong> performance improves with the speed of the disk drive systems.

<strong>ASAP</strong> | Setting the Working Directory | 15Setting the Working DirectoryThe Working Directory in <strong>ASAP</strong> is the location where files are stored when you perform tasks such as runningscripts or translating files. This topic describes the default locations of this directory in Windows XP and Windows7 systems, which are different. Default settings are the recommended locations. The topic also describes how to set auser-designated location.BRO recommends that you use the default settings for the Working Directory. Do not use a shared network drivelocation.The default settings differ in Windows XP and Windows 7 systems. In Windows XP systems, alldirectories are writable, and the default location of the <strong>ASAP</strong> Working Directory is C:\Program Files\<strong>ASAP</strong>xxxxVxRx\Projects, where xxxxVxRx indicates the <strong>ASAP</strong> version you are using; for example,<strong>ASAP</strong>2012V1R1. In Windows 7 systems, security restrictions limit the location of writable files, and the WorkingDirectory path that is writable in Windows XP is not writable in Windows 7. For this reason, the default locationof the Working Directory in Windows 7 is C:\Users\username\AppData\Local\<strong>Breault</strong> <strong>Research</strong><strong>Organization</strong>\<strong>ASAP</strong>xxxx.x\Projects, where <strong>ASAP</strong>xxxx.x indicates the <strong>ASAP</strong> version you are using; forexample, 1202.1, where 12=year, 02=version, and .1 = release number.To set the Working Directory to a different location, the location must be writable. Follow these steps:1. Click File> Set Working Directory in <strong>ASAP</strong>.2. In the Windows dialog box, select the folder to write the files, and click OK. Note: If you select a non-writablelocation, unexpected behavior may result.Assuming that the location of the Working Directory that you selected is writable, it is set until you change it.

<strong>ASAP</strong> | Commands and Macros (A) | 16Commands and Macros (A)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “A”.a,b,c... (<strong>ASAP</strong> Command Argument)Some commands (for example, PLANE NORMAL, ALIGN, RAY, SOURCE DIRECTION) require the specificationof a direction vector. The following formats can be used for these three input entries (shown as simply "a,b,c" in thecommand descriptions).Input Entry Input Entry Input Entry Descriptiona b c Actual relative componentsof direction vector+/- b c Two actual directioncosines, sign of thirda +/- ca b +/-X a a' Spherical angles (indegrees) from and aroundgiven axisYZDIR RAY n Current direction of givenray numberSOUAverage direction of raysfrom given sourceOBJ n n' Direction of vectorbetween positions of thetwo entitiesSUREDGLENRAYNOR SUR n Direction of normal togiven entity at its referencepoint at LIMITS boxcenterLENEDGOBJLIMat LIMITS box center

<strong>ASAP</strong> | Commands and Macros (A) | 17Input Entry Input Entry Input Entry DescriptionLOCAt LOCAL box centerLOC X n Direction of givenlocal coordinate axis ofSURFACE nYZTAN n u Tangent to CURVE/EDGEn at parametric value u.<strong>ASAP</strong> automatically normalizes the resulting vector to unit length.abc Argument ExamplesABEL (<strong>ASAP</strong> Command)Performs an Abel or inverse Abel transform on each line of data about the horizontal axis.Function• Display/Modify Data DistributionsSyntaxABEL [c] [INVERSE]OptioncINVERSEDescriptionCenter of dataFlag to perform an inverse Abel transformRemarks1. Performs an Abel or inverse Abel transform on each line of data assuming that the center is located at c (absoluteor fractional pixel value, default is centroid of data).2. An inverse Abel transform calculates an emission function based on an image (photograph) of that source.3. Use ABEL INVERSE on CCD images, and EMITTING DATA to model arc lamps.4. Bitmap (*.bmp) files can be read into distribution files (*.dis) using the executable file, BMP2DIS.EXE.Note: From <strong>ASAP</strong>, open and run the sample project, Banana_Arc.apf, located in \Projects\Samples\BananaArc.ABEL ExamplesABERRATIONS (<strong>ASAP</strong> Command)Displays the image aberrations of all the current lens or conicoids l through l' (up to 120 total). This command can beapplied only to <strong>ASAP</strong> lens-based objects, not to surface- or edge-based objects.Function• Define/Modify Lens Entities

<strong>ASAP</strong> | Commands and Macros (A) | 18SyntaxABERRATIONS [ l l' ] [ LIST ] [ PLOT [ k ] ] [ datum d ] [ datum' d' ] ...RemarksNote:Since the analysis is valid only for centered lens systems, the conicoids must have a common axis. If not, thelens is temporarily "unfolded" to make it so.1. The first-order operating data must be supplied with the additional entries, which is the data for the marginal axialray from the center of the "object" through the edge of the limiting aperture stop, and the chief ray from the edgeof the "object" to the center of this stop.2. First-order data defines the marginal and chief heights and angles relative to the object location and the limitingaperture stop.3. Object Space (before first conicoid):Datum Default DescriptionU0 0 Marginal ray slope (tangent ofangle)UB0 .01 Chief ray slope (tangent of semifieldangle)H0 1st aperture Marginal ray height at entrancepupil planeH1 1st aperture Marginal ray height at first conicoidHB1 0 Chief ray height at first conicoidTH0 0 Distance from entrance pupil to firstconicoidKTH0 none Conicoid number of actual aperturestop (0 to vary, .1 for telecentric inimage space)FB 0 Fractional evaluation fields (up to 5;for example, 0,.5,.7,.866,1)4. Image space (after last conicoid):Datum Default DescriptionKUF last Conicoid on which to put imagesolvesUF initial Marginal ray slope after lastconicoid (curvature solve)BKF NA Fix back focal distance (lastconicoid to paraxial focus)THF 0 Distance from paraxial focus todesired focal surfaceCVF 0 Curvature of focal surfaceCCF 0 Conic constant of focal surface

<strong>ASAP</strong> | Commands and Macros (A) | 19Datum Default DescriptionKTHF NA Solve for best axial position of focalsurfaceKCVF NA Solve for best curvature of focalsurfaceKCCF NA Solve for best conic constant offocal surface5. If the LIST option is present, the following surface-by-surface tables are produced: Paraxial marginal and chief raytraces.• Paraxial marginal and chief ray traces• Seidel primary/secondary aberrations (3rd-order, axial/lateral color)• Real marginal and chief ray traces• Glass and conicoid data (after solves)6. In any case, the final 1st-order (primary color), 3rd-order, 5th-order, and selected 7th/9th-order aberrationcoefficients (in waves) are listed for actual stop plane coordinates and relative to the ideal paraxial focus. Thesecoefficients are computed using both analytical formulas and real-ray data matching.7. <strong>ASAP</strong> carries out all these calculations in double precision.8. The optional PLOT displays (full-window or starting in quadrant k) the traced lens and the following graphs:• Ray fans (image deviation versus aperture) for each evaluation field.• Chief ray sagittal (S) and tangential (T) foci as a function of field.• Chief ray (D) and spot centroid © ) fractional distortion versus field.• Polychromatic (A)ctual and monochromatic (B)est-focused RMS spot vs. field.9. Except for the RMS spot size graphs, solid curves are computed from the approximate aberration coefficients(with color terms) while dotted curves are center-wavelength real-ray points.10. The ABERRATIONS command can be followed by any number and combination of the commands listed belowunder "Related information".ABERRATIONS ExamplesABG (<strong>ASAP</strong> Command)Creates an isotropic ABg (linear shift invariant) scatter model.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxABG a b g [ PLOT [ a’ a” …] ]OptionabgPLOTDescriptionSpecular peak numerator2 times surface correlation length Lc ( )A scattering quantitative and directional term that maybe positive or negative, but typically between 0 and 3.Plots the model in log(b-bo) and angle space

<strong>ASAP</strong> | Commands and Macros (A) | 20Optiona' a"...DescriptionUser-defined degree specular anglesRemarks1. Commonly used to model scattering from isotropic surface roughness. ABG is similar to the isotropic Harveymodel. The BSDF of this model is defined as:whereNote: Coefficient restrictions: A and B must be greater than or equal to 0. The ratio of A/B is the peakBSDF in the specular direction. If A equals zero, no scattering occurs; therefore, do not use PLOT option.If g is zero, the BSDF is constant in direction cosine space:and the resulting scattering is Lambertian. If A, B, and g are set to provide a relatively flat BSDF curve,using a Lambertian scatter model is preferable.2. Use with importance area sampling.3. The command argument, PLOT plots the model (common base 10 logarithm of the BSDF) for up to sevenspecular angles in ascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS settingcontrols the resolution of these plots in direction cosine space. It also creates a distribution file, name_angle.dis,for each of these angles.4. The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.ABG Examples$ABORT (<strong>ASAP</strong> Macro)From any macro/loop level, returns to the command prompt as soon as possible and displays the optional "message".SyntaxABORT [ 'message' ]

<strong>ASAP</strong> | Commands and Macros (A) | 21OptionmessageDescriptionOptional message to display$ABORT ExamplesABSORB (<strong>ASAP</strong> Command Argument)Absorption or gain option, which is positive for an absorbing medium or negative for a gain (assigning) medium.Syntax... [ ABSORB a [ j q t ] ]OptionajtDescriptionVolume absorption in inverse length unitsIts magnitude is the SURFACE designation for thisfunction when tracing a ray in this inhomogeneousmediumStep lengthRemarks1. If an absorption is not given (or zero), the program uses the wavelength and the imaginary part of the complexrefractive index (if specified) to calculate the absorption.2. Inhomogeneous absorption or gain can be handled by assigning to the medium a GENERAL polynomial in theglobal coordinates X,Y,Z or USERFUNC function (with additional wavelength w dependence).3. The magnitude of j is the SURFACE designation for this function.4. The absorption coefficient at each point in the medium is then given by:5. The t is the step length to be used by the program when tracing a ray in this inhomogeneous medium.ABSORB ExamplesACCURACY (<strong>ASAP</strong> Command)Provides user control of the trade-off between ray trace speed and accuracy when determining the ray/surfaceintersection.Function• Setup TraceSyntaxACCURACY [ HIGH | MEDIUM | LOW ] [ PARALLEL [ d ] ]

<strong>ASAP</strong> | Commands and Macros (A) | 22OptionHIGHMEDIUMLOWPARALLELDescriptionConducts most rigorous and time-consuming calculationConducts moderately rigorous and time-consumingcalculationConducts least rigorous and time-consuming calculationSets the threshold in degrees for approximatingTOWARDS edges as being parallel to the scatteringsurface. If PARALLEL is specified without d, d defaultsto zero.Remarks1. ACCURACY controls the trade-off between ray/surface intersection accuracy and calculation speed. For thoseobjects where the location of the ray/surface intersection must be determined iteratively, an ACCURACY ofHIGH forces a more rigorous and time-consuming calculation of this point than an ACCURACY of LOW. Seethe table below for approximate error ranges. For most SURFACE types, the location of the ray/surface or objectintersection is directly determined.2. HIGH (the startup default) should be used when parabasal rays must be as accurate as the base rays, and opticalpath lengths are required to be accurate to a small fraction of a wavelength over great distances. This is usuallynecessary for coherent high-resolution analyses.3. LOW may be appropriate for incoherent stray light and illumination calculations where parabasals rays are notgenerated. In most instances, MEDIUM or HIGH is recommended. This may also be sufficient for some coherentcalculations if the parabasal rays are located on a plane tangential to the intersection of the base ray on the opticalsurface.4. If PARALLEL is specified, a fast approximation is used for TOWARDS edges with surface-normals within ddegrees of the local surface normal of the scattering surface. A more accurate calculation is used for angles largerthan d degrees.5. If PARALLEL is specified but d is omitted, d defaults to zero, which has the effect of always applying the moreaccurate calculation.6. If PARALLEL is not specified, the angle of 8.1 degrees (direction cosine 0.99) is used. This is appropriate for mostgeneral-purpose, stray-light calculations, but is not appropriate for specialized investigations of predominantly onaxisscatter.7. PROFILES and RENDER calculations are also affected by this command.8. Typical relative error values used in iterative solvers are:LOWMEDIUMHIGH1.E-41.E-71.E-109. If no option is specified, the setting reverts to the state before the most recent ACCURACY command. Best practiceis to always apply the desired option on the ACCURACY command.ACCURACY ExamplesACTIVITY (<strong>ASAP</strong> Command Argument)Makes the current medium chiral--one that exhibits isotropic optical activity (circular birefringence).Function• Create/Modify Media, Coatings, Scatter Models

<strong>ASAP</strong> | Commands and Macros (A) | 23Syntax. . .[ ACTIVITY r [ g ] ]OptionrgDescriptionRadiansDifference between the right and left-handed refractiveindices (see Remarks)Remarks1. For a wavelength w (in system units), the specific rotary power in radians per unit length is,2. For r=0, g is just the difference between the right and left-handed refractive indices. Currently, this is assumed tobe a purely volume phenomenon and therefore, its (usually small) effect on direction splitting and the reflection/transmission coefficients at a surface are ignoredACTIVITY ExamplesAFOCAL (<strong>ASAP</strong> Command)Creates a two-element afocal telescope. Typical usage may be a beam expander or simple telescopes.Function• Define/Modify Lens EntitiesSyntaxAFOCAL X x l h h' m m'Y y REFL REFLZ zOptionX or Y or Zx or y or zlhh'm m'REFLDescriptionGlobal coordinate axisLocation on the global coordinate axisOverall length of the afocal telescopeInput heightOutput heightMediaReflectorRemarks1. The telescope elements may be both refractive, both reflective, or mixed.2. This lens entity starts out normal to the defined global coordinate axis (X, Y or Z).3. The conic constants of the two elements are adjusted so that there is no axial aberration.

<strong>ASAP</strong> | Commands and Macros (A) | 244. If h and h' are of opposite sign, there is an intermediate real focus.5. For a reflecting element, m should be -1 or REFL Either or both elements may be reflectors.AFOCAL ExamplesALIGN (<strong>ASAP</strong> Command)Rotates object, entity, or source so that its direction vector is aligned to different specified direction.Function• Create/Modify Objects• Define/Modify Lens Entities• Define/Modify Surfunc Entities• Modify Ray/Beam DataSyntaxALIGN a,b,c a',b',c' [ x,y,z ] [ LIST ]OptionDescriptiona, b, c First direction vectora', b', c'Second direction vectorx, y, z Fixed point that the rotation axis passes through (defaultis the entity's reference point)LISTRemarksPrints the resulting 4-by-4 transformation matrix1. ALIGN can be used when setting up systems for which you have only global vertex coordinates and global normalvectors. The rotation axis passes through the given point, and this point remains fixed during the transformation.Since it performs the most direct coordinate rotation, an ambiguous clocking rotation may occur. This commandrequires you to know the current direction vector as well as the desired orientation vector for each item.2. Rotates object, entity, or source represented as a,b,c so that its direction vector is aligned to a different specifieddirection a', b', c.'3. The rotation axis passes through a fixed point; that is, either point x,y,z or the entity's reference point (default).4. The LIST option causes the resulting 4-by-4 transformation matrix to be printed and decoded into simpleoperations if possible.5. See the topic, General Input Techniques for various formats that are supported for the a, b, and c entries. Forinstance, to align the average source direction with the positive Z axis direction, you can use the format, ALIGNDIR SOU 1 0 0 1. See the example.6. Some commands, including SOURCE DIRECTION, require the specification of a direction vector. The followingformat can be used for this input entry.ExampleEMIT RECT Z 0 0 0 1LIST DIRSURFACE; PLANE Z 0ALIGN 0 0 1 DIR SOU 1PRINTALIGN Examples

<strong>ASAP</strong> | Commands and Macros (A) | 25ALLOWED (<strong>ASAP</strong> Command)Controls whether a ray is allowed to proceed after intersecting an object.Function• Setup TraceSyntaxALLOWED [ LIST ][ ALL FORWARD ]SEQUENTIAL BACKWARDI j j' j":OptionLISTALLSEQUENTIALFORWARDBACKWARDDescriptionLists SEARCH settingsAll objects are candidates for intersectionSearches objects sequentiallySearches objects forwardSearches objects backwardI j j' j" On object I, searches objects j through j' in steps of "jRemarks1. Determines whether a ray is allowed to proceed once it has reached the next object.2. For an ALL input, where all objects are candidates for intersection, the current object is considered for the nextintersection with the rays.3. The range of possible objects can be selectively set by additional commands, with the first entry I being thenumber for the particular object, followed by a pair of entries.4. You must run the ALLOWED command after defining all objects. Otherwise, <strong>ASAP</strong> issues an error message.5. The LIST option prints the current allowed settings for each object.6. With m being the largest possible object number, the various options for ray intersection after OBJECT I aretabulated according to the following table.InputObject RangeFromTo<strong>Inc</strong>rementj j' j" j j' j"ALL 1 m 1ALL FORWARD I m 1ALL BACKWARD I 1 -1SEQUENTIAL I-1 I+1 2SEQUENTIALFORWARDSEQUENTIALBACKWARDI+1 I+1I-1 I-1

<strong>ASAP</strong> | Commands and Macros (A) | 26ALLOWED ExamplesALTER (Edge Modifier) (<strong>ASAP</strong> Command)Alters specific edge-points data. Modifies the shape of an edge-based entity.Function• Define/Modify Curvedge EntitiesSyntax 1ALTER n [ n' [n" ] ] fcn [ a [ b [ j ] ] ] a [ b [ j ] ]]...Syntax 2ALTER n [ n' [n" ] ] data a [ b [ j ] ] data' a' [ b' [ j'] ] ...Syntax 3ALTER n [ n' [ n" ] ] ... AX a [ b [ j ] ] ...AYAZOptionn n'fcna b, a' b' ...DescriptionEdge points rangeDefined $FCNALTER parameter scale factorsj, j' ... Edge points range used for calculationdata, data' ...AX, AY, AZRemarksSyntax 1:ALTER parametersAxis of rotation of conicoid1. Remaps specified points of the current curve using a previously defined $FCN fcn. The original coordinates ofeach point are passed in the _1, _2, and _3 registers, the arbitrary input parameter a, b, and j in _4, _5, and _6. Thefcn then returns the 3 new coordinates. For example, this capability could be used to do non-linear remapping, likeinputting curve points in cylindrical or spherical coordinates, and then converting them to the required Cartesianequivalents.Syntax 2:1. Alters data on a set of edges allowing, for example, pickups on other edges.2. The given data on points n through n' (default n) for the current edge are altered as follows for that edge; that is,for i= n to n' by "n (default 1):data (i) = a + b data (j) with 'defaults' b=0, j=idata' (i) = a' + b' data' (j'):

<strong>ASAP</strong> | Commands and Macros (A) | 273. The data parameters are shown in the following table.DataXYZQ WDescriptionx coordinate of edge pointy coordinate of edge pointz coordinate of edge pointConnection or weighting factorSyntax 3:1. Rotates the given conicoids about the X, Y or Z axis, respectively, through an angle a degrees relative to theposition that is a distance b (default 0) from the jth point (default itself).ALTER ExamplesALTER (Lens Modifier) (<strong>ASAP</strong> Command)Alters lens conicoid database.Function• Define/Modify Lens EntitiesSyntax 1ALTER n [ n' [ n" ] ] ... AX a [ b [ j ] ] ...AYAZSyntax 2ALTER n [ n' [ n" ] ] data a [ b [ j ] ] data' a' [ b' [ j' ] ] ...OptionDescriptionn n' Conicoid range (n' is defaulted to n)a, b, j Arbitrary input parametersAX, AY, AZRemarksSyntax 1:Axis of rotation of conicoid1. Rotates the given conicoids about the X, Y or Z axis, respectively, through an angle a degrees relative to theposition that is a distance b (default 0) center of the jth conicoid (default itself).Syntax 2:1. Alters data on a set of conicoids allowing, for example, pickups on other conicoids.2. Conicoids n through n' (default n) for the current lens are altered as follows for i=n to n' by "n (with defaults b=0,j=i):

<strong>ASAP</strong> | Commands and Macros (A) | 28data (I) = a + b data (j)data' (I) = a' + b' data' (j')The data parameters are as shown:DataDescriptionXx coordinate of vertex positionYy coordinate of vertex positionZz coordinate of vertex positionUx component of vertex normalVy component of vertex normalWz component of vertex normalHAperture heightC RVertex curvature or radiusK Conic constant (4th-order aspheric if curvature = 0)OObscuration (hole) ratioMMedium numberC0 R0Curvature or radius of subtracted parabolaSAspheric scale factorALTER ExamplesALTER (Surface Modifier) (<strong>ASAP</strong> Command)Edits specific polynomial coefficients to form a differently shaped or oriented surface.Function• Define/Modify Surfunc EntitiesSyntaxALTER [ n ] term a [ b ] [ term' a' [ b' ] ...Remarks1. <strong>ASAP</strong> is capable of handling any implicit surface that can be represented by an arbitrary function of a general nthorder polynomial in the global coordinates X,Y,Z, with arbitrary reference point x,y,z and real coefficients c.2. ALTER changes the coefficient of the given polynomial term to be a plus b (default 0) times its current value. Forexample, to multiply the constant term by 2 and change the Z term to -1:ALTER C 0 2 Z -13. If any of the terms are of a higher degree than the current surface, then increase the degree of the current surface ton (zeroing out new coefficients) before altering any terms.ALTER Examples

<strong>ASAP</strong> | Commands and Macros (A) | 29ANALYZE (<strong>ASAP</strong> Command)Changes first-order conditions and re-evaluates the lens.Function• Define/Modify Lens EntitiesSyntaxANALYZE [ datum d ] [ datum’ d’ ] ...RemarksChanges any of the given first-order operating conditions (see ABERRATIONS command for a detailed list), and reevaluatesthe lens.ANALYZE ExamplesANGLES (<strong>ASAP</strong> Command Argument)Several BSDF models allow fitting to or interpolation from actual data. They all use the following common optionsand format.Syntax... [ ANGLES ] [ LOG ] [ COS ][ ao bo ] !!first specular direction (defaults tooutput)a b f [ a' b' f' ...]!!triplets of output direction and BSDF:ao' bo'!!second specular direction: !!more tripletsOptionANGLESCOSLOGa a' ...ao boa b [a' b' ...]f [f' ...]ao' bo'DescriptionSpecifies spherical angle coordinates in degreesSpecifies angle coordinates in direction cosineSpecifies common logarithmic BSDF valuesUser-defined degree specular anglesFirst specular direction, polar and spherical angleEither direction cosine space coordinates or the sphericalANGLES from and around normal, respectivelyEither actual BSDF values or the common LOG of theBSDF (when specifying the LOG option)Second specular directionRemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. The a's and b's are either direction cosine space coordinates or the spherical ANGLES from and around normal,respectively.

<strong>ASAP</strong> | Commands and Macros (A) | 303. The f's are either actual BSDF values or the common (base 10) LOG of the BSDF (when specifying the LOGoption).4. Except for the RAWDATA model, BSDF values below 1.E-9 (-9 LOG) are ignored.ANGLES ExamplesANGLES (<strong>ASAP</strong> Command)Converts the current distribution data to an angle space RADIANCE or radiant intensity distribution.Function• Display/Modify Data DistributionsSyntaxANGLES [RADIANCE]Remarks1. ANGLES converts a direction cosines space radiance distribution, which is created by SPREAD or SPOTSDIRECTION, to an angle space RADIANCE or radiant intensity distribution.2. The polar axis of the spherical angle coordinate system is assumed to be horizontal (IES type B photometry). Thesecond direction of data set is based on the WINDOW command in effect at the time the data was captured (that is,WINDOW XY).3. This command converts the data in the working copy of the distribution file to angle space from direction cosinespace. All following commands are performed on angle space data until a Return from display is issued.ANGLES ExamplesAPPEND (<strong>ASAP</strong> Command)Appends the current data to the end of the distribution file number and updates the header accordingly.Function• Display/Modify Data DistributionsSyntaxAPPEND [ u ]nameOptionunameDescriptionDistribution file numberDistribution file nameRemarks1. Appends the current data to the end of distribution file number u or name.dis (the default is the one loaded onentry to DISPLAY) and updates the header accordingly.2. Due to the fixed structure of a BRO binary distribution file, the number of rows and columns must match betweenthe data sets.3. Direction of appended data is determined by the WINDOW command in effect at the time the data is captured. Datais stored in vertical/horizontal direction.

<strong>ASAP</strong> | Commands and Macros (A) | 314. <strong>ASAP</strong> reserves certain unit numbers for internal use such as BRO009 and BRO029. Do not use any <strong>ASAP</strong>reserved unit numbers. See the $IO (<strong>ASAP</strong> Macro) topic for a complete list of reserved unit numbers.APPEND ExamplesARC (<strong>ASAP</strong> Command)Creates a circular arc on the plane.Function• Define/Modify Curvedge EntitiesSyntax 1 (long form)ARC X x y [ z y' z' [ a ] ]Y y z x z' x'Z z x y x' y'Syntax 2 (short form)ARC X x rY yZ zOptionDescriptionX, Y or Z Coordinate axis of the planex, y or z Location of the plane on the coordinate axisy [ z ], z [ x ], or x [ y ]Arc starting pointy' z', z' x', or x' y' Arc center (default 0,0)ar<strong>Reference</strong> PointArc centerRemarksArc subtense (default 360 degrees)Radius of the arc (short form)1. The short form allows you to enter a complete circle of radius r centered on the axis.2. This edge is a combination of coplanar straight line and higher-order curved segments.3. Arcs up to 135 degrees are represented by a single, quadratic, rational, Bezier segment. Beyond that, the arc issubdivided into more of these segments (up to 4 for a full 360 degrees).ARC Examples$ARGS (<strong>ASAP</strong> Macro)Controls argument prompting in user-defined macros.

<strong>ASAP</strong> | Commands and Macros (A) | 32Syntax$ARGS [ ALL ]NONEUSERSCRRemarksThe SCR feature displays a dialog box for prompts with arguments. After pressing Enter after each entry, click theOK or Cancel button as appropriate to exit the dialog.Interactive prompts are displayed for either ALL NONE or only the ones defined by the USER in the macro definition.The default in the absence of any $ARGS command is ALL. If no argument is given on the command, the state beforethe last $ARGS command is restored.Examples$ARGS ExamplesARRAY (<strong>ASAP</strong> Command)Turns the last surface into a set of identical surfaces.Function• Define/Modify Surfunc EntitiesSyntaxARRAY n x y z [ n' x' y' z' ] [ EXPONENT p [ p' ] ] [ RANDOM r ] [ BOUNDS]X n s Y n' s' SEARCH [ k ]ZYZXZXYOptionARRAYn n'x y z x' y' z'EXPONENTRANDOM (or RAN)p p'BOUNDSSEARCHkDescriptionElements are associated with an OBJECTNumber of linearly spaced elements<strong>Reference</strong> point shiftModifies reference point coefficientRandomize positions of individual array elements (RANis an acceptable abbreviation for RANDOM.)reference point coefficient exponentTreats each instance as a separate entityLimits testing of ray intersections to elements within knearest neighborsNumber of additional "rings" of instances about thenearest one to consider

<strong>ASAP</strong> | Commands and Macros (A) | 33OptionDescriptions, s' Set of identical but linearly spaced (s and s’ apart)surfacesRemarks1. Turns the last surface into an n+1 by n'+1 set of identical but linearly spaced (s and s' apart) surfaces. For the first,more general (possibly skew) syntax, the replicated surfaces are spaced according to the equation:2. The EXPONENT option allows the reference point coefficient to be modified as follows:3. The defaults for p and p' are both 1.4. Positions of each element of the array (except for the original one, i=0, j=0) can be RANDOMized a relativeamount given by the fractional part of r. The whole/integer part of r (default 0) determines a unique randomsequence to be used. See the topic, "Mathematical Functions Supported".5. Each instance (that is, element) can be optionally treated as a separate entity on a BOUNDS command. Otherwise,if it is used as a base object surface, the SEARCH for any ray intersection is restricted to the instance nearest towhere the ray intersects the plane of the array (default is a k of zero). SEARCH cannot be applied to an ARRAYwith an ARRAY BOUNDS command.6. The k option is the number of additional "rings" of instances about this nearest one to also consider. For largearrays, this can speed up the trace calculation by orders of magnitude, but runs the risk of some rays unphysicallymissing the object. Larger values of k reduce this risk but slow down the trace.Note: From <strong>ASAP</strong>, open and run the sample project, backlight.apf, located in your \Projects\Samples\LCDbacklight.Note: On the Quick Start toolbar in <strong>ASAP</strong>, click Interactive Scripts, Array Enhancers to view tools forcreating several forms of arrayed structures. If the toolbar is not visible, click View, Quick Start Bar.ARRAY ExamplesARRAY NONLINEAR (<strong>ASAP</strong> Command)Turns the last surface into a set of identical but nonlinearly spaced surfaces.Function• Define/Modify Surface EntitiesSyntax 1ARRAY NONLINEAR v {f|TABLE|MVFCN|USERPROG} n v’{f'|TABLE|MVFCN|USERPROG} n' [POSITION] [RANDOM r] [SEARCH k|BOUNDS]

<strong>ASAP</strong> | Commands and Macros (A) | 34Syntax 2ARRAY NONLINEAR v {f|MVFCN|USERPROG} w v’{f'|MVFCN|USERPROG} w' [WIDTH] [POSITION] [RANDOM r] [SEARCH k|BOUNDS]Optionv and v’n and n’w and w’kf and f’TABLEMVFCNWIDTHPOSITIONRANDOMBOUNDSSEARCHkDescriptionLiteral coordinates, {X|Y|Z}, or general direction cosinetriples {a b c}Numbers of array elements (copies) to createMaximum width of desired elementNumber of additional “rings” of instances about thenearest one to searchLiteral reference to a $FCN that is implementing f(n)Specifies spacing/position of elementsSpecifies spacing/position of elementsSpecifies width of the filling, not the count of theelementSpecifies $FCN that controls positions of the elements,not the spacing between elementsRandomizes positions of individual array elementsTreats each instance as a separate entityLimits testing of ray intersections to elements within knearest neighborsNumber of additional "rings" of instances about thenearest one to considerRemarks1. Similar to the ARRAY command, ARRAY NONLINEAR creates an n+1 element 1D array or an n+1 times n'+1 2Darray. The element index starts at 0. The shift of the first element is always 0; that is, it is the original repeatingelement. You must specify the spacing between or the positions of the remaining n and n' elements. All spacingbetween elements must be positive and can be in arbitrary order, monotonically increasing or decreasing, evenperiodic. An error is issued if this is not satisfied.2. Use of a global axis or a specific direction can be mixed as array-repeating directions on a 2D array.3. Array elements can be created in four ways: single-variable, user-defined $FCN, TABLE, multivariable userdefined$FCN, and user-programmed UserNLA function in userprog.f90 (USERPROG). For two-dimensionalarrays, the methods are independent of each other for two repeating directions.4. If TABLE is used, the spacing/position of elements in this direction is specified in a table on the lines after thecommand line. If the elements in both repeating directions are controlled by the table data, the first n data entrieson the lines that follow the command line are for the first repeating direction, and the next n’ data entries are forthe elements in the second repeating direction. The data can span multiple lines.5. If MVFCN/USERPROG is used, the function name and coefficients are specified on the line after the commandline. If the elements in both repeating directions are controlled by MVFCN/USERPROG, the first line is for thefirst-repeating direction and the second line is for the second-repeating direction. Each line must be in the formatof: name a0, a1, a2 … a66, where a0 to a66 are the function coefficients. If you are using USERPROG, thefunction name must be USERPROG. If you are using MVFCN, the previously user-defined macro $FCN function

<strong>ASAP</strong> | Commands and Macros (A) | 35is the function name. If you are using USERPROG, the function name must be USERPROG followed by theappropriate input.6. If MVFCN is used, the multi-variable, user-defined macro $FCN name and the coefficients must be specified onthe line following the command line; one line for each direction. The first registry _ is reserved for the repeatingelement index. Up to 67 coefficients (_0, _1 ..., _66) can be used to define the user $FCN. The line starts with the$FCN name followed by the coefficients.7. If a user-programmable function in USERPROG.f90 is used for the USERPROG option, program the function,UserNLA in that file and compile it. If the user-programmed function is used, the line immediately following thecommand line must start with USERPROG followed by the actual coefficient values. Both repeating directions canbe driven by USERPROG, as demonstrated in userprog.f90.8. USERPROG can be used to create complicated, cross-dependent, 2D arrays; that is, the positions of elements arefunctions of both repeating indices. See the userNLA function in userprog.f90 for a sample case.9. The nonlinear array feature performs preliminary collision detection with the bounding box of the element. If apotential collision is detected, a warning message is issued.10. If WIDTH is specified and $FCN is used, confirm that the maximum value of the function is greater than thespecified width.11. The WIDTH option does not have any effect on the TABLE-driven array direction. Directly specify the repeatingcount for the TABLE-driven case.12. The RANDOM, SEARCH, and BOUNDS options are similar to those for the ARRAY command. Refer to the ARRAYcommand for remarks about these options.ARRAY NONLINEAR ExamplesARROWS (<strong>ASAP</strong> Command)Toggles between displaying arrowhead on rays and not displaying them.Function• Setup Plots and Verify SystemSyntaxARROWS [ s ]OFFOptionsOFFDescriptionRescaling factor for arrowhead sizeSuppresses appearance of an arrowRemarks1. Toggles the displaying of arrows on the PLOT RAYS, TRACE PLOT, and PLOT POLARIZATION commands.2. The s is a rescaling factor used to change the size of the arrowhead relative to the internal setting (default is 1).3. OFF is used to suppress the display of arrowheads.ARROWS ExamplesASCALE (<strong>ASAP</strong> Command)Deforms an edge or curve into a keystone.Function• Define/Modify Curvedge Entities

<strong>ASAP</strong> | Commands and Macros (A) | 36SyntaxASCALE s s'Optionss'DescriptionScale factor at the bottom of the edge/curveScale factor at the top of the edge/curveRemarks1. Scales the previous edge along the axis that follows the normal axis of that edge; for example, an ELLIPSE Z isscaled in the x direction.2. The bottom and top are determined from the minimum and maximum.3. The scaling varies linearly from s at the bottom to s' at the top of the edge (as measured along the third coordinatedirection), as shown in the following table where the coefficients a and b are computed from s s' and the height ofthe edges/curves.Edges/curvesCoordinate axis Scaled axis EquationX Y Yscaled = Y (a Z + b)Y Z Zscaled = Z (a X + b)Z X Xscaled = X (a Y + b)ASCALE Examples$ASK (<strong>ASAP</strong> Macro)Assigns a value to a variable through a prompting dialog box.Syntax&ASK [ register [ register' ... ] ] [ 'prompt' ]$ASKRemarks1. Macro prompts you for new value(s) for the variable(s) by displaying a prompting dialog box. This dialog box hasa user-specified prompt string across the top and an edit box along the bottom, into which the data is entered. Forimproved usability, enter a prompt string on Macro.2. The values may be either numeric or literal.3. In the event there is more than one variable, the dialog box contains a long edit box into which all of the values areentered. <strong>ASAP</strong> does not create a separate dialog box or prompting edit box for each variable.4. If the $ prefix is used, the current value(s) for the variable(s) is also displayed.5. If there are no variable arguments, <strong>ASAP</strong> displays the prompt dialog box and then waits for you to click OK.$ASK ExamplesASYM (<strong>ASAP</strong> Command)Modifies a surface to be cylindrical or anamorphic.

<strong>ASAP</strong> | Commands and Macros (A) | 37Function• Define/Modify Surfunc EntitiesSyntaxASYM u vOptionu vDescriptionScale factorsRemarks1. Allows the creation of a more general class of surfaces such as anamorphic OPTICAL surfaces.2. Can be used after TUBE, OPTICAL, TORUS, REVOLUTION, HORN, CARTOVAL, AXICONIC, BICONIC,CONDUIT, and SUPERCONIC commands to distort the rotational symmetry of the surfaces. For example, if Z isthe axis of symmetry, the surfaces are only a function of the distance from the axis squared:3. Performs the above replacement so that a more general class of surfaces is possible such as anamorphic OPTICALsurfaces. For example:OPTICAL Z 2.8 3.7 ! radius of curvature = 3.7ASYM 1 (3.7/4.6) ! radius of curvature in X = 3.7/1 = 3.7! radius of curvature in Y = 3.7/(3.7/4.6) = 4.64. To create a cylindrical trough, set either u or v to zero. All power is then in the nonzero direction.OPTICAL Z 0 10 ELLIPSE 2@3ASYM 0 1 !X radius = infinity!Y radius = 10ASYM ExamplesAVERAGE (<strong>ASAP</strong> Command)Smooths current distribution data by averaging adjacent pixels.Function• Display/Modify Data DistributionsSyntaxAVERAGE [ i [ j ] ] [WEIGHT]OptionijWEIGHTDescriptionPixels in the first direction (default=1)Pixels in the second direction (default=1)Weighted average; see Remarks

<strong>ASAP</strong> | Commands and Macros (A) | 38Remarks1. Smooths the data before displaying it by averaging over i (default 1) adjacent pixels in the first direction and j(default=1) in the second. For example, I=1 and j=1 replaces each pixel with the average of the 3x3 box of pixelscentered on it; I=2 and j=3 uses a 5x7 box, and so on.2. This operation is also equivalent to convolving the distribution with a finite window.3. If i and/or j are entered as negative numbers, the median value within the smoothing window is used instead of thenormal average value.4. Optionally, a WEIGHTed average can be done assuming that the error in each pixel within the given window isproportional to the square root of its value; that is, Monte Carlo statistics.AVERAGE ExamplesAXICONIC (<strong>ASAP</strong> Command)Creates a surface by spinning an arbitrarily oriented conic curve.Function• Define/Modify Surfunc EntitiesSyntaxAXICONIC X x h x' h' s [ x" h" ] [ LENGTH t ] [ LIST ]Y y h y' h' s [ y" h" ] [ HEIGHT ]Z z h z' h' s [ z" h" ]OptionDescriptionX, Y, or Z Coordinate axisx h, y h, or z hx' h', y' h', or z' h'Coordinates of a point on the surfaceCoordinates of first focal pointx" h", y" h", or z" h" Coordinates of second focal pointsLENGTHHEIGHTLIST<strong>Reference</strong> PointAt location along coordinate axis of first pointSurface NormalRadially outward from the axisAutolimitingYes, if LENGTH or HEIGHT option is usedRemarksAngle in degrees of second focus (if it is moved toinfinity) relative to coordinate axisDistance from 3rd entryDistance from axisLists the coefficients of the second order curve1. Generates a surface by rotating an arbitrarily oriented conic curve about the given axis.

<strong>ASAP</strong> | Commands and Macros (A) | 392. Similar to the REVOLUTION command, except that the second order curve (whose coefficients can be LISTed) isdetermined from the foci of a conic.3. Since the surface obeys Fermat's principle, the distance (on any plane) from the first focal point to the secondfocal point through the surface is stationary (or constant).4. AXICONIC has two modes of operation:• The positions of the two foci can be specified, in which case, the value of s is irrelevant and the sign of sdetermines whether the sum or difference of the distances is stationary, that is, an ellipse or hyperbola.• The position of one focus only can be specified. In this case, the second focus is moved to infinity and sbecomes the angle (in degrees) it makes with the axis of symmetry. This form of the command is useful inconstructing compound parabolic concentrators.5. Specifies other end of curve with LENGTH or HEIGHT option.6. An optimal LOCAL box for the surface can be automatically created if 1) the other end of the curve is specifiedeither by an axial LENGTH (distance from 3rd entry), or 2) a HEIGHT (distance from axis). The program solvesa quadratic for the other coordinate taking the root closest to the first unprimed point (if there are no real roots,no box is created). TEST and PARAMETERIZ ation are also automatically set so that one branch (maybe not thedesired one) of the surface should mesh properly for PLOTting.Note: See the scripts, CPC_AXICONIC.inr and CPC_BEZIER.inr. located in <strong>ASAP</strong> on the Quick Starttoolbar, Interactive Scripts tab, under Lens Creation.AXICONIC ExamplesAXIS (<strong>ASAP</strong> Command)Selects the coordinate system in which future ray trace data is printed.Function• Define/Modify Surfunc Entities• Setup TraceSyntaxAXIS [ OFF ]XYZ-X-Y-ZLOCAL [ I ]OptionOFFLOCALDescriptionResets <strong>ASAP</strong> to the default global Cartesian coordinatesCauses data to be output in a local Cartesian coordinatesystem (see Remarks)X, Y, Z, -X, -Y, or -Z Reports ray trace data in cylindrical coordinate relativeto the specified axisIRemarksObject number or name1. Allows future ray positions to be printed (for example, with STATS POS) in either local and/or cylindricalcoordinates relative to the specified axis.

<strong>ASAP</strong> | Commands and Macros (A) | 402. AXIS applies only to surface-based objects.3. The origin of the local Cartesian coordinate system is the reference point of the object's first entity.4. LOCAL causes data to be output in a local Cartesian coordinate system whose origin is the reference point ofobject I's base identity. The default for I is each ray's current object.5. AXIS OFF should be run to reset <strong>ASAP</strong> to the default global Cartesian coordinates as soon as the use for AXISLOCAL is finished.6. If the axis designation is preceded by a minus sign, a local cylindrical coordinate system is used; that is, relative tothe axis.7. The cylindrical coordinates are R (radial distance from the axis), T (angle theta in degrees around the axis), andthe actual axial coordinate (X, Y or Z if positions, and A, B or C if directions).8. The combination of an AXIS LOCAL command and a window override on a SPOTS, RADIANT, OPDMAP,SPREAD, or FIELD command forces the distribution to be calculated in a local Cartesian coordinate system. Forexample:SPOTS POSITION YXAXIS LOCALSPOTS ...windowOPDMAPSPREADFIELDRADIANT ... MAPAREA9. To distinguish this from the global case, the coordinate axes in the header of the resulting distribution file (orfiles) are in lower case. Also, the Euler angles and positional offsets needed to transform the distribution back intoglobal coordinates are stored in the header. If a reference object is not specified on the AXIS LOCAL command,the distribution is in the local coordinates of the base entity associated with the object on which the first valid ray/beam resides.AXIS Examples

<strong>ASAP</strong> | Commands and Macros (B) | 41Commands and Macros (B)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “B”.BEAMS (<strong>ASAP</strong> Command)Sets the default coherence, propagation, and shape characteristics for future ray creation.Function• Setup Beam CreationSyntaxBEAMS [ INCOHERENT ] [ GEOMETRIC ] [ SHAPE k [ s ] ]COHERENT DIFFRACTOptionINCOHERENT or COHERENTGEOMETRIC or DIFFRACTSHAPEksDescriptionFlag for default coherence; see Remarks belowFlag for default propagationFlag for beam shape characteristicsHermite-Gaussian modeOptional Hermite-Gaussian mode dataRemarks1. Sets the default coherence, propagation, and shape characteristics for future beam creation, except for theEMITTING and SCATTER rays, which are incoherent, geometric, and of a fixed shape by definition.2. Refer to the SHAPE command for a detailed explanation of the arguments k and s.3. In most circumstances, the INCOHERENT option should be used with the GEOMETRIC option and theCOHERENT option with DIFFRACT option. This is the default if only one is specified. Although it is possibleto specify the other two "cross" combinations, the results can be unexpected and, therefore, useful in only a fewrare cases (for example, BEAMS COHERENT GEOMETRIC SHAPE FIBR/SLAB, for a non-diffracting, guidedmode).4. The default in the absence of a BEAMS command depends upon the WAVELENGTH and XMEMORY settings at thetime of the first ray/beam creation. If WAVELENGTH = 0 or XMEMORY MIN, then the default is INCOHERENTGEOMETRIC; otherwise it is COHERENT DIFFRACT.5. Once set, the BEAMS settings are not affected by future WAVELENGTH and XMEMORY commands unless a BEAMScommand with no arguments is issued.6. The COHERENT option automatically sets the WIDTHS parameter to 1.6, and INCOHERENT automatically setsthe WIDTHS parameter to 1.0. An information message is printed in the Command Output window.WARNING: Set values that are not defaults after the BEAMS command to avoid overwriting settings.BEAM Examples$BEEP (<strong>ASAP</strong> Macro)Causes computer to emit a beep.

<strong>ASAP</strong> | Commands and Macros (B) | 42Syntax$BEEP [ n [ s ] ]RemarksCauses the terminal or console to beep n times (default 1) with s seconds (default 0.00) between each beep.$BEEP ExamplesBEND (<strong>ASAP</strong> Command)Bends the last surface along a parabolic curve.Function• Define/Modify Surfunc EntitiesSyntaxBEND X c [ c' ]YZOptionX Y or Zc c'DescriptionAxis which is bentCurvature coefficients of the bendingRemarks1. Bends the surface (relative to its reference point) by replacing the given coordinate in its polynomial function witha quadratic in the other two coordinates, for example, for a BEND Z:2. The c coefficients are the curvatures (inverse radii) of the bending.BEND ExamplesNote: This operation may double the order of the polynomial.BEZIER (<strong>ASAP</strong> Command)Creates a Bezier edge/curve in the plane.Function• Define/Modify Curvedge EntitiesSyntaxBEZIER X x y y' c [ c' [ c" ... ] ]Y y z z'

<strong>ASAP</strong> | Commands and Macros (B) | 43Z z x x'OptionDescriptionX, Y or Z Coordinate axisx, y, or z Axial location of the planey y', z z' or x x'c c' c" ...RemarksRange of the segment in the planeOrder of the explicit polynomial that defines the Beziersegment (not more than 20)1. Creates a single Bezier segment in the plane.2. The order of the Bezier segment is the same as the order of the explicit polynomial given by the remainingcoefficients and must not exceed 20.3. For a segment in the Z=z plane, the exact equation of the curve is:4. This edge is a combination of coplanar straight line and higher-order curved segments.BEZIER ExamplesBIC (<strong>ASAP</strong> Command)The BIC command is used to create birefringent coating.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxBIC number_of_coating_layers [ 'name_of_coating' ]Thickness n1 n2 n3 theta psi phi (for uniaxial and biaxial layers)Thickness biaxial_media theta psi phi (for uniaxial and biaxial layers)Thickness n media (for isotropic layers)......Optionnumber_of_coating_layersDescriptionThe number of total layers in this coating, including bothisotropic and birefringent coatingn1, n2 and n3 Principal indices of the biaxial media, or existingisotropic media names (or numbers)biaxial medianmediaExisting biaxial media name (or number)Refractive index of an isotropic mediaExisting isotropic media name (or number)

<strong>ASAP</strong> | Commands and Macros (B) | 44Optiontheta, psi, phiDescriptionThickness Specified in µmRemarksEuler angles between the local surface coordinate systemat the intersection point and the principal coordinatesystem. The Z-X-Z Euler angle convention is used. Theyare in degrees.1. If no name is supplied by users, <strong>ASAP</strong> uses a default name starting with BIC, followed by the list index of thisBIC element in the system BIC element list. For example, the second BIC is named as BIC00002.2. The process of setting the Euler angles works as follows: at the beginning, the principle coordinate system of theMEDIA BIAXIAL media is completely aligned with the local surface coordinate at the intersection point; that is,X->n1(xp), Y->n2(yp), Z->n3(zp). First rotate the xp-yp-zp coordinate about the Z axis, then about X axis, andlast Z axis again to get the final orientation of xp-yp-zp relative to local surface coordinate.3. Users can define a biaxial media with MEDIA BIAXIAL to use the media name or biaxial media number, insteadof the principal refractive index numeric values in the BIC command.4. Since media numbers are permitted to define the principal indices, the refractive indices should be defined asfloating-point numbers with decimal points, and media numbers should be defined using integers without decimalpoints. Best practice for media references is to use the media name rather than media number.5. The layers are defined starting at the lower index side (usually air), as in the COATING LAYERS command.BIC ExamplesBICONIC (<strong>ASAP</strong> Command)Creates a cubic or quartic biconic surface.Function• Define/Modify Surfunc EntitiesSyntaxBICONIC X x r r' k k' [ 3 ] [aperture... ]Y y 4Z zq6OptionDescriptionX, Y or Z Axis of symmetryx, y or z Location along axisr r'Vertex radii of curvaturek k'Conic constants (0 circle, -1 parabola, etc.)3 or 4 Specifies implicit cubic or explicit quartic surfaceapertureELLIPSE, RECTANGLE, or HEXAGONALqCross-section control factor6 6th order biconic surface

<strong>ASAP</strong> | Commands and Macros (B) | 45<strong>Reference</strong> PointAt intersection of the surface and coordinate axis.Surface NormalAlong positive coordinate direction.Remarks1. Creates a cubic (default), quartic, or 6th-order biconic surface with a given vertex radii of curvature (r,r') andconic constants (k,k').2. The second entry designates the axis of symmetry (either X, Y, or Z) for the surface.3. In the case of Z, the actual equations of the surfaces are given by,Implicit Cubic (3):Explicit Quartic (4):c=1/rc'=1/r'e=(1+k)ce'=(1+k')c'x^2=cX^2y^2=c'Y^2The two representations differ in how they blend the two conic profiles together. (See remarks below and theUSERSAG command for other distinct blendings).If e(Z-z) and e'(Z-z) are much less than one, the differences between the two versions are normally negligible.However, the cubic is also conic (usually an ellipse) in any plane perpendicular to the given axis, and its rayintersection is more robust. The quartic profile remains a conic in any plane containing the axis, but it degenerateson-axis when converted to implicit polynomial form.4. Two additional alternatives to the implicit exist: a) a quartic that blends the conic profiles using a cross-sectionalcontrol factor q between 0 (elliptical cross-section) and 1 (rectangular), inclusive. b) a 6th-order singularity-freeimplicit approximation to the standard explicit that will only differ (usually negligibly) near the diagonals. In mostcases, the latter is the preferred equivalent to the biconic surface found in most lens design programs.BICONIC ExamplesBILATERAL (<strong>ASAP</strong> Command)Folds data around a coordinate axis/axes to reduce the number of rays needed for a calculation where symmetry isexpected.Function

<strong>ASAP</strong> | Commands and Macros (B) | 46• Modify Ray/Beam DataSyntaxBILATERAL POSITION X [ Y,Z ]DIRECTION Y [ X,Z ]Z [ Y,X ]OFFOptionPOSITIONDIRECTIONX Y ZOFFDescriptionFolds positional ray dataFolds directional ray dataCoordinate axesTurns off previous BILATERAL settingsRemarks1. In systems with bilateral symmetry, the BILATERAL command and its options can be used to reduce the numberof rays traced, and still produce meaningful plots from the SPOTS command.2. Any ray, whose data specified by the second and third option (POSITION, DIRECTION) is negative, is mirrorimagedabout the zero coordinate plane, so that the particular data becomes positive.3. For systems with symmetrical quadrants, two coordinate directions should be entered.BILATERAL ExamplesBIN (<strong>ASAP</strong> Command)Apply to an OBJECT to mark it as a Conformal Radiometer.SyntaxBINOptionNo options applyDescriptionRemarks1. The BIN command tracks light interacting with the object for post-TRACE visualization and analysis.2. The BIN command takes no options.BIN ExamplesBOUNDS (<strong>ASAP</strong> Command)Assigns surfaces and edges as boundaries to objects.Function• Create/Modify Objects

<strong>ASAP</strong> | Commands and Macros (B) | 47SyntaxBOUNDS [ k [ k' ... ] [ MULTIPLE m [ m '... ] ] ] [ POINT x y z ]RBOUNDS OFFOptionk k'MULTIPLE m [ m' ... ]POINT x y zRBOUNDS OFFDescriptionNumbers of the surface and/or edge entitiesMakes a group of surfaces/edges equivalent to onestandard constraintMakes point x y z a valid point on the objectTemporarily turns off all boundary surfaces for thecurrent objectRemarks1. The k's are the numbers of the surface and/or edge entities that are used to define the boundaries of the object.If these numbers are positive, the valid object is assumed to be on the positive side of the corresponding entity,outside the surface's SOLID or outside the closed edge. A negative number means that the valid object is on theentity's negative side, inside the surface's SOLID or inside the edge.BOUNDSEdge Effect+ Object is assumed to be on positive side of thecorresponding surface, outside the surface's SOLID oroutside the closed edge.- Object is on the surface's negative side, inside thesurface's SOLID or inside the edge.2. The MULTIPLE option makes a group of surfaces/edges equivalent to one standard constraint; in other words, apoint that is valid for of any of one or more of the given m bounds is a valid object point. This behavior is similarto a Boolean OR operation. The valid surface is the region defined by the union of all the bounding edges, m,m’…3. To efficiently enter a very large number of boundaries, use the RBOUNDS version, where every pair of ks or msspecifies a range of entity numbers instead of individual entities.4. The POINT option to force point x y z to be a valid point on the object.5. A BOUNDS OFF command can be used to temporarily turn off all boundary surfaces for the current object. ABOUNDS command by itself turns them back on.6. Use the DIMENSION command to determine the maximum number of bounding surfaces that may be applied to agiven object.7. BOUNDS is used for more sophisticated surface boundaries. For very simple bounding of an object the LIMITScommand can be used.BOUNDS ExamplesBRANCH (<strong>ASAP</strong> Command)Provides an easy method of naming objects in a hierarchical fashion. Each name specifies a new level in thehierarchy.Function• Create/Modify Objects

<strong>ASAP</strong> | Commands and Macros (B) | 48SyntaxBRANCH [ name ].name^^.nameRemarks1. Specify an absolute or relative branch of the object name tree for future object definitions and display the currentor new full branch name.2. Periods (.) are used as node separators in the name. Carets (^) are used to move up one node. If the entry beginswith either of these two characters, then the branch is defined relative to the current branch.3. Otherwise, it is an absolute complete branch specification (with possibly many embedded periods).4. The number of levels is limited by the total object name length, which is 344 characters.5. The wildcard designator can be used to select all objects; for example, BRANCH NAME.?, selects all objectswhose name contains the specified root.BRANCH ExamplesBSDFDATA (<strong>ASAP</strong> Command)Indirectly or directly interpolates from entered BSDF (Bidirectional Scattering Distribution Function) values.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax 1 - Indirect (isotropic) interpolationBSDFDATA [ n ] [ d ][options…] [ PLOT [ a a' ... ] ]RAWDATAdata…:Syntax 2 - Direct (anisotropic) interpolationBSDFDATA X U R [ d ] [ options ... ]RAWDATA Y V TZ W A:data ...:OptionndPLOTa a' ...X,Y,ZDescriptionCollapsed 4D direction spaceSmall directional distance (default 0.001 radians)Plots the model in log(b-bo) and angle spaceUser-defined degree specular anglesSee the command argument, MODEL

<strong>ASAP</strong> | Commands and Macros (B) | 49OptionU,V,WR,T,Aoptions...data...DescriptionThe command argument, ANGLES specifies data input inpolar and azimuthal angles.COS provides a cosine correction to a data set.See Remarks for this optionRemarks1. BSDFDATA values are logarithmic; RAWDATA values are linear.2.In general, a BSDF is a 4D (four-dimensional) function, and is the function of incident angles, and and thescattering angles and defineandwhereFor isotropic models, it is assumed that then .Note: Variables T, U, V, and W are used in <strong>ASAP</strong> BSDFDATA models.3. Indirect (isotropic) interpolation:• The four-dimensional direction space is collapsed to just n (default 2) dimensions that enforce isotropicsurfacesymmetry and reciprocity (see the BINOMIAL model).Note: <strong>ASAP</strong> does not automatically enforce isotropic symmetry and reciprocity. You must assuresuch properties for the supplied BSDF data.• The d is a small directional distance (default 0.001 radians) in each collapsed dimension that is used todetermine if two input data points have collapsed to the same nD point. The BSDF or log(BSDF) (RAWDATAor BSDFDATA, respectively) is then interpolated as a function of these n directional coordinates:n Coordinates Interpolation1 sqrt(T) linear2 sqrt(T), V bilinear triangular

<strong>ASAP</strong> | Commands and Macros (B) | 50n Coordinates Interpolation3 U,V,W nearest point or reciprocal pointFor isotropic models,The and correspond to the scatter angles around (azimuthal) and from (polar) the normal, and isthe specular angle from the normal.• <strong>ASAP</strong> uses the data point check procedure shown below. For instance, to collapse into a 2D data set, if bothwhere subscript c and i mean current data point and data points stored in the BSDF database, <strong>ASAP</strong> assumesthat the current data entry is the same as the ith point in the data points.• If <strong>ASAP</strong> determines that the user-supplied data set has multiple entry BSDF values for the same point in thecollapsed space, <strong>ASAP</strong> uses the averaged BSDF value among these multiple entries as the BSDF value for thatpoint.• The use of a negative value for d (d

<strong>ASAP</strong> | Commands and Macros (B) | 51For applications of coating models, data is formatted:•For isotropic BSDF scatter models, must be 0.• Several BSDF models allow fitting to or interpolation from actual data. See the command argument, ANGLESfor common options and format.• The PLOT option plots the model (common base 10 logarithm of the BSDF) for up to seven specular anglesin ascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls theresolution of these plots in direction cosine space.• Creates a distribution file name_angle.dis for each of these angles.• The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.• Works with a single normal-incidence scan.• Processed points are written TO and read FROM SYSTEM file.BSDFDATA Examples

<strong>ASAP</strong> | Commands and Macros (C) | 52Commands and Macros (C)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “C”.CADEXPORT (<strong>ASAP</strong> Command)Writes out CAD-compatible system geometry file.Function• Save or Recover System DataSyntaxCADEXPORT [ IGS [ name ] ] [ p a ]CADEXPORT DXF [ name [ block ] ]CADEXPORT VCR [ name ]CADEXPORT TRACE [ name [ vcr ] ]OptionIGSDXFVCRTRACEnameblockvcrpaDescriptionWrites current geometry to an IGES file (the default)Writes current geometry to an AutoCAD DXF file usingAutoCAD 12 file formatReads geometry and rays from the current VCR file andwrites it to a DXF fileReads only the rays from a named VCR file and writes itto an IGES fileNames the output file to be writtenHolds the DXF file standards in the named fileNames the VCR file from which ray data will be read bythe TRACE optionThe three-dimensional positional tolerance for IGESoutput, in system unitsThe angular tolerance for IGES output, in degreesRemarks1. Writes a 3D CAD surface representation of the currently considered objects, or the 3D graphics in a VCR file, orjust the rays from the latest TRACE PLOT.2. CADEXPORT supports the fixed IGES IGS (the default) and AutoCAD 12 DXF file standards (including theoption to put everything into a named block). The file created is name followed by one of these extensions: IGSfor IGES or DXF for AutoCAD 12.3. CADEXPORT does not export a deformed surface that is produced in <strong>ASAP</strong> after a DEFORM command. The basesurface that is before DEFORM does export. Use the DEFORM command for phase / wavelength-level deformationsto base surfaces only in <strong>ASAP</strong>.

<strong>ASAP</strong> | Commands and Macros (C) | 534. The DXF and VCR options create DXF files; however, the DXF option converts from "system" geometry ratherthan the vector (VCR) file. BRO recommends you use the VCR option for DXF files to insure all trimming isconverted.5. Trimming information (LIMITS, LOCAL, BOUNDS) is translated as of <strong>ASAP</strong> 2006 V1R1. BOUNDing entitiesmust have limiting apertures.6. Limitations on surface export are:• Advanced surface effects (REDEFINE SURF/NORM, DEFORM) are not translated.• IGS usually requires that the system UNITS must have been set.• All base surfaces in DXF are, by necessity, approximated by facets.• LENS, connected CURVE/EDGE, and SAMPLED base surfaces are exported exactly to IGES. Since no CADstandard supports general algebraic surfaces, all other SURFACES are approximated by cubic spline patches orrevolved cubic spline curves when possible.7. The TRACE option extracts ray trajectories from a VCR file vcr (<strong>ASAP</strong>TEMP.VCR by default), and writes therays to an IGES file name (<strong>ASAP</strong>TEMP.IGS by default).CADEXPORT ExamplesCARTOVAL (<strong>ASAP</strong> Command)Creates a Cartesian oval surface.Function• Define/Modify Surfunc EntitiesSyntaxCARTOVAL X x d n d' n' [ aperture... ]Y yZ zOptionDescriptionX, Y, or Z Specifies axis of symmetryx, y, or z Location along axis of symmetrydnd'n'aperture<strong>Reference</strong> PointAt intersection of surface and coordinate axisSurface NormalAlong positive coordinate directionRemarksDistance from surface to first focus pointRefractive index of first mediumDistance from surface to second focus pointRefractive index of second mediumELLIPSE, RECTANGLE, or HEXAGONAL1. Creates a Cartesian Oval surface at the given location on the given axis.2. The second entry designates the axis of symmetry (either X, Y, or Z) for the surface.

<strong>ASAP</strong> | Commands and Macros (C) | 543. The surface perfectly images an axial point a distance d in the first medium of index n into an axial point adistance d' in the second medium of index n'4. This surface can extend to infinity unless a LOCAL command follows, or a trailing aperture option of thefollowing form is specified:ELLIPSE a [ a' [ o [ s [ s' ] ] ] ]RECTANGLEHEXAGONAL a [ o [ s [ s' ] ] ]5. a a' are the heights in the other two transverse directions.6. For the HEXAGONAL form, a is the center-to-vertex distance (maximum height).7. o is an optional central hole ratio.8. s s' are the transverse coordinates of the center of the aperture.CARTOVAL Examples$CASE (<strong>ASAP</strong> Macro)Specifies case sensitivity.Syntax$CASE [ UPPER ]LOWERBOTHRemarks1. Macro instructs the parser to recognize only UPPER- or LOWER-case letters or BOTH.2. The case of the prompt displayed below the <strong>ASAP</strong> Command Input window reflects the setting of the $CASEmacro.3. If no argument is given on the command, the state before the last $CASE command is restored.4. Letters opposite in case to that set by the $CASE command can also be used as embedded comments, sincethe program treats them as blanks. Trailing comments can be entered after an exclamation point "!", since thischaracter signals the program to stop decoding input from the command.5. Opposite case letters: treated as blanks.6. Last entry, stop parsing: exclamation point.7. When using lower case for comments, do not include underscores "_" as these are treated as upper case andgenerate an "Unrecognized command or macro" error.$CASE ExamplesCHARACTER (<strong>ASAP</strong> Command)Creates an edge of a specified string.Function• Define/Modify Curvedge EntitiesSyntaxCHARACTER X x y [ z ] string

<strong>ASAP</strong> | Commands and Macros (C) | 55Y y z x 'string'Z z x yOptionDescriptionX, Y or Z Character planex, y or z Character plane locationy, z or x Character widthz, x or y Character height (defaulted to the width)string or 'string'<strong>Reference</strong> PointFirst point of characterRemarks1. Creates an edge patterned after the character string.2. This edge is a combination of coplanar straight line segments.CHARACTER ExamplesEdge character stringCHROMATICITY (<strong>ASAP</strong> Command)Calculates CIE tristimulus (XYZ) values and chromaticity (x,y) coordinates.Function• Analyze Ray/Beam DataSyntax 1CHROMATICITY INTENSITY|IRRADIANCE [SOM] [resolution] [NORM TF|MX|MY|MZ|CX|CY|CZ|AX|AY|AZ|nflux|xn, yn, X|Y|Z]Syntax 2CHROMATICITY RADIANT|RADIANCE [SOM] [resolution] [ANGLE X|Y|Z f f' na a' n'] [NORM TF|MX|MY|MZ|CX|CY|CZ|AX|AY|AZ|nflux|xn, yn, X|Y|Z]OptionCHROMATICITY INTENSITY/IRRADIANCECHROMATICITY RADIANT/RADIANCESOMresolutionDescriptionCalculates the chromaticity with radiance in the spatialcoordinate system, using the most recent WINDOW andPIXELS settings.Calculates the chromaticity within the sphericalcoordinate system.Standard observer model for this colorimetry analysisconfiguration can be 1931 for 1931 2-degree observermodel or 1964 for 10-degree observer model.Wavelength resolution (in units of nm) for thisconfiguration. Must be an integer greater than 1. The

<strong>ASAP</strong> | Commands and Macros (C) | 56OptionANGLE X|Y|Zf f'na a'n'NORMTFMX, MY, MZCX, CY, CZAX, AY, AZX|Y|ZDescriptionbuilt-in color matching functions for both the 1931 and1964 SOM standard are from 360nm to 830nm in 1nmresolution.Polar angleStarting and ending polar (zenith/latitudinal) anglesNumber of polar subdivisions, must be 1 forCHROMATICITY RADIANCE optionStarting and ending azimuthal (longitudinal) anglesNumber of azimuthal subdivisions; must be 1 forCHROMATICITY RADIANCE optionNormalization method for the tristimulus values.Currently, there are 14 ways to normalize XYZ values. IfNORM is not present, the default normalization method isthat the calculated tristimulus values are not normalized.If present, it must be in one of the following forms:Normalization by the total flux of the rays used in thetristimulus calculationNormalization by the maximum values of the tristimulusvalues of X, Y, Z valuesNormalization by the X, Y, Z tristimulus values of thecenter pixelNormalization by the average values of tristimulusvalues of X, Y, Z nflux: normalization by the userspecifiedflux value, xn, yn: the spatial coordinate (x, y)in the sampling window of the pixel whose value is usedfor normalizationX, Y, Z tristimulus value of the normalization pixelRemarks1. CHROMATICITY INTENSITY calculates the tristimulus values and chromaticity coordinates in a directioncosine coordinate system. The Y tristimulus value is computed in a direction cosine coordinate system, and it canbe converted to an angular coordinate system by using the ANGLES display modifier. The other components arecomputed in a direction cosine coordinate system; therefore, do not use the ANGLES display modifier, since itapplies a cosine modification to the distribution.2. CHROMATICITY IRRADIANCE calculates the tristimulus values and chromaticity coordinates in a spatialcoordinate system.3. CHROMATICITY RADIANT calculates the tristimulus values and chromaticity coordinates in a polar sphericalcoordinate system.4. CHROMATICITY RADIANCE calculates the tristimulus values and chromaticity coordinates in a radianceformat; the spatial component is set with the current WINDOW and PIXEL settings, and the angular componentuses a polar spherical coordinate system that is set with the ANGLE option. See the RADIANT command for adescription of the ANGLE option.When using CHROMATICITY RADIANT, the ANGLE parameters set the angular sampling window for both polarand azimuth angles. When using CHROMATICITY RADIANCE, the ANGLE parameter sets the sampling solidangle. Typically, the angular resolution for both polar and azimuth angle is set to a number greater than one (>1)for CHROMATICITY RADIANT and exactly one (=1) for CHROMATICITY RADIANCE.

<strong>ASAP</strong> | Commands and Macros (C) | 575. If existing settings of SOM and/or the wavelength resolution of the current colorimetry analysis configuration aredifferent from the new settings, all colorimetry analyses performed in this configuration are automatically updatedwith the new SOM and/or wavelength resolution. These analyses include Lab, RGB, and LUV.6. The CIE tristimulus (XYZ) and chromaticity coordinate (xy) values are calculated and saved in the distributionfile named as CIEXYZxy_ followed by the configuration name as entered on the most recent CIE command. Theorder of the tristimulus values and chromaticity coordinates in a data record of the output distribution file is X,Y, Z, x, y. Use DISPLAY "CIEXYZxy_CIE_configuration_name" 1ST through 5TH to access desiredinformation.7. Multiple tristimulus value calculations (performed by multiple CHROMATICITY commands) can be carried outon a colorimetry analysis configuration.8. See the topic, "SOM Option Matrix for CIE-CHROMATICITY Commands".SOM Option Matrix for CIE-CHROMATICITY CommandsThis topic describes the SOM options matrix. The CIE command is intended to provide a single place to define userconfigurations of color calculations. The CHROMATICITY command is one type of color analysis that is controlledby the configuration, and others follow.SOM Options MatrixCIE Setting CHROMATICITY Setting ResultNone None 1964None 1964 1964None 1931 19311964 None 19641964 1964 19641964 1931 19311931 None 19311931 1964 19641931 1931 1931Summary• The 1964 SOM is the default result if no SOM option is specified on either the CIE or CHROMATICITYcommand.• If a SOM is specified with the CIE command, but is not specified with the CHROMATICITY command, the CIEoption is used.• If a SOM is specified with the CHROMATICITY command, the specification on the CHROMATICITY commandoverrides that of the CIE command.Note: BRO recommends as a best practice to specify the SOM option on the CIE command. The overridingbehavior of the SOM option with theCHROMATICITY command should be used as an exception to your usualworkflow.CIE-CHROMATICITY Resolution OptionsThe logic that coordinates the Resolution inputs to the CIE and CHROMATICITY commands is similar to the logicused for the SOM option:• A 5-nm resolution is the default result if no Resolution option is specified on either the CIE or CHROMATICITYcommand.

<strong>ASAP</strong> | Commands and Macros (C) | 58• If the Resolution option is specified with the CIE command only (that is, none is specified with theCHROMATICITY command), the Resolution option of the CIE command is used.• If Resolution is specified with the CHROMATICITY command, the specification on the CHROMATICITYcommand overrides that of the CIE command.CIE (<strong>ASAP</strong> Command)Creates a new colorimetry analysis configuration or recalls an existing colorimetry analysis configuration.Function• Analyze Ray/Beam DataSyntax 1CIE NEW [SOM] [resolution] [‘name’]Syntax 2CIE ID|name [SOM] [resolution]OptionSOMresolutionnameIDDescriptionThe standard observer model for this colorimetryanalysis configuration can be 1931 for the 1931 2-degreeobserver model, or 1964 for the 10-degree observermodel. The default is the 1964 10-degree observermodel.The wavelength resolution (in unit of nm) for thisconfiguration. Must be an integer greater than 1. If notspecified, the default resolution is 5nm. The built-incolor matching functions for both 1931 and 1964 SOMare from 360nm-830nm in 1nm resolution.Name of this colorimetry analysis configuration. It mustbe no longer than 40 characters and is case insensitive.If no name is specified, <strong>ASAP</strong> uses the default name inthe form of CACXXXXX, where XXXXX is the indexof the configuration. The configuration can be retrievedby its name or its index in the defined configuration list.The index of the colorimetry configuration that the userwants to retrieve.Remarks1. Before any colorimetry analysis, a colorimetry analysis configuration must be created. The default maximumnumber of colorimetry analysis configurations in <strong>ASAP</strong> is 25; users can change this with SET MNCC to anynumber.2. The normal work flow of <strong>ASAP</strong> colorimetry is similar to the traditional four-step <strong>ASAP</strong> work flow, except theanalysis step replaced by the colorimetry analysis step.3. As in classic <strong>ASAP</strong> radiometric analysis, specific ray set can be selected in <strong>ASAP</strong> colorimetry analysis with theSELECT command, and interested objects can be selected with the CONSIDER command. Also, the parameters

<strong>ASAP</strong> | Commands and Macros (C) | 59of analysis window can be set with WINDOW and PIXEL commands. These parameters must be set before CIEanalysis can be performed.4. The analysis results are saved to distribution files denoted with its configuration name. For example,the CIEtristimulus and chromaticity coordinate values generated by a CHROMATICITY command are saved in adistribution file named as CIEXYZxy_ followed by the configuration name entered on the most recent CIEcommand.5. For any colorimetry analysis configuration, the wavelengths of sources must be in units of nm.6. Syntax 2 is used to recall or modify an existing colorimetry analysis configuration.7. If a configuration is recalled with a different SOM or different wavelength resolution other than its previoussettings, all colorimetry analysis performed in this configuration is automatically updated with the new SOM and/or wavelength resolution.8. See the topic, "SOM Option Matrix for CIE-CHROMATICITY Commands".SOM Option Matrix for CIE-CHROMATICITY CommandsThis topic describes the SOM options matrix. The CIE command is intended to provide a single place to define userconfigurations of color calculations. The CHROMATICITY command is one type of color analysis that is controlledby the configuration, and others follow.SOM Options MatrixCIE Setting CHROMATICITY Setting ResultNone None 1964None 1964 1964None 1931 19311964 None 19641964 1964 19641964 1931 19311931 None 19311931 1964 19641931 1931 1931Summary• The 1964 SOM is the default result if no SOM option is specified on either the CIE or CHROMATICITYcommand.• If a SOM is specified with the CIE command, but is not specified with the CHROMATICITY command, the CIEoption is used.• If a SOM is specified with the CHROMATICITY command, the specification on the CHROMATICITY commandoverrides that of the CIE command.Note: BRO recommends as a best practice to specify the SOM option on the CIE command. The overridingbehavior of the SOM option with theCHROMATICITY command should be used as an exception to your usualworkflow.CIE-CHROMATICITY Resolution OptionsThe logic that coordinates the Resolution inputs to the CIE and CHROMATICITY commands is similar to the logicused for the SOM option:• A 5-nm resolution is the default result if no Resolution option is specified on either the CIE or CHROMATICITYcommand.

<strong>ASAP</strong> | Commands and Macros (C) | 60• If the Resolution option is specified with the CIE command only (that is, none is specified with theCHROMATICITY command), the Resolution option of the CIE command is used.• If Resolution is specified with the CHROMATICITY command, the specification on the CHROMATICITYcommand overrides that of the CIE command.$CLEAR (<strong>ASAP</strong> Macro)Clears the output buffer so that the scope of future $GRAB commands is limited to only the output that follows.Syntax$CLEAR$CLEAR ExamplesCLIP (<strong>ASAP</strong> Command Argument)Clips the distribution data according to an object or edge.Function• Standard Plot OptionsSyntax... CLIP [ i ]+j-jOptioniDescriptionSpecified OBJECT+j Exterior of the specified closed EDGE-j Interior of the specified closed EDGERemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. The clipping may be specified by the limits or bounds of OBJECT i the exterior of closed EDGE +j or the interiorof closed EDGE -j3. Use the command argument, CLIP on the SPOTS, OPDMAP, SPREAD, or FIELD commands to clip thedistribution data during the calculation. This option clips the distribution by either the specified LIMITS/BOUNDS of OBJECT i, or the given side of entity j.4. A minus (-) symbol means the interior of a closed EDGE or the negative side of a SURFACE. A plus (+) symbolmeans the exterior of a closed EDGE or the positive side of a SURFACE.5. Data points outside the specified regions have their distribution values set to zero.CLIP ExamplesCLIP (<strong>ASAP</strong> Command)Specifies positional or directional ray limiting or clipping boxes.Function

<strong>ASAP</strong> | Commands and Macros (C) | 61• Setup Beam CreationSyntax 1CLIP POS x x' [ y y' z z' ] [ X [ f ] ] POSITIONDIR a a' b b' c c' Y DIRECTIONZSHORTESTLONGESTNORMALSyntax 2CLIP POS [ OFF ] POSITIONDIR AXIS X [ f ] ] DIRECTION-X x Ya Z-Y y SHORTESTb LONGEST-Z z NORMALc OFF+X x'a'+Y y'b'+Z z'c'EXPAND rX rYZOptionPOSITION or DIRECTIONx x' y y' z z'a a' b b' c c'X Y ZfSHORTESTLONGESTNORMALOFFEXPANDDescriptionType of ray clippingLower and upper POSITIONal clipping entriesLower and upper DIRECTIONal clipping entriesSpecifies cylindrical (as opposed to rectangular) clippingSpecifies fractional holeSelects clipping axis according to shortest clip boxdimensionSelects clipping axis according to longest clip boxdimensionSelects clipping axis of the bounding ellipsoidal cylinderaligned to the longest component of surface normal forthe clipping entity or objectTurns off cylindrical clippingScales clipping box by relative amount rRemarks

<strong>ASAP</strong> | Commands and Macros (C) | 621. The CLIP command is useful for restricting propagation directions of entity rays to improve the ray traceefficiency.2. If initialized, positional clipping is done in all cases except the single RAY command. Directional clipping is doneonly for SOURCE DIRECTION GRID, EMITTING, and DECOMPOSE commands.3. The command specifies the POSITIONal or DIRECTIONal (direction cosines) limits for boxes clipping raysduring ray creation. Any ray with coordinates falling outside the specified clipping box is not created. Theunprimed entries are the lower bounds of the box; primed entries, the upper bounds.4. If a coordinate direction (that is, X, Y, Z) is specified, the coordinates are constrained by a cylinder of constantelliptical (as opposed to rectangular) cross section in planes perpendicular to the given axis. The SHORTEST,LONGEST, or NORMAL limit box dimension can also determine this axis.Note: NORMAL only: The chosen axis corresponds to the longest component of the surface-normal of theCLIPping object or entity, in the vicinity of the center of that object or entity. This is intended for usewith only simple <strong>ASAP</strong> surfaces. The CLIPping object cannot be faceted, or an error results.5. An optional inner boundary of fractional height f (default zero) may be used to put a proportional hole in the givencoordinate direction.6. The short form can also be used to temporarily turn OFF future clipping or reset all or any one of the six AXISlimit values.Note: POS and DIR are truncations of the POSITION and DIRECTION. Best practice is no truncation.7. EXPAND can be used to enlarge (or shrink) by a relative amount r the entire limits box or just in one direction, thatis, EXPAND -.1 shrinks the entire box by 10 percent.8. For CLIP POSITION, more complex ray bounding can be done by following it with the BOUNDS commandsyntax.CLIP ExamplesCOARSEN (<strong>ASAP</strong> Command)Converts the current edge to a piecewise linear curve.Function• Define/Modify Curvedge EntitiesSyntaxCOARSEN [ m ]OptionmDescriptionUse every mth pointRemarks1. Converts the current edge to a piecewise linear curve using every mth (default 1) point. This is the opposite of theSMOOTH command.COARSEN ExamplesCOATINGS LAYERS (<strong>ASAP</strong> Command)Creates a coating specified by its multilayer prescription.Function• Create/Modify Media, Coatings, Scatter Models

<strong>ASAP</strong> | Commands and Macros (C) | 63SyntaxCOATINGS [ k ] LAYERS [ w [ a ] ]d m [ d' m' d" m" ... ] [ 'name' ]:Optionkwad d' d" ...m m' m" ...DescriptionStarting coating number<strong>Reference</strong> wavelength in vacuumAngle of incidence (degrees)Layer thicknessesMedia numbers (or names)Remarks1. Specifies coatings on the basis of their actual layer structure.2. The default value of k is one more than the largest coating number defined and is set to 1 at start of programprocessing.3. The layer thicknesses d are entered in fractional optical waves if reference (vacuum) wavelength w is entered. Thea is the angle of incidence at which the thicknesses are desired; the default for a is zero (normal incidence).4. The layer thicknesses d are entered in absolute WAVELENGTH units if reference wavelength w is absent.5. Since the MEDIA command can define complex refractive indices at several wavelengths, the effects of absorptionand dispersion in each layer can be modeled precisely.6. Groups of layers may be replicated any number of times by following a set of layer definitions with a negative d(the magnitude of d is the number of previous layers to replicate) and positive m (the number of times the layersare to be replicated).7. Layers are defined from the low index side (usually the air side) to the high index side (usually the substrate side).<strong>ASAP</strong> flips the coating prescription as needed so the same coating may be applied to both sides of a lens.8. The maximum number of unique LAYERS is 100.9. <strong>ASAP</strong> can use the transmission (or reflection) values from a COATING PROPERTIES table or calculate thecoefficients from a COATINGS LAYERS table (based on the normal incidence form of Fresnel's formulae) todetermine the optical properties of a given object INTERFACE.COATINGS ExamplesCOATINGS MODELS (<strong>ASAP</strong> Command)Creates a coating specified by the angular properties for reflection and transmission.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxCOATINGS [ k ] MODELS i j m nr t r' t' r" t" ... [ 'name' ]:COATINGS [ k ] MODELSr i j t m n r' i' j' t' m' n' r" ... [ 'name' ]:

<strong>ASAP</strong> | Commands and Macros (C) | 64Optionkr r' r" ...t t' t" ...DescriptionStarting coating numberReal energy (or complex amplitude) reflectancesReal energy (or complex amplitude) transmittancesRemarks1. Starting with coating k coatings with real energy (or complex amplitude) reflectances r and transmittances t areentered.2. The default value for k is one more than the largest coating number defined and is set to one at the start of programprocessing.3. Separate angular properties can be specified by using previously defined (usually RAWDATA or BSDFDATA)MODELS where:ijmnModel for reflected S polarizationModel for reflected P polarizationModel for transmitted S polarizationModel for transmitted P polarization4. Anisotropic surface models are allowed in this context.5. Optionally, groups of six numbers can be entered so that each group corresponds to a wavelength entered on thelast multiple WAVELENGTH(S) command. For example, the actual reflectivities and transmissions at an incidenceangle a and a wavelength v between the first two WAVELENGTH(S) w w' would be:6. In the above equations, r, r' and t, t' are the entered complex amplitudes or the square roots of the real energycoefficients. The f is a normalized angular amplitude:COATINGS Examples

<strong>ASAP</strong> | Commands and Macros (C) | 65COATINGS PROPERTIES (<strong>ASAP</strong> Command)Creates a coating specified by its transmissive and reflective properties.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxCOATINGS [ k ] [ PROPERTIES ]r [ t r' t' r" t" ... ] [ 'name' ]:Optionkr r' r" ...t t t" ...'name'DescriptionStarting coating numberReal energy (or complex amplitude) reflectancesReal energy (or complex amplitude) transmittancesString for the name is limited to 16 charactersRemarks1. The default value of k is one more than the largest coating number defined, and is set to 1 at the start of programprocessing.2. If more than one pair of data is entered, the coefficients correspond to the wavelengths entered on the lastWAVELENGTHS command.3. <strong>ASAP</strong> linearly interpolates, if necessary, to obtain the coefficients at any desired wavelength.4. <strong>ASAP</strong> can use the transmission (or reflection) values from a COATING PROPERTIES table or calculate thecoefficients from a COATINGS LAYERS table (based on the normal incidence form of Fresnel's formulae) todetermine the optical properties of a given object INTERFACE.5. <strong>ASAP</strong> then interpolates (linearly in complex amplitude) to get the coefficients at any desired wavelength. Forexample, the actual reflectivities and transmissivities at a wavelength v between the first two WAVELENGTHS w w'would be,The rs and ts in the above equations are the entered complex amplitudes, or the square roots of the real energycoefficients.COATINGS ExamplesCOLLECTION (<strong>ASAP</strong> Command)Calculates the collection PERCENT efficiency or FLUX of the current rayset.Function• Analyze Ray/Beam Data

<strong>ASAP</strong> | Commands and Macros (C) | 66SyntaxCOLLECTION [ PERCENT ELLIP HEIGHT m ANGLE n a ]FLUX RECT AREA SINE MAXGCFOMEGAOptionDescriptionm Number of spatial samples (default 100)n and aNumber of direction samples up to the angle a in degrees(default 90 or rayset MAX)HEIGHT Geometric-mean height of the RECTangle or ELLIPse (0to MAX )AREAFunctional Coordinates:SINE Sine of the angle (0 to 1)Actual area of the RECTangle or ELLIPse (0 to full area)GCF Sine squared of angle (0 to 1)OMEGAMAXSolid angle (0 to 2 pi)Maximum raysetRemarks1. Calculates the collection PERCENT efficiency or FLUX of the current ray set for m (default 100) spatial samplesand n (default 90) direction samples up to the angle a in degrees (default 90 or rayset MAX). The spatial limits aredetermined from the current WINDOW setting and are either its full RECTangle or the inscribed ELLIPse.2. The first choice listed for each literal item is its default if it is left off the end of the command. The result is writtento the default distribution file (BRO009.DAT), and can then be processed by the DISPLAY command and itssubcommands.COLLECTION ExamplesCOLORS (<strong>ASAP</strong> Command Argument)Sets color for current graphics commands.Function• Standard Plot OptionsSyntax... COLORS k [ k' ... ]OptionDescriptionk k' ... Color number (1 through 27)Remarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.

<strong>ASAP</strong> | Commands and Macros (C) | 672. Entities displayed during the current command are plotted in only the colors given instead of any default coloring.Remember that the maximum color number 27 (or 0) is equivalent to the background and can be used for erasingin the graphics display.3. Use the command argument, COLORS with any of the following PLOT commands: EDGES, LENSES,SURFACES, LOCALS, ENTITIES, TRACE, SPOTS, and CURVES.4. <strong>ASAP</strong> uses a palette of 27 colors to display graphics. The table summarizes the colors and their associated red/green/blue (RGB) values. A reference to an example is given after the table.Number Color Name RGB Value1 Reverse video (1.00, 1.00, 1.00)2 Red (1.00, 0.00, 0.00)3 Light blue (0.00, 0.60, 1.00)4 Orange (1.00, 0.60, 0.00)5 Yellow (1.00, 1.00, 0.00)6 Purple (0.50, 0.00, 1.00)7 Sea green (0.00, 1.00, 0.60)8 Maroon (1.00, 0.00, 0.50)9 Cyan (0.00, 1.00, 1.00)10 Chartreuse (0.60, 1.00, 0.00)11 Blue (0.00, 0.00, 1.00)12 Magenta (1.00, 0.00, 1.00)13 Green (0.00, 1.00, 0.00)14 Salmon (0.88, 0.51, 0.45)15 Olive drab (0.45, 0.50, 0.10)16 Light brown (0.90, 0.65, 0.30)17 Forest green (0.30, 0.58, 0.35)18 Goldenrod (1.00, 0.85, 0.40)19 Plum (0.55, 0.40, 0.55)20 Tan (0.87, 0.87, 0.65)21 Turquoise (0.25, 0.80, 0.85)22 Gold (0.85, 0.74, 0.10)23 Thistle (0.83, 0.65, 0.83)24 Tomato (0.95, 0.35, 0.20)25 Wheat (0.80, 0.70, 0.55)26 Violet (0.60, 0.30, 0.90)27 Background (0.00, 0.00, 0.00)COLORS Examples

<strong>ASAP</strong> | Commands and Macros (C) | 68COLORS (<strong>ASAP</strong> Command)Reassigns the color used to display each object.Function• Setup Plots and Verify SystemSyntaxCOLORS [ i [ j [ k [ l [ m [ m' ... ] ] ] ] ] ]Remarks1. Reassigns the color used to display each object according to the last group assignment or dominant interfaceproperty as shown in the following table.COLORijklINTERFACEGroupAbsorbingReflectingTransmittingm m' ... Media 1, Media 2, ...2. <strong>ASAP</strong> uses a palette of 27 colors to display graphics. The following table summarizes the colors and theirassociated red/green/blue (RGB) values:Number Color Name RGB Value1 Reverse video (1.00, 1.00, 1.00)2 Red (1.00, 0.00, 0.00)3 Light blue (0.00, 0.60, 1.00)4 Orange (1.00, 0.60, 0.00)5 Yellow (1.00, 1.00, 0.00)6 Purple (0.50, 0.00, 1.00)7 Sea green (0.00, 1.00, 0.60)8 Maroon (1.00, 0.00, 0.50)9 Cyan (0.00, 1.00, 1.00)10 Chartreuse (0.60, 1.00, 0.00)11 Blue (0.00, 0.00, 1.00)12 Magenta (1.00, 0.00, 1.00)13 Green (0.00, 1.00, 0.00)14 Salmon (0.88, 0.51, 0.45)15 Olive drab (0.45, 0.50, 0.10)16 Light brown (0.90, 0.65, 0.30)17 Forest green (0.30, 0.58, 0.35)

<strong>ASAP</strong> | Commands and Macros (C) | 69Number Color Name RGB Value18 Goldenrod (1.00, 0.85, 0.40)19 Plum (0.55, 0.40, 0.55)20 Tan (0.87, 0.87, 0.65)21 Turquoise (0.25, 0.80, 0.85)22 Gold (0.85, 0.74, 0.10)23 Thistle (0.83, 0.65, 0.83)24 Tomato (0.95, 0.35, 0.20)25 Wheat (0.80, 0.70, 0.55)26 Violet (0.60, 0.30, 0.90)27 Background (0.00, 0.00, 0.00)3. In inverse video mode, only black and white switch; all other colors remain the same.4. If a wavelength is not specified for a set of sources, rays and ray paths are plotted in the arbitrary sequence ofcolors from the order in the COLORS command for the sequence of sources.5. Rays and ray paths are plotted in the same color for all rays originating from the same source.6. When sources of different wavelengths are created, the colors range from blue to red in a quasi-spectral sense,corresponding respectively to the wavelengths ranging from shorter to longer.COLORS ExamplesCOMBINE (<strong>ASAP</strong> Command)Combines the current distribution data file with a previously calculated distribution data file.Function• Display/Modify Data DistributionsSyntaxCOMBINE [ u ] [ c ]name fcnOptionnameucfcnDescriptionFile name of the distribution data file (extension is .DIS)Logical file numberScale factorFunctional combination of two data filesRemarks1. Use for analysis of general wavefronts.2. Adds, subtracts, or multiplies the current distribution data file with a previously calculated distribution data file ona pixel-by-pixel basis.3. The previously calculated data file may be specified by its logical file number u (BROxxx.DAT) or by name. Thefile extension for a named distribution data file is *.DIS.

<strong>ASAP</strong> | Commands and Macros (C) | 704. If u is less than one, the original file specified on entry into DISPLAY is used.5. If c is not equal to zero, the current data is added to c times the given file. If c is absent or zero, the twodistributions are multiplied together.6. Since the files are combined on a pixel-by-pixel basis, it is important that they have the same number of pixels.7. Any arbitrary combination can be performed using a $FCN definition.8. The functional combination uses a previously defined function to create new data for each pixel. The functionparameters passed are _1 (the original distribution pixel data value), and _2 (the combined file pixel data value).9. To divide two distribution data files, use:$FCN RATIO (_1/_2)DIS filename1COMBINE "filename2" RATIO10. The record buffer is 10,000 pixels per line.11. Ability to do an arbitrary combination with a $FCN definition.COMBINE ExamplesCOMPOSITE (Edge Modifier) (<strong>ASAP</strong> Command)Combines several edge entities into a single edge entity.Function• Define/Modify Curvedge EntitiesSyntaxCOMPOSITE [ -n ] [ GAPS q [ q' ] ]i [ i']OptionDescription-n Last n edgesi i'GAPS q q'RemarksEdges i through i'Connection factors1. COMPOSITE combines the last n edges, edges i through i', or all edges defined since the last EDGE command intoone edge.2. GAPS between the endpoints of one edge and the start of the next can be handled as follows.qDescription-1 merge gap points into one0 leave gaps open (default)1 linearly connect gaps3. Specify q' for the last-to-first point gap to make a single edge object from a set of discontinuous edges.COMPOSITE Examples

<strong>ASAP</strong> | Commands and Macros (C) | 71COMPOSITE (Lens Modifier) (<strong>ASAP</strong> Command)Combines several lens entities into a single lens entity.Function• Define/Modify Lens EntitiesSyntaxCOMPOSITE [ -n ]i [ i']Optionni i'DescriptionLast n lens entitiesRange of lens entitiesRemarks1. Combines the last n lenses, lenses i through i', or all defined lenses since the last LENS command into one lensentity.2. Note: IDEAL or PERFECT lens entities are not allowed in a composite set.COMPOSITE ExamplesCONDUIT (<strong>ASAP</strong> Command)Sweeps a circle along a planar explicit cubic.Function• Define/Modify Surfunc EntitiesSyntaxCONDUIT X x x' r [ y [ a [ a' ] ] ]Y y y' zZ z z' xOptionDescriptionX, Y, or Z Coordinate axisx, y, or z Starting axial coordinatex', y', or z'Ending axial coordinatey, z, or x Displacement of curve end from axisa a' Starting and ending angles in degrees; defaults are 0Remarks1. Creates up to a 6th-order surface formed by sweeping a circle of radius |r| along an explicit cubic planar curvestarting at the first axial location and ending at the second.

<strong>ASAP</strong> | Commands and Macros (C) | 722. If r is positive, the circle is perpendicular to the curve at every point. If it is entered as a negative number, thecircle is always perpendicular to the specified axis.3. The end of the curve can be displaced from the axis by the amount given on the fifth entry (default 0).4. The optional last two entries are the starting and ending angles in degrees of the curve relative to the axis. Theirdefaults are zero and any values entered must be (usually much) less than 90 degrees in magnitude.CONDUIT ExamplesCONIC (<strong>ASAP</strong> Command)Creates a quadratic Bezier edge/curve in the plane given at the 2nd and 3rd entries.Function• Define/Modify Curvedge EntitiesSyntaxCONIC X x c y z y2 yz z2 y' z' y" z"Y y' y" [ p ]Z z' z"y c z x z2 zx x2 z' x' z" x"Z z' z" [ p ]X x' x"z c x y x2 xy y2 x' y' x" y"X x' x" [ p ]Y y' y"OptionUsing the first form as an example:Xxc y z y2 yz z2y' z'DescriptionCoordinate axisLocation along coordinate axisImplicit coefficients of this conic curveCoordinates of start point of the curvey" z" Coordinates of end point of the curveY y' y"Z z' z"RemarksSpecifies y coordinates of start and stop points, solve forz' "zSpecifies z coordinates of start and stop points, solve fory' "y1. This edge is a single quadratic curved segment.2. Entries 4 through 8 are the implicit coefficients of this conic curve.3. Entries 9 and 10 are the coordinates in this plane of the start point of the segment, and 11 and 12 the stop point.4. Instead of giving a pair of coordinates for each point, only one coordinate value for each point can be given and<strong>ASAP</strong> solves for the others (smallest root) using the Y y' y", or Z z' z", or X x' x" syntaxes.5. If this is the case, p is an optional vertex radius of curvature of a parabola to subtract from the curve.Example

<strong>ASAP</strong> | Commands and Macros (C) | 73To define the equivalent of a classical optical conicoid:CURVER=1 !vertex radius of curvatureK=-1 !conic constantH=1 !outer aperture heightO=0 !inner obscuration heightCONIC X 0, 0 0 -2*R 1 0 K+1, Y (O) (H)SWEEP AXIS 360 ZOBJECTINTERFACE . . .CONIC ExamplesCONSIDER (<strong>ASAP</strong> Command)Choose a set of objects for ray tracing and plotting.Function• Setup Plots and Verify SystemSyntaxCONSIDER [ ALL ]NONEONLY [ i i' ... ]EXCEPTADDREMOVEOptionALLNONEONLYi i' ...EXCEPTADDREMOVEDescriptionConsider all known objectsConsider no objectsConsider only the objects specified (default is the currentGROUP)OBJECT numbers or names to be consideredConsider all objects except those specified (default is thecurrent GROUP)Adds the specified objects to the previous CONSIDERcommandRemoves the specified objects from the previousCONSIDER commandRemarks1. The CONSIDER command is used to isolate geometry, as well as all rays currently associated with that geometry.2. Provides control over the current set of objects that <strong>ASAP</strong> is to consider in all calculations and output. All objectsremain in the database at all times (that is, even when they are temporarily ignored with options other than ALL,they are not deleted).3. By default all objects in the system database are CONSIDERed.

<strong>ASAP</strong> | Commands and Macros (C) | 744. A CONSIDER command by itself (with no entries) produces a list of the currently CONSIDERed objects.5. The EXCEPT option restricts the current object set to all objects except those specified (default is the currentGROUP). All objects except those specified may be drawn, ray traced, or analyzed.6. Particular object numbers (or names with "?" wildcards) can be either excluded with the EXCEPT option or be theONLY ones CONSIDERed. If no object list is given, the last GROUP is used.7. The current state (that is, a previous CONSIDER command) can be updated using ADD or REMOVE instead ofONLY or EXCEPT, respectively.8. The ADD option adds the specified objects to the CONSIDER list. REMOVE subtracts the specified objects fromthe CONSIDER list.9. Ray data are initially referenced by OBJECT 0. Before ray tracing, CONSIDER EXCEPT 0 effectively turns offthe ray data while maintaining all other geometry.10. When using OBJECT names, you can use only 40 characters in the name when you CONSIDER them.CONSIDER ExamplesCONTOUR (<strong>ASAP</strong> Command)Creates a contour plot of the current distribution data file.Function• Display/Modify Data DistributionsSyntaxCONTOUR n [ LOW ] [ TICS t [ t' ] ] [ VECTOR ] [ 'title' ]c' [ c" ... ] HIGH GRIDOptionnc' c". . .LOWHIGHt'VECTOR'title'GRIDDescriptionNumber of equally spaced contour levelsFractional contours relative to the full range of thefunction being plotted or absolute contours (see remarksbelow)Produce a low resolution greyscale plotProduce a high resolution color map plotCoordinate TIC mark spacingWrites contour plot to 3D vector fileOptional title for plot (up to 64 characters)Produces line spacing for vertical and grid horizontallinesRemarks1. Generates a contour plot with fractional contours c' ... relative to the full range of the function being plotted(0=minimum, 1=maximum).2. If any of the cs are less than zero or greater than one, all cs are assumed to be absolute.3. Alternatively, n equally spaced contours can be specified.4. Also, a LOW-resolution greyscale or HIGH-resolution color map plot can be produced instead of the line contourplot.

<strong>ASAP</strong> | Commands and Macros (C) | 755. If the coordinate TIC mark or GRID line spacings t' (vertical, horizontal) are specified, the plot is slightly reducedin size and drawn with annotated coordinate scales.6. If VECTOR is specified, the contour plot is written to the 3D vector file. As an example, irradiance plots may beviewed with already existing system geometry plots by using the REPLOT command.7. The title is delimited by single quotes ( '), as shown.CONTOUR Examples$COPY (<strong>ASAP</strong> Macro)Performs a raw, byte-for-byte copy of the source file to a destination file.Syntax$COPY source destination&COPY s d$MOVE&MOVEOptionsdDescriptionSource file name or numberDestination file name or numberRemarks1. Does a raw byte-for-byte copy of the source file (name source or number s) to a destination file (name destinationor number d).2. If the destination file does not exist, it is created. Otherwise, $COPY overwrites it while &COPY appends to it.3. The command works with all file types (text and binary), but it usually is not recommended for appending withone or both files if they are binary.4. The MOVE versions behave identically to COPY, except that the source file is deleted afterwards.Example$COPY MODE.DAT 29&COPY NEW.LIB UTIL.LIB$COPY 30 SAVE.VCR!copy mode.dat to bro029.dat!add new library to util.lib!copy current 3D vectors to save.vcr$COPY ExamplesCORNER (<strong>ASAP</strong> Command)Creates an axis-aligned corner of a cube (three mutually perpendicular planes), with the apex at the location given bythe third entry.Function• Define/Modify Surfunc EntitiesSyntaxCORNER X x HEIGHT dY y HEXAGONAL d

<strong>ASAP</strong> | Commands and Macros (C) | 76Z z LENGTH dOptionHEIGHTHEXAGONALLENGTHdDescriptionCircular corner cubeSix-sided cornerAxial corner cubeSee RemarksRemarks1. Creates an axis-aligned corner of a cube (three mutually perpendicular planes) with an apex at the location givenby the third entry.2. The size of the corner cube can be specified either by a circular HEIGHT, HEXAGONAL height, or an axialLENGTH (maximum cross-section will then be triangular).3. Note: A small hole is created at the apex, since the normal to the function becomes undefined there.Therefore, an on-axis ray never hits the surface(s).CORNER ExamplesCPE (<strong>ASAP</strong> Command)CPE (Cascaded Polarization Element) is used to define a compound polarization device. Every polarization devicecascaded in a CPE element is specified by its polarization device type or type index and its device name or device listindex in its defined list.The orientation of the polarization axis of every cascaded device is specified by the polar and azimuthal angles either1) relative to its previous device in the series (relative orientation convention), or 2) relative to the first element(absolute orientation convention).Function• Create/Modify ObjectsSyntaxCPE n Alignment [stacked] [‘name’]{type|type_ID} {element name|list_ID} theta phi{type|type_ID} {element name|list_ID} theta phi…..OptionnAlignmentstackedDescriptionNumber of polarization elements cascaded in this CPEdeviceAlignment convention. It can be either RELATIVE (orsimply R) or ABSOLUTE (A). In RELATIVE alignmentconvention, the orientation of its polarization axis iscalculated relative to those of its immediate previouselement is the series.Controls the way space and material between individualelements are interpolated. If this argument is not present,

<strong>ASAP</strong> | Commands and Macros (C) | 77OptionnameDescriptionthe polarization elements of the CPE is assumed tobe separated by infinitesimally thick isotropic layerswith the refractive index of the incident medium of theINTERFACE POLARIZATION (PolarizationModifiers) to which it is attached. If it is set tostacked, the polarization elements in the CPE areassumed to be stacked together.User-specified name of the Cascaded PolarizationElement (CPE), up to 32 characters long. If no name isspecified, <strong>ASAP</strong> uses a default name starting with "CPE"followed by the list index of this cascaded polarizationelement in the system CPE element list. For example, thesecond CPE element is named as "CPE00002".Note: The name is case sensitive.type|type_IDelement name|list_IDthetaphiTypes of polarization devices. See Remarks for a table ofdefined polarization device types.Note: You can specify the polarization devicetype by either its type index or its alternativeinput option listed in the table in the Remarkssection. If the alternative input is used, theletters must be included in single quote. Forexample, 'JONES' can stand for Jones matrixelement.Name or list index of the cascaded elements.Alternatively, you can also input the list index of theelement on its defined list.Note: <strong>ASAP</strong> maintains a dynamic list for eachdefined polarization device type.Polar angle in degrees of the polarization axis of thecascaded polarization deviceAzimuthal angle in degrees of the polarization axis ofthe cascaded polarization deviceRemarks1. A CPE element can contain an unlimited number of polarization elements.2. CPE elements cannot be nested. This means that the polarization elements of a CPE cannot be another CPEelement or itself.3. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER3 Realistic polarizer POLARIZER RPM

<strong>ASAP</strong> | Commands and Macros (C) | 78Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC8 Cascaded polarizationelementCPE ExamplesCPECPECRYSTAL (<strong>ASAP</strong> Command Argument)Identifies the medium as a birefringent uniaxial crystal.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax... [ CRYSTAL a,b,c [ m' ] ]Optiona,b,cm'DescriptionOptical axis directionPrevious mediumRemarks1. The command argument, CRYSTAL, identifies the medium as a birefringent uniaxial crystal with optical axisdirection a,b,c, and given extraordinary refractive indices.2. Ordinary indices are specified on a previous medium m' (default is last). For example, a calcite crystal with itsoptical axis initially aligned along the Y direction is defined as follows:MEDIA1.66 !ordinary index for following extraordinary1.49 CRYSTAL 0 1 0 =CALCITE3. If SPLIT is one or higher, <strong>ASAP</strong> automatically generates an ordinary and an extraordinary ray/beam at eachcrystal interface.CRYSTAL ExamplesCUTOFF (<strong>ASAP</strong> Command)Sets the conditions controlling ray termination.Function• Setup Trace

<strong>ASAP</strong> | Commands and Macros (C) | 79SyntaxCUTOFF [ t ] [ n ]OptiontnDescriptionAbsolute flux threshold (must be in decimal format)Maximum number of total object intersections for anyray (must be in integer format)Remarks1. Causes rays to be ignored.2. Sets the absolute flux threshold; below this value, <strong>ASAP</strong> ignores the rays to the decimal number t (default 1.E-18).3. The maximum number of total object intersections for any ray can be set to the integer n (default 1000).4. Tracing of CUTOFF rays cannot be continued.CUTOFF ExamplesCVF (<strong>ASAP</strong> Command)The CVF (Complex Vector Field) command provides a bidirectional translation facility between <strong>ASAP</strong> and FDTDSolutions by Lumerical.SyntaxCVF EXPORT format [ dist_filespec [ exch_filespec ] ]IMPORT [ exch_filespec [ dist_filespec ] ]OptionEXPORT or IMPORTformatdist_filespecexch_filespecDescriptionDirection of data exchange, from or to <strong>ASAP</strong>,respectivelyManner of data exchange; currently only LUMERICALis supportedOptionally specifies an <strong>ASAP</strong>-native distribution file byeither name or unit number. See Remarks below.Optionally specifies a file for data exchange by name.See Remarks below.Remarks1. CVF works with complex vector fields and, therefore, requires that FRESNEL BOTH be in effect. See remarkbelow about the FIELD command.2. CVF exports the full vectorial electric field, and so operates only on fields of specified polarization and only inCOHERENT mode. Therefore, both BEAMS COHERENT and a POLARIZ command must precede the creation of asource that is to be exported with CVF EXPORT.3. Exchanged data comprise transformed complex electric vector field data, such as those typically stored in theBRO029.DAT file by the FIELD command, along with a small amount of internal metadata.4. dist_filespec: the filename may have a three-letter extension. If a filename is provided without an extension, .DATis assumed. If neither a name nor a unit number is provided, the BRO029.DAT file is used by default. Pre-existingfiles are overwritten on output.

<strong>ASAP</strong> | Commands and Macros (C) | 805. exch_filespec: the filename may have a three-letter extension. If a filename is provided without anextension, .FLD is assumed. If no filename is provided, CVF.FLD is assumed. Pre-existing files are overwrittenon output.6. Note: (A) The second filespec requires that the first filespec also be present. The converse is false.7. Data exchange between <strong>ASAP</strong> and FDTD Solutions is performed in SI units. Unit conversions are handledinternally, and are transparent to users. An exchange file, upon being imported to a native <strong>ASAP</strong> distribution file,is expressed in the current system UNITS and WAVELENGTH units. See Note below.8. Note: (B) If you have not set system units before importing the exchange file, a message in the CommandOutput window advises you that <strong>ASAP</strong> will use meters.Remarks for Advanced <strong>ASAP</strong> UsersThe following <strong>ASAP</strong> register settings occur after a successful import:CVF_WAVECVF_DEPTHCVF_INDEXCVF_SCALECVF_XCVF_YCVF_ZCVF_PHICVF_THETACVF_PSIHolds the wavelength that is associated with importeddata, expressed in the current WAVELENGTH units (seeNote (A) above).Holds the offset 'depth' of the sampled field with respectto the grid, as expressed in the current system UNITS(see Note (B) above). This situation is exactly analogousto the depth specified with a FIELD command.Holds the refractive index associated with the importeddata, and can be used to IMMERSE a source that wascreated by applying DECOMPOSE to the imported data.To ensure that the practical effects of fields overlappinginhomogeneous media are minimized, you must makejudicious choices for the locations of grids in <strong>ASAP</strong>, andof sources and monitors in FDTD Solutions.Holds the scale factor found in the exchange file, whichdescribes scaling between natural <strong>ASAP</strong> units and SIunits for the electric field. This scale factor is typicallyof little interest, as unit conversions are automaticallyperformed.X-offset of local system wrt global systemY-offset of local system wrt global systemZ-offset of local system wrt global system1st Euler angle2nd Euler angle3rd Euler angleCVF Examples

<strong>ASAP</strong> | Commands and Macros (D) | 81Commands and Macros (D)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “D”.$DATIM (<strong>ASAP</strong> Macro)Switches on and off the printout of date and time in plots.Syntax$DATIM [ ON [ ON ] ]OFF OFFRemarksTurns ON or OFF any date and/or clock time outputs. When turned OFF, the system date and/or time routines returnblank strings.$DATIM OFF OFFDate Time Version$DATIM OFF ON x x$DATIM ON OFF x x$DATIM ON ON x x x$DATIM Examples$DBG (<strong>ASAP</strong> Macro)Creates a debug listing of parser output.Syntax$DBG [ ... ][ ... ]Remarks1. Displays how the parser decoded a line of input into entries.2. The start, length, type, and value of each entry on the line is listed.3. If the line of input is on the $DBG macro itself, the line is not passed to <strong>ASAP</strong>.$DBG ExamplesDECOMPOSE (<strong>ASAP</strong> Command)Decomposes an existing field into a new set of Gaussian beams.Function

<strong>ASAP</strong> | Commands and Macros (D) | 82• Create Rays and BeamsSyntax 1DECOMPOSE [ u ]n.eSyntax 2DECOMPOSE [ u ] POSITION [ x y z CON ] [ ADJUST ]n.e -POSITION DIV+POSITION a,b,c PLASyntax 3DECOMPOSE [ u ] DIRECTION [ m [ a [ a' ] [ RECT ] ] ]n.e -DIRECTION+DIRECTIONOptionx y zCONADJUSTDIVa,b,cPLAma a'RECTDIRECTIONDescriptionCenter of the CONverging or DIVerging sphericalreference wavefrontSpecifies a converging spherical reference wavefrontProduces an accurate decompositionSpecifies a diverging spherical reference wavefrontDirection of the PLAnar reference wavefrontSpecifies a planar reference wavefrontNumber of Gaussian beams createdLimiting cone angles for the Gaussian directions (default90 degrees)Specifies limiting cone angle pattern to be rectangularinstead of the elliptical defaultDecomposition Fourier transformRemarksSyntax 11. The DECOMPOSE command reads the complex coherent field stored in the distribution file (number or name withextension). The default is 29 or BRO029.DAT, which is normally created by a FIELD command. The field is thendecomposed into a new set of propagating Gaussian beams.2. If the field is a complex vector, that is FRESNEL BOTH is set before the FIELD calculation), only the componentspecified by the last POLARIZATION command is decomposed.3. Negligible beams are not created; that is, their relative flux is below the CUTOFF command floating entry or theirrelative flux is below HALT.

<strong>ASAP</strong> | Commands and Macros (D) | 834. For example, to decompose properly a vector field propagating mostly in the Z direction:RAYS 0POLARIZ X; DECOMPOSE ...POLARIZ Y; DECOMPOSE ...5. The new ray set is automatically added to the current ray set, and a new source with the current WAVELENGTHcommand is created. If, however, the DECOMPOSE command is immediately preceded by a RAYS 0 command,the current ray set is deleted before the new ray set is created.Syntax 21. The POSITIONal decomposition creates a straight forward spatial distribution of beams, one per input field pixel(as defined by the last PIXELS command) and is used only when the pixel size is a few wavelengths or larger.The direction of each beam in the new grid is adjusted to be normal to the local phase front.To make this determination more robust, a CONverging or DIVerging spherical (centered at x y z) or PLAnar (withdirection a,b,c) reference wavefront can also be specified.The first setting on the last WIDTH command controls the overlap of beams.Syntax 31. The DIRECTIONal decomposition Fourier transforms the field and creates up to m (actual integer number orfloating point fraction of maximum possible, default 0.1) Gaussian beams whose sum closely approximates theoriginal field distribution. The centers and waists of the beams are all located at the center of the original fielddistribution. The beams all have the same widths (chosen such that they are uniformly distributed in the far field),but different propagation directions.The a's are the limiting cone angles in degrees (default is 90; that is, a full hemisphere) for the Gaussiandirections, and should be set to the acceptance cone of the subsequent optical system.When the RECT option is used this cone is rectangular instead of elliptical.If you want the number of beams to just fill the given angular cone (assuming a=a' and a square WINDOW), thespatial sampling interval of the original field must be:where λ is wavelength, N is the size of the FFT used (set by the last FTSIZE command), and c is either 4 forRECT or Π otherwise. Therefore, the PIXEL setting for the original field should be the WINDOW size divided byd.The overlap of the beams in the far field is controlled by the first setting on the last WIDTH command. TheADJUST option takes into account this overlap and produces a more accurate decomposition in most cases.2. The accuracy of the decomposition is related to the number of beams and their maximum far field angle.As a check, it is a good idea to issue a SPOTS DIRECTION and a SPREAD NORMAL command just afterdecomposing and before continuing to TRACE the beam set to verify the source (beam set) fidelity.DECOMPOSE ExamplesDEFORM (<strong>ASAP</strong> Command)Adds small deformations to an object.

<strong>ASAP</strong> | Commands and Macros (D) | 84Function• Create/Modify Objects• Setup Plots and Verify SystemSyntax 1 - Short formatDEFORM k [ k' ]Syntax 2 - Long formatDEFORM x y z a [ a' a" ... ] [ AXIS a,b,c ] [ FCN fcn ]Optionk k'x y zDescriptionExplicit surface functionsPoint on the object's surfacea a' a" ... Aspheric deformation coefficients (up to 20)AXIS a,b,cFCN fcnRemarksNormal direction of axisOptional macro function1. With the short format, one or two general deformation functions defined entirely by the given explicit surfacefunctions (GENERAL EXPLICIT, FITTED EXPLICIT, ZERNIKE, SAMPLED, EXPLICIT orUSERSAG) are added to the object surface.2. With the long format, a small user-definable aspheric deformation is added to the previous object. Thisdeformation is rotationally symmetric about the axis defined by either the normal vector that passes through thepoint x y z on the object's surface or the given point a,b,c and AXIS.3. The deformation or sag value as a function of perpendicular distance from the aspheric axis (r below) is given by,where fcn is the name of an optional macro function (intrinsic, for example, SIN, or user-defined $FCN).4. CADEXPORT does not export a deformed surface that is produced in <strong>ASAP</strong> after a DEFORM command. The basesurface that is before DEFORM does export. Use the DEFORM command for phase / wavelength-level deformationsto base surfaces only in <strong>ASAP</strong>.DEFORM ExamplesDIMENSIONS (<strong>ASAP</strong> Command)Displays a table of maximum array dimensions for the most important program arrays.Function• Setup Plots and Verify SystemSyntaxDIMENSIONSRemarks

<strong>ASAP</strong> | Commands and Macros (D) | 851. The table information summarizes the storage capabilities of a given version of the program.2. Values listed in the form "number-1" usually indicate a limitation due to decimal encoding (either internally or fortext output).3. The limit for "Ray Selection Flags" is set to 0. The 0 indicates that <strong>ASAP</strong> has not yet allocated any memory, but itwill do so after the first SELECT command.DIMENSIONS ExamplesDIRECTIONAL (<strong>ASAP</strong> Command)Produces a polar plot of the current angular distribution data file.Function• Define/Modify Surfunc Entities• Display/Modify Data DistributionsSyntaxDIRECTIONAL [ UNWRAP ] [RADIANCE] [ 'title' ]OptionUNWRAPRADIANCE'title'DescriptionFlag to create a Cartesian plot of intensity versus angleFlux per projected angleOptional title for plot (up to 64 characters)Remarks1. Produces a polar plot of the angular energy distribution created by a SPOTS DIRECTION or SPREADDIRECTION command to an angle space RADIANCE or radiant intensity distribution. The polar axis of thespherical angle coordinate system is assumed to be "horizontal" (IES type B photometry).2. By default (that is, without the RADIANCE option), it converts the radiance (flux per projected solid angle) as afunction of direction cosines generated by these commands to an integrated radiant intensity (flux per solid angle)as a function of angle.3. If any distribution value is negative, the data is assumed to be the common logarithm of energy and is handledaccordingly.4. Optionally, the polar plot can be UNWRAPped into a Cartesian plot of intensity versus angle.5. The title is delimited by a single quotation mark ( ' ).DIRECTIONAL Examples$DISP (<strong>ASAP</strong> Macro)Immediately displays the given binary distribution file.Syntax$DISP [ ON ]OFFfileRemarks1. Immediately displays the given binary distribution file (default BRO009.DAT or "file.DIS").

<strong>ASAP</strong> | Commands and Macros (D) | 862. Otherwise, turns ON or OFF the automatic displaying of such files immediately after their creation.$DISP ExamplesDISPLAY (<strong>ASAP</strong> Command)Reads previously created distribution data files so that they can be modified.Function• Display/Modify Data DistributionsSyntaxDISPLAY [ u [ MODULUS ] [ s ] ]name PHASEAMPLITUDEWAVEFRONTREALIMAGINARYENERGY1ST2ND3RD4TH:name.BMP REDGREENBLUEMONOOptionunameMODULUS, PHASE,AMPLITUDE, WAVEFRONT,REAL, IMAGINARY,ENERGY,1st, 2nd, 3rd, 4thDescriptionLogical unit number of distribution data fileName of distribution data file, or use DISPLAY toprompt for file name from Open File dialog boxField characteristic of interestRemarks1. Reads a previously created distribution data file into <strong>ASAP</strong> where it may be modified and/or examined byDISPLAY subcommands.2. The distribution data on logical unit u (default=9) or file name.DIS is read into memory and can be modified and/or displayed with the following sets of commands:ororDISPLAY "*"DISPLAY _DISPLAY "*.bmp"DISPLAY _.BMP

<strong>ASAP</strong> | Commands and Macros (D) | 873. If a bitmap file is given, it is first translated to distribution file format (see description of BMP2DIS utility in thetopic, Importing CCD Images).4. The bitmap translation is intended for use with only color Windows bitmaps (24 bits per pixel), and explicitly notfor black-and-white bitmaps (1 bit per pixel).5. A DISPLAY distribution file can be multi-valued or multi-dimensional.If the distribution is multi-valued (for example, the six-component complex vector that can be created by a FIELDcommand), the first value is extracted by default. Otherwise, a specific component given by the third entry can beextracted for processing.If the distribution in 3D s is either an absolute (integer) or fractional slice number, the default is the last 2D slice.6. If more than one set of values is generated in this file, additional options are in the DISPLAY command to selecta subset from the data matrix. These are 1st, 2nd, and so on. Without these parameters, only the first matrix ofvalues is seen (therefore, 1st is actually not necessary).7. Commands that modify the distribution data file include:NORMALIZE, FORM, FFT, AVERAGE, RADIAL, TRANSPOSE, MODIFY, COMBINE, REDUCE,SECTION, ANGLES, VALUES, OFFSET, FOLD, ABEL, and THRESHOLD.8. Commands that display the distribution data file include: TABLE, RANGE, PLOT3D, ISOMETRIC, DMAP,GRAPH, CONTOUR, DIRECTIONAL, ENCLOSED, MESH, and PICTURE.9. Many analysis commands such as SPREAD, SPOTS, RADIANT, OPDMAP produce scalar distribution datafiles. These files are stored by default in BRO009.DAT (logical unit number 9).10. For examples of how to use the DISPLAY command for reading in data, see the MAP command. Other examplesare shown below.• Header or Output--- DISPLAYOpening OLD distribution file 9: C:\<strong>ASAP</strong>Work\MoreAboutSources\bro009.datFile header:Geometrical Ray SPOTS 1C direct 0.7341523 Milliwatts / srA direction -0.9992853 0.9993443 39B direction -0.9985530 0.9982522 39Statistics on 39 by 39 data set:Milliwatts / sr Location B directionA directionMinimum 0.000000 1 1 -0.9729529-0.9736619Maximum 11.95395 20 21 -0.1503881E-030.5127642E-01Average 2.061445 20 20 -0.1503881E-030.2950244E-04RMS var 2.003785 9 9 0.43805790.4378794TOTAL Milliwatts = 8.226968• Entering Files into DISPLAY...(other <strong>ASAP</strong> commands)...DISPLAY

<strong>ASAP</strong> | Commands and Macros (D) | 88Reads BRO009.DAT into <strong>ASAP</strong> for further examination and/or analysis....(other <strong>ASAP</strong> commands)...DISPLAY 25Reads FOR025.DAT into <strong>ASAP</strong> for further examination and/or analysis....(other <strong>ASAP</strong> commands)...nDISPLAY JOEReads JOE.DIS into <strong>ASAP</strong> for further examination and/or analysis.FIELD AMPLITUDE 0DISPLAY...(other DISPLAY commands)...RETURNDISPLAY 29 PHASE...(other DISPLAY commands)...Calculates the amplitude of the field and saves it in BRO009.DAT. (The complex field is saved by default inBRO029.DAT.) The first time DISPLAY is called, it reads the BRO009.DAT file containing the amplitude. Theuser can then examine the data as desired. When finished, the user issues a RETURN to return to <strong>ASAP</strong>, and thencalls DISPLAY again, this time specifying that the phase of the complex field is desired. DISPLAY reads thecomplex field data from BRO029.DAT and extracts the phase information. You can then examine the phase dataas desired.DISPLAY ExamplesDMAP (<strong>ASAP</strong> Command)Creates a character map of the current distribution data file.Function• Display/Modify Data DistributionsSyntaxDMAP [ n ]OptionnDescriptionNumber of distinct levels to be simulated with differentcharacters (default 10)DMAP Examples$DO (<strong>ASAP</strong> Macro)Loops through input record(s).

<strong>ASAP</strong> | Commands and Macros (D) | 89Syntax$DO [ i [ j [ k ] ] ]&DO... [ ? ] ...|Remarks1. Reads and runs the next input record(s) as many times as necessary to satisfy the starting, ending, and incrementparameters.2. The integer increment k defaults to either +1 or -1 depending upon the values of i and j.3. The sign of k is always set to be the same as the sign of j-i, and so the loop is always run at least once.4. For $DO the question mark “?” is the loop counter; for &DO the vertical bar “|” is used instead.5. The loop is terminated only when the counter reaches or exceeds the ending value.6. Only one level of looping per macro nesting level is permitted; for multiple looping it is necessary to jump toanother macro level.7. An input error, a $GO or a $LEAVE command in the record forces a premature exit from the loop.8. It is not necessary to reference the loop counter in the record(s).9. By default only the next record is repeated. If all of the commands to be looped cannot fit on the next record,you may put the commands into a macro and then loop over the macro. Alternatively, you may enclose multiplelooping records between curly braces.10. When $DO with multiple records enclosed between curly braces is nested inside a user-defined macro, the closingcurly brace should not be in the first column. Otherwise, the user-defined macro is delimited by the intended endof the $DO.11. You cannot implement nested $DO loops directly. However, you can define a macro with a $DO loop, and themacro can contain a $DO loop.Example!! TO CONSTRUCT A NESTED LOOP AND UPDATE!! GRAPHICS TITLE WITH INCREMENT VALUES!! [date]SYSTEM NEWRESETMACC { 1$DO 2 3{ TITLE 'BTB=#1 BCB=?'SURFACEPLANE Z 0 RECT 1 1OBJECTWINDOW Y ZPROFILES}}$DO 0 2&MACC LIT[?]$DO ExamplesDOMACROS (<strong>ASAP</strong> Command)Controls when currently defined macros are executed relative to top-level <strong>ASAP</strong> commands.

<strong>ASAP</strong> | Commands and Macros (D) | 90SyntaxDOMACROS FIRSTLASTNEVERRemarks1. Determines whether your macro commands are checked FIRST, LAST, or NEVER relative to the top-level <strong>ASAP</strong>commands.2. Use the default option, LAST; however, you can use FIRST if your macro name conflicts with an <strong>ASAP</strong> command.DOMACROS ExamplesDOME (<strong>ASAP</strong> Command)Creates a single refractive element.Function• Define/Modify Lens EntitiesSyntaxDOME X x t m [ r [ r' ] ]Y yZ zOptiontmrr'DescriptionAxial thicknessMediaFront radius of curvatureBack radius of curvatureRemarks1. Creates a single refractive element of axial thickness t and media m with front and back radius of curvature r andr', respectively.2. The side with the shortest radius will be a complete hemisphere while the other will be truncated at the sameplane.3. The default for r is t (solid hemisphere) while the default for r' is r-t (concentric shell).DOME ExamplesDOPL (<strong>ASAP</strong> Command)Controls how the Optical Path Length (OPL) and phase of a ray/beam are determined at a DIFFRACTive surfaceINTERFACE.Function• Setup Trace

<strong>ASAP</strong> | Commands and Macros (D) | 91SyntaxDOPL STAIRCASEWAVEFRONTPHASEOFFOptionSTAIRCASEWAVEFRONTPHASEOFFDescriptionFraction of wave added to ray's OPL (default)OPL represents an integrated, smooth wavefront (mostcommon)Ray's OPL with phase in beam's complex amplitudecoefficientOnly ray's OPL (faster but useful only for incoherentanalyses)Remarks1. For the first three options, coherent FIELD or SPREAD calculations should be identical, except for possiblynumerical roundoff. On the other hand, OPDMAP results and MOVE optical path differences vary significantly, withWAVEFRONT normally being the desired mode.DOPL ExamplesDOUBLET (<strong>ASAP</strong> Command)Creates a cemented doublet lens.Function• Define/Modify Lens EntitiesSyntaxDOUBLET X x t h m m' [ f b r ]Y yZ zOptionX or Y or Zx or y or zthm m'fbDescriptionGlobal coordinate axisLocation on the global coordinate axisOverall thicknessAperture heightMediaFocal lengthOverall bending factor

<strong>ASAP</strong> | Commands and Macros (D) | 92OptionrDescriptionRatio of the focal length of the first element to thesecondRemarks1. A cemented doublet lens is a positive and negative lens in contact.2. This lens entity starts out normal to the defined global coordinate axis (X, Y or Z).3. The r is the ratio of the focal length of the first element to the second; for an achromatic doublet, r is also the ratioof dispersions (the default if r is not given).4. The bending parameter is defined as (c+c')/(c-c') or, equivalently, as (r'+r)/r'-r); therefore, b=0 implies a planoconvexor plano-concave element and others <strong>ASAP</strong> computes the curvature automatically shared upon the desiredbending parameter.DOUBLET ExamplesDRAWING (<strong>ASAP</strong> Command)Plots a four-view drawing of the current system geometry.Function• Setup Plots and Verify SystemSyntaxDRAWING [ xyz ] [ DIMENSIONS ] [ NORAYS ]OptionxyzDIMENSIONSNORAYSDescriptionChanges the default XYZ coordinate orderingAdd system dimensions to plotPlot the intersection points of the rays on each objectRemarks1. Plots a black-and-white, four-view drawing of the current data in the 3D vector file (BRO030.DAT or *.VCR).The three non-oblique views are aligned and identically scaled, and optionally, can have simple DIMENSIONingadded.2. The default views are:QuadrantTop LeftTop RightBottom LeftBottom RightViewX vs. ZY vs. XY vs. ZYX Oblique3. The optional xyz argument is a three-letter permutation of the default XYZ coordinate ordering and can be used toobtain a different set of views.4. The NORAYS option suppresses the replotting of the rays themselves, but does plot the intersection points of therays on each object.5. Takes into account the current CONSIDER settings.DRAWING Examples

<strong>ASAP</strong> | Commands and Macros (D) | 93DUMP (<strong>ASAP</strong> Command)Dumps the currently selected rays to a data distribution file. If only one argument is specified (non-polarized syntax),the ray polarization data is not dumped, even if the rays include polarization data.Function• Analyze Ray/Beam DataSyntax 1 - Non-polarizedDUMP [ name ]+Syntax 2 - PolarizedDUMP [name|+] [JONES|STOKES]OptionnameDescriptionName of the distribution data file created (defaultLASTDUMP.DIS)+ Append to the previous DUMP, or after END commandreinitialization. Indicates the form of the dumpedpolarization data.JONES|STOKESRemarksJONES refers to polarization data in Jones vector form.STOKES refers to polarization data in Stokes vectorform.1. Dumps the currently selected rays to the binary distribution file name (default LASTDUMP.DIS) or appends + tothe previous DUMP.2. Dumping the ray polarization state is used to export ray polarization data for visualization in the Poincaré spherevisualization tool.3. If the name is omitted and only + is presented for this argument, <strong>ASAP</strong> appends the new ray data to a previousDUMP command.4. Only the essential information about each ray is written to the file: position coordinates, direction cosines, flux(size and divergence if XMEMORY MIN is not set). For polarized rays, the transverse polarization direction,polarization vector, and ray wavelength are also written.5. Use EMITTING DATA to efficiently read the file.Note: Dumped rays can be retrieved with EMITTING DATA to create both unpolarized and polarizedsources. Polarized sources must have been DUMPed in JONES form.6. <strong>ASAP</strong> independently tracks the previously DUMPed file for non-polarized and polarized data. Therefore, it isimpossible to mix non-polarized and polarized ray data in the same dump file.DUMP Examples

<strong>ASAP</strong> | Commands and Macros (E) | 94Commands and Macros (E)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “E”.$ECHO (<strong>ASAP</strong> Macro)Controls display of input commands.Syntax$ECHO [ ALL ]NONERemarks1. Macro echoes (redisplays) ALL input commands or NONE. The macro overrides the control of echoing asspecified on the call to a user macro.2. A $ECHO command by itself (no argument) restores this default mode.$ECHO ExamplesEDGES/CURVES (<strong>ASAP</strong> Command)Signals <strong>ASAP</strong> that edge definition commands follow.Function• Define/Modify Curvedge EntitiesSyntaxEDGES [ i ]CURVESOptioniDescriptionStarting number for defining EDGES/CURVESRemarks1. The default value for i is one more than the highest edge number previously defined. The i is initialized to one atstart of program processing.2. EDGES, LENSES, and SURFACES data currently reside in the same internal storage locations. Therefore, anEDGES number cannot be the same as an already defined LENSES or SURFACES number.EDGES Examples$EDIT (<strong>ASAP</strong> Macro)Calls user-specified editor from within <strong>ASAP</strong>.

<strong>ASAP</strong> | Commands and Macros (E) | 95Syntax$EDIT filename.ext$EDIT macroname$EDIT [ 'string' ]Remarks1. When editing an entire file, BRO recommends reinitializing <strong>ASAP</strong> before the new file is loaded (or the result is acomposite of old and new data). You can initialize <strong>ASAP</strong> with the following commands: SYSTEM NEW, RESET,or RAYS 0.2. $EDIT filename.ext edits the given text file specification, which must contain a period ".". If the file is alreadyopen, it is first closed, then edited, and reopened. <strong>ASAP</strong> prompts you before positioning the pointer at the end ofthe file.3. $EDIT macroname edits the specified macro, extracting it from the current library if necessary. After exiting theEditor, <strong>ASAP</strong> asks if you want to replace the old macro definition with the new one, and if you want to run themacro immediately.4. $EDIT 'string' edits the current input file (as specified on the last $IO command) or only the part delimited byblank lines that contains the given 'string'. After exiting the editor, you are asked if you want to replace the oldpart of the input file with the new one, and if you want to run the entire input file, only the edited part, or none ofit. Note that no application initialization is automatically done before re-running the input file. You must do thiswith the appropriate application commands.5. Select any editor available on your system to do online editing by specifying in the command line with theEDITOR switch or environmental variable. Otherwise, the following variables apply:OFFASKEACHNORMSuppresses screen graphicsPrompts at end of each screen for plotting and/or savingPlots each screen without promptingRestores default (screen graphics and no prompting)EDIT ExamplesELLIPSE (<strong>ASAP</strong> Command)Creates an elliptical edge/curve.Function• Define/Modify Curvedge EntitiesSyntaxELLIPSE X x y z [ n a a' ]Y y z xZ z x yOptionDescriptionX, Y or Z Specifies the axis of symmetryx, y or z Location along coordinate axis

<strong>ASAP</strong> | Commands and Macros (E) | 96Optiony z (z x or x y)na a'DescriptionSemimajor widths of the ellipseNumber of points (or segments) on the ellipse (default16)Angular range (in degrees from first semimajor axis)over which ellipse is defined (default is 0 to 360 degrees)Remarks1. The default number of points along the edges/curves of the ellipse is 16 or the value specified on a previousELLIPSE command. Use -n if you want it to become the default for future ELLIPSE commands.2. The default angular range over which the ellipse is defined is 0 to 360 degrees.3. The semimajor widths are measured to the points, not to the lines connecting the points.4. If n, a and a' are specified, they become the default settings for most future EDGE commands. They are only actualangles when they are multiples of 90 degrees or the aspect ratio of the figure is unity (that is, the ellipse becomes acircle). In the Z axis case, the effective and actual angles are related by the formula:x TAN(actual) = y TAN(effective)5. This edge is made up of coplanar straight line segments; that is, convex polygons whose vertices lie on a particularcurve.ELLIPSE ExamplesELLIPSOID (<strong>ASAP</strong> Command)Creates an ellipsoidal surface.Function• Define/Modify Surfunc EntitiesSyntaxELLIPSOID u v w [ x y z ] [ -X ]-Y-ZXYZOptionu v wx y z-X, -Y, -Z, X, Y, ZDescriptionSemi-lengths along each axisCenter of the ellipsoidCreate only this half of the ellipsoid<strong>Reference</strong> PointAt center of surface.Surface NormalAlong positive coordinate direction.Autolimiting

<strong>ASAP</strong> | Commands and Macros (E) | 97YesRemarks1. Creates a general ellipsoid with semi-lengths along each axis of u,v,w and center at (x,y,z).2. The normal vector points out and away from the center.3. Normally, a full closed ellipsoid is created (for example, a complete sphere). However, the additional literal entrycan be used, instead, to specify which half of the ellipsoid is wanted (for example, a hemisphere).ELLIPSOID ExamplesEMITTING (<strong>ASAP</strong> Command)Creates a composite single-source emitter from several EMITTING volume commands.Function• Create Rays and BeamsSyntaxEMITTINGw DISK ...RECTENTITYOBJECTCONEPYRAMIDBOXSPHEROIDRAYSFILAMENTHELIXIESDATAw' ...w" ...:Optionw w' w"DISK, RECT,ENTITY, OBJECT,CONE, PYRAMID,BOX, SPHEROID,RAYS, FILAMENT,HELIX, IES, DATADescriptionEmitting commands flux weighting factorsSpecific emitting commandsRemarks1. In both Jones vector mode and Stokes vector mode, randomization of the polarization state of the created rays canbe controlled by using POLARIZ RANDOM in <strong>ASAP</strong> 2009 and forward.2. Any of the EMITTING types may be used in a composite (single-source) emitter using the EMITTING format.3. The w's are the flux weighting factors for the individual component emitters.

<strong>ASAP</strong> | Commands and Macros (E) | 984. Only linear transformation commands are allowed between the individual emitter commands.5. Any USERAPOD commands defined before EMITTING is applied to all of the emitting types.EMITTING ExamplesEMITTING BOX/SPHEROID (<strong>ASAP</strong> Command)Creates a ray set uniformly distributed within a box or spheroid of an emitting volume.Function• Create Rays and BeamsSyntaxEMITTING BOX x y z u v w n [ X ]SPHEROIDYZOptionx y zu v wnX Y ZDescriptionCenter of emitting volumeSemimajor heights along x, y, and z axesTotal number of rays to be createdFlag to vary radiation non-isotropicallyRemarks1. Creates a ray set uniformly distributed within either a BOX or a SPHEROID centered at x,y,z..2. The total radiated flux of the volume is initialized to 1.0 without X, . . . and π/4 with X, . . .3. By default the radiation pattern is isotropic. If the optional axis flag is entered, the radiation pattern is a donut ortorus centered on that axis; that is, the radiation pattern is a function of the sine of the angle from that axis.4. The overall pattern can be apodized in position and/or direction by the current settings of the USERAPODANGLES or USERAPOD BOTH commands.EMITTING ExamplesEMITTING CONE/PYRAMID (<strong>ASAP</strong> Command)Creates a rayset uniformly distributed within a cone or pyramid.Function• Create Rays and BeamsSyntaxEMITTING CONE X x y z x' y' z' n [ ISO ]PYRAMID Y y z x y' z' x'Z z x y z' x' y'

<strong>ASAP</strong> | Commands and Macros (E) | 99OptionDescriptionX, Y or Z Coordinate axisx, y or z Location of the first face on the coordinate axisy z (z x or x y)x', y' or z'y' z' (z' x' or x' y')nISORemarksSemimajor heights in the given directions at the first faceLocation of the second face on the coordinate axisSemimajor heights in the given directions at the secondfaceTotal number of rays to be createdEmits as an isotropic source1. Creates a ray grid distributed within either an elliptical CONE or a rectangular PYRAMID emitting volume.2. The total radiated flux of the volume is initialized to π/4 without ISO and 1.0 with ISO.3. The number of rays per unit length along the axis is held constant so that the ray density is higher at a small end ofthe volume. This closely simulates the plasma in a compact arc lamp.4. By default the far-field radiation pattern is a donut or torus; that is, the radiation pattern is a function of the sine ofthe angle from that axis. The ISO option yields an isotropic radiation pattern.5. The overall pattern can be apodized in position and/or direction by the current settings of the USERAPODANGLES or USERAPOD BOTH commands.EMITTING ExamplesEMITTING DATA (<strong>ASAP</strong> Command)Creates rays from data in a given binary distribution file.Function• Create Rays and BeamsSyntax 1EMITTING DATA [ file ] [ n ] [ a [ a' ] [ RECT] ] [ ISO ]-DATA u+DATA name.BMPSyntax 2EMITTING DATA [ file | LIST ] [ n ] [ a [ a' ] [ RECT ] ] [ ISO ][DUPLICATE [m]][+/-]file1 [n1] [a1 [a1'] [RECT] ] [ISO] [DUPLICATE m1][+/-]file2 [n2] [a2 [a2'] [RECT] ] [ISO] [DUPLICATE m2]OptionfileuDescriptionName of the distribution data file (default extension is*.dis)FORTRAN unit number (default 9) of distribution datafile (default extension is *.dat)

<strong>ASAP</strong> | Commands and Macros (E) | 100Optionna a'RECTISODUPLICATELISTmfile1, file2 …DescriptionNumber of rays createdHalf-angles (in degrees) for the elliptical orRECTangular cone of emitted radiation centered on theaxisEmits as a rectangular coneSpecifies isotropic emissionCreates a multi-wavelength source from a single data fileby duplicating the data fileCreates a multi-wavelength source from a list of datafilesNumber of duplication times; the default is the numberof wavelengths set on the previous WAVELENGTH(S)commandName of the distribution data files for the LIST optionn1, n2 … Number of rays created from the corresponding filea1, a1’, a2, a2’ … Half angles (in degrees) for the elliptical or RECTangularcone of emitted radiation centered on the axis for thecorresponding fileRemarks1. Creates n rays at the current WAVELENGTH (or 3 WAVELENGTHS if a polychromatic bitmap) based on thedistribution stored in the distribution data file (default file.dis), unit number u (default 9), or standard bitmapname.BMP. The default for n is the total number of samples in the file.2. The EMITTING DATA command currently supports the following distributions:a. General list of rays in full (.*dis) or compressed (*.dmp) DUMP command format. If the current WAVELENGTHis zero, it is reset to the shortest one stored in the DUMP file header.b. Two-dimensional planar spatial distributions (for example, SPOTS POS, SPREAD). Optional half-angles indegrees for the elliptical or RECTangular cone of emitted radiation centered on the positive normal axis aredefined by a a'. The default for a' is a,; that is, circular or square light cone. The default for a is 90 degrees;that is, a full hemisphere. By default, the surface emits directionally in a Lambertian fashion or ISOtropically(the sign on the DATA literal determines into which hemisphere). This pattern can be further apodized indirection by the current USERAPOD DIR settings.c. General 3D volume distributions that emit isotropically in direction (unless USERAPOD ANGLES is set).d. Volumes with cylindrical symmetry (for example, ABEL INVERSE). Normally, the far-field radiation patternis a donut; that is, it varies as the sine of the angle from the axis. The ISO option yields an isotropic radiationpattern.3. Except for the first distribution, the rays are distributed spatially in a random fashion, using the given data as theprobability density function.4. Use the MOVE BY command to move the rays just off the geometry before tracing the rays.5. Two options, DUPLICATE and LIST, were added in <strong>ASAP</strong> 2010 to support EMIITING DATA in the creation ofmulti-wavelength sources from ray data files.6. DUPLICATE and LIST options cannot be used on the command line at the same time, since they are exclusive ofeach other; only one can be used on an EMITTING DATA command.7. Before using EMIITING DATA, the WAVELENGTH(S) command must be used first to define wavelengths forthe source, and then the SPECTRUM command can be used if source apodization is needed.8. The DUPLICATE option creates a multi-wavelength source from a single data file by duplicating the data fileat previously defined wavelengths with its spectrum weightings. The optional parameter m is the number of

<strong>ASAP</strong> | Commands and Macros (E) | 101duplications. The default number is the number of wavelengths defined in the previous WAVELENGTH(S)command.9. The LIST option creates a multi-wavelength source from a list of data files at previously defined wavelengths withits spectrum weightings. The wavelengths defined in the previous WAVELENGTH(S) command are subsequentlyused to match the files listed after the command, accounting for their duplication times. The user is responsible forcorrectly matching the wavelengths and files.10. For the LIST option, the settings of +/-, n, a, a’, RECT, or ISO on the EMITTING DATA command line are theglobal settings. The settings of +/-, n, a, a’, RECT, or ISO on each subsequent command line are local settings,and apply only to the file on the corresponding line. The local settings override the global settings if they arepresent. If local settings are not present, the global settings are used for the file.11. If the local DUPLICATE option is not present on a command line, the source is created at the wavelength to whichit corresponds. If the local DUPLICATE option is present, the duplication number m must also be present. The fileis used m times for m wavelengths, starting from the current wavelength, to create rays.12. The arguments on the command lines are divided into two groups. The first group, the numerical group, includesn, a, and a’. The arguments must be entered in the order shown in Syntax 2. For example, if a’ is present, n amust be present. The second group, the string group, includes ISO, RECT, and DUPLICATE m. The settings inthis group can be present independently in arbitrary order. The string group settings must be always used after thenumerical group settings, if there are any.13. <strong>ASAP</strong> quits reading the list of files if a RETURN command is specified on a command line, or if there is an errorreading from the specified data file. If the specified file does not exist, an unrecognized <strong>ASAP</strong> command error isissued instead of a file input/output error. This is because <strong>ASAP</strong> treats the file name as a new <strong>ASAP</strong> command.14. The original syntax and the new DUPLICATE and LIST options use different wavelength settings. Theoriginal syntax always creates sources at current system wavelength, which can be set by a WAVELENGTH(S)n UNIT script. The DUPLICATE and LIST options always use the wavelengths specified in the previousWAVELENGTH(S) command with multiple wavelengths, in the form WAVELENGTH n1, n2, n3 ..UNIT. Since the current system wavelength may differ from the first entry (n1) on the last WAVELENGTH(S)command, the EMITTING DATA file n script in the original syntax and the EMITTING DATA file nDUPLICATE 1 script may create sources at different wavelengths.EMITTING ExamplesEMITTING DISK/RECTANGLE (<strong>ASAP</strong> Command)Creates random emitting surfaces.Function• Create Rays and BeamsSyntaxEMITTING DISK X x y z n [ a [ a' ] [ RECT ] ] [ ISO ]RECT Y y z xZ z x y-X-Y-ZOptionDISK[RECT]RECTDescriptionEmitting surface is an elliptical/circular DISKElliptical/circular DISK emits as a rectangular coneEmitting surface is a RECTangular plane

<strong>ASAP</strong> | Commands and Macros (E) | 102OptionDescriptionX, Y or Z Coordinate axisx (y or z)y z (z x or x y)na a'ISORemarksLocation of plane on the coordinate axisSemimajor heights in the given directionsTotal number of rays createdHalf-angles (in degrees) for the elliptical orRECTangular cone of emitted radiation centered on theaxisSpecifies isotropic emission1. Creates a ray set that simulates either an elliptical/circular DISK or a RECTangular plane emitting surface. Theradiation pattern is by default Lambertian or may be made to emit ISOtropically.2. The total radiated flux of the surface is initialized to unity without ISO and 2.0 with ISO.3. The default for a is 90 degrees; that is, a full hemisphere.4. The default for a' is a (circular or square light cone).5. The surface radiates in the positive coordinate direction. To radiate into the negative coordinate direction, enterEMITTING DISK -X.6. The overall pattern can be apodized in position and/or direction by the current settings of the USERAPODcommand.EMITTING ExamplesEMITTING ENTITY or OBJECT (<strong>ASAP</strong> Command)Randomly distributes rays over the faceted surface(s) of SURFACE/EDGE entities or SURFACE/EDGE OBJECTS(entity number k or object k (number or name)).Function• Create Rays and BeamsSyntaxEMITTING ENTITY k [ n ] [ ISO ]OBJECT -k -n [ d ] NORM+nOptionkndNORMDescriptionEntity or object number or nameNumber of rays (default 100) per facetDistance from the actual smooth surface(s); -1 greaterthan d less than +1Directs rays exactly parallel to local surface normalRemarks

<strong>ASAP</strong> | Commands and Macros (E) | 1031. If the integer entry n is negative, its absolute value is the maximum number of uniformly distributed rays thatis created. If n is preceded by a plus sign, n is the number of rays per facet, and the total number of rays createddepends on the entity's intrinsic patching, the object's FACETS setting, and this value. In the absence of a leadingsign, the current default for emitting objects assumes the minus sign; that is, the total rays usage. The default foremitting entities assumes the plus sign. The default for n is 100.2. The resulting ray position lies very nearly on the actual smooth surface(s) of the entity or for an object, a distanced (default is a small fraction of largest limits box dimension) from the actual smooth surface(s). If floating pointnumber d is entered as exactly 0. The ray is tagged as being on the actual object instead of object zero.3. If NORM is specified, the ray is directed exactly parallel to the local surface normal. Otherwise, the raysdirectionally radiate in a random Lambertian or ISOtropic fashion from the surface(s).4. The sign of k controls the direction of the hemispherical emission relative to the local surface normal; that is,whether the emission is, for example, outward or inward from a sphere. Before apodization, the flux emitted by afacet is equal to its area. Therefore, the total flux in the rays approaches the total exact surface area of the object asthe number of facets increases.EMITTING ExamplesEMITTING EULUMDAT (<strong>ASAP</strong> Command)Creates a ray set that emits according to the photometric data in a European standard EULUMDAT file format.Function• Create/Modify ObjectsSyntaxEMITTING EULUMDAT name X x y z n [ a ]YZOptionnameDescriptionName of EULUMDAT data file with extension .LDTX, Y or Z Coordinate axis to associate with the file's polar axisx y znaRemarksEmitter coordinatesNumber of rays to createAzimuthal angle (in degrees)1. Creates a ray set that emits according to the data in a European EULUMDAT Photometric Data file calledname.ldt.2. The coordinate axis corresponds to the file's polar axis.3. An optional azimuthal angle a (in degrees) can also be specified to rotate the angular pattern around the polar axis.4. The USERAPOD settings do not affect EMITTING EULUMDAT, since the equivalent information is found in theEULUMDAT file.EMITTING FILAMENT (<strong>ASAP</strong> Command)Creates a randomly generated ray set that is uniformly distributed along a predefined or arbitrary curve.Function

<strong>ASAP</strong> | Commands and Macros (E) | 104• Modify Ray/Beam DataSyntaxEMITTING FILAMENT [ i ] [ fcn t' t" ] n [ r ] [ ISO ]Optionifcnt'DescriptionSpecifies the curveParametric function nameLower parametric boundt" Upper parametric boundnrISORemarksNumber of raysCross-sectional, semi-thickness of the wireSpecifies isotropic emission1. Creates n rays randomly but uniformly distributed either along previously defined curve i or the arbitrary curve,X, Y, Z[ ,W ] = fcn(t) t' < t < t"where the function name is defined by a previous $FCN command. The last three or four entries created by itsexpressions are the three coordinates and an additional flux weighting (apodization) value (default 1).2. With a semi-thickness r specified, the emitter becomes an emitting volume source. For example, the commandsfor a helical filament might be:R=1 radius T=5 turns L=5 length$FCN EFCN x R*COS(6.2832*T*_) y R*SIN(6.2832*T*_) z L*_ w !! 0

<strong>ASAP</strong> | Commands and Macros (E) | 105Z z z'Syntax #2 (long format)EMITTING HELIX X x y z x' y' z' t r n [ ISO ]Y y z x y' z' x'Z z x y z' x' y'OptionDescriptionX, Y or Z Coordinate axisx x', y y' or z z'thrnISOx y z, y z x, or z x yx' y' z', y' z' x', or z' x' y'RemarksThe initial and final coordinate along the axis (xx')=lengthNumber of turns (not necessarily integer)Outside radius of the helixRadius (semi-thickness) of the wireNumber of raysSpecifies isotropic emissionFirst elliptical shape (second syntax)Second elliptical shape (second syntax)1. Creates n random rays that follow a helical (spiral, spring, coil) curve.2. The t is the number of turns (not necessarily an integer).3. The h is the outside radius, and r the radius of the wire.4. Normally, each segment of the helix emits like a Lambertian cylinder.5. The ISO option forces each point to radiate isotropically.6. In addition to a true helix, EMITTING HELIX can also be used for some special cases of interest:a. Torus: set the two axial coordinates to be equal and t to one.b. Hollow Cylinder: set t to a high number and r to |x'-x|/2t (X case).7. The second syntax (long format) is more flexible since it lets the helix vary from one elliptical shape (unprimedcoordinates) to another (primed).8. To get a planar spiral, set the two axial coordinates in the second syntax (long format) to be equal.EMITTING ExamplesEMITTING IES (<strong>ASAP</strong> Command)Creates a ray set that emits according to Illuminating Engineering Society (IES) data.Function• Create Rays and BeamsSyntaxEMITTING IES name X x y z n [ a ]

<strong>ASAP</strong> | Commands and Macros (E) | 106YZOptionnameDescriptionName of IES data file with extension .IESX, Y or Z Coordinate axis to associate with the file's polar axisx y znaRemarksEmitter coordinatesNumber of rays to createAzimuthal angle (in degrees)1. Creates a ray set that emits according to the data in an IESNA Standard Photometric Data file called name.ies.EMIT IES and DISPLAY;IESFILE follow the LM-63-1995 or LM-63-2002 standard.2. For Photometry A and C IES files, settings of the polar axis of the RADIANT command and the polar axis of theEMITTING IES command determine source creation.3. The coordinate axis corresponds to the file's polar axis (vertical if type A or C photometry, horizontal if B).4. Use the same global polar axis specified on the RADIANT command as the same axis specified on the EMITTINGIES command. The SOURCE direction of the sources from which the current ray set is created is not important.Note: BRO does not recommend using +X, +Y, +Z for the polar axis on the RADIANT command whileusing with -X, -Y, and -Z for the axis specified on the EMIITING IES command or vice versa. To doso is to mix a right-handed coordinate system with a left-handed coordinate system. The resulting radiantintensity pattern created by the EMIITING IES command is inverted, and possibly reverted, requiringrotations to properly orient the source.5. The EMITTING IES command is primarily used to create sources from IES files provided by light sourcemanufacturers. To create sources from a current rayset in <strong>ASAP</strong>, an alternative and more efficient approach is touse the DUMP command to dump rays into a distribution file. EMITTING DATA is used to create new sourcesfrom the DUMPed file.6. An optional azimuthal angle a (in degrees) can also be specified to rotate the angular pattern around the polar axis.7. The USERAPOD settings do not affect EMITTING IES since the equivalent information is found in the IES file.EMITTING ExamplesEMITTING RAYS (<strong>ASAP</strong> Command)Creates an arbitrary set of rays.Function• Create Rays and BeamsSyntaxEMITTING RAYS [ n dx dy dz da db dc ]x y z a,b,c f s dx' [ y' z' a',b',c' f' s' d' ]:OptionnDescriptionNumber of random rays per input ray

<strong>ASAP</strong> | Commands and Macros (E) | 107Optiondx dy dzda db dcx y za,b,cfs dDescriptionDifferential spatial volume over which the rays arecreatedDifferential direction cosine over which the rays arecreatedGlobal spatial coordinate of an arbitrary rayGlobal direction vectors of an arbitrary rayFlux of an arbitrary raySize and divergence of an arbitrary rayRemarks1. Creates an arbitrary set of rays (one line of following input per ray) in terms of their positions, directions, fluxes,sizes, and divergences. Any trailing entries that are omitted take their value from the previous ray.2. Optionally, instead of each of these defined rays, n rays randomly distributed within the given half-intervals abouteach defined ray can be created.EMITTING ExamplesENCLOSED (<strong>ASAP</strong> Command)Calculates an encircled (ensquared) energy using a square array of points.Function• Display/Modify Data DistributionsSyntaxENCLOSED [ i j ] [ 'title' ]MAXOptioni jMAX'title'DescriptionPixel centerMaximum pointOptional title for plot (up to 64 characters)Remarks1. Sums the data within a square array of points centered about the pixel i j, the MAXimum point, or the centroid andplots the percent enclosed as a function of the size of the square.2. The title is delimited by a single quote ' , as shown.ENCLOSED ExamplesEND (<strong>ASAP</strong> Command)Terminates program processing.

<strong>ASAP</strong> | Commands and Macros (E) | 108Function• Save or Recover System Data and Control ExecutionSyntaxEND [ OFF ]NOWRemarks1. Immediately terminates the current session of <strong>ASAP</strong> and does either of two things:a. If in batch mode, returns control to the operating system, orb. If in interactive mode, executes a SYSTEM NEW and RESET.2. The OFF option temporarily turns off the processing of the END command. In other words, any END commandfollowing an END OFF command does not terminate the session but simply switches the input to interactivemode. This is useful for executing input files in interactive mode that also work properly in batch mode. Toterminate the session under these conditions, enter an END NOW or $EXIT command.Examples...(other <strong>ASAP</strong> commands entered in batch mode)...END OFFtoggles input to interactive mode...(other <strong>ASAP</strong> commands entered in interactive mode)...END NOWterminates <strong>ASAP</strong> execution...(other <strong>ASAP</strong> commands entered in interactive mode)...ENDterminates <strong>ASAP</strong> execution.END ExamplesENTITIES (<strong>ASAP</strong> Command)Defines mixed geometrical entities without using the EDGE, LENS, or SURFACE commands.Function• Define/Modify Entities or Single Entity ObjectsSyntaxENTITIES [ OBJECTS ]lens … [ 'name' ]edgesurfentity modifiers (for example, LOCAL, SWEEP)[ object modifiers (for example, INTERFACE, BOUNDS) ]lens' …edge'surf'

<strong>ASAP</strong> | Commands and Macros (E) | 109:Remarks1. Begin defining mixed geometrical entities without using the EDGE/CURVE, LENS, or SURFACE/FUNCTIONcommands.2. Optionally, make each subsequently defined entity an object automatically, without using the OBJECT command.This means that only single entity objects can be defined in this manner (although BOUNDS can still be applied ifthe bounding entities are defined in the normal manner before the ENTITIES OBJECTS command).3. All entity modifiers (for example, LOCAL, SWEEP) must precede any object modifiers (for example,INTERFACE, BOUNDS).ExampleThe following valid syntax creates objects automatically as entities are given:ENT OBJECTPLANE ........... 'BASE' !! These are just examples of some entitiesTUBE ............ 'WIRE1' !! that automatically become objects.TUBE............. 'WIRE2'REDEFINE COLOR 5!! This is a modifier for the above object,"WIRE2"RETURN!! This ends the ENT OBJECT list.Note:Do not enter ENTITY OBJECT. The correct syntax is: ENT OBJECT.ENTITIES Examples$ERR (<strong>ASAP</strong> Macro)Branches on an input error.Syntax$ERR label:label:Remarks1. Sets a flag so that when an input error occurs, <strong>ASAP</strong> skips records until a record starting with the label string isfound. Normal input processing resumes on the next record, and the flag is reset.2. The label must start in column 1 of the input record.$ERR ExamplesEULUMDATFILE (<strong>ASAP</strong> Command)Writes out an EULUMDAT format file.Function• Display/Modify Data Distributions

<strong>ASAP</strong> | Commands and Macros (E) | 110SyntaxEULUMDATFILE [ name [ SFLUX f ] [ ELLIP w l h ] ] [ PAD [ p ] ] [ 'string' ]RECTOptionnameSFLUXELLIP or RECTwlhPAD p'string'DescriptionName of the created file (extension is *.ldt)Causes the source flux f to be written to the header of theoutput EULUMDAT fileAdds the devices ELLIPtical or RECTangularwidth, length, and height to the header of the outputEULUMDAT fileWidth of the elliptical or rectangular deviceLength of the elliptical or rectangular deviceHeight of the elliptical or rectangular deviceFlag to pad the distribution with a value given by p(defaults to minimum value in the distribution if p isomitted)Adds a comment string to the header of theEULUMDAT fileRemarks1. Writes out a European EULUMDAT photometric data file (name.ldt) representing an angular distribution createdby either a RADIANT command or a SPOTS DIR and ANGLES combination.2. The device's RECTangular or ELLIPtical width w, length l, and height h can be written to the outputEULUMDAT file. Dimensions are written in meters.3. If the distribution does not start at 0 degree in polar or azimuthal angles, it can be optionally PADded with valuep, which defaults to the minimum value in the distribution. However, <strong>ASAP</strong> does not pad beyond the maximumangles for both polar or azimuthal angles if the distribution does not extend to their allowed maximums (180degrees for polar angle and 360 degrees for azimuthal angle).4. A comment string may be added to the header of the output EULUMDAT file.5. EULUMDATFILE must be executed from within the display mode, as shown in the following example:DISPLAY....ANGLES !!if requiredEULUMDATFILE filename...RETURNEULUMDATFILE Examples$EVAL (<strong>ASAP</strong> Macro)Evaluates a given $FCN function.Syntax

<strong>ASAP</strong> | Commands and Macros (E) | 111$EVAL vary a b n [ vary' a' b' n' ...] [ func [ func' ...] ][ 'title' ][ m ] d d'Remarks1. The first format evaluates the given $FCN functions while changing the internal register, vary from a to b in nsteps (up to 30000). Actually,2. Up to 60 variables are permitted. The resulting values in the function func (or the sum of the squares, if more thanone given) at the first three levels are continually written to a BRO binary distribution file called EVAL.DIS ormacro.dis (with optional title) for later processing. One additional evaluation is done with the registers reset totheir values at which the discrete value of func was minimum.3. The second format iterates the next input record either m times while changing the varys randomly, or to approachthe actual minimum of the sum of the squared funcs (up to 250). If m is specified the d are the probabilitydistribution types; that is,Otherwise, if m is not specified, d are fractional derivative increments, relative to the ranges a b that are usedto build a change matrix, which is solved by a Singular Valued Decomposition (SVD) technique. Double-sidedderivatives are computed to approximate a damping factor from the non-linearity predicted by the homogeneoussecond derivatives. Therefore, the required number of evaluations is 2*(variables+1); that is,4. The number of funcs should be greater than (>) or equal to (=) the number of varys for it to find a unique solution.For nonlinear problems, successive $EVAL commands may be needed to reach the precise minimum.$EVAL Examples$EXIT (<strong>ASAP</strong> Macro)Starts immediate program termination.

<strong>ASAP</strong> | Commands and Macros (E) | 112Syntax$EXITRemarks1. $EXIT is supported only in batch mode, not in the user interface.2. Immediately terminates program and returns control to the operating system. If the program is in interactive mode,you are asked to verify your decision to terminate program.3. $EXIT bypasses the normal <strong>ASAP</strong> shell program. As a result, it does not rename certain files from theirBRO0XX.DAT designation.$EXIT Examples$EXP (<strong>ASAP</strong> Macro)Switches the expression precedence.Syntax$EXP [ OLD ]NEWRemarks1. Instructs the parser to recognize the OLD left-to-right or the NEW operator precedence expression syntax; thedefault is NEW.2. When $EXP is set to OLD, consecutive operations are always evaluated from left to right with no operatorprecedence until a delimiter terminates the expression. Nested parentheses or brackets can be used whennecessary.3. The $EXP OLD should precede any arithmetic operations or variable designations defined using the OLD left-torightprecedence expression syntax. Users with .INR files and macros created prior to version 4.0 who do not wantto update the file syntax should include this macro in their .INR files.4. To reset <strong>ASAP</strong> to the default, BRO recommends you also include a $EXP NEW command at the end of a file,immediately before the END command.5. The defsetup.inr file runs at startup.6. $EXP may be used at any time to switch between expression syntax parsers.7. If no argument is given, the state before the last $EXP command is restored.$EXP ExamplesEXPLICIT (<strong>ASAP</strong> Command)Converts the current function to explicit form.Function• Define/Modify Surfunc EntitiesSyntaxEXPLICIT [ X ] [ m] [ SVD ]Y-Z

<strong>ASAP</strong> | Commands and Macros (E) | 113OptionDescriptionX, Y, or -Z Axis entrym Degree of the explicit polynomial (maximum 20)SVDRemarksFlag to perform a least squares fit operation1. Converts the current surface function to an explicit polynomial of degree m (maximum 20 and defaulted to theoptimum). This may be necessary if the function is used as a DEFORM on an OBJECT.2. The optional axis entry allows order doubling of certain coordinates to enforce symmetry.3. In general, the conversion is done by a Cholesky or Singular Value Decomposition (SVD) least squares fitoperation on the original surface's mesh points. Therefore, the original surface must have a LOCAL box and shouldprobably have PARAMETERIZE set to -Z.4. Unless the conversion is exact, the root-mean square (RMS) and MAXimum sag error is always displayed uponcompletion, the sign of the surface normal may change, which would affect its use as a BOUNDS entity.EXPLICIT ExamplesEXPLODE (<strong>ASAP</strong> Command)Explodes lens conicoids into separate surface objects.Function• Create/Modify ObjectsSyntaxEXPLODE +l [ macro ]-l [ macro ]+ALL-ALLOptionDescription+l or -1 Specifies lens to explode into separate surface objectsmacro+ALL or -ALLRemarksName of the created macro file (default extension*.MAC)Apply to all lens entities, not just one at a time1. Explodes the + lth or -lth LENS or +ALL or -ALL lens entities into separate SURFACE-based objects (or CURVEbasedobjects if the current macro library is the standard CADEQUIV.LIB).2. Creates glass inner edge, Mangin outer edge, and mirror back.3. When a sign precedes the entry, additional objects are created that represent mirror backs and the baffle,mounting, or edge surfaces that connect each coaxial lens surface.4. Use - for direct sloped cones or + for right cylinders. The resulting input commands either go into the filemacro.MAC or are immediately run from an internal buffer.5. The interfaces for the surfaces are preset as follows:

<strong>ASAP</strong> | Commands and Macros (E) | 114RefractiveReflectiveBack/EdgesLast primarily transmissive COATING PROPERTY orBARELast primarily reflective COATING PROPERTY orUnit reflectivityTotally absorbingEXPLODE ExamplesEXTEND (<strong>ASAP</strong> Command)Linearly extends one or both ends of a curve edge.SyntaxEXTEND d [ d' ]Optiondd'DescriptionStart of edgeEnd of edgeRemarks1. Linearly extends the start and end of the current edge a distance d and d', respectively.2. The default for d' is d. Enter a zero distance if you want to extend only the other end.EXTEND ExamplesEXTREMES (<strong>ASAP</strong> Command)Lists the minimum and maximum information regarding position, direction, flux, or optical path length in currentlyselected ray data.Function• Analyze Ray/Beam DataSyntaxEXTREMES POSITION [ k ]P#DIRECTIOND#FLUXLENGTHOptionkPOSITIONDIRECTIONDescription<strong>Reference</strong> ray number from which extremes aremeasuredPosition of base ray dataDirection of base ray data

<strong>ASAP</strong> | Commands and Macros (E) | 115OptionDescriptionP# Position of the parabasal ray specified by the value of #D# Direction of the parabasal ray specified by the value of #FLUXLENGTHRemarksFlux of the base ray dataOptical path length of the base ray data1. Determines the extremes in the ray data specified by the given option (POSITION, DIRECTION, etc.) and lists thecorresponding rays. By default the positions or directions of each base ray are used.2. Any particular parabasal ray may be selected by specifying its number # (that is, P0 means base ray position, D1first parabasal ray direction, and so on).3. The flux, current object, and optical path length of each extreme ray is listed along with all base coordinate data.4. If k is less than zero, the average of the ray data is used.EXTREMES Examples

<strong>ASAP</strong> | Commands and Macros (F) | 116Commands and Macros (F)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “F”.FACETS (<strong>ASAP</strong> Command)Controls the subdivision of mesh patches.Function• Create/Modify ObjectsSyntaxFACETS n [ n' ]-n -n'+n +n'Optionnn'DescriptionNumber of facets along the edge or curve (intra-edge)Number of facets between edges or curves (inter-edge)Remarks1. Sets the number of facet subdivisions in each mesh patch direction.2. The n specifies the number of facets along the EDGE or CURVE (intra-edge), and n' specifies the number of facetsbetween edges or curves (inter-edge). Greater numerical values of n and n' result in smoother looking plots, butlarger plot files.3. If n is unsigned, then this is the number that is always used.4. If n is positive, it is the maximum number of subdivisions relative to the corresponding number on a PLOTFACETS or VUFACETS command.5. If n is negative, its absolute value is the minimum number of subdivisions per patch.6. Controls the density of rays when applied to a GRID OBJECT or EMITTING OBJECT.7. A PLOT MESH shows the mesh boundaries.8. Note that some edges are discrete, and some are continuous; FACETS only controls how the entity is plotted andnot how continuous the entity is.FACETS Examples$FAST (<strong>ASAP</strong> Macro)Performs fast reading of numeric arrays.Syntax$FAST n [ m ] [ s ] [ COMPLEX ]label. . . n or 2n numbers:m records

<strong>ASAP</strong> | Commands and Macros (F) | 117[ label ]Remarks1. Macro reads directly from the current input file m records (default 1 or until label is reached, or until read error) ofn real or COMPLEX entries each.2. <strong>ASAP</strong> uses the flexible, list-directed input facility of Fortran and, therefore:• <strong>ASAP</strong> does not do the extensive parsing it normally does; that is, only numbers separated by a comma and/orblanks are accepted.• This input is never echoed to the output device.• If reading directly from a file and not indirectly from a macro or loop, <strong>ASAP</strong> attempts to read n times mnumbers, with line breaks required only after every nth number; that is, additional line breaks can be insertedso that lines are not limited to the normal 344 characters.• The number of data that $FAST itself can read is limited only by how high a 32-bit or 64-bit computer cancount using signed integers. Typically, the meaningful limit is imposed by the purpose for which $FAST isapplied. If, for example, $FAST is used to define POINTS for an EDGE, an implied limit on $FAST data forthis purpose is set by the Total CurvEdge Points, which depends on the version of <strong>ASAP</strong>. Another examplewould be the limit imposed by sampling points to create a SAMPLED surface, based on maximum allowedSampling Pixels on a Side (See DIMENSIONS command).3. Each number of the array optionally may be multiplied by a scale factor s (default 1).4. Optionally, <strong>ASAP</strong> can also assume each successive pair of numbers forms a COMPLEX (real, imaginary) entry. Inthis case, rule 3 above should be read with 2n substituted for n5. $FAST may be used in $DO and $ITER loops and in user-defined macros.$FAST Examples$FCN (<strong>ASAP</strong> Macro)Defines new in-line math functions.Syntax$FCN [ name [ e e' e" ... ] ]Remarks1. Macro defines a new in-line math function with up to a 32-character name. The new function may be used infuture arithmetic expressions just like the intrinsic functions SIN, COS, SQRT, and so on.2. The function is defined by the expressions ee'"e entered after the name. Up to 60 of these functions can be definedat any one time. The result of the last expression is the function value returned during processing.3. The dummy argument of the function is represented in the defining expressions as the base argument register "_".For example:$FCN SECH 2/(EXP(_)+EXP(-_))4. If no expressions are given, the function, name is deleted from internal storage. A $FCN command with no otherentries deletes all current user functions.5. These user-definable functions are recursive; that is, you may include one in the argument of another. Also,any registers/variables defined in the function before they are used are automatically assumed to be local to thatinstance of the function, and therefore do not conflict with any external (for example, global) ones of the samename.$FCN Examples

<strong>ASAP</strong> | Commands and Macros (F) | 118$FF (<strong>ASAP</strong> Macro)Inserts a form feed into the output stream.Syntax$FF [ text ]&FF kRemarks1. If $ prefix is used, a page advances or form feed is sent to the current output unit. Any text present on thiscommand (up to 62 characters) is also printed at the top of the page along with the current date and time.2. The integer entry form outputs only a form feed to logical unit k instead.3. If the &FF syntax is used, only the text (up to 80 characters) that is preceded and followed by single blank lines iswritten.$FF ExamplesFFAD (<strong>ASAP</strong> Command)Formats currently selected ray data and plots full-field aberration displays (FFAD).Function• Analyze Ray/Beam DataSyntaxFFAD [ SPOTS [ s ] ] [ REFERENCE w [k] ] [ LIST ]OptionSPOTSsREFERENCE w kLISTDescriptionPlots spot diagram at each field pointSpot diagram scale factorSmallest spot identifierLists the flux, centroids, and RMS sizes of each sourceRemarks1. Produces a real Full Field Aberration Display, which is a plot of the 3D best-focused RMS spot ellipses for eachfield position entered on the SOURCE command. The ellipses are scaled up so that the largest one just touches thespot from an adjacent field position. These plots are useful for identifying aberration nodes on the image surfacesof non-centered or perturbed systems.2. FFAD prints the statistics of the spots, including the best-fit planar and curved surface parameters.3. The corresponding unfocused ray SPOTS can also be plotted. The s (default=0.3) is an additional scale factor usedto make room for the spot patterns since they are always larger than the RMS ellipses.4. The REFERENCE option specifies the width w (in system units) of a square that is drawn around the smallest (orkth) spot.5. FFAD also prints out the statistics of the spots including the best-fit planar and curved surface parameters.6. The flux, centroids, and RMS sizes of each source can also be LISTed.

<strong>ASAP</strong> | Commands and Macros (F) | 119ExampleFFAD SPOTS REFERENCE 0.01 !plot spots with rms ellipsesSTATISTICS on best RMS spot sizes from 63 SOURCES:X Y ZOverallAverages 0.21973E-02 0.18023E-02 0.10722E-02 0.30374E-02Maximums 0.45477E-02 0.32650E-02 0.20836E-02 0.59736E-02at 57 57 5757Best-fit planar focal surfaceCENTER 0.4236867E-01 -.5913160E-10-.2902888E-03NORMAL 0.2065236E-01 -.2884811E-09 0.9997867Best-fit curved focal surface RADIUS,SHIFT -2.053243 0.8969964E-03• RMS deviations are scaled by a factor of 0.65212.FFAD ExamplesFFT (<strong>ASAP</strong> Command)Calculates the spatial frequency spectrum of current distribution data.Function• Display/Modify Data DistributionsSyntaxFFT [ f ] [ AMPLITUDE ] [SIZE [ m ] ] [ 'flabel' ]n PHASEMODULUSWAVEFRONTREALIMAGINARYENERGYOptionfmnAMPLITUDE, PHASE, MODULUS, WAVEFRONT,REAL, IMAGINARY, ENERGYflabelDescriptionFraction of grid of transformed data to be used to replacethe current distribution fileFourier transform size (see Remarks)Number of pixels in the transformed data to be used toreplace the current distribution fileTransform characteristic of interestNew label for functional dataRemarks1. Replaces the current distribution file with its spatial frequency spectrum. It does this by applying a Fast FourierTransform to an m by m block of data points, where m is the current Fourier transform size (2 raised to the mthpower, or as set by the FTSIZE command) minus one. See DIMENSION output.

<strong>ASAP</strong> | Commands and Macros (F) | 1202. If the original data area is smaller than m-by-m, the data is centered and any excess is zero filled.3. If the original data area is larger, you must make sure that most of the energy lies in the first m-by-m block. <strong>ASAP</strong>then takes the selected part (default MODULUS) of the center n-by-n or f*m-by-b*m area of the FFT as thecurrent data set.4. If f is an integer n greater than one, it is the actual number of pixels to use. <strong>ASAP</strong> calculates the default for n tomaintain the original data size.5. If f or n, are a negative number, the inverse FFT operation is performed.6. Applying the FFT command to the diffraction image of a point object generated by a SPREAD or OPDMAPcommand produces the classical MTF (Modulation Transfer Function) of the system.7. The spacing S' between sample points after the FFT is related to the original spacing S by:where the maximum pixel value determines the constant in the above expression.Use the flabel option to relabel the functional data.8. If the Fourier transformed field U(p,q) is written in the form:where A(p,q) is the real part and B(p,q) is the imaginary part of the field, then the components of the complexfield that can be displayed include:Option Operation Physical SignificanceAMPLITUDE sign(real( U )) | U | signed modulus of fieldPHASE arctan( B / A ) phase in radiansMODULUS | U | modulus of the fieldWAVEFRONT arctan( B / A ) / 2 p wavefront in wavesREAL real( U ) or A real part of fieldIMAGINARY imaginary( U ) or B imaginary part of fieldENERGY U U* modulus squared of field (energydensity)9. The phase transfer function (PTF) may be obtained by extracting the phase or wavefront from the FFT operation.The wavefront is usually better choice because it attempts to remove the 2π phase steps from the wavefront.FFT ExamplesFIELD (<strong>ASAP</strong> Command)Calculates the exact complex field distribution.Function• Calculate Diffraction/Propagation EffectsSyntax 1

<strong>ASAP</strong> | Commands and Macros (F) | 121FIELD... MODULUS ... [ option [ option' [ option" ... ] ] ]PHASEAMPLITUDEWAVEFRONTREALIMAGINARYENERGYNONESyntax 2FIELD ... component ... ADD ...MULTIPLYCOUPLE [ r v [ a ] ]Syntax 3FIELD ... component ... DELTA [ t ] ...Syntax 4FIELD ... component ... CONTOUR k ...c c' [ c" ... ]Syntax 5FIELD ... component ... PROPAGATE [ d ] ...OptionSyntax 1:AMPLITUDE, PHASE,MODULUS, WAVEFRONT,REAL, IMAGINARY,ENERGY, NONEDescriptionSpecify the field characteristic of interestSyntax 2:ADDMULTIPLYCOUPLE r v aSyntax 3:Flag for adding the calculated field to the existing opticalfield file (BRO029.DAT)The result is the product of the two fieldsFlag for coupling the calculated field to the existingoptical field file (BRO029.DAT) (see Remarks forSyntax 2)

<strong>ASAP</strong> | Commands and Macros (F) | 122OptionDELTA tSyntax 4:CONTOURkc c' c" ...Syntax 5:PROPAGATE dDescriptionConstant phase shift in units of cycles at the currentWAVELENGTHGenerates an additional contour plotUse k equally spaced contours; if k is less than zero, a"gray scale" plot is produced in place of the line contourplotSpecific contour levels to plotFree-space propagate the resulting field an additional ddistance (default is infinity) (see Remarks for Syntax 5)RemarksAll Syntaxes1. <strong>ASAP</strong> PRO can use only up to 2896X2896 pixels for scalar fields and vector fields. If you enter a pixel valuelarger than 2896, as in the following example, <strong>ASAP</strong> attempts to accommodate the larger number by resizing thegrid. <strong>ASAP</strong> issues a message: "Warning *** PIXELS has been reset to 3999", while the actual grid for the pixelsis resized to 3999X2096.WINDOW X -2 @1 Y -2 @1PIXELS 4000FIELD ENERGYSyntax 11. If the optical field U(p,q) is written in the form:where A(p,q) is the amplitude function and W(p,q) is the wavefront function, then the components of the complexfield can be displayed as shown:Option Operation Physical SignificanceAMPLITUDE sign(real( U )) | U | signed modulus of fieldPHASE2 π W(p,q) / λ phase in radiansMODULUS | U | modulus of the fieldWAVEFRONT W(p,q) / λ wavefront in wavesREAL real( U ) real part of fieldIMAGINARY imaginary( U ) imaginary part of field

<strong>ASAP</strong> | Commands and Macros (F) | 123Option Operation Physical SignificanceENERGY U U* modulus squared of field (energydensity)NONE -- none2. Except for NONE, writes the given component of the complex scalar (or last vector POLARIZATION) field to thestandard distribution file BRO009.DAT for later processing by DISPLAY. The original full complex scalar/vectorfield is always written to unit 29 (file BRO029.DAT).Syntax 21. If the ADD option is present, the calculated complex field is added to the previously stored field in theBRO029.DAT file.2. If the COUPLE option is present, the calculated field is coupled to the field previously stored in the file.3. Alternatively, you can directly COUPLE to the fundamental mode field of a circular fiber of core radius r,normalized frequency v, and optional gradient index power a (for example, 2 for parabolic, absent for step index).If MULTIPLY is specified, the result is the product of the two fields. In all three cases, the two fields should becalculated under the same conditions; that is, WAVELENGTH, PIXELS, and WINDOW settings. If you attempt tocalculate under differing PIXEL conditions, <strong>ASAP</strong> issues an error and does not perform the calculation. Youcan combine (with ADD, MULTIPLY, or COUPLE) any two distributions having the same PIXEL settings. Theresults are typically sensible only if the WINDOW settings and the WAVELENGTH settings also match.Syntax 31. A constant phase shift t (in cycles at the current WAVELENGTH) can be added to each beam. This is equivalentto calculating the field at a time other than t=0. If this DELTA option is present and a vector field is beingcalculated (that is, FRESNEL BOTH is set), <strong>ASAP</strong> produces a plot of polarization ellipses, or if t is given, arrowsrepresenting the relative magnitude and direction of the instantaneous electric field at each sample point.Syntax 41. The CONTOUR option generates an additional contour plot with fractional contours c c' ... relative to the fullrange of the function being plotted. Alternatively, k equally spaced contours can be specified. If k is less than zero,a grey scale plot is produced instead of the line contour plot.Syntax 51. At the current IMMERSE index and WAVELENGTH, free-space PROPAGATE the resulting field an additionaldistance d (default is infinity), using an approximate (ACCURACY LOW) to an exact (ACCURACY HIGH) FastFourier Transform (FFT) technique.ExampleNote:Regardless of the order the previous options are entered, the order in which FIELD actually performs itscalculations is as follows:1. Read/calculate field2. ADD, MULTIPLY or COUPLE with another3. CLIP with an entity or object4. DELTA polarization plot5. PROPAGATE additional distance6. Write distribution files7. CONTOUR plotFIELD ENERGY -1Distribution of data within:Across or Vertical: Z = -2.50000 to 2.50000 ( 5.00000 )

<strong>ASAP</strong> | Commands and Macros (F) | 124Down or Horizontal: Y = -2.50000 to 2.50000 ( 5.00000 )Sample plane at: X = -1.00000MINIMUM (m) = 0.000000 MAXIMUM (M) = 1.01502FIELD ExamplesFIELDBPM (<strong>ASAP</strong> Command)Field propagation through small geometries and inhomogeneous media.Function• Calculate Diffraction/Propagation EffectsSyntaxFIELDBPM u component [ d [ n ] ] [ BC [ i [ i' ] ] ] ...optionsn.e f f' i j i' j'Optionunn.ef f'i j, i' j'dBC...optionsDescriptionComplex distribution file numberNumber of intermediate locationsComplex distribution file nameDepth coordinate information used to determine the gridOne or both directions of the computational windowDistance in the depth directionBoundary conditionSee options in command syntaxRemarks1. FIELDBPM is the second version of the FIELD command that does not use any of the current ray/beam data.2. Takes the field stored in the complex distribution file number u or name (with extension) n.e, and propagatesit a distances d (or from f to f') in the depth direction by directly solving the partial differential harmonic waveequation (the scalar or semi-vectorial Helmholtz equation).3. The n is the number of equally spaced, intermediate propagation locations, at which the field distributions arewritten to the default binary files (BRO009.DAT and BRO029.DAT). The default is zero; that is, only the finallocation.4. A unique Finite Difference Beam Propagation Method (FD-BPM) technique is used, which is not only fast andaccurate, but automatically determines the best reference refractive index and axial step size for the given mediaand lateral sampling.5. The field is assumed to start entirely within the current IMMERSE medium, but then interacts with any othermedia it encounters. All media can be complex (ABSORBing), inhomogeneous (GRIN), and birefringent(CRYSTAL if the optical axis is parallel to one of the global coordinate axes).6. Any object geometry (including surfaces imported via CAD) can act as interfaces between the media, but theactual reflection and transmission coefficients of these objects are ignored.7. Whenever possible, order the media on the INTERFACE command of each object, so that the first media isbefore the surface and the second is after (relative to the positive X, Y, or Z depth axis direction). Also, the two

<strong>ASAP</strong> | Commands and Macros (F) | 125INTERFACE media entries must be separated by only a single comma (",") to indicate that there is a preferredorder to them. This separator permits nearly all "MEDIA mismatch" errors to be fixed quickly and automatically.8. To prevent spurious "numerical" reflections at the edge of the computational window, a physical (BC optionabsent) or numerical (BC option alone) absorbing region is implemented by default, which involves the outer 1/6pixels at each edge of the window (that is, a total of 1/3 of the pixels in each lateral direction). Otherwise, thefollowing explicit boundary conditions can be specified with the BC option for one (i) or both (ij) directions of thecomputational window (unprimed entries first end of window, primed second):BCDescription1 Number of pixels in each numerically absorbing band9. The normally integer is and js can also be entered as floating point fractions of the number of samples in therespective direction.10. The specific BPM algorithm that is used is capable of operating outside the normal "paraxial" region (smalldepartures from the factored plane wave), because it expands the lateral differential operator into higher orderterms. The order number is controlled by the current ACCURACY setting, and the possibilities are listed (fromfastest to slowest) below:ACCURACY setting Operator Order Max Angle from Axis CommentsLOW 1 10 Fresnel/paraxial/weaklyguidedapproximationMEDIUM 2 20HIGH 3 40 Wide-angle and/or largerefractive index variations11. Besides the obvious current restriction to scalar (non-vector) fields, there is also a basic limitation inherent in theBPM method: it tracks only the "forward" propagating component of the field, and thus ignores back-reflectedwaves and any flux lost to them. This means that it does a good job of predicting the relative shape and phase ofthe main field, but not necessarily the absolute magnitude.12. The advantage of the BPM method is that it relatively efficient at propagating wavefields through 3D volumes,versus a more rigorous Time-Domain (TD) method that is essentially 4D, and thus orders of magnitude slower forthe same size problem.13. The accuracy of the calculation is most directly affected by the lateral sampling used; that is, the number ofPIXELS for a given size WINDOW. Many problems require sub-wavelength sampling, which means a practicallimitation to small volumes. A good rule of thumb is to use a sample spacing of one-third of the shortestwavelength (the vacuum wavelength divided by the highest index in the volume). Some problems may allowcoarser sampling, while others require finer sampling. The best indicator of accuracy is the two numbers displayedunder the "Relative Flux" heading during the propagation. For a non-absorbing (actual and/or numerical) problem,the closer these numbers stay to unity during the entire propagation, the more accurate the final result. To reducetheir fluctuation, decrease the lateral sample size (for example, increase the number of PIXELS). Be carefulthough, the number of longitudinal steps required may increase dramatically along with run times.14. As with virtually all types of numerical simulations, there is a tradeoff between speed and accuracy. BROrecommends that the optimum sampling for a given problem be found first, with a fast two-dimensional version(negligible width in second WINDOW direction), before proceeding to the full 3D calculation. For 3D problemswith cylindrical symmetry, a fast, radially symmetric calculation can be done by using the following commandsequence:

<strong>ASAP</strong> | Commands and Macros (F) | 126WINDOW Y 0 rmax X -tiny tinyFIELD ENERGY ...!create 1D starting fieldAXIS ZFIELD 29 ENERGY dist ... !propagate a distancewhere, in this example, Z is the symmetry and propagation axis.FIELDBPM ExamplesFIELDSUM (<strong>ASAP</strong> Command)Sums coherent beams.Function• Calculate Diffraction/Propagation EffectsSyntaxFIELDSUM component [ f [ f' n ] ] ...options[ l l' m m' x y z x' y' z' x" y" z" ]Optionf f'nDescriptionDepth coordinate information used to determine the gridNumber of stepsx, y, z Origin position vectorx'x", y'y", z'z"...optionsRemarksTwo direction increment vectorsSee options in command syntax1. FIELDSUM is a more general implementation of the (Gaussian) beam summation technique than the SPREADNORMAL method. It sums ALL coherent beam contributions from the current ray set, including multiplewavelengths.2. Any component of the resulting complex scalar or vector field can be calculated and displayed on an orthogonal orarbitrarily oriented skew planar grid.3. Normally, the grid is determined by the last WINDOW and PIXELS commands, and the third depth coordinatevalue f (or a range from f to f' in n steps).4. If f is omitted and the next command starts with a number, the grid information is read from that command. Thisskew planar grid is specified by an origin position vector (x,y,z) and two direction increment vectors, (x’,y’,z’) and("x,"y,"z.) The integer ranges of the two grid coordinates are given by l to l’ for the first direction and m to m’ forthe second. In other words, the actual grid coordinates in global coordinates are given by:x(i,j) = x + ix' + jx"i=l,l' j=m,m'y(i,j) = y + iy' + jy"z(i,j) = z + iz' + jz"For the total number of grid points, refer to the FIELD command.5. The printed map of the desired field component is displayed if the GRAPHICS unit is active (see $IO macro).FIELDSUM Examples

<strong>ASAP</strong> | Commands and Macros (F) | 127FITTED (<strong>ASAP</strong> Command)Creates a surface specified by curve fitting an arbitrary set of points.Function• Define/Modify Surfunc EntitiesSyntax 1:FITTED [ X ] [ k ] [ t ] [ SVD [ m ] ] [ FIXTERM [n] ] [ EDGES -n ][ VECTOR c ]Yi i' i"Z-X-Y-ZEXPLICIT[ fcn ]coord coord' coord"x y z [ ABS ] x' y' z' x" y" z" ...RELx y z x' y' z' x" y" z" ...:Syntax 2:FITTED PLANE [ EDGES -n ] [ VECTOR c ] ]PARABOLOID i i' i"SPHEREELLIPSOIDfcn[ coord coord' coord" ]x y z [ ABS ] x' y' z' x" y" z" ...RELx y z x' y' z' x" y" z" ...:OptionDescriptionX, Y, Z, -X, -Y or -Z Axis for order-doubled polynomialk Degree of polynomial surface fit (default 2)tSVD mFIXTERM nEDGES -nEDGES i i' i"VECTOR cCoefficient threshold (default 1.E-5)Singular Value Decomposition optionNumber of the term to be normalized to 1 (see Remarksfor default)Uses points on last n EDGES for fitUses points on EDGES i through i', incremented by i" forfitPuts each data point in the current 3D file as a dot ofcolor c (default 1) for later plotting

<strong>ASAP</strong> | Commands and Macros (F) | 128OptionEXPLICITcoord coord' coord"x y z x' y' z' x" y" z" ...ABS RELDescriptionExplicit function optionSpecifies data coordinate orderPoints for fitSpecifies how data is referenced<strong>Reference</strong> PointSee RemarksSurface NormalAlong negative coordinate axisAutolimitingSee Syntax and OptionsRemarks1. Fits a polynomial surface of degree k (default 2) in a least-squares sense to the set of points given on successivecommands. The points on the last n EDGES, or EDGES i through i' are incremented by "i.2. The optional literal entries (X, Y, Z, -X, -Y, -Z) are the same as the ones on the GENERAL command, and specifysome required symmetry.3. <strong>ASAP</strong> saves the maximum extents in each coordinate direction, and uses these as the default LOCAL box modifier.4. The t is an optional threshold between 1.E-8 and 1.E-2 (default 1.E-5), below which the relative contribution of asurface coefficient is assumed to be negligible, so that it is reset to zero. If the highest-order surface coefficientsare all zero, the degree of the surface is reduced accordingly.5. The rarely needed FIXTERM option specifies the number of the term to be fixed or normalized to 1. The default isthe largest component of the normal to the surface through the first point (if the point lies on the surface) or zero(constant term).6. By default, the EXPLICIT solution is a Cholesky decomposition of the normal matrix, which can accept anynumber of data points. You can elect to do a more robust SVD solution, but the maximum number of data pointsit accepts is limited (see output from the DIMENSIONS command). If m is given, only every mth point is used,which may be necessary to get below this limit.7. When entering points directly, the first point always becomes the reference point of the surfaces and, by default,<strong>ASAP</strong> assumes that the surface also passes exactly through this point; that is, the constant coefficient of thesurface function is set to zero. However, if the literal option is placed after the first three entries, this referencepoint is not on the surface (constant coefficient nonzero), and all other points entered are either measuredABSolutely or RELatively from it.8. The VECTOR options puts each data point in the current 3D file as a dot of color c (default 1) for later plotting bya REPLOT, DRAW or $VIEW command.9. By default, the ordering of a triplet of numbers describing a point is (x,y,z). You may specify a different order bylisting the coordinate order. For example, to specify data as (z,x,y),, enter (Z,X,Y).Remarks for Syntax #21. The given specific surface type is fitted in a least-squares sense to the set of points given on successivecommands, the points on the last n EDGES, or EDGES i through i' by "i.2. When entering points directly, the first point always becomes the surface’s reference point. However, if the literaloption is placed after the first three entries, this reference point is not on the surface (constant coefficient nonzero),and all other points entered are either measured ABSolutely or RELatively from it. The VECTOR optionsputs each data point in the current 3D file as a dot of color c (default 1) for later plotting by a REPLOT, DRAW, or$VIEW command.3. The input points can be remapped by specifying the coordinate (X, Y, or Z) to which each triplet value actuallycorresponds. Alternatively, you can remap each input triplet using a previously defined $FCN fcn that takes

<strong>ASAP</strong> | Commands and Macros (F) | 129_1,_2,_3 as the entered values and returns three results. This latter capability can be used to convert input points incylindrical or spherical coordinates to their required Cartesian equivalents.FITTED ExamplesFLUX (<strong>ASAP</strong> Command)Modifies ray fluxes of currently selected ray data.Function• Modify Ray/Beam DataSyntaxFLUX a [ b [ i j ] ]TOTALSOU mOptiona bi jTOTALSOU mDescriptionScale factors for ray fluxes<strong>Inc</strong>lusive ray numbersChange the fluxes to produce a total flux bSource numberRemarks1. Scales the fluxes for the currently SELECTed ray set (or the rays specified by the optional i and j) according to thefollowing equation:2. The default for b is zero.3. Alternatively, the TOTAL option specifies that the fluxes be changed to produce a total flux b.4. <strong>ASAP</strong> ignores rays with fluxes less than or equal to the CUTOFF value in any calculation.5. The presence of a BEAMS command changes the way <strong>ASAP</strong> assigns flux values to the rays. Given a GRID XXXR r p q s t m n command where XXX is either elliptical or rectangular, the flux per ray is computed asfollows:BEAMS INCOHERENT GEOMETRIC: (q - p)(t - s) / (mn) = flux / rayBEAMS COHERENT DIFFRACT: (q - p)(t - s) / (2mn w^2) = flux / ray6. The GRID POLAR command is too general for this simple calculation to apply, since <strong>ASAP</strong> has to perform allkinds of manipulations (including a least squares fit) to get the fluxes correct.7. By default all rays entered through the RAYSET command have unity flux assigned to them.FLUX ExamplesFMAP (<strong>ASAP</strong> Command)Creates a contour slice map of a 3D surface.Function

<strong>ASAP</strong> | Commands and Macros (F) | 130• Define/Modify Surfunc EntitiesSyntaxFMAP f [ f' n ][ r x y z ]Optionf f'nrx y zDescriptionCutting plane depth coordinate (or range)Number of steps for cutting plane depth coordinate rangeRadius of sphere from which the difference betweensurface and sphere is calculatedCenter of sphere (global coordinate)Remarks1. Can follow any surface definition commands and generates a contour map of one (or more) cuts of the current3D surface function. The paper coordinates and ranges are given by the last WINDOW command. The resolution isgiven by the PIXEL command.2. The depth coordinate's cutting plane value is f (or f to f' in n steps). The map indicates the different branches,sheets, and regions of the function and its sign so that any problems with signs of normals and unexpectedintersections can be graphically verified.3. Optionally, the difference between the surface and a sphere of radius r centered at (x y z) can be displayed.4. A distribution file of the surface data is also created on logical unit 9 (BRO009.DAT) for later processing by theDISPLAY commands.FMAP ExamplesFOCUS (<strong>ASAP</strong> Command)Determines the best 3D focal point of currently selected ray data.Function• Analyze Ray/Beam DataSyntaxFOCUS [ MODE [ m ] ] [ MOVE [ r ] ]OptionMODE mMOVEMOVE rDescriptionSpecifies the method of determining the best 3D focalpoint for the current ray bundleTransfers currently selected ray data to a plane thatpasses through the best 3D focal pointTransfers currently selected ray data to a referencesphere of radius r centered on the best 3D focal pointRemarks1. Determines the best 3D focal point and RMS deviations of the ray data from this point for the current ray bundleusing one of the following methods (listed from fastest to slowest):

<strong>ASAP</strong> | Commands and Macros (F) | 131MODEMETHODm0 Above plus first m parabasal rays2. In general, use CONSIDER to isolate the object of interest before using FOCUS. If you do not, FOCUS uses raydata from all available objects and gives you the wrong answer.3. If there are several sources, you may need to use SELECT to isolate a particular source to avoid the problemdescribed previously.4. The MOVE option calculates best focus and then moves the current ray bundle to the plane that passes through thisfocal point.5. The SPOTS command can then be used to generate a spot diagram at this best focus.6. MOVE r is used to move the ray data to a reference sphere centered on the best focal point and adjust the opticalpath lengths so that geometric wavefront analyses may be performed. The peak-to-valley and RMS optical pathdifferences are also printed out.Example--- SELECT ONLY SOURCE 1160 ray flags changed80 rays now selected--- STATS POSCurrent Statistics for Object 0 -Total Flux = 13.1172 from 80 rays ( 33.33%)XYZCentroid: 0.185707E-07 -.461274 0.000000RMS Deviation: 0.951377 0.961321 0.000000Maximum Spread: -1.80000 -1.33873 0.000000to 1.80000 2.26127 0.000000--- FOCUSLeast Squares Focus Calculation for 80 Rays:X Y ZCentroid Point 0.0000000 -3.000000 3.000000RMS Deviations 0.3033E-07 0.7508E-07 0.8019E-07Mean Direction 0.0000000 -0.6244647 0.7810531Total Flux = 13.12 RMS Blur Diameter = 0.1832593E-06Maximum Ray Angle from Mean = 25.1041 degrees, F/ 1.067--- FOCUS MOVELeast Squares Focus Calculation for 80 Rays:XYZCentroid Point 0.0000000 -3.000000 3.000000RMS Deviations 0.3033E-07 0.7508E-07 0.8019E-07Mean Direction 0.0000000 -0.6244647 0.7810531Total Flux = 13.12 RMS Blur Diameter = 0.1832593E-06Maximum Ray Angle from Mean = 25.1041 degrees, F/ 1.067--- STATS POS

<strong>ASAP</strong> | Commands and Macros (F) | 132Current Statistics for Object 0 -Total Flux = 13.1172 from 80 rays ( 33.33%)XYZCentroid: 0.462397E-17 -3.00000 3.00000RMS Deviation: 0.547368E-16 0.198808E-15 0.146429E-15Maximum Spread: -.146438E-15 -.888178E-15 -.444089E-15to 0.285834E-15 0.888178E-15 0.444089E-15--- FOCUS MOVE -10Least Squares Focus Calculation for 80 Rays:XYZCentroid Point 0.3239507E-17 -3.000000 3.000000RMS Deviations 0.5079E-16 0.8324E-16 0.9947E-16Mean Direction 0.0000000 -0.6244647 0.7810531Total Flux = 13.12 RMS Blur Diameter = 0.2206772E-15Maximum Ray Angle from Mean = 25.1041 degrees, F/ 1.067Flux weighted statistics:P-V Optical Path Difference =Wavefront Variance (RMS) =0.280714E-11 waves0.412710E-12 wavesFOCUS ExamplesFOLD (<strong>ASAP</strong> Command)Averages the current distribution data about the pixel number of the specified coordinates.Function• Display/Modify Data DistributionsSyntaxFOLD [ FIRST ] [ n ]SECONDBOTHOptionFIRSTSECONDBOTHnDescriptionAverage the data about the center of the first coordinateAverage the data about the center of the secondcoordinateAverage the data about the center of both coordinates(default)Absolute or fractional pixel numberRemarks1. Averages the current distribution data about the given absolute or fractional pixel number n (default is center) ofthe FIRST (vertical), SECOND (horizontal) or BOTH (default) coordinates.

<strong>ASAP</strong> | Commands and Macros (F) | 1332. Useful for distributions that should be perfectly symmetric about one or both centers but are not due to samplingand/or statistical errors.FOLD ExamplesFORM (<strong>ASAP</strong> Command)Controls the form of the current distribution data.Function• Display/Modify Data DistributionsSyntaxFORM [ f ] [ 'flabel' ]OptionfflabelDescriptionControls the form of the data to be plotted (default=1)New label for functional dataRemarks1. Either raises the data in the current distribution data file to a power or puts it into log (base 10) space.2. The default value of f is one, which does nothing to the data.3. If f is greater than zero, the data is raised to that power (that is, FORM .5 takes the square root of the distributiondata) before plotting.4. If less than zero, the common logarithm of the data is plotted with f setting a lower cutoff relative to the datamaximum.5. If the distribution has any negative values in it, a bias is added to make all values greater than or equal to zerobefore the requested operation takes place.6. Use flabel to relabel the functional data.FORM ExamplesFRESNEL (<strong>ASAP</strong> Command)Adjusts the reflection/transmission coefficients specified on an interface using Fresnel's formulae during a ray trace.Function• Create/Modify Objects• Setup TraceSyntaxFRESNEL [ TIR ][ OFF ]AVESPBOTHk

<strong>ASAP</strong> | Commands and Macros (F) | 134OptionTIROFFAVESPBOTHkDescriptionNo variation with angle of incidence up to the criticalangle, then TIRNo variation with angle of incidence (default)<strong>Inc</strong>oherent average of polarizationsS polarization coefficient onlyP polarization coefficient onlyBoth separatelyControls which Fresnel coefficient to use in therefraction calculationRemarks1. This command can be used either as a local command to override defaults for the current object, or as a globalcommand. In the latter case, the command acts as an interface control and becomes the default used by any objectfor which it is not explicitly set. Since the global command is identical to the OBJECT subcommand, make sureyou are not at the OBJ> prompt when you use it as a global command. If you are, issue a RETURN command first.2. FRESNEL is typically used with a bare coating, specified on the INTERFACE command, and a split level of oneor higher. See the topic, "Combinations of INTERFACE and FRESNEL Settings" for other settings.3. FRESNEL can be applied globally or on an OBJECT-by-OBJECT basis, as a global modifier. One of thepolarization components of a ray is eliminated at any objects that do not have FRESNEL BOTH set.4. Signals <strong>ASAP</strong> to take into account the variation of the reflection and transmission coefficients with incidenceangle at the object's interface and adjust the flux accordingly. It does this by evaluating the media on either side ofthe interface and then applying the Fresnel formulae.CAUTION• It is not possible to globally apply FRESNEL BOTH and then locally (to a specific surface, for example) applyFRESNEL OFF. The FRESNEL OFF is ignored.• FRESNEL must be used whenever you want to recalculate the reflection/transmission coefficients for each rayduring a ray trace.• The k parameter, or equivalent literal entry, determines which Fresnel coefficient to use in the refractioncalculation, as shown by the following:Literal Integer k DefinitionTIR -2 Allow TIR rays but no angular fluxvariation for othersOFF -1 Use normal incidence properties forall rays (default)AVE 0 <strong>Inc</strong>oherent average of polarizationsS 1 S polarization coefficient onlyP 2 P polarization onlyBOTH 3 Both polarizations separatelyFRESNEL Examples

<strong>ASAP</strong> | Commands and Macros (F) | 135FTSIZE (<strong>ASAP</strong> Command)Sets the Fourier Transform size to the default maximum.Function• Save or Recover System Data and Control ExecutionSyntaxFTSIZE [ m ]Remarks1. Sets the Fourier Transform size used by future DECOMPOSE DIR, OPDMAP PSF, and FFT commands to thedefault maximum recommended (as shown by DIMENSIONS command) or 2 raised to the mth power.2. The default size at startup (or after a RESET or END) is 9; that is, 512 samples.3. The absolute maximum allowed is 16 (65536 samples).FTSIZE Examples

<strong>ASAP</strong> | Commands and Macros (G) | 136Commands and Macros (G)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “G”.GAUSSIAN (<strong>ASAP</strong> Command)Creates a beam set simulating a coherent astigmatic Gaussian mode.Function• Create Rays and BeamsSyntax 1 - Long formGAUSSIAN X x x' x" n' n" m' m" a' a" [ DEGREES ]Y y y' y"RADIANSZ z z' z"Syntax 2 - Short formGAUSSIAN X x x' n a [ DEGREES ]Y y y' RADIANSZ z z'OptionDescriptionX, Y, or Z Axis of symmetryx, y, or z Rays/beams starting planex' x", y' y", or z' z"nn' n"m' m"aa' a"DEGREES or RADIANSRemarksFirst and second waist locationsNumber of rays/beams along waist directionNumber of rays/beams along waist directionsMode numbers along waist directionsWaist semiwidth (or angular semidivergence)Waist semiwidths (or angular semidivergences)Units for a' "a (angular semidivergences)1. Creates an astigmatic Hermite-Gaussian field distribution propagating in the specified direction and starting at thegiven plane.2. The GAUSSIAN command takes the place of the GRID and SOURCE commands since this information isspecified directly on the GAUSSIAN command.3. The WAVELENGTH must be previously defined, and the field created has total flux identical to a unit peakirradiancefundamental mode.4. GAUSSIAN has two modes of operation:

<strong>ASAP</strong> | Commands and Macros (G) | 137• Specify the general astigmatic properties of the GAUSSIAN beam in terms of waist locations and semiwidths(that is, a HeNe laser).• Specify the general astigmatic properties of the GAUSSIAN beam in terms of the waist locations and angularsemidivergences (that is, a semiconductor-like laser).5. The waist location is determined by the right-hand rule. For example, x' is the waist location (or line focus) alongthe y direction, and "x is the waist location (or line focus) along the z direction.6. When you specify angular semidivergences, you should not have a coincident ray starting plane and waistlocations. Start the rays at a distance away from the waist locations and use the MOVE command to move the raysto the actual waist locations.7. The current CLIP POSITION and flux CUTOFF/HALT settings may be used to truncate the rays created withthe GAUSSIAN command.8. When the beam is in the fundamental mode, circularly symmetric, and not astigmatic, then the short form may beused.Example--- CF=0.8862269--- UNITS MM--- RAYS 00 rays defined--- WAVELENGTH 0.6328 UM--- PARABASAL 4; WIDTH 1.6--- GAUSSIAN Z 0 0 0 21 21 0 0 0.4*CF 0.6*CFOVERALL Gaussian semi-widths 0.354491 0.531736wavefront curvatures 0.000000 0.000000Individual beam semi-widths 0.716071E-01 0.107411( 113.159 169.739 waves)293 rays created in a GAUSSIAN distribution for a total 293GAUSSIAN ExamplesGENERAL (<strong>ASAP</strong> Command)Creates a general surface defined by polynomial coefficients.Function• Define/Modify Surfunc EntitiesSyntaxGENERAL [ X ] [ x y z [ c c' c" ... ] ]COEFFICIENTS YZ-X-Y-ZEXPLICITXiYjZk c [ c' c" ... ]:OptionDescriptionX, Y, Z, -X, -Y, or -Z Axis for order-doubled polynomial

<strong>ASAP</strong> | Commands and Macros (G) | 138Optionx y zc c' c" ...COEFFICIENTSEXPLICITXiYjZkDescription<strong>Reference</strong> pointPolynomial coefficientsSynonym for GENERALExplicit function optionCoefficient term representation<strong>Reference</strong> PointAs givenSurface NormalAs definedAutolimitingNoRemarks1. An entirely general surface may be created by directly entering a reference point and any of the up to 286 singleprecisionpolynomial coefficients. This can be done either on the GENERAL command starting with the lowestordercoefficient, or on successive commands that begin with the coefficient of the term represented by XiYjZk,where i,j,k are integer powers. Any coefficients that are not entered are set to zero.2. In effect, all other SURFACE definition commands are shorthand for GENERAL, since <strong>ASAP</strong> saves surface dataonly in this form. The surface may be written as a 10th-order polynomial in the three Cartesian coordinates asshown in the following equation.where (x 0 ,y 0 ,z 0 ) defines the reference point of the function.3. The c entries are the coefficients of the 286-term function defining polynomial. These polynomials are ordered asshown in the table (numbers in the Terms column are powers):Order0 Constant CTerms1 Linear X Y Z2 Quadric X2 XY XZ Y2 YZ Z23 Cubic X3 X2Y X2Z XY2 XYZ XZ2 Y3 Y2Z YZ2 Z34 Quartic X4 X3Y X3Z X2Y2 X2YZ X2Z2 XY3 XY2Z XYZ2XZ3 Y4 Y3Z Y2Z2 YZ3 Z45 th-order X5 X4Y X4Z X3Y2 X3YZ X3Z2 X2Y3 X2Y2ZX2YZ2X2Z3 XY4 XY3Z XY2Z2 XYZ3 XZ4 Y5 Y4Z Y3Z2Y2Z3 YZ4 Z5

<strong>ASAP</strong> | Commands and Macros (G) | 139OrderTerms6 th-order X6 X5Y X5Z X4Y2 X4YZ X4Z2 X3Y3 X3Y2ZX3YZ2X3Z3 X2Y4 X2Y3Z X2Y2Z2 X2YZ3 X2Z4 XY5XY4Z XY3Z2XY2Z3 XYZ4 XZ5 Y6 Y5Z Y4Z2 Y3Z3 Y2Z4 YZ5Z67 th-order X7 X6Y X6Z X5Y2 X5YZ X5Z2 X4Y3 X4Y2ZX4YZ28 th-order X8 ...9 th-order X9 ...10 th order X10 ...X4Z3 X3Y4 X3Y3Z X3Y2Z2 X3YZ3 X3Z4 X2Y5X2Y4Z X2Y3Z2X2Y2Z3 X2YZ4 X2Z5 XY6 XY5Z XY4Z2 XY3Z3XY2Z4XYZ5 XZ6 Y7 Y6Z Y5Z2 Y4Z3 Y3Z4 Y2Z5 YZ6 Z74. In the 10th-order polynomial equation, fcn is the name of an optional macro function (intrinsic; for example, SINor user-defined $FCN).5. The optional coordinate axis is a flag for <strong>ASAP</strong> to create a surface/function with symmetry about some plane oraxis. Substituting one or two of the coordinates in the functional equation with their squares, effectively doublingthe order of the polynomial, does this.6. The mathematical effect of order doubling is:Entry Mathematical Effect Geometrical EffectXis replaced bysymmetry about local x plane-Xis replaced bysymmetry about local x axisis replaced by7. The alternate EXPLICIT entry removes all Z-dependent terms from the polynomial except an implied linear zcoefficient of -1 as shown in the following equation.

<strong>ASAP</strong> | Commands and Macros (G) | 1408. This general 2D polynomial can go as high as the 20th order in X and Y.ExampleA sphere of radius 5 centered at 0,0,2 could be defined in the following ways:GENERAL 0 0 2 -25 0 0 0 1 0 0 1 0 1GENERAL 0 0 2; C -25; X2 1; Y2 1; Z2 1GENERAL -Z 0 0 2; C -25; X2 1; Y2 1; Z2 1GENERAL ExamplesGET (<strong>ASAP</strong> Command)Retrieves ray data and copies it into variables.Function• Modify or Use Internal Ray/Beam Data as InputSyntaxGET [ k [ k' ] ]Optionk k'DescriptionNumber of a given ray or range of raysRemarks1. Get the current data for all rays, ray k, or rays k to k' and place it into the input registers. This data can then beused in any future commands and can even be modified if the PUT command is used.2. If more than one ray is selected, registers contain flux-weighted averages (except total flux).3. The register assignments are as follows:Register Literal Ray/Beam DataA0,B0,C0 X,Y,Z_DIR_B Absolute X,Y,Z direction cosines ofbase rayAi,Bi,Ci X,Y,Z_DIR_i Relative direction vector of ithparabasal rayD0 OPL Optical path length from start ofbase rayE1,E2,E3 X,Y,Z_EPOL Components of unit polarizationvectorF0 FLUX Total flux in ray/beamG0 DIVERG Average divergence angle of beam

<strong>ASAP</strong> | Commands and Macros (G) | 141Register Literal Ray/Beam DataH0 HEIGHT Average height of beam centered onbase rayIi PREV_O_i ith previous split object for ray/beamJ0 SOURCE Source number from which ray/beam originatedK0 CURR_OBJ Current object at which ray/beam islocatedL0 HITS Total number of surfaces ray has hit(intersected)M0 MEDIUM Medium of the ray/beamN0 SPLITS Number of times ray/beam was splitN1 LEVELS Number of times ray/beam wasscatteredP0 POLAR_0 Relative modulus of fundamentalbeam modeP1,P2 POLAR_1,2 Relative moduli of polarizationcomponentsQ0 NUM_RAYS Total number of ray/beamsQ1 NSOURCES Total number of original sourcesR0 PARENT Number of rays from which this raywas split (parent)S0 SHAPE Beam shape number (see SHAPEScommand)S1 FACTOR Beam shape factor or number ofhigher modesT0 PHASE_0 Relative phase angles offundamental beam modeT1,T2 PHASE_1,2 Relative phase angles ofpolarization componentsU0,V0 U,VPARAMB Parametric coordinates of base raypositionW0 WAVELEN Wavelength of ray/beamWi WAVLNS_i Wavelength for ith sourceX0,Y0,Z0 X,Y,Z_POS_B Global X,Y,Z coordinates of baserayXi,Yi,Zi X,Y,Z_POS_i Relative coordinates of ith parabasalray4. In Stokes vector mode, the values of the P1, P2, P3, and P4 registers are S0, S1, S2, and S3 of the Stokes vector ofthe ray. The value of T1 register is the Degree of Polarization (DoP) of the ray.5. Some of the variables defined with the GET command relate to the polarization state of a coherent ray:

<strong>ASAP</strong> | Commands and Macros (G) | 142• If U describes the complex scalar wave function of the beam, the addition of a coherent polarization statecauses the description to be:• When the beam is first created,are determined by the parameter of the current POLARIZ command. During the refraction operation, as the raypropagates, the quantities, are re-computed so that is the local s-polarization direction, andare determined by the s and p Fresnel equations.GET Examples$GO (<strong>ASAP</strong> Macro)Branches to other records or skips over input records.Syntax$GO m+m-m$GO label:label:Remarks1. Use this macro to branch or skip records unconditionally.2. If m is unsigned, the next record to be run is macro record m.3. If m is signed, the next record plus or minus m is run.4. If the target record goes beyond the end of the macro definition, the macro that is run is terminated after thecurrent record is processed.5. If a label is entered, <strong>ASAP</strong> skips over input records until it finds a record with the label starting in column 1.Normal input processing begins on the next record. You must first rewind the file to branch back to a previouslabel in the input file.6. The label may be in opposite case letters from the current $CASE input mode (default is $CASE UPPER). Thisway the label is ignored if the $GO is commented out or skipped by using a $IF structure. If using lower case forthe label, be sure not to include an underscore "_" character in the name, since this is treated as upper case andgenerates a parsing error.$GO Examples

<strong>ASAP</strong> | Commands and Macros (G) | 143$GRAB (<strong>ASAP</strong> Macro)Grabs isolated numbers or literals from the output buffer.Syntax$GRAB 'string' [ i j ] [ reg [ reg '...]]$GRABRemarks1. $GRAB (numbers) or &GRAB (literals) (blank delimited strings) searches backwards through the output buffer forthe given string (delimited like a comment.) It then displays or assigns to the given register the jth number or wordafter the string, or the jth number or word of the ith relative record.2. Successive numbers (or words) may also be assigned to additional registers.3. A nonfatal warning is issued, and the variable is set to zero if a number is not found.4. The default values are: i=0 (found record) and j=1 (next number or word).5. If you want to specify j explicitly, also enter i.6. Literals must be stored in one of the 286 direct registers designated by the letters A through Z by themselves orfollowed by the numbers 0 through 9.7. Buffer size is 10,000 lines of output.$GRAB ExamplesGRAPH (<strong>ASAP</strong> Command)Creates 1D profile(s) of the current distribution data file.Function• Display/Modify Data DistributionsSyntaxGRAPH [ i [ i'...]] [ APPEND ] [ AXIS [ x [ x' ]]] [ AUTO ] [ w ] 'title' ][ DISCRETE ]fMINMAX[ ' comment … ]:Optioni i' …DescriptionPlot ith line of distribution dataf Plot line that is the floating point fraction f (between 0and 1) of the total number of lines in the distribution dataMAXMINAPPENDPlot line that contains MAXimum distribution value(default)Plot line that contains MINimum distribution valueOption to append current GRAPH to last GRAPH

<strong>ASAP</strong> | Commands and Macros (G) | 144OptionAXISx x'AUTODISCRETE'title''comment'DescriptionOverwrite abscissa valuesFactors for overwriting abscissa valuesTake the vertical function limits from the specified linedataDraws vertical lines (default w=0) or bars (0

<strong>ASAP</strong> | Commands and Macros (G) | 145OptionfileunRANDOM rDescriptionName of the distribution file (default .DIS extension)Logical unit number (default 9) of distribution data file(default .DAT extension)Specifies the creation of rays at every nth locationRandomization factorRemarks1. Creates a rectangular grid of rays based on the coordinates found in the header of the distribution file (defaultfile.dis or BRO009.DAT).2. A ray is created at each sample location in the file (or optionally every nth location).3. Each ray's flux is proportional to the corresponding data value in the file.4. Each ray position on the grid can be uniformly RANDOMized within a region r times the local grid spacing.5. In addition to the usual CLIP POSITION, the current flux CUTOFF and HALT settings may also truncate thedistribution.6. If the labels in the file do not contain coordinates, the data is mapped to the current plotting WINDOW at the zerodepth plane.7. Used in conjunction with the SOURCE command, GRID DATA creates ray data that can be traced in <strong>ASAP</strong>.8. When in doubt about the exact distribution that is created by GRID DATA, use the SPOTS POSITION commandto display the grid.9. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns when this occurs.Modifications do not permanently change the POLARIZ settings.GRID ExamplesGRID ELLIPTIC (<strong>ASAP</strong> Command)Generates a rectangular grid of rays inside an elliptical aperture.Function• Create Rays/BeamsSyntaxGRID ELLIPTIC X x y y' z z' n n' [ c ] [ RANDOM f ]Y y z z' x x'Z z x x' y y'OptionDescriptionX, Y, or Z Coordinate axisx, y, or z Location of plane on the coordinate axisy y', z z', or x x'z z', x x', or y y'n n'cRANDOM fMinimum and maximum extent of the plane in the givendirectionNumber of rays in each direction on the planeFraction height of a central hole in the gridrandomization factor

<strong>ASAP</strong> | Commands and Macros (G) | 146Remarks1. Generates a uniform rectangular grid of rays on the given plane, which is then clipped by an inscribed ellipticalaperture.2. The flux of each ray is adjusted to give unit irradiance (flux/area) to the entire GRID.3. Rays are equally spaced in the two directions only if the extents and the number of rays in each direction areidentical.4. The values for n and n' set the number of rays of the full rectangular grid. The number of rays contained in theinscribed elliptical aperture is usually less than the number in a full rectangular grid.5. The optional c entry specifies a fractional height for a central hole in the grid.6. Each position on the grid can be uniformly RANDOMized within a region f times the local grid spacing.7. Used in conjunction with the SOURCE command, GRID ELLIPTIC creates ray data that can be traced in <strong>ASAP</strong>.8. When in doubt about the exact distribution that is created by GRID ELLIPTIC, use the SPOTS POSITIONcommand to display the grid.9. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns when this occurs.Modifications do not permanently change the POLARIZ settings.GRID ExamplesGRID HEX (<strong>ASAP</strong> Command)Generates a hexagonal grid of rays.Function• Create Rays and BeamsSyntaxGRID HEX X x y z h n [ RANDOM f ]Y y z xZ z x yOptionDescriptionX, Y, or Z Coordinate axisx, y, or z Location of plane on the coordinate axisy z, z x, or x yhnRANDOM fRemarksOffset of gridHeight of hexagonNumber of rays along each edge of hexagonRandomization factor1. Creates a hexagonal grid of rays normal to the given direction and centered at the given coordinates.2. The h is the height of the hexagon as measured from the center to one of its vertices.3. The n is the number of rays along one side of the hexagon.4. Each ray position on the grid can be uniformly RANDOMized within a region f times the local grid spacing.5. Used in conjunction with the SOURCE command, GRID HEX creates ray data that can be traced in <strong>ASAP</strong>.6. When in doubt about the exact distribution that is created by GRID HEX, use the SPOTS POSITION commandto display the grid.

<strong>ASAP</strong> | Commands and Macros (G) | 1477. The height parameter is, in absolute value, the radius of a bounding circle for the grid. This circle becomes aminimum one only when the limit of the number of rays n along each edge of the hexagon is large; for example,10 or more.Note: Equivalent statements regarding height parameter include the following: The height parameteris, in absolute value, the bounding value of the semi-distance between opposing vertices of the hexagon.Also, the height parameter is, in absolute value, the bounding value of the length of an edge of thehexagon. If n is not large, the actual size of the hexagon is slightly less than these bounding values.8. If you are concerned about the absolute flux of any source, or about the ratio of fluxes of multiple sources, BROrecommends using the FLUX TOTAL command on each such source.9. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns when this occurs.Modifications do not permanently change the POLARIZ settings.Note: For advanced users: The hexagonal grid is described by constant inter-ray spacings in each of twoorthogonal directions; for example X and Y. Since each edge of the hexagon comprises n points, the spacingsin X and Y are necessarily different. Therefore, the density of grid points is anisotropic in the X and Ydirections. The rotational symmetry of the array is therefore two-fold. The asymmetry between X and Y canbe reversed by specifying the number of points along an edge n as a negative integer. This feature is unlikelyto be of interest for n of order 10 or larger, but is available.GRID ExamplesGRID OBJECT (<strong>ASAP</strong> Command)Generates a uniform grid of rays on an object.Function• Create Rays and BeamsSyntaxGRID OBJECT k [ n [ +-X ] ] [ RANDOM f ]YZOptionkn+X, -X, +Y, -Y, +Z, or -ZRANDOM fDescriptionObject number or nameNumber of raysSpecifies limit box endRandomization factorRemarks1. Generates a uniform grid of rays based on the location and dimensions of the given object k.2. If the limits box axis is not specified, the ray positions lie at the centers of the object's facets. To control thenumber of facets on the EDGE/OBJECT, use the object modifier FACETS.3. If the limits box axis is specified, approximately n rays are distributed over the specified LIMITS box endspecified by the axis entry. The rays lie at the centers of the object's facets projected on the LIMITS box end.4. Rays created with GRID OBJECT should be MOVEd off of the OBJECT to prevent intersection problems withthat OBJECT.5. Each ray position on the grid can be uniformly RANDOMized within a region f times the local grid spacing.6. Used in conjunction with the SOURCE command, GRID OBJECT creates ray data that can be traced in <strong>ASAP</strong>.

<strong>ASAP</strong> | Commands and Macros (G) | 1487. When in doubt about the exact distribution that is created by GRID OBJECT, use the SPOTS POSITIONcommand to display the grid.8. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns when this occurs.Modifications do not permanently change the POLARIZ settings.GRID ExamplesGRID POLAR (<strong>ASAP</strong> Command)Generates a circular grid of rays.Function• Create Rays and BeamsSyntax 1GRID POLAR X x r r' a a' n n' [ w ] [ RANDOM f ]Y yZ zSyntax 2GRID POLAR X x r' n [ RANDOM f ]Y yZ zOptionDescriptionX, Y, or Z Coordinate axisx, y, or z Location of plane on the coordinate axisr r'a a'nn'wRANDOM fRemarksMinimum and maximum extent in the radial directionMinimum and maximum extent in the angular directionNumber of rays in the radial directionNumber of rays in the first nonzero radial ringWeighting factorRandomization factor1. Generates a circular grid of rays centered on the coordinate axis when w is not unity.2. The angular arguments a and a' are entered in degrees.3. The sign of n determines how the range entries are to be used:+n divide r to r' into n rings-n divide 0 to r' into n rings, eliminate rings inside r+n'-n'divide a to a' into n sectors (first ring)divide 0 to 360 into n sectors, eliminate sectors outsidea to a'

<strong>ASAP</strong> | Commands and Macros (G) | 1494. For r=0 or n

<strong>ASAP</strong> | Commands and Macros (G) | 1501. Generates a uniform rectangular grid of rays.2. The flux of each ray is adjusted to give unit irradiance (flux/area) to the entire GRID.3. Rays are equally spaced in the two directions only if the extents and the number of rays in each direction areidentical.4. The optional c entry specifies a fractional height for a central rectangular hole in the grid.5. Each ray position on the grid can be uniformly RANDOMized within a region f times the local grid spacing.6. Used in conjunction with the SOURCE command, GRID RECT creates ray data that can be traced in <strong>ASAP</strong>.7. When in doubt about the exact distribution that is created by GRID RECT, use the SPOTS POSITION commandto display the grid.8. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns when this occurs.Modifications do not permanently change the POLARIZ settings.GRID ExamplesGRID WINDOW (<strong>ASAP</strong> Command)Creates a rectangular raster-type ray grid.Function• Create Rays and BeamsSyntaxGRID WINDOW [ f [ m n [ RANDOM r ] ] ]MINMAXCENOBLOptionfmnMINMAXCENOBLRANDOM rDescriptionSpecifies the grid depth plane (default f=0)Sampling vertical raysSampling horizontal raysGrid depth plane is given by the MINimum valueGrid depth plane is given by the MAXimum valueGrid depth plane is given by the CENter valueGrid depth plane is given by the last OBLique valueRandomization factorRemarks1. Creates a rectangular raster-type ray grid, using the current WINDOW dimensions and sampling m rays vertical by nhorizontal (or current PIXEL settings).2. The grid depth plane is given by f (default 0), the MINimum, MAXimum, CENter, or last OBLique value.3. Each ray position on the grid can be uniformly RANDOMized within a region r times the local grid spacing.4. Used in conjunction with the SOURCE command, GRID WINDOW creates ray data that can be traced in <strong>ASAP</strong>.5. When in doubt about the exact distribution that is created by GRID WINDOW, use the SPOTS POSITIONcommand to display the grid.

<strong>ASAP</strong> | Commands and Macros (G) | 1516. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns when this occurs.Modifications do not permanently change the POLARIZ settings.GRID ExamplesGRIN (<strong>ASAP</strong> Command Argument)Similar to the command argument, ABSORB, GRIN handles the gradient index (GRIN) materials by assigning to themedium a GENERAL polynomial or USERFUNC function.Syntax... [ GRIN k p t [ l ] ]OptionkptlDescriptionIts magnitude is the SURFACE designation for thisfunctionValue of polynomial function that can be raised to apowerStep length used for tracing a ray when tracing a ray inthis inhomogeneous mediumMaximum number of steps a ray can take in the medium(default 1000)Remarks1. The refractive index squared at each point in the medium is given by:where w is the wavelength.2. If the constant coefficient of the function f is unity (1), the refractive indices entered after the MEDIA commandcorresponds to those at the function’s reference point.GRIN ExamplesGROUP (<strong>ASAP</strong> Command)Groups a collection of objects or sources as a single unit.Function• Create/Modify ObjectsSyntaxGROUP [ i [ i' ... ] ] [ SOURCES j [ j' ... ] ]-n -n0

<strong>ASAP</strong> | Commands and Macros (G) | 152Optioni i' ...DescriptionObject numbers or names-n Specifies last n objectsSOURCESj j' ...SOURCES -nSpecifies grouping sourcesSource numbersSpecifies last n sources0 Specifies last groupRemarks1. Temporarily declares the objects/sources whose number (or object names possibly with '?' wildcards) are enteredon it, the last n objects/sources, the last group (0), or all objects (no entries) as belonging to the same "group". Thissingle unit can be modified using the SHIFT or ROTATE command.2. The SOURCES option can be abbreviated only to SOURCE to avoid confusion with an object name.3. Any linear transformation commands that immediately follow this command are applied to every object andsource in the group.4. A few specific examples include:GROUP !all objectsGROUP ? !all objectsGROUP -1000 !all objectsGROUP .? !objects in same branch as last object5. If GROUP is used without any additional arguments, all previously defined objects are grouped.6. If -n is entered, only last n objects/sources are grouped.7. If 0 is entered, the last group is grouped again.8. A RETURN command always terminates the active group. Use GROUP 0, if necessary, to re-activate.9. If i, i', ... are entered, only these objects are grouped.10. If j, j', ... are entered, only these sources are grouped.11. The reference point of the group is defaulted to that of the first object/source.GROUP Examples$GUI (<strong>ASAP</strong> Macro)Sends the given command strings to the graphical user interface (GUI).Syntax$GUI command [ command' ... ]&GUICommandExplorer_OffExplorer_OnRemoteStart ComputerName [workdir]DescriptionTurns off the Explorer pane.Turns on the Explorer pane.Starts a remote kernel session on the named computer.

<strong>ASAP</strong> | Commands and Macros (G) | 153CommandRemoteEnd ComputerNameRemoteCommand ComputerNameRemoteSendFile ComputerName FilenameRemoteGetFile ComputerName FilenameRemoteBusy ComputerName regnameRemoteSetPriority ComputerName priorityRemoteSetCPU ComputerName cpuRemoteProps ComputerName, RemotePropsComputerName -dRemoteOpenFile ComputerName Filename,RemoteOpenFile FilenameDisplayRange fMin fMaxPlot LinkPlot OffPlot OnEcho OffEcho OnClearConsoleClearWarningsClearAllCalculateCIEDescriptionEnds a previously started kernel session on the namedcomputer.Issues an <strong>ASAP</strong> command to the remote computer.Sends the file(s) from the local computer to the namedremote computer.Transfers the file corresponding to Filename, inthe working directory of the remote machine, to thesubdirectory named ComputerName, within theworking directory of the local computer.Tests whether the kernel session on the named remotecomputer is busy executing a command or if it is idle,waiting for input.Changes the process priority for the kernel session on thenamed computer while it is busy executing commands.The priority is set to Low, Normal, High, or Realtime.Sets the ideal cpu on which the kernel runs on theremote computer.Gets information from the remote machine (seeRemarks). The extension –d displays information in theProperties dialog.Transfers, if necessary, the requested Filename tothe local machine, and then opens it in the applicabledocument window.Changes the minimum (fMin) and maximum (fMax)range for the last opened Display Viewer window.Forces all plot windows that are created by the kernel tobecome links that can be clicked in the Command Outputwindow.Disables all dynamic plot creation by the kernel.Restores the dynamic plot creation ability of the kernel.Turns off the echoing of information from the kernel tothe GUI.Restores the echoing of information from the kernel tothe GUI.Clears the text from the Command Output window.Sets to zero the Warnings counter on the <strong>ASAP</strong> statusbar.Performs both the ClearConsole and ClearCounteroptions.Performs color analyses to quantify the chromaticityand lightness of photometric values using CIE standardobserver models and CIELAB 1976 color appearancemodels. This is intended to test the uniformity of

<strong>ASAP</strong> | Commands and Macros (G) | 154CommandCharts_OffCharts_OnDescriptionthe projected light on an analysis object, using CIEstandards.Turns off the Chart Viewer, so that the Plot Viewerdisplays plots.Turns on the Chart Viewer, so that plots are displayed inthis viewer and not the Plot Viewer.Remarks1. $GUI sends the string exactly as entered.2. &GUI parses any expressions and replaces their results with string equivalents.3. Three forms of ComputerName (or pcname) can be used with $GUI Remote commands:a. pcnameb. DNS-resolvable name; for example, pcname.domain.comc. fully qualified IP address; for example, 125.0.156.120Note: The reserved character $ cannot be part of pcname.Note: Do not to use backslashes (\\) before the computer name.Note: pcname can also be written as pcname:n where n is an integer between zero and n-1 thatrepresents the number of cores on computer.4. Examples using $GUI RemoteStart:$GUI RemoteStart tut1$GUI RemoteStart tut1.breault.com$GUI RemoteStart 125.0.156.120$GUI RemoteStart tut1:0Note: $GUI RemoteStart tut1:0 starts an <strong>ASAP</strong> REMOTE session on CPU 0 of the remotePC named "tut1". If the command is given again using tut1:1, a second session starts on CPU 1.If additional CPUs (cores) are available on the remote PC, they can be accessed in sequential orderby changing the specified CPU number. If you start multiple sessions on a single core, you can alsofollow this same syntax; that is, for a single core computer, $GUI RemoteStart pcname:0 (andpcname:1) start two (2) sessions on the available core.5. $GUI Explorer_On: In the On mode, you can view files in the current working directory. The On mode iscurrently the default if it is used with <strong>ASAP</strong> REMOTE.6. $GUI RemoteStart: The computer name is added to either the drop-down list on the <strong>ASAP</strong> REMOTE toolbar(if in toolbar mode), or to a tab on the Command Input window (if in tabular mode). If this computer name isselected, all commands typed in the Command Input window are directed to its kernel. The following exampleshows how to create a Working Directory for the <strong>ASAP</strong> REMOTE session.$GUI RemoteStart tut1 "C:\Users\Public\foo"Note: When no path is given, the default working directory on Windows 7 is under C:\Users\Public\Documents\<strong>ASAP</strong>Remote\username_pcname_0.bro\. The default workingdirectory on Windows XP is Documents and Settings\All Users\Application Data.If a second session is opened this way on the same computer, <strong>ASAP</strong> issues the message, "A remote kernel onthe requested core is already running". Therefore, a second session must be specified with pcname:1 or higher.BRO recommends that you provide the Remote working path when possible. Once the working directory is set

<strong>ASAP</strong> | Commands and Macros (G) | 155for a remote session, it cannot be changed during the session. This restriction limits potential conflict with otherremote kernels running on one machine. You must specify a different Working Directory to use for each <strong>ASAP</strong>REMOTE session that is started on the same computer. For example:$GUI RemoteStart pcname:0 "C:\Users\Public\REMOTE_SESSION1\"$GUI RemoteStart pcname:1 "C:\Users\Public\REMOTE_SESSION2\"7. $GUI RemoteEnd pcname: The remote computer name is deleted and some final status from the kernel isposted to the Command Input window of the local computer. In the following example, the remote kernel is endedon the computer named “tut1”: $GUI RemoteEnd tut1.8. $GUI RemoteCommand pcname <strong>ASAP</strong>Command: Commands are placed in a queue on the remote session.In the following example, the remote <strong>ASAP</strong> seed is set to a value that is different from the default value with theSEED command, using the QUASI option:$GUI RemoteCommand tut1 SEED 987654321 QUASI9. $GUI RemoteSendFile pcname Filename: If this command is used from a remote computer and aperiod is used in place of a computer name, the file(s) are transferred from the remote computer to the localcomputer. Transfer of files from one remote session to another remote session is not possible. Full wildcard use issupported, although it cannot recursively act upon subdirectories. Files sent from a remote computer to the localcomputer are placed in a subdirectory with the same name as the remote computer (see Note in Remark 10). Forexample:$GUI RemoteSendFile tut1 “*.lib”$GUI RemoteSendFile . “*.dis”10. $GUI RemoteGetFile: Allows remote files to be retrieved and placed in the associated folders on the localcomputer. For example:$GUI RemoteGetFile pcname:0 FILENAME.DISNote: Absolute paths for FILENAME are not permitted. Files are transferred to sub-folders in theWorking Directory of your local machine and named after the computer name of the remote. For multiplesessions on multiple cores per computer, the computer name is appended by an underscore and numberto designate the CPU or session. For example, for a session that was labeled pcname:0, a sub-foldercontaining the retrieved files is named pcname_0.11. $GUI RemoteBusy pcname regname: The result, 1 or 0, is placed in the register, regname. The regnameregister must be previously declared.12. $GUI RemoteSetPriority pcname priority: A priority setting of Low ensures that the kerneluses CPU cycles only when other processes are idle. A priority of Normal puts the kernel session on the samelevel as all other processes. A priority of High causes the kernel session to have a slightly higher average amountof CPU time as compared to all other processes. A priority of Realtime causes the kernel session to become themost important task for the operating system. All other processes get only idle time processing, which due to thenature of the kernel, is almost never. Setting the priority to Low is the most typical use, so that a remote computeris not burdened with extensive CPU cycles, which a kernel session may require if running in a priority of Normalmode. Normal Windows usage can therefore be expected by the typical user. For example:$GUI RemoteSetPriority tut1 Low13. $GUI RemoteSetCPU pcname cpu: This setting does not guarantee that the process runs only on theselected CPU; it specifies the preferred CPU whose numbering starts with zero. For example:

<strong>ASAP</strong> | Commands and Macros (G) | 156$GUI RemoteSetCPU pcname:0 1Note: The colon method in pcname: must always be used, even with only one started <strong>ASAP</strong> REMOTEsession. The number after the colon represents the particular <strong>ASAP</strong> REMOTE session you want to select,starting with :0, :1 for second, and so on. The last number designates the CPU to which you want toassign that <strong>ASAP</strong> REMOTE session, if available on that computer.14. $GUI RemoteProps pcname -d: Gets number of remote kernel processes currently occurring, number of<strong>ASAP</strong> processes currently occurring, and available disk space; pcname is the name of the remote machine. If youselect the –d option, the information is displayed in the Properties dialog.15. $GUI RemoteOpenFile pcname Filename. For example:$GUI RemoteOpenFile pcname “somefile.dis”This string causes the “somefile.dis” file on the remote pcname to be transferred to a temporary file on the localmachine, and then opened in the Display Viewer.$GUI RemoteOpenFile . “somefile.dis”This string causes the file, “somefile.dis” to be opened on the local machine.16. $GUI DisplayRange fMin fMax: No error checking is done to ensure that the minimum is less than themaximum. For example:$GUI DisplayRange -5.25 10.2517. $GUI CalculateCIE: Tests the uniformity of the projected light on an analysis object, using CIE standards.$GUI ExamplesRemote ExamplesGUM (<strong>ASAP</strong> Command)Define a general uniaxial birefringent media device.Function• Create/Modify ObjectsSyntax 1GUM [thickness no ne REFL Rs Rp 'name']Syntax 2GUM [thickness Crystal_Medium_index REFL Rs Rp 'name']OptionThicknessDescriptionThickness of the GUM device, which must be specified inum. Default value is 100 um.

<strong>ASAP</strong> | Commands and Macros (G) | 157OptionnoneREFLRsRp'name'DescriptionOrdinary refractive index of the uniaxial crystal. Defaultis 1.543. See Remarks.Extraordinary refractive index of the uniaxial crystal.Default is 1.552. See Remarks.Controls reflection calculation. See Remarks.Power reflectance for the s polarization state (spolarization).Default is 0 (no reflection).Power reflectance for the p polarization state (ppolarization).Default is 0 (no reflection).Name of the GUM device. Default name format isGUM0001, GUM0002, and so on.Remarks1. The general uniaxial media model is a simplified field propagation model for uniaxial media, alternative tooriginal rigorous ray tracing algorithm in <strong>ASAP</strong> for the uniaxial media. This GUM model accurately models bothon and off axis propagation of polarized light inside the crystal with extended Jones matrix method under smallbirefringence approximation (that is, .2. Multiple reflections inside of the crystal are ignored. Fresnel transmission loss at the uniaxial input and outputinterface can be automatically calculated if enabled.3. The default material of the uniaxial media is assumed to be quartz, which is a positive uniaxial material (ne > no).4. GUM is assumed to be a parallel plate before it is attached to <strong>ASAP</strong> object. In addition, the polarization axis ofGUM is referred to the direction of the optical axis of the uniaxial crystal. When created, the optical axis is alwaysassumed to be the local x-axis of any object with an INTERFACE POLARIZATION. The optical axis can berotated to any arbitrary direction with INTERFACE POLARIZATION theta and azimuthal angles.Note: The theta angle controls the angle between the optical axis and the local surface tangential plane ofthe attached <strong>ASAP</strong> object, as determined by the conformal wrapping process.5. All arguments are optional. If you do not supply the value of an argument, its default value is used.6. For no, you can alternatively specify the name or index of a previously defined crystal media, as in Syntax 2.<strong>ASAP</strong> interprets types of this input differently for integer and real numbers. For real numbers, <strong>ASAP</strong> assumes thatit stands for the refractive index, while for an integer, <strong>ASAP</strong> assumes that it stands for the index of a previouslydefined crystal media.7. ne is used to specify directly the extraordinary index of the crystal.Note: ne is not used if the device crystal is specified by a previously defined crystal media.8. If REFL is presented without Rs and Rp specified, the reflection is calculated with the Fresnel formula. If REFLis presented with Rs and Rp, the reflectance is Rs for s-polarized and Rp for p-polarized light, regardless of theincident angle of the ray. If not presented, the reflection is ignored.9. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER3 Realistic polarizer POLARIZER RPM

<strong>ASAP</strong> | Commands and Macros (G) | 158Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC8 Cascaded polarizationelementGUM ExamplesCPECPE

<strong>ASAP</strong> | Commands and Macros (H) | 159Commands and Macros (H)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “H”.HALT (<strong>ASAP</strong> Command)Sets conditions to stop (that is, quit) tracing each ray.Function• Create/Modify Objects• Setup TraceSyntaxHALT[ n ] [ OFF ] [ c ]-X-Y-ZXYZ-+OptionncOFF+X,-X, +Y,-Y, or +Z,-ZDescriptionMaximum number of times a ray can consecutivelyintersect the same non-LENS object; must be an integer;default is 12Current flux/initial flux threshold ratio in fractional form(see Remark below)Turns off the global coordinate or surface normaldirection; this is default stateUndesirable propagation direction (literal entries)Remarks1. If you run this command without any options, the defaults are restored.2. HALT forces the tracing of certain rays to be halted; that is, stopped, based on selected options. A ray that isHALTed (stopped) still exists and appropriately appears in the STATS output. Tracing of HALTed rays can beresumed.3. HALT is used either as a local command to override defaults for the current object, or as a global command. In thelatter case, the command acts as an interface control, and becomes the default on any object for which HALT isnot explicitly set. Issue a RETURN command to apply HALT globally, since the global command is identical to theOBJECT subcommand; otherwise, HALT is applied locally to the last created object.4. The n is the maximum number of times a ray can consecutively intersect the same object, and n must be entered asan integer. The default value of n is 12.5. The signed coordinate option specifies a certain global coordinate direction (global HALT) or surface normaldirection (local HALT). If the direction vector of a ray attains a component in this direction after reflection or

<strong>ASAP</strong> | Commands and Macros (H) | 160refraction, tracing halts for that particular ray. The OFF option returns it to the default condition, where allpropagation directions are allowed.6. The default for c is 1.E-6 (that is, a ray is stopped when the ratio of current flux to initial flux drops below 1.E-6).7. The c option must be entered as a fraction in decimal format.HALT ExamplesHARVEY (<strong>ASAP</strong> Command)Creates a Harvey (linear shift invariant) scatter model or simple specific model.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax 1 - Isotropic modelHARVEY b s [ l [ m [ n [ w ] ] ] ] [ PLOT [ a a' ... ] ]Syntax 2 - Anisotropic modelHARVEY X b s l l' [ w ]YZ:Optionbsl and l'DescriptionBSDF at 0.01 radians (0.573 degrees) from specular; if lis used, b 0 is the maximum BSDF (at specular).Asymptotic fall-off with angle (typically between -1 to-2.5)A-A 0 and B-B 0 shoulder point in radians (see Remarks)m, n 2 additional invariance parameters postulated for roughsurfaceswPLOTa a' ...Remarks1. The out-of-field analog to the SCATTER BSDF command.2. Use with importance area sampling.3. If l is used,Wavelength (in current or eventual wavelength units)Plots the model in log(b-b 0 ) and angle spaceUser-defined degree specular anglesSimple, specific (isotropic) models:

<strong>ASAP</strong> | Commands and Macros (H) | 1611. If the optional b-b 0 shoulder point l (in radians) is given, b is the maximum BSDF (at specular). These parametersdescribe a shift-invariant generalized Lorentzian function of B-B 0 that normally fits the scatter from smoothsurfaces (RMS as well as wavelength) extremely well.2. The m and n are two additional invariance parameters postulated for rough surfaces; that is, if:where B, C are the sine, cosine of the scatter angle from normal and B 0 , C 0 are the sine, cosine of the specularangle. For typical rough surfaces, m is approximately 2 and n around 1.3. The w is the wavelength (in current or eventual wavelength units), at which this model is defined (or wasmeasured).Elliptical (Anisotropic) Harvey model:1. Scattering from anisotropic surfaces is not rotationally symmetrical at normal incidence, and not necessarilysymmetrical about the plane of incidence otherwise. Therefore, the orientation of the model on the surface isimportant, and is generally specified by an axis for the second command entry. For syntax information, see thecommand argument, MODEL.2. The b is the maximum BSDF (at specular), s is the asymptotic fall-off with angle (typically between -1 to -2.5).The l and l' are the A-A 0 and B-B 0 shoulder points in radians. More precisely,where A, B are the scatter direction cosines and A 0 , B 0 are the specular.Both models1. The w is the wavelength (in current or eventual wavelength units) at which this model is defined (or wasmeasured). The default is the current value from the last WAVELENGTH(S) command. If it is greater thanzero, any ray whose wavelength is different automatically has its scatter scaled according to the smooth surfaceapproximation.2. Command argument, PLOT plots the model (common base 10 logarithm of the BSDF) for up to seven specularangles in ascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls theresolution of these plots in direction cosine space. Also, creates a distribution file name_angle.dis for each of theseangles.3. The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.HARVEY ExamplesHEADER (<strong>ASAP</strong> Command)Redefines the file header for the current data in the display file.Function

<strong>ASAP</strong> | Commands and Macros (H) | 162• Display/Modify Data DistributionsSyntaxHEADER zlabel z flabel ylabel y y' xlabel x x' 'title'Remarks1. Any entries that are not included at the end of the command syntax or any literals that are replaced by anunderscore "_" do not alter that part of the header. For example, to change only the horizontal label and range,enter:HEADER _ _ _, "New Label" -12 122. There must be a space between each underscore "_".HEADER ExamplesHELIX (<strong>ASAP</strong> Command)Creates a general helical curve.Function• Define/Modify Curvedge EntitiesSyntaxHELIX X x y z x' y' z' t [ n ]Y y z x y' z' x'Z z x y z' x' y'OptionDescriptionX, Y or Z Coordinate axisx, y, or z Axial location of the starting planex', y', or z'y z, z x, or x yy' z', z' x', or x' y'tnRemarksAxial location of the ending planeElliptical semi-heights at the starting planeElliptical semi-heights at the ending planeNumber of turns (not necessarily integer)Number of linear segments1. If the axial locations of the starting and ending planes are the same, the helix becomes a planar spiral.2. The helix consists of t turns (not necessarily integer and defaulted to 1).3. By default, the helix is perfectly smooth. Optionally, it can consist of n linear segments.4. This edge is a combination of straight line or higher-order curved segments.HELIX Examples

<strong>ASAP</strong> | Commands and Macros (H) | 1645. Refer to example script RANDOM_NUMBER04.INR, "Automated Random Number Distributions" in <strong>ASAP</strong>.HISTOGRAM ExamplesHISTORY (<strong>ASAP</strong> Command)Recalls ray data from a previously saved binary file for plotting or listing. The second syntax is for the Path Explorer.Function• Analyze Ray/Beam DataSyntax 1HISTORY [ k ] [ PLOT [ m ] ]SPOTS [ m ] ]LIST [ m ] ]Syntax 2 - Path ExplorerHISTORY [ k ] PX• Elementary Tests...NONE [ setname ]...ALL [ setname ]...STARTS object [ setname ]...ENDS object [ setname ]...SCATTER object [ setname ]...DIVIDE object [ setname ]...ESCAPES [ setname ]...INTERSECTS volume [ comp_type comp_val ] [ setname ]object [ comp_type comp_val ] [ setname ]...SPLITS comp_type comp_val [ setname ]...LEVELS comp_type comp_val [ setname ]...GENERATION comp_type comp_val [ setname ]...HITS comp_type comp_val [ setname ]...FLUX [ object ] comp_type comp_val...ANGLE [ object ] comp_type comp_val• Modifier for Elementary Tests...GLOBAL...• Logical Tests...AND set1 set2...OR set1 set2...NOT set1setnamesetnamesetname• Analysis Functions

<strong>ASAP</strong> | Commands and Macros (H) | 165...LIST [ setname ] [ m ]...PLOT [ setname ] [ m ]...SPOTS [ setname ] [ m ]...WINDOW......REFRESH...SUMMARY [ setname ]• Session Management...STORE setname...RECALL [ setname ]...RETURNOptionkLISTPLOTSPOTSmWINDOWREFRESHSUMMARYGLOBALNONEALLSTARTSENDSSCATTERDIVIDEESCAPESINTERSECTSDescriptionSAVE file number from the last TRACE commandLIST the trajectories in the selected path-setPLOT paths graphically for the selected path-setDisplay a spots diagram for the selected path-setStride (default 1) with which to choose paths output byPLOT, SPOTS or LIST; that is, every mth ray.Set window parameters for plotting paths; see mainWINDOW commandRefresh the 3D graphics file for plotting pathsReport statistics on the selected path-setModifier that can appear only at the end of anyElementary Test and specifies that the test applies to theentire ray history file (not the ACTIVE path-set)Creates a path-set containing no paths and makes this theactive setCreates a path-set containing all paths and makes this theactive setCreates a path-set containing all paths in the active setstarting on a specified objectCreates a path-set containing all paths in the active setending on a specified objectCreates a path-set containing all paths in the active setscattering from the specified objectCreates a path-set containing all paths in the active setsplitting from the specified objectCreates a path-set containing all paths in the active setthat escaped; that is, missed rays.Creates a path-set containing all paths in the active set,including a specified number of, or upper bound or lowerbound on, the number of intersections with a specified

<strong>ASAP</strong> | Commands and Macros (H) | 166OptionSPLITSLEVELSGENERATIONHITSDescriptionobject or volume. An intersection with a volume isdefined as a traversal of any boundary of the specifiedslab, tube, or box.Creates a path-set containing all paths in the active setincluding a specified number of, or upper bound or lowerbound on, split eventsCreates a path-set containing all paths in the active setincluding a specified number of, or upper bound or lowerbound on, scatter eventsCreates a path-set containing all paths in the active setincluding a specified number of, or upper bound or lowerbound on, the sum of split and scattering eventsCreates a path-set containing all paths in the active setincluding a specified number of, or upper bound or lowerbound on, hits; that is, intersection eventscomp_type Comparison type EQ – equal to…LT – less than…LE –less than or equal to…GT – greater than…GE – greaterthan or equal to…comp_valANDORNOTSTORERECALLRETURNobjectvolumesetnameset1, set2FLUXANGLEInteger value for comparisonChooses paths that are present in both set1 and set2(intersection)Chooses paths that are present in either set1 or set2(union)Chooses rays not in set1 (exclusion)Stores the active path-set as setnameResets the active set to the set of all paths or, optionally,a named path-setCloses the Path Explorer sessionSpecifies an existing object by name or numberSpecifies a volume as an infinite rectangular slab(ASLAB), an infinite rectangular tube (ATUBE), or afinite box (ABOX) as described in the Remarks below.A name to assign to the resulting path-set; defaults toactive set when optional and not specifiedSpecifies an existing path-set by name or numberCreates a path-set containing all paths for which the fluxincident on 'object' satisfies the comparison. If 'object' isomitted, the comparison is applied to the terminal flux,which is either the flux on the object on which a pathends or, in the case of a missed ray, the flux escaping thesystem.Creates a path-set containing all paths intersecting'object' at an angle satisfying the comparison, which

<strong>ASAP</strong> | Commands and Macros (H) | 167OptionDescriptionis expressed in degrees. If 'object' is omitted, thecomparison is applied to all objects.Remarks1. Elementary Tests, FLUX and ANGLE, are available only as a script command, not in the Query Builder userinterface.2. If a SAVE file number k exists from the last TRACE, the HISTORY command can be used to LIST or PLOT thereverse trajectories of the current ray set. Use the SPOTS option only to plot where the rays struck the objects.3. Volumes are specified as rectangular axis-aligned structures in the global coordinate system.4. A volume bounded in one dimension may be specified by ASLAB as follows:ASLAB axis c_min c_maxwhere axis is one of X, Y or Zc_min and c_max are the coordinates of the intersections of axis with the slab faces5. A volume bounded in two dimensions may be specified by ATUBE as follows:ATUBE axis c1_min c1_max c2_min c2_maxwhere axis is one of X, Y or Zc1_min and c1_max are the coordinates of the intersections of the tube faces with the coordinate axis that comesnext in cyclic permutation order after axis.c2_min and c2_max are the coordinates of the intersections of the tube faces with the coordinate axis that comessecond in cyclic permutation order after axis.6. A volume bounded in three dimensions may be specified by ABOX as follows:ABOX axis c0_min c0_max c1_min c1_max c2_min c2_maxwhere axis is one of X, Y or Zc0_min and c0_max are the coordinates of the intersections of the box faces with axis.c1_min and c1_max are the coordinates of the intersections of the box faces with the coordinate axis that comesnext in cyclic permutation order after axis.c2_min and c2_max are the coordinates of the intersections of the box faces with the coordinate axis that comessecond in cyclic permutation order after axis.7. If c_max = c_min for any axis, an error is generated.8. If c_max

<strong>ASAP</strong> | Commands and Macros (H) | 168HORN (<strong>ASAP</strong> Command)Creates a generalized tube with polynomial profiles and elliptical/rectangular cross-sections.Function• Define/Modify Surfunc EntitiesSyntax 1HORN X x r [ r' r" ... ] [ FIT n x [ x' x" ... ] ]Y y [ y [ y' y" ... ] ]Z z [ z [ z' z" ... ] ]Syntax 2 (see Remarks)HORN Z z x0 [ x1 x2 ... ] [ FIT n z0 [ z1 z2 ... ] ]y0 [ y1 y2 ... ] [ n' z0' [ z1' z2' ... ] ]q0 [ q1 q2 ... ] [ n" z0" [ z1" z2" .. ] ]OptionDescriptionX, Y or Z Axis of symmetryx, y or z Location along coordinate axisr r' r"...FITnx x' x"..., y y' y"...,or z z' z"...<strong>Reference</strong> PointAt intersection of surface and coordinate axis.Surface NormalRadially outward from the axis.AutolimitingRequires a LOCAL modifier if a FIT is not being done.RemarksRadial coefficientsFlag to fit dataOrder number for the polynomialData points on surface1. Creates a symmetrical surface about the given axis, with a radial profile determined by the following polynomialin the radial distance squared:where d represents the particular axial distance coordinate relative to the reference point (and therefore d ismeasured in the local coordinate system).2. Syntax 1 and 2: The program can also FIT the given set of radial and axial positions to an nth-order polynomial (nless than or equal to 10). See LSQFIT to control the fitting algorithm.

<strong>ASAP</strong> | Commands and Macros (H) | 1693. Syntax 2: Rectangular/elliptical horns with different polynomial profiles in the two cross-sections can be createdwith variations of the following format (only the Z axis form is shown for sake of brevity):HORN Z z x0 [ x1 x2 ... ] [ FIT n z0 [ z1 z2 ... ] ]y0 [ y1 y2 ... ] [ n' z0' [ z1' z2' ... ] ]q0 [ q1 q2 ... ] [ n" z0" [ z1" z2" .. ] ]The q parameter controls whether the cross-section is elliptical, rectangular, or something in between. See theTUBE command for more details.4. Syntax 1 and 2: The coefficients or the fit points are relative to the reference point (the third entry). The followingrestrictions on the polynomial orders apply:n less than or equal to 10n' less than or equal to 8n+n' less than or equal to 10n" less than or equal to 6HORN Examples

<strong>ASAP</strong> | Commands and Macros (I) | 170Commands and Macros (I)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “I”.IDEAL (<strong>ASAP</strong> Command)Creates an idealized optical element (ABCD and Jones matrices).Function• Define/Modify Lens EntitiesSyntaxIDEAL X x h [ t [ h' ] ] [ RANA ] [ fcn ]Y yRANBZ z[ a b c d [ o ] ][ p q r s ]OptionDescriptionX, Y, or Z Specifies axis of symmetryx, y, or z Location along coordinate axishth'RANA or RANBfcna b c dop q r sRemarksInput aperture semidiameter (height)Output distanceOutput aperture semidiameter (height)Randomize the output rays azimuthally (around the axis)Name of the functionComponents of 2x2 ABCD matrixObject distance from first conicoid2x2 complex Jones matrix1. Defines an idealized (but unphysical) lens of input height h, output distance t, and output height h'. The inputray vectors are linearly related to the output ray vectors by the 2x2 ABCD matrix given on the next line of input(default is an identity matrix), and whose input polarization state is related to the output polarization state via aJones matrix.2. Jones matrix behavior is virtually independent of the incidence angle. Jones matrix behavior is virtuallyindependent of the incidence angle. For devices where the polarization state varies significantly with angle ofincidence, please see the realistic polarizer devices such as RRP, RPM, CPE, etc.3. Each matrix is entered on an individual input line. The matrix coefficients are as follows:Ray Matrixa bJones Matrixp q

<strong>ASAP</strong> | Commands and Macros (I) | 171Ray Matrixc d4. Common idealized optical elements include:Perfect lens of focal length f, a=1 b=0 c=-1/f d=1Afocal system of angular magnification m, a=1/m b=0 c=0 d=mJones Matrix"Nonlens" where output rays are extensions of input rays: a=1 b=t c=0 d=1Telecentric lens of focal length f and semi-field angle u, t=f a=1 b=f c=-1/f d=0 h'=h+ftanu5. The input and output media are assumed to be the same isotropic medium. Therefore, the determinant of the raymatrix should be unity; that is, ad-cb=1.6. There are no ray aberrations at any conjugates. However, the wavefronts from this lens can be only perfectlyspherical for a single conjugate. The o is the object distance from the first surface for the perfect imaging. Thedefault value for o is zero; the object is at infinity (optical path length is not constant for different field points).7. The optional additional line of input p q r s is the four elements of the 2x2 complex Jones matrix for linearlyaltering the polarization states of transmitted beams. In general, Jones matrices are defined only for beamsnormally incident on the reference plane. Therefore, non-normal incidence beams may have their polarizations(and fluxes) altered in unexpected ways. See the realistic polarizer devices such as RRP, RPM, CPE, etc. foralternate representations.8. The RAN options azimuthally (around the axis) randomize the output rays. RANA randomizes the angle. RANBrandomizes both position and angle by rotating about the center of the output aperture. These options can be usedto simulate some non-imaging effects.9. The fluxes of the rays can be apodized both radially and directionally if a $FCN fcn is specified. The functiontakes as it first argument _1 the normalized (between 0 and 1) radial position of the ray. The optional secondargument _2 is the sine of the angle from normal for the ray direction. The value returned (last expression) ismultiplied by the ray flux to get the new ray flux. For example, these two options could be combined to do anefficient simulation of an incoherent multi-mode fiber:r sNA=.5 !numerical aperture of fiber$FCN CUTOFF RECT(_2/(2*NA)) !directional cutoffIDEAL Z 0 .1 1000 .1 RANB CUTOFF !1000mm long 100um fiberIDEAL ExamplesIESFILE (<strong>ASAP</strong> Command)Writes out an Illuminating Engineering Society (IES) formatted file.Function• Display/Modify Data DistributionsSyntaxIESFILE [ name [ SFLUX f ] [ ELLIP w l h ] ] [ PAD [ p ] ] [IES1995][ 'string' ]RECTOptionnameDescriptionName of the created file (extension is .IES)

<strong>ASAP</strong> | Commands and Macros (I) | 172OptionSFLUXELLIP or RECTwlhPAD pIES1995'string'DescriptionCauses the source flux f to be written to the header of theoutput IES fileAdds the devices ELLIPtical or RECTangular width,length, and height to the header of the output IES fileWidth of the elliptical or rectangular deviceLength of the elliptical or rectangular deviceHeight of the elliptical or rectangular deviceFlag to pad the distribution with value given by p(defaults to minimum value in the distribution if p isomitted)Output creates a LM-63-1995 format fileAdds a comment string to the header of the IES fileRemarks1. Writes out a standard LM-63-2002 IESNA photometric file (name.IES) representing an angular distributioncreated by either a RADIANT command (A-Type or C-Type photometry, where the polar axis becomes vertical),or a SPOTS DIR and ANGLES combination (B-Type photometry). The IESFILE must follow the LM-63-2002standard or LM-63-1995 standard. The default standard is LM-63-2002. To write to the LM-63-1995 standard, theIES1995 option must be present.2. The device's RECTangular or ELLIPtical width w, length l, and height h can be written to the header of the outputIES file. The dimensions are written either in meters (if the system UNITS are metric) or in feet (if the systemUNITS are English). If system UNITS are not defined, the dimension default is meters.3. If the distribution does not cover the whole sphere, it can be optionally PADded with value p, which defaults tothe minimum value in the distribution for A-Type and B-Type photometry.4. PADding is not performed for C-Type photometry. Distributions for C-Type photometry are assumed to fill asphere and can be created, for example, with this script:RADIANT Z 0 180 180 0 360 3605. A comment string may be added to the header of the output IES file.6. IESFILE must be executed from within the display mode, as shown in the following example:DISPLAY...ANGLES !!if required only with B-Type photometryIESFILE filename...RETURN7. The IESFILE command assumes that the polar and azimuthal angles that are written in the distribution filefollow the IESNA standard ranges for the specific photometry type, and are in ascending order.Note: The IESFILE command does not accommodate non-IESNA standard angles in the distributionfile. Users are required to follow the IESNA standard for setting the polar and azimuthal angles on theRADIANT command to create correct IES Photometry A and C files. The spans of the polar and azimuthangles are necessary to allow proper projection of the RADIANT command results into IES results withthe IESFILE command. This rule also applies to the SPOTS DIRECTION command for the creationof correct IES Photometry B files. Please see RADIANT and SPOTS DIRECTION command topics formore details.

<strong>ASAP</strong> | Commands and Macros (I) | 1738. For symmetric distributions, the horizontal angles in the distribution file must cover the entire angular range.IESFILE Examples$IF (<strong>ASAP</strong> Macro)Creates conditional processing of a block of records or block structures.Syntax$IF a rel b [ log a' rel' b' log' ... ] [ n ]Remarks1. This macro provides a means to optionally run a block of n records, depending on the result of some combinationof relational and logical operations. The a and b entries (either both numerical or both literal) are compared usingthe specified RELational operator. More complex tests are evaluated from left to right using the LOGical and/orRELational operators.2. Valid operators are listed below.Relational operatorsEQLTGTNEGELEequalless thangreater thannot equalgreater than or equalless than or equalLogical operatorsANDOREQVNEQVXORlogical "and"logical "or"equal in logical valuenot equal in logical valueexclusive or (same as NEQV)3. Normally, the relational operators compare two floating-point (real) entries or two full, 40-character literals(including trailing blanks.) However, if any recognizable alphanumeric character is appended to the operatorname, truncated forms of the two entries are compared; that is, the nearest integer equivalents of the numerics orthe literals, truncated to the smaller of the two. Numerical comparisons performed with augmented operators (forexample, EQS instead of EQ) on floating point values are performed by rounding to the nearest integer (not bytruncation). In this remark, "augmented" refers to one of the previously mentioned comparison operators with anextra character appended.Example of Truncated Comparisons:1.75 EQ 2. false1.75 EQI 2 trueYES EQ Y falseYES EQS Y true

<strong>ASAP</strong> | Commands and Macros (I) | 1744. If the overall $IF result is true, the next n input records are processed, including any commands that follow the$IF on its record. Otherwise, they are skipped over, and processing resumes on the next record.5. The default value of n is 1; that is, only the next record is processed if the expression is true. However if n is notspecified and more commands follow the $IF on its record, n is set to zero. Otherwise, the default is 1.6. This macro, when combined with other macros and registers, can be used to implement extended DO blocks thatinclude more than one input record; for example::$ERR end!on error, go to "end" of loopL=0 !initialize loop counterL=L+1!increment loop counter at top of loop:!block of n-3 input records:$IF (L) GE 10; $GO end !test for end of loop$GO -n!otherwise go back to top of loopend:$IF Examples$IF THEN (<strong>ASAP</strong> Macro)Use the THEN keyword at the end of a $IF statement to trigger processing of conditional block structures.Syntax$IF a rel b [ log a’ rel’ b’ log’ ... ] THEN:[ $ELSEIF ... THEN ]:[ $ELSE ]:$END[IF]Remarks1. The THEN keyword is used to trigger processing of conditional block structures.2. These structures can be nested up to 99 deep. However, the control words must be uniquely and identicallyindented at each level of nesting. This mandatory indentation significantly speeds processing and is also a goodstandard programming practice. This example shows an IF structure inside a DO loop block.$DO 1 3{ $IF ?\2 EQ 0 THENA?=?$ELSEB?=?$ENDIF }3. Notice the required vertical alignment of the $IF, $ELSE, $ENDIF commands.4. Using a $GO to jump into a block may cause unexpected results.5. Only a forward $GO to a label can be safely used to jump out of a block.$IF THEN Examples

<strong>ASAP</strong> | Commands and Macros (I) | 175IMAGE Curve/Edge (<strong>ASAP</strong> Command)Images a curve/edge through a specified LENS entity.Function• Define/Modify Curvedge EntitiesSyntaxIMAGE l k k'Optionk k'lDescriptionStarting/ending curve/edge points in spaceLens entityRemarks1. Images the points of the current curve/edge from space k to space k' of LENS entity l.2. The spaces k k' are numbered from 1 (before the first conicoid) to N+1 (after the last conicoid N).3. IMAGE uses the auxiliary axis technique that steps the image through the centers of curvature of the conicoids (theaperture semi-diameters, conic constants, and obscuration ratios of the conicoids do not affect the imaging), andalways produces an image even if it is virtual or unphysical. The resulting imaging transform is stigmatic (pointsgoing into points), but not necessarily collinear (lines going into lines). Therefore, it is only an approximation,since in any real optical system, the image is aberrated (not a perfect point focus).4. IMAGE is most useful for SCATTER TOWARDS edges that represent images of importance areas.5. IMAGE can also be used to image the stop surface to locate pupil positions.IMAGE ExamplesIMAGE (Global Point) (<strong>ASAP</strong> Command)Images a global point through a specified LENS entity.Function• Define/Modify Lens EntitiesSyntaxIMAGE k x y z k'Optionk k'x y zDescriptionStarting/ending spacesGlobal pointRemarks1. Images the given point x y z in space k of the current lens into space k' and displays the coordinates.2. The spaces are numbered from 1 (before the first conicoid) to N+1 (after the last conicoid N).3. Uses the auxiliary axis technique that steps the image through the centers of curvature of the conicoids (theaperture semi-diameters, conic constants, and obscuration ratios of the conicoids do not affect the imaging), andalways produces an image even if it is virtual or unphysical. The resulting imaging transform is stigmatic (pointsgo into points), but not necessarily collinear (lines go into lines). Therefore, it is only an approximation, since inany real optical system, the image is aberrated (not a perfect point focus).

<strong>ASAP</strong> | Commands and Macros (I) | 176IMAGE ExamplesIMAGE (Ray Positions) (<strong>ASAP</strong> Command)A ray modifier that finds the conjugates of ray coordinates through a LENS (images the current ray positions througha specified LENS entity).Function• Modify Ray/Beam DataSyntaxIMAGE l k k'Optionlk k'DescriptionLENS entityStarting/ending spacesRemarks1. Images the current ray positions (not directions) from space k to space k' of LENS entity l. The spaces arenumbered from 1 (before the first conicoid) to N+1 (after the last conicoid N).2. IMAGE uses the auxiliary axis technique that steps the image through the centers of curvature of the conicoids (theaperture semi-diameters, conic constants, and obscuration ratios of the conicoids do not affect the imaging), andalways produces an image even if it is virtual or unphysical. The resulting imaging transform is stigmatic (pointsgo into points), but not necessarily collinear (lines go into lines). Therefore, it is only an approximation, since inany real optical system, the image is aberrated (not a perfect point focus).3. IMAGE is most useful for mapping a grid of rays at an internal stop position of an optical system into its objectspace (that is, entrance pupil).ExampleMapping a grid of rays at an internal stop position of an optical system into its object space.LENS 99; ... !!equivalent imaging train:GRID ... !!covers internal stopIMAGE 99 4 1 !!image into entrance pupilSOURCE DIR ... !!now set directionsMOVE TO ... !!out in front of first surfaceTRACEIMAGE ExamplesIMMERSE (<strong>ASAP</strong> Command)Creates rays in MEDIA other than air/vacuum.Function• Setup Beam Creation

<strong>ASAP</strong> | Commands and Macros (I) | 177SyntaxIMMERSE [ m ]OptionmDescriptionMedia name or number (default=0)Remarks1. Sets the starting MEDIA (refractive index) for future ray creation to m (name or number, default 0). AIR/VACUUMis available with a refractive index of 1.2. The propagation of rays and fields in <strong>ASAP</strong> depends on the properties of all media with which the rays interact,including the medium in which rays originate. By default in <strong>ASAP</strong>, the initial medium is air/vacuum (n=1).Sources that are immersed or embedded in another medium must be preceded by an IMMERSE command tooverride the default.3. Spherical particles in a VOLUME MIE model must be immersed in their host media. The IMMERSE commandshould precede a VOLUME MIE model declaration.4. LENS objects are immersed in AIR/VACUUM by default. Use the IMMERSE command to change media at theentrance and exit port.Note: For Wave Optics: Since the propagation of fields depends on the surrounding medium, the IMMERSEcommand should precede the DECOMPOSE command.IMMERSE ExamplesIMPORT (<strong>ASAP</strong> Command)Import a lens from a ZEMAX file.Function• Define/Modify Lens EntitiesSyntaxIMPORT X x file [ k ] [ options ... ]Y yZ zOptionfilekoptionsDescriptionSpecifies ZEMAX file nameLens configurationFrom ABERRATIONS commandRemarks1. Import lens (configuration k) from ZEMAX file position reference (GLRS or first) surface at a given plane, andrun any ABERRATIONS options.2. Supports these ZEMAX surface types: STANDARD, ODDASPHE/EVENASPH (approximate), DGRATING(Sweatt model), PARAXIAL, and TILTSURF.IMPORT Examples

<strong>ASAP</strong> | Commands and Macros (I) | 178INTERFACE (<strong>ASAP</strong> Command)Assigns a reflective, refractive or diffractive interface to objects.Function• Create/Modify ObjectsSyntax 1INTERFACE r [ t m m'] …COAT k coat coat'-k+kSyntax 2INTERFACE … DIFFRACT i j [ e j' e' … ]coat coat'Syntax 3INTERFACE … DIFFRACT i coat j j' j" …Syntax 4INTERFACE … DIFFRACT i… DIFFRACT i' … [ DIFFRACT i" … ]Optionrtm m'kDIFFRACTij j' ...e e' ...coat coat'DescriptionReflection coefficientTransmission coefficientMedia numbers (or names) on each side of the objectCoating number (or name)Flag to assign a diffractive interface to an objectMULTIPLE surface numberDiffraction order number(s)Relative efficiencies of the corresponding ordersName of a given coating propertyRemarks1. If the object surface is an optical boundary through which rays are to be traced, the optical properties of theinterface must be specified using the INTERFACE command, after the definition command for that object.2. The r is the relative energy (or complex amplitude) reflection coefficient for the surface (or the reflectors in a lensstructure).3. The t is the transmission coefficient of the surface (or the refractors in a lens structure, their reflectivities are thenassumed to be 1t).

<strong>ASAP</strong> | Commands and Macros (I) | 1794. If explicitly stating numerical r and t quantities in the INTERFACE command, the COATING parameter shouldnot be used; otherwise, <strong>ASAP</strong> produces the wrong number of rays. For example, instead of entering:INTERFACE COATING 0 1 GLASS GLASSenter:INTERFACE 0 1 GLASS GLASSwhere "0 1" are examples.5. If t is nonzero, m and m' are the numbers (or names) of the media on each side of the object surface.6. The order in which m and m' are entered is arbitrary; <strong>ASAP</strong> determines which to use.7. If either side of the interface is air or vacuum, m or m' may be set to 0 (zero), AIR, or VACUUM.8. Alternatively, the r and t coefficients can be determined from coating number or name k (0 for a BARESUBSTRATE) and the current WAVELENGTH. <strong>ASAP</strong> uses the reflection and transmission values from theCOATING PROPERTIES table or calculates the coefficients from the COATING LAYERS table based on thenormal incident form of Fresnel's formulae.9. The signs in front of k can be used to instruct <strong>ASAP</strong> to either propagate only a reflected ray (-k: t=0) at that object,or to propagate only a transmitted ray (+k: r=0) at that object.10. INTERFACE COATING +k m m', where k=0 or BARE_SUBSTRATE, is the syntax for modeling thepolychromatic transmission properties of a bare substrate. The transmission coefficient is calculated from thenormal incident form of the Fresnel formulae and applied to all incident ray angles.11. If an INTERFACE command does not follow an object definition, the surface is assumed to be perfectlyabsorbing, and all rays reaching the surface is trapped there.12. Diffractive lines are created by the intersection of the object surface with the different sheets of a MULTIPLEsurface i; that is, a ruled linear grating is created if i is a plane, a zone plate is created if the surface is a cylinder,etc.13. If i is positive, the multiple sheet spacing is taken to be the grating spacing in system units. If i is negative, thespacing is assumed to be in the same units as the last WAVELENGTH specification. The number of sheets enteredon the MULTIPLE surface command has no bearing on this application.14. <strong>ASAP</strong> generates diffracted rays/beams for the diffraction order numbers given by the j's, with relative efficienciesgiven by the corresponding positive e's.15. If an e is entered as a negative number or as a name, it is a COATING PROPERTY possibly containingpolychromatic complex amplitudes.16. A named COATING MODEL can be used to specify the angular variation of the diffraction order efficiencies; thatis,INTERFACE ... DIFFRACT i coat j j' j" ...17. Multiple exposure holograms can be modeled by using more than one DIFFRACT option (the zeroth-order shouldonly be specified once):INTERFACE ... DIFFRACT i ... DIFFRACT i'... [ DIFFRACT i" ... ]INTERFACE ExamplesINTERFACE POLARIZATION (Polarization Modifiers) (<strong>ASAP</strong> Command)Assigns a polarization modification interface to objects.Function

<strong>ASAP</strong> | Commands and Macros (I) | 180• Create/Modify ObjectsSyntaxINTERFACE POLARIZATION {±polarization device type|type ID} {name|ID} thetaphi media1 media2 [a b c] [DIR a’ b’ c’] [LOCAL]Optionpolarization device type|type IDName|IDThetaPhimedia1, media2a,b,cDIR a' b' c'LOCALDescriptionSpecifies the type of the polarization device attached tothis surface. See Remarks for the defined polarizationdevice types.Name of the specified polarization device. Alternatively,you can input the list index of the specified polarizationdevice on its defined list.Polar angle of the polarization axis of the polarizationdevice in the attached surface's local coordinate system.Theta is the angle between the polarization axis and thelocal x-y plane. The valid range is [-90, 90 degrees]. Theangle must be specified in degrees.Azimuthal angle of the polarization axis of thepolarization device in the attached surface's localcoordinate system. The angle must be specified indegrees. The valid range is [0, 36 degrees].Input/output media of the interface.Directional cosines of the local x axis. The cosinesspecify the optional local x axis of the polarizationelement of the polarization interface. You can specifythis local x axis to turn off the conformal process forthis surface polarization modifier (object level). SeeRemarks.Positive propagation direction for the surfacepolarization modifier. The a' b' c' are the direction cosineof the desired direction and can also be replace with X,Y, Z to specify global X, Y, and Z axes. The default isglobal +Z axis if the axis is not specified.Alignment flag to indicate the initial orientation of thepolarization device before the conformal wrapping.Remarks1. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER

<strong>ASAP</strong> | Commands and Macros (I) | 181Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command3 Realistic polarizer POLARIZER RPM4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC8 Cascaded polarizationelement2. The sign + or - before the polarization device type/type ID controls ray tracing and splitting on surfacepolarization modifier. The + sign instructs <strong>ASAP</strong> to trace only the transmitted ray and the reflected ray is ignored.The - sign instructs <strong>ASAP</strong> to trace only the reflected ray and the transmitted ray is ignored. If no sign is presented,which is the default, both the transmitted ray and reflected rays are traced.3. The surface local coordinate is defined as the local z-axis in surface normal direction. The local x axis isdetermined by the "conformal wrapping" process. The polarization axis is specified in this local coordinate formost flexibility. The polarization axis is different for different types of polarization devices.Note: Turning off conformal process is physically valid only for planar objects, since the local x axisis same for every point on the plane. However, for any other non-planar object, <strong>ASAP</strong> always uses aconformal wrapping process to determine the local x axis, and the conformal wrapping process cannot beoverridden.4. The order of media1 and media2 is important. Media 1 is assumed to be the incident medium, and media2 isassumed to be the exit medium if the ray propagates forward in the direction specified by the DIR option.<strong>ASAP</strong> first uses media on both sides of the interface to determine the ray propagation direction (forward orbackward propagation). If the media are same, <strong>ASAP</strong> uses the angle between the base ray vector and the positivepropagation direction specified by DIR option to determine the ray propagation direction. Rays with an angle lessthan ±90°, with respect to the positive propagation direction, are assumed to propagate forward. Otherwise, raysare assumed to propagate backward.5. BEAMS INCOHERENT GEOMETRIC must be set.6. Globally, FRESNEL must be set to either AVE or BOTH to set up a surface polarization ray tracing throughsurface polarization modifiers. In general, BRO recommends FRESNEL BOTH for the global FRESNEL setting.Since FRESNEL AVE as the global setting is an advanced feature, proceed with caution. If used correctly, it doesallow <strong>ASAP</strong> to model unpolarized light in JONES vector mode. For STOKES vector mode, FRESNEL must be setto BOTH.7. Wavelength must be set before any surface polarization modifier can be used.8. If the object has multiple entities, the surface polarization modifier is attached to all entities of the object.9. If LOCAL is presented, the initial orientation of the polarization device is assumed to be aligned with the localsurface coordinate of the object at the reference point. Otherwise, the initial orientation of the polarization deviceis assumed to be always aligned with global coordinate, no matter what the rotation of the object.INTERFACE POLARIZATION ExamplesCPECPEINTERFACE REPEAT (<strong>ASAP</strong> Command)Assigns the interface characteristics of either a specified object or the previous object to the current object.Function• Create/Modify ObjectsSyntaxINTERFACE REPEAT [ i ]

<strong>ASAP</strong> | Commands and Macros (I) | 182OptioniDescriptionObject numberRemarks1. If i is zero, all the interface properties are removed.INTERFACE ExamplesINVERT (<strong>ASAP</strong> Command)Reverses the parametric direction of a curve.Function• Define/Modify Curvedge EntitiesSyntaxINVERTRemarks1. Reverses the parametric direction of a curve; that is, spatially it remains the same curve but the last point becomesthe first and vice-versa.2. INVERT is useful when connecting curves into a parametric mesh OBJECT.3. If the entity is a PATCH or USERCURVE parametric surface, this command just transposes the u and v parametricdirections.INVERT Examples$IO (<strong>ASAP</strong> Macro)Controls I/O redirection.Syntax$IO iotype n iotype' ...literalfile [ n ]$IO [ n ]Remarks1. Redirects the ASCII I/O specified by the iotype to another file or logical unit number n.2. The significance of each type and its defaults are described in this table.Input/Output Type N DefaultName(*.DAT) Extension DescriptionINPUT 1 BRO001 INR Default commandinputLIBRARY 24 BRO024 LIB Macro library(new precedenceexpressions). SeeNote.

<strong>ASAP</strong> | Commands and Macros (I) | 183Input/Output Type N DefaultName(*.DAT) Extension DescriptionMACRO 24 BRO 024 MAC Macro library(old left-rightexpressions). SeeNote.OUTPUT 6 BRO 006 OUT Default nongraphicaltextoutput. See Note.GRAPHICS 6 BRO 006 OUT Character graphicsoutput (off bydefault)USER 7 BRO 007 USR Archive ofinteractively enteredcommands* 8 BRO 008 virtual.pgs* 9 BRO 009 Default distributiondata filePLOT 20 BRO 020 PLR Default 2-D plotinstruction outputLIBRARY 24 BRO 024 LIB Macro librarycommand input(new expressionparser)* 29 BRO 029 Complex opticalfield data fromFIELDVECTOR 30 BRO 030 VCR Default 3D vectorinstruction outputFILE - Arbitrary file (usermust specify n)** I/O cannot beredirectedNote:$IO OUTPUT text files of type *.out can be opened in a text file under Windows 7 only if you haveassociated this file type with a text editor. Right-click an existing *.out file, click Open with, and clickNotepad or WordPad (or any other installed text editor). You can also assign a *.txt extension to the filename on the $IO OUTPUT command to assign that extension. For example:$IO OUTPUT JOE.TXT 2Alternatively, assign a file extension of *.txt in place of *.out.Library files specified with the $IO LIBRARY syntax are searched for in the following locations, in thisorder:• working directory,• $SEARCH path elements, in the order assigned,

<strong>ASAP</strong> | Commands and Macros (I) | 184• directory containing the last library specified with $IO LIBRARY, if any, and• directory specified by the FILES environment variable, on platforms supporting environment variables.3. An iotype entry without any trailing arguments simply closes that unit; to reopen it, type$IO iotype nwhere n is the file unit number.4. If no entries are present, $IO toggles the program input between your Command Output window and the currentinput unit assignment. This allows you to insert interactive breakpoints in the input file.5. When directing OUTPUT to a file, it is by default also echoed to the Command Output window. If the word ONLYis placed after the file name instead of the unit number, nothing is sent to the Command Output window. Forexample,$IO OUTPUT file n$IO OUTPUT file BOTH$IO OUTPUT file ONLY!both to file and console!same!just to file6. A prefix character for each number or a literal determines which of the following operations are performed beforethe unit is used:Literal Numeric Form OperationAPPEND +n Unit n is positioned at the end of thefileCANCEL 0 Output to iotype (GRAPHICS,PLOT, VECTOR) is suppressedCHANGE n Current position of unit n is notchangedCLOSE None Unit associated with iotype is closedDELETE 0n Unit n is closed and the associatedfile is deletedREWIND -n Unit n is positioned at the beginningof the fileExampleTo understand the relationship between unit number and file name, consider the following example.$IO OUTPUT JOE 2is equivalent to the Fortran expression:OPEN (unit=2, file="JOE.OUT",. . .).In this special case, text is directed to the file JOE.OUT and to the screen. Without the unit number, text is directedonly to the file.$IO ExamplesIRRADIANCE (<strong>ASAP</strong> Command)Selects the axis that energy or peak flux density is computed relative to a given fixed direction for all sample points.

<strong>ASAP</strong> | Commands and Macros (I) | 185Function• Calculate Diffraction/Propagation EffectsSyntaxIRRADIANCE [ OFF ]XYZOptionOFFX Y or ZDescriptionCompute irradiance relative to local propagationdirectionCompute irradiance relative to given fixed directionRemarks1. Causes any future SPREAD or FIELD commands (until it is turned OFF) to calculate the irradiance (flux per unitarea) relative to a given fixed direction for all sample points.2. If no entry is given, the normal to the sample grid is used.3. If the IRRADIANCE command is turned OFF by default, the SPREAD and FIELD commands calculate theenergy or peak flux density relative to the local propagation direction at each sample point.IRRADIANCE ExamplesISOMETRIC (<strong>ASAP</strong> Command)Creates an isometric view of the current distribution data file.Function• Display/Modify Data DistributionsSyntaxISOMETRIC [ s ] [ n ] [ 'title' ]Optionsn'title'DescriptionReadjustS the vertical scalePlots every nth line (default is n=1)Optional title for plot (up to 64 characters)Remarks1. Produces a true isometric view of the data and no 1D cross-sections.2. ISOMETRIC is similar to the PLOT3D command.3. The floating point entry s can be used to readjust the vertical scale.4. The integer entry can be used to plot every nth line instead of the default of every line (n=1).5. The title is delimited by single quotes 'title', as shown.ISOMETRIC Examples

<strong>ASAP</strong> | Commands and Macros (I) | 186$ITER (<strong>ASAP</strong> Macro)Iterates input records and a set of variables.Syntax$ITER vary a b n [ vary' a' b' n' ... ] [func [ func' ... ][ 'title'] ] [NOMIN] [ m ] d d' ...Remarks, 1st syntax1. The first syntax of $ITER iterates the next input record (or brace delimited block) while changing the internalregister vary from a to b in n steps (up to 30000):2. Up to 60 vary variables (levels of iteration) are permitted, so that the next input record is executed n*n’*... times.If a single register func is specified, the values stored in func at the first three levels of iteration are written to aBRO binary distribution file. If more than one func register is specified, the sum of the squares of these valuesis written to the file instead. The name of the distribution file is either ITER.DIS or macro.DIS, with an optionaltitle. The file may be processed like any Distribution file, typically with the DISPLAY command and relatedcommands.3. One additional iteration is performed, by default, after the specified n*n'*... iterations, with the vary variables setto the values for which either the discrete value of func was minimized, if only one func register was specified; orthe discrete value of the sum of the squares of the func registers was minimized, if more than one was specified. Ifthe minimum of the discretely tabulated value is not unique, the first minimizing combination of vary variables isused, in the order of iteration.4. The additional iteration can be suppressed by specifying the NOMIN option. Consequently, NOMIN is a reservedname within the scope of an ITER construct and cannot be used as a func register. If NOMIN is specified,each vary variable contains its corresponding terminal value upon completion of the iterations. If NOMIN isnot specified, the vary variables are set to the values corresponding to the (possibly non-unique) minimum, asdescribed in the previous paragraph, upon completion of the additional iteration.5. The second sytax iterates the next input record either m times while changing the vary variables randomly, or inorder to approach the actual minimum of the sum of the squared func registers (up to 250). If m is specified, the dsare the probability distribution types. That is,Otherwise if m is not specified, the ds are fractional derivative increments relative to the ranges a b, which areused to build a change matrix that will be solved by a SVD technique. Double-sided derivatives are computed toapproximate a damping factor from the non-linearity predicted by the homogeneous second derivatives. Therefore,the required number of iterations is 2*(variables+1); that is,

<strong>ASAP</strong> | Commands and Macros (I) | 1876. The number of funcs should be greater than (>) or equal to (=) the number of vary's to find a unique solution. Inthe case of nonlinear problems, successive $ITER commands may be required to reach the precise minimum.7. Use &ITER instead of $ITER to automatically cancel output during loop processing and restore it whencompleted.8. Multiple record iteration loops must be enclosed in braces; that is, the next record after the ITER and the firstrecord of the block must start with an open brace { and the last must end with a closed brace }.$ITER vary a b n [ vary ' ...] [ func [ func' ... ] ]{ ...:... }$ITER Examples

<strong>ASAP</strong> | Commands and Macros (JKL) | 188Commands and Macros (JKL)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letters "J, K, L".JONES (<strong>ASAP</strong> Command)Defines a Jones matrix element polarization device definition.Function• Create/Modify ObjectsSyntaxJONES T11 T12 T21 T22 [R11 R12 R21 R22] [REFL] ['name']OptionNameT11, T12, T21, T22 Transmission JONES matrixR11, R12, R21, R22 Reflection JONES matrixnameName of the JONES matrix element, up to 32 characterslongNote: the name is case sensitive.Remarks1. For the Jones matrix element, the polarization axis refers to its local x axis.2. The REFL option is important if only one JONES matrix is specified. In this case, the REFL indicates that thespecified JONES matrix is for only a reflected ray. If REFL is not presented, the specified JONES matrix defaultsto being applied to a transmitted ray. If two JONES matrices are specified, the first JONES matrix is applied to thetransmitted ray and the second to the reflected ray.3. If no name is supplied by users, <strong>ASAP</strong> uses a default name string with "JONES", followed by the list index ofthis Jones matrix element in the system Jones matrix element list. For example, the second Jones matrix is named"JONES00002".4. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER3 Realistic polarizer POLARIZER RPM4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC

<strong>ASAP</strong> | Commands and Macros (JKL) | 189Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command8 Cascaded polarizationelementJONES ExamplesCPECPEKCORRELATION (<strong>ASAP</strong> Command)Creates an isotropic K-Correlation scatter model.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxKCORRELATION r rms b w dn s [ PLOT [ a a’ …] ]OptionrrmsbwdnsPLOTa a' ...DescriptionSurface specular reflectivityTotal effective rms (root mean squared) surfaceroughness over frequencies from 0 to 1/m, ( ( )), in units of2 times surface correlation length Lc ( m); seeRemarksMeasurement wavelength, in units ofChange in index of refraction at the surface, (=2 formirrors)Slope of the Log-log BSDF plot (S 2 and BRDF function)at large spatial frequencies (S)Plots the model in log(b-bo) and angle spaceUser-defined degree specular anglesmRemarks1. This model is similar to ABg model, but with an additional small angle roll-off. It is useful to characterize manysurface finishes. The BSDF of this model can be written as:

<strong>ASAP</strong> | Commands and Macros (JKL) | 190Note: See the technical guide, "Scattering in <strong>ASAP</strong>" on the Knowledge Base for more information on thisfeature.2. May be used with importance area sampling.3.The w is the wavelength (in unit of m) at which this model is defined (or was measured).4. Command argument, PLOT plots the model (common base 10 logarithm of the BSDF) for up to seven specularangles in ascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls theresolution of these plots in direction cosine space, and creates a distribution file, name_angle.dis, for each of theseangles.5. The command argument, MINMAX can be used to set the minimum and maximum values of the BSDF for thisspecific model.KCORRELATION ExamplesLAMBERTIAN (<strong>ASAP</strong> Command)Creates a Lambertian scatter model.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxLAMBERTIAN t [ PLOT [ a a' ... ] ]OptionDescriptiont Total hemispherical diffuse scatter ratio (

<strong>ASAP</strong> | Commands and Macros (JKL) | 191Syntax 1LCC thickness {no ne}| Crystal_Medium_index THETA|PHI start_angleend_angle steps [REFL [Rs Rp]] ['name']Syntax 2LCC thickness {no ne}| Crystal_Medium_index THETA|PHI FCN|TABLE steps[REFL [Rs Rp]] ['name']Syntax 3LCC thickness {no ne}| Crystal_Medium_index BOTH {FCN1 FCN2}|TABLE steps[REFL [Rs Rp]] ['name']OptionThicknessnoneCrystal_Medium_indexTHETA|PHI|BOTHStart_angle, end_angleStepsFCN, FCN1, FCN2TABLEREFLRsRpnameDescriptionThickness of the liquid crystal cell, which must bespecified in um. Default value is 5um.Ordinary refractive index of the liquid crystal. Default is1.487. See Remarks.Extraordinary refractive index of the liquid crystal.Default is 1.568. See Remarks.Refractive index of a previously defined crystal mediumControls the spatial variations of the direction of theoptical axis (or director) of the liquid crystal along thedepth of the cell. See Remarks.Specifies the start and end angles of the varying angle forthe linear distribution.Specifies the number of sub-cells used to model the LCcell.Name of a user defined function to control thedistribution of the varying angle of the LC director. SeeRemarks.Keyword specifying that the variation of the liquidcrystal director, which is listed in a table below thecommand.Controls reflection calculation. See Remarks.Power reflectance for s-polarization. Default is 0 (noreflection).Power reflectance for p-polarization. Default is 0 (noreflection).Name of the LCC device. Default name format isLCC0001, LCC0002, and so on.

<strong>ASAP</strong> | Commands and Macros (JKL) | 192Remarks1. The liquid crystal cell (LCC) model accurately models both on- and off-axis propagation of polarized lightinside the crystal with the extended Jones matrix method under small birefringence approximation; that is,.2. The liquid crystal cell is divided into a number of sub-cells. Multiple reflections at the interfaces of the sub-cellsare ignored. Fresnel transmission loss at the cell input and output interface can be automatically calculated. Thereflection on the input interface can be included if enabled.3. The incident and exit medium of the liquid crystal cell are assumed to be isotropic.4. In general, both polar and azimuthal angles of the optic axis of the liquid crystal vary along the depth of the cell.Syntax 3 is designed for this general application scenario.5. Polar angle is defined as the angle between the optic axis and the liquid crystal cell surface plane (xy plane), andazimuthal angle is the projection of the optic axis on the xy plane and the x axis.6. Detailed implementation of the extended Jones matrix method can be found in A. Lieu, “Extended Jonesmatrix representation for the twisted nematic liquid-crystal display at oblique incidence,” Appl. Phys. Lett. 57,2767-2769 (1990).7. For no, you can alternatively specify the name or index of a previously defined crystal media, as in Syntax 2.<strong>ASAP</strong> interprets types of this input differently for integer and real numbers. For real numbers, <strong>ASAP</strong> assumes thatit stands for the refractive index, while for an integer, <strong>ASAP</strong> assumes that it stands for the index of a previouslydefined crystal media.8. ne is used to specify directly the extraordinary index of the crystal.Note: ne is not used if the device crystal is specified by a previously defined crystal media.9. THETA means that only the polar angle varies and the azimuthal angle is constant. PHI means that only theazimuthal angle varies and the polar angle is constant, which means it is a twisted liquid crystal cell. BOTH meansthat both polar and azimuthal angles vary along the depth of the cell.Note: BOTH can be used only in Syntax 3.The distribution of the varying angle along the depth of the cell can be linear, as in Syntax 1, or be controlled by auser defined function (FCN), or can be listed in a table (TABLE).10. In Syntax 3, the first function (FCN1) controls polar angle, and the second function (FCN2) controls azimuthalangle.11. For TABLE, the first column of the table is the depth. If only one angle is varying, the second column is the valueof that angle at the corresponding depth in first column. In this case, the table has only two columns. If both polarand azimuthal angles vary, the second column of the table is the polar angle and the third column is the azimuthalangle.Note: The number of rows of the table must match the number of sub-cells specified by steps argument.Also, the last input of the depth must match the thickness of the cell. For example, the following table isvalid for a liquid crystal cell of 5um thickness modeled with five sub-cells.1.0 10 5.02.0 20 12.33.5 30 15.74.5 40 19.05.0 50 25.012. If REFL is presented without Rs and Rp specified, the reflection is calculated with the Fresnel formula. If REFLis presented with Rs and Rp, the reflectance is Rs for s-polarized and Rp for p-polarized light, regardless of theincident angle of the ray. If not presented, the reflection is ignored.13. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.

<strong>ASAP</strong> | Commands and Macros (JKL) | 193Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER3 Realistic polarizer POLARIZER RPM4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC8 Cascaded polarizationelementLCC ExamplesCPECPE$LEAVE (<strong>ASAP</strong> Macro)Causes premature exit from a loop, macro, or input file.Syntax$LEAVE [ n ]Remarks1. This macro forces an immediate exit from the current DO loop, macro, or input file in that order.2. The n is the number of construct levels to exit (default is 1). If the above loop is also inside a macro and you wantthe test to exit not only the loop but also the macro, set n to 2.$LEAVE ExamplesLENSES (<strong>ASAP</strong> Command)Signals <strong>ASAP</strong> that lens definition commands follow.Function• Define/Modify Lens EntitiesSyntaxLENSES [ i ]OptioniDescriptionStarting number for defining LENSESRemarks1. <strong>ASAP</strong> defines a lens entity to be a sequence of refractive or reflective conicoid surfaces bounded by circularapertures and separated by homogeneous MEDIA. When assigned as a whole to an OBJECT, rays from otherobjects can only intersect the first or last conicoid of the lens. The ray then propagates sequentially through each

<strong>ASAP</strong> | Commands and Macros (JKL) | 194lens entity until it fails or exits at one of the ends. The advantage of a LENSES object over individual SURFACES(for example, OPTICAL) objects is not only simplicity but also speed in both ray tracing and 3D graphicalrepresentation (see PLOT LENSES).2. Lens entities have similarities with conventional sequential ray-tracing codes. Like surface entities, lens entitiescan be described by a mathematically continuous function and are fast to ray trace.3. The default value for i is one more than the highest lens number previously defined. The i is initialized to one atstart of program execution.4. EDGES, LENSES, and SURFACES data currently reside in the same internal storage locations. Therefore, aLENSES number cannot be the same as an already defined EDGES or SURFACES number.LENSES ExamplesLEVEL (<strong>ASAP</strong> Command)Controls the number of times a scattered ray may be rescattered.Function• Create/Modify ObjectsSyntaxLEVEL [ n ] [ OFF ] [ c ]ALLOptionnOFFALLcDescriptionMaximum number of scattering levels allowed forrandom diffuse raysTurns off generation of random diffuse raysGenerates scattered rays for each specular child rayDiffuse ray relative flux thresholdRemarks1. This command can be used either as a local command to override defaults for the current object, or as a globalcommand. In the latter case, the command acts as an interface control, and becomes the default used by anyobject for which it is not explicitly set. You must first issue a RETURN command before issuing a global LEVELcommand, since the global form of the LEVEL command is identical to the OBJECT subcommand.Note: The global form may be issued anywhere in the file before the TRACE, and it applies to all scatterinterfaces where explicit declaration is not set.2. LEVEL can be applied on an OBJECT by OBJECT basis. In effect, this is now an OBJECT modifier, similar to theINTERFACE command.3. Controls the level of scattered ray splitting in much the same way the SPLIT command controls the level ofspecular ray splitting.4. The parent rays (for example, a ray originally created by the GRID or RAYSET commands) are allowed togenerate random diffuse scatter rays at any object with a SCATTER RANDOM interface. The LEVEL commandcontrols the splitting of child scatter rays (rays that have been split off a parent ray). Therefore, LEVEL 1 tells<strong>ASAP</strong> to split the parent rays, but the child scatter rays are not allowed to split. LEVEL 2 allows the parent raysand the child scatter rays to split as often as necessary, but the grandchild scatter rays are not allowed to split.5. Deterministic near-specular and back-scattered rays (created at interfaces with SCATTER RMS or SCATTERBSDF) are never rescattered, so LEVEL should be set to 1 if only these two scatter mechanisms are of interest.

<strong>ASAP</strong> | Commands and Macros (JKL) | 1956. If the fractional scattered energy (relative to the incident ray) drops below c (defaulted to 1E-12), the scattered rayis not generated.7. Normally, scattered rays are not generated for any of the specular child rays, only the parent. If ALL is specified,scattered rays are generated for each specular child ray (including multiple diffraction orders, extraordinary rays,etc.), so that "bi-directional" scatter can occur at a partially reflecting/transmitting interface.8. Sets the default refraction/reflection controls for all objects or may be applied only to a specific object.LEVEL ExamplesLIGHTS (<strong>ASAP</strong> Command)Sets up optional light sources for the RENDER command.Function• Setup Plots and Verify SystemSyntaxLIGHTS e a,b,c [ e' a',b',c' [ e" ... ] ]-e x y z -e' x y z -e"OptionDescriptione, e', ... Relative irradiance of the collimated beamsa,b,c a',b',c' ...-e, -e', ...x y z, x' y' z', ...RemarksDirection of propagation of the collimated beamsIsotropic point sourcesLocation of the point sources1. Sets up optional light sources (up to 10) for the RENDER command.2. If e is positive, it is the relative irradiance of the collimated beam, and a,b,c are its direction of propagation.3. If e is negative, the light is an isotropic point source at x y z.4. The addition of these light sources can significantly increase the time it takes to render a scene, because <strong>ASAP</strong>must check for obscurations along the path of the light sources.LIGHTS ExamplesLIMITS (<strong>ASAP</strong> Command)Assigns a global bounding box to the object.Function• Create/Modify ObjectsSyntax 1- Long formatLIMITS x x' [ y y' z z' ] [ X [ f ] ]YZSHORTESTLONGEST

<strong>ASAP</strong> | Commands and Macros (JKL) | 196NORMALSyntax 2- Short formatLIMITS [ OFF ]REPEAT i [ X [ f ] ]STATS YAXIS Z-X x SHORTEST-Y y LONGEST-Z z NORMAL+X x' OFF+Y y'+Z z'EXPAND rX rYZOptionx x'y y'z z'DescriptionX, Y, or Z Coordinate directionSHORTESTLONGESTNORMALOFFfLIMITS OFFREPEAT iSTATSAXISMinimum and maximum extent in the global x directionMinimum and maximum extent in the global y directionMinimum and maximum extent in the global z directionCoordinate axis determined by shortest limit boxdimensionCoordinate axis determined by longest limit boxdimensionCoordinate axis determined by coordinate directionnearest to the surface normalMakes limits a rectangular box nearest surface normalFractional height of inner boundary (default=0)Temporarily turn off future limits checkingCopies/repeats the limits box from object iResets the limits box according to the previous TRACESTATS commandResets the limits axis-X x, -Y y, -Z z ... Specifies the specific bounding box sideEXPANDrRemarksScales the limits boxRelative scale factor1. The minimum and maximum extents are defined in global coordinates.2. If the coordinate direction is not entered, the object is constrained by a rectangular box whose endpoints are givenby the minimum and maximum extent.

<strong>ASAP</strong> | Commands and Macros (JKL) | 1973. If the coordinate direction is entered, the object is constrained by a cylinder with a constant elliptical cross-sectionin planes perpendicular to the given coordinate.4. The optional inner boundary of fractional height f (default is zero) may be used to put a proportional hole in theobject in the coordinate direction. If f is negative, the proportional hole is rectangular.5. The LIMITS command can be used for very simple bounding of an object. For more sophisticated surfaceboundaries, BOUND surfaces can also be employed.6. The short format can be used to: turn OFF future limits checking temporarily, set the limits on the current objectto those of a previous object I. Use the ranges of ray intersections found from the previous TRACE STATScommand, or reset the limits AXIS, or just one of the six limits values.7. EXPAND can be used to enlarge (or shrink) by a relative amount r the entire limits box or just in one direction,that is, EXPAND -.1 shrinks the entire box by 10 percent and EXPAND X .1 enlarges the limit box by 10percent in the X direction.8. Any linear transformation commands that follow an object definition are applied to the object surface and allboundary surfaces, that is, the entire object. The coordinate ranges entered with the LIMITS command are alsoadjusted so that the object lies entirely in a new 3D orthogonal box. Therefore, the shape of the object can changewith a ROTATE or SKEW if only the LIMITS are used to bound it. To avoid this, use a LOCAL box on the baseSURFACE of the object.LIMITS ExamplesLINE (<strong>ASAP</strong> Command)Creates a line edge.Function• Define/Modify Curvedge EntitiesSyntaxLINE x y z x' y' z' [ n ] [ DASHED ]Optionx y zx' y' z'nDASHEDDescriptionLine starting coordinatesLine ending coordinatesNumber of connected segments (default is 1 or valuespecified on previous LINE command)Disconnects every other segment of the line (open)Remarks1. Creates a straight line from the first point to the second point that is equally divided into n connected segments.2. The default value for n is 1 or value specified on the previous LINE command. Use -n if you want it to becomethe default for future LINE commands.3. If the DASHED option is used, then every other segment of the line is open (not connected).LINE ExamplesLIST (<strong>ASAP</strong> Command)Lists currently selected ray data by the second literal entry for the current ray set.

<strong>ASAP</strong> | Commands and Macros (JKL) | 198Function• Analyze Ray/Beam DataSyntax 1LIST POSITION [ k ]DIRECTIONSOURCESSyntax 2LIST SOURCE POLYCHROMATICOptionPOSITIONkDIRECTIONSOURCESDescriptionLists ray positions, fluxes, current objects, and opticalpath lengthsRay number whose coordinates and optical path lengthare subtracted from each ray before they are listedLists ray directions, fluxes, current objects, and opticalpath lengthsLists wavelength and ray numbers for each sourceRemarks1. Lists the specified ray data for POSITION, DIRECTION, or SOURCES. By default, the positions or directions ofeach base ray are used.2. All rays are listed. To select a subset of rays to be listed, the CONSIDER and SELECT commands should be used.3. The SOURCES option lists the wavelength and range of ray numbers for each currently defined source.4. Syntax 2: LIST SOURCE POLYCHROMATIC lists the wavelength range and the ray number range for allcurrently defined polychromatic sources.LIST ExamplesLIST ELLIPSE (<strong>ASAP</strong> Command)Lists polarization parameters of currently selected ray data.Function• Analyze Ray/Beam DataSyntaxLIST ELLIPSERemarks1. If FRESNEL BOTH is set, prints the major axis orientation (in global coordinates), the ellipticity, and handednessof the polarization ellipse.2. The major axis orientation is printed out in global coordinates. The ellipticity ratio is the ratio of the minor tomajor axis of the polarization ellipses. A purely linear state has a ratio of zero, and a purely circular state has aratio of 1. The sign of the ellipticity determines the handedness of the polarization ellipse.LIST ELLIPSE Examples

<strong>ASAP</strong> | Commands and Macros (JKL) | 199LIST INTEGER (<strong>ASAP</strong> Command)Lists ray database information.Function• Analyze Ray/Beam DataSyntaxLIST INTEGERRemarks1. Creates a list containing the current medium, split level, source number, number of objects, current object andprevious starting objects for each ray in the VIRTUAL.PGS file.2. To reduce the amount of output, <strong>ASAP</strong> only lists the break points where the integer data changes from one ray tothe next.LIST INTEGER ExamplesLIST (Parabasal Ray Data) (<strong>ASAP</strong> Command)Lists currently selected base and parabasal ray data.Function• Analyze Ray/Beam DataSyntaxLIST P#D#Remarks1. Creates a list of the ray data specified by the given option for the current ray set.2. Any particular parabasal ray may be selected by specifying its number (#). For example, P0 indicates base rayposition; D1 indicates first parabasal ray direction, and so on.3. If an S is used for #, PS, or DS, the differences between the base ray and all the parabasal rays are also listed.4. The flux, size, and optical path length of each beam are listed along with the coordinate data.5. The CONSIDER and SELECT commands can be used to restrict the list to rays that are currently on certainobjects.LIST ExamplesLIST RAYS (<strong>ASAP</strong> Command)Lists ray data in EMITTING RAYS format.Function• Analyze Ray/Beam DataSyntax 1 - Non-polarizedLIST RAYS

<strong>ASAP</strong> | Commands and Macros (JKL) | 200Syntax 2 - PolarizedLIST RAYS [POLARIZATION] [JONES|STOKES] WOptionPOLARIZATIONJONES|STOKESWDescriptionLists polarization states of the current ray set if the rayscarry polarization state information.Lists the polarization state in a particular form. JONESrepresents Jones vector form, and STOKES representsStokes vector form.WavelengthRemarks1. LISTs the direction (A, B, C), position (X, Y, Z), flux (F), size (S), and divergence (D) of each ray/beam in aformat compatible with the input to the EMITTING RAYS command. Size and divergence information shouldonly be used with coherent beams.2. Can print in local or global coordinate system, as in LIST DIRECTION or POSITION commands (controlled byAXIS command).3. When a POLARIZATION option is present, additionally includes polarization reference X direction (RXA, RXB,RXC) in direction cosine coordinates.4. When the POLARIZATION JONES option (the default when POLARIZATION keyword is used withoutadditional options) is present, appends the Jones vector components in the reference direction coordinates, JXR (Xreal), JXI (X imaginary), JYR (Y real), and JYI (Y imaginary), after the reference direction items.5. When the POLARIZATION STOKES option is present, appends the Stokes vector components S0, S1, S2, S3after the reference direction items.6. When the POLARIZATION option is present, the wavelength, W, is the last entry.Note: When polarization is being traced in Stokes mode, by using the command POLARIZ MODE STOKESas a system setting, the data cannot be converted to JONES form. When using the Jones mode via settingPOLARIZ MODE JONES, either form is available.LIST RAYS Examples$LOC (<strong>ASAP</strong> Macro)Makes the given registers/variables names local to the current macro.Syntax$LOC reg [ reg’ reg" ... ]Remarks1. On exit from the macro, the values of these registers are automatically restored to their values previous to the$LOC macro.2. MY_MACRO does not (permanently) change the values of the registers A, B, and C when it is called.ExampleMY_MACRO {$LOC A,B,CA=#1 B=#2 C=#3

<strong>ASAP</strong> | Commands and Macros (JKL) | 201:}$LOC ExamplesLOCAL (<strong>ASAP</strong> Command)Assigns a local bounding box to the surface/function.Function• Define/Modify Surfunc EntitiesSyntax 1LOCAL x x' [ y y' z z' ] [ X [ f ] ]YZSHORTESTLONGESTNORMALSyntax 2: Overriding Syntax (temporarily changes the main syntax):LOCAL [ OFF ]REPEAT i [ X [ f ] ]STATS YAXISZ-X x SHORTEST-Y y LONGEST-Z z NORMAL+X x' OFF+Y y'+Z z'EXPAND rX rYZOptionx x', y y', or z z'DescriptionX, Y or Z Coordinate axisfSHORTESTLONGESTNORMALOFFMinimum and maximum extents in the given directionOptional inner boundary of fractional height (default is0)Coordinate axis determined by shortest limit boxdimensionCoordinate axis determined by longest limit boxdimensionCoordinate axis determined by coordinate directionMakes local box a rectangular box nearest surfacenormal

<strong>ASAP</strong> | Commands and Macros (JKL) | 202OptionREPEAT iSTATSAXIS-X, -Y, -Z, +X, +Y, or +ZrDescriptionCopies/repeats the local box from surface iResets the local box according to the previous TRACESTATS commandResets the local box axisSpecifies the specific bounding box sideRelative scale factorRemarks1. Assigns a local bounding box to the previous surface/function. The previous surface can be simply bounded by thespecification of allowable ranges on each of the current coordinates. The unprimed entries are the lower bounds,and primed entries are the upper.2. The optional form of the command allows you to specifically override or reset any quantity of the local box. Foradditional functionality, use this form of the command.3. The minimum and maximum extents are defined in local coordinates.4. If the coordinate direction is not entered, the surface is constrained by a rectangular box whose endpoints aregiven by the minimum and maximum extents.5. If the coordinate direction is entered, the surface is constrained by a cylinder with a constant elliptical crosssectionin planes perpendicular to the given coordinate.6. The SHORTEST limit box dimension, the LONGEST, or the coordinate direction nearest to the surface NORMALcan also determine the axis.7. An optional inner boundary of fractional height f [default is zero] can be used to put a proportional hole in thesurface in the given coordinate direction. If f is negative, the proportional hole is rectangular.8. LOCAL OFF temporarily turns off future limits checking.9. The REPEAT option sets the limits on the current surface to those of a previous surface i.10. The STATS option sets the ranges of ray intersections found from the previous TRACE STATS command(assuming an AXIS LOCAL command is in effect).11. The optional form can also be used to reset the limits AXIS or just one of the six limits values.12. The EXPAND option can be used to enlarge (or shrink) by a relative amount r the entire limits box or just in onedirection; for example, EXPAND -.1 shrinks the entire box by 10%.13. After a LOCAL command, any linear transformation command is applied to the surface's local-to-globaltransformation matrix and not to the surface coefficients themselves.14. The LOCAL command can be used for simple bounding of a surface/function. For more sophisticated boundaries,BOUNDS may be applied to surfaces for more complex boundaries.15. Certain surfaces/functions are self-bounding (ELLIPSOID and TORUS, for example) if you use the entire surface/function. To use only a portion of these surfaces, use the LOCAL command. The LOCAL command creates arectangular or cylindrical box around the surface, effectively defining its physical dimension. The LOCAL box iscentered on the surface's reference point. The reference points of surfaces are as follows:SurfacePLANEOPTICALELLIPSOIDTORUSTUBE<strong>Reference</strong> PointAt intersection of surface and coordinate axisAt intersection of surface and coordinate axisAt center of ellipsoidAt center of torusDependent on sign of symmetric axis qualifierIf unsigned: midpoint of tube+

<strong>ASAP</strong> | Commands and Macros (JKL) | 203Surface<strong>Reference</strong> PointX, +Y, +Z: positive end of tube-X, -Y, -Z: negative end of tubeLOCAL ExamplesLSQFIT (<strong>ASAP</strong> Command)Controls the singular value decomposition least squares fitting algorithm.Function• Save or Recover System Data and Control ExecutionSyntaxLSQFIT [ t ] [ LIST ] [ NORM ]OFFOptiontLISTNORMOFFDescriptionSingular value threshold (default 3.E-5)Option to print fit parametersNormalizes variables prior to fitDoes not normalize variables prior to fitRemarks1. Controls the Singular Value Decomposition (SVD) algorithm used by any of the commands that do a least squaresfit. The LSQFIT command must be issued prior to that command.2. Any singular values that are t (default 3.E-5) times less than the maximum are removed.3. If the LIST option is present, the singular values, variable values, and fit errors are printed.4. Sometimes, an improved fit is obtained if the variables are first NORMalized. OFF sets both these options to theirdefault states.LSQFIT Examples

<strong>ASAP</strong> | Commands and Macros (M) | 204Commands and Macros (M)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “M”.MANGIN (<strong>ASAP</strong> Command)Creates a Mangin mirror.Function• Define/Modify Lens EntitiesSyntaxMANGIN X x t h m [ RD r r' ]Y yCV c c'Z z FL f b [ a ]a APLANATOptionX Y or Zx y or zthmfbc c'r r'RDCVFLAPLANATaDescriptionGlobal coordinate axisLocation on the global coordinate axisLens thicknessAperture heightInternal medium (number or name)Focal lengthBending parameterCurvatures of the two surfacesRadii of curvature of the two surfacesSurfaces defined by radius valuesSurfaces defined by curvature valuesSurfaces defined by focal length and bending parameterBending factor and one conic constant are automaticallycalculatedConjugate factorRemarks1. A Mangin mirror is a lens with a reflective second conicoid; rays are refracted twice at the first conicoid.2. The format of this command is identical to that of the SINGLET, except that the second surface is reflective; thatis, rays are refracted twice at the first surface. The following remarks are the same for the SINGLET.3. This lens entity starts out normal to the defined global coordinate axis (X, Y or Z).4. RD is used to specify radii of curvature (r r'), CV is used to specify curvatures (c c'), and FL is used to specifyfocal length f and bending parameter b.

<strong>ASAP</strong> | Commands and Macros (M) | 2055. The bending parameter b is defined as (c+c')/(c-c') or, equivalently, as (r'+r)/(r'-r); therefore, b=0 implies abiconvex or biconcave element; b=-1 implies a plano-convex or plano-concave element; and b=1 implies aconvex-plano or concave-plano element.6. a is an optional conjugate factor; that is, one plus the object-to-image magnification divided by one minus themagnification (0=one-to-one imaging, 1=infinite object distance, -1=infinite image distance)7. If the APLANAT option is used, the bending factor is automatically determined for the given a so that third-ordercoma is also eliminated (assuming the thin lens approximation applies).MANGIN ExamplesMAP (<strong>ASAP</strong> Command)Produces a depth map of the currently defined object surfaces.Function• Setup Plots and Verify SystemSyntaxMAP [ name ] [ DEPTH [ d' [ d"] ] ] [ SLOPES ]Optionnamed' d"SLOPESDEPTHDescriptionName of the distribution data file (default extension*.dis)Range of the third coordinate (the one different than thetwo specified on the most recent WINDOW command)Flag to compute surface derivative data; see examplebelow for optional parametersValue of map depthRemarks1. Produces a depth map of the current object surfaces using the last WINDOW and PIXEL settings.2. The map is saved to user-named distribution data file name.dis (otherwise, the data is stored in BRO009.DAT) forlater processing and can optionally contain not only the depth value but also the two SLOPES at each scan point.This file may be examined using the DISPLAY command.3. If the actual range of depth values (d' to "d are not given, they are automatically calculated from the current objectgeometry (and reversed if a DEPTH option is present, but without any numerical entries).4. If SLOPES is present, <strong>ASAP</strong> also computes and saves the slopes (derivatives) of the surface at each scan point aswell. See the examples below.Examples for MAP and DISPLAYTo map the surface of an object and save it to a file, specify a WINDOW and PIXEL resolution, and then enter:MAP REF_MAP SLOPESData is now in the file, REF_MAP.dis. However, SLOPES creates three sets of data for each pixel in the windowspecified: one matrix of Height data, one matrix of the slopes with respect to the first window coordinate, and onematrix of slopes for the second window coordinate. The DISPLAY command with the file name REF_MAP alonewould bring in only the first matrix. To read in a particular matrix for viewing or saving to a file, enter one or all ofthe following:

<strong>ASAP</strong> | Commands and Macros (M) | 206DISPLAY REF_MAP 1ST !! Reads in the height values for the entire pixelmatrixDISPLAY REF_MAP 2ND !! Reads in the first window coordinate slope values forall pixels (for example, X values for WIN X Y)DISPLAY REF_MAP 3RD !! Reads in the second window coordinate values for allpixels (for example, Y values for WIN X Y)After each of the above lines, data may be reviewed in the Command Output window, or saved to a separate file usingthe WRITE command.MAP ExamplesMATRIX (<strong>ASAP</strong> Command)Specifies the general transformation matrix that operates on a surface.Function• Create/Modify Objects• Define/Modify Curvedge Entities• Define/Modify Lens Entities• Define/Modify Surfunc Entities• Modify Ray/Beam DataSyntax 1MATRIXx a b cy a' b' c'z a" b" c" [ LIST ]Syntax 2:MATRIX [ PREVIOUS ] [ LIST ]INVERSEk-kOptionx y za b c, a' b' c', a" b" c"DescriptionTranslation vectorRotation submatrixk, -k Specifies the rotation matrix specified with entity k, and–k specifies the inverse of the rotation matrix specifiedwith entity k.LISTPREVIOUSINVERSERemarksDecodes transformation matrix into single operation (ifpossible) and printsUses previously defined transformation matrixUses inverse of previously defined transformation matrix

<strong>ASAP</strong> | Commands and Macros (M) | 2071. Specify a 3x4 (first dummy row excluded) transformation matrix directly.2. MATRIX PREVIOUS or INVERSE allows you to reuse the transformation matrix from the previous entity, itsinverse, or the matrix of SURFACE entity k (use zero for inverse of the SURFACE entity currently beingtransformed).3. Another form of the matrix command recalls either the PREVIOUSly used matrix, its INVERSE or the matrix ofSURFACE entity k (use -k for inverse, 0 for inverse of entity currently being transformed).4. When used with REPEAT, group MATRIX with these commands: ROTATE; SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQ.MATRIX ExamplesMEDIA (<strong>ASAP</strong> Command)Creates a single refractive material.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax 1MEDIA [ m ] n [ n' n" ... ] [ options ... ] [ 'name' ]catalog_glass …:Syntax 2MEDIAcatalog_glass 'alias'Syntax 3 - CONRADYMEDIACONRADY w1 w2 a b c [ABSORB] 'name'[ (k) 1 ...(k) N ]Syntax 4 - SCHOTTMEDIASCHOTT w1 w2 a b c d e f g h [ABSORB] 'name'[ (k) 1 ...(k) N ]Syntax 5 - HERZBERGERMEDIAHERZBERGER w1 w2 a b c d e f [ABSORB] 'name'[ (k) 1 ...(k) N ]Syntax 6 - SELLMEIERMEDIASELLMEIER w1 w2 b1 c1 b2 c2 b3 c3 b4 c4 [ABSORB] 'name'

<strong>ASAP</strong> | Commands and Macros (M) | 208[ (k) 1 ...(k) N ]Optionmn n' n" ...options ...namecatalog_glassDescriptionStarting media numberReal (or complex) refractive indices...ABSORB, ...CRYSTAL, ...GRIN, or...SCATTER command argumentsDescriptive name that can be assigned to this medium(only the first 24 characters after the comment delimiterare stored)Name of a catalog materialw1, w2 The lower and upper limits of the domain of validwavelengths, in microns; see Remarks - Syntax 3, 4, 5,and 6a,b,c...Coefficient parameters (CONRADY, HERZBERGER,SCHOTT, and SELLMEIER)k Imaginary parts of the refractive index; see Remarks -Syntax 3, 4, 5, and 6Remarks - All Syntax1. All model coefficients for the real part of the refractive index are required, and any may be set to zero if notneeded.2. See the topic, "MEDIA Command Coefficients" for specific formulas.3. As with media found in the glass catalog, MEDIA defined with dispersion formulas are tabulated at theWAVELENGTH values currently in effect, and indices at intermediate wavelengths are approximated with linearinterpolation. If no wavelength is defined in the context of the MEDIA command, the yellow helium (FraunhoferD3) line is assumed and dispersion is neglected.Note: Subsequent Remarks are categorized by specific syntax.Remarks - Syntax 1, MEDIA1. Starting with medium m, define media with real (or complex) refractive indices n, or from its literal designationin a glass catalog (for example, SCHOTT_BK7). Optionally, separate indices can be entered (or computed) thatcorrespond to the wavelengths entered on the last multiple WAVELENGTHS command.2. The default value of m is one more than the largest medium number defined, and is set to 1 at the start of programrun.3. If specifying more than one of the options, make the step size and the maximum number of steps the same foreach option. the related command topics (see list of related MEDIA commands under "Related information").4. The name of the medium is delimited by single quotes, and is is limited to 24 characters. Longer names areaccepted; however, only the first 24 characters are used.Remarks - Syntax 2, MEDIA1. The second syntax for MEDIA allows the assignment of a convenient alias to a material in the supplied mediacatalog. This can be used, for example, to quickly substitute glasses (or other catalog materials) by applying thealias to multiple INTERFACE definitions and changing only the material referenced by the alias.Remarks - Syntax 3, 4, 5, and 6, CONRADY, HERZBERG, SCHOTT, and SELLMEIER1. Supports direct input of CONRADY, HERZBERGER, SCHOTT, and SELLMEIER coefficients to define materialindex of refraction over a specified wavelength range. Equations are provided with each syntax for each dispersionformula.

<strong>ASAP</strong> | Commands and Macros (M) | 2092. The keyword ABSORB is optional for media defined with dispersion formulae. If this keyword is present, the nextline must define the imaginary parts k of the refractive index at each of the N wavelengths currently set with themost recently executed WAVELENGTHS command.3. Each medium can have a different interpolation WAVELENGTH. Separate indices can be entered (or computed)that correspond to the wavelengths entered on the last multiple WAVELENGTHS command. <strong>ASAP</strong> interpolates toget the refractive index at any desired wavelength.4. Linear interpolation is performed, if necessary, to compute a refractive index at a particular wavelength. Theinterpolated values are then used to calculate absorption coefficients (for complex indices).5. More than one of the options (ABSORB, CRYSTAL, GRIN, or SCATTER command arguments) may be used in asingle MEDIA command; for example, as in MEDIA ABSORB. The parameters associated with these options arediscussed in the related command topics (see list of commands under "Related information").6. Options w1 and w2 represent, respectively, the lower and upper limits of the domain of valid wavelengths, inmicrons. For wavelengths outside the range of validity, <strong>ASAP</strong> uses a strongly absorbing refractive index of 1+i.7. The name of the medium is delimited by single quotes, and is is limited to 24 characters. Longer names areaccepted; however, only the first 24 characters are used.8. The N values of k are the imaginary parts of the refractive indices at the N values of WAVELENGTHS in effectwhen the MEDIA command is issued. In other words, the number of k values must match the number ofWAVELENGTHS values.MEDIA ExamplesMEDIA Command CoefficientsThis topic provides coefficient formulas for the MEDIA command.Note: Each of the following media formulas (CONRADY, HERZBERGER, SCHOTT, and SELLMEIER)assumes wavelengths in microns; therefore, the coefficients must be entered in appropriately scaled units.CONRADY CoefficientSCHOTT CoefficientHERZBERGER Coefficient

<strong>ASAP</strong> | Commands and Macros (M) | 210SELLMEIER CoefficientMEDIA ABSORB (<strong>ASAP</strong> Command)Creates an absorbing refractive material.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxMEDIA [ m ]n [ n' n" ... ] ABSORB a [ j q t [ l ] [ 'name' ]:Optionmn n' n" ...ajqtlnameDescriptionStarting media numberReal (or complex) refractive indicesAbsorption (or gain) coefficient (inverse length units);positive for an absorbing medium or negative for a gain(lasing) mediumSURFACE designation for a inhomogeneous ABSORBfunctionExponent of inhomogeneous ABSORB functionStep length to be used during ray trace in aninhomogeneous mediumMaximum number of ray steps in medium; default is1000Descriptive name that can be assigned to this medium.(The name of the medium is delimited by single quotes,and is limited to 24 characters.)Remarks1. ABSORB identifies the medium as a general absorbing one.2. Refractive indices for dispersive materials must be entered in the order indicated by the previous WAVELENGTHScommand.3. If only real refractive index data are entered and a non-zero value is not given for a, the absorption is set to zero.4. If complex refractive index data are entered and a is not specified, <strong>ASAP</strong> calculates a (the absorption coefficient)from the wavelength and the imaginary part of the complex refractive index nk as follows. Given:

<strong>ASAP</strong> | Commands and Macros (M) | 211The meaning of the absorption coefficient a is given byIn this equation, I is the intensity of a plane-wave at a propagation distance L in the medium, when the intensityon entering the medium isSee the Example below.5. To handle inhomogeneous absorption or gain, assign the medium a GENERAL polynomial function in globalcoordinates (X,Y,Z). The magnitude of j is the SURFACE designation for this function.The absorption coefficient a at each point in the medium is then given by:6. Linear interpolation is performed, if necessary, to compute a refractive index at a particular wavelength. Theinterpolated values are then used to calculate absorption coefficients (for complex indices).ExampleConsider aluminum with n^ = 1.44 + i5.23:You can enter this in <strong>ASAP</strong> using either of two forms:UNITS MICRONSWAVELENGTH 0.589N=1.44NK=5.23K=NK/NALPHA=4*3.14*NK/0.589!! REAL PART OF INDEX!! IMAGINARY PART OF INDEX!! ATTENUATION INDEX KAPPA!! ABSORPTION COEFFICIENT AT 589 NANOMETERSMEDIA(N)`(NK) 'ALUMINUM_1'!! 1ST FORM(N) ABSORB (ALPHA) 'ALUMINUM_2' !! 2ND FORMRETURNThese two definitions are equivalent in the example given, in which only a single wavelength is present. The secondform, using ABSORB, is independent of wavelength. The first form becomes wavelength-dependent if dispersion dataare specified; that is, if multiple WAVELENGTHS are specified with corresponding complex refractive indices. In thelatter case, <strong>ASAP</strong> interpolates among the given indices to compute the complex index and the absorption coefficient.Note: <strong>ASAP</strong> does not impose the Kramers-Krönig relation upon refractive indices specified for multiplewavelengths; the indices need not be consistent with causality.MEDIA ExamplesMEDIA BIAXIAL (<strong>ASAP</strong> Command)This command creates a biaxial medium description, optionally used by BIC. As a dummy media that is referencedby the BIC command, MEDIA BIAXIAL does not define a bulk medium that can be applied directly to an objectinterface.Function• Create/Modify Media, Coatings, Scatter Models

<strong>ASAP</strong> | Commands and Macros (M) | 212Syntax 1MEDIA BIAXIALn1|media1, n2|media2, n3|media3 [‘new media name’]......OptionDescriptionn1, n2, n3 Principal refractive indices (see Remarks)media1, media2…new media nameRemarksMedia names (or media number) referencing definedexisting mediaName applied to the MEDIA BIAXIAL being defined.(The name of the medium is delimited by single quotes,and is limited to 24 characters.)1. Note: This media definition must not be used as a bulk media referenced directly in an INTERFACEcommand. It must be used only to define the refractive indices to be applied in a BIC (biaxial layer)command.2. For n1, n2, n3 options, users can alternatively reference the previously defined media by media ID or media name.The parameters n1, n2, n3 define the principal refractive indices of biaxial media, which are assigned with theBIC command.3. Since media may be defined directly by principal refractive index, or by a previously defined media name ormedia number, the inputs must avoid ambiguity between refractive indices and media numbers. An integer maybe assumed to be a media number, while a floating-point number with a decimal is assumed to be a refractiveindex value. Best practice is to use names if referencing previous media definitions, and floating-point numbersfor direct input of refractive index.4. If no name for the new biaxial media is supplied by users, <strong>ASAP</strong> uses a default name starting with BIAXIAL, andfollowed by the list index of this biaxial media in the system biaxial media list. For example, the 2nd biaxial mediais named as BIAXIAL00002.5. Users can define an unlimited number of biaxial media below the MEDIA BIAXIAL line. Users can also use theMEDIA BIAXIAL command many times.6. The defined biaxial media are kept in a linked list so they are not counted in the defined isotropic media created bythe simple MEDIA command. Biaxial media are counted in their own list, starting at 1.MEDIA CRYSTAL (<strong>ASAP</strong> Command)Defines birefringent media.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxMEDIA [ m ]n [ n' n" . . . ] CRYSTAL a,b,c [ m' ] [ 'name' ]:

<strong>ASAP</strong> | Commands and Macros (M) | 213Optionmn n' n" ...a,b,cm'nameDescriptionStarting media numberReal (or complex) refractive indicesOptical axis directionOrdinary index number or nameDescriptive name that can be assigned to this medium(only the first 24 characters after the comment delimiterare stored).Remarks1. The ordinary indices are specified on a previous medium m' (default is last media). For example, a calcite crystalwith its optical axis initially aligned with the Y-direction is defined as follows:MEDIA1.66 !!ordinary indices for following extraordinary1.49 CRYSTAL 0 1 0 'CALCITE'2. The above example is expressed in the following way when the ordinary index is not defined on the immediatelyprevious medium:MEDIA1.66 'ORDINARY' !!ORDINARY INDICES FOR FOLLOWING EXTRAORDINARY1.60 'GLASS'1.49 CRYSTAL 0 1 0 ORDINARY 'CALCITE'3. If SPLIT is one or higher, <strong>ASAP</strong> automatically generates an ordinary and extraordinary ray/beam at each crystalinterface.4. If you linearly transform an object assigned a birefringent MEDIA, the linear transformation is applied also to theoptical axis direction of the medium. Any other object using this medium is therefore affected.5. Refractive indices for dispersive materials must be entered in the order indicated by the previous WAVELENGTHScommand.6. Linear interpolation is performed, if necessary, to compute a refractive index at a particular wavelength.7. Accurately handles interface reflectivity/transmissivity values in the most common cases (for example,waveplates). However, the approximate (but fast) algorithm used can produce erroneous values for more exoticsituations. (The algorithm will be updated in a future release of <strong>ASAP</strong> to address this.)MEDIA ExamplesMEDIA GRIN (<strong>ASAP</strong> Command)Creates a GRIN refractive material.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxMEDIA [ m ]n [ n' n" . . . ] GRIN k p t [ l ] [ 'name' ]

<strong>ASAP</strong> | Commands and Macros (M) | 214:OptionmnkptlnameDescriptionStarting media numberReal (or complex) refractive indexGRIN function numberExponent of GRIN functionStep length to be used during ray trace in thisinhomogeneous mediumMaximum number of ray steps in medium; default is1000Descriptive name that can be assigned to this medium(The name of the medium is delimited by single quotes,and is limited to 24 characters.)Remarks1. GRIN specifies that the medium consists of Gradient index (GRIN) materials. The square of the refractive index isgiven by:whereis a general polynomial function andis the refractive index entered on the MEDIA command. The technique for modeling dispersive gradients is todefine a separate GRIN function for each WAVELENGTH and to update the object data between individual raytraces.2. The k refers to the SURFACE/FUNCTION that defines the index variation.3. If the constant coefficient of the functionis unity, the refractive indices entered after the MEDIA command correspond to those at the function's referencepoint.4. The GRIN function is defined in global coordinates. This is of little consequence if the gradients are radial (thereis no position dependence along the axis), but if the desired gradient is axial, you may have to SHIFT the gradientto the correct global coordinates to align the gradient with the object.5. The function can be ARRAYed.6. You may need to adjust the HALT and/or CUTOFF values to account for step length and maximum number of raysteps.

<strong>ASAP</strong> | Commands and Macros (M) | 215MEDIA ExamplesMEDIA SCATTER (<strong>ASAP</strong> Command)Assigns to medium a GENERAL polynomial or USERFUNC function in the global coordinates X, Y, Z.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxMEDIA [ i ]n [ n' n" . . . ] SCATTER m [ k e t [ l ] ] 'name':OptioniSCATTERmketlnameDescriptionStarting media numberAllows specification of the maximum number ofscattering events per ray for all volumetric models,including homogeneous models expressed by the shortform. The maximum number of scattering events per raydefaults to 1000 if l is not specified.Refers to a VOLUME scattering MODELIts magnitude is the SURFACE designation for thisfunctionExponent of the scattering functionStep length used for tracing a ray when tracing a ray inthis inhomogeneous mediumMaximum number of ray steps in mediumDescriptive name that can be assigned to this medium(The name of the medium is delimited by single quotes,and is limited to 24 characters.)Remarks1. The medium is homogeneously scattering by default.2. The medium is inhomogeneously scattering if a SURFACE k is specified, which has the effect of multiplying thehomogeneous scattering model m by the modified SURFACE function.3. The SURFACE function k, if specified, must be greater than zero at all points in regions characterized by mediumi.4. Rays that require more than l scattering event or more than LEVEL scattering events do not escape from thevolumetric scatterer, and are reported (by STATS) as attached to the last surface intersected. Setting l larger thanLEVELS has no effect.MEDIA Examples

<strong>ASAP</strong> | Commands and Macros (M) | 216$MENU (<strong>ASAP</strong> Macro)Displays a menu of currently defined macros for selection.Syntax$MENU [ m ] [ 'title' ]&MENURemarks1. Displays a menu of current macro library names (and any descriptions found on the definition line). Make aselection by selecting the name of the desired macro and clicking OK.2. The menu entries are displayed horizontally in columns by default. The m is the maximum number of columns touse (default 6). For example, entering a 1 would force the menu entries into one vertical column.$MENU ExamplesMESH (<strong>ASAP</strong> Command)Creates a 3D representation of the distribution in the system vector (*.VCR) file.Function• Display/Modify Data DistributionsSyntaxMESH [ i [ j ] ] [ LOW ]HIGHOptionijDescriptionLine across specificationLine down specificationRemarks1. Writes a three-dimensional representation (wireframe or LOW / HIGH-resolution shaded "surfaces") of thedistribution into the 3D system vector file so that it can be REPLOTted with other geometrical entities.2. If given, only every ith line across or jth line down is written (defaults are 1).MESH ExamplesMICROSTRUCTURE (<strong>ASAP</strong> Command)Creates a replicated microstructure scattering geometry/object.Function• Object CreationSyntax 1MICROSTRUCTURE X e j1 j2 j3 … [ SCALE SFAC ] [ PITCH PITFUNCX PITFUNCY ]

<strong>ASAP</strong> | Commands and Macros (M) | 217Syntax 2MICROSTRUCTURE D a b c, e j1 j2 j3 … [ SCALE SFAC ] [ PITCH PITFUNCXPITFUNCY ]OptionXSCALESFACPITCHPITFUNCX, PITFUNCYDa,b,ceDescription<strong>Reference</strong> direction used to determine the localconformal coordinate system at any given point on thesurface. The reference direction is used in conjunctionwith the surface normal at the point to determine thelocal surface axes. It can be one of the nine choices: X,Y, Z, U, V, W, R, T, A.Varies (scales) the microstructure size with positionName of $FCN used to apply scaling factorVaries spatial period of the microstructureName of user-defined functions to vary the spacing inlocal x and y directionsAllows you to explicitly define an arbitrary referencedirection.Vector components of the reference direction in globalcoordinates.Entity number of the rectangular edge that defines thedimensions of a unit cell.j1, j2, j3… Objects that collectively define the unit cell withinthe dimensions of the rectangular edge e. Absolute orrelative referrencing or object names may be used.Remarks1. Modeling a microstructure in <strong>ASAP</strong> begins by defining the size, geometry, and optical properties of a unit cell. Arectangular edge defines the boundary and size of the unit cell. The edge must be normal to the z axis and centeredon origin.2. Syntax 2 is for rendering microstructures. If used, <strong>ASAP</strong> renders one unit cell at the center of each facet in theobject, as defined with the object modifier FACETS n m. See the following example.OBJECT0.1 'PLATE'FACETS 11 11SCATTER MODEL 1The size of a rendered unit cell bears no relation to the actual size of the microstructure. The rendering is onlya graphical representation of the shape and orientation of the unit cells that define the microstructure. Unit cellrenderings are automatically scaled to fit within the shortest dimension of each facet. You can see the unit cellsonly by using the 3D Viewer ($VIEW).3. A microstructure is represented as a two-dimensional replication of a unit cell. For curved surfaces, a conformalcoordinate system with local x and y axis directions at every point on the surface is used to repeat the unit cellover the whole surface.

<strong>ASAP</strong> | Commands and Macros (M) | 2184. Unit-cell geometry is defined with surface and edge (curve) objects. Lens entities may not be used to define theobjects in a unit cell. Assign interface and scatter properties to objects in the unit cell in the usual way.5. The interior of the unit cell must not have gaps through which rays can pass without intersecting anything, and theobjects within the unit cell should fill, but not overfill, the boundaries of the unit cell as defined by the rectangularedge of the unit cell.6. An array of unit cells should not have gaps at the boundaries of the unit cell.7. Unit cells must avoid coincident surfaces when they are arrayed.8. Note: Although a microstructure is defined in <strong>ASAP</strong> by adding an <strong>ASAP</strong> scatter model, a microstructureis not modeled as an effective BRDF (bidirectional reflectance distribution function).9. A microstructure is applied to an object/surface in the same way as any scatter model: call out an object with theOBJECT command and append a SCATTER MODEL command below it:OBJECT 'object_name'SCATTER MODEL mwhere m is the number of the microstructure model.10. A microstructure must be applied to the correct side of the surface. The side of any <strong>ASAP</strong> surface is related tothe surface normal at the points of the surface. For surface-based entities, the direction of the surface normalis documented under the Surface Normal heading in <strong>ASAP</strong> Help for each entity. For many edge- or curvebasedentities, the normal direction depends upon how the edges are joined together to form an object. Forthese objects the simplest way to identify the positive side may be to put rays on them with the EMITTINGOBJECT command, and then render the object and rays with PLOT FACETS OVERLAY followed by a SPOTSPOSITION command. By viewing the rendering in the <strong>ASAP</strong> 3D viewer ($VIEW command), the spots on thepositive side of the surface are displayed. If the opposite orientation for the unit cell is desired, flip over the unitcell itself.MICROSTRUCTURE ExamplesMINIMIZE (<strong>ASAP</strong> Command)Minimizes the RMS spot size or the average of the previously specified fields, weighted by the w's.Function• Define/Modify Lens EntitiesSyntaxMINIMIZE [ w w'...] [ control c ] [ control c' ] ...RemarksControl Default DescriptionDIST 1 (100%) Maximum allowed fractional spotcentroiddistortionGLTH 0 Minimum center and/or edge glassthicknessinfiniteMaximum center and/or edge glassthicknessTLEN infinite Maximum total system length (firstto last conicoid)1 Optional starting conicoid

<strong>ASAP</strong> | Commands and Macros (M) | 219Control Default DescriptionlastOptional ending conicoidSDIA infinite Maximum unvignetted semidiameterof a conicoid set1 Optional starting conicoidlastOptional ending conicoidBKFD 0 Minimum back focal distance (lastconicoid to focus)BKWD -Infinite Minimum back working distanceUBAR 1 Maximum magnitude of final chiefray slopeIf the image quality of a design does not get better during an optimization, it is usually due to conflicting constraintviolations or constraint violations not affected by the specified variables.1. Normal optimization controls:Control Default DescriptionMULT 1 (local) Number of multiple trial solutions(large for global)SEED 987654321 Random (large odd integer) orquasi-random (zero) seedTARG 1.E-9 Take first solution that drops belowthis RMS spot size2. Advanced optimization controls:Control Default DescriptionTOLR .0001 Fractional change in merit functionat local minimaDELV .001-1 Maximum allowable randomizationof normalized variablesITER 10 Maximum number of iterations perlocal optimizationThese advanced controls are automatically determined by the MULTIPLE value and the number of variables. Inrare circumstances, they may have to be set explicitly.3. The underlying design engine actually has a comprehensive "pickup" (a conicoid variable is constrained to followone at a previous conicoid), and "paraxial solve" (a conicoid variable is determined from paraxial ray-tracerequirements) capability. These are currently hidden but are used in the following circumstances:• The focal length of the lens is always held by a paraxial marginal ray solve for the curvature of the "last"conicoid (not counting any image space plane parallel plates, such as windows of filters), and, sometimes, aprevious one coupled to it (see #3 and #5).• The nominal focal plane position is found from a paraxial marginal ray solve for the back focal distance thatresults in a zero ray height.• If the starting design is symmetric and only the conicoid parameters for the front half are varied, the lens willautomatically remain symmetric during optimization.

<strong>ASAP</strong> | Commands and Macros (M) | 220• If more than one element references the same glass and only the first instance of that glass is varied, all otherinstances follow automatically.• If an element is actually a reflector, where the surface before and after it are geometrically the same, andeven though, internally, two conicoids are used to represent the duplicate surface, the second instance willalways replicate any changes in the first. A Mangin back-surface mirror and a Maksutov telescope (wherethe secondary is an aluminized spot on the back of the meniscus corrector) are common examples of thiscondition.MINIMIZE ExamplesMINMAX (<strong>ASAP</strong> Command Argument)Sets BSDF (Bidirectional Scattering Distribution Function) bounding.Function• Standard Plot OptionsSyntax... MINMAX b b'Optionbb'DescriptionMinimum BSDF valueMaximum BSDF valueRemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. Limits the minimum and maximum attainable BSDF values for the commands used to specify scatter MODELS.3. This option can be used on any model definition and only applies to that particular model.MINMAX ExamplesMIRROR (<strong>ASAP</strong> Command)Creates a simple mirror.Function• Define/Modify Lens EntitiesSyntaxMIRROR X x h [ f k o ]Y yZ zOptionX Y or Zx y or zhDescriptionGlobal coordinate axisLocation on the global coordinate axisAperture height of mirror

<strong>ASAP</strong> | Commands and Macros (M) | 221OptionfkoDescriptionFocal length (zero for a flat)Conic constant (for example, 0=sphere, -1=parabola)Central hole ratioRemarks1. The focal length of a concave mirror is positive; the focal length of a convex mirror is negative.MIRROR ExamplesMISSED (<strong>ASAP</strong> Command)Sets how a missed ray is plotted.Function• Setup TraceSyntaxMISSED [ OFF ] [ d ]ARROWLINEOptionOFFdARROWLINEDescriptionDoes not draw missed rayDistance for extending rays in 3DDraws arrowDraws lineRemarks1. Determines what type of vector is drawn during ray plotting to indicate a missed ray. Normally, the missed raysare extended only to the edge of the 2D plotting window.2. 2D plots show missed rays out to the edge of plot as a convenience, but missed rays do not normally display in the3D Viewer.MISSED ExamplesMODEL (<strong>ASAP</strong> Command Argument)Scattering from anisotropic surfaces (for example, brushed, diamond-turned) is not rotationally symmetric at normalincidence, and is not necessarily symmetric about the plane of incidence.Syntax... model X ...YZU

<strong>ASAP</strong> | Commands and Macros (M) | 222VWRTA-X-Y-Z-U-V-W-R-T-A:where:EntryX Y ZU V WR T AAnisotropic AxisGlobal coordinate directionCURVE object parametric direction or local x,y,z ofSURFACE objectRadial, angular, or axial direction for LENS, SWEEPAXIS, or PARAMETERized/LOCALized SURFACEobjectRemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. The orientation of the model (such as BSDFDATA, HARVEY, VANES, USERBSDF) on the surface is important,and is generically specified by an axis for the second command entry.3. The local "Alpha" direction is perpendicular to the given axis and the surface normal. The "Beta" direction is thenperpendicular to the "Alpha" direction and the surface normal. The local direction cosines are the projections ofthe global direction vector onto the planes, as defined by these locally orthogonal directions.Direction Components MagnitudeScatter A, B see equation (1) (scatter angle fromnormal)Specular Ao, Bo see equation (2) (specular angle fromnormal)(1) (scatter angle from normal)(2) (specular angle from normal)MODELS ExamplesMODELS (<strong>ASAP</strong> Command)Creates a scattering model.Function

<strong>ASAP</strong> | Commands and Macros (M) | 223• Create/Modify Media, Coatings, Scatter ModelsSyntaxMODELS [ i [ PLOT [ a a'...] ] ]OptioniPLOTa a' ...DescriptionBeginning model numberPlots the model in log (b-bo) and angle spaceUser-defined degree specular anglesRemarks1. Defines a specific scatter model from a general set of Bi-directional Scattering Distribution Function (BSDF)scattering models.2. Begin defining scatter MODELS at number i (the default model number is one more than the highest defined).3. Similar to the MEDIA and the COATING commands, it constructs a database for use in the construction of anOBJECT.4. Creates a distribution file name_angle.dis for each of these angles.5. Both the r and t values on the INTERFACE command must be non-zero.6. The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.MODELS ExamplesMODIFY (<strong>ASAP</strong> Command)Modifies current distribution data.Function• Display/Modify Data DistributionsSyntaxMODIFY [ m m' n n' [ a b ] ] [ 'flabel' ]fcn[ m m' n n' [ a b ] ]fcn:Optionm m'n n'a bfcn'flabel'DescriptionInteger pixel ranges in the across directionInteger pixel ranges in the down directionScale factorsInternally or user-defined functionOptional text to relabel the functional dataRemarks1. Modifies the data region specified by the two integer pixel ranges, m to m' (across) and n to n' (down). The data inthat region is replaced by a plus b times the data value, that is:

<strong>ASAP</strong> | Commands and Macros (M) | 2242. Alternatively, an intrinsic or extrinsic function may be used to modify the data according to the equation:3. The function name fcn is either internal or user-defined via $FCN.4. More complex modifications can be done with multiple commands.5. Use the 'flabel' option to relabel the functional data.MODIFY ExamplesMOVE (<strong>ASAP</strong> Command)Moves rays along their propagation direction to a new location.Function• Modify Ray/Beam DataSyntax 1MOVE BY dOPLSyntax 2MOVE BY X dYZSyntax 3MOVE TO X vY

<strong>ASAP</strong> | Commands and Macros (M) | 225ZOptionBYTOdX Y ZOPLvDescriptionRelative moveAbsolute moveDistance along a given coordinate directionDirection vectorsOptical path lengthValue for location of ray intersectionRemarks for Syntax 11. MOVEs rays along their direction vectors BY the specified distance d, or projected distance along direction vectorX, Y, or Z.2. MOVEs rays along their direction vectors BY the specified OPL, accounting for the index of the media in which therays currently exist.Remarks for Syntax 21. MOVEs the rays along their direction vectors BY the projected distance d along the specified axis.Remarks for Syntax 31. MOVEs rays along their direction vectors TO the specified location value v or to the point of closest approach if theprojection vector does not intersect value v.Remarks - General1. During the MOVE operation, the rays are projected along their direction vectors. The rays do not intersect anyOBJECTS along the way.2. Commonly used for virtual ray tracing from a buried entrance pupil to object space, so that the beam may then betraced through the system.3. Use MOVE to observe the effects of defocus on a beam.MOVE ExamplesMOVE PARABASALS (<strong>ASAP</strong> Command)Moves the parabasal rays for each ray/beam to its base ray plane.Function• Modify Ray/Beam DataSyntaxMOVE PARABASALSRemarks1. Moves parabasals to a plane perpendicular to the base point. It does not in any way change the beamcharacteristics, but does affect the PLOT BEAMS display since, by default, the parabasals lie on the current objectsurface.MOVE Examples

<strong>ASAP</strong> | Commands and Macros (M) | 226MOVE TO FOCI (<strong>ASAP</strong> Command)Moves rays or beams along the propagation direction to a focus determined by the plane of minimum RMS spot size.Function• Modify Ray/Beam DataSyntaxMOVE TO FOCI [ n n' n" ... ]Optionn n' n" ...DescriptionSpecified parabasal raysRemarks1. Moves each ray/beam to the centroid of the intersections of the given parabasal rays with the base ray.MOVE ExamplesMOVE TO PLANE (<strong>ASAP</strong> Command)Moves rays along their propagation direction to a specified reference plane.Function• Modify Ray/Beam DataSyntaxMOVE TO PLANE [ x y z ] [ a,b,c ]Optionx y za,b,cDescriptionGlobal coordinate of a reference planeGlobal direction vector of the surface normal of theplaneRemarks1. Transfers the current ray/beam set to a plane with normal (a,b,c) through the point (x,y,z).2. The default point is the average of the current base ray coordinates.3. The default for the normal to the plane is the average of the current base ray directions.4. The peak-to-valley optical path difference on this surface is also printed so that normally it represents thereference plane of an afocal system.MOVE TO PLANE ExamplesMOVE TO POINT (<strong>ASAP</strong> Command)Moves rays along their trajectories to their closest approach to the given point (x y z).Function• Modify Ray/Beam Data

<strong>ASAP</strong> | Commands and Macros (M) | 227SyntaxMOVE TO POINT x y zMOVE TO POINT ExamplesMOVE TO SPHERE (<strong>ASAP</strong> Command)Moves rays along their propagation direction to a specified different sphere.Function• Modify Ray/Beam DataSyntaxMOVE TO SPHERE r [ x y z ]Optionrx y zDescriptionRadius of reference sphereCoordinate of center of reference sphereRemarks1. Transfers the current ray/beam set to the surface of a sphere of radius r centered on the point (x,y,z) or a PLANEwith normal (a,b,c) through point (x, y, z) by using the variation of the MOVE command.2. The default point is the average of the current base ray coordinates.3. The peak-to-valley optical path difference on this surface is also printed so that normally it represents thereference sphere of a focusing system.4. If none of the SPHERE data is given, a best-fit spherical wavefront is used.5. The default for the normal to the PLANE is the average of the current base ray directions.6. The default point is the average of the current base ray coordinates.7. The peak-to-valley and RMS optical path difference on this surface are also printed so that normally it representseither the reference sphere of a focussing system or the reference plane of an afocal system.MOVE TO SPHERE Examples$MSGS (<strong>ASAP</strong> Macro)Switch on or off the display of warning and informative messages other than error messages.Syntax$MSGS [ ON ]OFF$MSGS ExamplesMUELLER (<strong>ASAP</strong> Command)Creates Mueller matrix elements.Function

<strong>ASAP</strong> | Commands and Macros (M) | 228• Create/Modify ObjectsSyntax 1Mueller M11 M12 M13 M14 ... M41 M42 M43 M44 RM11 RM12 RM13 ... RM41 RM42RM43 RM44 'name'Syntax 2Muellerm11 m12 m13 m14 rm11 rm12 rm13 rm14m21 m22 m23 m24 rm21 rm22 rm23 rm24... ...m41 m42 m43 m44 rm41 rm42 rm43 rm44 'name'OptionDescriptionM11, M12 , M13, M14, … RM41, RM42, RM43, RM44 Keywords for the transmission and reflection of Muellermatrices elements.m11, m12 , m13, m14, … rm41, rm42, rm43, rm44 Values for the transmission and reflection of Muellermatrices elements.'name'Remarks - Syntax 1Name of the MUELLER device. Default name format isMUELLER0001, MUELLER0002, and so on.1. Syntax 1 supports both positional and keyword parsing of Mueller matrix elements.2. M11 M21... and RM11 and RM21... are keywords. M11 to M44 specify the transmission Mueller matrix, andRM11 to RM44 specify the reflection Mueller matrix.Note: All matrix elements are optional, but at least one element must be present.3. You can directly specify a non-zero matrix element by using the syntax keywords. All other unspecified elementsdefault to zero. For example, the scriptMUELLER M11 1.0 M22 1.0 M33 1.0 M44 1.0 'MUELLER_FREE_SPACE'creates a free-space Mueller matrix without the reflection Mueller matrix.4. Keywords for Syntax 1 are convenient for setting up sparse Mueller matrices with only a few non-zero elements.5. Alternatively, you can specify Mueller matrix elements in the exact order as listed in Syntax 1. The elements afterthe last specified elements default to zero. For example, the following script also creates a free-space Muellermatrix without the reflection Mueller matrix.1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 'MUELLER_FREE_SPACE'6. Default values for the Mueller matrix elements are zero.Remarks - Syntax 21. In syntax 2, the transmission and reflection Mueller matrices are specified on the four lines following the Muellercommand in the row format. The first four numbers on each line specify the transmission Mueller matrix, and thelatter four numbers on the line specify the transmission. If all elements on one line are zero, only one zero needs tobe entered.2. The name of the Mueller matrix device is specified on the last line.

<strong>ASAP</strong> | Commands and Macros (M) | 2293. <strong>ASAP</strong> ignores all trailing zero entries on each line. Therefore, you must specify all elements until the last nonzeromatrix element. If all elements on one line are zero, only one (1) is needed. For example, the following scriptcreates an ideal depolarizer for both reflected and transmitted rays.MUELLER1 0 0 0 1000 'IDEAL_depolarizer'4. As in Syntax 1, default values for the Mueller matrix elements are zero.5. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER3 Realistic polarizer POLARIZER RPM4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC8 Cascaded polarizationelementMUELLER ExamplesCPECPEMULTIPLE (<strong>ASAP</strong> Command)Converts the surface into multiple sheets.Function• Create/Modify Objects• Define/Modify Surfunc EntitiesSyntaxMULTIPLE n f' [ EXPONENT p ]d x y zOptionnf'dx y zDescriptionNumber of sheets to be generatedAdditive constant to the original functionDistance between original and first sheetsAn arbitrary point on the original surface

<strong>ASAP</strong> | Commands and Macros (M) | 230OptionEXPONENT pDescriptionExponent to which sheet number is raisedRemarks1. The surface is converted into multiple parallel surfaces. In other words, the equation of the surfaces becomes:2. The zeroth sheet is the original surface.3. Alternatively, <strong>ASAP</strong> can calculate f' such that the distance from a point x,y,z on the original surface to the firstsheet is d.4. The exponent p is defaulted to 1, but can be used, for example, to get evenly spaced cylinders or spheres (p=2).5. If MULTIPLE is being used to define a diffraction grating, then the value of n is irrelevant.6. Graphical viewing (for example, PROFILES or RENDER) of changes to sheet spacing that use the EXPONENToption is not possible. Instead, verification may be made after tracing an INTERFACE...DIFFRACT object thatreferences this multiple surface.MULTIPLE Examples

<strong>ASAP</strong> | Commands and Macros (N-O) | 231Commands and Macros (N-O)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “N-O”.$NEXT (<strong>ASAP</strong> Macro)Immediately begins processing of the next $DO or $ITER iteration by forcing a branch to the top of the current loopblock.Syntax$NEXTExample$DO 1 10{ :This block is executed every iteration:$IF ? LE 5; $NEXT:This block is executed only for iterations 6 through 10:$NEXT ExamplesNONLINEAR (<strong>ASAP</strong> Command)Creates a scatter model based on the combination of the Phong and Harvey models.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax 1- Isotropic (polynomial coefficients)NONLINEAR a1 b1 c1 d1 e1 [ a2' b2' c2' d2' e2' [ a3" b3" c3" d3"e3" ...] ] ] [ PLOT [ a a' ...] ]Syntax 2 - AnisotropicNONLINEAR X p q a b c d e [ p' q' a' b' c' d' e' ... ] ]YZ:Syntax 3 - Fitting BSDF valuesNONLINEAR FIT [ n ] [ options ]FRAC e e' ...

<strong>ASAP</strong> | Commands and Macros (N-O) | 232data…:Optiona b c d e ...PLOTa a' ...FITn (or optionally e e' ...)FRACANGLESLOGDescriptionBSDF equation coefficientsPlots the model in log(b-bo) and angle spaceUser-defined degree specular anglesFIT the BSDF values to the modeln is the number of 5-parameter terms (default 5); the e'sare the starting guesses for the exponents of each termFractional errorSpecifies spherical angle coordinatesSpecifies common logarithmic BSDF valuesRemarksThe following remarks apply to both isotropic and anisotropic versions unless otherwise noted.1. Generalizes the combination of the Harvey (sharp peak) and Phong (broad peak) models and, as such, isapplicable to both smooth and rough surfaces.2. Isotropic: The command is defined by the following relatively simple formula:where from the previous definition of the isotropic-surface direction cosine variables:where3. Anisotropic: The command assumes the surface anisotropy is aligned with the local Alpha or Beta direction andis defined by the following relatively simple formula:

<strong>ASAP</strong> | Commands and Macros (N-O) | 233where from the previous definition of the anisotropic-surface direction cosine variables:where F = Scatter angle from normalwhere = Specular from normal4. If the quantity in braces {} is less than zero, the term is set to zero.5. The e exponents do not have to be integer or positive.6. Note that the resulting BSDF is guaranteed to have all the correct positivity, symmetry, and reciprocity properties.7. Scattering from anisotropic surfaces is not rotationally symmetric at normal incidence, and not necessarilysymmetric about the plane of incidence. Therefore, the orientation of the model on the surface is important, and isgenerally specified by an axis for the second command entry. For syntax information, see the command argument,MODEL.8. Isotropic: The total number of parameters must be less than or equal to 285, that is, N less than or equal to 57quintuples (five or less terms is usually sufficient for most surfaces). The specific cases of this model are:Forward Harvey a1>>1 b1=-2a1 c1=0 d1>0 e1>1 b1=2a1 c1=0 d1>>0 e10 e1=1Forward Phong a1=0 b1=c1 c1>0 d1=0 e1>1Retro Phong a1=0 b1= -c1 c1>0 d1=0 e1>19. Anisotropic: The total number of parameters must be less than or equal to 40 terms (five or less terms are usuallysufficient for most surfaces).Note: When the ps equal the qs and the as equal the bs for each term, this model reduces to the isotropicsurfaceversion.10. Isotropic: The user can optionally fit BSDF values to the above model by using the NONLINEAR FIT commandwhere n is the number of five-parameter terms (default 3) or optionally the es are the starting guesses for theexponents of each term.11. Anisotropic: The user can optionally fit BSDF values to the above model by entering the data on successivecommands:NONLINEAR FIT [ n ] [ options ... ]FRAC e e' ...data ...:12. Anisotropic: n is the number of 7-parameter terms (default 5), or optionally the es, are the starting guesses forthe exponents of each term. If the given data does not cover most of the input and output hemispheres, the fittedmodel can do unexpected things in the missing regions; for example, it can have a TIS greater than one.

<strong>ASAP</strong> | Commands and Macros (N-O) | 23413. Since the NONLINEAR model is not defined in logarithm space (like the POLYNOMIAL model), the FIT mayhave difficulty in accurately reproducing any BSDF with a high dynamic range. Optionally, the FRACtional errorat each data point can be used instead of the absolute error. This has about the same effect as fitting in logarithmspace. In either case, the fit is done using an iterative non-linear damped least-squares algorithm. Therefore,it converges to one of the local minima and not necessarily the best one. An off-line, time-consuming, globaloptimization technique (for example, simulated annealing) could be used if the data only needs to be fit once.14. The PLOT option plots the model (common base 10 logarithm of the BSDF) for up to seven specular angles inascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls the resolutionof these plots in direction cosine space, and it creates a distribution file, name_angle.dis for each of these angles.15. The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.NONLINEAR ExamplesNORMALIZE (<strong>ASAP</strong> Command)Renormalizes the current distribution data.Function• Display/Modify Data DistributionsSyntaxNORMALIZE [ d [ v [ h ] ] ] [ 'flabel' ]MAX MAXOptiondvhMAX'flabel'DescriptionData renormalization valueVertical scale factorHorizontal scale factorMaximum distribution data or coordinate valueNew label for functional dataRemarks1. Renormalizes distribution data (divides functional values) by the value of the last NORMALIZE command(default).2. Alternatively, the data may be normalized by the given value d or the MAXimum value in the distribution data.3. Vertical v and horizontal h coordinate ranges can also be normalized in a similar manner by the optional third andfourth entries.4. Use the flabel option to relabel the functional data.5. Different scale factors can be used for the two coordinate ranges.NORMALIZE ExamplesNUMBERS (<strong>ASAP</strong> Command)Displays current valid media, surfaces, edges, lenses, and object numbers.Function

<strong>ASAP</strong> | Commands and Macros (N-O) | 235• Setup Plots and Verify SystemSyntaxNUMBERS [ NAMES ]SUMMARYOptionNAMESSUMMARYDescriptionLists a table of numbers and names for all media,coatings, and objectsLists a short summary of storage usageRemarks1. Displays either a short SUMMARY of storage usage or a table of numbers and NAMES of the current valid media,coatings, surfaces, edges, lenses, and object members.2. Displays unused numbers as blank areas in the tables.3. Displays temporarily disabled objects (via the CONSIDER command) as negative numbers (when using NUMBERSalone).NUMBERS ExamplesOBJECT (<strong>ASAP</strong> Command)Defines an object based upon previously defined entities.Function• Create/Modify ObjectsSyntax 1 - Makes a new object from the last defined entityOBJECT 'name'OBJECT0.1 'name'Syntax 2 - Use multiple surfaces or edges to create a solid or mesh objectOBJECT; i [ q i' q' ... ]-n q [ q' ... ] q"Syntax 3 - Recalls the previously defined object for modificationOBJECT namejOptionjnameDescriptionStarting object numberName of the object

<strong>ASAP</strong> | Commands and Macros (N-O) | 236Optioni i' ...q q' q" ...nDescriptionEntity numbersConnection factorsLast number of entitiesRemarks1. Syntax 1 defines a new OBJECT using either the last entity, or begins defining OBJECTS starting with number j.2. The default value for j is one more than the largest object number defined, and is set to one at the start of programexecution.3. For Syntax 1, the i is the surface, edge, or lens number that defines the geometry of the object. Simple meshobjects can be formed by one or (if i' is also given) two edges. The edges used to define a simple mesh object musthave the same number of points. If the second edge is not entered, <strong>ASAP</strong> defines the object as a planar surfacebounded by the dimensions of the first edge.4. The name is a descriptive designator that the user can assign to the object.5. For Syntax 2, if the i's refer to EDGES, a two-dimensional mesh is formed from these edges with the edge-to-edgeconnection specified by the q's (See the POINTS commands for definitions but note that the inter-curve Bezierdegree cannot be greater than 2). The edges in the mesh should be similar; that is, have the same number of pointsand point-to-point connection factors.6. Alternatively, with Syntax 2, the last n edges may be used to form a mesh with q, the connection factor for oddedges, q' for the even edges, and "q the last to first. The edges in the mesh should be similar; that is, have the samenumber of segments.7. For Syntax 2, if the i's refer to SURFACES, a solid is formed by bounding each surface with the others. The signsof the q's determine the proper side of each surface (See the BOUNDS command). A zero q means the surface isnot to be used to bound the others in the object. Note that each surface's LOCAL box (if defined) always clips it.8. The default INTERFACE for surfaces and edges is totally absorbing. Regarding the default INTERFACE for alens object, refractive conicoids are 100 percent transmitting and reflective conicoids are 100 percent reflecting;the lens itself is surrounded by air.9. The FRESNEL, SPLIT, and LEVEL commands can be different for every object.10. Syntax 3 recalls a previously defined object for modification.OBJECT ExamplesOBLIQUE (<strong>ASAP</strong> Command)Switches future graphical output between normal (orthogonal) projection and oblique (non-orthogonal) projection.Function• Setup Plots and Verify SystemSyntaxOBLIQUE [ f ] [ a a' ]OFFOptionfaa'DescriptionThird depth coordinate pivot pointRotation angle (in degrees) about the vertical axisRotation angle (in degrees) about the horizontal axis

<strong>ASAP</strong> | Commands and Macros (N-O) | 237OptionOFFDescriptionNormal orthogonal projections are restored by OBLIQUEOFF (the default at program startup)Remarks1. When active, all future plots are an oblique projection that is pivoted about f.2. If autoscaling is in effect, f is automatically determined by <strong>ASAP</strong>; otherwise f=0.3. The defaults for a and a' are 45 and 30 degrees, respectively.4. Setting both a and a' equal to zero effectively turns OBLIQUE off.5. WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinate system. UseWINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handed coordinate system.OBLIQUE ExamplesOFFSET (<strong>ASAP</strong> Command)Shifts the origin of the current distribution data.Function• Display/Modify Data DistributionsSyntaxOFFSET [ v [ h ] [ d ] ] ]Optionv hdDescriptionCoordinates of the new originAdditive constant to distribution data valuesRemarks1. Shift the origin of the distribution to the given actual coordinates.2. Default is to make the new origin the center of the data set.3. Optionally, add d to all distribution data values.OFFSET ExamplesOPDMAP (<strong>ASAP</strong> Command)Creates a geometric wavefront map of the currently selected ray data.Function• Analyze Ray/Beam DataSyntaxOPDMAP [ name ] [ d ] [ PSF [ f ] ]OptionnamedDescriptionName of the distribution file (default extension *.dis)Specifies the sampling performed (see Remarks below)

<strong>ASAP</strong> | Commands and Macros (N-O) | 238OptionPSFfDescriptionFlag for determination of point spread function (PSF)Controls how much of the PSF to return. See Remarks.Remarks1. Produces a geometric wavefront map of the ray data as contained within the plotting window specified by the lastWINDOW command. The wavefront map is stored in the file, name.dis or the default file, BRO009.DAT. The datacan then be manipulated and plotted using the DISPLAY commands.2. The geometric wavefront map is determined by interpolating the optical path length data (of the first sourceencountered in the current ray set). In the process, the average Optical Path Difference (OPD) value (piston)is removed. You may remove focus and tilt errors by preceding OPDMAP with a FOCUS MOVE or MOVE TOcommand.3. If d is entered as zero, <strong>ASAP</strong> generates a fast discrete map of the wavefront with no interpolation.4. Otherwise, <strong>ASAP</strong> uses a general (and somewhat slower) linear interpolation (no extrapolation) technique thatconsiders only a small set of ray points within a distance d (default is three times the smallest ray separation) ofeach grid point.5. If a WAVELENGTH is set and d is non-zero, <strong>ASAP</strong> forms the complex geometrical pupil function from theinterpolated OPD map and stores its Fourier Transform (that is, the coherent PSF) in the BRO029.DAT file.The f controls how much of the PSF to return. If it is less than one (1), it is the maximum distance in Airy units (default 5). This PSF isnormalized relative to an ideal circular aperture of equivalent area. A DISPLAY 29 ENERGY command can thenbe used to manipulate and plot this far-field distribution.6. Do not use OPDMAP at focus or within a caustic; the calculation is not relevant there. Instead, use the FOCUSMOVE or MOVE TO SPHERE command to move the ray data to an appropriate reference sphere (located wellaway from focus, the exit pupil is a traditional location) before issuing the OPDMAP command.7. The command argument, CLIP can be used to specify an object (i) or edge number (j) whose bounds and limitsclip the distribution. If i is not given, it is defaulted to the current object number of the first valid ray. If j isnegative the interior of the closed edge is used, if j is positive, the exterior of the closed edge is used.OPDMAP ExamplesOPTICAL (<strong>ASAP</strong> Command)Creates spherical, conic, or aspheric surfaces normal to the axis of symmetry.Function• Define/Modify Surfunc EntitiesSyntaxOPTICAL X x r [ c d e f g h i j k l ] [EXPAND] [aperture ... ]Y yZ z[ t r [ c d e f g h i j k l ] [EXPAND]]OptionDescriptionX, Y or Z Axis of symmetryx, y or z Location along coordinate axisrVertex radius of curvaturecConic constant

<strong>ASAP</strong> | Commands and Macros (N-O) | 239OptionDescriptiond, e, ..., l 4th, 6th, ..., 20th-order aspheric deformation coefficientsEXPANDaperturet<strong>Reference</strong> PointAt intersection of surface and coordinate axis.Surface NormalAlong positive coordinate direction.RemarksFlag to expand conic into aspheric termsELLIPSE, RECTANGLE, or HEXAGONALRelative distance of second optical surface1. Creates a classical optical surface normal to the axis of symmetry at a value given by the third entry. This is thecommand of choice for making simple conic or aspheric surfaces in <strong>ASAP</strong>.2. The second entry designates the axis of symmetry (either X, Y, or Z) for the surface.3. The vertex radius of curvature r is negative if the center of curvature is on the negative side of the surface. A zeroor very large r corresponds to a planar surface.4. OPTICAL surfaces may not facet properly when the slope at the boundary becomes infinite, such as the edgeof a hemisphere. Using an ELLIPSE aperture that is slightly smaller than the boundary radius minimizes theseproblems.Example: A hemispherical dome with radius 100 is defined by:SURFACE; OPTICAL axis Z z 0 radius 100 conic 0 ELLIPSE 99.9995. c is the conic constant (for example, 0 is a sphere, -1 is a parabola, and so on).6. d is the 4th-order aspheric deformation coefficient, e is the 6th-order, and so on up to l the 20th.7. This surface/function is stored in order doubled mode.8. <strong>ASAP</strong> exactly models the surface function up to the 10th order, or if the base surface is parabolic (conicconstant = -1) up to the 20th order. If the base surface is not parabolic and exceeds the 10th order, the surface isapproximated by a truncated power series. If an aperture a is specified, a table of sag points for user verification isprinted to verify accuracy.9. If the highest order aspheric entry is the literal EXPAND, the conic is expanded for all coefficients into asphericcomponents up to that order. If the EXPAND option is used, the table of sag points is not produced.10. The sag of the surface as a function of the radial coordinate is given by the following equation:11. At the vertex of the surface the normal vector points along the positive coordinate direction.12. A second line immediately following the OPTICAL command can be used to specify an optional second surfacea distance t from the first surface. This inclusion permits modeling of the front and back surfaces of a singlet lenswith a single entity.

<strong>ASAP</strong> | Commands and Macros (N-O) | 24013. This surface can extend to infinity unless a LOCAL command follows, or a trailing aperture option of thefollowing form is specified:ELLIPSE a [ a' [ o [ s [ s' ] ] ] ]RECTANGLEHEXAGONAL a [ o [ s [ s' ] ] ]14. a a' are the heights in the other two transverse directions.15. For the HEXAGONAL form, a is the center-to-vertex distance (maximum height).16. o is an optional central hole ratio.17. s s' are the transverse coordinates of the center of the aperture.OPTICAL ExamplesOVAL (<strong>ASAP</strong> Command)Creates a polygonal edge.Function• Define/Modify Curvedge EntitiesSyntaxOVAL X x y z q [ n a a' ]Y y z xZ z x yOptionDescriptionX, Y or Z Specifies the axis of symmetryx, y or z Location along coordinate axisy z (z x or x y)qSemimajor widths of the ovalParameter controlling the type of closed curven Number of points (or segments) on the oval (default 16)a a'RemarksAngular range (in degrees from first semimajor axis)over which the oval is defined (default is 0 to 360degrees)1. Defines a polygonal edge that can continuously vary between an ellipse (q=0) and a rectangle (q=1).2. The semimajor widths are measured to the points, not to the lines connecting the points.3. If n, a, and a' are specified, they become the default settings for most future EDGE commands.4. This edge is made up of coplanar straight line segments, whose vertices lie on a particular curve.OVAL ExamplesOVERLAY (<strong>ASAP</strong> Command Argument)Overlays plots (that is, places them on top of each other).

<strong>ASAP</strong> | Commands and Macros (N-O) | 241Function• Standard Plot OptionsSyntax... OVERLAY [ k ]OptionkDescriptionInteger quadrant flagRemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. The command argument, OVERLAY tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.3. Use as a modifier on any <strong>ASAP</strong> command that produces graphical output.4. The k is an integer between 1 and 4 inclusive that tells <strong>ASAP</strong> to scale the plot down to half size and place it in thekth quadrant of the normal plotting area. This feature can be used to overlay but not overlap successive plots; thatis, spot diagrams for different source points. The quadrants are numbered in the following manner: 1=upper left,2=upper right, 3=lower left, 4=lower right. Due to the scaled-down size, no ordinary border text is placed on theplot.5. The default value of k is 0, that is, normal full-sized plot, if the last plotting command did not have an OVERLAYoption on it. Otherwise, it is one more than the last quadrant specified.OVERLAY Examples

<strong>ASAP</strong> | Commands and Macros (P) | 242Commands and Macros (P)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “P”.$PAGE (<strong>ASAP</strong> Macro)Pauses text output.Syntax$PAGE [ n ]OFFRemarks1. Macro causes future text output to be paused every n lines (default 12); that is, it waits for you to press Enter tocontinue.2. Pausing can be turned OFF with this command or by typing a caret “^” at a pause.$PAGE (<strong>ASAP</strong> Macro)PARABASAL (<strong>ASAP</strong> Command)Sets the number of parabasal rays.Function• Setup Beam CreationSyntaxPARABASAL n [ d [ d' ] ] [ CLIP ][ g h u v ][ g' h' u' v' ][ g" h" u" v" ]:Optionnd d'g h u v, g' h' u' v' ...CLIPDescriptionNumber of parabasal raysSemi-divergences of each geometric incoherent beam(radians)See RemarksFlag to check for parabasal ray clippingRemarks1. Sets the number of parabasal rays to be traced around each base ray. The command should precede any raydefinition commands (GRID, RAYSET and others).2. The parabasal rays follow the same path through the system as the primary ray, and are never clipped by aboundary unless the base ray is also clipped.3. The n usually takes on values of 0, 2, 4 or 8.

<strong>ASAP</strong> | Commands and Macros (P) | 2434. If n equals four or eight and a WAVELENGTH is specified, the parabasal rays are used to define general Gaussianbeams centered on each base ray.5. The d and d' set the defaults for the semi-divergences of each geometrical incoherent beam in radians. This valueis used only if n=0 or 4, and the current WAVELENGTH is zero; that is, a geometrical optics radiant beam.6. The CLIP option signals <strong>ASAP</strong> to check for clipping of the parabasal rays by boundaries, and to reduce the beamflux accordingly. The parabasal rays are not actually clipped from the beam, however.7. Parabasal rays are numbered according to the following scheme (where Wi refers to a waist ray displaced in thepositive ith direction and Di refers to a divergence ray propagating in the positive ith direction):Parabasal Ray Numbern 1 2 3 4 5 6 7 81 Wx2 Wx Wy3 Wx Wy Dx4 Wx Wy Dx Dy5 Wx Wy Dx Dy -Wx6 Wx Wy Dx Dy -Wx -Wy7 Wx Wy Dx Dy -Wx -Wy -Dx8 Wx Wy Dx Dy -Wx -Wy -Dx -Dy8. The divergence angle, u, of the parabasal rays is calculated from the equation:where is the WAVELENGTH of the beam and h is the waist semi-diameter of the Gaussianbeam. This definition was chosen so that the width of the Gaussian beam corresponds toor roughly the 45 percent amplitude point.9. Normally, depending upon the properties of the beams being created, the transverse positions and direction of theparabasal rays are automatically set by <strong>ASAP</strong>. However, an override table can be entered, one line per parabasalray. The g's and h's are the relative heights in the two orthogonal directions. The u's and v's are the orthogonalconvergence/divergence angles in radians.10. The WIDTHS command modifies the default parabasal ray settings, scaling the width of the parabasal rays.PARABASAL ExamplesPARAMETERIZE (<strong>ASAP</strong> Command)Sets the parameterization axis for meshing the current surface.Function• Define/Modify Surfunc EntitiesSyntaxPARAMETERIZE -X-Y-Z+X+Y+Z

<strong>ASAP</strong> | Commands and Macros (P) | 244Remarks1. PLOT FACETS can be used on most SURFACE/OBJECTS to produce a wire-frame plot of the OBJECT. Insome situations, the inherent parameterization of the polynomial fails. The PARAMETERIZE command reparameterizesthe plot.2. Sets the parameterization of the current surface to be either parallel ( - ) or perpendicular ( + ) to the given localaxis.3. Tells <strong>ASAP</strong> how to mesh the surface (for PLOT SURFACE, PLOT MESH, PLOT FACETS, VUFACETS, andGRID OBJECT or ENTITY, EMIT OBJECT or ENTITY commands), but requires that the surface has a LOCALbox defined either implicitly or explicitly. Since this is automatically set for most surfaces, it is rarely necessary tooverride with the PARAMETERIZE command.4. If you do override the LOCAL command, the LOCAL box must be at least as large as the surface to be meshed orfaceted.5. This command and whether a surface can be meshed (faceted) have absolutely no effect on tracing rays/beams toor through the surface.6. Surfaces that cannot be meshed or faceted can be visualized using PROFILES or RENDER.PARAMETERIZE ExamplesPARTICLES (<strong>ASAP</strong> Command)Creates a particulate scatter model.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxPARTICLES g q[`p] fVOLUME MIE m a a' f [ fcn n c c' … ]r sOptionDescriptiong Directional factor between -1 (perfect backscatter) to 1(perfect forward scatter) exclusiveq `pMIEma a'frsRemarksScattering and absorption efficiency per particle(typically near or less than one)Flag for exact MIE calculationMEDIA number or nameParticle radii (in wavelength units)Overall fractional area obscuration at a normal incidenceIntrinsic surface reflectivityRMS surface roughness1. The surface/volume scatters as if it had a uniform random distribution of particles on/in it. The three-entry shortform is based on the simple Henyey-Greenstein model (see option g).2. A g value of zero corresponds to isotropic scatter.

<strong>ASAP</strong> | Commands and Macros (P) | 2453. The `p allows for optional entry of absorption efficiency per particle. If used, it should immediately follow thescatter efficiency value q with only a backward tick to separate the two numbers. Either number is typically nearor less than one. Entering q `0 is the same as entering q by itself.Note: This entry may look like a complex number, but it is not treated mathematically as such. It is only aconvenient method to allow entry of the optional value for p.4. The f option is equivalent to the number of particles-per-unit-volume times the average particle cross-sectionalarea. Therefore, it is usually a small number, much less than one.5. For particles in a VOLUME, f is the overall fractional area obscuration per unit length, and is equivalent to thenumber of particles per-unit-volume times the average particle cross-sectional area. Whether the scattering is fromactual real particles or something else, only the product of q and f is important, since it is just equal to the standard"extinction" coefficient.6. Whether the scattering is from actual real particles or something else, only the product of q+p and f matters, sincethis is equal to the standard "extinction" coefficient (q times f is inversely proportional to the mean free pathlength).7. Two other models for single sphere scattering are available:• An exact time-consuming MIE calculation with particle refractive indices specified by MEDIA m.• A fast approximation for large (radii much greater than a wavelength), opaque (indices much greater than one),rough (white Gaussian statistics) spheres with intrinsic surface reflectivity r, and RMS surface roughness s(relative to the sphere radius).In both cases, the particle radii lie between a a' (in wavelength units) corresponding to the one-over-e-squaredpointsof a default Gaussian normal-size distribution.8. PLOT creates a plot of the model.9. Optionally, any size distribution function fcn can be defined via a previous $FCN macro. The main "_" argumentof the function is a normalized size between the integration limits -1 to 1; that is, the main "_" argument is equal towhere r is the actual size (again in wavelength units). The n is the number of integration samples to use in thegiven size range (enter zero for a minimal default). The additional (and optional) c c’ .". command parametersare passed in the "_1 _2 ..." registers (up to 66). For example, an equivalent to the default distribution is simplydefined as follows:$FCN E2GAUS EXP(-2*_^2)Also, if the distribution function is known in terms of actual size R, define it in terms of the normalized radius "_";that is,$FCN PSDIST R=_*(_2-_1)/2+(_1+_2)/2 ...MODELPARTICLE MIE m a a' f PSDIST a a' ...PARTICLES ExamplesPATCHES (<strong>ASAP</strong> Command)Points represent Bezier surface patches.

<strong>ASAP</strong> | Commands and Macros (P) | 246Function• Define/Modify Curvedge EntitiesSyntaxPATCHES k l [ m n [ SEPARATE ] ]Optionk lm nSEPARATEDescriptionBezier degrees used for surface meshRational patchesUse separate rational patches (default is joined)Remarks1. Make current curve/edge points a surface mesh of Bezier degree k by l (neither to exceed 20) with m by ncontinuously joined or SEPARATE rational patches.2. The total number of points must be exactly equal to:(1+k*m)*(1+l*n) continuous(1+k)*(1+l)*m*n SEPARATE3. The connection q factors for each point is interpreted as actual rational Bezier weights w.4. Separate patches are defined sequentially from first to last.PATCHES Examples$PATH (<strong>ASAP</strong> Macro)Sets the default directory "path" for future file openings.Syntax$PATH [ "path" ]Remarks1. If no path is given, <strong>ASAP</strong> reverts to the previous one.2. The "path" must include the closing directory character (\, /, or ], depending on the operating system).3. The default files (see $IO) are closed in the old directory, and then reopened in the new one.$PATH ExamplesPATHS (<strong>ASAP</strong> Command)Produces a table of summarizing propagation paths of currently selected rays.Function• Analyze Ray/Beam DataSyntaxPATHS [ p ] [ n ] [ TOTAL ] [ SUM ] [ SHORT ]PEAK MINIMUM MEDIUMAVERAGE MAXIMUM LONGOBJECT

<strong>ASAP</strong> | Commands and Macros (P) | 247OptionpnAVERAGEPEAKTOTALOBJECTSUMMINIMUMMAXIMUMSHORTMEDIUMLONGDescriptionFlux sorting threshold, expressed as a percentage of totalflux in all pathsFlag to turn off printing paths containing fewer than nraysSorts paths by AVERAGE irradianceSorts paths by PEAK irradianceSorts paths by TOTAL flux (default)Sorts paths by OBJECT fluxReports sum of contributions to each pathReports minimum contribution to each pathReports maximum contribution to each pathSpecifies that the length of the printed output is SHORT(all integer object numbers)Specifies that the length of the printed output is MEDIUM(current and previous objects integer) (default)Specifies that the length of the printed output is LONG(all decimal object numbers)Remarks1. Prints out a table of ray paths according to current, previous, and initial objects.2. If p is greater than zero, <strong>ASAP</strong> sorts the paths by AVERAGE irradiance, PEAK irradiance, TOTAL flux (default),or OBJECT flux and prints out only those paths whose percentage contribution is greater than the decimal numberp. The number p must include a decimal point. For example, use 5.0 to make 5% the threshold. If p is not entered,paths are listed in the order of ray creation (parent, first generated child rays, second generated child rays, and soon).3. If specified, any paths containing fewer than n rays are also not printed.4. The report includes the SUM (by default) or the MINIMUM or the MAXIMUM individual contribution to theabove flux-related quantity for each distinct path.5. The value of the integer m determines whether the above flux-related quantity for each distinct path is theminimum (m = -1), sum (m = 0, default), or maximum (m = +1) of the individual contributions.6. The length of the printed output can be SHORT (all integer object numbers), the default MEDIUM (current andprevious objects integer) or LONG (all decimal object numbers).7. In the list of split/scatter objects, a negative number indicates scattered ray generation. Except for SHORT output,the three digits following the decimal point can be used to determine more precisely the mechanism that generatedthat ray at that object. The code numbers and their meanings are listed in the table below.Note: The DIFFRACT number refers to the order in which the diffraction orders are given on thecommand line, starting with 0 representing the first number. For example, in the following example, thepossible DIFFRACT numbers are 0, 1, and 2, representing -1, 0, and 1, respectively.INTERFACE COATING DOE AIR AIR DIFFRACT 0.2 -1 0.25 0 0.5 1 0.25

<strong>ASAP</strong> | Commands and Macros (P) | 2481st Digit Definition 2nd, 3rd Digits Definition0 Random Scatter 0 0 Hemispherical0 Random Scatter # # TOWARDS number1 Ordinary Reflection # # DIFFRACT number2 Ordinary Transmission # # DIFFRACT number3 Deterministic Scatter 0 0 Retro-reflected3 Deterministic Scatter 0 1 Near Reflected3 Deterministic Scatter 0 2 Near Transmitted4 Extraordinary Reflection # # DIFFRACT number5 ExtraordinaryTransmission# # DIFFRACT number6 Volume Scatter # # MEDIA numberPATH ExamplesPERFECT (<strong>ASAP</strong> Command)A "perfect" (but realistic) lens.Function• Define/Modify Lens EntitiesSyntaxPERFECT X x f h [ t [ h' ] ]Y yZ zOptionfhth'DescriptionFocal lengthInput heightOutput distanceOutput heightRemarks1. A "perfect" (but realistic) lens of focal length f (signed), input height h (less than magnitude of f), output distance t(default 0), and output height h' (default f*tan(asin(h/f)) ).2. The output ray vectors are determined from the input ray vectors by the solutions to the eikonal (characteristic)function for perfect imaging of an object plane at infinity (image plane at back focal plane), and no sphericalaberration of the principal points.3. Unlike the IDEAL lens, there are blurring ray aberrations at all other conjugates.4. Two back-to-back PERFECT lenses, with a small collimated space between them, can be used to perfectly reimagea finite-distance object to a finite-distance plane, with a magnification equal to the ratio of their focallengths.

<strong>ASAP</strong> | Commands and Macros (P) | 249PERFECT ExamplesPHYSICAL (<strong>ASAP</strong> Command)A comprehensive, physical reflection model that is "good" even for rough surfaces at grazing incidence.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxPHYSICAL s l [ r ] [ GAUSSIAN ]coatOptionslrDescriptionRMS roughnessAutocorrelation lengthNormal incidence ideal reflectivityRemarks1. Defined in terms of the statistical properties of the surface height variation; that is, RMS roughness s andautocorrelation length l in WAVELENGTH UNITS for either a fractal or GAUSSIAN Power Spectral DistributionFunction (PSDF).2. Requires the normal incidence ideal reflectivity r or polychromatic COATING name (default is the particularobject's specular reflectivity).PHYSICAL ExamplesPICTURE (<strong>ASAP</strong> Command)Produces a picture of the current distribution data.Function• Display/Modify Data DistributionsSyntaxPICTURE [ 'title' ]Option'title'DescriptionOptional title for plot (up to 64 characters)Remarks1. Opens the Display Viewer window containing the currently defined distribution data.2. Produces a color (default) or grey-scale picture of the current distribution data.3. An optional comment string, 'title' can be used to specify a title for the output.4. When the PICTURE command is entered, <strong>ASAP</strong> copies the current DISPLAY distribution data to a fileDISPLAYxx.TMP and then creates a Data Viewer window with which you can interrogate the distribution data.With each PICTURE command, xx is incremented, and a new file is created.

<strong>ASAP</strong> | Commands and Macros (P) | 2505. <strong>ASAP</strong> deletes the DISPLAYxx.TMP files when the Data Viewer window is closed. If you want to save thisdisplay file, use the WRITE command.PICTURE ExamplesPIXELS (<strong>ASAP</strong> Command Argument)Sets the number of pixels for the current plot only.Syntax... PIXELS nOptionnDescriptionNumber of pixelsRemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.PIXELS ExamplesPIXELS (<strong>ASAP</strong> Command)Sets the resolution for graphics and calculations.Function• Setup Plots and Verify SystemSyntaxPIXELS n [ r ] [ ON ] [ FILL ]OFF NOFILLOptionnrON or OFFFILL or NOFILLDescriptionSets the number of equally-spaced pixels along thevertical axis of the plotting window for all subsequentplots (default=39)Ratio of pixels per system unit along the horizontalaxis to pixels per system unit along the vertical axis(default=1)Flag to turn on or off the plotting of a pixel sampling box(the default)Flag to fill or not fill the plotting window, in bothdirections, with the plot1. Sets the resolution of the various plotting functions by dividing the window into a given number of pixels.2. Also sets the number of rays used to create a profile, and therefore determines the resolution of system plots.3. If the window is square, the plotting window is divided into a grid n pixels vertical by n*r horizontal.4. The default value of n is 39. (The DIMENSION command may be used to determine the maximum number ofpixels allowed in your version of <strong>ASAP</strong>.)

<strong>ASAP</strong> | Commands and Macros (P) | 2515. The r is the desired aspect ratio of the pixels; that is, the ratio of the vertical width to the horizontal (default 1).This option can be used to assure that the character plots are of the correct proportion.6. The number of horizontal pixels, m, is calculated from the window parameters (a, a', d, d'), n, and r, as follows:7. By default, all high-resolution (non-printer) graphics are mapped into the plotting window so that the aspect of thephysical entities is properly maintained. However, physically distorted views, where the entity completely FILLsthe plotting window in both directions, can also be obtained.8. By default, <strong>ASAP</strong> autoscales so that the aspect ratio is maintained. To distort the aspect ratio, make r negative.9. Certain graphics commands, PROFILE in particular, can plot a dotted box to highlight the current window setting.ON/OFF toggles this feature; the default is OFF.10. The FILL option allows you to plot physically distorted views, in which the entity completely fills the plottingwindow in both directions.11. PIXELS controls the number of data pixels generated by the SPREAD command (within the current WINDOW),and therefore determines the record structure of the data files they create and use.12. The command argument, PIXELS sets the number of pixels for only the current plot.PIXELS ExamplesPLACE (CURve/edge) (<strong>ASAP</strong> Command)Places the entity at the global position that corresponds to parametric coordinate u of CURve/edge k.Function• Define/Modify Curvedge EntitiesSyntaxPLACE CUR k uOptionkuDescriptionEntity numberParametric coordinatePLACE ExamplesPLACE (Global Coordinate) (<strong>ASAP</strong> Command)Specifies the absolute placement of an entity in global coordinates.Function• Create/Modify ObjectsSyntaxPLACE [ x y z ] [ LIST ]

<strong>ASAP</strong> | Commands and Macros (P) | 252X xY yZ zOptionDescriptionX, Y or Z Places axisx, y or z Position in global coordinatesLISTRemarksDecodes a 4-by-4 transformation matrix into simpleoperations (if possible) and prints1. Translates the entity TO the given point (x,y,z). Therefore, PLACE performs an absolute shift.2. If you enter PLACE without any numeric arguments, <strong>ASAP</strong> moves the entity's reference point to the global origin.3. The LIST option causes the resulting 4x4 transformation matrix to be printed and decoded into simple operations,if possible.PLACE ExamplesPLACE (Relative to Entity) (<strong>ASAP</strong> Command)Places the current entity relative to previously defined entities.Function• Define/Modify Curvedge Entities• Define/Modify Lens Entities• Define/Modify Surfunc Entities• Modify Ray/Beam DataSyntaxPLACE AT k [ d k' ] [ LIST ]SUR x y zEDGLENOBJRAYOptionk k'DescriptionEntity numbersd Fractional distance between the two entities (default 0)x y zATSUREDGLENCoordinates of the second point in spaceRefers to the same entity type as the entity beingtransformedSpecifies SURFACE entitySpecifies EDGE entitySpecifies LENS entity

<strong>ASAP</strong> | Commands and Macros (P) | 253OptionOBJRAYLISTDescriptionSpecifies OBJECT entitySpecifies RAY entityDecodes the 4-by-4 transformation matrix into simpleoperations (if possible) and printsRemarks1. Translates the entity TO the point (x,y,z). This form of PLACE determines the point (x,y,z) from the fractionaldistance d (default 0) from a given entity k to another point or entity k'.2. PLACE (Relative to Entity) is an alternate form of the PLACE (Global Coordinate) command.3. PLACE AT k tells <strong>ASAP</strong> to move the current entity so that its reference point is at the same coordinates as thereference point of entity k.4. PLACE AT k 0.5 k' tells <strong>ASAP</strong> to move the current entity so that its reference point is located at 0.5 timesthe distance between entities k and k'.5. PLACE SUR k 0.75 x y z tells <strong>ASAP</strong> to move the current entity so that its reference point is located at 0.75times the distance between the reference point of surface k and point (x, y, z).PLACE ExamplesPLANE (<strong>ASAP</strong> Command)Creates a plane normal to the axis of symmetry, at the value given by the third entry.Function• Define/Modify Surfunc EntitiesSyntaxPLANE X x [ aperture ... ]Y yZ zOptionDescriptionX, Y or Z Axis of symmetryx, y or z Location along coordinate axisaperture<strong>Reference</strong> PointAt intersection of surface and coordinate axisSurface NormalAlong positive coordinate directionRemarks1. Creates a planar surface.2. The normal vector points along the positive coordinate direction.ELLIPSE, RECTANGLE, or HEXAGONAL

<strong>ASAP</strong> | Commands and Macros (P) | 2543. This surface can extend to infinity unless a LOCAL command follows, or a trailing aperture option of thefollowing form is specified:ELLIPSE a [ a' [ o [ s [ s' ] ] ] ]RECTANGLEHEXAGONAL a [ o [ s [ s' ] ] ]4. For the HEXAGONAL form, a is the center-to-vertex distance (maximum height).5. o is an optional central hole ratio.6. s s' are the transverse coordinates of the center of the aperture.PLANE ExamplesPLANE NORMAL (<strong>ASAP</strong> Command)Creates a plane specified by its surface normal and a point.Function• Define/Modify Surfunc EntitiesSyntaxPLANE NORMAL a,b,c x y zOptiona,b,cx y zDescriptionUnit normal vector in global coordinatesPoint on surface of plane<strong>Reference</strong> PointAt specified pointSurface NormalIn specified directionAutolimitingNo, requires LOCAL or LIMITS modifiers.Remarks1. Creates a plane surface containing the point (x y z) and with unit normal vector (a,b,c ).2. The normal vector always points into the space on the positive side of the surface, where f(x y z)>0. As aprotective measure, <strong>ASAP</strong> always renormalizes the vector length to 1.PLANE ExamplesPLANE POINTS (<strong>ASAP</strong> Command)Creates a plane specified by three points.Function• Define/Modify Surfunc Entities

<strong>ASAP</strong> | Commands and Macros (P) | 255SyntaxPLANE POINTS x y z x' y' z' x" y" z"Optionx y z x' y' z' x" y" z"DescriptionGlobal coordinates of the three points on the surface<strong>Reference</strong> PointAt second specified pointSurface NormalBy right-hand ruleAutolimitingNo, requires LOCAL or LIMITS modifiers.Remarks1. Creates a planar surface that contains the three points (x y z), ( x' y' z'), and ("x "y "z)2. The positive side of the plane is found by applying the right-hand rule to the three points in the order they areentered.3. The second point becomes the surface's reference point.PLANE Examples$PLAY (<strong>ASAP</strong> Macro)Replays current output buffer.Syntax$PLAY [ n ] [ INPUT ] [ ’string’ ]ONOFFRemarks1. Replays the current output buffer (up to 10,000 lines), or just the output starting from the last occurrence of’string’. The replayed output pauses for a carriage return key every nth (default 12th) line.2. To exit the replay, enter an EOF character (Ctrl-Z or Ctrl-D) at the pause.3. The INPUT option displays only previously echoed input records. The program then asks for a range of lines tore-execute. Press Return for none.4. Alternatively, the capturing of output in the replay buffer can be turned OFF or ON (the default).$PLAY ExamplesPlotting CommandsThe PLOT command is a general command for plotting virtually any aspect of system geometry and selected ray data.Two common command syntaxes for producing pictures are:• PROFILE d d' n: Plots slices of each object by planes parallel to the window and between the depthcoordinates d and d' (set resolution with the PIXEL command and number of slices n.)• PLOT FACETS n n': Plots a three-dimensional mesh (set resolution by entering values for n and n').

<strong>ASAP</strong> | Commands and Macros (P) | 256The following standard plot command arguments can be used on the PROFILE, REPLOT, PLOT, TRACE PLOT,HISTORY PLOT, and SPOTS commands:• OVERLAY (<strong>ASAP</strong> Command Argument), which also applies to all PLOT commands• XY[Z] and Other Plot Window Overrides (<strong>ASAP</strong> Command Argument)• PLOT (<strong>ASAP</strong> Command Argument).The following commands list the types of geometry and ray data that can be plotted:• PLOT3D• PLOT CURVES• PLOT BEAMS• PLOT EDGES• PLOT ENTITIES• PLOT FACETS• PLOT LENSES• PLOT LIMITS• PLOT LOCAL• PLOT MESHES• PLOT POLARIZATION• PLOT RAYS• PLOT SURFACESPLOT3D (<strong>ASAP</strong> Command)Creates a 3D representation of the current distribution data file with 1D cross-sections.Function• Display/Modify Data DistributionsSyntaxPLOT3D [ s ] [ t [ r ] ]OptionstrDescriptionReadjusts the vertical scaleTilt (default 18) (see Remarks)Rotation (default 33) (see Remarks)Remarks1. Produces a 3D hidden line representation of the data and a set of 1D cross-sections on the same plot.2. The s can be used to readjust the vertical scale of the plot downward (that is, s less 1).3. The actual view is controlled by the tilt t and rotation r angles in degrees (defaults 18 and 33). Both these anglesshould be greather than 1.5 degrees and less than 90.4. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT3D Examples

<strong>ASAP</strong> | Commands and Macros (P) | 257PLOT BEAMS (<strong>ASAP</strong> Command)Plots extent of each Gaussian beam within the currently specified graphics window.Function• Analyze Ray/Beam DataSyntaxPLOT BEAMS [ 'title' ]Option'title'DescriptionOptional title for plot (up to 64 characters)Remarks1. Plots either existing parabasal ray data or internally generated, symmetric, Gaussian ray data within the windowspecified by the WINDOW command. The half-amplitude ellipses are plotted.2. May be executed at any time after the beam is constructed. Use the WINDOW command to set the plotting window.3. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.4. Use the SELECT and CONSIDER commands to restrict either the ray set or the objects.5. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR (*.vcr) file (default logicalunit 30).6. The title is delimited by single quotes ', as shown.7. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT CURVES (<strong>ASAP</strong> Command)Plots a wire-frame outline of curves, with the control points displayed, in the currently specified graphics window.Function• Setup Plots and Verify SystemSyntaxPLOT CURVES [ -n ] [ 'title' ][ k [ k' [ k" ] ] ]Optionnk k' k"'title'DescriptionPlot last n curvesRange of edges (k to k') to be plotted in "k stepsOptional title for plot (up to 64 characters)Remarks

<strong>ASAP</strong> | Commands and Macros (P) | 2581. By default, plots all currently defined curves, whether or not they are assigned to objects.2. If n is entered, the last n curves are plotted.3. If k is positive and no other entries are present, only the kth curves is plotted.4. If k and k' are present, curves k through k' are plotted.5. If k, k', and "k are all present, <strong>ASAP</strong> plots curves k through k' in steps of "k (that is, PLOT CURVES 1 5 2 tells<strong>ASAP</strong> to plot curves 1, 3, and 5).6. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.7. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).8. The title is delimited by single quotes ', as shown.9. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT EDGES (<strong>ASAP</strong> Command)Plots a wireframe outline of edges in the currently specified graphics window.Function• Setup Plots and Verify SystemSyntaxPLOT EDGES [ -n ] [ 'title' ][ k [ k' [ k" ] ] ]Optionnk k' k"'title'DescriptionPlot last n edgesRange of edges (k to k') to be plotted in "k stepsOptional title for plot (up to 64 characters)Remarks1. By default, plots all currently defined edges, whether or not they are assigned to objects.2. If n is entered, the last n edges are plotted.3. If k is positive and no other entries are present, only the kth edge is plotted.4. If k and k' are present, edges k through k' are plotted.5. If k, k', and "k are all present, <strong>ASAP</strong> plots edges k through k' in steps of "k (that is, PLOT EDGES 1 5 2 tells<strong>ASAP</strong> to plot edges 1, 3, and 5).6. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.7. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).8. The title is delimited by single quotes ', as shown.

<strong>ASAP</strong> | Commands and Macros (P) | 2599. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot, so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT ENTITIES (<strong>ASAP</strong> Command)Plots surface, edge, and lens entities in the currently specified graphics window.Function• Setup Plots and Verify SystemSyntaxPLOT ENTITIES [ -n ] [ 'title' ][ k [ k' [ k" ] ] ]Optionnk k' k"'title'DescriptionPlot last n entitiesRange of edges (k to k') to be plotted in "k stepsOptional title for plot (up to 64 characters)Remarks1. By default, plots all currently defined surface, edge, and lens entities, whether or not they are assigned to objects.2. If n is entered, the last n entities are plotted.3. If k is entered and no other entries are present, only the kth entity is plotted.4. If k and k' are entered, entities k through k' are plotted.5. If k, k', and "k are all present, <strong>ASAP</strong> plots entities k through k' in steps of "k (that is, PLOT ENTITIES 1 5 2tells <strong>ASAP</strong> to plot entities 1, 3, and 5).6. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.7. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).8. The title is delimited by single quotes ', as shown.9. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT FACETS (<strong>ASAP</strong> Command)Plots parametric mesh representation of objects in the currently specified graphics window.Function• Setup Plots and Verify System

<strong>ASAP</strong> | Commands and Macros (P) | 260Syntax 1PLOT FACETS [ n n' [ m ] ] [ REMOVE ] [ 'title' ]HIDE [ d ]Syntax 2PLOT FACETS n m [MICROSTRUCTURE nc mc|AXIS]Optionn n'mREMOVEHIDEd'title'MICROSTRUCTUREnc, mcAXISDescriptionMinimum or maximum number of subdivisions in thetwo parametric directions for each patch of an objectMaximum number of facets per objectRemoves nonessential facet edgesProduces hidden-line perspective viewViewing distance relative to the maximum lateral size(default: d=2)Optional title for plot (up to 64 characters)Plots unit cells of the microstructure that is attached tothe objectControls the number of facets on the unit cell renderingsRenders a set of local axes for the microstructure unitcellsRemarks1. Produces a parametric mesh representation of all currently defined objects in the current plot window.2. For n n', also see the FACETS command.3. If possible, the maximum number of total facets on any object is kept below m (the default is 4096; use 0 to turnoff).4. Each facet is trimmed by any BOUNDS and/or LIMITS command into, at most, an eight-sided convex polygon.Therefore, it may be necessary to increase the facet density to see the effects of fine-scale trimming.5. REMOVE can be used to remove all facet, edges from the plot except for the main patch edges and any trimmingedges. The plot this option produces is just as accurate, but is less crowded.6. For d, the default is d=2, which simulates a typical 35 mm camera lens. Use a d of 1000 to produce a nearlyparallel projection.7. Currently, the following restrictions apply to the HIDE option:• There is a limit to the total number of facets that can be processed, so you may get only a partial plot.• All objects are plotted in the same color.• The plot is always autoscaled to fill the window (or scaled window; that is, WINDOW 1.1 command beforePLOT command).• The VECTOR unit is restarted so that the previous 3D plot data is lost.• Unlike other plots, an oblique view is always true (right-handed). Therefore, OBLIQUE may not produce theexpected view.8. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.

<strong>ASAP</strong> | Commands and Macros (P) | 2619. In addition to the 2D plot that is generated, the full 3D data is written to the vector file (default logical unit 30).10. The title is delimited by single quotes ', as shown.11. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.12. Syntax 2 is for rendering microstructures. If used, <strong>ASAP</strong> renders one unit cell at the center of each facet in theobject. The size of a rendered unit cell bears no relation to the actual size of the microstructure. The rendering isonly a graphical representation of the shape and orientation of the unit cells that define the microstructure. Unitcell renderings are automatically scaled to fit within the shortest dimension of each facet.13. The number of unit cell renderings may be large if large numbers are entered for m and n on the PLOT FACETScommand. The unit cell renderings may then require excessive amounts of computer time and disk space,especially if the unit cells are complex. This may also occur if mc and nc are set to large values after theMICROSTRUCTURE option.14. The MICROSTRUCTURE and AXIS options work by reading the vector file that is produced by PLOT FACETS.This file is read by the 3D Viewer with the $VIEW command. The MICROSTRUCTURE and AXIS optionscan be exercised anytime a vector files exists, not only as options on a PLOT FACETS command. Forexample, the following pair of commands are equivalent to issuing a single PLOT FACETS command with aMICROSTRUCTURE option:PLOT FACETS m nPLOT MICROSTRUCTUREThe same applies to the AXIS option:PLOT FACETS m nPLOT AXISPLOT ExamplesPLOT LENSES (<strong>ASAP</strong> Command)Plots lenses in the currently specified graphics window.Function• Setup Plots and Verify SystemSyntaxPLOT LENSES [ -n ] [ 'title' ][ k [ k' [ k" ] ] ]Optionnk k' k"'title'DescriptionPlot last n lensesRange of edges (k to k') to be plotted in "k stepsOptional title for plot (up to 64 characters)Remarks1. By default, plots all lenses in the current database, whether or not they are assigned to objects.

<strong>ASAP</strong> | Commands and Macros (P) | 2622. If n is negative, the last n lenses are plotted.3. If k is positive and no other entries are present, only the kth lens is plotted.4. If k and k' are present, lenses k through k' are plotted.5. If k, k', and "k are all present, <strong>ASAP</strong> plots lenses k through k' in steps of "k (that is, PLOT LENSES 1 5 2 tells<strong>ASAP</strong> to plot lenses 1, 3, and 5).6. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.7. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).8. The title is delimited by single quotes ', as shown.9. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT LIMITS (<strong>ASAP</strong> Command)Plots a wireframe box denoting the extent of the specified objects limits box in the currently specified graphicswindow.Function• Setup Plots and Verify SystemSyntaxPLOT LIMITS [ 'title' ]Option'title'DescriptionOptional title for plot (up to 64 characters)Remarks1. By default, plots the limit boxes of all currently defined objects. Only CONSIDERed objects are drawn.2. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.3. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).4. The title is delimited by single quotes ', as shown.5. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT LOCAL (<strong>ASAP</strong> Command)Plots local boxes of surface entities.Function• Setup Plots and Verify System

<strong>ASAP</strong> | Commands and Macros (P) | 263SyntaxPLOT LOCALS [ -n ] [ 'title' ][ k [ k' [ k" ] ] ]Optionnk k' k"'title'DescriptionPlot the local boxes of last n surfacesRange of edges (k to k') to be plotted in "k stepsOptional title for plot (up to 64 characters)Remarks1. By default, plots the local boxes of all currently defined surfaces, whether or not they are assigned to objects.2. If n is entered, the local boxes of the last n surfaces are plotted.3. If k is entered and no other entries are present, only the local box of the kth surface is plotted.4. If k and k' are entered, the local boxes of surfaces k through k' are plotted.5. If k, k', and "k are all present, <strong>ASAP</strong> plots the local boxes of surfaces k through k' in steps of "k (that is, PLOTLOCAL 1 5 2 tells <strong>ASAP</strong> to plot the local boxes of surfaces 1, 3, and 5).6. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.7. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).8. The title is delimited by single quotes ', as shown.9. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT MESHES (<strong>ASAP</strong> Command)Plots all currently specified objects using a wireframe mesh.Function• Setup Plots and Verify SystemSyntaxPLOT MESHES [ m ] [ 'title' ]Optionm'title'DescriptionInterpolation curves between segmentsOptional title for plot (up to 64 characters)Remarks1. Plots a wireframe mesh for each currently specified OBJECT.2. The m is the number of interpolation curves between segments of an object mesh (wireframe). It can be 0, 1 (thedefault), or 2.

<strong>ASAP</strong> | Commands and Macros (P) | 2643. BOUNDS or LIMITS do not trim plotted meshes. However, BOUND edges for an object are also shown.4. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.5. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).6. The title is delimited by single quotes ', as shown in the syntax.7. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT POLARIZATION (<strong>ASAP</strong> Command)Plots polarization state ellipses.Function• Create Rays and Beams• Analyze Ray/Beam DataSyntaxPLOT …POLARIZATION [ e ] [ 'title' ] …Optione'title'DescriptionSize of the ellipses is proportional to the ray/beam's fluxraised to the "e" power.Optional title for plot (up to 64 characters)RemarksCAUTION: The SOURCE propagation direction must be initialized before running PLOT POLARIZATION, or thecommand does not plot anything.1. The polarization state ellipses for each ray/beam are plotted. The size of the ellipses is proportional to the ray/beam's flux raised to the e (default 1) power.2. Arrows are drawn to show the handedness of the polarization state. In the case of linear polarization, arrows aredrawn on both ends of the degenerate ellipse. The size of the tip of the arrow used to show the handedness of thepolarization is determined by the overall size of the polarization ellipse. At times it might be necessary to use theARROW command to scale the tip for better visibility.3. In Jones vector mode, PLOT POLARIZATION e, when e is less than 0, the program invokes the Poincare SphereVisualization Tool (PSVT) to visualize the polarization state in forms of Stokes vector. In Stokes vector mode,PLOT POLARIZATION always uses the PSVT to visualize the polarization state.4. May be executed at any time after the beam is constructed.5. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.6. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).7. The title is delimited by single quotes ', as shown.

<strong>ASAP</strong> | Commands and Macros (P) | 2658. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT RAYS (<strong>ASAP</strong> Command)Plots vectors along the direction of each ray that is contained within the currently specified graphics window.Function• Analyze Ray/Beam DataSyntaxPLOT RAYS d [ i ] [ 'title' ]Optiondi'title'DescriptionScale factor for ray plot vectorPlot only every ith rayOptional title for plot (up to 64 characters)Remarks1. Plots a line from the current position of each ray along its direction vector. The actual distance plotted is d timesthe flux of the ray divided by the maximum ray flux.2. If d is entered as a negative number, only the endpoint of this vector is plotted. This structure is useful forproducing 3D far-field intensity distribution point clouds if d is much larger than any inter-ray distance. Thedefault for d is approximately 1/10th the window size.3. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.4. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).5. The title is delimited by single quotes ', as shown.6. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT RAYS ExamplesPLOT SURFACES (<strong>ASAP</strong> Command)Plots surfaces in the currently specified graphics window.Function• Trace Rays/BeamsSyntaxPLOT SURFACES [ -n ] [ 'title' ][ k [ k' [ k" ] ] ]

<strong>ASAP</strong> | Commands and Macros (P) | 266Optionnk k' k"'title'DescriptionPlot last n surfacesRange of edges (k to k') to be plotted in "k stepsOptional title for plot (up to 64 characters)Remarks1. By default, plots all currently defined surfaces, whether or not they are assigned to objects.2. If n is entered, the last n surfaces are plotted.3. If k is entered and no other entries are present, only the kth surface is plotted.4. If k and k' are entered, surfaces k through k' are plotted.5. If k, k', and "k are all present, <strong>ASAP</strong> plots surfaces k through k' in steps of "k (that is, PLOT SURFACES 1 5 2tells <strong>ASAP</strong> to plot surfaces 1, 3, and 5).6. WINDOW, WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinatesystem. Use WINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handedcoordinate system.7. In addition to the 2D plot that is generated, the full 3D data is written to the VECTOR file (default logical unit30).8. The title is delimited by single quotes ', as shown in the syntax.9. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.PLOT ExamplesPLOT (<strong>ASAP</strong> Command Argument)Plots the current model.Syntax... [ PLOT [ a a' ... ] [ OVERLAY ] ]Optiona a'DescriptionSpecular anglesRemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. Plots the model's BSDF for up to seven specular angles in ascending order (default 0, 15, 30, 45, 60, 75, 89.9degrees). A unit reflectivity surface in the current IMMERSE medium and at the current WAVELENGTHS isassumed when a model is plotted.3. The current PIXELS setting controls the resolution of these plots in direction cosine space.4. For the default angles and a model sharply peaked at specular, the optimum setting for PIXELS is 580.5. Optionally, the multiple graphs plotted can be OVERLAYed into separate quadrants. If the angles a a' … areexplicitly given, PLOT also creates a full-hemispherical 2D distribution file, "name_angle.DIS", for each of thespecular angles.6. Otherwise, the command argument, PLOT creates a 3D distribution file, name.dis, for each of these angles.7. Use command argument, OVERLAY to plot multiple graphs into separate quadrants.8. Assumes a unit reflectivity surface in the current IMMERSE media and at the current WAVELENGTH when a modelis plotted.PLOT Examples

<strong>ASAP</strong> | Commands and Macros (P) | 267$PLOT (<strong>ASAP</strong> Macro)Used to control screen graphics and plots.Syntax$PLOT [ OFF ]ASKEACHNORMOptionno argumentOFFASKEACHNORMDescriptionImmediately processes all the plots in the current 2D plotfile using the operating system command defined withthe PLOTTER switch or environment variable.Suppresses screen graphicsPrompts at end of each screen for plotting and/or savingPlots each screen without promptingRestores default (screen graphics and no prompting)$PLOT ExamplesPOINTS (2D) (<strong>ASAP</strong> Command)Creates a generalized planar edge.Function• Define/Modify Curvedge Entities• Define/Modify Surfunc EntitiesSyntaxPOINTS X x y z q [ y' z' q' ... ]Y y z x z' x'Z z x y x' y':OptionDescriptionX, Y or Z Specifies coordinate axisx, y or z Specifies location along coordinate axisy z (z x or x y), y' z' ...Coordinates of point in orthogonal axesq q' ...Connection parameters<strong>Reference</strong> PointOrigin of the coordinates

<strong>ASAP</strong> | Commands and Macros (P) | 268AutolimitingYesRemarks1. Edges consist of a coplanar straight line and/or higher-order curved segments.2. Initially, the reference point is the specified axial location and, therefore, not necessarily on the edge.3. Directly inputs the coordinates of a collection of planar points.4. The q parameters control how each edge point is connected to the next, as described in the following table.q PARAMETEREDGE POINT CONNECTIONq=0 Not connected to the next point (open)q=1 Connected by a straight line to the next pointq=2 Connected by a quadratic rational Bezier (conic)curve to the point after next. The next point isthe intermediate control vertex. The next q is theintermediate weighting factor and is always positive:q=-2q=n0 straight line1 hyperbolaConnected by an elliptical arc to the point after next.The next point is the center of the parent ellipse. Thenext q is the angular subtense (in degrees) of the arcand must be less than 180 degrees.Connected by an nth (up to 10th) degree rationalBezier curve. The intermediate n-1 points are controlvertices with given (positive) weight factors.5. A nonzero q for the last point tells <strong>ASAP</strong> to connect this point to the first point making a closed curve. However,if the first q entry is a literal, the second point entered is the first point on the edge. All other points are measuredeither ABSolutely or RELatively from the reference point.6. The first point entered is always the reference point for the edge, and is normally the first point on the actual edge.7. The POINT command, analogous to the GENERAL and SEQUENCE commands, is the most generalimplementation of <strong>ASAP</strong> edges. Although the POINT command is useful for modeling simple systems, especiallywhen used with the SWEEP command, its primary purpose is to serve as an input form for the output of the IGESto <strong>ASAP</strong> translator.8. Edge objects ray trace slower than surface or lens objects because of the parametric nature of the edge objects.This edge is a combination of coplanar straight line and higher-order curved segments.POINTS ExamplesPOINTS (3D) (<strong>ASAP</strong> Command)Creates a generalized edge.Function• Define/Modify Curvedge Entities• Define/Modify Surfunc Entities

<strong>ASAP</strong> | Commands and Macros (P) | 269SyntaxPOINTS x y z q [ x' y' z' q'... ]ABSREL[ x" y" z" q" ... ]:Optionx y z [x' y' z' ...]q [q' ...]ABSRELDescriptionCoordinates of pointsConnection parametersMeasure all points in the global coordinate systemMeasure all points RELative to the reference point<strong>Reference</strong> PointOrigin of the coordinatesRemarks1. Use to input the coordinates of edge points directly.2. The q parameters control how each edge point is connected to the next, as described in the following table.q PARAMETEREDGE POINT CONNECTIONq=0 Not connected to the next point (open)q=1 Connected by a straight line to the next pointq=2 Connected by a quadratic rational Bezier (conic)curve to the point after next. The next point isthe intermediate control vertex. The next q is theintermediate weighting factor and is always positive:q=-2q=n0 straight line0.5 circular1 hyperbolaConnected by an elliptical arc to the point after next.The next point is the center of the parent ellipse. Thenext q is the angular subtense (in degrees) of the arcand must be less than 180 degrees.Connected by an nth (up to 10th) degree rationalBezier curve. The intermediate n-1 points are controlvertices with given (positive) weight factors.3. A nonzero q for the last point tells <strong>ASAP</strong> to connect this point to the first point making a closed curve. However,if the first q entry is a literal, the second point entered is the first point on the edge. All other points are measuredeither ABSolutely or RELatively from the reference point.4. The first point entered is always the reference point for the edge and is normally the first point on the actual edge.

<strong>ASAP</strong> | Commands and Macros (P) | 2705. If ABS or REL are entered (instead of the first q), the second point entered is the first point on the edge, and it andall other points are measured either ABSolutely in the global coordinate system, or RELatively from the referencepoint.6. The POINT command, analogous to the GENERAL and SEQUENCE commands, is the most generalimplementation of <strong>ASAP</strong> edges. Although the POINT command is useful for modeling simple systems, especiallywhen used with the SWEEP command, its primary purpose is to serve as an input form for the output of the <strong>ASAP</strong>to IGES translator.7. Edge objects ray trace slower than surface or lens objects because of the parametric nature of the edge objects.POINTS ExamplesPOLARIZ (<strong>ASAP</strong> Command)Sets the polarization properties for future ray creation.Function• Setup Beam CreationSyntaxPOLARIZ X [ a a' ]YZOFFOptionDescriptionX, Y, or Z Coordinate axisa a'OFFRemarksComplex amplitudesFlag to turn polarization direction off1. Sets the polarization direction and optionally the complex amplitudes of the two orthogonal polarizationcomponents of rays, for future ray creation (RAYSET and GRID) and analyses (SPREAD and FIELD).2. Initializes the complex coefficients a and a'> for the two orthogonal components.3. POLARIZ selects the E field direction in the FIELD command. The E field is parallel to the specified coordinateaxis.4. Must precede the GRID , RAYSET, FIELD, and SPREAD commands, since it is a physical property of the rays.5. The FRESNEL BOTH command should be used in conjunction with POLARIZ to configure the system geometryto include polarization effects.6. A transverse optical field can be written as:where and are orthogonal real (linear) unit vectors, and the wave-vector

<strong>ASAP</strong> | Commands and Macros (P) | 271gives the propagation direction of the field. The POLARIZ command allows specification of complex amplitudesa and a' to represent the polarization of the electric field. The unit vectoris parallel to the coordinate axisspecified by the parameter immediately before a. The unit vectoreach subsequently defined source to satisfy the transverse condition,is derived from the propagation direction ofthat is to say,7. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns when this occurs.Modifications do not permanently change the POLARIZ settings.8. SHOW presents the complete complex coefficients of POLARIZ.POLARIZ ExamplesPOLARIZ K (<strong>Reference</strong> Ray Direction) (<strong>ASAP</strong> Command)Sets the direction of the polarization reference ray.SyntaxFunction• Create Rays and BeamsPOLARIZ K [a b c]POLARIZ K [X|Y|Z]OptionKa b cDescriptionSetting reference ray direction for the non-collimatedraysDirection cosine of the reference ray. Alternatively, youcan specify a global axis as a reference ray direction.POLARIZ K Examples

<strong>ASAP</strong> | Commands and Macros (P) | 272POLARIZ MODE (<strong>ASAP</strong> Command)Sets the polarization mode.Function• Create/Modify ObjectsSyntaxPOLARIZ MODEPOLARIZ MODE 1|2POLARIZ MODE JONES|STOKESOptionDescription1|2 1 to set Jones vector mode, 2 to set Stokes vector modeJONES|STOKESRemarks1. POLARIZ MODE without any argument prints out the current polarization mode.2. Stokes vector mode requires that the FRESNEL setting must be BOTH.JONES to set Jones vector mode, STOKES to set Stokesvector modeNote: Do not change polarization mode during ray tracing; if you do, your results will be unexpected.3. The default polarization state in Stokes vector mode is [1 1 0 0 ], which is x-polarized, as in Jones vector mode.POLARIZ MODE ExamplesPOLARIZ (Polarization Vector) (<strong>ASAP</strong> Command)Sets the polarization vector in a ray local polarization coordinate system.Function• Create Rays and BeamsSyntaxPOLARIZ a a'Optiona a'DescriptionTwo complex numbers for two orthogonal componentsof the polarization vector.Remarks1. Before using this command, the reference ray direction and the transverse polarization reference direction must beset by issuing POLARIZ K and POLARIZ TREF commands.POLARIZ (Polarization Vector) Examples

<strong>ASAP</strong> | Commands and Macros (P) | 273POLARIZ RANDOM (<strong>ASAP</strong> Command)Randomizes the polarization state vector of the rays.Function• Create/Modify ObjectsSyntaxPOLARIZ RANDOM ON|OFFPOLARIZ RANDOM UNIFORM|GAUSSIAN e1 e2 θ1 θ2 p1 p2 [DoP1 DoP2]OptionsDescriptionPOLARIZ RANDOMONOFFUNIFORM|GAUSSIANRandomize the polarization state of a ray in terms of itsellipticity, the orientation angle of the principle axis andits initial phase (ellipticity based randomization).<strong>ASAP</strong> uses ellipticity based polarization randomizationof uniform distribution with default values for futuresource creation. See Remarks for default values.For backward compatibility to <strong>ASAP</strong> originalpolarization randomization method."UNIFORM" refers to uniform random distribution and"GAUSSIAN" refers to Gaussian distribution.e1, e2 Random function parameters for the ellipticity of thepolarization state. The default values for e1 and e2 are 0and 1, respectively.01, 02 Random function parameters for the orientation angle ofthe principle axis relative to the x axis of the transversepolarization reference coordinate.p1, p2 Random function parameters for the initial phase of thepolarization state.DoP1, DoP2RemarksRandom function parameters for the degree ofpolarization. These two parameters are only valid inStokes vector mode. See Remarks.1. Polarization randomization is built on the concept of the reference ray. Before issuing the POLARIZ RANDOMcommand, the reference ray direction and the polarization transverse reference direction of the reference ray mustbe specified.2. In Jones vector mode, the POLARIZ RANDOM command randomizes the polarization state of a ray in terms of itsellipticity, the orientation angle of the principle axis and its initial phase (ellipticity based randomization).3. In Stokes vector mode, the POLARIZ RANDOM command randomizes the Stokes vector by first decomposingit into unpolarized and completely polarized parts, and then combining them. <strong>ASAP</strong> randomizes the completelypolarized part in the same way as in the Jones vector mode. In addition, <strong>ASAP</strong> randomizes the degree ofpolarization for the unpolarized part.4. The polarization states of the rays of all sources created by the SOURCE command (SOURCE POS, SOURCEDIR, etc.) can be randomized.

<strong>ASAP</strong> | Commands and Macros (P) | 2745. The polarization states of the rays of all sources created by the EMITTING command (including EMITTINGBOX/SPHERE, EMITTING FILAMENT, EMITTING HELIX, EMITTING OBJECT, EMITTINGDATA, and so on) can also be randomized.6. For UNIFORM distribution, e1 and e2 specify the minimum and maximum of the range in which the ellipticitycan randomly vary.7. For GAUSSIAN distribution, e1 is the mean value and e2 is the standard deviation of the distribution function.Note: Since the Gaussian distribution function is not bounded in [-1, 1], if the randomly generatedellipticity is out of the range of [-1, 1], <strong>ASAP</strong> clips the ellipticity to the nearest bound value.8. For UNIFORM distribution, θ1 and θ2 specify the minimum and maximum of the range in which the orientationangle can randomly vary. The default values for θ1 and θ2 are -180° and 180° respectively.9. For GAUSSIAN distribution, θ1 is the mean value and θ2 is the standard deviation of the distribution function. Thedefault values for θ1 and θ2 are 0 and 90°, respectively.10. For UNIFORM distribution, p1 and p2 specify the minimum and maximum of the range in which the initial phasecan randomly vary. This is useful for modeling partially coherent light. The default values for p1 and p2 are 0 and360° respectively.11. For GAUSSIAN distribution, p1 is the mean value and p2 is the standard deviation of the distribution function.Both default values for p1 and p2 are 180° respectively.12. For UNIFORM distribution, DoP1 and DoP2 specify the minimum and maximum of the range in which thedegree of polarization can randomly vary. The default values for DoP1 and DoP2 are 0 and 1 respectively.13. For GAUSSIAN distribution, DoP1 is the mean value and DoP2 is the standard deviation of the distributionfunction. Both default values for DoP1 and DoP2 are 0.5.POLARIZATION RANDOM ExamplesPOLARIZ TREF (Transverse <strong>Reference</strong> Direction) (<strong>ASAP</strong> Command)Sets the polarization coordinate system's transverse reference direction.Function• Create Rays and BeamsSyntaxPOLARIZ TREF [a b c]POLARIZ TREF [X|Y|Z]POLARIZ TREF AUTOOptionTREFa b cAUTODescriptionPolarization transverse direction for the reference rays.Direction cosine in the global coordinate of thepolarization transverse reference direction for thereference ray. This option can be global X, Y, Z.<strong>ASAP</strong> automatically determines the local transversereference polarization axis with a process similar toconformal wrapping; that is, directly aligning globalZ axis to the reference ray direction with a minimumrotation.Remarks1. <strong>ASAP</strong> enforces the orthogonality between the reference ray direction and polarization transverse referencedirection.

<strong>ASAP</strong> | Commands and Macros (P) | 275POLARIZATION TREF ExamplesPOLYNOMIAL/TRINOMIAL/BINOMIAL (<strong>ASAP</strong> Command)Creates a scatter model based on user-supplied data or polynomial coefficients.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax 1 - Polynomial coefficientsPOLYNOMIAL n m [ l [ l' [ d ] ] ] [ PLOT [ a a' ... ] ]TRINOMIALBINOMIALc [ c' c" ... ]Syntax 2 - Data fittingPOLYNOMIAL n m [ l [ l' [ d ] ] ] FIT [ k ] [ options…]TRINOMIALSVDBINOMIALdata...:Optionn m l l'dc c' c" ...PLOTFITkSVDf [f' ...]DescriptionSumming indicesLogarithmic coefficientPolynomial coefficientsPlots the model in log(b-bo) and angle spaceFIT the BSDF values of the polynomial modelUse every kth value in the FIT (default is to use everyentered BSDF value)Using the singular value decomposition (SVD)algorithm, FIT the BSDF values to the polynomialmodelEither the actual BSDF values or the common LOG ofthe BSDFRemarks1. Models scattering is described by a general polynomial of three symmetry variables. In this formalism, scatteringfrom an isotropic surface must be symmetric with regard to the plane of incidence and surface normal. Symmetryproperties are guaranteed if the BSDF is only a function of the following variables:2. The α and β are the direction cosine coordinates of scatter direction; the (0,βo) is the specular direction. Note thatthe distance squared (in direction cosines) from specular is given by

<strong>ASAP</strong> | Commands and Macros (P) | 2763. The scattering is modeled by a general polynomial of 2 or 3 symmetry variables with coefficients c ... (up to 286);that is:POLYNOMIALTRINOMIALBINOMIAL4. If m is entered as a negative number, the upper limit of the second sum becomes |m|-k. The coefficients areentered in the order in which they appear in the previous equations for the given n m l l'.5. Note that if d is zero, all the Lorentzian (log specular) terms vanish.6. If FIT or SVD is entered, <strong>ASAP</strong> fits the user-supplied BSDF data to the specified polynomial form. Under the SVDoption, a limited number of data points can be fitted. (See DIMENSIONS command output.)7. By default, every BSDF value entered (above 1.E-9, -9 LOG) is used in the fit. Optionally, only every kth valuecan be used.8. The restricted variables used in the BINOMIAL form and the term symmetry in the POLYNOMIAL form assurethat the resulting BSDF exactly obeys reciprocity. The TRINOMIAL form is not, by definition, reciprocal; but,during a FIT, it replicates each input point by interchanging the specular and scatter directions. This in effect triesto force the resulting BSDF to obey reciprocity.

<strong>ASAP</strong> | Commands and Macros (P) | 2779. If the peak of the BSDF remains nearly centered on all specular directions (as is the case for relatively smooth orglossy surfaces), or if only in-plane data is available, try the following Lorentzian-only fit:POLYNOMIAL n 0 14 -4 2. FITTRINOMIALBINOMIALwhere n is less than or equal to the number of non-normal incident directions in the data. This generates a modelwith 20(n+1) coefficients. Confirm that there are at least as many BSDF values (a few times more is better).10. Another more general technique is to use $ITER to do a "regressive" fit. For example:$ITER N 1 5 -5, M 1 5 -5, E{ MODEL 1BINOMIAL INT[N] INT[M] SVD:data:RETURN$GRAB 'RMS=' E }11. The PLOT option plots the model (common base 10 logarithm of the BSDF) for up to seven specular angles inascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls the resolutionof these plots in direction cosine space.12. Creates a distribution file name_angle.dis for each of these angles.13. The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.14. Use with importance area sampling.POLYNOMIAL Examples BINOMIAL Examples TRINOMIAL ExamplesPostScript File Utility (PSCRIP) (<strong>ASAP</strong> Command)The PSCRIP.exe utility reads <strong>ASAP</strong> PLR (plot) files and creates PostScript files for printing. The utility is stored inyour <strong>ASAP</strong> installation area under the \bin folder.Syntax 1PSCRIPSyntax 2PSCRIP ‘file’ is an input text file of six lines with this content:plrnames'printer'cp[blank line]

<strong>ASAP</strong> | Commands and Macros (P) | 278OptionplrnameDescriptionName of a file with an extension .plr that contains theplots stored in the file, asaptemp.plrs Scaling factor (1 = 1 plot on a printed page; .5 creates 2x 2 plots on a page, and so on)‘printer’cNetwork name of a PostScript printer, or name of adirectly attached printercolors:1 = Different thicknesses instead of colors2 = Old BRO colors3 = Colors from xtermc utility4 = New BRO colorsp[blank line]Page orientation (L = landscape, P = portrait)A required blank line at the end of the fileRemarks1. In Syntax 1, you are prompted for input to satisfy the same options in file.2. In Syntax 2, the options are all given in the text file, file.PSCRIP ExamplesPRINT (<strong>ASAP</strong> Command)Prints out specific database information.Function• Setup Plots and Verify SystemSyntaxPRINT [ i ]SPRINT SURFACE [ i ]QPRINT EDGELENSALLMEDIACOATINGMODELOBJECTOptionPRINTSPRINTQPRINTDescriptionPrints complete information for the specified databaseExcludes the main geometry data (that is, coefficients,conicoids, points) from the print outPrints only one line per entity

<strong>ASAP</strong> | Commands and Macros (P) | 279OptioniSURFACE, EDGE, LENS, ALL, MEDIA, COATING,MODEL, OBJECTDescriptionEntity numberSpecific databaseRemarks1. Prints database information.2. If the entity number is omitted, all the information in the given database is printed.Examples1. Output for a Surface/Object--- MEDIA--- 4.03 'GERMANIUM'--- COATING PROPERTIES--- 0 1 'TRANS'--- SURFACE--- PLANE Y -5 ELLIPSE 0.5--- OBJECT 'LENS_SURF_1--- INTERFACE COATING TRANS AIR GERMANIUM--- SURFACE--- OPTICAL Y -4.7 -1 -16.241 ELLIPSE 0.5--- OBJECT 'LENS_SURF_2--- INTERFACE COATING TRANS AIR GERMANIUM--- PRINT 2SURFUNC 2: Degr=2x2(OPTICAL ) X 0.00000 Y -4.70000 Z 0.00000Branch Test sign and direction 1. 0.00000 1.00000 0.00000RefPt Ave Radius -1.0000 Normal 0.0000000 1.00000000.0000000Local Box X -.5000 0.5000 Y -.7879E-1 0.5000E-3 Z -.5000 0.5000width= 1.0000 width= 0.79291E-1 width= 1.0000Cylindrical along Y axis with central ratio 0.00000Parameterization -YThis entity used by objects 2Polynomial Coefficients:x2 0.500000 y 1.00000 z2 0.500000 y2 -7.62050OBJECT 2: LENS_SURF_2Physical Surface 2 (OPTICAL )Faceting (patch subdivision) -3 by -3Box X -.5000 0.5000 Y -4.789 -4.689 Z -.5000 0.5000width= 1.0000 width= 0.99291E-1 width= 1.0000Bounding sphere 0.502459 0.00000 -4.739150.00000Coating 1 at 0.000 wavelengthTransmission 1.0000 Media 0 1MEDIA Index/Absorb FUNC: exponent steplength maxnum0 1.000000 0 1.00000 0.100000E+16 1000 VACUUM|AIR1 4.030000 0 1.00000 0.100000E+16 1000 GERMANIUMWavelengths 0.000COATING NameR 1 T1 TRANS 0.0000 1.000KEY TO OUTPUT:

<strong>ASAP</strong> | Commands and Macros (P) | 280SURFUNCDegr= Entity identifier & data base location= Order of the polynomial surface/function equationX, Y, Z = Coordinates of reference pointLocal AveNormalLocal BoxPolynomialOBJECTPhysicalBoxCoatingTrans2. Output for Edge ObjectsKEY TO OUTPUT:CURVEDG= Base radius of curvature= Surface/function normal direction vector in directioncosines= Extents & widths of the LOCAL box in localcoordinates= Polynomial coefficients of surface/function= Object data base location & name= Entity number used by the object= Extents & widths of the LIMIT box in globalcoordinates= Coating number & wavelength used by theINTERFACE command= R & T coefficient values & media surrounding theinterface= Entity identifier & data base locationx, y, z = Coordinate of curve/edge pointsq= Previous point to next point connection factor--- COATING PROPERTIES--- 0.05 0 'REFL'--- EDGES--- RECTANGLE Y 4 1 .5--- RECTANGLE Y 12 3 1.5--- OBJECT--- 0.1 0.2 'FACETED_TUBE'--- INTERFACE COATING REFL--- PRINT 1CURVEDG 1: Pts=4 (RECTANGL) X 0.00000 Y 4.00000 Z 0.000004 segments of degree 14 total with 0 breaksSweep distance & direction 0.000 0.00000 1.000000.000000.00000 4.000000.00000This entity used by objects 1Points and Connection Factors:x y z q x y z q-0.500000 0.000000 1.000000 1.00000 0.500000 0.000000 1.0000001.000000.500000 0.000000 -1.000000 1.00000 -0.500000 0.000000 -1.0000001.00000

<strong>ASAP</strong> | Commands and Macros (P) | 281CURVEDG 2: Pts=4 (RECTANGL) X 0.00000 Y 12.0000 Z 0.000004 segments of degree 14 total with 0 breaksSweep distance & direction 0.000 0.00000 1.000000.000000.00000 12.00000.00000This entity used by objects 1Points and Connection Factors:x y z q x y z q-1.500000 0.000000 3.000000 1.00000 1.500000 0.000000 3.0000001.000001.500000 0.000000 -3.000000 1.00000 -1.500000 0.000000 -3.0000001.00000OBJECT 1: FACETED_TUBEPhysical Surface 2 (RECTANGL) to 1 (RECTANGL)1 segments of degree 11 total with 1 breaksFaceting (patch subdivision) +1 by +1Box X -1.580 1.580 Y 3.920 12.08 Z -3.080 3.080width= 3.1600 width= 8.1600 width= 6.1600Bounding sphere 5.35063 0.596046E-07 8.000000.00000Coating 1 at 0.000 wavelengthInterface Reflectivity 0.50000E-01Wavelengths 0.000COATING NameR 1 T3. Output for Lens Objects--- UNITS IN--- WAVELENGTHS 486 587 656 NM--- LENSES--- DOUBLET Z 0 1.5 2 SCHOTT_BK7 SCHOTT_F2 10 1 36.6/64.2Dispersion (and power) ratio = 0.5700935--- OBJECT 'DOUBLET'--- PRINT 1LENS 1: Srfs=3 (DOUBLET ) X 0.00000 Y 0.00000 Z 0.00000This entity used by objects 1Conicoid Data:X Y Z A B C1 0.00000 0.00000 0.00000 0.000000 0.000000 1.000000APT= 2.000 CRV=0.231506 CON= 0.0000 OBS=.0000 MED= 1 schott_BK72 0.00000 0.00000 1.35000 0.000000 0.000000 1.000000APT= 2.000 CRV=-.209587 CON= 0.0000 OBS=.0000 MED= 2 schott_F23 0.00000 0.00000 1.50000 0.000000 0.000000 1.000000APT= 2.000 CRV= 0.00000 CON= 0.0000 OBS=.0000 MED= 0 VACUUM|AIROBJECT 1: DOUBLETPhysical Surface 1 (DOUBLET )Faceting (patch subdivision) -3 by -3Box X -2.040 2.040 Y -2.040 2.040 Z -.4000E-1 1.540width= 4.0800 width= 4.0800 width= 1.5800Bounding sphere 2.99120 0.00000 0.000000.750000Interface Reflectivity 1.0000Transmission 1.0000 Media 0 0MEDIA Index/Absorb FUNC: exponentsteplength maxnum

<strong>ASAP</strong> | Commands and Macros (P) | 2820 1.000000 0 1.00000 0.100000E+16 1000 VACUUM|AIR1 1.522386 0 1.00000 0.100000E+16 1000 schott_BK72 1.632103 0 1.00000 0.100000E+16 1000 schott_F2Wavelengths 486.0 587.0 656.0MEDIA Name Re 1 Im Re 2 Im Re 3 Im1 schott_BK7 1.522386 1.516824 1.5143312 schott_F2 1.632103 1.620089 1.615049KEY TO OUTPUT:LENS= Entity identifier & data base locationSrfs= Number of conicoids of lensX, Y, Z = Coordinates of reference pointConicoid Data:X, Y, Z = Coordinates of first conicoidA, B, C = Conicoid normal direction vector in direction cosinesAPTCRVCONOBSMED= Conicoid aperture semi-diameter= Conicoid base curvature= Conicoid conic constant= Conicoid obscuration ratio= Media after conicoidPRINT ExamplesPRINT (Polarization Models) (<strong>ASAP</strong> Command)Prints defined surface polarization modifiers.Function• Create Rays and BeamsSyntaxPRINT [I]PRINT MODEL {JONES|RPM|CPE|PM} [j]OptionJONES|RPM|CPE|PMIjDescriptionSpecifies the type of the polarization interface modelsto be printed. PM represents the surface PolarizationModifier.Ith objectList index of the model to be printed in the systemdefinedlist of the desired polarization interface model

<strong>ASAP</strong> | Commands and Macros (P) | 283OptionDescriptiontype. If no I is present, <strong>ASAP</strong> prints all models of thespecified polarization interface.Remarks1. PRINT command without argument prints all polarization interface models along with other system databaseinformation.2. By default, PRINT MODEL prints all scatter models and polarization interface models.3. Relative indexing is supported when referring to individual polarization interface models.4. For the PRINT I command, the polarization interface model of the specified object is printed along with all otherproperties of the object.PRINT (Polarization Models) ExamplesPROFILES (<strong>ASAP</strong> Command)Plots slices through objects contained within the specified graphics window.Function• Setup Plots and Verify SystemSyntaxPROFILES [ f f' n ] [ NOOPTIMIZE ] [ QUICK ] [ 'title' ]Optionf f'nNOOPTIMIZEQUICK'title'DescriptionRange of the third depth coordinateNumber of the third depth coordinateGenerates the original raw plot commandsTurns off exact boundary clipping to speed up the plotOptional title for plot (up to 64 characters)Remarks1. Basic system plot command for <strong>ASAP</strong> that is valid for all types of objects.2. PROFILES draws the system by tracing grids of rays through the plotting volume. The number of rays (and,hence, the spatial resolution) is determined from the PIXELS command. At the intersection of a ray and an object,a tick mark is drawn at an angle that corresponds to the slope of the object at that point. A complete system plotis therefore built up from these tick marks. All objects are considered to be transparent during the generation of aprofile(s).3. Two common commands for producing pictures are:PROFILES d d' n for plotting slices of each object by planes parallel to the window and between the depthcoordinates d and d'. (To improve resolution, increase the number of PIXELS and the number of slices n.)PLOT FACETS n n' for plotting a 3D mesh (set resolution by entering values for n, n'), and m.4. The n is the number of cross-sectional slices through the current set of objects that are plotted within the range ofthe third depth coordinate f to f' (the depth coordinate that is not specified on the last WINDOW command).5. If n is negative, then f f' are ignored on objects with LOCAL/LIMITS, and n equally spaced slices are madeacross the individual local/limits ranges of those objects. If n is positive, then n equally spaced slices are madeacross the plotting volume. An object appears on the plot only if a slice intersects the object. In most cases, it isbest to use a negative value for n.

<strong>ASAP</strong> | Commands and Macros (P) | 2846. The default for n is -1 when OBLIQUE is off and -5 when it is on.7. If n is negative, f f' are ignored on objects with LOCAL/LIMITS, and n equally spaced slices are made across theindividual local/limits ranges of those objects. If n is positive, n equally spaced slices are made across the plottingvolume. An object appears on the plot only if a slice intersects the object. Always use a negative value for n unlessthere is a valid reason not to do so.8. WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinate system. UseWINDOW X -Z, WINDOW Y -X, or WINDOW Z -Y to display the system in a right-handed coordinate system.9. Use the command argument, XY[Z] to explicitly set the window limits without affecting a previously declaredWINDOW definition. For example:SPOTS DIRECTION YX -4@1, orSPOTS POSITION YZ -2@1 -2@210. The title is delimited by a single quote ', as shown.11. The command argument, OVERLAY tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.12. Technique for rapidly plotting 3D geometry:WINDOW Y ZPROFILES 0 0 -11WINDOW Y XPROFILES 0 0 -11WINDOW X ZPROFILES 0 0 -11PROFILES ExamplesPUT (<strong>ASAP</strong> Command)Copies variable data into the current ray data.Function• Modify or Use Internal Ray/Beam Data as InputSyntaxPUT kOptionkDescriptionNumber of a given rayRemarks1. Puts the current values in the input registers into the storage locations for ray k.2. Input register assignmentsinclude:Register Literal Ray/Beam DataA0,B0,C0 X,Y,Z_DIR_B Absolute X,Y,Z direction cosines ofbase rayAi,Bi,Ci X,Y,Z_DIR_i Relative direction vector of ithparabasal ray

<strong>ASAP</strong> | Commands and Macros (P) | 285Register Literal Ray/Beam DataD0 OPL Optical path length from start ofbase rayE1,E2,E3 X,Y,Z_EPOL Components of unit polarizationvectorF0 FLUX Total flux in ray/beamG0 DIVERG Average divergence angle of beamH0 HEIGHT Average height of beam centered onbase rayLi PREV_O_i ith previous split object for ray/beamJ0 SOURCE Source number from which ray/beam originatedK0 CURR_OBJ Current object at which ray/beam islocatedL0 HITS Total number of surfaces ray has hit(intersected)M0 MEDIUM Medium that ray/beam is inN0 SPLITS Number of times ray/beam is splitN1 LEVELS Number of times ray/beam isscatteredP0 POLAR_0 Relative modulus of fundamentalbeam modeP1,P2 POLAR_1,2 Relative moduli of polarizationcomponentsQ0 NUM_RAYS Total number of ray/beamsQ1 NSOURCES Total number of original sourcesR0 PARENT Number of the ray from which thisray split (parent)S0 SHAPE Beam shape number (see SHAPEScommand)S1 FACTOR Beam shape factor or number ofhigher modesT0 PHASE_0 Relative phase angles offundamental beam modeT1,T2 PHASE_1,2 Relative phase angles ofpolarization componentsU0,V0 U,VPARAMB Parametric coordinates of base raypositionW0 WAVELEN Wavelength of ray/beamWi WAVLNS_i Wavelength for ith source

<strong>ASAP</strong> | Commands and Macros (P) | 286Register Literal Ray/Beam DataX0,Y0,Z0 X,Y,Z_POS_B Global X,Y,Z coordinates of baserayXi,Yi,Zi X,Y,Z_POS_i Relative coordinates of ith parabasalray3. In Stokes vector mode, the values of the P1, P2, P3, and P4 registers are S0, S1, S2, and S3 of the Stokes vector ofthe ray.PUT Examples

<strong>ASAP</strong> | Commands and Macros (R) | 287Commands and Macros (R)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “R”.RACETRACK (<strong>ASAP</strong> Command)Creates a racetrack or rectangular edge with smooth (continuous) rounded corners.Function• Define/Modify Surfunc EntitiesSyntaxRACETRACK X x y z y' [ z'] [ SPLIT ]Y y z x z' x'Z z x y x' y'OptionDescriptionX, Y or Z Coordinate axisx, y or z Location along coordinate axisy z, z x, or x yy' [ z' ], z' [ x' ], or x' [ y' ]SPLITRemarksOverall semimajor widthsSemimajor widths of the elliptical cornersFlag to split straight-aways into two equal line segments1. RACETRACK creates a racetrack or rectangular edge with straight sides and smooth (continuous), rounded corners.2. If the overall semiwidths are equal to the corner semiwidths, the racetrack has no straight-aways; it is a pureellipse.3. If the corner semiwidths are zero, the racetrack has no elliptical turns; it is a pure rectangle.4. For compatibility with previous versions of <strong>ASAP</strong>, the straight-aways can be SPLIT into two equal line segments.5. This edge is a combination of coplanar straight line and higher-order curved segments.RACETRACK ExamplesRADIAL (<strong>ASAP</strong> Command)Rotationally averages the current distribution data, and optionally computes the encircled energy.Function• Display/Modify Data DistributionsSyntaxRADIAL [ i j ] [ FUNCTION [ REPLACE ] ] [ 'title' ]MAX INTEGRAL [ p ]BOTH

<strong>ASAP</strong> | Commands and Macros (R) | 288Optioni jMAXFUNCTIONINTEGRALBOTHREPLACEp'title'DescriptionRotationally average the distribution data about the pixel(i j)Rotationally average the distribution data about themaximum pointPlot out a cross-section of the radially averaged functionPlot out the cross-section of the encircled energyPlot the cross-sections of the radially averaged functionand the encircled energyReplace the current distribution data with the radiallyaveraged dataPrint the radius of p percent encircled integralOptional title for plot (up to 64 characters)Remarks1. Rotationally averages the distribution data about the centroid (default), and then replaces the current distributiondata.2. RADIAL i j causes <strong>ASAP</strong> to rotationally average the distribution data about the pixel (i j).3. RADIAL MAX causes <strong>ASAP</strong> to rotationally average the distribution data about the maximum point.4. In all cases, the resulting distribution is radially symmetric about the given point.5. FUNCTION plots out a cross-section of the radially averaged function, but does not replace the currentdistribution data.6. INTEGRAL plots out the cross-section of the encircled energy, but does not replace the current distribution data.7. BOTH plots the cross-sections of the radially averaged function and the encircled energy, but does not replace thecurrent distribution data.8. RADIAL BOTH and RADIAL INTEGRAL should not be used after the ANGLES command if averaging directionaldistributions. ANGLES remapping distorts the coordinate system, making the radial average invalid.9. REPLACE replaces the current distribution data with the radially averaged data.10. If p is specified, the radius of p percent encircled integral is printed.11. RADIAL should only be used if rotational symmetry is expected; in most cases, use the AVERAGE command,which assumes no symmetry.12. The title is delimited by a single quote ' , as shown.RADIAL ExamplesRADIANT (<strong>ASAP</strong> Command)Calculates the far-field incoherent intensity or radiance of the currently selected ray data.Function• Analyze Ray/Beam DataSyntaxRADIANT [ X [ f f' n a a' n' ] ] [ MAP [ s ] ] [ LOW ]Y AREA HIGHZ

<strong>ASAP</strong> | Commands and Macros (R) | 289-X-Y-ZOptionDescriptionX, Y, or Z Specifies polar axis of the coordinate system (default Z)f f'na a'n'MAPsLOW/HIGHAREARemarksZenith/latitude angle rangesNumber of zenith/latitude subdivisionsAzimuth/longitudinal angle rangesNumber of azimuth/longitudinal subdivisionsRadiant intensity (flux per solid angle) calculationoption; produces polar plots of the radiant intensity as afunction of spatial positionPolar diagram rescaling factorResolution factorRadiance (flux per solid angle per projected area)calculation option; produces a distribution file containingthe radiance (flux/solid angle/projected unit area)1. Normally calculates in spherical coordinates the far-field incoherent radiant intensity (flux per solid angle) patternof the current ray set.2. The f f' is the range in degrees for the angles from the polar axis (zenith/latitude angles). The defaults are 0 to 180degrees. The n is the number of subdivisions of this angular range (default 36; that is, five-degree increments).3. The a a' is the range in degrees for the angles about the axis (azimuth/longitude angles). The defaults are -180 to180 degrees. The n' is the number of subdivisions of this angular range (default 36, that is, 10 degree increments).4. The pattern is written to the standard distribution file BRO009.DAT, and can therefore be processed further by theDISPLAY commands (for example, DIRECTION or MESH produces a 2D or 3D representation of the radiationpattern, which may be viewed with REPLOT).5. MAP or AREA also uses the current PIXELS and WINDOW settings to calculate the full four-dimensional pattern;that is, a function of not only the two angles but also the two spatial coordinates. MAP outputs radiant intensity(flux per solid angle) while AREA outputs radiance (flux per solid angle per projected area).6. The 3D polar diagrams for each point on the spatial grid are written to the current VECTOR file (use REPLOT or$VIEW to see this data) as either simple wireframes or LOW/HIGH-resolution, shaded "surfaces".7. The s is an optional rescaling factor for altering the sizes of the polar diagrams relative to the spatial grid spacing.8. If the angular sampling is 1x1, the radiant intensity or radiance map for this solid angle is written to the standarddistribution file, BRO009.DAT.9. The distribution file created by the RADIANT command is used by the IESFILE command to translate theradiant distribution information into the IESNA Photometry type A or C file formats. However, to create correctIES files, the start and end settings of the polar and azimuth angles of the RADIANT command must follow thevertical and horizontal angle ranges of IESNA standard Photometry A or C type, and must be in ascending order.10. The +X, +Y and +Z specification of the RADIANT command polar axis creates a right-handed, polar sphericalcoordinate system. The –X, -Y, and –Z specification of the RADIANT command polar axis creates a left-handed,polar spherical coordinate system.11. For a Photometry A IES file, the polar angle spans from -90 to 90 degree, and the azimuth angles spans from -180to 180 degrees.12. For a Photometry C IES file, the polar angle spans from 0 to 180 degree, and the azimuth angles spans from 0 to360 degrees.

<strong>ASAP</strong> | Commands and Macros (R) | 29013. The start and end settings for the polar angle of the RADIANT command determine which type of IES photometryfile can be created. If, the created distribution file can be used only to create a Photometry A IESfile. Otherwise, the distribution file can be used only to create a Photometry C IES file.14. BRO does not recommend use of the MAP or AREA options on the RADIANT command for IES photometry filegeneration and source creation.RADIANT Examples$RAN (<strong>ASAP</strong> Macro)Resets the random number seed for the "~" operator to the integer i (default 2000000001).Syntax$RAN [ i ] [DEC]BESTRemarks1. The default uniform random number generator (upon which all others are based) is identical to that used onthe Digital Equipment Corporation systems. You can switch to the BEST possible generator based on the samealgorithm, but using different numerical constants, and thus a different seed sequence.2. $RAN affects only the ~ (tilde) operator. Use SEED to reset the seed for random numbers for all other randomnumber generation; for example, for GRID, RANDOM, and EMITTER commands.$RAN ExamplesRANGE (<strong>ASAP</strong> Command)Adjusts the vertical plotting scale of the current distribution data.Function• Display/Modify Data DistributionsSyntaxRANGE [ d [ d' ] ]Optiondd'DescriptionMinimum values to be plottedMaximum values to be plottedRemarks1. Expands or recalculates the minimum d and/or maximum d' values to be plotted by the GRAPH, PLOT3D,ISOMETRIC, CONTOUR and MESH commands.2. Plots different data at the same fixed scale.3. Makes the plotting range only larger than the actual data range.4. Use the THRESHOLD command to "clamp" the data values to a smaller range.RANGE Examples

<strong>ASAP</strong> | Commands and Macros (R) | 291RAWDATA (<strong>ASAP</strong> Command)See the command BSDFDATA.RAWDATA ExamplesRAY (<strong>ASAP</strong> Command)Defines and traces a single ray.Function• Trace Rays/BeamsSyntaxRAY x y z a,b,c [h] [DIR] [PLOT [d]] [SEARCH] [KEEP] [LENS [n]]Optionx y za,b,cDescriptionStarting coordinates of rayInitial direction vector of rayh Cross-sectional, semidiameter (default 1)DIRPLOTdSEARCHKEEPLENS nRemarksPrints ray coordinates and direction cosines at eachintersectionPlots ray and any PARABASALS in current graphicsWINDOWRay depth coordinateRay intersection logic optionAdds ray to current ray storage after ray tracing;otherwise, deletesCreates a lens entity n from the sequence of surfacesencountered by the parent ray1. Traces a single ray/beam through the entire system, starting in the IMMERSE medium at the point (x, y, or z), witha direction given by the vector (a, b, c) and cross-sectional, semidiameter h (default 1).2. The program always lists the ray coordinates at each surface intersected. The DIR option adds the ray directions tothe listing.3. The PLOT option plots the ray and any PARABASALS in the current graphics WINDOW. If you enter RAYinteractively and the ray is being overlaid on a previous system graphics screen, you may trace more rays bymarking the starting point (depth x, y, or z) and second point (depth d) with the graphics pointer. Right-click (orpress the Enter key) to terminate this mode.4. The d is the depth of each ray starting coordinate within the plotting window.5. The SEARCH option resets the allowable object intersections for future rays according to the sequence of objectsencountered during this single ray trace.6. Unless the KEEP option is used, any rays traced with RAY are deleted from storage after they are traced.7. The sequence of surfaces encountered by the parent ray can be optionally used to create LENS entity n (default isone more than current highest entity number).

<strong>ASAP</strong> | Commands and Macros (R) | 292Some commands, including RAY, require the specification of a direction vector. The following format can be usedfor this input entry:RAY direction of vector between positions of the two entities.Example - General FormatRay number IObject X Y Z Size FluxU Vobject nameobject number x y z beam size flux before intersectionu vNrm l m n average curvature incident angle <strong>Inc</strong>Dir a b c beam divergence flux after intersectionNote: for u and v parameters,• The u and v are not printed for a SURFACE; OBJECT unless the SURFACE is a SURFACE; ARRAY;OBJECT, inwhich case the u is the nth array element of the OBJECT and the v is the nth array element of the OBJECT that theray intersects.• The u indicates the conicoid number for the LENS;OBJECT the ray intersects.• The u and v for an EDGE;OBJECT parametrically indicate the mesh number and the fractional coordinate withinthe mesh that the ray intersects.Example - Plot Options--- WIN Y Z; WIN 1.5--- PROFILE 'RAY COMMAND RAY TRACE AND PROFILE' OVERWindow Vertical: Y = -7.50000 to 7.50000 ( 15.0000 )Horizontal: Z = -21.3806 to 16.2821 ( 37.6627 )-1 Cuts for X=0.000000 to 0.000000--- RAY 2 2 -20 0 0 1 PLOT 2 SEARCHWindow Vertical: Y = -7.50000 to 7.50000 ( 15.0000 )Horizontal: Z = -21.3806 to 16.2821 ( 37.6627 )Ray number 1Object X Y ZSizeFlux0 2.000000 2.000000 -20.00000 1.0000001.0000002 2.000000 2.000000 -.1000000 1.0000001.0000001 0.5005005 0.5005005 -15.02002 0.25025020.89999993 -.1916530E-06 -.1916530E-06 10.00000 0.5674274E-06 0.8099998Total OPL = 60.00000000381213Effective Focal Length = 100.020Window Vertical: Y = -7.50000 to 7.50000 ( 15.0000 )Horizontal: Z = -21.3806 to 16.2821 ( 37.6627 )Ray number 2Object X Y Z SizeFlux

<strong>ASAP</strong> | Commands and Macros (R) | 2930 2.000000 -4.188794 -10.49998 1.000000 1.0000002 2.000000 -2.989614 -.1617224 1.000000 1.0000001 0.4851324 1.061682 -15.05435 0.2309581 0.8999999***Ray 2 missed after object 1 - SECONDARY_MIRROREffective Focal Length = 74.5145--- SEARCH LISTObject From To By Description0 2 2 11 1 300 1 SECONDARY_MIRROR2 1 1 1 PRIMARY_MIRROR3 1 300 1 DETECTORRAY ExamplesRAYS (<strong>ASAP</strong> Command)Sets the total number of rays in the virtual memory paging.Function• Setup Plots and Verify SystemSyntaxRAYS [ n ]OptionnDescriptionTotal number of rays in storageRemarks1. A shortened version of the RAYSET command for resetting the total number of rays in storage to n. The default isthe number of rays in the current virtual ray file; that is, the rays from a previous run can be restored with RAYS.The following two commands restart an analysis from the last time <strong>ASAP</strong> was run within the current directory:SYSTEM FROM !!restores system from the LASTEXEC.SYS fileRAYS!!restores rays/beams from the VIRTUAL.PGS file2. Reinitialize ray storage by entering RAYS 0.RAYS ExamplesRAYSET (<strong>ASAP</strong> Command)Specifies an arbitrary set of rays.Function• Create Rays and BeamsSyntax 1 - if rays originate in the X planeRAYSET X xy [ z f y' z' k [ a a' a" ... ] ] [ NOSPLIT ]: s

<strong>ASAP</strong> | Commands and Macros (R) | 294Syntax 2 - if rays originate in the Y planeRAYSET Y yz [ x f z' x' k [ a a' a" ... ] [ NOSPLIT ]: sSyntax 1 - if rays originate in the Z planeRAYSET Z zx [ y f x' y' k [ a a' a" ... ] [ NOSPLIT ]: sOptionDescriptionX, Y, or Z Plane in which rays originatex, y or z Location of plane from which rays originatey z, z x, or x yfy' z', z' x', or x' y'kaa' a" ...sNOSPLITRemarksCoordinates of ray on that planeFlux assigned to the ray45 percent amplitude semidiameters of the parabasal raywaistBeam shape and coherence parameterComplex amplitude of TEMoo beam modeComplex amplitudes of higher order beam modesOptional beam shape parameterFlag to never split this ray, regardless of what theSPLIT command indicates1. Object zero is used to refer to the ray data.2. Any number of ray coordinates may follow the RAYSET command.3. RAYSET always adds rays to the current ray storage until a TRACE is performed.4. The f is the flux (energy per unit time) to be assigned to each corresponding ray (default=1, unity).5. The primed coordinates are the relative positions of the 2 orthogonal parabasal rays to be traced if the number ofparabasal rays was previously set by a PARABASAL command.6. The k sets the beam shape and coherence of the ray (See the SHAPE command for a definition of s and furtherinformation).7. If k=0, the beam is a coherent set of Hermite-Gaussian modes and a a' "a. . . are the complex amplitudecoefficients for each mode. The modes are ordered as follows: 00 10 01 20 11 02 30 21 12 03 40 31 22 13 04 50.8. The default amplitude for the fundamental mode (TEMoo) is 1 (unity). The amplitudes of the higher-order beammodes default to zero.9. If higher-order beam modes are desired, both the number of higher-order modes and their amplitudes must beentered. The number of higher-order beam modes is given by n.10. The NOSPLIT option tells <strong>ASAP</strong> never to split this ray, regardless of what the SPLIT or LEVEL commandsindicate.11. The RAYS command (short form for the RAYSET command) resets the number of rays in storage to n. TheRAYSET and GRID commands always add their rays to the ones already in storage until a TRACE is performed.

<strong>ASAP</strong> | Commands and Macros (R) | 29512. <strong>ASAP</strong> modifies the polarization of rays as needed to avoid the creation of axial fields, and warns if this occurs.Modifications do not permanently change the POLARIZ settings.RAYSET Examples$READ (<strong>ASAP</strong> Macro)Starts to read future records from the beginning of the given file name (with default extension .INR).Syntax$READ nameRemarks1. Temporarily reads input from a specified file, which needs to be in the working directory. Alternatively, namemay be replaced with a full path in double quotes to point to a file on another drive or folder. For example,$READ "C:\MyFILES\Temp\File.inr" points to the file named File.inr, which is on the C:\ drive in theMyFILES\Temp folder.2. If end of file is reached, return to calling macro or file automatically.3. $READ commands, in addition to other commands that read data lists, can be nested directly or indirectly.4. File names are limited to 24 alphanumeric characters unless the name is enclosed in double quotation marks("name").$READ ExamplesRECTANGLE (<strong>ASAP</strong> Command)Creates a rectangular edge/curve.Function• Define/Modify Curvedge EntitiesSyntaxRECTANGLE X x y z [ n a a' ]Y y z xZ z x yOptionDescriptionX, Y or Z Specifies the axis of symmetryx, y or z Location along coordinate axisy z (z x or x y)na a'RemarksSemimajor widths of the rectangle1. Defines a rectangular polygon. See ELLIPSE for description of parameters.Number of points (or segments) on the rectangle (default4)Angular range (in degrees from first semimajor axis)over which the rectangle is defined (default is 0 to 360degrees)

<strong>ASAP</strong> | Commands and Macros (R) | 2962. If you are defining a closed rectangle (0 to 360 degrees), n should be a multiple of 4 so that there are edge pointsat each corner.3. The default value for n is 4 or the value specified on a previous RECTANGLE command. Use -n if you want it tobecome the default for future RECTANGLE commands.4. If n, a and a' are specified, they become the default settings for most future EDGE commands.5. This edge is made up of coplanar straight line segments; that is, convex polygons whose vertices lie on a particularcurve.RECTANGLE ExamplesREDEFINE (<strong>ASAP</strong> Command)Adds options to an object.Function• Create/Modify ObjectsSyntaxREDEFINE [ SURFACE [ j ] [ THICKNESS t ] [ COLOR k ] [ 'name' ]NORMALOptionSURFACEjNORMALTHICKNESStCOLOR k'name'DescriptionTransfers to alternate surfaceSurface numberUses alternate surface normalFlag to thicken the object surface(s)Distance by which object surface(s) are thickenedAssigns a specific color number to the objectDescriptive name to be assigned to this objectRemarks1. The SURFACE option forces <strong>ASAP</strong> to move any intersection points on a non-lens object to a nearby continuoussurface j after first intersecting the original object surface. The j is then used to calculate the normal for refractionand/or reflection.2. The NORMAL option allows the user to designate a continuous surface number j to be used for calculating just thenormal to the object that is different than the actual object normal.3. The SURFACE and NORMAL options are useful for modeling Fresnel optics and more accurately tracing rays/beams through discrete faceted approximations to objects.4. The default for j is the object's base entity; that is, it turns off either option.5. The THICKNESS option is used to thicken the object surface(s); that is, effectively turn it into two surfaces spaceda small distance t apart (default 0). The sign of t determines in which direction along the surface normal thesecond surface is located.6. The COLOR option assigns a specific color number k to the object, which is used in all subsequent graphicaldisplays, unless overridden by the global COLORS command. The default for k is the number of the object.7. Although REDEFINE may be used with objects based upon lenses with its full options, the most common usage isfor COLOR remapping of a lens object.REDEFINE Examples

<strong>ASAP</strong> | Commands and Macros (R) | 297REDUCE (<strong>ASAP</strong> Command)Selects a subset of the current distribution data and rejects remaining data.Function• Display/Modify Data DistributionsSyntaxREDUCE [ s [ s' ] ]-s+sm" [ n" ]m m' m" [ n n' n" ]OptionsDescriptionSelects out a square region of points (fractional) at thecenter-s Selects out a square region of points (fractional)bordering the lower edge, centered between corners+s Selects out a square region of points (fractional)bordering the upper edge, centered between cornersm m'n n'Integer pixel ranges in the across directionInteger pixel ranges in the down directionm" <strong>Inc</strong>rements in the across directionn" <strong>Inc</strong>rements in the down directionRemarks1. Reduces the number of data points by selecting out a subset of the current data; that is, the new data points aregiven by:2. The defaults for the increments "m and "n are 1.3. The default for n is m and n' is m'.4. A single fractional entry s selects out a square region of points at the center, lower middle (-s), or upper middle(+s). The s must be in the range of (0, 1.0].5. <strong>ASAP</strong> uses the data type of the first numerical entry on the command line to determine the syntax to use. If thefirst numerical entry is an integer, <strong>ASAP</strong> interprets it as REDUCE m syntax. If the first numerical entry is a floatnumber, <strong>ASAP</strong> interprets it as REDUCE s syntax.6. If no entries are given, the outer minimum value is cropped.REDUCE Examples$REG (<strong>ASAP</strong> Macro)Displays the contents of registers and associated variables.

<strong>ASAP</strong> | Commands and Macros (R) | 298Syntax$REG [ register register' ... ] [ 'text' ]&REGRemarks1. Macro displays the contents of a given register or set of registers with optional 'text'2. If no registers or variables are entered, all the registers or variables for which content has changed since programstartup are displayed.3. $REG prints out the internal <strong>ASAP</strong> register name in addition to the variable name(s) and value(s). &REG printsonly the variable name(s) and value(s).Examples$REG ExamplesREMOVE (<strong>ASAP</strong> Command)Subtracts best-fit polynomial.Function• Display/Modify Data DistributionsSyntaxREMOVE [ k ]OptionkDescriptionDegree of best-fit, 1D polynomial (default 1, linear)Remarks1. Removes (subtracts) best-fit, 1D polynomial of degree k (default 1, linear) from distribution data averaged in theother direction.2. Use a TRANSPOSE and another REMOVE to subtract a 2D polynomial (excluding any cross terms).REMOVE ExamplesRENDER (<strong>ASAP</strong> Command)Creates rendered graphics of the system geometry and ray trace.Function• Setup Plots and Verify SystemSyntaxRENDER [ d ] [ DEPTH [ d' [ d"] ] ] [ RAYS [ s ] ] [MODEL [ m ] ]x y z

<strong>ASAP</strong> | Commands and Macros (R) | 299Optiondx y zDEPTH d' d"RAYSsMODELmDescriptionDistance of the observation point in front of the sceneCoordinates (global) of the observation pointCuts in the depth direction at the near and far coordinateplanes d' and "dFlag to add a ray trace to the renderingScale factor for the width of the raysAny reflective SCATTER MODELS assigned to objectsare used in renderingDefaults objects with no SCATTER MODELS to givenMODEL mRemarks1. Creates a 3D shaded view (rendering) of the system geometry as seen through the current plot window, and asdetermined by the WINDOW, PIXELS, and LIGHT commands. RENDER works for all types of entities withcomplex bounds and obscurations.2. The observation (eye/camera) point is either given absolutely as (x,y,z) or as a distance d (default 10 timesmaximum scene span) in front of the scene.3. The scene is always illuminated by a light source of unit irradiance emanating from the observation point (forexample, a camera-mounted flash bulb). Therefore, unless a second LIGHTS source is specified, no shadowing isvisible.4. Normally, only the outside of the objects is visible. However, the outside can be cut away in the DEPTH directionat the near and far coordinate planes d' and "d .5. The rendered plot is written to the distribution data file BRO009.DAT. See the DISPLAY command for moreinformation about reading and displaying the data distribution file. A somewhat crude representation of the sceneis written to the 2D plot device during the rendering process.6. RAYS can be added to the rendering if SAVE was turned on before the last TRACE command. Only those portionsof the ray paths that are not hidden by any part of any object (whether it is transmissive or not) is visible.7. The addition of rays can significantly increase the time to render a scene; therefore, the number of rays should bekept to a minimum. The s is an optional scale factor for the width of the rays (default is 1 pixel). If s is entered as anegative number, each ray segment is rendered as a smooth cylinder (that is, anti-aliasing).8. Normally, all object surfaces are considered to be perfect 100% Lambertian diffuse reflectors. With the MODELoption, any reflective SCATTER MODELS assigned to objects are used in the rendering. Objects with noSCATTER MODELS assigned to them either default to 100% Lambertian or the given MODEL m.9. Each pixel point is a single floating point value, where the integer part is a color number and the fractional part itsintensity (shade). A standard COLORS command argument can be used to set the background color to somethingdifferent from the default black.10. Previously, a separate utility program (such as DIS2PS or DIS2VGA) was required to display this file on a devicecapable of representing many intensities of the colors.RENDER ExamplesRENORM (<strong>ASAP</strong> Command)Renormalizes coefficients of surface/function polynomials.Function• Define/Modify Surfunc Entities

<strong>ASAP</strong> | Commands and Macros (R) | 300SyntaxRENORM [ c ][ term c ][ MIN c ][ MAX c ][ FUNC c [ x y z ] ]Optioncterm, MIN, or MAXx y zDescriptionNormalization constantNormalizes the specified coefficients to be exactly equalto cPoint at which the function value is to be setRemarks1. Renormalizes the coefficients of the previous surface function.2. If it is actually a surface (function is 0), the renormalization does not affect the location of the surface, but maychange the direction of the normal to the surface or avoid numerical overflow problems.3. If no additional entries are made, the coefficients are normalized so that the largest and smallest ones are equallyspaced in magnitude about 1.4. If a single numerical value is entered, all the coefficients are divided by c.5. If a term is specified (that is, XiYjZk or the MIN/MAX), the coefficients are normalized so that the particularcoefficient becomes exactly equal to c.6. The last form allows you to set the value of the FUNC to c at the point (x,y,z) (default is the reference point).RENORM ExamplesREPEAT (<strong>ASAP</strong> Command)Repeats previously defined entity data.Function• Define/Modify Curvedge Entities• Define/Modify Lens Entities• Define/Modify Surfunc EntitiesSyntaxSURFACE or EDGE or LENSREPEAT [ i ]OptioniDescriptionPreviously defined entity numberRemarks1. Copies data from a previously defined entity into the current entity location. The new surface created is the sameas surface number i.

<strong>ASAP</strong> | Commands and Macros (R) | 3012. The default for i is 0.1 or the last entity defined. The ith lens (default last) is duplicated so that it may be displacedand/or rotated separately from the parent, using the linear transformation commands.3. After repeating entity data, the current entity data may be changed by various entity modifiers; that is, lineartransformations.4. If the entity is a SURFACE, all the coefficients are transferred in their final form, which include any lineartransformations applied to the original surface.5. If the entity is an EDGE, all edge points are transferred in their final form, which includes any lineartransformations applied to the original edge.6. If the entity is a LENS, all conicoid data are transferred in their final form, which includes any lineartransformations applied to the original lens.REPEAT ExamplesREPLICATE (<strong>ASAP</strong> Command)Replicates (copies) a distribution.Function• Display/Modify Data DistributionsSyntaxREPLICATE [ n ]OptionnDescription|n| times in horizontal (second) directionRemarks1. Copies a distribution |n| times in horizontal (second) axis.2. If n is negative, alternate reversing (mirroring) the distribution for each replicate.3. The default for n is one.REPLICATE ExamplesREPLOT (<strong>ASAP</strong> Command)Plots data stored in the 3D vector file within the currently defined graphics window.Function• Setup Plots and Verify SystemSyntaxREPLOT [ NORAYS ] [ OPTIMIZE ] [ 'title' ]OptionNORAYSOPTIMIZE'title'DescriptionPlot only intersections of rays with objectsOptimize plot vectorsOptional title for plot (up to 64 characters)Remarks

<strong>ASAP</strong> | Commands and Macros (R) | 3021. Replots within the currently defined graphics WINDOW all the 3D vector data found in the BRO030.DAT (*.VCR)file. Vector data outside of this window is not plotted.2. Useful for zooming in on particular areas by changing the WINDOW and REPLOTting.3. The NORAYS option suppresses the replotting of the rays themselves; however, it does plot the intersection pointsof the rays on each object.4. The OPTIMIZE option forces <strong>ASAP</strong> to try and connect any short vectors generated by a previous PROFILEcommand. This slows the immediate generation of the graphics but produces a cleaner plot file that does notadversely affect a pen plotter.5. A graphical pointer (that is, crosshairs) appears at the end of plotting. You can then position this pointer and pressthe specified key (or mouse button) to perform the following operations:Keys Mouse button Operation? Displays 3D system coordinates ofpointer position in output windowShift+3 (#)Displays number of object nearestto pointerSpace Left click Mark the lower left-hand corner of anew windowEnter Right click Opens menu; select End Replot toterminate6. The # (Shift+3) keyboard operation also replaces the current GROUP with all objects so-tagged (a GROUP and/orCONSIDER command can then be used to operate on these selected objects).7. The ? (Shift+/) keyboard operation also puts the coordinates in the output buffer for access by $GRAB.8. For the last operation, place the pointer at the upper-right corner of the desired window. After striking anotherspace key (or left mouse button), <strong>ASAP</strong> draws a box on the current plot to indicate the extent of the new windowand then beeps. Pressing the Enter key or right-clicking the mouse causes <strong>ASAP</strong> to clear the screen and to beginreplotting the data in the new window. This zooming-in process can be repeated indefinitely. If the two corners ofthe new window are entered as the same point, <strong>ASAP</strong> zooms back to include the entire plot.9. The $IO VECTOR REWIND command may be used to rewind (and thereby reinitialize) the BRO030.DAT file sothat new data may be written into the file.10. WINDOW X Z, WINDOW Y X, and WINDOW Z Y display the system in a left-handed coordinate system. UseWINDOW X -Z, WINDOW Y -X or WINDOW Z -Y to display the system in a right-handed coordinate system.11. The title is delimited by a single quote ( ' ), as shown.12. The OVERLAY command argument tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.REPLOT ExamplesRESET (<strong>ASAP</strong> Command)Reinitializes all control settings to those at program startup.Function• Save or Recover System Data and Control ExecutionSyntaxRESETRemarks1. Resets all ray data and performs the equivalent of the RAYS 0 command.

<strong>ASAP</strong> | Commands and Macros (R) | 303Note: PARABASALS and WIDTHS are also set to 0 and 1, respectively. This effectively disables anypreviously stated BEAMS COHERENT DIFFRACT.2. Does not affect system description (use SYSTEM NEW to reset this).RESET ExamplesRESTRICT (<strong>ASAP</strong> Command)Further controls ray search within lens.Function• Define/Modify Lens EntitiesSyntaxRESTRICT BACKWARDFORWARDOFFRemarks1. Instead of a conicoid seeing itself and adjacent ones, the command further restricts the ray search to either thelogical FORWARD or BACKWARD direction.2. Use OFF to go back to the default. Like the object SEARCH command, RESTRICT can be used to speed up raytraces.RESTRICT ExamplesRETURN (<strong>ASAP</strong> Command)Returns <strong>ASAP</strong> to top command level (that is, the <strong>ASAP</strong>> prompt).Function• Save or Recover System Data and Control ExecutionSyntaxRETURNRemarks1. Alternatively, RETURN can be used to terminate the graphics mode (that is, OVERLAY) and return you to textcommand level.RETURN ExamplesREVERSE (<strong>ASAP</strong> Command)Reverses the propagation direction of all currently defined rays.Function• Modify Ray/Beam Data

<strong>ASAP</strong> | Commands and Macros (R) | 304SyntaxREVERSE [ OPL ]OptionOPLDescriptionSignals <strong>ASAP</strong> to start subtracting optical path lengths(OPL) instead of adding them for ALL raysRemarks1. Reverses the directions of the currently selected rays.2. Useful for doing virtual ray traces.REVERSE ExamplesREVOLUTION (<strong>ASAP</strong> Command)Creates a surface specified by spinning a 2D curve around a given axis.Function• Define/Modify Surfunc EntitiesSyntax(numbers represent powers):REVOLUTION X x c0 z1 x1 [z2 zx x2 [z3... [z4... [z5... ]]]] [DECENTER d]Y y c0 x1 y1 [x2 xy y2 [x3... [x4... [x5... ]]]]Z z c0 y1 z1 [y2 yz z2 [y3... [y4... [y5... ]]]]OptionDescriptionX, Y, or Z Axis of symmetryx, y, or z Location along coordinate axisc0 z1 x1..., c0 x1 y1..., or c0 y1 z1...DECENTER d<strong>Reference</strong> PointAt location along coordinate axis.Surface NormalRadially outward from the axis.AutolimitingNo; requires LOCAL or LIMITS modifiers.RemarksCoefficients of 2D curveOptional decentering1. Takes the general 2D curve defined relative to the given coordinate by the ascending coefficients (up to 21; that is,fifth), optionally DECENTERs it a distance d, and then rotates it about the given axis to form a 3D surface of up totwice the order of the curve.REVOLUTION Examples

<strong>ASAP</strong> | Commands and Macros (R) | 305REVOLUTION (Fitted) (<strong>ASAP</strong> Command)Creates a surface by spinning a 2D curve fit to data points.Function• Define/Modify Surfunc EntitiesSyntaxREVOLUTION X 1ST z x z' x' ... [ VECTOR [c ] ]Y 2ND x y x' y'Z 3RD y z y' z'4TH5THFITOptionVECTORDescriptionSee RemarkX, Y, or Z Axis of symmetry1ST 2ND ...Type of curve fitz x z' x' ..., x y x' y' ..., or y z y' z' ... Coordinate pairs (up to 1000)<strong>Reference</strong> PointAxial location of the point furthest from the axisSurface NormalRadially outward from the axisAutolimitingYesRemarks1. Determines the coefficients of a 1st, 2nd, 3rd, 4th, or 5th-order curve by fitting in a least squares sense to a seriesof points (up to 5000 coordinate pairs).2. The axial location of the point furthest from the axis becomes the surface's reference point.3. The threshold on the last LSQFIT command is used to determine if any of the resulting coefficients can beconsidered negligible (that is, zero).4. The VECTOR option puts each data point in the current 3D file as a dot of color c (default 1) for later plotting by aREPLOT, DRAW, or $VIEW command.REVOLUTION ExamplesRIGHT (<strong>ASAP</strong> Command)Creates a simple prism that deviates the rays by 90 degrees.Function• Define/Modify Lens Entities

<strong>ASAP</strong> | Commands and Macros (R) | 306SyntaxRIGHT X x h m [ Y,Z ]PENTA Y y Z,XZ z X,YOptionDescriptionX, Y, or Z Global coordinate axisx, y, or z Location on the global coordinate axishmY,Z or Z,X or X,YRemarksAperture heightMedia (name or number)Output coordinate direction1. RIGHT and PENTA create the specified 90-degree deviation prism with aperture height h', medium m, and outputcoordinate direction given by the last entry. RIGHT creates a right-angle prism; whereas, PENTA creates a fivesidedprism.2. The output coordinate direction establishes the orientation of the prism by specifying the output direction of a raythat originally entered the prism propagating along the input coordinate axis.3. All faces are circular.4. The best way to model any prism in <strong>ASAP</strong> is to write a macro that creates a faceted object from two EDGES.5. This lens entity starts out normal to the defined global coordinate axis (X, Y or Z).RIGHT ExamplesRMS (<strong>ASAP</strong> Command)Scatter model given surface variations for RMS, fall-off, and autocorrelation.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxRMS r l sOptionrlsDescriptionRMS height variation of the surface in WAVELENGTHunitsAutocorrelation length of the surface variations inWAVELENGTH unitsAsymptotic fall-off with angle from specular(0=Lambertian, otherwise typically between -1 and -2.5)Remarks1. The B-Bo shoulder point is the ray's wavelength divided by l.

<strong>ASAP</strong> | Commands and Macros (R) | 3072. The s is the asymptotic fall-off with angle from specular (0=Lambertian, otherwise typically between -1 and -2.5).This is an approximate (violates reciprocity) theoretical model primarily for smooth surfaces (r much less than awavelength and l much greater than a wavelength), but it otherwise behaves well (although it may not representany actual rough surface).3. The BSDF varies with wavelength, incidence direction, scatter direction, and the specific object's INTERFACEproperties. It also automatically conserves energy (within standard statistical variations) if a ROUGHNESS r lcommand is also assigned to the object.RMS ExamplesROOF (<strong>ASAP</strong> Command)Two rectangles that are "hinged" at a common side.Function• Define/Modify Surfunc EntitiesSyntaxROOF X x y [ z [ a ] ]Y y z xZ z x yRemarks1. Two rectangles with a (nearly) common edge at the given location, and with an apex angle a in degrees (default90) between them.2. The "base" of the roof (which is perpendicular to the given AXIS) has semiwidths specified by the fourth and fifthentries.3. A small gap exists between the rectangles, because they must be represented by a single, implicit equation, and thenormal is undefined there.ROOF ExamplesROTATE (<strong>ASAP</strong> Command)Rotates an entity about a point.Function• Create/Modify Objects• Define/Modify Curvedge Entities• Define/Modify Lens Entities• Define/Modify Surfunc Entities• Modify Ray/Beam DataSyntax 1ROTATE X d [ y z ] [ LIST ]Y d z xZ d x y

<strong>ASAP</strong> | Commands and Macros (R) | 308Syntax 2ROTATE d ABOUT a,b,c [ x y z ] [ LIST ]OptionDescriptionX, Y or Z Rotation axisdy z (z x or x y)LISTa,b,cx y zRemarksRotation angle measured in degreesDisplacement from coordinate axisDecodes transformation matrix into simple operations (ifpossible) and printsArbitrarily oriented axis directionPoint about which entity is rotated1. Rotates the entity through an angle d, about an axis displaced from the coordinate axis.2. The sign of the angle is determined by the right-handed rule where the positive value results when the thumbpoints along the positive direction of the rotation axis.3. The center of rotation is defaulted to the entity's reference point.4. To rotate d degrees about an arbitrary vector (a,b,c) passing through a point (x,y,z), use Syntax 2.5. Group ROTATE with these commands: MATRIX; SHIFT; SCALE; SKEW; PLACE; ALIGN; and XEQ.ROTATE ExamplesROUGHNESS (<strong>ASAP</strong> Command)Assigns a roughness to the entity of an object, and conserves energy between specular and scattered beams.Function• Create/Modify ObjectsSyntaxROUGHNESS [ r [ l ] ] [ MODEL i [ FRACTION [ f ] ] ]RANDOM h [ s [ m ] ]OptionrlMODEL IRANDOMhsmDescriptionRMS micro-roughnessAutocorrelation lengthSpecifies BRDF scattering model iFlag for height and slope variationsRMS random height variationRMS normal deviationsProbability distribution for normalRemarks

<strong>ASAP</strong> | Commands and Macros (R) | 3091. Assigns macroscopic, random height, and normal deviations to the object entities.2. ROUGHNESS r assigns an RMS micro-roughness to object surface(s) in wavelength units. use it to transfer energyout of the specularly reflected/refracted beams (and usually into any scatter beams) to conserve energy betweenspecular and scattered beams. It does not affect the optical path lengths or directions of the specular beams.3. If the autocorrelation length l (also in WAVELENGTH units) is given, the effects of shadowing at high angles ofincidence are included.4. For autocorrelation length, <strong>ASAP</strong> assumes that any roughness characterized by a user-specified RMS value isdescribed by an isotropic, stationary Gaussian process of zero mean, described by the two-point autocorrelationfunction of the surface height given by, where is the local deviation of the surface-height from the mean, and the angular brackets represent anensemble average over the surface to which and are confined. The length, , is called the autocorrelationlength, sometimes shortened to "correlation length." We readily identify as the RMS deviation of surfaceheightby setting. We also see that the stated properties are satisfied by this form:isotropicstationaryzero meanCorrelation does not vary with azimuth about thenormalCorrelation does not vary with position on the surfaceThe base surface defines the "average" surface-height5. For a FRACTION f (default 1 or given MODEL TIS) of the incident rays, RANDOM or MODEL assigns amacroscopic height variation h (defaulted to 0) is a Gaussian distribution with an RMS value entered inWAVELENGTH units, and slope error s in radians (both defaulted to 0) to the surface(s) of the object. The randomheight variations affect only the position of a point on the object and, therefore, the optical path lengths of anyreflected or refracted beams, while the slope errors affect only the normal (and thus the beam directions).6. The RANDOM normal deviations s, entered as an RMS value in radians, affect only the normal and, therefore,the beam directions. The maximum allowable normal deviation is 0.2 radians. If s exceeds about one fifth (0.2radians), unexpected ray trace results may occur at the surface; that is, wrong side warnings may be generatedbecause, for example, a ray may randomly reflect into the surface.Note: The form ROUGHNESS RANDOM is obsolescent and is preserved primarily for backwardcompatibility in <strong>ASAP</strong>. BRO recommends the use of ROUGHNESS MODEL.7. For near normal incidence rays, if the RMS slope error exceeds about one fifth (.2), unexpected raytrace resultsmay occur at the surface; for example, "wrong side" warnings, because a ray may randomly reflect or refract intothe surface. For near grazing incidence rays, the RMS slope may have to be much smaller than this to avoid theseraytrace errors. Both errors are, by default, generated according to an approximately Gaussian-normal distribution(type 2 below). However, the slope error distribution function can be any one of the following:m Slope distribution (Maximum/RMS)^2 Equivalent-3 Two deltas 1 RAN(-15)-2 Lambertian-1 Ramp 2 RAN(-1)0 Uniform 3 RAN(0)1 Triangular 6 RAN(2)2 Gaussian-like 9 RAN(3)

<strong>ASAP</strong> | Commands and Macros (R) | 310m Slope distribution (Maximum/RMS)^2 Equivalent3 Cosine 5 RAN(1)4 Near-Gaussian 15 RAN(5)5 Gaussian 2 ln (2^32) RAN(15)8. To be more precise, if the randomly unperturbed normal points along the z axis, the components of the randomlyperturbed normal are:where u is a uniformly distributed random number, and s is a random number determined by the given slopedistribution (RMS and probability function).9. Note the maximum absolute slope error is always limited to one; that is, 45 degrees.10. Alternatively, the surface slopes may be randomized so that the shape of the normal incidence reflected patternmatches that of the BRDF specified by the scattering MODEL i.ROUGHNESS ExamplesROUNDED (<strong>ASAP</strong> Command)Creates a rounded-corner, rectangular edge/curve.Function• Define/Modify Curvedge EntitiesSyntaxROUNDED X x y z r [ n a' ]Y y z xZ z x yOptionDescriptionX, Y or Z Specifies the axis of symmetryx, y or z Location along coordinate axisy z, z x, or x yrSemimajor widths of the ovalRadius of the rounded cornersn Number of points (or segments) on the oval (default 16)a'Remarks1. The default number of points along the curves of the rectangle is 16.2. The default angular range over which the rectangle is defined is 0 to 360 degrees.Angular range (in degrees from first semimajor axis)over which the oval is defined (default is 0 to 360degrees)

<strong>ASAP</strong> | Commands and Macros (R) | 3113. If n, a, and a' are specified, they become the default settings for most future EDGE commands.4. This edge is made up of coplanar straight line segments; that is, convex polygons whose vertices lie on a particularcurve.ROUNDED ExamplesRPM (<strong>ASAP</strong> Command)Defines a realistic polarizer model.Function• Create/Modify ObjectsSyntaxRPM [extinction ratio] [Tp] [Rp] [Rs] [acceptance angle] [no] [ne] [PRE]'[name]'Optionextinction ratioT pR pR sacceptance anglen on ePREnameDescriptionExtinction ratio of the realistic polarizer. The defaultvalue is 1000.Transmittance when incident light is polarized in thedirection of the transmission axis. The default value is 1.Reflectance when incident light is polarized in thedirection of the transmission axis. The default value is 0.Reflectance when incident light is polarized in thedirection orthogonal to the transmission axis. The defaultvalue is 0.Specifies the acceptance angle of the polarizer. Theangle must be in degrees. The default value is 90°.The real part of the ordinary refractive index of thepolarizer. The default value is 1.5.The real part of the extraordinary refractive index of thepolarizer. The default value is 2.1.The RPM is a pre-polarizer, in which <strong>ASAP</strong> assumesthat the incident light on this RPM polarizer isunpolarized.The name of the realistic polarizer, up to 32 characterslong.Note: the name is case sensitive.Remarks1. Both O-type and E-type polarizers can be modeled with RPM model.2. The extinction ratio is defined as T p |T s , where T p is the transmittance when incident light is polarized in thedirection of the transmission axis and the T s is the transmittance when incident light is polarized in the directionorthogonal to the transmission axis. Note: a positive extinction ratio represents an O-type polarizer, and a negative

<strong>ASAP</strong> | Commands and Macros (R) | 312extinction ratio represents an E-type polarizer. The default extinction ratios for O- and E-type polarizers are 1000and -1000 respectively.3. For realistic polarizer models (RPMs), the polarization axis refers to the direction of its transmission axis.When created, the transmission axis is always assumed to be the local x axis of any object with a INTERFACEPOLARIZATION. The transmission axis is in the plane parallel to the object surface. However, the transmissionaxis can be rotated with INTERFACE POLARIZATION azimuthal angle. The polar angle setting is ignored.4. If no name is specified, <strong>ASAP</strong> uses a default name starting with "RPM" followed by the list index of this realisticpolarizer in the system RPM element list. For example, the second RPM element is named "RPM00002".5. The pre-polarizer concept only works for forward propagating rays. For backward propagating rays, thepolarization states of the rays are assumed to be their actual polarization state. This pre-polarizer concept isconvenient to model some type of polarization films such as 3M's DBEF with polarization state is represented byJones vectors.6. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER3 Realistic polarizer POLARIZER RPM4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC8 Cascaded polarizationelementRPM ExamplesCPECPERRM (<strong>ASAP</strong> Command)The RRM command defines a realistic retarder model in <strong>ASAP</strong>.Function• Create/Modify ObjectsSyntaxRRM [retardance [wavelength [thickness [transmission [no [ne [RoRe ]]]]]]]] ’[name]’OptionretardancewavelengthDescriptionPhase retardance of the retarder for normal incident rays,in unit of wavelength. For example, the phase retardanceof a quarter waveplate is 0.25, which is the default value.Wavelength at which the nominal phase retardanceoccurs, specified in um. Default value is 0.633 um.

<strong>ASAP</strong> | Commands and Macros (R) | 313OptionthicknessDescriptionThickness of the retarder, specified in um. Default valueis 100 um.transmission Power transmittance of the retarder. Default value is 1.0(100% transmission). See Remarks.noneRoRe'name'RemarksOrdinary refractive index of the uniaxial crystal. Defaultis 1.543. See Remarks.Extraordinary refractive index of the uniaxial crystal.Default is 1.552. See Remarks.Power reflectance for the ordinary eigenmode. Default is0 (no reflection).Power reflectance for the extraordinary eigenmode.Default is 0 (no reflection).Name of the RRM device. Default name format isRRM0001, RRM0002, and so on.1. The realistic retarder model is a uniaxial crystal-based physical model for linear retarders. This RRM modelaccurately models both on- and off-axis propagation of polarized light inside the crystal with the extended Jonesmatrix method under small birefringence approximation (that is, .2. The ordinary (O-) and extraordinary (E-) rays inside the uniaxial crystals are assumed to be coherent even for theincoherent illumination. Therefore, interference can occur between O- and E-rays and is calculated in the model.3. Multiple reflections inside of the crystal are ignored. Fresnel transmission loss at the retarder input and outputinterface can be automatically calculated if the transmission setting is less than zero. This is useful for modeling aliquid crystal cell with multiple sub-cell approach and a CPE element.4. The default material of the retarder is assumed to be quartz, which is a positive uniaxial crystal (ne > no).5. The retarder is assumed to be a parallel plate before being attached to an <strong>ASAP</strong> object. In addition, thepolarization axis of RRMs is referred to as the direction of the optic axis of the uniaxial crystal. When created,the optic axis is always assumed to be the local x axis of any object with a INTERFACE POLARIZATIONcommand. The optic axis can be rotated to any arbitrary direction with INTERFACE POLARIZATION theta andazimuthal angles. Note the theta angle controls the angle between the optic axis and the local surface tangentialplane of the attached <strong>ASAP</strong> object, determined by conformal wrapping process.6. Usually, commercial retarders (waveplates or phase plates) use fast or slow axis convention, and their fast or slowaxis is marked on the element. For such elements, their fast or slow axis is usually in the plane of the retardersurface. However, the <strong>ASAP</strong> RRM model needs the direction of the retarder's optic axis. It is simple to find thedirection of the optic axis from the direction of a fast or slow axis. For retarders made from positive uniaxialcrystal (for example, quartz), the slow axis is the optic axis. And for retarders made from negative uniaxial crystal(for example, Calcite), the fast axis is the optic axis.7. All arguments are optional. If the value of an argument is not supplied by the user, its default value is used.8. With the transmission option, the negative setting for this parameter instructs <strong>ASAP</strong> to calculate Fresneltransmittance automatically on the input and output interface of the retarder.9. With the option, no, the user can alternatively specify the name or index of a previously defined crystal media.<strong>ASAP</strong> interprets types of this input differently for integer and real numbers. For real numbers, <strong>ASAP</strong> assumes thatit stands for the refractive index. While for an integer, <strong>ASAP</strong> assumes that it stands for the index of a previouslydefined media.10. With the option, ne, it is used to specify directly the extraordinary index of the crystal for the retarder. Note: it isnot used if the device crystal is specified by a previously defined crystal media.11. <strong>ASAP</strong> maintains a dynamic list for each defined polarization device type, listed in the table below. A polarizationdevice type can be referenced by either its type index number or its alternative input name.

<strong>ASAP</strong> | Commands and Macros (R) | 314Type Index Device Type Name Alternative Input <strong>ASAP</strong> Command1 Jones matrix element JONES JONES2 Mueller matrix element MUELLER MUELLER3 Realistic polarizer POLARIZER RPM4 Realistic retarder RETARDER RRM5 General uniaxial media GUM GUM6 Liquid crystal cell LCC LCC7 Biaxial coating BIC BIC8 Cascaded polarizationelementRRM ExamplesCPECPE

<strong>ASAP</strong> | Commands and Macros (S) | 315Commands and Macros (S)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “S”.SAG (<strong>ASAP</strong> Command)Deforms or sags an edge onto a surface.Function• Define/Modify Curvedge EntitiesSyntaxSAG [ X ] i [ ABS ]Y RELZ [ CV c [ c'] ] [ CC k [ k'] ] [ AD d [ d'] ] [ VP p [ p'] ]RD r r'SPHERE r [ q q' [ p p' ] ]OptionX Y ZiABSRELCVc c'CCk k'ADd d'VPp p'RDr r'k k'SPHERErq q'p p'DescriptionSag directionThe ith previously defined surface/functionSag the edge ABSsolutely (the default) for all pointsSag the edge RELatively for any interior control pointsCurvature sag flagVertex curvatureConic constant sag flagConic constantFourth-order deformation sag flagFourth-order deformation coefficientsVertex offset sag flagVertex offsetRadius sag flagVertex radiusConic constantSphere sag flagDistance from the edge's reference point (or the givenvertex point p p') to center of sphereMaps remaining two coordinate directions to the surfaceVertex offset

<strong>ASAP</strong> | Commands and Macros (S) | 316Remarks1. Deforms the last EDGE specification by sagging the points on the edge.2. The actual sag can be specified in three different ways:• The edge can be sagged to the previously defined ith SURFACE. This can be ABSolutely (the default) for allpoints or RELatively for any interior control points. The latter retains the shapes of individual segments of theedge.• The sag can be specified independently via a standard optical sag formula. The c, r, d, k and p specify thevertex curvature, vertex radius, fourth-order deformation coefficient, conic constant, and vertex offsetrespectively, of the first semimajor axis component. The primed quantities refer to the second axis and aredefaulted to the same values as the first. The default for the conic constant k is -1; that is, a parabola.• All the edge points can be exactly sagged to a SPHERE. The center of the sphere is located a distance r fromthe edge's reference point (or the given vertex point p p') along the given coordinate axis. The mapping of theother two coordinate directions to the surface of the sphere is controlled by the q and q' parameters. A value ofzero performs a latitude mapping; a value of one performs a longitude mapping. The parameters can be variedcontinuously between these two cases.SAG ExamplesSAMPLED (<strong>ASAP</strong> Command)Creates an explicit surface interpolated from sampled data.Function• Define/Modify Surfunc EntitiesSyntax 1 - Use an existing data distribution fileSAMPLED [ name ]Syntax 2 - Create the file directlySAMPLED name X x y y' z z' [ SLOPES ]Y y z z' x x' DIFFSZ z x x' y y'd [ s' s" ] d' ...:OptionnameDescriptionDistribution file name of sampled data; see RemarksbelowX, Y or Z Specifies axis of symmetryx, y or z Location along axisy y', z z', or x x'z z', x x', or y y'd d' ...SLOPESs' s"Maximum data extents in specified directionDeformation valuesSpecifies slope dataSlope values in direction of maximum data extents

<strong>ASAP</strong> | Commands and Macros (S) | 317OptionDIFFSDescriptionEstimates slopes based on finite differences from finitedeformations only<strong>Reference</strong> PointIf read from a distribution file, name.dis file (default BRO009.DAT), point is at (0,0) depth coordinate.If created directly, point is at the intersection of reference plane and coordinate axis.Surface NormalAlong positive coordinate directionAutolimitingYes, see RemarksRemarks1. Creates an explicit surface defined by:• Reading deformation samples found in the binary distribution file name.dis (default BRO009.DAT) externalfile.• Entering the sample points following the command description.2. The deformation and slopes for ray tracing, if specified in the distribution file, are linearly interpolated betweendata points. Up to 1000 data points are allowed in the across direction and an unlimited number in the downdirection.3. Each directly created SAMPLED surface must be given a distinct distribution file name.WARNING: Attempts to re-use a distribution file name for directly created SAMPLED data results in an error.<strong>ASAP</strong> generates the error message, "The named distribution file already exists." <strong>ASAP</strong> does not crash, butexecution of the script stops.This situation is particularly important for the direct creation of more than one SAMPLED surface with a loop.Direct creation of multiple surfaces in a $DO loop can be accomplished by incorporating the loop variable ? intothe file name. Creating unique names for each iteration of a $ITER is somewhat more complex, and requires thatthe file name depends uniquely on each of the $ITER variables.4. The file header of the distribution file should contain directional labels (X, Y, and Z), and data ranges thatdetermine the orientation and size of the surface in its local coordinate system. If not specified, <strong>ASAP</strong> assumes az(x,y) surface located at the origin.5. The distribution file can be created by an external user program, a $ITER command, or by a MAP command.6. If the sample points are entered directly in <strong>ASAP</strong>, using X as an example, name.dis is the name of the distributionfile created from the sample points, X is the axis of symmetry, and x is the location of the reference plane alongthe axis. The y,y' and z,z' are the maximum extents of the sample points. The subsequent lines specify thedeformation values that cover the given area uniformly up to (and including) the given extents.7. If the SLOPES option is included, each sample point has a deformation value and the slopes in the two otherdirections associated with it.8. Uses smooth positional interpolation with slopes and ACCURACY HIGH.9. If DIFFS is specified, the slopes are estimated from the deformation values by finite differences.10. The SAMPLE entity is autolimiting, but only in a rectangular sense because of the data file structure. If anelliptical aperture is desired, you must use a LOCAL or LIMITS modifier.ExampleFor defining an approximation to a shallow conical surface:$ITER X -1. 1. -11 Y -1. 1. -11 Z !!negative sample numbers requiredZ=.1*SQRT(X^2+Y^2)!!z proportional to radial valueSURFACE; SAMPLED ITER !!default file name when $ITER not in a macro

<strong>ASAP</strong> | Commands and Macros (S) | 318LOCAL AXIS ZSHIFT Z ...!!convert box from default rectangular to cylindrical!!move it into global positionSAMPLED ExamplesSAMPLED (Cylindrical) (<strong>ASAP</strong> Command)Creates a deformed cylindrical surface interpolated from sampled data.Function• Define/Modify Surfunc EntitiesSyntaxSAMPLED name RX r x x' a a' [ SLOPES ]RY y y' DIFFSRZ z z'd [ s' s" ] d' ...:OptionRX, RY, or RZrx x', y y', or z z'a a'd d' ...SLOPEs' s" ...DIFFSDescriptionSpecifies axis of reference cylinderRadius (semidiameter) of reference cylinderInitial and final axial extents of reference cylinderInitial and final angular extents of reference cylinderDeformation valuesSpecifies slope dataSlope values in axial and angular directionsEstimates slopes based on finite differences from finitedeformations only<strong>Reference</strong> PointAt the intersection of the reference cylinder and coordinate axis.Surface NormalRadially outward (cylindrical symmetry)AutolimitingYesRemarks1. This variation of the SAMPLED surface may be used to model sample points as a departure from a cylinder insteadof a plane.2. The third and fourth entries define the reference cylinder (that is, its axis and radius). The fifth and sixth entriesdefine its extent in the axial direction. The seventh and eighth define the angular (degrees) extent around the axis.The command is then followed by the lines of deformation values that cover the given area uniformly up to (andincluding) the given extents.

<strong>ASAP</strong> | Commands and Macros (S) | 3193. If the sample points are entered directly in <strong>ASAP</strong>, using RX as an example, name.dis is the name of thedistribution file created from the sample points. RX is the axis of the reference cylinder, x x' is the initial and finalaxial extents of the reference cylinder, and a a' is the initial and final angular extents of the reference cylinder.The lines that follow specify the deformation values that cover the given area uniformly up to (and including) thegiven extents.4. If the SLOPES option is included, each sample point has a radial deformation value and the slopes in the axial andangular directions associated with it.5. The angular slope has units of length per radian.6. If DIFFS is specified, the slopes are estimated from the deformation values by finite differences.7. The deformation values for a cylindrical sampled surface must cover the area of surface uniformly up to andincluding the given extents.CYLINDRICAL ExamplesSAVE (<strong>ASAP</strong> Command)Writes future ray trace data to a file for post-processing.Function• Save or Recover System Data and Control ExecutionSyntaxSAVE [ k [ name ]]OFFOptionknameOFFDescriptionUnformatted binary file number (or extension)Unformatted binary file nameTurns off selection of saving ray trace data (data is notsaved)Remarks1. Directs <strong>ASAP</strong> to save an unformatted binary file number information about every ray intersection found duringany future ray traces.2. If k is present, it becomes the file extension; otherwise, *.his is the assumed extension, and is automaticallyincremented after each TRACE command, unless another SAVE command is used to override it or turn it OFF.3. The default name part of the file is "<strong>ASAP</strong>TEMP" or it is taken from the last SYSTEM or $IO command.Otherwise, it can be directly specified with the additional name entry.4. The next HISTORY or RENDER…RAYS command uses the file.5. Currently, SAVE takes precedence over the TRACE PLOT command to prevent excessive disk thrashing.6. The <strong>ASAP</strong> PRO edition includes angles of incidence in the SAVEd trace data if a file number is provided to theSAVE command. <strong>ASAP</strong>, without the PRO edition, does not SAVE angles of incidence.SAVE ExamplesSAWTOOTH (<strong>ASAP</strong> Command)Creates a sawtooth pattern edge in the plane.Function

<strong>ASAP</strong> | Commands and Macros (S) | 320• Define/Modify Curvedge EntitiesSyntaxSAWTOOTH X x y z y' z' n [ w ]Y y z x z' x'Z z x y x' y'OptionDescriptionX, Y or Z Coordinate axis of planex, y or z Location of plane on coordinate axisy z, z x, or x yy' z', z' x', or x' y'nwRemarksFirst tip (or control point)End of the first toothNumber of teethPositive Bezier weight factor used to get rounded conicteeth1. The edge starts at the origin in the plane.2. Instead of sharp pointed teeth, a positive Bezier weight factor w can be used to get rounded conic teeth (see thePOINTS command for more information).3. SAWTOOTH Bezier weights are positive real numbers ranging from 0 to 1000 (any larger number has little effectand can lead to numeric errors).4. This edge is a combination of coplanar straight line and higher-order curved segments.SAWTOOTH ExamplesSCALE (<strong>ASAP</strong> Command)Specifies arbitrary scaling of an entity.Function• Create/Modify Objects• Define/Modify Curvedge Entities• Define/Modify Lens Entities• Define/Modify Surfunc Entities• Modify Ray/Beam DataSyntaxSCALE a [ b c ] [ LIST ]X a [ x ]Y b yZ c z

<strong>ASAP</strong> | Commands and Macros (S) | 321Optiona b cx y zLISTDescriptionScales the entity by the uniform factor "a", ornonuniformly by separate coordinate factors (a,b,c)optional point (x,y,z)decodes transformation matrix into simple operations (ifpossible) and printsRemarks1. Scales the entity by the uniform factor "a", or nonuniformly by separate coordinate factors (a,b,c), about theoptional point (x,y,z). This point is defaulted to the entity's reference point.2. <strong>ASAP</strong> scales relative to the original centroid as the reference point. Simple statistical noise can therefore createlarge variations in x, y, z positioning. When scaling sources centered about 0, 0, 0, it is best to specify x, y, z as 0,0, 0 to fix their position.3. The default for (a,b,c) is 1 (no scaling).4. When scaling rays anamorphically (unequal scaling in one or more directions), the angular direction cosines ofeach ray is inversely scaled. An isotropic or Lambertian source does not remain isotropic or Lambertian afteranamorphic scaling.5. Group SCALE with these commands: MATRIX; ROTATE; SHIFT; SKEW; PLACE; ALIGN; XEQ.CAUTIONDo not use a nonuniform SCALE command to resize raysets created using; for example, EMIT DATA. If you do, theangular distribution of the rayset is altered (see above).Note: BRO recommends using the NORMALIZE command to rescale the axes of the distribution data filebefore creating rays.SCALE ExamplesSCALE FROM (<strong>ASAP</strong> Command)Scales from the given length units to the current system UNITS.Function• Modify Ray/Beam DataSyntaxSCALE FROM units [ LIST ]OptionunitsLISTDescriptionGiven length unitsDecodes transformation matrix into simple operations (ifpossible) and printsRemarks1. Scales from the given length units to the current system UNITS.2. For allowable units strings, See the UNITS command.3. If system UNITS are not set, they are set to units and no scaling takes place.SCALE Examples

<strong>ASAP</strong> | Commands and Macros (S) | 322SCATTER (<strong>ASAP</strong> Command Argument)This command argument for inhomogeneous Monte-Carlo scattering.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax... [ SCATTER m [ k e t [ l ] ] ]USEROptionmktDescription<strong>Reference</strong> to a VOLUME scattering MODELThe magnitude of k is the SURFACE designation for thisfunctionStep lengthRemarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. Inhomogeneous scattering can be handled by assigning to the medium a GENERAL polynomial in the globalcoordinates X,Y,Z or USERFUNC function (with additional wavelength w dependence). The magnitude of k is theSURFACE designation for this function. The scattering at each point in the medium is then multiplied by:3. For the case of USER, m and e are arbitrary integer and float parameters, respectively, passed to the user-suppliedFortran function USERSCAT.4. If k is zero, the positional coordinates of the ray are also passed. Otherwise, the value and gradient of FUNCTIONentity k are passed instead. With the additional passing of the current complex refractive index, the Fortranfunction then allows you to change the wavelength, flux, and/or direction of the ray while returning a mean-freepathlength for the next interaction.5. The t is always the step length to be used by <strong>ASAP</strong> to sample the inhomogeneous medium when tracing a ray.SCATTER ExamplesSCATTER RANDOM or MODEL (<strong>ASAP</strong> Command)Assigns a scattering interface to an object.Function• Create/Modify ObjectsSyntax 1SCATTER [ RANDOM [ r' n ] ] [ ABS r t ]REL

<strong>ASAP</strong> | Commands and Macros (S) | 323Syntax 2SCATTER MODEL mMODELS m m'OptionRANDOMr'nABS or RELr tm m'MODEL m m'DescriptionSpecifies Lambertian scatter propertyTotal hemispherical reflectivity (TIS)Number of randomly distributed scatter rays to begenerated (default value is 1)Specifies absolute or relative scatterSeparately scales the magnitude of the reflective/transmissive components; required with INTERFACEand LEVEL ALL for two-way scatteringModel number for the scatterAssigns reflective m and transmissive m' scatter modelsto the interfaceRemarks1. SCATTER RANDOM assigns incoherent random diffuse scattering properties to an interface and may be used tosimulate Lambertian scatter at the interface (equally bright in all directions).2. All rays generated by RANDOM have the same flux.3. The RANDOM option does not require the modifier TOWARDS, but BRO recommends it since it is more efficient toscatter TOWARDS an importance sampled edge.4. Using the MODELS option requires non-zero specular reflection and transmission coefficients on the INTERFACEcommand. Use INTERFACE 1E-15 1E-15 to eliminate the specular rays, while still allowing two-way scatter.5. The LEVEL command limits the number of generations of scattered rays. See the LEVEL command topic forfurther details.6. The r' is the total hemispherical diffuse reflectivity of the scattering surface. The r'=1 corresponds to whiteLambertian.7. The n is the number of rays to be scattered into the hemisphere centered on the ray intersection point.8. If both reflective and transmissive (or multiple diffraction orders) scatter rays are generated (see the LEVEL ALLcommand topic), the specified scatter can be separately scaled in magnitude for the two components by the givenr and t factors. The scatter specified can also be either ABSolute (referenced to incident power) or RELative to thespecular power. The default is ABS 1 1 (except for SCATTER RMS, which is REL 1 1).9. <strong>ASAP</strong> allows reflected and/or transmitted scatter models to be combined with total internal reflection (TIR). Thisenables, for example, approximate simulation of lossy waveguides, for which scatter partially frustrates TIR.Caution: energy is not conserved.10. To produce scattered rays, SCATTER MODEL m must be followed by the TOWARDS modifier.11. If reflective m and transmissive m' scatter models are different, specify both.SCATTER ExamplesSCATTER REPEAT (<strong>ASAP</strong> Command)Assigns the scatter characteristics of a given object to the current object.Function

<strong>ASAP</strong> | Commands and Macros (S) | 324• Create/Modify ObjectsSyntaxSCATTER REPEAT [ i ]OptioniDescriptionObject numberRemarks1. Assigns the scatter characteristics of object i (or the previous object) to the current object.2. If i is zero, all the scatter properties are removed.SCATTER ExamplesSCATTER RMS/BSDF (<strong>ASAP</strong> Command)Assigns a near-specular scattering interface to an object.Function• Create/Modify ObjectsSyntaxSCATTER [ RMS b [ s a ]BSDFOptionRMS or BSDFbsaDescriptionSpecifies incoherent near-specular scatter inputEither the RMS microroughness of the surface inwavelength units, or actual BSDF in inverse steradians at0.573 degrees from specularAsymptotic falloff of surfaces PSDF (also the BSDF) inthe direction cosine space, typically a number between -1and -2Back scatter divergence angleRemarks1. Assigns incoherent, near-specular scattering properties to an object, thereby simulating the type of scattercommonly seen on a smooth optical surface.2. Since the SCATTER RMS command requires the reflection and transmission coefficients, an INTERFACEcommand must be executed first.3. If scattered ray/beam generation is turned on by the LEVEL command, <strong>ASAP</strong> generates a diverging near-specularbeam at any interface with a non-zero b value.4. If the cone half-angle in radians a is non-zero, <strong>ASAP</strong> generates a back-scattered beam that propagates back alongthe incoming direction of the ray with a half-angle divergence of a radians in addition to the forward-scatteredbeam. The scatter in this direction is calculated using the b, s, or m parameters.5. If a is negative, only the back-scattered beam is generated at the interface; the forward-scattered beam issuppressed. The scatter in this direction is calculated using the b, , or m parameters.

<strong>ASAP</strong> | Commands and Macros (S) | 325CAUTIONDo not use these commands to assign a Harvey model to an object; use MODEL, HARVEY, and SCATTER MODELfor this purpose.SCATTER Examples$SCR (<strong>ASAP</strong> Macro)Defines a user-programmable screen template.Syntax$SCR [ name ] [ 'title' ]mScreen definition file extensionMaximum screen sizeRegister field start delimiter \Register field end delimiter \ ?Literal field designator "Integer field designatorFloating point designator .Boolean field designator :RemarksSCR79 x 24 characters(nothing at end of register)1. This macro may be used to define a screen template from which any group of variables may be displayed ormodified by editing their assigned fields. In this case and instead of the normal end-of-file, a line with only aclosed brace } in column one can be used to terminate the template definition and signal the beginning of up to1000 lines of 79 character-wide help text.2. The template may be read from a file called name.scr or from the m records that follow.Note: Screen files invoked with the $SCR command are searched in the following locations, in this order:• working directory, and• $SEARCH path elements, in the order assigned.3. Within the screen template, each register field is delimited by either two back slashes \\ for display-only fields or abackslash and question mark ? for modifiable fields. The register name immediately follows the first backslash.4. A colon, caret, period, double quote or nothing at the end of the register name determines the register data type;Boolean, floating point, literal or integer, respectively. If floating, a single-digit number to the right of the perioddetermines the number of digits to the right of the decimal point to display. The overall size of the field, and theregister value displayed in it, are controlled by the position of the second delimiter.5. If there are no editable fields in the template (no question marks ?), the result is written directly as simple text tothe current output device.Screen definition file extension:Maximum editable screen size:Maximum output template size:SCR79x24 characters344x24 characters

<strong>ASAP</strong> | Commands and Macros (S) | 326Register field start delimiter: \Register field end delimiter \ ?Literal field designator "Integer field designator:Floating point designator: .# digits right of decimal point: .#Boolean field designator: :Exponential field designator6. The display attributes of the background and fields can be programmed according to the following table:Entry Default Meaningat 7 Background textaw 7 Write-only fieldsar 0 Read fields beforeau 0 After update7. The Tab and Shift-Tab keys are used to move the pointer within the dialog.8. Press Enter after each entry, and click OK or Cancel as appropriate to exit the dialog.9. The screen is displayed in the upper-right corner.10. To display the Cancel button, enter SCR_CANCEL=1 before the $SCR command. If SCR_CANCEL=0, thebutton does not display.11. If you need text or display-only fields, enter \DUMMY : ? at the end of the .SCR file to display the window.12. If you click OK, SCR_CANCEL becomes 0.13. If you previously clicked OK, reset SCR_CANCEL to 1 before using it each time. Otherwise, the next $SCRcannot display a Cancel button.14. After the $SCR line, enter:$IF (SCR_CANCEL) EQ 1; $GO usercancel !! or a similar jump to skip thecode that you do not want to execute!!15. When the screen template displays, the OK and Restore buttons are visible. Click OK if you want the INR fileto continue from the point the $SCR command was issued. If you entered values but want to return to the originalsettings, click Restore. This action restores the default values that were in place when you issued the $SCRcommand.$SCR Examples^SEARCH (<strong>ASAP</strong> Command)Sets the local and global object intersection strategy.Function• Setup TraceSyntaxSEARCH [ LIST ][ ALL FORWARD ]SEQUENTIAL BACKWARD

<strong>ASAP</strong> | Commands and Macros (S) | 327i j j' j":OptionLISTALLSEQUENTIALFORWARDBACKWARDDescriptionLists SEARCH settingsAll objects are candidates for intersectionSearches objects sequentiallySearches objects forwardSearches objects backwardi j j' j" On object i, searches objects j through j' in steps of "jRemarksThe SEARCH command provides another method to control the way rays are traced by the TRACE command.Normally, <strong>ASAP</strong> traces rays along all physically realizable paths. The SEARCH command provides per-object searchrules. These rules explicitly specify which objects are considered directly "visible" to rays originating from any givenobject. Namely, a search rule specifies the only "target" objects that are accessible from a given "originating" object.The SEARCH command is useful, for example, to restrict ray tracing to selected paths, and may accelerate ray tracingfor important paths through the system.CautionObjects that are not included as "targets" in the search rule for an "originating" object effectively do not exist forray tracing purposes. Rays pass through such objects unaffected. This can lead to unexpected results, such as rays"passing through" opaque objects that are not explicitly specified as targets.The first element of a search rule specifies the object number i of an originating object. The arguments in thefollowing table specify the range and increment of target objects in which m represents the highest object numberdefined in the system. Any number of search rules can be specified, with one rule per line.InputObjectRange and<strong>Inc</strong>rementj j' j" j to j' by j"ALL 1 m 1ALL FORWARD i m 1ALL BACKWARD i 1 -1SEQUENTIAL i-1 i+1 2SEQUENTIALFORWARD i+1 i+1SEQUENTIALBACKWARD i-1 i-1SEARCH recognizes four special words:1. ALL refers to all objects, including the originating object i. This is important when an object can reflect or scatterlight onto itself.2. SEQUENTIAL alone limits tracing to the objects numbered one higher or one lower than the originating object i.3. FORWARD further limits tracing to objects numbered higher than the originating object.4. BACKWARD further limits tracing to objects numbered lower than the originating object i.The effect of multiple SEARCH commands is cumulative.

<strong>ASAP</strong> | Commands and Macros (S) | 328Invoking SEARCH LIST produces a list of all search rules in effect.Normal raytracing rules can be reinstated by issuing the special command, SEARCH ALL.SEARCH Examples$SEARCH (<strong>ASAP</strong> Macro)Provides user control of which paths are searched, and also the order in which paths are searched. These paths aredefined and associated with symbolic names. $SEARCH specifies up to 20 paths to be searched for screen (*.scr),macro (*.mac), and macro library (*.lib) files.Syntax$SEARCH MENULISTRESETSETSETADDADDsymbol"path"symbol"path"OptionMENULISTSETADDRESETDescriptionDisplays the paths available to the $SEARCH commandDisplays the paths currently in use as search paths by<strong>ASAP</strong>Sets the $SEARCH path to include only the path namedby symbol. Accepts a literal path of up to 344 characters.See Remarks.Appends the path named by symbol to the $SEARCHpath. Accepts a literal path of up to 344 characters. SeeRemarks.Clears the $SEARCH path and restores default behaviorRemarks1. The paths displayed by the MENU option are selected for use by the SET or ADD options.2. To ensure backward compatibility, the list displayed by the LIST option is initially empty when the <strong>ASAP</strong> kernelis started or restarted.3. If ALL is substituted for symbol with the SET option, all available paths in the menu are added, in the order ofappearance in PATHS.txt.4. The literal path limit of 344 characters for the SET and ADD options is inclusive of the required delimiting doublequotes, and is not associated with any symbol.5. Paths defined and associated with symbolic names are in the PATHS.txt file in the <strong>ASAP</strong> installation area, \binfolder.$SEARCH ExamplesSECTION (<strong>ASAP</strong> Command)Prints or transfers the current distribution data to/from variables.

<strong>ASAP</strong> | Commands and Macros (S) | 329Function• Display/Modify Data DistributionsSyntaxSECTION [ m m' [ n n' ] ] [ GET ]PUTOptionm m' n n'GETPUTDescriptionRange of pixels to be printed or transferredFlag to transfer distribution data into variablesFlag to put variables into distribution dataRemarks1. Prints a table of current distribution data or transfers the current distribution data to or from an array of variables.Print, GET into registers or PUT from registers the section of data:f(i,j): i=m to m', j=n to n'2. If the GET or PUT options are used, the first data value is associated with register A0.3. If m'-m > 8 and n'-n > 24, the maximum allowable intrinsic register section is transferred:4. Historical note: the SECTION command was the TABLE command in pre-<strong>ASAP</strong> 5.1 versions.SECTION (<strong>ASAP</strong> Command)SEED (<strong>ASAP</strong> Command)Initializes the seed for the random number generator.Function• Setup TraceSyntaxSEED [ n ] [ QUASI ]OFFOptionDescriptionn Seed number (default =2000000001)QUASIUse a quasi random number sequenceOFFCease using a quasi random number sequenceRemarks

<strong>ASAP</strong> | Commands and Macros (S) | 3301. Initializes the seed value for the random number generator used by the ROUGHNESS RANDOM, GRIDRANDOM, SCATTER RANDOM/TOWARDS and EMITTING commands.2. For EMITTING sources, a QUASI random number Halton sequence can be used instead. In this case, only theremainder of n divided by 50 is used to select among 50 possible sequences.3. The n should be some large, odd integer and is set to 2000000001 at program startup.4. If a zero is entered for n, the QUASI number generator is no longer random and returns a fixed value of 0.5 everytime.5. If no options are given on this command, n is derived from the system clock.6. SEED does not affect the independent random number generator for the ~ (tilde) operator, which is seeded by$RAN.SEED ExamplesSEGMENTS (<strong>ASAP</strong> Command)Controls number of segments plotted per arc.Function• Setup Plots and Verify SystemSyntaxSEGMENTS [ n ]OptionnDescriptionNumber of straight line segments used to approximate a45 degree arcRemarks1. Controls the number of straight-line segments used to draw conic arcs.2. The default number of line segments is 3. The minimum and maximum numbers are 1 and 45, respectively.SEGMENTS ExamplesSELECT (<strong>ASAP</strong> Command)Isolates a ray set for further analysis.Function• Modify Ray/Beam DataSyntax 1SELECT [ ALL ]ADD [ entry entry' [ AND entry entry' ...ORREMOVE [ entry entry' [ AND entry entry' ...ORONLY [ entry entry' [ AND entry entry' ...OREXCEPT [ entry entry' [ AND entry entry' ...NONE

<strong>ASAP</strong> | Commands and Macros (S) | 331Syntax 2SELECT POLYCHROMATIC n|'name'OptionALLADDREMOVEONLYEXCEPTNONEAND ORentry entry'DescriptionSelects all raysConditionally adds raysConditionally removes raysSelects only the specified raysSelects all rays except the specified raysDeselects all raysBoolean logical operatorsSee RemarksRemarks1. Gives the user control over the current set of rays <strong>ASAP</strong> is to consider in all calculations and output (similar to theCONSIDER command for objects).2. ADD and REMOVE: add rays to or remove rays from the currently SELECTed set of rays based on Booleanoperators.3. Boolean conditions are specified by entering pairs of entries separated by a logical operator (AND/OR) accordingto the following table.entry entry' Descriptioni j Ray number is between i through jinclusiveOBJECT n Ray comes from previous object n(name or number)OBJECT -n Ray was scattered from object nOBJECT +n Ray was split from object nSOURCE k Ray originated from source numberkSOURCE -k Scattered ray from source number kMEDIA m Ray is in MEDIA m (name ornumberMEDIA -m Scattered ray is in MEDIA mGENERATION n Ray was split +scattered n timesGENERATION -n Ray was scattered n timesGENERATION +n Ray was split n timesEVERY n Ray number modulo n equals one.HITS n Ray has hit objects n times

<strong>ASAP</strong> | Commands and Macros (S) | 332entry entry' Description-[n]+[n]Ray has hit objects n times and hasnot yet refracted/reflected with lastobjectRay has hit objects n times and hasrefracted/reflected with last objectPATH l Ray belongs to lth path from lastPATHS commandPATH 0 Ray belongs to a path not listed bylast PATHS commandw W Ray has wavelength greater than wW w Ray has wavelength less than wf F Ray has flux greater than fF f Ray has flux less than fd L Ray has optical path length greaterthan dL d Ray has optical path length less thandr R Ray has AXIS radial coordinatesgreater than rR r' Ray has AXIS radial coordinatesless than r't T Ray has AXIS angular coordinatesgreater than t degreesT t' Ray has AXIS angular coordinatesless than t' degreesU i Ray on object's element # i(conicoid, array or patch "row")V j Ray on object's element # j (array orpatch "column")u U Ray has first parametric coordinategreater than uU u Ray has first parametric coordinateless than uv V Ray has second parametriccoordinate greater than vV v Ray has second parametriccoordinate less than vx X Ray has X coordinates greater thanxX x' Ray has X coordinates less than x'

<strong>ASAP</strong> | Commands and Macros (S) | 333entry entry' Descriptiony Y Ray has Y coordinates greater thanyY y' Ray has Y coordinates less than y'z Z Ray has Z coordinates greater than zZ z' Ray has Z coordinates less than z'a A Ray has X direction cosines greaterthan aA a' Ray has X direction cosines lessthan a'b B Ray has Y direction cosines greaterthan bB b' Ray has Y direction cosines lessthan b'c C Ray has Z direction cosines greaterthan cC c' Ray has Z direction cosines lessthan c'4. The sign of the entry for hits determines whether or not the ray has interacted with the last object. A minus signindicates the ray has not yet refracted/reflected. A plus sign or no sign indicates the ray has already refracted/reflected.5. All tests, including logical operations, are applied to each ray individually, one at a time. The ray must satisfy allspecified conditions to be selected. The final number of rays selected is displayed after all rays have been tested.SELECT ExamplesSEQUENCE (<strong>ASAP</strong> Command)Creates a lens composed of a sequence of conicoid surfaces.Function• Define/Modify Lens EntitiesSyntaxSEQUENCE [ CURV ] [ HEIGHT ]RADI DIAMx y z a,b,c h [ r[`p ] k[`s] o m ]REFLd h [ r [ `p ] k [ `s ] o m ]REFL:OptionCURVRADIDescriptionSpecifies a vertex curvatureSpecifies a vertex radius

<strong>ASAP</strong> | Commands and Macros (S) | 334OptionDIAMx y za,b,chrkomdpREFLsDescriptionDiameterGlobal coordinates of the vertex (center) of the conicoid(long format)Normal vector to the conicoid at the vertex (long format)Aperture HEIGHT (semidiameter) or DIAMeterEither the vertex CURVature or RADIusConic constant (0=sphere, -1=parabola, and so on)Central obscuration (or hole) ratioNumber or name of medium that follows the conicoid(use -1 or REFL for a reflector)Distance from previous conicoidFirst optional paired entry p is either a vertex CURVatureor RADIus of a paraboloid that is subtracted from theconicoidReflecting (paraxial (planar) surface of power kMultiplier for aspheric termsRemarks1. Enter the lens directly as a sequence of conicoids (one line of input per surface).2. Two formats are available: a long and short. In either case, the last five entries are the same. The first conicoid of aSEQUENCE must be entered in the long format. The following conicoids may be entered in either the long format(x y z a,b,c) or short format (d) as appropriate.3. If the curvature is non-zero (that is, not flat), k is the conic constant (for example, 0=sphere, -1=parabola).Otherwise, it is the 4th-order aspheric coefficient.4. For a reflecting surface, m is the number or name of the medium that follows this conicoid (use -1 or REFL forreflector).5. If r is zero and k is not, the surface is a refracting or REFLecting paraxial (planar) surface of power k (inversefocal length) or actual focal length k with the RDCV option.6. Currently, this paraxial surface does not adjust the optical path lengths to be consistent with the new raydirections. Therefore, it should not be used in any coherent field analyses.7. The first optional paired entry p is either a vertex CURVature or RADIus of a paraboloid that is subtracted fromthe conicoid. To get an aspheric "flat" (for example, corrector plate), set p equal to r. The 4th-order and higheraspheric terms are then identical to those of the series-expanded conicoid times s.8. For the long format, x y z are the global coordinates of the vertex (center) of the conicoid and a,b,c is the normalto the conicoid at that point. Alternatively, these six entries can be replaced with a distance d from the previousconicoid. Therefore, the first conicoid of a SEQUENCE must always be entered in the long format.SEQUENCE ExamplesSET (<strong>ASAP</strong> Command)Sets the system-wide parameters for <strong>ASAP</strong>, including the maximum number of colorimetry analysis configurations.Function• Save or Recover System Data and Control Execution

<strong>ASAP</strong> | Commands and Macros (S) | 335Syntax 1SET p1 v1 p2 v2 ...OptionDescriptionp1, p2 Names of the <strong>ASAP</strong> system parameterv1, v2 Values of the corresponding <strong>ASAP</strong> system parameterRemarks1. The parameter and the value must be paired in the Command Input window.2. The SET command must be used after the SYSTEM NEW command and before any commands that use thefeatures involving the system parameter, which is reset to a new value.3. System parameters that can be reset:Parameter (p) Description ValueMNPSMNCCMaximum number of polychromaticsourcesMaximum number of colorimetryanalysis configurations that the usercan createAny positive integerAny positive integer4. The default maximum number of colorimetry analysis configurations is 25, which is adequate for mostcolorimetry analysis tasks.5. The default maximum number of polychromatic sources in <strong>ASAP</strong> is 50.6. This command must be called before any colorimetry analysis configuration is created. If the command is calledafter a colorimetry analysis configuration is created, the new setting is effective only after the next SYSTEM NEWcommand is called.SET ExamplesSHAPE (<strong>ASAP</strong> Command)Sets the beam shape of the individual rays of the currently selected rayset.Function• Modify Ray/Beam DataSyntaxSHAPE k [ s ]beam0 [ n a ] [ a' a" ... ]MODEOptionkbeamsDescriptionBeam shape parameterBeam shape name corresponding to kOptional parameter required by certain shape parameters

<strong>ASAP</strong> | Commands and Macros (S) | 336OptionDescription0 (or MODE) Specifies higher-order Hermite-Gaussian beam modesnaa' a" ...RemarksNumber of higher order Hermite-Gaussian beam modesComplex amplitude of TEMoo beam modeComplex amplitudes of higher order beam modes1. Resets the beam shape to the literal beam or integer k for the currently SELECTed ray set.2. <strong>ASAP</strong> currently allows the following beam shapes (the shape is either an amplitude profile for coherent beams ora flux density profile for incoherent beams).Beam k Beam ShapeMODE 0 Complex Hermite-Gaussian beam(default if WAVEL>0)ELIP 1 Uniform ellipse (default whenWAVEL=0), central hole ratio sGAUS 2 External real Gaussian (optionalsupergaussian of order s )RECT 3 Uniform parallelogram with centralhole ratio sBELL 4 Bell-shaped (cosine squared)approximation to GaussianLRNZ 5 General Lorentzian (inverse sasymptotic falloff)SINC 6 Sinc (sinx/x) with Fourier centralhole ratio sSECH 7 Sech (hyperbolic secant)SOMB 8 Sombrero or Airy disk functionwith Fourier central hole sFIBR 9 Fundamental mode of circular fiberat normalized frequency sSLAB 10 Fundamental mode of symmetricwaveguide at normalized frequencys3. The sign of k (or beam) determines whether the beam is incoherently added (intensity summing) or coherentlyadded (complex field summing) to other beams of similar designation.k < 1 Coherent beamk > 0 <strong>Inc</strong>oherent beam4. The optional entry s is an arbitrary factor that is passed to the USHAPE routine.5. For MODE or k equal to 0, n is the number of higher-order Hermite-Gaussian beam modes and a a' "a... are thecorresponding complex amplitudes. The modes are ordered in the following manner: 00 10 01 20 11 02 30 21 1203 40 31 22 13 04 50 ...CAUTIONWhen using SHAPE to alter the beam shape, please be aware that it is possible to create a physically unreal beam.

<strong>ASAP</strong> | Commands and Macros (S) | 3376. The default amplitude for the TEMoo is 1 (unity). The amplitudes of the higher-order beam modes are defaulted tozero.7. When higher-order beam modes are desired, both the number of higher-order modes and their amplitudes must beentered. The number of higher-order beam modes is given by n.8. Ray tracing has no affect upon beam shape; it is a property of the beam and is not altered by propagation.Consequently, it may be reset at any time and may be parametrically varied if desired.9. For k equal to 9, beam name FIBR, the HE 11 fundamental mode of a step-index single-mode fiber with normalizedfrequency s is produced 1,2 . This result typically behaves well for normalized frequencies above 1, but within thesingle-mode regime.1 Fiber Optics and Optoelectronics, Peter K. Cheo, 2nd ed. 1990, Prentice Hall, Englewood Cliffs, New Jersey, p.102.2 Springer Handbook of Lasers and Optics, Frank Träger, ed., 2007, Springer, New York, pp. 476-7.10. For k equal to 10, beam name SLAB, the TE 0 fundamental mode profile of a symmetric slab waveguide withnormalized frequency s is produced 3 . This general result typically behaves well through the single-mode range ofnormalized frequency.3 Fiber Optics and Optoelectronics, Peter K. Cheo, 2nd ed. 1990, Prentice Hall, Englewood Cliffs, New Jersey, pp.19-29.SHAPE ExamplesSHIFT (<strong>ASAP</strong> Command)Specifies a relative shift of an entity along the coordinate axes.Function• Create/Modify Objects• Define/Modify Curvedge Entities• Define/Modify Lens Entities• Define/Modify Surfunc Entities• Modify Ray/Beam DataSyntax 1SHIFT [ x y z ] [ LIST ]X xY yZ zSyntax 2SHIFT d ALONG a,b,c [ LIST ]OptionDescriptionX, Y, Z Shifts axisx, y, z Relative shift along coordinate axisdDistance along a given directiona b cDirection vector

<strong>ASAP</strong> | Commands and Macros (S) | 338OptionLISTDescriptionDecodes transformation matrix into simple operations (ifpossible) and printsRemarks1. Translates the entity by the given distances (x,y,z). The default distances move the reference point of the entity tothe global origin.2. To shift a distance d along a given direction (a,b,c), use the second syntax.3. If used with REPEAT, group SHIFT with these commands: MATRIX; ROTATE; SCALE; SKEW; PLACE;ALIGN; XEQ.Examples!!++!! SHIFT02.INR!! Title: Shifting Rays!! Category: Isolated Command!! Keywords: SHIFT!! Description: SHIFT command is used in same!! way for an Object or an Entity.!! Edit History (latest first)!! 02/018/2002 - cl - creation!!--!! Shift rays 15 units parallel to Z axisRAYSSHIFT Z 15SHIFT ExamplesSHOW (<strong>ASAP</strong> Command)Displays current settings.Function• Setup Plots and Verify SystemSyntaxSHOW [ ALL ]Remarks1. SHOW presents the complete complex coefficients of POLARIZ.2. Prints out the current status of some or ALL of those commands that set flags or data used by other commands.These commands include: ACCURACY, ARROWS, AXIS, BEAMS, BILATERAL, CLIP DIRECTION/POSITION, CUTOFF, FRESNEL, HALT, IRRADIANCE, LEVEL, LIGHT, LSQFIT,POLARIZATION, SAVE, SEED, SEGMENTS, SPLIT, TITLE, UNITS, UPDATE, WARNINGS,WAVELENGTH, WIDTHS, WINDOW, and XMEMORY.3. System parameters that can be reset:

<strong>ASAP</strong> | Commands and Macros (S) | 339Parameter (p) Description ValueMNPSMNCCSHOW ExamplesMaximum number of polychromaticsourcesMaximum number of colorimetryanalysis configurations that the usercan createAny positive integerAny positive integer$SHOW (<strong>ASAP</strong> Macro)Displays the status and states of several internally defined macros.Syntax$SHOW&SHOWRemarks1. Macro shows the current states of internal macro commands.2. The & version also lists the internal stack code (operators/operands) for any $FCN definitions.Examples$IF (<strong>ASAP</strong> Macro)$SHOW ExamplesSINGLET (<strong>ASAP</strong> Command)Creates a simple singlet lens.Function• Define/Modify Lens EntitiesSyntaxSINGLET X x t h m [ RD r r']Y yCV c c'Z z FL f b [ a ]a APLANATOptionX or Y or Zx or y or zthmDescriptionGlobal coordinate axisLocation on the global coordinate axisLens thicknessAperture heightInternal medium (number or name)

<strong>ASAP</strong> | Commands and Macros (S) | 340Optionr r'c c'fbAPLANATaDescriptionRadii of curvature of the two surfacesCurvatures of the two surfacesFocal lengthBending parameterProduces zero third-order spherical aberration and comaConjugate factorRemarks1. This lens entity starts out normal to the defined global coordinate axis (X, Y or Z).2. RD is used to specify radii of curvature (r r'), CV is used to specify curvatures (c c'), and FL is used to specifyfocal length f and bending parameter b.3. The bending parameter b is defined as (c+c')/(c-c') or, equivalently, as (r'+r)/(r'-r); therefore, b=0 implies abiconvex or biconcave element; b=-1 implies a plano-convex or plano-concave element; and b=1 implies aconvex-plano or concave-plano element.4. a is an optional conjugate factor; that is, 1 plus the object-to-image magnification divided by 1 minus themagnification (0=one-to-one imaging, 1=infinite object distance, -1=infinite image distance)5. If the APLANAT option is used, the bending factor is automatically determined for the given a so that third-ordercoma is also eliminated (assuming the thin lens approximation applies).SINGLET ExamplesSKEW (<strong>ASAP</strong> Command)Specifies an arbitrary skewing of an entity.Function• Define/Modify Lens EntitiesSyntaxSKEW X a Y [ c ] [ LIST ]ZY a ZXZ a XYOptionX Y ZacLISTDescriptionSkew direction (first column of X,Y,Z)Angle measured in degrees from the second direction(second column of X,Y,Z)Corresponding coordinate of the skew center in seconddirectionDecodes transformation matrix into simple operations (ifpossible) and prints

<strong>ASAP</strong> | Commands and Macros (S) | 341Remarks1. Skews the entity in the first direction by an angle a measured in degrees from the second direction.2. The corresponding coordinate of the skew center is optionally given by c. The skew center is defaulted to thereference coordinate of the entity.SKEW ExamplesSMOOTH (<strong>ASAP</strong> Command)Quadratically (or cubically) smooths the current curve.Function• Define/Modify Curvedge EntitiesSyntaxSMOOTH [ 2 ]3OptionDescription2 Quadratically smooth the current curve (default)3 Cublicly smooth the current curveRemarks1. Quadratically (default 2) or cubicly (default 3) smooths the current curve, assuming it is piecewise linear; that is,one created by the ELLIPSE, ROUNDED, or OVAL command.SMOOTH ExamplesSOLID (<strong>ASAP</strong> Command)Makes the previous surface a solid.Function• Define/Modify Surfunc EntitiesSyntaxSOLID PLUS [ NOHOLE ]MINUSOFFOptionPLUSMINUSNOHOLEDescriptionUses positive side of surface/functionUses negative side of surface/functionExcludes the interior hole of the LOCAL box, if oneexists

<strong>ASAP</strong> | Commands and Macros (S) | 342OptionOFFDescriptionSets the SOLID command to offRemarks1. Makes the current surface a SOLID formed from the interior of its LOCAL box and the given side of the function.2. Currently, the SOLID command affects only the BOUNDS command.3. If the volume needed can be represented by just a LOCAL box, use the above command with a dummy degree zerosurface. See example below.SURFACE nGENERAL x y z +1LOCAL ...SOLID PLUS:OBJECT:BOUNDS +-nSOLID ExamplesSOURCE (<strong>ASAP</strong> Command)Specifies sources for the rays/beams.Function• Create Rays and BeamsSyntaxSOURCE POSITION x y z [ x,y,z' x,y,z" ... ]FOCUSLINEDIRECTION a,b,c a,b,c' a,b,c" ... [ RANDOM f ]GRID [ ONE ]OptionPOSITIONFOCUSLINEx y zx,y,z' x,y,z"...DIRECTIONa,b,ca,b,c' a,b,c" ...DescriptionDefines the angular properties of a diverging beamDefines the angular properties of a focusing beamDefines the ray propagation for an ellipsoidal or linesourceGlobal coordinate of point from which rays appear toemanate (POSITION) or converge (FOCUS)Additional source pointsDefines the angular properties of a collimated beamDirection vectorAdditional source direction vectors

<strong>ASAP</strong> | Commands and Macros (S) | 343OptionRANDOM fGRIDONEDescriptionRandomizes the directions within an angle f times thedivergence angleSets up a grid of sourcesTreats the entire grid as one sourceRemarks1. The SOURCE command is used after the GRID and RAYSET commands to initialize the directions and opticalpath lengths of the rays.2. The vector (a,b,c) specifies a direction assigned to all the rays; that is, a collimated beam.3. It is not necessary to normalize the direction vector; <strong>ASAP</strong> does it automatically.4. With the LINE option, each pair of coordinates locates the foci of an ellipsoidal wavefront. If the foci aresufficiently separated, one effectively gets a line (or cylindrical) source.5. The optical path length of the first ray is always zero.6. More than one source location or direction can be entered on SOURCE.7. With the DIRECTION option, the directions can be RANDOMized within an angle f times the divergence anglegiven on the PARABASAL command.8. DIRECTION can be used with the first parameter as the AXIS (X Y Z), and with the second parameter as theangle in degrees made to that axis. For example, SOURCE DIR Z 50 makes rays go at 50 degrees to the Z axis.9. The GRID option uses the coordinates defined in the last GRID command (GRID DATA, GRID ELLIPTIC,GRID HEX, GRID OBJECT, GRID POLAR, or GRID RECT, GRID WINDOW) as the SOURCEcoordinates and not as starting ray coordinates.10. If the GRID option is used with the DIRECTION option, the grid coordinates are interpreted as direction cosines.Therefore, the sum of the squares of the grid coordinates should not exceed one; if they do, they are eliminatedfrom the grid. The sign of the third direction is taken from the 4th entry on the GRID command.11. By default each entry in the source grid is treated as a separate source. The entire source grid may be treated asa single source by using the ONE option. (It may be necessary to treat all sources as a single source if the totalnumber of individual sources exceeds the maximum number of sources permitted in a given installation of <strong>ASAP</strong>.)12. Multiple SOURCEs refer to the same grid of rays. Each is a different source, but all sources initially are referencedas OBJECT 0.SOURCE ExamplesSOURCE POLYCHROMATIC (<strong>ASAP</strong> Command)The SOURCE POLYCHROMATIC command creates a polychromatic source.Function• Create Rays and BeamsSyntax 1SOURCE POLYCHROMATIC BB t f n lambda1 lambda2 [RANDOM POSITION|DIRECTION|BOTH r [a]] [BASE i] ['name']Syntax 2SOURCE POLYCHROMATIC CIE|FCN [CIE standard illuminant|FCN name] f n lambda1lambda2 [RANDOM POSITION|DIRECTION|BOTH r [a]] [BASE i] ['name']

<strong>ASAP</strong> | Commands and Macros (S) | 344Syntax 3SOURCE POLYCHROMATIC TABLE f n[BASE i] ['name']w cw' c':[RANDOM POSITION|DIRECTION|BOTH r [a]]Syntax 4SOURCE POLYCHROMATIC FILE file-name f n [SKIP h] [RANDOM POSITION|DIRECTION|BOTH r [a]] [BASE i] ['name']OptionCIECIE standard illuminantFCNFCN nametfnlambda1lambda2SKIP hraBASE inameDescriptionStandard CIE illuminants are used for spectraldistribution. See Remarks.Identifier for illuminantUser-defined function ($FCN) is used for spectralintensity. See Remarks.Name assigned to $FCNBlackbody temperature in kelvinsRadiant flux for the polychromatic sourceNumber of sampled wavelengths in the spectrumStart wavelength of the spectrumEnd wavelength of the spectrumNumber of header lines to skip in the data fileRange to randomize the position of the raysCone angle around the ray direction to randomize the raydirection in units of degrees<strong>Reference</strong> to the source model that is used to generatethe polychromatic source. See Remarks.Name of the polychromatic source, up to 32 characters.The name is case insensitive; lower-case characters areconverted to upper case. The name must be in <strong>ASAP</strong>command syntax (for example, POLYCHROMATIC 1).w, w' Spectral power distribution wavelengthc, c' Corresponding spectral power distribution valueRANDOMRemarksSee Remarks.1. The SOURCE POLYCHROMATIC command creates a polychromatic source by duplicating the single-wavelengthsource specified by BASE i (using absolute or relative referencing), or the latest defined single-wavelength

<strong>ASAP</strong> | Commands and Macros (S) | 345source at specified sample wavelengths with a proper relative spectral power distribution. A polychromatic sourceconsists of many single-wavelength sources. The single-wavelength source is defined by using commands such as:GRID, SOURCE, EMITTING, ROTATE, and FLUX.2. Each SOURCE POLYCHROMATIC requires its own baseline source definition. By using the BASE option, a givensource definition can be applied to multiple polychromatic sources. For example:!!This is the first defined sourceGRID ELLIPTIC Z 0 -4@1 11 11SOURCE POSITION 0 0 -5SOURCE POLYCHROMATIC CIE D50 100.0 97 380 680'CIE_D50_BUILT_IN'...SOURCE POLYCHROMATIC CIE D50 100.0 97 380 680 BASE 1'CIE_D50_BUILT_IN'SOURCE POLYCHROMATIC CIE DTC6500 100.0 107 300 830BASE 1 'CIE_DTC_6500K_BUILT_IN'3. By default, the maximum number of allowed polychromatic sources is 50, which can be reset to any number withSET MNPS n. This command must be used before a polychromatic source is defined.4. The SOURCE POLYCHROMATIC command adds the specified number (n) of single-wavelength sources tothe source list. Be aware that the total number of independent monochromatic sources that are allowed is easilyreached if you are defining a large number of polychromatic sources. The total number (currently 4096) is printedin the command output window by running the DIMENSIONS command.5. Wavelength must be specified in units of nm for blackbody polychromatic sources and CIE standard illuminants.6. CIE standard illuminants C, D50, D55, D75, and F1 to F12 are supported with tabulated data in 5nm resolution.Linear interpolation is used for higher resolutions.7. CIE standard illuminants A and D65 are supported with tabulated data in 1nm resolution. Linear interpolation isused for higher resolutions.8. For an arbitrary CIE D-series illuminant with correlated color temperature of T c in kelvins, the CIE standardilluminant must be specified as DTCxxxx, where xxxx is the correlated color temperature T c . The temperaturerange is 5000K to 20,000K.9. The CIE standard E source is supported and is a uniform source in which the spectral power distribution (SPD) isconstant in the visible spectrum. Any resolution is supported since it is just a constant for the SPD.10. The wavelength spectrum must be uniformly sampled for a blackbody radiator, all CIE standard illuminants, and$FCN-driven polychromatic sources.11. The wavelength spectrum can be sampled at arbitrary intervals that are specified in the table, or the file forTABLE- and FILE-driven polychromatic sources. BRO recommends as a best practice to use standard or equalincrement wavelength spacings in your definitions for the SPD.12. For FILE-driven polychromatic sources, the relative spectral power distribution must be specified in theformat of: wavelength and SPD value on each line. The file extension must also be specified (there is no defaultextension). Up to 1000 data pairs/lines can be specified. The file can have any number of header lines before theSPD data. The number of header lines must be specified on the command line with the SKIP h option.13. The default name of the polychromatic source is POLYSOURCE####, where #### is the index of thepolychromatic source.14. The wavelength-sampling resolution/step is calculated by (lambda2 - lambda1)/(n-1). For example, to sample thespectrum from 380nm to 780nm at 5nm resolution, n must be 81, not 80.15. BRO recommends that a WAVELENGTHS command be set before the source definition to determinewavelength units. (The value of the wavelength on the WAVELENGTHS command is ignored by the SOURCEPOLYCHROMATIC option.) A sufficient number of WAVELENGTHS should be defined to allow accuratecalculation of the index of refraction at all source wavelengths. A sufficient number of WAVELENGTHS shouldbe defined to allow accurate calculation of the index of refraction at all source wavelengths. See the MEDIAcommand.

<strong>ASAP</strong> | Commands and Macros (S) | 34616. The polychromatic source can be selected as a whole with the POLYCHROMATIC option for the SELECTcommand; see the SELECT command for details. Individual wavelength components of a polychromatic sourcecan be selected by combining multiple SELECT options, such as:SELECT ONLY POLYCHROMATIC p AND w1-d W AND W w1+d17. The polychromatic source information can be checked with LIST SOURCE POLYCHROMATIC. Individual,single-wavelength component sources of the polychromatic sources can be checked with the classic LISTSOURCES command.18. The RANDOM option can be used for both GRID and EMITTER sources. By design, each GRID or EMITTER thatis used in the SOURCE POLYCHROMATIC command at a specified wavelength has the same ray distribution inposition and propagation direction. Although EMITTER rays are randomized in position and propagation directionwhen created, each EMITTER that is used in the SOURCE POLYCHROMATIC command continues to have thesame ray distribution in position and propagation direction, unless RANDOM is specified as an option.SOURCE POLYCHROMATIC ExamplesSOURCE WAVEFUNC (<strong>ASAP</strong> Command)Specifies the ray propagation direction using a wavefront function.Function• Create Rays and BeamsSyntaxSOURCE WAVEFUNC k [ p k' p' ... ]XYZNOptionkDescriptionPreviously defined surface/functionp Power to which surface/function is raised (default is 1)k' p' ...Specifies additional sourcesX, Y, or Z Direction along which ray positions are moved to thewavefront surface kNRemarksMoves ray positions along surface normal to thewavefront surface k1. The wavefront function or eikonal is specified by the previously defined SURFACE FUNCTION k raised to thepth power (default 1) and the ray GRID.2. The normalized gradient of the function (times the sign of k) becomes the direction of the ray, the normalizedvalue its optical path length.3. Alternatively, the rays generated by a GRID command are moved along the given direction X, Y, Z or along thesurface normal N to the actual wavefront surface k.

<strong>ASAP</strong> | Commands and Macros (S) | 3474. Multiple source wavefronts can be created with additional pairs of entries and refer to the same GRID of rays.Each is a different source, but all SOURCEs initially are referenced as OBJECT 0.SOURCE ExamplesSPECTRUM (<strong>ASAP</strong> Command)Simplifies flux weighting of rays as a function of wavelength - for spectral apodization.Function• Setup Beam CreationSyntaxSPECTRUM [ OFF ]FCN fcn [ s ]VISUALSCOTOPICTHERMAL tPHOTONS tw w' w" w'"...OptionOFFfcnsVISUALSCOTOPICTHERMALPHOTONSw w' w" w'"...DescriptionTurn off spectral apodizationName of the functionScale to some other peak valueStandard Luminosity Curve (photopic eye in bright light)Eye response in dim lightPower output of a blackbody at temperature t (degreesK)Photons/second of a blackbody at temperature t (degreesK)Table of weightsRemarks1. Spectrally apodizes individual monochromatic sources that constitute a polychromatic source.2. Sets up or turns OFF spectral apodization (flux weighting as a function of wavelength) for future ray/beamcreation.3. Two user-definable curves are provided. They can be either a $FCN called fcn or a table of weights w w' ... (up to200, with one for each wavelength specified on the last WAVELENGTHS command).4. Four standard spectral curves are provided, and are defined as follows:VISUALSCOTOPICTHERMALStandard Luminosity Curve (photopic eye in brightlight)Eye response in dim lightPower output of a blackbody at temperature t (degreesK)

<strong>ASAP</strong> | Commands and Macros (S) | 348PHOTONSPhotons/second of a blackbody at temperature t(degrees K)SPECTRUM ExamplesSPLINE, EXPLICIT 2D (<strong>ASAP</strong> Command)Explicit 2D curvature (G2) continuous, piecewise cubic spline curve in the given plane (default 0).Function• Define/Modify Curvedge EntitiesSyntaxSPLINE X [ x ]Y yZ zh s d [ c ]h' s' [ d'][ h" s" [ d"] ]:Remarks1. Defined in terms of subsequent heights (next coordinate), slopes, optional distances (remaining coordinate), andstarting curvature c (inverse radius).SPLINE ExamplesSPLINE, GENERAL 3D (<strong>ASAP</strong> Command)General 3D piecewise, cubic, spline curve with given reference point (default origin), and defined in terms ofsubsequent relative points and tangent directions (and optional inverse radii of CURVatures).Function• Define/Modify Curvedge EntitiesSyntaxSPLINE [ x y z ]x y z a, b, cx' y' z' a',b',c'[ x" y" z" a",b" c" ] ]:Remarks1. If a tangent direction is not provided for any point, one is calculated by finite differences using the adjacent points.Therefore, this command can also be used as an (often better) alternative to POINTS followed by SMOOTH 3(although it does create a curve with three times as many Bezier points).SPLINE Examples

<strong>ASAP</strong> | Commands and Macros (S) | 349SPLIT (<strong>ASAP</strong> Command)Controls the number of times a ray may be split into specular components.Function• Create/Modify Objects• Setup TraceSyntaxSPLIT [ n ] [ MONTECARLO ] [ 'c' ]TRANREFLNORMOFFALLOptionMONTECARLOnOFFTRAN, REFL, or NORMcALLDescriptionNo additional specular and/or scatter rays are createdMaximum number of times a ray can be split intospecular componentsResets n to zeroSplit trace operation selection; NORM is the defaultFractional energy cutoff for ray splittingAllows all possible ray splitting to occur above CUTOFFRemarks1. This command can be used either as a local command to override defaults for the current object, or as a globalcommand. In the latter case, the command acts as an interface control and becomes the default used by any objectfor which it is not explicitly set. Since the global command is identical to the OBJECT subcommand, make sureyou are not at the OBJ> prompt when you use it as a global command. If you are, issue a RETURN command first.2. SPLIT can be applied on an OBJECT by OBJECT basis. In effect, this is now an OBJECT modifier, similar to theINTERFACE command.3. Controls the splitting of the children rays, which are rays that have been split off a parent ray. Therefore, SPLIT1 tells <strong>ASAP</strong> to split the parent rays, but the children rays are not allowed to split. SPLIT 2 allows the parentrays and the children rays to split as often as necessary, but the grandchildren rays are not allowed to split, and soon. The parent ray is a ray originally created by the GRID or RAYSET commands.4. Since the total number of rays to be traced can become quite large, SPLIT should be used with some attention tothe possible consequences of generating a large number of split rays. For a typical application such as ghost imageanalysis, n=2 is sufficient.5. Even though <strong>ASAP</strong> has virtual ray storage, you are practically limited by your total free disk storage and long runtimes. Therefore, the default deterministic splitting should be used with these restrictions in mind. The SPLITALL option allows ray splitting to occur as many times that there are opportunities for rays to split and ray energyhas not dropped below CUTOFF.6. Splitting may occur at interfaces with nonzero reflection and transmission coefficients as well as on diffractiongratings with multiple orders. When <strong>ASAP</strong> encounters a nonzero reflection and transmission coefficient on anINTERFACE command, it automatically sets SPLIT to 1.7. Normally, if the transmission coefficient is equal to or greater than the reflection coefficient, the transmitted rayis the first ray propagated. If the reflection coefficient is greater than the transmission coefficient, the reflected ray

<strong>ASAP</strong> | Commands and Macros (S) | 350is the first ray propagated. The split trace option selection allows the most energetic ray at NORMal incidence (thedefault), the TRANsmitted or REFLected component to be traced first, while the other component is traced later.8. Total internal reflection is considered a ray error unless SPLIT is turned on.9. With the MONTECARLO option, no additional specular and/or scattered rays are created. Both the total numberof rays and the total power summed over all rays are conserved. The direction of each ray after intersecting anobject is selected randomly from among the assigned reflection, refraction, diffraction, or scatter properties. Theprobability that a given direction is selected is proportional to the flux that would actually reflect, refract, or scatterinto that direction. If the total power from reflection, refraction, diffraction, and scatter is less than 1 on an object,the ray may stop on that object. This represents absorption by that object. When the MONTECARLO option isselected, you must arrange the interface and scatter commands so the total power from reflection, refraction,diffraction, and scatter never exceeds 1 for any angle of incidence.10. When the TOWARDS command is used to simulate scatter from an object, the following rules should be carefullyfollowed:• If a surface has a Lambertian scatter model attached to it, the entry on the TOWARDS command for the numberof scattered rays should be 1. Entering a larger value slows the ray trace and does not improve the accuracy ofthe calculation.• For surfaces that have a non-Lambertian scatter model, the accuracy of the calculation improves as the entryfor the number of scattered rays gets larger.•For non-Lambertian BRDFs, if the maximum BRDF over all relevant angles of incidence and scatter is ,the number of scattered rays N on the TOWARDS command should be greater than .• In most cases, the TOWARDS SPEC option should be used with scatter into the hemisphere above the surface:TOWARDS SPEC (N) 3.14/2 0 where N is the entry for the number of scattered rays.11. For a typical application such as ghost image analysis, a value of 2 for n is sufficient.12. If the fractional energy in the split-off ray/beam is below c (default 1.E-6), splitting does not occur; that is, onlythe main component is propagated.13. To control the level of scattered component splitting, use the parallel command LEVEL. Sets the defaultrefraction/reflection controls for all objects or may be applied only to a specific object.14. Assuming the presence of the Fresnel equations, the global SPLIT cannot be 0 if there are any COATINGPROPERTY BARE commands. The global value is reset to 1. If the initial global SPLIT is greater than 0,encountering a COATING PROPERTY BARE command does not alter the SPLIT value.Example:SYSTEM NEWRESETMEDIA1.5 'GLASS'FRESNEL AVESPLIT 0 !!GLOBAL SPLIT IS 0SURFACEPLANE Z 1 RECT 1 1OBJECT 'PLANE1'INTERFACE COATING BARE AIR GLASSSPLIT 4 !!GLOBAL SPLIT IS 1; LOCAL ON PLANE1 IS 4RETURNSPLIT 0 !!GLOBAL SPLIT IS 0SURFACEPLANE Z 2 RECT 1 1OBJECT 'PLANE2'INTERFACE COATING BARE AIR GLASS

<strong>ASAP</strong> | Commands and Macros (S) | 351!!GLOBAL SPLIT IS 1; LOCAL ON PLANE2 IS 1RETURNSPLIT 3 !!GLOBAL SPLIT IS 3SURFACEPLANE Z 3 RECT 1 1OBJECT 'PLANE3'INTERFACE COATING BARE AIR GLASSSPLIT 0 !!GLOBAL SPLIT IS 3; LOCAL ON PLANE3 IS 0RETURNSPLIT ExamplesSPOTS (<strong>ASAP</strong> Command)Creates a geometric spot diagram for the currently selected ray data.Function• Analyze Ray/Beam DataSyntaxSPOTS POSITION [ u ] [ ATTRIBUTE i ] [ OBJECT ] [ NUMBER [s] ] [ EVERY n ][ 'title' ]PcADDDIRECTIONDcOptionPOSITIONDIRECTIONuPcDcADDATTRIBUTE iOBJECTNUMBERsEVERY n'title'DescriptionSpot diagram of positional ray dataSpot diagram of directional ray dataFORTRAN unit number for distribution data fileSpot diagram of positional ray data for the base ray and/or particular parabasal rays (see Remarks)Spot diagram of directional ray data for the base ray and/or particular parabasal rays (see Remarks)Adds flux data to existing distribution data fileOutput format control (see Remarks)Output color controlDraw the rays number on the plotOptional scale factor for the character sizePlot only every nth ray instead of all the currentlyselected onesOptional title for plot (up to 64 characters)Remarks

<strong>ASAP</strong> | Commands and Macros (S) | 3521. For the current ray set, SPOTS produces a spot diagram of the ray data of the specified type in coordinatedirections specified by the last WINDOW command. By default, the positions or directions of each base ray areused.2. SPOTS may be calculated at any time to examine the ray distribution. <strong>ASAP</strong> projects all SPOTS into the plottingwindow regardless of third coordinate location.3. To calculate SPOTS (or FIELD or SPREAD or OPDMAP) on a tilted surface, use the AXIS LOCAL andIRRADIANCE commands followed by the long form of the SPOTS.4. The WINDOW settings, if not specified, are automatically adjusted for either position or direction cosine data. TheSPOTS calculation is faster if the WINDOW is preset, as opposed to <strong>ASAP</strong> autoscaling the WINDOW. <strong>ASAP</strong> cannotautoscale a finite WINDOW size from just 1 ray. You must explicitly set the WINDOW.5. Use the CONSIDER and SELECT commands to isolate the object(s) and sources whose ray distributions are to beexamined.6. The default distribution file is BRO009.DAT. The flux data for each pixel written to logical unit u in unformatteddirect access binary records whose length is the same as the current PIXELS setting. If u is negative, then anyprevious data on the specified unit is overwritten. Otherwise, the flux data is added pixel by pixel to the existingfile. The default value of u is -9. ADD is equivalent to +9. This file can be manipulated, plotted, and named withthe DISPLAY command and its associated subcommands.7. For the Pc and Dc options, the c entry can be used to select the following specific data:cSCoordinates PlottedCurrent base ray (default)All the current parabasals0 Initial base ray1 First parabasal only2 Second parabasal only: :8. <strong>ASAP</strong> produces a distribution file of accumulated ray fluxes at each pixel location. The ATTRIBUTE option offersother options, other than the default dots, to indicate where each ray strikes, as shown by the following table.ATTRIBUTESymbol-1 Connecting line0 No plot generated1 Plus sign2 X cross3 Up triangle4 Down triangle5 Square6 Diamond9. Since the SPOTS command always creates a new distribution file and overlays the old file, you must save the oldfile before running a new SPOTS command, if the old file is needed for further analysis. This can be done, forexample, with the $COPY command.$COPY BRO009.DAT NEWFILENAME.DIS10. With the OBJECT option, the color associated with the current object of the ray, instead of the source of the ray,is used for plotting the SPOT. In addition, the distribution file contains object number information and not fluxinformation.

<strong>ASAP</strong> | Commands and Macros (S) | 35311. Optionally, the NUMBER of the ray can also be drawn on the plot. The s is an optional scale factor for the charactersize to be used.12. Only EVERY nth ray can be plotted instead of all the currently selected ones (which are still summed in thedistribution file).13. The title is delimited by a single quote ', as shown.14. The command argument, CLIP can be used to specify an object (i) or edge number (j) whose bounds and limitsclips the distribution. If i is not given, it is defaulted to the current object number of the first valid ray. If j isnegative, the interior of the closed edge is used. If j is positive, the exterior of the closed edge is used.15. The command argument, OVERLAY tells <strong>ASAP</strong> not to issue an end of plot so that the next plot created is overlaidwith the current plot. This is useful for combining system plots with ray trace plots (assuming that the WINDOW isthe same for all plots), multiple spot diagrams, and so on.16. The command argument, COLORS n can set one of 27 colors to the spots, overriding the <strong>ASAP</strong> default color.SPOTS ExamplesSPREAD (<strong>ASAP</strong> Command)Calculates the exact coherent/incoherent energy distribution.Function• Calculate Diffraction/Propagation EffectsSyntaxSPREAD DIRECTION [ u ] [ DOWN d d' ] [ COLENGTH l ]POSITION ADDAPPROXNORMALOptionDIRECTION, POSITION, APPROX, or NORMALuDOWN d d'COLENGTH lADDDescriptionCalculation to use (see Remarks)Logical unit number for the distribution data fileRestricts the calculation to a fractional range given by dto d'<strong>Inc</strong>oherently sums any beam whose optical path lengthis different from that of the first valid beam by thecoherence length ladd the calculated distribution to the existingBRO009.DAT fileRemarks1. Calculates the coherent/incoherent energy distribution for the current beam set in the directions given by the lastWINDOW command.2. The particular calculation is selected by the DIRECTION, POSITION, APPROX or NORMAL entry (listedfrom fastest to slowest):OptionFunctionalCoordinatesOptical MethodAssumedCoherenceUnitsDIRECTION d-cosines rough geom incoherent Flux/Ster

<strong>ASAP</strong> | Commands and Macros (S) | 354OptionFunctionalCoordinatesOptical MethodAssumedCoherenceUnitsPOSITION positions rough geom incoherent Flux/AreaAPPROX positions rough wave coh/incoh Flux/AreaNORMAL positions exact wave coh/incoh Flux/Area3. For the SPREAD calculation to take place, a WAVELENGTH (and possibly a PARABASAL) command must beentered before any ray definitions.4. <strong>ASAP</strong> performs this calculation with four or eight parabasal rays. To accurately model astigmatic effects in theGaussian beams, four or eight parabasal rays are required.5. The WINDOW and PIXELS commands affect the sampling used. WINDOW sets up the area in space over which thecalculation is to be performed. PIXEL defines the number of resolution points that are to be contained within thecurrent WINDOW setting.6. DOWN may be used to select only a piece of the WINDOW setting in the down (horizontal) direction. This pieceis determined by the d and d' entries. For example, for d=.25 and d'=.75, the central 50 percent of the window isselected. However, if d=d'=.5, a 1-D profile of the energy pattern along the centerline of the current WINDOW iscalculated.7. The maximum resolution (number of pixels) across the window is dependent on your version of the software.There is no limit to the number of pixels down the window, but the distribution data file is truncated past themaximum number of pixels.8. The default distribution file is BRO009.DAT. This file can be manipulated, plotted, and named with theDISPLAY command and its associated subcommands.9. If the ADD option is present, the calculated distribution is added to the existing BRO009.DAT file.10. SPREAD automatically sums over multiple wavelengths incoherently and only uses beams located in the samemedium.11. If SPREAD APPROX is selected or the number of PARABASAL rays is 0, only symmetric beams are used; that is,individual astigmatic effects are ignored.12. SPREAD NORMAL is exact only if at least four PARABASAL rays were created and/or traced. If there are multiplewavelengths in the current ray set, <strong>ASAP</strong> automatically cycles through each distinct wavelength and incoherently(intensity) sums it with any other wavelengths.13. SPREAD NORMAL does not calculate polarization effects.14. SPREAD NORMAL is nominally equivalent to FIELD ENERGY.15. The COLENGTH option may be used to incoherently sum a subset of beams that is normally coherently summed.Any beam whose optical path length is different from that of the first valid beam by the coherence length l isincoherently summed. The default for l is a very large number; beams with SHAPE factors that are less than orequal to zero are coherently summed.16. The command argument, CLIP can be used to specify an object i or edge number j whose bounds and limits clipthe distribution. If i is not given, it is defaulted to the current object number of the first valid ray. If j is negativethe interior of the closed edge is used, if j is positive, the exterior of the closed edge is used.17. The flux data for each pixel is written to logical unit u in unformatted direct access binary records whose length isthe current PIXEL setting. If u is negative, any previous data on the specified unit is overwritten. Otherwise, theflux data is added pixel by pixel to the existing file. The default value of u is -9.18. ADD is equivalent to +9. This file can be manipulated, plotted, and named with the DISPLAY command and itsassociated subcommands.SPREAD Examples$STAMP (<strong>ASAP</strong> Macro)$STAMP causes <strong>ASAP</strong> to print a timestamp to the Command Output window based on the current system time.

<strong>ASAP</strong> | Commands and Macros (S) | 355Syntax$STAMPRemarks1. The components of the timestamp are also assigned to named registers for convenience.Example$STAMP2010-01-31 17:32:19&REG _YEAR _MONTH _DAY _HOUR _MINUTE _SECOND_YEAR=2010_MONTH=1_DAY=31_HOUR=17_MINUTE=32STATS (<strong>ASAP</strong> Command)Lists statistics of the currently selected ray data.Function• Analyze Ray/Beam Data• Create/Modify ObjectsSyntaxSTATS [ ALL ] [ p ]SOURCESPOSITIONP#DIRECTIOND#OptionALLpSOURCESPOSITIONDIRECTIONDescriptionObject summary for all considered objectsSort by total flux and truncate list below this percentageLists current number of rays and total flux from eachsourceStatistical analysis of positional ray dataStatistical analysis of directional ray dataP# Statistical analysis of positional ray data of the base rayor a particular parabasal rayD# Statistical analysis of directional ray data of the base rayor a particular parabasal ray

<strong>ASAP</strong> | Commands and Macros (S) | 356Remarks1. By default, produces a one-line-per-object summary of the flux and number of rays on each object (ALLconsidered objects, even those with no rays and zero flux on them). It also produces a sum of the total number ofrays and flux on all currently CONSIDERed objects.2. If a second entry is specified, it either lists the current number of rays and total flux from each SOURCE, orproduces a statistical analysis of the POSITIONal or DIRECTIONal ray data including centroids, full variances(RMS deviations), and maximum spreads in each coordinate direction on each object.3. By default, the positions or directions of each base ray is used.4. Any particular parabasal ray may be selected by specifying its number #, for example, P0 is base ray position, D1is first parabasal ray direction, etc.5. The actual objects analyzed may be controlled by the CONSIDER command.6. Optionally, the list can be sorted and truncated below a percentage p of the total flux.STATS ExamplesSTATS TRACE (<strong>ASAP</strong> Command)Prints statistics of a previous TRACE.Function• Trace Rays/BeamsSyntaxSTATS TRACE [ MEDIA ] [ MODELS ] [ OBJECTS ]Remarks1. If the previous TRACE included a STATS or ACCUM option, selectively print the given statistics.2. For OBJECTS (the default), only those currently CONSIDERed are printed.STATS Examples$STO/$RCL/&STO (<strong>ASAP</strong> Macro)Stores or recalls variable data to or from a file.Syntax$RCL [ file ]$STO [ reg reg' ]&STORemarks1. Stores or recalls the range of given registers (or the entire register set) to or from a binary($) or text(&) "file") Thedefault file is LASTVALS.REG.2. $RCL reads in either a binary or text file. If it does not recognize the requested format, it tries the other.3. &STO writes the .REG file in an ASCII format.$STO Examples

<strong>ASAP</strong> | Commands and Macros (S) | 357STORE (<strong>ASAP</strong> Command)Stores the current state of the lens in the <strong>ASAP</strong> internal database, or optionally in the following file types: <strong>ASAP</strong>input , macro, CODE V SEQuence, or Zemax.Function• Define/Modify Lens EntitiesSyntaxSTORE [ name.INR ] [ name.MAC ] [ name.SEQ ] [ name.ZMX ] [ name.LEN ]-name -name+name +nameRemarks1. Virtually all commercial lens-design programs can read this simple version of an Optical <strong>Research</strong> AssociatesCODE V file. The possible exception is the private glass catalog, which can be avoided if you use standard catalogglasses like Schott.2. Stores the current state of the lens into the <strong>ASAP</strong> internal database or, optionally, in an <strong>ASAP</strong> input file, <strong>ASAP</strong>MACro file, CodeV SEQuence file, or ZMX (Zemax) file. The commercial lens design programs can usuallyread these simple versions of their files, except for possibly the private glasses, which can be avoided if standardcatalog glasses like Schott are used.3. The stand-alone <strong>ASAP</strong> files automatically create lens edges, depending upon the sign passed to the EXPLODEcommand, but always does a basic plot with ray traces, and produces spot diagrams across the image surface.STORE ExamplesSUBSET (<strong>ASAP</strong> Command)Selects a subset of the current ray set and rejects remaining ray data.Function• Modify Ray/Beam DataSyntaxSUBSET [ RESET [ m ] ]Remarks1. Collapses ray storage to include only those rays determined by the last CONSIDER, SELECT, and CUTOFFcommands. All other ray information is lost.2. Useful when a lot of rays are traced, and only a small subset is analyzed extensively.Optionally RESET the following information:RESET InformationCurrent object 0Previous objects 0Number of hits 0Specular splits 0RESET value

<strong>ASAP</strong> | Commands and Macros (S) | 358RESET InformationScatter levels 0Parent rayRESET valueItselfOptical Path Length 0 for ray 1Current mediumm if specified3. Useful for preparing the output from one optical system (for example, a complex source) to be the input for acompletely different one.SUBSET ExamplesSUM (<strong>ASAP</strong> Command)Creates a composite scatter model.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxSUM [ X ] i i' [ i" ... ]YZ:Optioni i' i" ...DescriptionPreviously defined model numbersRemarks1. Adds the BSDFs of the given list of previously defined models to form a composite model.2. <strong>ASAP</strong> does not support other VANES and non-VANES models. However, it is fully recursive so that one SUMmodel can reference another.3. Only one anisotropy orientation is used for all the models: either the one specified or the one for the firstanisotropic model listed.4. The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.SUM ExamplesSUPERCONIC (<strong>ASAP</strong> Command)Superconic asphere used in optical design.Function• Define/Modify Surfunc EntitiesSyntaxSUPERCONIC X x d c c' c" a b' b" [ aperture... ]Y y

<strong>ASAP</strong> | Commands and Macros (S) | 359Z zOptiondcDescriptionUsually one (or zero)Vertex curvature (inverse radius)Remarks1. In the Z axis case, the full implicit equation of the surface is given by:Some special cases are:CasePlaneParabolaParabolaSphereSphereConic (constant k)Conic (constant k)Cartesian OvalRational PolynomialNon-zero CoefficientsNonecd=1, a=-cd=1, cc, a=cd=1, c, a=ckc, a=c(1+k)d=1, c, c', a, b'All but d and aSUPERCONIC(<strong>ASAP</strong> Command)SURFACES/FUNCTIONS (<strong>ASAP</strong> Command)Signals <strong>ASAP</strong> that surface definition commands follow.Function• Define/Modify Surfunc EntitiesSyntaxSURFACES [ i ]FUNCTIONS

<strong>ASAP</strong> | Commands and Macros (S) | 360OptioniDescriptionStarting number for defining SURFACES/FUNCTIONSRemarks1. <strong>ASAP</strong> is capable of handling any "implicit" surface that can be represented by an arbitrary function of a general n-th order polynomial in the global coordinates X,Y,Z with arbitrary reference point x,y,z and real coefficients c.2. The default value for i is one more than the highest surface number previously defined. The i is initialized to oneat start of program run.3. EDGES, LENSES, and SURFACES data currently reside in the same internal storage locations. Therefore, aSURFACES number cannot be the same as an already defined EDGES or LENSES number.SURFACES ExamplesSWEEP (<strong>ASAP</strong> Command)Specifies the optional sweeping of a curve into a surface.Function• Define/Modify Curvedge EntitiesSyntax 1SWEEP DIR d [ a,b,c ]TO x y zPOS f [ x y z ]AXIS t a,b,c [ x y z ]Syntax 2SWEEP [ OFF ]dftOptionDIR POS AXISda b cTOx y zftOFFDescriptionSweep type (see Remarks)Sweep distance along a directionSweep direction or axisSweep first point on edge TOSweep pointFractional sweep distanceSweep angleTurns off sweepRemarks

<strong>ASAP</strong> | Commands and Macros (S) | 3611. If DIRection, sweep an actual distance d along direction a,b,c (default is normal to best fit plane through edgepoints) or sweep the first point on edge TO x y z.2. If POSition, sweep edge a fractional distance f towards point x y z (default is centroid of edge points).3. If AXIS, sweep the edge an angle t in degrees around the axis specified by the given direction and point.4. This information is used to define the surface of a single edge object or a BOUNDS edge.5. The SWEEP can be turned OFF or modified with the second syntax.SWEEP Examples$SYS (<strong>ASAP</strong> Macro)Runs a system command or opens a Windows command window.Syntax$SYS [ command line ]Remarks1. If entered without a command line argument, the macro instructs <strong>ASAP</strong> to open a command window. Thiswindow remains open and visible until it is closed with an $EXIT command.2. If this command is entered with a command line, a command window is opened, the command is run, the windowis closed immediately, and control returns to <strong>ASAP</strong>. Given the short time the window is visible on the screen, thissyntax is best for commands that do not require much user interaction, such as the Delete command.$SYS ExamplesSYSTEM (<strong>ASAP</strong> Command)Stores and retrieves system information.Function• Save or Recover System Data and Control ExecutionSyntaxSYSTEM NEWTO [ file ]FROMOptionNEWFROMTOfileDescriptionReinitializes the data storageReads system from fileSaves system to fileName of unformatted binary file (up to eight characters)Remarks1. Initializes <strong>ASAP</strong> at startup. To input a new system, you must reinitialize the data storage using SYSTEM NEW, or<strong>ASAP</strong> appends the new data to the old system data.2. Saving the current system data in a binary format is accomplished with the SYSTEM TO file command.CAUTION:

<strong>ASAP</strong> | Commands and Macros (S) | 362<strong>ASAP</strong> stores only the system data (in a binary format, not a text format). Ray data and associated parameters arenot saved with the system.3. Previously stored system files may be reloaded into <strong>ASAP</strong> with the SYSTEM FROM file command.4. The file extension for system files is *.SYS.5. After an END command and just before exiting, <strong>ASAP</strong> writes out a system data file named LASTEXEC.SYS. Thisfile may be read into <strong>ASAP</strong> during the next session by typing SYSTEM FROM without any additional arguments.6. A Select File dialog box containing all the SYSTEM files in the current directory may be obtained by issuingSYSTEM FROM "*" or SYSTEM FROM_.Note: BRO recommends that you avoid using SYSTEM files for archival purposes, since their binaryformat normally changes between releases. Data from the SYSTEM command saves include:• Data the SYSTEM command saves: Number of surfaces, edges, lenses, number of media, number of objects,number of coatings• Objects' names• Commands used to define each surface, edge, lens• Degree of each surface polynomial, number of points in each edge, number of conicoids in each lens• Number of aspheric terms (using the DEFORM command) used on each object• <strong>Reference</strong> point of each surface, edge, lens• Surface coefficients/edge points/lens parameters• Multiple and array surface data• Test points• LOCAL data (including transformation matrices and others)• Refractive index and absorption data• GRIN data• Names of MEDIA• COATING prescription data• OBJECT status (from CONSIDER command)• LIMITS Main data• BOUNDed surface data• Real/complex reflection/transmission coefficients• INTERFACE media numbers• Diffractive/holographic optic INTERFACE data• Object SEARCH strategy data• INTERFACE scatter data (RMS heights, slopes, BSDFs, RMS roughnesses, important areas, backscatter data andothers)• Current WAVELENGTH, UNITs, and wavelengths used to define dispersive MEDIA• $FCNs needed to create geometrySYSTEM Examples

<strong>ASAP</strong> | Commands and Macros (T) | 363Commands and Macros (T)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “T”.TABLE (<strong>ASAP</strong> Command)Creates a table of the current data.Function• Display/Modify Data DistributionsSyntaxTABLE [ m n ] [ l ] [ SKIP [ s ] ] [ PLOT [ c ] ]OptionDescriptionm n Table range (default 10x10)l Number of characters (default 7, maximum 13)SKIP sPLOTLeaves table entries with value s blankFlag to plot the tablec Character rescaling factor (default 1)Remarks1. Produces an m by n (default 10x10) table of the current data with l characters (default 7, maximum 13) for eachnumber.2. If the SKIP option is used, table entries with the same value as s (default is the minimum value of the data) areblank.3. The table can also be PLOTted where c is a character rescaling factor (default 1). This plotted table can beOVERLAYed with other similar plots such as PLOT BEAMS, PLOT POLARIZATION, SPOTS, FIELD DELTA,or CONTOUR.TABLE ExamplesTELESCOPE (<strong>ASAP</strong> Command)Creates a one- or two-mirror telescope.Function• Define/Modify Lens EntitiesSyntaxTELESCOPE X x h FL1 f [ SEP s FL2 d ] [ STOP p [ m ] ] [ FOV a [ l ] ]Y y FL MAG BWDZ z

<strong>ASAP</strong> | Commands and Macros (T) | 364Option Description SignX or Y or Zx or y or zhGlobal coordinate axisLocation on the global coordinateaxisEntrance pupil heightFL1 f Focal length of primary mirror +FL Overall focal length of telescope +C,-G *SEP s Separation distance between mirrors +MAG Secondary magnification factor +C,-G *FL2 d Focal length of the secondary mirror -C/+G *BWDSTOP pmPosition of final image relative toprimaryDistance from real object spaceaperture stop to primaryMedia number or name for acorrector plate at stopFOV a Semifield angle in degrees +lMedia number or name for a fieldflattening lens* C = two-mirror Cassegrain configuration, G = two–mirror Gregorian configurationRemarks1. Creates a one- or two-mirror telescope with or without a corrector plate and/or field flattener.2. The primary mirror is located at the plane, given the defined global coordinate axis and the location on the globalcoordinate axis.3. The final design is always corrected for third-order spherical aberration, and as many other aberrations as possible.TELESCOPE Examples+/-+++TERRAIN (<strong>ASAP</strong> Command)Prints number of peaks/valleys and full width at half maximum (FWHM) of the highest peak.Function• Display/Modify Data DistributionsSyntaxTERRAIN [ j ] [ LIST ]OptionjLISTDescriptionLine number on print outLists all peaks and valleysRemarks

<strong>ASAP</strong> | Commands and Macros (T) | 3651. Prints out the number (and LISTs all) of peaks/valleys along jth line (for example, fringe statistics).2. Displays the full width at half maximum (FWHM) of the highest peak.3. TERRAIN operates on the data set currently considered by the DISPLAY mode, and is intended to perform asimple estimation of peaks and valleys along “slices” of a surface as defined by data read from a file. The surfacemay, for example, represent an interferogram.Note: The TERRAIN command is not a replacement for conventional data reduction or image processingalgorithms.4. With no parameters, TERRAIN considers the vertical slice of the data (as visualized in <strong>ASAP</strong> using DISPLAYPICTURE) passing through the biased global maximum of the data. (If the location of the global maximum isunique, this is used. If the global maximum is shared by multiple data points, preference is given first to that pointwith the smallest x coordinate. If this is insufficient to break a “tie”, secondary preference is given to the pointwith the smallest y coordinate.)5. If the j parameter is present and is an integer, it is assumed to be the column number, in pixels, of the column toconsider as the slice for analysis.6. If the j parameter is present and is a floating point number between 0.0 and 1.0, it is taken to be the fractionalposition within the data to consider as the slice for analysis. For example, TERRAIN 0.25 selects for analysisthe column that is approximately one-quarter through the data set.7. The command then applies a simple three-point sign-change filter to the selected column to estimate peaks andvalleys. A three-point filter detects only peaks with point-wise curvature; mesas and flat-bottomed valleys arenot detected. So if, for example, the data contains perfectly flat areas – perhaps as the result of a THRESHOLDcommand, and these are not detected. Also, the filter performs no transverse averaging; only data in the exactcolumn selected are considered.8. The LIST option directs <strong>ASAP</strong> to print the location along the slice and data value at each of the peaks and valleysfound.TERRAIN ExamplesTEST (<strong>ASAP</strong> Command)Selects a particular branch of a surface.Function• Define/Modify Surfunc EntitiesSyntaxTEST OFF-POINT x y z+POINT-DIRECTION a,b,c+DIRECTION-AXIS a,b,c [ x y z ]+AXISOptionOFF+/-POINT+/-DIRECTION+/-AXISDescriptionTurns OFF previous or default testTests POINT at (x,y,z)Tests DIRECTION at (a,b,c)Tests AXIS vector (a,b,c) through point (x,y,z)Remarks

<strong>ASAP</strong> | Commands and Macros (T) | 3661. If a surface of order two or greater has multiple branches, usually you are only interested in one of them. Thisproblem is equivalent to the alternate surface intersection problem seen in conventional optical design software.Use TEST to select a given branch relative to a test point or direction.2. TEST initiates the following action: at each intersection with the surface, <strong>ASAP</strong> takes the DIRECTION orthe vector from the POINT to the intersection and dots it with the gradient of the SURFACE at the point ofintersection. The AXIS syntax is useful for surfaces of cylindrical symmetry. <strong>ASAP</strong> draws a vector perpendicularto the AXIS to a point on the curve. In all cases, the intersection is valid only if the result has the indicated sign.Only one entry (OFF/POINT/DIRECTION/AXIS) can be used at a time with TEST.3. Certain commands (OPTICAL, AXICONIC and others) internally generate a test in an attempt to select theappropriate branch. In the event the logic fails, it is usually necessary to issue a new TEST command to get thedesired surface.TEST ExamplesTEXT (<strong>ASAP</strong> Command Argument)Prints text annotation within the graphics window.Function• Standard Plot OptionsSyntax... TEXTx y [ z ] x' y' [ z' ] x" y" [ z" ] [ k ] 'string':Optionx y [ z ]x' y' [ z' ]DescriptionStarting pointCharacter spacing vectorx" y" [ z" ] Character height vectork Color number (1-26)'string'RemarksText annotation1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. Draws text of color k (default 1) on 2D and 3D plots.3. The number of entries determines whether the starting point, character spacing vector and character height vectorare in 2D plot units or 3D system units as follows:• If the number of entries is seven or less, <strong>ASAP</strong> assumes 2D only, paper coordinates (0-10, 0-7.5).• If the number of entries is eight or more, <strong>ASAP</strong> assumes 3D (and 2D projection) system coordinates.4. With 2D coordinates, the plot window is 10 inches wide (horizontal or x direction) by 7.5 inches high (vertical ory direction). Especially useful for placing text relative to the plotting window; using 2D paper coordinates to placetext next to a system OBJECT can be difficult, since the location of plotted OBJECTs in the window changesaccording to the setting of the WINDOW command.5. The starting point and vector entries for placing text on 3D and 2D projection plots are expressed in global systemcoordinates. Remember that the WINDOW setting determines the apparent size of the text on a given plot, so sizethe text in proportion to the size of the OBJECTs that you want to view in the plot WINDOW.TEXT Examples

<strong>ASAP</strong> | Commands and Macros (T) | 367TEXTFILE (<strong>ASAP</strong> Command)Writes the current data to a user-definable text file.Function• Display/Modify Data DistributionsSyntaxTEXTFILE name:header lines:DATA [ k ] [ s ] [ 'format' ]:trailer lines:EOFOptionnameksformatEOFDescriptionName of the text file (default extension is *.txt)Number of columns to write per lineScale factor (default=1; no scaling)Fortran FORMAT specification (default G15.7)Flag to close the fileRemarks1. Writes the current data to a user-definable text file called name (default extension is *.txt).The following registers are immediately loaded and can be used in the header and trailer definitions:Register Literal Value Numeric Value DescriptionT title 0 Data set titleF flabel 0 Function labelZ LABELZ zval 3rd coordinate valueL1 labelx 0 1st coordinate labelL2 labely 0 2nd coordinate labelN1 NUMX numx Number of 1st samplesN2 NUMY numy Number of 2nd samplesA1 XMIN xmin Minimum 1st coordinateA2 YMIN ymin Minimum 2nd coordinateB1 XMAX xmax Maximum 1st coordinateB2 YMAX ymax Maximum 2nd coordinateD1 DELX delx 1st coordinate spacing

<strong>ASAP</strong> | Commands and Macros (T) | 368Register Literal Value Numeric Value DescriptionD2 DELY dely 2nd coordinate spacingF1 FMIN fmin Minimum function valueF2 FMAX fmax Maximum function value2. The actual DATA can be written in virtually any format.3. The s is an optional scale factor that is multiplied with each data value before writing (default is 1, no scaling).4. An actual Fortran FORMAT specification (format) can be used for each number (default G15.7).5. The k is the number of columns to write per line (default is number of columns in data). Some values of k havespecial meaning:koutput-1 f-2 x f-3 x y f-4 x y z fNUMX+1 x x' ...::::y f ...y' f' ...6. EOF closes the text file.7. Alternatively, a RETURN can be used to return to DISPLAY mode without closing the file. Another TEXTFILEcommand without a file name entry continues writing to the original file. This way multiple distribution data setscan be written to the same file.8. TEXTFILE in the DISPLAY command can output the distribution data file into a matrix format, for directimporting to a spreadsheet program. In general, the output format is user-modifiable.• The simplest use of TEXTFILE is to dump the data in straight matrix/array or row/column format forimporting into spreadsheet software; that is, TEXTFILE name; DATA; EOFExampleA sophisticated example of TEXTFILE is a macro that takes the current distribution in DISPLAY and converts it to aPostScript image file::PSFILE { 1 Convert current distribution to a PostScript image fileDISPLAYTEXTFILE #1.PSR=ABS((YMAX-YMIN)/(XMAX-XMIN)) I=(700/R)

<strong>ASAP</strong> | Commands and Macros (T) | 369"/picstr" (NUMX) "string def"20 20 "translate" (I) (J) "scale"(NUMX) (NUMY) 8"[" (NUMX) 0 0 -(NUMY) 0 (NUMY) "]"'{ currentfile picstr readhexstring pop }''image'DATA 255/FMAX 'Z2.2''showpage grestore'EOF}PostScript file name>TEXTFILE ExamplesTHRESHOLD (<strong>ASAP</strong> Command)Resets all data values.Function• Display/Modify Data DistributionsSyntaxTHRESHOLD a b [ m n ]Optiona bm nDescriptionReset all data values less than b to aReset all data values greater than m to nRemarks1. Reset all data values less than b to a.2. Optionally, reset all data values greater than m to n.3. Each of these value entries can be specified either directly, as the MIN, AVE or MAX value, or as a percentage ofthe range from minimum to maximum (for example, 33.3%).THRESHOLD Examples$TIC (<strong>ASAP</strong> Macro)Displays elapsed and CPU time.Syntax$TIC&TICRemarks1. $TIC macro displays the number of CPU seconds that have elapsed since the last $TIC or &TIC macro wasprocessed.2. &TIC macro displays nothing and resets the timer.

<strong>ASAP</strong> | Commands and Macros (T) | 3703. Normally the time "units" are allowed to float, but can be fixed for this and all future outputs to MICroseconds,MILIiseconds, SEConds, MINutes, HOUrs, DAYs, WEEks or YEArs.4. Use OFF to go back to the default floating units. The display resolution is always 1/100 of the selected units and islimited to less 10,000 total units.$TIC ExamplesTITLE (<strong>ASAP</strong> Command)Specifies default title for future graphics.Function• Setup Plots and Verify SystemSyntaxTITLE [ userid ] [ 'default_title' ]Optionuserid'default_title'DescriptionDisplay a user ID literal in the upper-left corner of eachgraphics screen (up to 8 characters)Default title for graphics created with subsequentcommandsRemarks1. Up to an eight-character USERID literal can be displayed in the upper-left corner of each graphics screen. If atitle is not supplied on a graphics generating command (that is, a comment string on a PROFILE or PLOT), the'default_title' specified by this command is used.TITLE ExamplesTORUS (<strong>ASAP</strong> Command)Creates a toroidal or doughnut surface.Function• Define/Modify Surfunc EntitiesSyntaxTORUS X x h r [ r' [ q ] ]Y yZ zOptionDescriptionX, Y, or Z Axis of symmetryx, y, or z Location along coordinate axishHeight to center of torus ring

<strong>ASAP</strong> | Commands and Macros (T) | 371Optionr r'qDescriptionSemimajor lengths of the cross-sectional ellipse/rectangle at height hCurve type control parameter (default is q=0, an ellipse)<strong>Reference</strong> PointAt the specified coordinate point (not on the surface of the torus).Surface NormalOutward from the surface.AutolimitingYesRemarks1. The q parameter controls the shape of the cross-section in the following way:q=0 Elliptical (default)0

<strong>ASAP</strong> | Commands and Macros (T) | 372OptionREFLTRANPOINTinftDescriptionReflected directionTransmitted directionDirection from ray point to entity, a reference pointImportance area EDGE numberNumber of randomly distributed scatter rays to begenerated (default value is 1)As an EDGE modifier: fractional lower importance areaor direction band (default is 0)As a Direction modifier: cone half-angle in radiansAs an EDGE modifier: fractional upper importance areaor direction band (default is 1)As a Direction modifier: scattering directional parameter(default value is 1)Remarks1. To produce scattered rays, SCATTER MODEL m must be followed by the TOWARDS modifier.2. If reflective m and transmissive m' scatter models are different, specify both.3. <strong>ASAP</strong> allows reflected and/or transmitted scatter models to be combined with total internal reflection (TIR). Thisenables, for example, approximate simulation of lossy waveguides, for which scatter partially frustrates TIR.Caution: energy is not conserved.4. The TOWARDS modifier specifies an importance edge or direction towards or away from which rays are scattered.Up to 20 TOWARDS commands can be associated with one object.5. If an EDGE or a number follows the TOWARDS option, i specifies the EDGE number (relative or absolute) used asan importance area. If i is entered as a positive number, radiation is scattered towards the designated real area; if iis negative, radiation is scattered away from the designated virtual area. Use only rectangular or elliptical EDGEs.6. The entry n is the number of randomly directed rays scattered into the importance area or importance direction byeach TOWARDS command.7. For EDGE scattering, f and t are the fractional lower and upper bounds (default 0 to 1) of the importance arearelative to the defining edge.8. For directional scattering, f is the cone angle in radians into which rays are scattered. This angle is measured fromthe surface normal (t=0) or from the specular direction (t=1).9. For directional scattering, t is a parameter that varies the scattering direction from the surface normal (t=0) to thespecified direction (t=1, default). A value of t=-1 corresponds to retroreflection.10. Attempting to scatter below the horizon may lead to an incorrect calculation of scattered flux. This situationoccurs when some portion of an importance EDGE or angular cone specification forms an angle near or greaterthan /2 with the local surface normal.11. <strong>ASAP</strong> does not take into account importance areas whose solid angles overlap to maintain conservation of energy.12. Flux assigned to each scattered ray is computed from the formulawhere F1 is the incident flux, BSDF is the bidirectional scatter distribution function, A is the importance edgearea, R is the distance from scattering surface to importance edge measured along the scattered ray trajectory,

<strong>ASAP</strong> | Commands and Macros (T) | 373and are polar and azimuthal angles, and the subscript I, s, and e indicate incident angle, scatter angle and theangle between scattered ray and importance edge normal, respectively.13. The number of scattered rays per incident ray n affects both accuracy and ray-trace time. A single scatteredray per incident ray (n=1) is sufficient if the anglethat is subtended by the importance edge or importancedirection is less than 0.1 radians. For>0.1, the scattered flux quickly converges towards a stable value asn approaches 100/ where is the solid angle subtended by the importance edge or importance direction.Use n>1 also in cases where the probability of a scattered ray reaching the target is low; that is, if significantaberrations are present. Finer sampling of the scattering surface is always recommended over increasing the valueof n in an effort to raise signal-to-noise ratio.14. If the MONTECARLO option is used with SPLIT, the following guidelines should be applied:• If the scattering surface has a Lambertian model, the entry for the number of rays n should be 1. Entering alarger value of n only slows down the ray trace without improving the accuracy of the calculation.• For surfaces that have a non-Lambertian scatter model, the accuracy of the calculation improves as the entryfor the number of rays n increases.•For non-Lambertian BRDFs, if the maximum BRDF over all relevant angles of incidence and scatter is ,the number of scattered rays n should be greater than .• In most cases, the SPEC option should be used with scatter into the hemisphere above the surface rather thanan importance EDGE.15. If MONTECARLO is in effect, the n parameter of the TOWARDS command specifies the number of Monte Carlotrial rays for each scattered ray, and should be chosen to be 1 if the scattering is Lambertian, and otherwise at leasttimes the maximum value of the BSDF over the solid angle of interest for scattering.TOWARDS ExamplesTRACE (<strong>ASAP</strong> Command)Traces all currently selected rays in storage.Function• Trace Rays/BeamsSyntaxTRACE [j j'] [STEP [k]] [LIST [n]] [GRAPH [n ] [STATS [m] ] [KEEP]DIRPLOT [n [d ] ] ACCUMOptionj j'DescriptionStarting/stopping objects (defaults are 0 0, from allobjects to all possible objects)STEP [ k ] Number of stepped object intersections (default is -1)LIST [ n ]DIR [ n ]PLOT [ n ]Prints every nth ray object-by-object ray position dataPrints every nth ray object-by-object ray position anddirection dataPlots every nth ray as it is being traced

<strong>ASAP</strong> | Commands and Macros (T) | 374OptionTRACE PLOT COLOR [ n ]GRAPH [ n ]STATS [ m ]KEEPdACCUMDescriptionPlots a trace in a color of your choiceGraphical means of monitoring ray trace, n is themaximum ray number magnitude (default is 6; that is, 1million rays)Prints ray statistics (base and up to the first m parabasals)for each model or object encountered during ray trace;handles only absorption (not gain media)Keeps previously traced raysDistance from zero plane (see Remarks)Tracks ray statistics (base and up to the first m parabasalswhere the default is all)Remarks1. Uses the ray data in the virtual.pgs file (which is constructed if you use the GRID, RAYSET, EMITTINGcommands, and other ray initialization commands), and traces only those rays currently SELECTed through theobjects currently CONSIDERed. During the ray trace, each ray is accessed, traced, and the final status of the ray iscopied to the virtual.pgs file. Upon completion of the ray trace, you can issue analysis commands such as SPOTS,OPDMAP and others, which in turn access the virtual.pgs file for current ray data. Rays traced via the TRACEcommand are therefore permanent rays.2. With TRACE only, no output is typically generated except for possible ray warning messages. TRACE also listswarning summary for suppressed child rays.3. The PLOT option plots the rays as they are being traced and also stores their vectors on the 3D graphics file forpossible future plotting.4. Optionally, only those rays whose starting depth coordinate lies within a distance d of the zero plane are PLOTted.This option requires the input of stride [ n ] value.5. Once traced, rays cannot be retraced unless they are reinitialized.6. By default, the first ray definition command (for example, GRID, EMIT), executed after tracing, automaticallyresets the ray pointer to zero (RAYS 0) which flushes any rays. To override this behavior, use the KEEP option onthe TRACE command.7. Sign of j' or k determines if a refraction/reflection calculation is performed at the stopping object (negative j'or k turns this calculation off). In other words, a +j' or +k performs the optical transformation on the ray at theOBJECT; -j' or -k does not.8. Alternatively, the rays can be STEPped k objects intersection. The sign of this entry determines whether one stepsthrough the object (+k) or up to the object (-k).9. The progress of the ray trace can be monitored GRAPHically on a logarithmic curve. The n in this case is themaximum ray number magnitude (default is six; that is, 1 million rays).10. STATS or ACCUM tracks ray statistics (base and up to the first m parabasals, where the default is all) for eachGRIN/absorbing media, scatter model, and object encountered during the trace. STATS prints the statistics oncompletion of the trace. If scattered rays are involved, they are listed separately, with minus signs preceding theobjects. If ACCUM is used, the same information is displayed when you issue the STATS TRACE command at alater time. Absorption inside media is also calculated.11. TRACE LIST/DIR produces the same output as the RAY command (less the effective focal length).12. A typical use of the TRACE PLOT option is to plot a ray trace over a graphic; that is, PROFILES 0 0 -nOVERLAY; TRACE PLOT. The command argument, OVERLAY tells <strong>ASAP</strong> not to issue an end of plot so thatthe next plot created is overlaid with the current plot. This is useful for combining system plots with ray trace plots(assuming that the WINDOW is the same for all plots), multiple spot diagrams, and so on.13. WARNINGS limit ends only current TRACE, not entire program.TRACE Examples

<strong>ASAP</strong> | Commands and Macros (T) | 375TRANSPOSE (<strong>ASAP</strong> Command)Rotates the current distribution data by 90 degrees.Function• Display/Modify Data DistributionsSyntaxTRANSPOSE [ i ]OptioniDescriptionLine to transpose distribution data array about (default isabout diagonal)Remarks1. Transposes distribution data array about the ith line (default is about diagonal), so that future PLOT3D andISOMETRIC commands give a different view of the function.2. Use before the GRAPH command to see reversed profiles or perpendicular to usual ones.TRANSPOSE ExamplesTREE (<strong>ASAP</strong> Command)Displays object name tree.Function• Setup Plots and Verify SystemSyntaxTREE [ ENTITIES ] [ i ] [ 'delimiter' ]OptionENTITIESi'delimiter'DescriptionDisplays the base entities and BOUNDS entities for eachobjectIndent space to use if displaying object name tree(default 2)Character delimiter separating each object name treelevel (default is a period)Remarks1. Displays object name tree indented by i (default 2) at each level, assuming they are separated by the singlecharacter delimiter (default is a period ( . )).2. The ENTITIES option also displays the base entities and signed BOUNDS entities for each object.3. The corresponding object (and entity) numbers are shown inside angle brackets < >.BRANCH Examples

<strong>ASAP</strong> | Commands and Macros (T) | 376TUBE (<strong>ASAP</strong> Command)Creates a tube with rectangular/elliptical cross-sections.Function• Define/Modify Surfunc EntitiesSyntax 1TUBE X x y z x' y' z' [ q [ q' ] ]Y y z x y' z' x' INNERZ z x y z' x' y' OUTERSyntax 2TUBE X x y z [ ANGLES b c [ q ] ]Y y z x c aZ z x y a bOptionDescriptionX, Y or Z Axis of symmetryx, y or z Location along coordinate axis of first closed curvey z, z x, or x yx', y' or z'y' z', z' x', or x' y'q q'INNER/OUTERb c, c a, or a b<strong>Reference</strong> PointIf +X, +Y, +Z, reference point is at positive end of the tubeIf -X, -Y, -Z, reference point is at negative end of the tubeIf X, Y, Z, reference point is in the middle of the tubeSurface NormalRadially outwardAutolimitingSyntax 1: Yes Syntax 2: NoRemarksSemimajor widths of first closed curveLocation along coordinate axis of second closed curveSemimajor widths of second closed curveParameters that control the type of closed curve at thetwo ends (see Remarks)See RemarksAngles (in degrees) that the two orthogonal projectionsof the sides of the tube make with the symmetry axis1. Creates a general tube-like surface symmetric about the given axis with rectangular or elliptical cross-sections.2. The parameters q and q' control the type of closed curves at the two ends of the tube in the following way:

<strong>ASAP</strong> | Commands and Macros (T) | 377q=0 Elliptical0

<strong>ASAP</strong> | Commands and Macros (U) | 378Commands and Macros (U)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “U”.UNITS (<strong>ASAP</strong> Command)Defines the system units.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxUNITS [ length ] [ 'flux' ]Optionlength'flux'DescriptionLength units of the system geometryLabel for the flux unitsRemarks1. After you enter the UNITS command, do not enter it again until the system geometry is replaced by anothersystem. Similarly, enter the UNITS option on the WAVELENGTH command only once.2. Takes an optional flux label that is printed on intensity, irradiance, and radiance plots in DISPLAY.3. Sets the length units of the system geometry to one of the following lengths:INMMYDFTMIMKMMILUMCMUINor INCHESor MILLIMETERSor YARDSor FEETor MILESor METERSor KILOMETERSor MILSor MICRONSor CENTIMETERSor MICROINCHES4. The labeling of flux units can be set to the given string (up to 11 arbitrary characters). Some typical ones would beWATTS, LUMENS or PHOTONS/SEC.5. The UNITS command is used in conjunction with the WAVELENGTH and CAD commands to associate units withthe optical system.6. Also specifies system units in conjunction with a WAVELENGTH UNITS command to properly scale the opticalpath difference.UNITS Examples

<strong>ASAP</strong> | Commands and Macros (U) | 379$UNVAR (<strong>ASAP</strong> Macro)Determines the type of message to be issued for future uninitialized (used before set) variables/registers.Syntax$UNVAR [ NONE ]WARNERRORRemarksThe default is WARN; that is, a message but not a fatal ERROR. If no entry is given, the state before the last $UNVARcommand is restored.$UNVAR ExamplesUPDATE (<strong>ASAP</strong> Command)Controls the entity storage updating.Function• Define/Modify Entities or Single Entity ObjectsSyntaxUPDATE [ OFF ]OptionOFFDescriptionOverwrites data in storageRemarks1. Controls how basic geometrical entity data (that is, SURFACE coefficients, LENS conicoids, EDGE points) isupdated in storage.2. Normally, if an already defined entity is updated at a later time, the new data overwrites the old. This overwritepresents no problems as long as the amount of new data is less than or equal to the amount of old data. However,if the new data occupies more storage space, data for the next entity can become corrupt.3. The UPDATE command tells <strong>ASAP</strong> to place all future entity data at the end of storage. The old data is not deleted,but it is never used again.4. To return to the default overwrite mode, use the OFF option.UPDATE ExamplesUSERAPOD (<strong>ASAP</strong> Command)Specifies a beam irradiance or intensity apodization.Function• Modify Ray/Beam DataSyntax 1

<strong>ASAP</strong> | Commands and Macros (U) | 380USERAPOD POS [ fcn ] [ c c' c" ... ] [ 'string' ]APODIZE DIR OFFOFFSyntax 2USERAPOD POS c c'APODIZE DIR[ e p [ f ] [ PLOT ] ]PROD[ e' p' [ f' ] ]:OptionPOS or DIRfcnc c' c". . .OFFe fpPLOTPRODDescriptionType of apodizationName of the apodization function to be applied to the setof raysUp to 50 coefficients used to define the apodizationfunctionTurn off the currently defined apodization functionMeasured energy fluxSpatial or direction cosine coordinateCreates a default distribution file (BRO009.DAT)Flag to use the product of the two orthogonal profilesinstead of the weighted sumRemarks1. Users can define their own POSitional and/or DIRectional apodization function for application to a set of rays orbeams created in a GRID or EMITTING surface command. This is done by either using the given $FCN function,fcn or rewriting the Fortran function, USERAPOD and relinking the program.2. Turns on or OFF the use of the currently defined apodization function by the program.3. APODIZE operates immediately on all the currently selected or considered rays and therefore, and can be usedbefore or after a TRACE.4. APODIZE is a ray modifier that apodizes ray distributions of all currently selected and/or considered rays beforeor after a ray trace. It is less constrictive than the USERAPOD command. It may be used to angularly apodize raysthrough a filter or at a detector.5. USERAPOD is applied only to rays when they are created. Therefore, it should be placed prior to the ray definitioncommands for which it is applicable. Once entered, however, it modifies all subsequent ray data until turned OFF.6. USERAPOD POS only applies to the following ray creation commands: GRID ELLIPTIC, GRID HEX,GRID POLAR, GRID RECT, GRID WINDOW, SOURCE POS GRID, SOURCE DIR GRID, andEMITTING DISK/RECTANGLE.7. USERAPOD DIR only applies to the following ray creation commands: SOURCE DIR GRID, EMITTINGDISK/RECTANGLE, EMITTING ENTITY or OBJECT, and EMITTING DATA plane.8. If fcn is specified, the in-plane, 2D POSitional or DIRectional coordinates are passed in the _1 and _2 variables.The 50 coefficients c c'... are passed in the _3 _4 ... _52 variables. The last entry in the $FCN definition of fcn isused as the apodization flux scaling factor. For example, to define and use a Gaussian apodization (identical to thedefault one discussed below):

<strong>ASAP</strong> | Commands and Macros (U) | 381$FCN APOD _5*GAUS[_1/_3]*GAUS[_2/_4]/(_3*_4):USERAPOD POS APOD ...:GRID ...SOURCE ...9. Otherwise, up to 50 coefficients (c c' ...) and the 'string' can be passed to the USERAPOD/APODIZE commandwhere the default apodizing function is a Gaussian apodization of the form (using the Z axis as the direction ofpropagation):Therefore, co and c1 are the semimajor widths of the Gaussian envelope. The c2 is the total flux in the beam,assuming it is not appreciably truncated by the finite size of the grid or emitting surface and that the default POSirradiance or DIR radiance distribution is unity.10. Only a rotationally symmetric apodization may be used with the GRID POLAR.11. The x and y in the T(x,y) equation become direction cosines if the DIR option is used.12. With the second syntax, a table of measured energy flux in the two orthogonal grid directions e,f versus POSitionor DIRection cosine p can be entered to apodize the grid.13. The values of p are entered in ascending order (0 < p < 1, the first quadrant in direction cosine space). <strong>ASAP</strong>linearly interpolates to obtain intermediate flux values. The remaining three quadrants are mapped by reflectionacross the coordinate axes.14. The c0 and c1 values are used to scale p into the two coordinate values at the GRID or EMITTER plane. If noscaling is desired, enter 1 1 for c0 and c1.15. Using the PLOT option with the second syntax creates a default distribution file (BRO009.DAT) for futureplotting by the DISPLAY command (the current PIXELS setting controls the resolution).USERAPOD ExamplesUSERAPOD ANGLES (<strong>ASAP</strong> Command)Specifies 3D angular apodization of volume emitters.Function• Setup Beam CreationSyntax 1USERAPOD ANGLES X [ fcn ] [ c c' c" ... ] [ 'string' ]APODIZEYZOFFSyntax 2USERAPOD ANGLES X [ f f' t t' ] [ i t" s ]APODIZE Y -1 'filename'Z

<strong>ASAP</strong> | Commands and Macros (U) | 382OptionX Y Zfcnc c' c". . .f f't t'iDescription-1 'filename' See RemarksSpecifies spherical coordinate system axisName of the apodization functionUp to 50 coefficients used to define the apodizationfunctionZenith angle limits in degreesAzimuth angle limits in degreesNumber used to name the interpolation data filet" Azimuth angle data offsetsRemarksData scale factor1. As a function of spherical angles for the given axis, apodize the 3D radiation patterns of volume emitters createdwith the EMITTING commands.2. APODIZE operates immediately on all the currently selected or considered rays and, therefore, can be used beforeor after a TRACE.3. USERAPOD is only applied to rays when they are created. Therefore, it should be placed prior to the ray definitioncommands for which it is applicable. Once entered, however, it modifies all subsequent ray data until turned OFF.4. USERAPOD ANGLES applies only to the following ray creation commands: EMITTING ENTITY or OBJECT,EMITTING DATA volume, EMITTING BOX/SPHEROID, EMITTING CONE/PYRAMID, EMITTINGFILAMENT, EMITTING HELIX, and EMITTING RAYS.5. The volume emitters are apodized according to the predefined $FCN function or the user-supplied Fortran in thefunction USERANGS. If fcn is specified, the zenith angle from the axis (0 to pi radians) and the azimuth anglearound the axis (-pi to pi radians) are passed in the _1 _2 and the 50 coefficients c c'... in _3 _4 ... _52.6. Otherwise, the optional coefficients (c c' "c ...) and 'string' are passed to USERANGS. The default definition forUSERANGS is a spherical angle clipping and/or interpolation (see second syntax).7. The f f' are the limits of the zenith angle (in degrees) measured from the axis (default 0 to 180).8. The t t' are the limits of the azimuth angle measured around this axis (default 0 to 360).9. The i is an optional number (non-zero) of a file that contains an interpolation table in spherical coordinates. Ifi is negative, the complete case-sensitive name of the file is taken from the comment string. If i is positive andless than 80, the file's name must be USAP3D and its extension is the character whose ASCII value is i+48 (forexample, for i=2, the file is USAP3D.2). Otherwise, the file name is the number itself and the extension is *.ua3(that is, for i=9007, the file is 9007.ua3).10. The "t is an azimuthal angle data offset and s a data scale factor for the data in the file.11. Data contained in the file USAP3D.i is used to apodize the emitting volumes. The first two numbers on the firstrow of the file are the number of azimuth and zenith angles, respectively. The first column is the zenith angles.The first row is the azimuth angles. The subsequent data is the flux-weighted value at the particular angles. <strong>ASAP</strong>linearly interpolates to obtain the flux between data points.USERAPOD ExamplesUSERAPOD BOTH (<strong>ASAP</strong> Command)Apodize in position and/or direction the full 3D radiation patterns of volume emitters.Function• Setup Beam Creation

<strong>ASAP</strong> | Commands and Macros (U) | 383Syntax 1USERAPOD BOTH [ fcn ] [ c c' c" ... ] [ 'string' ]APODIZE OFFSyntax 2USERAPOD BOTH k f f' t t' [ i t" s ]APODIZE X -i 'filename'YZOptionfcnc c' c". . .kX Y Zf f't t'iDescription-i 'filename' See RemarksName of the apodization functionUp to 50 coefficients used to define the apodizationfunctionSpecifies axis for spherical coordinate systemSpecifies spherical coordinate system axisZenith angle limits in degreesAzimuth angle limits in degreesNumber used to name the interpolation data filet" Azimuth angle data offsetsRemarksData scale factor1. Apodize, in position and/or direction, the full 3D radiation patterns of volume emitters created with theEMITTING commands.2. APODIZE operates immediately on all the currently selected or considered rays and therefore, can be used beforeor after a TRACE.3. USERAPOD is applied only to rays when they are created. Therefore, you must place it prior to the ray definitioncommands for which it is applicable. Once entered, however, it modifies all subsequent ray data until turned OFF.4. USERAPOD BOTH applies only to the following ray creation commands: EMITTING ENTITY or OBJECT,EMITTING BOX/SPHEROID, EMITTING CONE/PYRAMID, EMITTING FILAMENT, EMITTINGHELIX, and EMITTING RAYS.5. The volume emitters are apodized according to the predefined $FCN function or the user-supplied Fortran inthe function USERBOTH. If fcn is specified, then the global positional coordinates are passed in the _1 _2 _3registers, the unit direction vector in _4 _5 _6, and the 50 coefficients c c' ... in _7 _8 ... _56. Otherwise, theoptional coefficients (c c' "c ...) and 'string' are passed to USERBOTH.6. The default definition for USERBOTH is the same as USERANGS, a spherical angle clipping and/or interpolation(see second syntax).7. Option k is an axis specification (1=x, 2=y, 3=z) for a spherical coordinate system.8. Option f f' are the limits of the zenith angle (in degrees) measured from this axis (default 0 to 180).9. Option t t' are the limits of the azimuth angle measured around this axis (default 0 to 360).

<strong>ASAP</strong> | Commands and Macros (U) | 38410. Option i is an optional number (non-zero) of a file that contains an interpolation table in spherical coordinates. If iis negative, the complete case-sensitive name of the file is taken from the comment string. If i is positive and lessthan 80, the name of the file must be USAP3D and its extension is the character whose ASCII value is i+48 (thatis, for i=2, the file is USAP3D.2). Otherwise, the file name is the number itself and the extension is ua3 (that is,for i=9007, the file is 9007.ua3).11. The "t is an azimuthal angle data offset and s a data scale factor for the data in the file.12. Data contained in the file USAP3D.i is used to apodize the emitting volumes. The first two numbers on the firstrow of the file are the numbers of azimuth and zenith angles, respectively. The first column is the zenith angles.The first row is the azimuth angles. The subsequent data is the flux-weighted value at the particular angles. <strong>ASAP</strong>linearly interpolates to obtain the flux between data points.USERAPOD ExamplesUSERBSDF (<strong>ASAP</strong> Command)Specifies an isotropic or anisotropic scatter model.Function• Create/Modify Media, Coatings, Scatter ModelsSyntax - Isotropic-surface Scatter Model (user definable)USERBSDF [ fcn ] [ SPATIAL ] c c' c" ... [ PLOT [ a a' ... ] ]OptionfcnSPATIALc c' c" ...PLOTa a' ...Description$FCN (<strong>ASAP</strong> macro) functionSpecifies that the local coordinates of the scatteringlocation are passed to the $FCN functionCoefficientsPlots the model in log(b-bo) and angle spaceUser-defined degree specular anglesSyntax - Anisotropic-surface Scatter ModelUSERBSDF X [ fcn ] c c' c'' …YZ:RemarksIsotropic-surface Scatter Model1. The fcn function passed to USERBSDF can now use the coordinates of the incident ray if SPATIAL is specified.The coordinates are expressed in the local coordinates x, y, z of the scattering object, stored in high registers. Theregisters set by SPATIAL are therefore,

<strong>ASAP</strong> | Commands and Macros (U) | 385RegisterValue_0 Vacuum wavelength of incident ray_1 U_2 V_3 W_64 x_65 y_66 z2. The intersection point (x, y, z) for SPATIAL is expressed in the local coordinates of the scattering object. Thisfacilitates use of a single scattering $FCN on multiple surfaces. Careful attention to the reference point of thesurface is required. The z coordinate is useful for applying scattering models to curved surfaces.3. Recall that USERBSDF... PLOT evaluates the TIS using the specified user-defined fcn, and that care istherefore required to ensure that the user-defined function yields a meaningful 'nominal' function for PLOT. Thismeans that any registers on which $FCN depends, other than those set by SPATIAL, must be set appropriatelybefore the USERBSDF...PLOT command is issued.4. Creates, along with a $FCN definition, a user-defined Bi-directional Scattering Distribution Function (BSDF).5. Up to 63 coefficients c can be used by the predefined $FCN function or up to 286 coefficients can be passed to theUSERBSDF Fortran function.6. If fcn is specified, the incident vacuum wavelength and the three isotropic-surface symmetry variables (U,V,W) arepassed in the variables _0, _1, _2, _3 registers, the 63 input coefficients c c' … in _4_5 …66. The last entry on thedefinition is returned as the actual BSDF value. If the BSDF is only a function of these variables, scattering froman isotropic surface is symmetric with regard to the plane of incidence and surface normal.7. The last entry on the $FCN definition is returned as the actual BSDF value. For example, a BSDF that varies asthe cosine of the angle from specular raised to some arbitrary power (Phong-like model) could be implementedwith the following code:$FCN FONG C=_2+SQRT((1-_1)*(1-_3)), !cosine of angle from specular_4*((C>0)^_5)+_6MODEL; USERBSDF FONG .3 10 .18. Alternatively, the simplest BSDF model with constant Total Integrated Scatter (TIS); that is, Lambertian at normalincidence, but becomes more and more specular as it approaches grazing incidence:$FCN ROUGH _4*(1+_2)/3.1416, !_4 will be the TISMODEL; USERBSDF ROUGH .9 !90% TISBoth of these examples, as defined, obey reciprocity (same results occur if _1 and _3 are interchanged).9. Another example of USERBSDF is the GUERAPV standard model:$FCN GUERAPV C=SQRT(1-_1) A=ACOS(_2+C*SQRT(1-_3)),A1=_4 B1=_5 C1=_6 D1=_7 A2=_8 B2=_9 C2=_10 D2=_11 D=_12,(A1*EXP(-B1*A)*COS(C1*A+D1)+A2*EXP(-B2*A)*COS(C2*A+D2))/C+D/3.1416MODEL; USERBSDF GUERAPV ...

<strong>ASAP</strong> | Commands and Macros (U) | 38610. This is an unphysical model that does not obey reciprocity, cannot have the proper directional dependency forsmooth surfaces, and could even become negative.11. Enter a negative index for particles on a reflecting surface.12. Besides a $FCN definition, users can program the USERBSDF routine to return the BSDF as a function of thewavelength and isotropic-surface scattering variables. The default definition for USERBSDF is the crude APARTmodel for scattering from a random collection of homogeneous spherical particles where:c = particle radius divided by wavelengthc’ = fractional area obscured by particlesc" = real refractive index of particle (default=100; that is, opaque)Anisotropic-Surface Scatter Models1. Scattering from anisotropic surfaces is not rotationally symmetric at normal incidence and not necessarilysymmetric about the plane of incidence otherwise. Therefore, the orientation of the model on the surface isimportant and is generally specified by an axis for the second command entry. For syntax information, see thecommand argument, MODEL.2. The predefined $FCN function can use up to 62 coefficients, or up to 286 coefficients can be passed to theUSERANIS Fortran function. If fcn is specified, the following registers are passed:RegistersData_0 <strong>Inc</strong>ident vacuum wavelength_1 Scatter Alpha direction cosine_2 Scatter Beta direction cosine_3 Specular Alpha direction cosine_4 Specular Beta direction cosine_5 ... _66 c c' c" ... input entriesThe last entry on the $FCN definition is returned as the actual BSDF value.3. The default definition for USERANIS is a simple elliptical Gaussian centered on the specular direction:c = Peak BSDF valuec’ = Width in local Alpha directionc" = Width in local Beta directionBoth Isotropic and Anisotropic Models:1. The PLOT option plots the model (common base 10 logarithm of the BSDF) for up to seven specular angles inascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls the resolutionof these plots in direction cosine space. Creates a distribution file, name_angle.dis for each of these angles.2. The MINMAX command argument may be used to set the minimum and maximum values of the BSDF for thisspecific model.USERBSDF ExamplesUSERCURVE (<strong>ASAP</strong> Command)Creates a piecewise linear curve (or bilinear surface) from a $FCN function.Function

<strong>ASAP</strong> | Commands and Macros (U) | 387• Define/Modify Curvedge EntitiesSyntaxUSERCURVE fcn u u' m [ v v' n ]SPLINECURVOptionfcnu u'mv v'nDescriptionUser-defined functionParameter rangeNumber of segmentsSecond parameter rangeNumber of segments (second parameter)Remarks1. Normally creates a piecewise linear curve (or bilinear surface) from a $FCN function fcn.2. The last three expressions of the $FCN definition are the X, Y, and Z coordinates of a point as function of theparameter register _ or _1 (and optionally _2 for a surface).3. For a curve, the parameter ranges from u to u' in m segments.4. For a surface, the second parameter ranges from v to v' in n segments. See the example below.ExampleA wiggly circle definition:PI=ACOS(-1)$FCN SQUIGGLE A=2*PI*_ R=1+.1*SIN(10*A),x R*COS(A) y R*SIN(A) z 0EDGEUSERCURVE SQUIGGLE 0 1 100SMOOTHor a bilinear approximation to a "sphere" surface$FCN SPHERE R=1 P=_1*PI/180 A=_2*PI/180,x R*COS(A)*SIN(P) y R*SIN(A)*SIN(P) z R*COS(P)EDGEUSERCURVE SPHERE 0 180 6 0 360 6Optionally, the derivatives of the $FCN function can be used to smooth the curve into a curvature (G2) continuous,piecewise cubic, non-rational SPLINE or rational CURVe.USERCURVE ExamplesUSERFUNC (<strong>ASAP</strong> Command)Creates a surface specified by a user-defined function.Function

<strong>ASAP</strong> | Commands and Macros (U) | 388• Define/Modify Surfunc EntitiesSyntaxUSERFUNC [ EXPLICIT ] x y z [ fcn ] [ c c' c" ... ]Optionx y zEXPLICITfcnc c' c" ...DescriptionGlobal coordinates of reference pointExplicit functionUser-defined function ($FCN)Coefficients of function<strong>Reference</strong> PointAs specifiedSurface NormalAs specifiedAutolimitingNo, requires LOCAL or LIMITS modifiers.Remarks1. A user-programmable, implicit (f(x,y,z)=0) or EXPLICIT (f(x,y)-z=0) function with reference point x,y,z anddouble-precision coefficients.2. Its value and gradient at any point (and wavelength) can be coded by the user in the $FCN named fcn or theFortran function USERFUNC.3. If the function is continuous in both value and gradient everywhere in space, there are no restrictions on the use ofthis function in the program, except possibly the application of non-orthogonal transformations to it; for example,SKEW or non-isotropic SCALE.4. If the fcn is specified, the current WAVELENGTH (or the associated ray/beam’s wavelength) is passed in the "_0"register, the local x y z coordinates are passed in the _1 _2 _3 registers, and up to 63 coefficients c c’ ... in _4 _5 ..._66.5. If 4 or more values are returned, the last four entries of the executed function must be the functional value and itsgradient vector. If only one value is returned, it is the functional value and the gradient is calculated numericallyusing finite-differences. For example, a sphere of radius 10 centered about the reference point is done as follows:$FCN SPH _1^2+_2^2+_3^2-_4^2 2*_1 2*_2 2*_3:SURFACE; USERFUNC .5 0 -1 SPH 106. Otherwise, the default USERFUNC is an aspheric conicoid with vertex at x,y,z and normal direction c,c’,"c.The fourth and fifth coefficients are the vertex curvature (inverse radius) and the conic constant (0=sphere,-1=parabola), respectively. The remaining coefficients are for a straight polynomial in an offset radial distanceincluding odd terms; that is, the seventh coefficient is the linear term, the eighth is the quadratic, and so on. Forexample:USERFUNC x y z 0 0 1 c k h d d’ d" ...

<strong>ASAP</strong> | Commands and Macros (U) | 389An exception has been implemented when the curvature c is zero; that is,USERFUNC ExamplesUSERSAG (<strong>ASAP</strong> Command)Creates a surface with a user-defined radial or toric profile.Function• Define/Modify Surfunc EntitiesSyntaxUSERSAG X x [ fcn ] c c' ... [ TORIC r [ k ] ] [ aperture ]Y yZ zOptionDescriptionX, Y or Z Axis of symmetryx, y or z Location along axisfcnUser-defined functionc c' ... Coefficients (up to 66)TORIC rapertureFlag to create a TORIC surface of radius rELLIPSE, RECTANGLE, or HEXAGONAL1. Creates at the given plane, a surface with a user-programmable radial or TORIC (of radius r) profile specified by asag formula.2. The second entry in the syntax designates the axis of symmetry (either X, Y, or Z) for the surface.3. If fcn is specified, the local transverse height coordinate is passed in the _0 (or _) register and up to 66 coefficientsc c' ... in registers _1 _2 ... _66. The last expression of the executed function must be the sag value at that height.4. If k is specified, the profile is, instead, shifted along a conic curve with vertex radius of curvature r and conicconstant k (0 = circular, -1 = parabolic). Specifying a k of zero is not the same as an absent k .

<strong>ASAP</strong> | Commands and Macros (U) | 3905. Otherwise, the default is a conic plus aspheric terms. The fourth and fifth entries of the syntax are the vertexcurvature (inverse radius) and the conic constant (0=sphere, -1=parabola), respectively. The remaining coefficientsare for a straight polynomial including odd terms; that is, the sixth entry is the linear term, the seventh is thequadratic, and so on.6. For the Z-axis case,USERSAG Z z c k d d’ d" ...USERSAG Z z c k dThis surface can extend to infinity unless a LOCAL command follows, or a trailing aperture option of thefollowing form is specified:ELLIPSE a [ a' [ o [ s [ s' ] ] ] ]RECTANGLEHEXAGONAL a [ o [ s [ s' ] ] ]a a' are the heights in the other two transverse directions.For the HEXAGONAL form, a is the center-to-vertex distance (maximum height).o is an optional central hole ratio.s s' are the transverse coordinates of the center of the aperture.USERSAG ExamplesUVSPACE (<strong>ASAP</strong> Command)Tags current curve to be defined in the parametric space of an object.Function• Define/Modify Curvedge EntitiesSyntaxUVSPACE [ OFF ]iOptioniDescriptionObject number/name

<strong>ASAP</strong> | Commands and Macros (U) | 391OptionOFFDescriptionReturn the curve definition to the Z=0 plane in globalthree-dimensional space (for example, so that it can bePLOTted).Remarks1. Assume current edge is defined in UV-space parametric space of object i. Currently, UVSPACE is only useful if itis used as a closed BOUNDS on the object.2. Alternatively, any planar edge can be directly defined in parametric space by substituting UV for the second (axis)and third (location) entries on its command. For example:becomesUVSPACE ExamplesPOINTS Z z ...POINTS UV ...

<strong>ASAP</strong> | Commands and Macros (V) | 392Commands and Macros (V)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “V”.VALUES (<strong>ASAP</strong> Command)Lists the functional values of the current distribution data file.Function• Define/Modify Entities or Single Entity ObjectsSyntaxVALUES v h [ reg ] [ v' h' [ reg' ] ... ]Optionv h, v' h', ...reg, reg', ...DescriptionCoordinate valuesv for vertical, h for horizontal)Register namesRemarks1. Lists the functional values corresponding to the exact pair of actual coordinates given.2. <strong>ASAP</strong> linearly interpolates, if necessary, to obtain functional values. If any of the given actual coordinates areout of the range of the coordinates on which data are defined, a warning message is issued. <strong>ASAP</strong> automaticallyresets the out-of-range actual coordinate to the closest coordinate limit in the corresponding direction defined bythe data.3. The functional values can be optionally placed in the given register names.VALUES ExamplesVANES (<strong>ASAP</strong> Command)Creates an anisotropic scatter model that simulates the scatter from a vane structure.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxVANES X a s d t [ t' [ c [ w ]]] [ EDGES r [ t" ]] [ PLOT [ a a' ... ] ]YZ:OptionDescriptionXSpecifies symmetric axisa Vane angle from the surface (0 to 180).

<strong>ASAP</strong> | Commands and Macros (V) | 393Optionsdt t'cwEDGES rDescriptionVane separationVane depthVane TIS (sides and bottom)Cylindrical radius of curvature of the vaned surface(default=0; infinite)Vane cavity width (default=0; infinite)Vane tips edge with radiust" Lambertian vane edge TISPLOTa a' ...RemarksPlots the model in log(b-bo) and angle spaceUser-defined degree specular angles1. The surface scatters as if it were the locus of vane tips parallel to the local "Alpha" direction.2. The vane cavity surfaces are assumed to be Lambertian with Total Internal Scatter (TIS) values of t and t' for thesides and bottom, respectively.3. The vane tips may have rounded EDGES of radius r and a Lambertian TIS of "t.4. Scattering from anisotropic surfaces is not rotationally symmetric at normal incidence, and not necessarilysymmetric about the plane of incidence otherwise. Therefore, the orientation of the model on the surface isimportant, and is generally specified by an axis for the second command entry. For syntax information, see thecommand argument, MODEL.5. The PLOT option plots the model (common base 10 logarithm of the BSDF) for up to 7 specular angles inascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls the resolutionof these plots in direction cosine space. Also, creates a distribution file name_angle.dis for each of these angles.6. The command argument, MINMAX may be used to set the minimum and maximum values of the BSDF for thisspecific model.7. Note that this model is an approximation that currently ignores the scatter between the sides and bottom of thecavity. Therefore, under certain circumstances it may underestimate the effective BRDF.VANES ExamplesVARIABLES (<strong>ASAP</strong> Command)Declares which lens construction parameters are to be varied during optimization.Function• Define/Modify Lens EntitiesSyntaxVARIABLES [ OFF ] [ LIST ] [ TH [ i i'...] ] ...VARYCVCCCPASBNGL

<strong>ASAP</strong> | Commands and Macros (V) | 394OptionTHCVCCCPASBNGLDescriptionThicknessesCurvaturesConic constantsVertex curvatureAspheric surfacesBendingGlass. Conicoid numberRemarks1. The basic parameters are the thicknesses (TH), curvatures (CV), and conic constants (CC) on any set of conicoidslisted after each variable. If the conicoid number is positive, the parameter is free to vary.2. If entered as a negative number, that particular parameter is subtracted from the variable list (that is, it is frozen atits current value). If no conicoid set is given, all but the last conicoid is allowed to vary.3. The ABERRATIONS command can be followed by any number and combination of the commands in thesyntax. These commands are cumulative until another ABERRATIONS command or an OFF option resets all theparameters to their default frozen state. The new variable set can also be LISTed where asterisks indicate eachactive one.4. The sag of higher-order aspheric surfaces (like corrector plates) is given by aspheric (AS) (default 1) times thedifference between the conic defined by CV/CC and a parabola with vertex curvature (CP).5. Bending (BN) is a composite variable that changes the curvature of the given conicoid(s) while keeping constantthe difference in curvatures between it and the next conicoid in the lens. This approximately fixes the power (andfocal length) of the two adjacent conicoids, while allowing their aberration contributions to vary. It works withboth glass elements and air spaces.6. In global optimization mode, the optimum GLass (or combination of glasses) can be found from all the currentlydefined MEDIA.7. Since there can be potentially six variables per conicoid, an optimization can use up to 720 variables. Alarge number of variables can quickly become impractical even for a local optimization, because runtimes goapproximately as its cube.VARIABLES ExamplesVCAVITY (<strong>ASAP</strong> Command)Creates a scatter model as a random collection of v-cavities.Function• Create/Modify Media, Coatings, Scatter ModelsSyntaxVCAVITY s r r' [ PLOT [ a a' ... ] ]-k -hOptionsDescriptionRMS slope (in radians)

<strong>ASAP</strong> | Commands and Macros (V) | 395Optionrr'khPLOTDescriptionIntrinsic normal-incidence specular reflectivity of thematerialLambertian diffuse reflectivityCOATING (in vacuum/air)Diffuse from the RMS height roughness (in wavelengthunits)Plots the model in log(b-b_o) and angle spacea, a', ... User-defined degree specular anglesRemarks1. Scatter from a rough surface geometrically modeled as a random collection of v-cavities.2. <strong>Inc</strong>ludes the effects of shadowing and multiple reflections within a cavity.3. The slopes of the cavities are assumed to follow a Gaussian-normal probability distribution with zero mean andRMS slope s (in radians).4. The intrinsic normal-incidence specular reflectivity of the material is defined by r and the correspondingLambertian diffuse reflectivity is defined by r' (that is, the sum of these reflectivities should be equal to one minusthe material absorption).5. For polychromatic effects, the specular reflectivity can be determined from COATING k (in vacuum/air) and thediffuse from the RMS height roughness h (in wavelength units).6. The PLOT option plots the model (common base 10 logarithm of the BSDF) for up to 7 specular angles inascending order (default 0, 15, 30, 45, 60, 75, 89.9 degrees). The current PIXELS setting controls the resolutionof these plots in direction cosine space.7. Creates a distribution file name_angle.dis for each of these angles.8. The command argument, MINMAX command argument may be used to set the minimum and maximum values ofthe BSDF for this specific model.VCAVITY ExamplesVERSION (<strong>ASAP</strong> Command)Prints the version of the <strong>ASAP</strong> Kernel.SyntaxVERSIONVIEW (<strong>ASAP</strong> Command)Make all future plots a true perspective view.Function• Setup Plots and Verify SystemSyntax 1VIEW [ X ] [ h ] [ CENTER x y z ] [ EYE x' y' z' ]YDIR a,b,c

<strong>ASAP</strong> | Commands and Macros (V) | 396Syntax 2ZThe current view can be modified with the following forms:VIEW [ OFF ] [ ZOOM f ] [ DOLLY d ] [ ORBIT o ] [ FOV a ]0Remarks - Syntax 21. Make all future plots a true perspective view instead of using the current WINDOW (and OBLIQUE) settings. Theview is completely determined by an up coordinate axis, a vertical full height h in system units, the global centerof the view x y z, and eye point x' y' z' (or DIRection a,b,c equivalent to an eye point a distance 1000*h away).The current perspective view can be modified a variety of ways, as shown in the second syntax above.2. Turn perspective viewing OFF; that is, return to normal WINDOW (and OBLIQUE) settings.The form VIEW 0 calculates the closest perspective view to the current WINDOW (and OBLIQUE) settingsassuming an eye distance that is twice the vertical height (closely approximates a standard 35mm camera lens).OptionDescriptionZOOM divides the current vertical height by a factor f (>1zooms in,

<strong>ASAP</strong> | Commands and Macros (V) | 397VIOLATION (<strong>ASAP</strong> Command)Controls the handling of paraxial departure and positivity violations during future SPREAD and FIELD commands.Function• Calculate Diffraction/Propagation EffectsSyntaxVIOLATION g [ g' [ p [ p' [s [s' ] ] ] ] ]Option Default Descriptiong 0.1 wave Paraxial invariant departure beforemessage issuedg' 1 wave Paraxial invariant departure beforecalculation terminatedp 0.01 Positivity violation before messageissuedp' 1 Positivity violation before messageissueds .1 Stability violation before messageissueds' 10 Stability violation before calculationterminatedRemarks1. Setting these thresholds higher than the defaults may allow a calculation to finish, but the results should be viewedas suspect.VIOLATION ExamplesVOXELS (<strong>ASAP</strong> Command)Accumulates on the next TRACE, in a 3D array of volume elements (voxels), the flux-per-unit volume or irradianceon an area.Function• Setup TraceSyntax 1VOXELS FLUENCE [ d d ' [ n ] ]ABSORBED x x' y y' z z' [ n n' n" ]XYZ-X-Y-Z+X

<strong>ASAP</strong> | Commands and Macros (V) | 398+Y+ZSyntax 2VOXELS [ OFF ]READ [ u ]fileRemarks - Syntax 11. During the next TRACE, accumulate in a 3D array of volume elements (voxels), the flux-per-unit volume (totalabsolute FLUENCE or ABSORBED in media) or irradiance on an area perpendicular to the given coordinate axis.2. Only accumulates irradiance from rays going in the direction specified by the sign of the axis (no sign isequivalent to a bidirectional irradiance).3. The volume is either the enclosing box of the currently considered objects, determined by the current WINDOWsettings and the specified depth range, or given directly in terms of a range for each of the global coordinates.4. The number n of samples per coordinate is then either taken from the current PIXELS setting and a depth numberor specified directly. If any of the ns are entered as zero, the PIXELS setting at the time of the TRACE is used.5. The total number of voxels is constrained only by limits imposed by the operating system.6. After the completion of the next TRACE, the results are written to a 3D version of the standard binary distributionfile (BRO009.DAT), and any 2D slice can then be processed by DISPLAY and its subcommands.Remarks - Syntax 21. Turn ON or OFF the volume flux tracking during the next TRACE. Optionally, read in a previous 3D binarydistribution given by number u (default 9), or name "file" (default DIS extension). The results of the next TRACEare added to these values, and the total is written to the standard distribution file (BRO009.DAT).VOXELS ExamplesVUFACETS (<strong>ASAP</strong> Command)Shortcut for faceting and viewing current objects.Function• Setup Plots and Verify SystemSyntaxVUFACETS [ n n' [ m ] ] [ LIST ]Optionn n'mDescriptionFaceting numbersMaximum number of facets per objectRemarks1. VUFACETS is a shortcut for the $IO VECTOR REWIND, PLOT FACETS [ n n' ], and $VIEW commandsequence. However, it temporarily suppresses any 2D plotting to minimize computation time and disk space.2. Replots the current accumulated 3D VECTOR graphics taking into account the current CONSIDER settings.3. If possible, the maximum number of total facets on any object is kept below m (the default is 1000; use 0 to turnoff).

<strong>ASAP</strong> | Commands and Macros (V) | 3994. Remembers the faceting numbers n n' "m from the previous VUFACETS command (an END command resets themto the default 1).5. A $VIEW lists the facets in the Command Output window.6. The numbers of facets created for each object can also be LISTed (a $VIEW is not automatically issued in thiscase).VUFACETS Examples

<strong>ASAP</strong> | Commands and Macros (W) | 400Commands and Macros (W)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letter “W”.$WAIT (<strong>ASAP</strong> Macro)Causes the program to wait a specified number of seconds (default is 5 seconds) before continuing. An optionalmessage can also be displayed.Syntax$WAIT [ s ] [ 'message' ]$WAIT ExamplesWARNINGS (<strong>ASAP</strong> Command)Controls output of parent ray warning messages.Function• Setup TraceSyntaxWARNINGS [ n ] [ LIST ]OptionnLISTDescriptionThreshold number of ray warningsLists all future warning messagesRemarks1. Sets a state based on the number of ray warnings.2. If n is zero or greater and more than n ray warnings occur, the raytrace is terminated. The default for n is anegative number, which means there is no limit on the number of warnings.3. If the LIST option is present, all warning messages are printed during future ray traces.WARNINGS ExamplesWAVELENGTH(S) (<strong>ASAP</strong> Command)Defines the wavelength(s) for different MEDIA and COATING definitions.Function• Create/Modify Media, Coatings, Scatter Models• Setup Beam CreationSyntaxWAVELENGTH w [ w' w" ... [ name ] ]UNITS u

<strong>ASAP</strong> | Commands and Macros (W) | 401Optionw w' w" ...nameuDescriptionWavelength(s)Wavelength units designationMultiplier to convert wavelength into system unitsRemarks1. Sets the wavelength for any future calculations to w (normally in system units).2. WAVELENGTH(S) must precede any ray definitions to properly set up the Gaussian beams used to calculate thediffracted field.3. To change the wavelength (for setting up rays for tracing, for example), enter the WAVELENGTH(S) commandwith the appropriate wavelength. <strong>ASAP</strong> remembers the wavelength units.4. Enter the UNITS option on the WAVELENGTH(S) command only once.5. Specifies wavelengths used in media, coatings, and other databases. Multiple wavelengths in either ascending ordescending order should be entered for any MEDIA or COATING commands that have multiple refractive indicesor properties so as to identify the wavelength for each entry.6. WAVELENGTH(S) as measured in vacuum should be entered on WAVELENGTH(S).7. The UNITS option with a scale factor u (default=1) may be used to convert w into system units. The argument u isalmost always a number much less than unity.8. Alternatively, if a basic UNITS command was already issued, any of the following names can be used to calculateu automatically:A or ANGSTROMSNM or NANOMETERSUM or MICRONSMM or MILLIMETERSCM or CENTIMETERSM or METERS9. Some input parameters have units that are the same as w (see the INTERFACE command), so that it is sometimesmore convenient for these parameters to have different units than the physical system.10. <strong>ASAP</strong> remembers the units used to define MEDIA; interpolation does not depend on WAVELENGTH units.11. When the WAVELENGTH(S)) command is used with the MEDIA command, up to 40 wavelengths may bespecified for interpolation purposes to determine the refractive index for intermediate wavelengths.12. When the WAVELENGTH(S) command is used with the SPECTRUM command, up to 200 weights, along withthe corresponding wavelengths from the most recent WAVELENGTH(S) command, can be used to create a multiwavelengthspectrum of a source.13. If a wavelength is not specified for a set of sources, rays and ray paths are plotted in the arbitrary sequence ofcolors from the order in the COLORS command for the sequence of sources.14. All the rays from one source have the same color, whatever color is appropriate for that source.15. When sources of different wavelengths are created, the colors range from blue to red in a quasi-spectral sense,corresponding respectively to the wavelengths ranging from shorter to longer.WAVELENGTHS ExamplesWEDGE (<strong>ASAP</strong> Command)Creates a wedge of glass.Function

<strong>ASAP</strong> | Commands and Macros (W) | 402• Define/Modify Lens EntitiesSyntaxWEDGE X x h m a [ t ]Y yZ zOptionX or Y or Zx or y or zhmatDescriptionGlobal coordinate axisLocation on the global coordinate axisAperture heightMedium (number or name)Angle between the two facesOptional minimum thickness (default is h/10)WEDGE ExamplesWIDTHS (<strong>ASAP</strong> Command)Modifies the default parabasal ray settings, scaling the width of the parabasal rays.Function• Setup Beam CreationSyntaxWIDTHS w [ h ] [ EDGE ]OptionwhEDGEDescriptionGaussian beam overlap scale factorParabasal ray height scale factorOption that improves the sharpness of the edge of a beampatternRemarks1. The w is the factor by which <strong>ASAP</strong> scales the actual width of each beam. If w=1 (the default), a GRID commandcreates a set of beams the just touch each other; that is, unit packing density. If w1, they overlap. The latter case is especially useful for overlapping a Gaussian beam setso that the overall beam shape is much smoother. For this application, a value of 1.6 is usually sufficient and avalue of 2 is more than enough.2. The h is the ratio of the parabasal ray heights to the half-max half-width of the beam they define. The default is 1,but it can be set smaller if the exact parabasal rays depart too much from the first-order approximation on whichthe beam calculations are based. The h option should be used with caution because it may contribute to samplingerrors.

<strong>ASAP</strong> | Commands and Macros (W) | 4033. The EDGE option causes <strong>ASAP</strong> to add narrow odd-order Hermite-Gaussian beams at the edge of a GRID RECTor GRID POLAR of beams to preserve the sharpness of the overall beam pattern.4. See Remarks for the BEAMS command to avoid non-default settings from being overwritten.WIDTHS ExamplesWINDOW (<strong>ASAP</strong> Command)Sets the plotting window for graphical output.Function• Setup Plots and Verify SystemSyntax 1 - Setting a windowWINDOW [ X [ a a' ] Y [ d d' ] ]OBJ i Z OBJ jYZXZXYSyntax 2 - Modifying a windowWINDOW [ ACROSS ] m p [ ACROSS m' p' ]VERTICAL CEN VERTICAL CENDOWNDOWNHORIZONTALHORIZONTALBOTHOptiona a'd d'OBJ i, OBJ jX Y Zm m'p p'ACROSSDOWNVERTICALHORIZONTALCENDescriptionWindow limits along the vertical axis of the graphicsdeviceWindow limits along the horizontal axis of the graphicsdeviceSets window to the LIMITS range on the given OBJectnumbersCoordinate axisMagnification factorsRelative pan factorsWindow direction to be modifiedWindow direction to be modifiedWindow direction to be modifiedWindow direction to be modifiedAutomatically centers the window on the current dataRemarks

<strong>ASAP</strong> | Commands and Macros (W) | 4041. Since <strong>ASAP</strong> has no preferred set of axes, use WINDOW to define the plane of your plotting window. For example:WINDOW Y Z, orWINDOW Y - 1 1 Z 0 32. Objects/data inside the window are plotted; objects/data outside this window are not plotted.3. WINDOW does not set the third coordinate (the one different than the two entered on the WINDOW command).4. If either a=a' or d=d', <strong>ASAP</strong> attempts to autoscale in that direction (the word "attempt" is used because WINDOWalways keeps the aspect ratio correctly unless overridden with a PIXEL command).5. If both sets of numerical entries are omitted, <strong>ASAP</strong> autoscales in both directions.6. Autoscaling is performed on the basis of the current object set. Objects that are considered invalid do not influencethe autoscaling, nor are they drawn. Autoscaling is also performed on ray trace data (spot diagrams, and so on).7. Window settings are active until replaced by another WINDOW command. A previous window setting may bescaled by WINDOW f, where f is a scale factor.8. If a'

<strong>ASAP</strong> | Commands and Macros (W) | 405Remarks1. Writes the current data to the current file, logical unit number u, binary file name.dis, or text file name.din(default is both). An optional comment string can be used to override the 'title' record in the resulting file.2. The filename, if specified explicitly, is normally written without an extension. If an extension is specified as partof the filename, it must be either DIS or DIN.3. With DIN, <strong>ASAP</strong> limits the column output per line to 10, writes a comma to the end of the line, and continues anyfurther numbers on the next line.4. The title is delimited by a single quote ', as shown.WRITE Examples

<strong>ASAP</strong> | Commands and Macros (XYZ) | 406Commands and Macros (XYZ)Topics in this section of the Contents tab include <strong>ASAP</strong> commands and macros that begin with the letters “X, Y, Z”.XEQ (<strong>ASAP</strong> Command)Specifies immediate application of current linear transformation.Function• Create/Modify Objects• Define/Modify Curvedge Entities• Define/Modify Lens Entities• Define/Modify Surfunc Entities• Modify Ray/Beam DataSyntaxXEQ [ LIST ]OptionLISTDescriptionDecodes transformation matrix into simple operation (ifpossible) and printsRemarks1. Forces <strong>ASAP</strong> to immediately apply the current transformation matrix to the entity instead of waiting for a nontransformationcommand to signal the end to the transformation command set. The transformation matrix is thenreinitialized to the identity matrix and <strong>ASAP</strong> begins looking for a new set of transformation commands.XEQ ExamplesXMEMORY (<strong>ASAP</strong> Command)Specifies the type and amount of ray data to store, subject to available hardware and operating system limits.Function• Setup Beam CreationSyntaxXMEMORY MIN [ 'pagefile' ]NORM mFULLOptionNORMDescriptionImaging (incoherent) no parabasals and higher-orderbeam modes are saved

<strong>ASAP</strong> | Commands and Macros (XYZ) | 407OptionMINFULL'pagefile'mDescriptionIllumination (incoherent) no polarization, path lengths,paths, and beam sizes; PLOT BEAMS/POLARIZ,SPREAD, FIELD, OPDMAP are disabledImaging (coherent) automatically set by PARABASALcommandName of the pagefile (default VIRTUAL.PGS)Allocates only contiguous RAM for virtual.pgs, up to amaximum of m raysRemarks1. The availability of the FULL, NORM, and MIN options are dependent on the <strong>ASAP</strong> edition:<strong>ASAP</strong> Edition<strong>ASAP</strong> PRO<strong>ASAP</strong>Available OptionsMIN, NORM, FULLDefault is NORM on start-up and RESET.Dynamic allocation of rays in RAM.Use m after the command to specify the maximumnumber of rays.MINDefault is MIN on start-up and RESET.2. Raytracing speed may benefit from using the lowest XMEMORY option (MIN, NORM, FULL) appropriate for theapplication.XMEMORY setting Words (Bytes) per ray CommentsFULL 128 (512) Automatically set by thePARABASAL command.NORM 48 (192) No parabasals or higher-order beammodes (default) are saved.MIN 16 (64) No polarization, path lengths, paths,and beam sizes are saved. LISTELLIPSE, PLOT BEAMS/POLARIZ, SPREAD, FIELD,and OPDMAP are disabled.3. Use XMEMORY MIN when modeling illumination system sources. XMEMORY MIN is recommended because ofthe large number of rays required in these analyses.4. The format of a VIRTUAL.PGS file for XMEMORY FULL is different from the file format produced by XMEMORYMIN or XMEMORY NORM. Therefore, files created under the control of XMEMORY FULL are not readable underthe control of XMEMORY MIN or XMEMORY NORM, and vice versa.5. By default, the VIRTUAL.PGS file is written to the hard drive in the current <strong>ASAP</strong> working directory. However,if the optional parameter m is specified, <strong>ASAP</strong> attempts to secure from the operating system physical memory(RAM) sufficient to store up to a maximum of m rays. If the operating system cannot satisfy this request, <strong>ASAP</strong> isforced to use a VIRTUAL.PGS file.6. Physical memory (RAM) allocated with the m parameter is taken from contiguous free memory. System loadunrelated to <strong>ASAP</strong> can reduce the amount of contiguous free memory. The Windows operating system for 32-bitsystems limits the memory available to 2 GB, regardless of the total installed RAM. The operating system also

<strong>ASAP</strong> | Commands and Macros (XYZ) | 408requires memory of its own. A system with 2 GB of RAM typically can make, at most, a little over 1 GB of RAMavailable for ray data, before forcing <strong>ASAP</strong> to switch to a VIRTUAL.PGS file.CAUTIONXMEMORY should be set before defining rays. If you run XMEMORY during an <strong>ASAP</strong> analysis, <strong>ASAP</strong> initializes(deletes) the current VIRTUAL.PGS file.XMEMORY ExamplesXY[Z] and Other Plot Window Overrides (<strong>ASAP</strong> Command Argument)Sets the window to the given directions and size for only the currently active plot.Function• Standard Plot OptionsSyntaxXY[Z] [ m ]YZ[X] a a' d d'ZX[Y]YX[Z]ZY[X]XZ[Y]Remarks1. <strong>ASAP</strong> command arguments are optional and must follow a command.2. If the third direction is given, an OBLIQUE plot is generated.3. If the plot ranges, a a' d d' are not given, the plot is autoscaled (and then the window optionally magnifiedby a factor m). A good use of the option is for controlling the direction cosine space window without affecting thecurrent spatial WINDOW command. For example:SPOTS DIR YX -4@1XY[Z] ExamplesZERNIKE (<strong>ASAP</strong> Command)Creates a surface specified by an explicit Zernike polynomial.Function• Define/Modify Surfunc EntitiesSyntaxZERNIKE X x c c' c" ... [aperture ]Y yZ z

<strong>ASAP</strong> | Commands and Macros (XYZ) | 409OptionDescriptionX, Y, or Z Specifies axis of symmetryx, y, or z Location along axis of symmetryc c' c" c'" ...aperture<strong>Reference</strong> PointAt intersection of the surface and coordinate axis.Surface NormalAlong negative coordinate axis.RemarksUniversity of Arizona FRINGE Zernike coefficientsELLIPSE, RECTANGLE, or HEXAGONAL1. Creates an explicit surface by transforming the University of Arizona FRINGE Zernike coefficient set c c' ... to apolynomial.2. The second entry designates the axis of symmetry (either X, Y, or Z) for the surface.3. The zeroth coefficient c is the constant term (piston). The 36th or last coefficient is the 12th-order radial term(spherical). The first nine terms are related to the classical third-order optical aberrations:4. ρ is the distance from the coordinate axis.5. It may be necessary to SCALE the surface to its proper dimensions, since these coefficients are usually definedrelative to a unit circle area. The SCALE command automatically scales the physical dimension of the surface.6. If the sag of the surface is to remain constant over the new physical dimension, one of the SCALE parameters mustbe 1. For example, to SCALE by a factor of 2 in the X and Y dimensions, while maintaining the same sag as overthe unit circle, use SCALE 2 2 1.7. This surface can extend to infinity unless a LOCAL command follows, or a trailing aperture option of thefollowing form is specified:ELLIPSE a [ a' [ o [ s [ s' ] ] ] ]RECTANGLEHEXAGONAL a [ o [ s [ s' ] ] ]8. a a' are the heights in the other two transverse directions.9. For the HEXAGONAL form, a is the center-to-vertex distance (maximum height).10. o is an optional central hole ratio.11. s s' are the transverse coordinates of the center of the aperture.

ZERNIKE Examples<strong>ASAP</strong> | Commands and Macros (XYZ) | 410

<strong>ASAP</strong> | Building Your System | 411Building Your System<strong>ASAP</strong> commands can be grouped by function. The functional categories are in the approximate order that you wouldfollow in a typical workflow to build your system.Define/Modify Entities or Single Entity ObjectsDefine/Modify Curvedge EntitiesDefine/Modify Surfunc EntitiesDefine/Modify Lens EntitiesCreate/Modify Media, Coatings, and Scatter ModelsCreate/Modify objectsSetup Plots and Verify SystemStandard Plot OptionsSetup Beam CreationCreate Rays/BeamsModify Ray/Beam DataSetup TraceTrace Ray/BeamsAnalyze Ray/Beam DataModify or use Internal Ray/Beam Data as InputCalculate Diffraction/Propagation EffectsDisplay/Modify Data DistributionsSave or Recover System Data and Control ExecutionYou can define your own commands via the macro input facility. By default, <strong>ASAP</strong> first checks your input keywordagainst the primary command list. If it does not find a match, it searches the current macros and library file (if itexists).If a match is found, the macro is expanded in the normal way, except that the $ or & prefix on the macro name is notneeded.The command line does not echo the internal macro lines. These new commands are therefore indistinguishable fromnormal program commands. This capability does not alter the normal macro expansion when the macro name prefix ispresent. This means that a macro can still be run and echoed even if its name conflicts with a primary command.Achieving Optimal Performance in <strong>ASAP</strong>When determining your computer requirements, BRO encourages you to select an operating system that supportsoptimal performance for <strong>ASAP</strong>, and uses processor resources intensively for its computation, analysis, and graphicaloutput.In particular, if you are running <strong>ASAP</strong> on Windows 7 operating systems with 64-bit versions, you can achieveoptimal performance from <strong>ASAP</strong> by adding as much memory as your budget allows. These operating systemsautomatically cache the virtual.pgs file in RAM up to the available amount of RAM memory. The virtual.pgs filecontains the rays used in the simulation. This is the file that <strong>ASAP</strong> uses to read and write rays during ray tracing, andit accesses this file for other analyses requiring ray data.As a general rule, each ray of an incoherent extended source uses approximately 64 bytes of memory. If you knowthe number of rays in your source, you can use this simple relationship to estimate the size of the virtual.pgs file. Forexample, if you create 70 million rays, <strong>ASAP</strong> uses approximately 4.5 GB of available memory. If your initial sourcesize exceeds the available memory, <strong>ASAP</strong> uses the hard disk space, which is considerably slower and consequentlyaffects certain performances. Similarly, some simulations such as deterministic stray light analyses create rays andadd to the size of the virtual.pgs file.

<strong>ASAP</strong> | Building Your System | 412The Windows operating system in 32-bit versions limits the memory available to 2 GB, regardless of the totalinstalled RAM. The operating system also requires memory of its own. A system with 2 GB of RAM typically canmake, at most, slightly over 1 GB of RAM available for ray data, before forcing <strong>ASAP</strong> to switch to a virtual.pgs fileon disk.For faster speed, you may want to consider using SSD (solid-state drive) disks, regardless of the Windows operatingsystem, instead of traditional magnetic disks such as hard disk drives (HDDs). If <strong>ASAP</strong> runs out of available systemmemory, it uses disk storage. Therefore, <strong>ASAP</strong> performance improves with the speed of the disk drive systems.Setting the Working DirectoryThe Working Directory in <strong>ASAP</strong> is the location where files are stored when you perform tasks such as runningscripts or translating files. This topic describes the default locations of this directory in Windows XP and Windows7 systems, which are different. Default settings are the recommended locations. The topic also describes how to set auser-designated location.BRO recommends that you use the default settings for the Working Directory. Do not use a shared network drivelocation.The default settings differ in Windows XP and Windows 7 systems. In Windows XP systems, alldirectories are writable, and the default location of the <strong>ASAP</strong> Working Directory is C:\Program Files\<strong>ASAP</strong>xxxxVxRx\Projects, where xxxxVxRx indicates the <strong>ASAP</strong> version you are using; for example,<strong>ASAP</strong>2012V1R1. In Windows 7 systems, security restrictions limit the location of writable files, and the WorkingDirectory path that is writable in Windows XP is not writable in Windows 7. For this reason, the default locationof the Working Directory in Windows 7 is C:\Users\username\AppData\Local\<strong>Breault</strong> <strong>Research</strong><strong>Organization</strong>\<strong>ASAP</strong>xxxx.x\Projects, where <strong>ASAP</strong>xxxx.x indicates the <strong>ASAP</strong> version you are using; forexample, 1202.1, where 12=year, 02=version, and .1 = release number.To set the Working Directory to a different location, the location must be writable. Follow these steps:1. Click File> Set Working Directory in <strong>ASAP</strong>.2. In the Windows dialog box, select the folder to write the files, and click OK. Note: If you select a non-writablelocation, unexpected behavior may result.Assuming that the location of the Working Directory that you selected is writable, it is set until you change it.Building the GeometryAs you build optical system models, <strong>ASAP</strong> creates and adds to optical property and system geometry databases.The databases have additional commands for direct data entry and commands called modifiers that allow you to alterthe databases. You then associate data from these databases to an object for ray tracing.Your system models are typically created either in <strong>ASAP</strong> with the Builder, the <strong>ASAP</strong> Editor, or with your computersystem editor, and then opened in <strong>ASAP</strong>.Define/Modify Entities or Single Entity ObjectsThis topic lists commands that are used when defining or modifying entities or single entity objects.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.UPDATEENTITIES, OBJECTSControl entity updating in storageStart streamlined entity/object input

<strong>ASAP</strong> | Building Your System | 413Define/Modify Curve/Edge EntitiesThis topic lists commands that are used when defining or modifying curve/edge entities.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.CURVES/EDGESPOINTSLINE, DASHEDELLIPSERECTANGLEOVALROUNDEDRACETRACKCHARACTERARCCONICSAWTOOTHHELIXBEZIERSPLINEUSERCURVCOMPOSITEREPEATSAGASCALEBegin defining curvedge(s)Enter line/arc/controlpoints directlyEqually divided straightlineElliptical (circular)polygonRectangular (square)Something between ellipseand rectangleRectangle with crudelyrounded cornersRectangle with preciselyrounded cornersEdge patterned after acharacterPortion or all of a circleQuadratic segment givenconic coefficientsShape and number of teethGeneral helical (coiled)curveExplicit polynomial assame order BezierCurvature (G2) continuouscubic segmentsParametric curve or surfaceusing $FCNCombine set of previousedges into oneRepeat a previous edgedefinitionSag the edgeNon-linear asymmetricscaling

<strong>ASAP</strong> | Building Your System | 414ALTER X,Y,Z,QSMOOTHCOARSENINVERTSWEEP POS/DIR/AXIS/OFFIMAGEPATCHESUVSPACEEXTENDMATRIX ; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQAlter specific edge point(s)dataSmooth a piecewise linearcurveOpposite of SMOOTHReverse curve's parametricdirectionSweep curve into a surfaceImage curve through aspecified lensPoints represent Beziersurface patchesCurve in parametric spaceof an objectLinearly extend one or bothends.Linear transformation ofedgeDefine/Modify Surface/Function EntitiesThis topic lists commands that are used when defining or modifying surface/function entities.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.SURFACES/FUNCTIONSHORNTUBEOPTICALBICONICTORUSREVOLUTION ,FITAXICONICCARTOVALBegin defining surfacefunction(s)Horn given profilesTube-like surface (cone,cylinder)Classic rotationallysymmetric opticSurface with two distinctconic profilesTorus (doughnut)Rotated 2D curveRotated conic curve withfociCartesian oval

<strong>ASAP</strong> | Building Your System | 415CONDUITSUPERCONICZERNIKESAMPLEDGENERAL/COEFFICIENTS,EXPLICITPLANEELLIPSOIDFITTEDUSERFUNCUSERSAGCORNERROOFREPEATASYMFCNFMAPMULTIPLEARRAY EXPON,BOUNDS/SEARCH/RANTEST OFF/POINT/DIRECTION/AXISBENDLOCALRENORMCircle swept along planarexplicit cubicSpecial asphere used inoptical designDistort an axiallysymmetric surfaceExplicit Zernikepolynomial surfaceExplicit surfaceinterpolated from samplesEnter surface coefficientsdirectlyPlanar surfaceOrthogonal ellipsoid(sphere)Least squares fit to a set ofpointsUser-programmablefunctionUser-programmable radialor toric profileAxis-aligned corner of acubeTwo rectangles "hinged" atcommon sideRepeat a previous surfacedefinitionWrap macro functionaround surfuncOutput a surface functionmapExpand surface intomultiple sheetsReplicate single patch intospatial arraySet test for particularbranchBend surface in givendirectionLocalize surface in a "box"Renormalize surfacecoefficients

<strong>ASAP</strong> | Building Your System | 416SOLIDPARAMETERIZEALTEREXPLICITMATRIX; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQBounding volume formedwith local boxSet local axis for meshingsurfaceAlter specific polynomialcoefficientsConvert to explicit formLinear transformation ofsurfaceDefine/Modify Lens EntitiesThis topic lists commands that are used when defining or modifying lens entities.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.LENSESSEQUENCE, CURV/RADIMIRRORSINGLET FL/CV/RD,APLANATMANGIN FL/CV/RDDOMEDOUBLETTELESCOPERIGHTPENTAWEDGEAFOCALCOMPOSITEPERFECTIDEALBegin defining lensentity(s)Arbitrary set of conicoidsurfaceSingle reflecting surfaceTwo refractive surface lensSecond surface mirrorRefractive with one side ahemisphereCemented (achromaticdoublet)1 or 2 mirror telescope andcorrectorRight-angle prismPenta prismWedge of glassAfocal beam expanderCombine set of previouslenses into oneFor object at infinity butrealisticSpecify matrices of anideal lens

<strong>ASAP</strong> | Building Your System | 417IMPORTREPEATALTER X, Y, Z, U, V, W,H, C/R, K, O, MIMAGERESTRICT FORWARD/BACKWARD/OFF lensImport a lens design(ZEMAX) fileDuplicate a previous lensAlter specific lensconicoid(s) dataImage a global pointthrough lensDisplay aberrations ofcentered lensABERRATIONS ,LIST,PLOTDisplay aberrations ofcentered lensVARY, TH, CV, CC, CP,AS, BN, GLMINIMIZE, DIST, TLEN,GLTHANALYZESTOREMATRIX; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQDeclare variables foroptimizing lensMinimize RMS spotsubject to constraintsChange 1st-orderconditions, re-evaluateStore design in <strong>ASAP</strong>,CODE V, or ZEMAXformatsLinear transformation oflensCreate/Modify Media, Coatings, Scatter ModelsThis topic lists commands that are used when creating or modifying media, coatings, and scatter models.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.UNITSWAVELENGTH, UNITSMEDIAMODELS, PLOTABSORB, GRIN, CRYSTAL,SCAT/USER, ACTIVBegin defining scatter modelsLAMBERTIANHARVEYPOLYNOMIAL/TRINOM/BINOM,FITSet system geometry length unitsSet MEDIA and COATINGwavelengthsBegin defining media (glasses)Indices, absorption, gradient, andbirefringenceSimple constantPolished (smooth) surfaceGeneral polynomial with data fitting

<strong>ASAP</strong> | Building Your System | 418NONLINEARCOATINGS PROPERTIES /LAYERS / MODELSABGBICKCORRELATIONMEDIA BIAXIALVANES, EDGESUSERBSDFPARTICLES/VOLUME, MIEVCAVITYBSDFDATA / RAW DATARMSPHYSICALSUMVane structureUser-programmableRandom scattering centers or smallspheresRough (random v-cavities) surfaceInterpolate from entered valuesEstimate scatter from surfacestatisticsComprehensive physical reflectivescatterSum of other modelsBegin defining optical coatingsCreates an isotropic ABg (linear shiftinvariant) scatter model.Creates a birefringent coating.Creates an isotropic K-Correlationscatter model.Creates a biaxial medium descriptionoptionally used by BICCreate/Modify ObjectsThis topic lists commands that are used when creating or modifying objects.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.BRANCHOBJECTSREDEFINE SURF/NORM,THICK, COLORDEFORM, AXISBOUNDS/RBOUNDS,MULTIPLE,POINTLIMITS AXIS/REPEAT/STATS/EXPANDFACETSSet position in object namehierarchyBegin defining objectsRedefine basic optionsAdd small userprogrammabledeformationComplex boundingsurfaces, curves, volumesSimple orthogonal limitingboxSet subdivision of patchesinto facets

<strong>ASAP</strong> | Building Your System | 419GROUPEXPLODECPEGUMJONESLCCMUELLERPOLARIZ RANDOMPRINT (PolarizationModels)RPMINTERFACE COATING,DIFFRACTROUGHNESS, RANDOMSCATTER MODEL/RMS/BSDF, RANDOMSPLITLEVELFRESNELHALTMATRIX; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQMATRIX; ROTATE;SHIFT, SCALE; SKEW;PLACE; ALIGN; XEQTOWARDSLinear transformation ofentire objectAssign optical properties toobjectAffect specular by surfaceroughnessAssign scatteringcharacteristicsPreferential randomscatteringSpecifies specula ray/beamsplittingSpecifies scattered ray/beam levelFlux variation withincidence angleSets conditions for haltinga traceTemporary collection ofobjectsLinear transformation ofentire groupCreate separate objectsfrom lens partsDefines a compoundpolarization device.Define a general uniaxialbirefringent media deviceDefines a Jones matrixelement polarization devicedefinitionDefines a liquid crystal celllayer device modelCreates a Mueller matrixelementRandomizes thepolarization state vector ofthe raysPrints defined surfacepolarization modifiersDefines a realistic polarizermodel

<strong>ASAP</strong> | Building Your System | 420RRMDefines a realistic retardermodelObject CreationThis topic lists commands that are used in object creation.MICROSTRUCTURECreates a replicated microstructurescattering geometry/objectBuilding the SourceA grid of rays with assigned directions or a collection of rays generated by an EMITTING command is referred to asa source.Rays are created on a 2D planar grid (GRID or RAYSET commands and EMITTING DISK/RECT command) or 3Dvolume in space. These rays may be rotated, shifted, or otherwise transformed for a given application.Rays created with the GRID or RAYSET commands cannot be traced until a direction is assigned to each ray; use theSOURCE command for this activity.Unique Properties of Rays and Sources• Each source is independent.• Each source can have either one wavelength or no wavelength assigned to it. Polychromatic sources in <strong>ASAP</strong> areactually superpositions of individual monochromatic sources.• Every ray in a source is associated with an object. Untraced are referenced as object 0.• An object can be isolated by using the CONSIDER command.• At the conclusion of tracing, each ray in a source is again associated with a particular object.TipsIf a ray encounters a totally absorbing object, it remains there.If a ray is redirected by an object but cannot find another object with which to intersect, it remains on that object.If the flux of a ray drops below thresholds set by the HALT and CUTOFF commands, the ray remains on thecurrent object.• Sources can be traced only once. Generally, it is best to store the source construction commands in a separate fileand read them into <strong>ASAP</strong> as needed.• <strong>ASAP</strong> calculates the absolute phase of every ray during the ray trace.• Use the Builder to create sources.Create Rays/BeamsThis topic lists commands that are used when creating rays or beams.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.RAYSETGRID RECT/POLAR/ELLIP/OBJECT/HEX/WIN/DATBegin defining a table of rays/beamsDefine a spatial grid of rays/beams

<strong>ASAP</strong> | Building Your System | 421SOURCE POSIT/DIREC/FOCUS/LINE/WAVEEMITTINGGAUSSIANDECOMPOSE POSITION/DIRECTIONSOURCE POLYCHROMATICPLOT POLARIZATIONPOLARIZ K (<strong>Reference</strong> RayDirection)POLARIZ (Polarization Vector)POLARIZ TREF (Transverse<strong>Reference</strong> Direction)SOURCE POLYCHROMATICEMIT DISK/RECTEMIT CONE PYRAMID/BOX/SPHEROIDEMIT FILAMENT/HELIXEMIT RAYSEMIT IESEMIT ENTITY/OBJECTEMIT DATASpecify source(s) for the rays/beamsComposite of random emittersSimulate a random emitting surfaceSimulate a random emitting volumeSimulate a random emitting curve(wire)Arbitrary collection of raysEmitter specified by IES file dataRandom emission from definedsurface(s)Emit according to distribution datafileRays for coherent astigmaticGaussian modelDecompose an existing coherentfieldCreates a polychromatic sourcePlots polarization state ellipsesSets the direction of the polarizationreference raySets the polarization vector in a raylocal polarization coordinate systemSets the polarization coordinatesystem's transverse referencedirectiorCreates a polychromatic sourceVerifying the System and SourcesUsing <strong>ASAP</strong>, you verify the system and sources after building the geometry and sources.The key to creating sophisticated graphics in <strong>ASAP</strong> is to understand the relationship between the various types ofgraphics commands and the data itself.<strong>ASAP</strong> has a complete 2D and 3D graphics capability that includes overlays, oblique views, annotation, staticand dynamic rendering, zoom in/out, interactive point-and-shoot ray tracing, and many other features. Graphicscommands are divided into two broad categories:1. Set defaults, operating status, options (PIXEL, WINDOW, OBLIQUE, and others.)2. Create graphical output (SPOTS, OPDMAP and others)Setup Plots and Verify SystemThis topic lists commands that are used when setting up plots and verifying the system.• A slash between entries indicates that only one of the entries is allowed at a time.

<strong>ASAP</strong> | Building Your System | 422• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.TITLEPIXELS, ON/OFF, FILLWINDOWOBLIQUEVIEW, CENTER, EYE, DOLLY, ZOOM, ORBITPRINT SURF/EDGE/LENS/COAT/MED/OBJSPRINT SURF/EDGE/LENS/COAT/MED/OBJQPRINT SURF/EDGE/LENS/COAT/MED/OBJDIMENSIONSNUMBERS, NAMES/SUMMARYPROFILES NOOPTIM,PLOTREPLOT, OPTIM, NORAYSDRAWING, DIMENSIONS, NORAYSVUFACETS, LISTCONSIDERARROWSSEGMENTSSHOW, ALLCOLORSLIGHTSRENDER, DEPTH, RAYS, MODELMAP, DEPTH, SLOPESTREE, ENTITIESSpecify user ID and/or default titleSampling number and aspectDefine 2D graphics window on 3D dataOblique (nonorthographic) viewsPerspective viewsFull display of system informationShorter display of system informationShortest display of system informationShow dimensions of main arraysList currently used entity numbersDraw system profiles (slices)Plot geometry and/or ray dataReplot all 3D vector graphicsDraw four views of 3D vector graphicsFacets and views current objectsLimit current set of objectsSet rescaling of arrows on plotsNumber of segments per arcDisplay current command settingsSet colors by object's interfaceSpecify light sources for renderRender current object surfacesMap current object surfacesDisplay object name hierarchyStandard Plot OptionsThis topic lists command arguments that are used when setting up standard plot options.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together....CLIP...OVERLAY...COLORSSpecifies limits boxes for clipping raysPlaces next plot on topOverrides normal colors

<strong>ASAP</strong> | Building Your System | 423...TEXT…PIXELS...XY[Z] and Other Plot Window OverridesAnnotates plot with 2-D or 3-D textTemporarily overrides number of PIXELSTemporarily overrides current WINDOWSetup Beam CreationThis topic lists commands that are used when setting up beam creation.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.PARABASAL ,CLIP Controls parabasal ray calculationsWIDTHS, EDGE Sets relative beam width factorsWAVELENGTH Set operating wavelengthCLIP POS/DIRBOUNDS/RBOUNDS, MULTIPLE,POINTUSERAPOD POS/DIR/ANG/BOTH/OFFClip rays during creation and forPOS:Complex boundingsurfaces,curves,volumesUser-programmable apodizationPOLARIZ Set polarization direction and valuesXMEMORY FULL/NORM/MIN Controls extended ray/beam pagingBEAMS INCOH/COHER/GEOM/DIFF, SHAPESPECTRUM VIS/SCO/THERM/PHOT/FCN/OFFIMMERSEPOLARIZSets future beam characteristicsSets spectral weighting for futurebeamsSets starting medium for futurebeamsSets the polarization properties forfuture ray creationModify Ray/Beam DataThis topic lists commands that are used to modify ray/ beam data.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.SELECT SOURCE/OBJECTSUBSET ,RESETFLUXSelect ray group for future operationsCreate subset of current rays/beamsAssign total flux (power) in rays/beams

<strong>ASAP</strong> | Building Your System | 424SHAPEREVERSEMOVE BY/TO, POINT/PLANE/SPHERE/FOCIBILATERALIMAGEAPODIZE POS/DIR/ANG/BOTHMATRIX;ROTATE;SHIFT;SCALE;SKEW;PLACE;ALIGN;XEQSpecify shape and coherence of beamsReverse current ray/beam directionsMove to new positions on rays/beamsFlip ray/beam data about a planeImage ray points through a specified lensUser-programmable apodizationLinear transformation of ray dataTracing the Rays OverviewRay tracing is probably the most basic operation in <strong>ASAP</strong> since all information regarding system performance isobtained with it.In <strong>ASAP</strong>, rays are points in space that propagate from object to object until they are absorbed or there are no otherobjects to intersect.Rays start on object zero, a fictitious object. At the end of a ray trace, the rays are on the last object that theyintersected.Rays are traced only once, and new rays must be defined if a retrace is desired. They are traced nonsequentially,where rays intersect objects in the physically correct order, regardless of the order the objects are entered into theprogram.Preparation StepsRay tracing can involve several preparation steps, depending upon the type of analysis to be done, beamcharacteristics, and the complexity of the system geometry. Most analyses require these steps:• Initializing settings used during ray generation (WAVELENGTH, PARABASAL, POLARIZ and others)• Ray generation (GRID, SOURCE, EMITTING)• Post-ray generation modifications (FLUX, SHAPE and others)• Ray tracing settings (SPLIT, LEVEL, AXIS, FRESNEL and others)• Ray tracing (RAY or TRACE)During ray tracing, rays follow physically realizable trajectories unless overridden by the SEARCH command. Thismeans that rays intersect objects regardless of the order in which the objects were entered, and that rays intersectobjects as many times as physically necessary.Completing a Ray TraceTracing a ray is completed when the flux of the ray has dropped below a certain threshold (set absolutely orrelatively), or the ray has:• intersected an absorbing object• intersected an object, but cannot find another object along its trajectory• encountered too many objects• encountered the same object too many times• encountered a total internal reflection condition but SPLIT has not been set• begun to propagate in an undesirable direction or the ray is not ALLOWED to propagate

<strong>ASAP</strong> | Building Your System | 425TipWhen a ray intersects an object, the object’s interface properties determine which trajectory it will follow. Also,depending upon your choice of interface properties, <strong>ASAP</strong> can split an incoming ray into transmitted, reflected,diffracted (by the grating equation), and scattered components. A single ray can potentially generate thousands ofchild rays. Energy conservation is determined by your inputs.Tracing a Group of Rays or BeamsAny number of rays or beams may be traced at one time. The procedure involves initializing the ray and beam data(coordinates, directions, and sizes) at a plane in the system, which the program designates as object zero.The commands RAYSET and GRID set the coordinates and sizes while the SOURCE command then sets the directionsand starting optical path lengths.The FLUX command initializes the energy flux per ray or beam.Actual performance of the ray/beam trace is accomplished with the TRACE command.At any time the new ray data may be analyzed using the STATS and SPOTS commands.Coherent beam data is analyzed using the SPREAD and FIELD commands.Setup TraceThis topic lists commands that are used when setting up a ray trace.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.WARNINGSAXISSEED, QUASISEARCH ALL/SEQUENTIAL/LISTALLOWED ALL/SEQUENTIAL/LISTHALTCUTOFFSAVE, file#SPLITLEVELFRESNELMISSED ARROWS/LINE/OFFACCURACY HIGH/MEDIUM/LOWVOXELS FL/AB/X/Y/Z/OFFDOPL STAIRCASE/WAVEFRONT/PHASE/OFFControls warning messagesLocal and/or cylindrical coordinatesInitializes random number seedObject intersection search patternObject intersection halt patternSets conditions for halting traceSet absolute flux and number thresholdSaves all intersection data to fileSpecifies specular ray/beam splittingSpecifies scattered ray/beam levelFlux variation with incidence angleControls missed ray plottingAccuracy of ray/surface intersectionsSetup volume energy tracking during traceControls OPL from DIFFRACTive INTERFACEsRay Tracing Data Saved by <strong>ASAP</strong>For each ray traced by <strong>ASAP</strong>, different types of data can be saved (in the virtual.pgs file), depending on theXMEMORY setting and your particular edition of <strong>ASAP</strong>. This topic lists these types of data.

<strong>ASAP</strong> | Building Your System | 426• Absolute X,Y,Z direction cosines of base ray• Average divergence angle of beam• Average height of beam centered on base ray• Beam shape factor or number of higher modes• Beam shape number (see SHAPE example command)• Components of unit polarization vector• Current facet or multiple sheets of an object• Current object at which ray/beam is located• Global X,Y,Z coordinates of base ray• Medium in which the ray/beam is located• Number of the parent ray from which this ray was split• Number of times ray/beam was split• Number of times ray/beam was scattered• Optical path length from start of base ray• Parametric coordinates of base ray positions• Relative coordinates of ith parabasal ray• Relative direction vector of ith parabasal ray• Relative moduli of polarization components• Relative modulus of fundamental beam mode• Relative phase angles of fundamental beam modes• Relative phase angles of polarization components• Source number from which ray/beam originated• The ith previous split object for ray/beam• Total flux in ray/beam• Total number of objects ray has intersected• Total number of original sources• Total number of rays/beams• Wavelength of ith source• Wavelength of ray/beamTrace Ray and BeamsThis topic lists commands that are used when performing a ray/beam trace.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.RAY, PLOT, DIR, SEARCH, GALOP, LENSTRACE, PLOT/GRA, LIST/DIR, STATS, STEPTrace a single rayTrace current set of rays/beamsAnalyzing the DataAt the conclusion of ray tracing, the rays have been acted upon by the system geometry and are ready for the nextoperation, which is usually an analysis function.Unlike most optical design programs that produce ray-tracing output, <strong>ASAP</strong> treats ray tracing as simply an operationon the ray data.The analysis commands in <strong>ASAP</strong> access the ray data stored in the file, VIRTUAL.PGS and operate on the ray dataaccordingly. In some cases, the action of the analysis command changes the ray data; for example, a MOVE command

<strong>ASAP</strong> | Building Your System | 427determines the position of best focus in three dimensions and translates the ray data along their trajectories to thiscoordinate.Alternatively, the command produces a plot of the ray coordinates within the currently defined window, and doesnot modify the ray data in any way. The action depends upon the specific command or the specific option within thecommand.Analyze Ray/Beam DataThis topic lists commands that are used when analyzing ray/beam data.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.LIST POS/DIR/RAY/SOU/INT/ELLEXTREMES POS/DIR/FLUX/LENSTATS POSITION/DIRECTIONPATHS AVE/PEAK/TOT/OBJHISTORY, PLOTSPOTS POSITION/DIRECTIONFOCUS, MODE, MOVEPLOT BEAMS, RAYS, POLARIZATIONFFAD, SPOTS, REFERENCEOPDMAP fileRADIANT, MAP/AREADUMPCOLLECTIONCHROMATICITY, CIEList specific data for all or some raysList data on extreme raysStatistics of ray/beam data by objectGrouping and listing of ray pathDisplay histories of rays in SAVE fileDistribution of current ray dataFind (and move to) best focusPlot beams, rays or polarizationFull Field Aberration (Spot) DisplayInterpolate OPDs into file for DISPLAYRadiant pattern in spherical coordinatesCurrently selected rays to binary fileEfficiency vs. aperture and cone angleColorimetry analysisModify or Use Internal Ray/Beam Data as InputThis topic lists commands that are used when modifying or using internal ray/beam data as input.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.GETPUTLoad ray data into input registersMove values in registers to storageCalculate Diffraction/Propagation EffectsThis topic lists commands that are used when calculating diffraction/propagation effects.• A slash between entries indicates that only one of the entries is allowed at a time.

<strong>ASAP</strong> | Building Your System | 428• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.IRRADIANCEVIOLATIONSPREAD DIR/POS/APROX/NOR, DOWN, CLIPFIELDSUM, DELT, ADD, MULT, COUPLE, CONTFIELDBPM, DELT, MULT, COUPLE, CONTSet irradiance definition directionControls paraxial/positivity/stability messagesSpecular/scattered energy distributionsCoherent beam summationFinite-difference beam propagationSave or Recover System Data and Control Execution• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.SAVESYSTEM NEW/TO/FROM fileRESETDOMACROS FIRST/LAST/NEVERLSQFIT ,NORM/OFF,LISTFTSIZECADEXPORT IGS/DXF/VCRRETURNEND ,OFFWrites future ray trace data to a fileRead/write system data to binary fileReinitialize all settingsTransparent macro execution controlControls SVSD fitting algorithmSets Fourier Transform sizeExport object surfaces to CAD fileReturn to previous command levelEnd execution or ignore future ENDsDisplay/Modify Data DistributionsThis topic lists commands that are used when displaying or modifying data distributions.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.DISPLAYNORMALIZEFORMFFT, SIZERead distribution data,modify/displayNormalize by constant ormaximumSet to power or logarithmicformFourier Transform data

<strong>ASAP</strong> | Building Your System | 429ABEL, INVERSEAVERAGE, WEIGHTRADIAL, FUNC/INTEG/BOTHTRANSPOSEMODIFYCOMBINEREDUCEWRITEDMAPRANGETHRESHOLDPLOT3DISOMETRICGRAPH, APPENDCONTOUR, LOW/HIGH/TICS/VECTORDIRECTIONAL,UNWRAP, RADIANCEMESHENCLOSEDSECTIONTABLEANGLES, RADIANCEVALUESOFFSETAbel transform dataAverage data over severalpixelsRadially average about apointTranspose distributionarrayModify regions ofdistributionMultiply or add anotherdata fileReduce to a smaller subsetof dataWrite current data to <strong>ASAP</strong>files(s)Print a map of dataOverride min/max for dataplottingReset floor and/or ceilingdata valuesPlot in 3-D data plus majorprofilesIsometric plotPlot 1-D profiles of dataContour or "color" mapplotCreate polar plot of angulardistributionWrite distribution to 3Dsystem filePlot percent enclosedfunctionDisplay or transfer asection of dataDisplay a table of numericvaluesConvert direction cosinesto anglesList value(s) at actualcoordinatesShifts coordinate origin

<strong>ASAP</strong> | Building Your System | 430FOLD, FIRST/SECOND/BOTHPICTUREIESFILETEXTFILEHEADERREPLICATEAPPENDHISTOGRAMTERRAINREMOVEDATAEOFAverage data about one orboth centersProduce gray-scale pictureWrite IES file of angulardistributionCreate user-definable textfile of distributionWrite actual data inspecified formatEnd of text fileRedefine header (that is,labeling)Replicate distribution oneor more timesAppend current data togiven filePlot of data valuedistributionPeaks/valleys and FWHMstatisticsSubtract best-fitpolynomial

<strong>ASAP</strong> | Kernel Capabilities Overview | 431Kernel Capabilities OverviewThis topic briefly describes how <strong>ASAP</strong> models optical/mechanical systems, traces rays through the system, andmodels physical optics.Modeling Optical-Mechanical Systems<strong>ASAP</strong> accurately models virtually any optical-mechanical systems. Similar to 3D solids modeling programs,it utilizes a powerful geometrical approach that permits a nearly limitless variety of systems to be handled in astraightforward manner. As opposed to most other ray tracing algorithms, all surfaces and ray data are referenced bydefault to a single global Cartesian coordinate system. Smooth continuous object surfaces can be represented by asequence of simple conicoids or a general 286-term polynomial (taken to 10th or 20th-order in the three Cartesiancomponents or their squares), and can be bounded by other surfaces of the same general form. Therefore, anythingfrom a simple plane with a polygonal boundary to an arbitrarily oriented elliptical toroid can be modeled precisely.Even more complex parametric mesh surfaces (NURBS) can be defined by connecting two or more arbitrary curves,each formed by a series of lines and/or conic arcs in space.Tracing Rays through the SystemBundles of rays can be traced through the system so that, after every reflection or refraction, each ray always transfersto the nearest object. Rays are allowed to interact with an object any number of times; that is, multiple bounces.Therefore, the program easily handles the "funneling" effect of non-imaging radiation collectors as well as imagingsystems. Each ray may be assigned an arbitrary total flux that is reduced by volume and surface absorption (orincreased in a gain medium) as the ray propagates through the system. The standard Fresnel equations are used tonot only calculate (as a function of incidence angle and polarization) transmission losses at interfaces between twodielectric media, but also reflection losses at any dielectric/conductor interfaces. The program is also capable ofsplitting any ray into reflected, transmitted, diffractive, near specular, diffuse, and backscatter components.Modeling of Physical OpticsEach ray may also be treated as a coherent/incoherent scalar/vector beam (normally Gaussian). Groups of these beamscan be combined to simulate the optical or electromagnetic field incident on a system. Each beam and thus the entire"wavefront" is then rigorously propagated. The resulting field may then be calculated and displayed at any locationwithin the system (including on the surfaces of grazing incidence optics) and not just near focus. <strong>ASAP</strong> not onlyperforms geometrical optics modeling, but also accurate physical optics modeling of any system.Command ScriptingThis topic describes scripting functions available only in command mode.• Scatter and several other commands.• Macros for performing looping, if-statements, source and geometry libraries; and for reducing frequently usedcommand sequences to a single command.• User-written files that you can extensively comment and easily read.• Variables and mathematical expressions for defining quantities that are frequently changed.Note: You can use the command mode interactively or in the background in batch mode. Since the outputfiles are fully compatible with the user interface, you can use the user interface to view or manipulategraphics.

<strong>ASAP</strong> | Kernel Capabilities Overview | 432Examples of Command ScriptsYou can open any one of the hundreds of example scripts in the form of <strong>ASAP</strong> INR files, and use them as templatesfor creating your own <strong>ASAP</strong> files. Copy all or portions of these examples to the Clipboard, paste them into an Editorwindow.These scripts are accessible in three ways: from the command help topics, from your <strong>ASAP</strong> installation directory,or directly from the Quick Start toolbar. Select the Example Files tab on the toolbar, and then select the commandname or example file name you are interested in viewing. The script will open in the Editor window. More than oneexample may be listed for a command or category of commands.If the Quick Start toolbar is not visible in your <strong>ASAP</strong> window, go to the View menu and select Properties Bar.Examples are categorized into these groups:CategoriesCommandsJScriptKeywordsVBScriptGroups of <strong>ASAP</strong> commandsIndividual <strong>ASAP</strong> commandsExamples of JScript commandsCommands grouped by keywordsExamples of VBScript commandsYou can also access the Index of Example Scripts on your computer in your asap installation area under projects\examples\example_scripts.html.Command Usage<strong>ASAP</strong> commands consist of up to 10,000 unformatted alphanumeric entries that are separated by one or more ofblanks " " or commas ",".Arbitrary string entries can be delimited by double quotes. Otherwise, literal entries consist of an unbroken string ofalphanumeric characters (A through Z through 9, and _). They must start with a letter or underscore "_" and can be ofany length (but only the first 8 may be significant).Numeric entries can be in integer, floating point or exponential format. Exponential entries, for example "1.34E-5",are limited to 40 characters.Usually a command begins with a literal, with only one command in each input record. However, more than onecommand can be placed in a record by separating the commands with semicolons ";". A command can extend overmore than one record. If the last non-blank character in an input record is a comma (,), the command continues to thenext record.Entry delimitersMaximum number of entries per command 10000Literal entriesCommandsMaximum exponential numeric entry lengthblanks and commasBegin with a letterUsually start with a literal40 charactersMultiple commands per record separator Semicolon (;)Command continuationCommand argumentsComma (,) at last character of recordOptional entries beginning with …(for example, …CLIP); must appear after a command

<strong>ASAP</strong> | Kernel Capabilities Overview | 433Note to European <strong>ASAP</strong> UsersDecimal numbers must be entered with a U.S. decimal point, using the period (.) key. If you enter decimal numberswith the European decimal point using the comma (,) key, <strong>ASAP</strong> treats it as a space, and your results are not accurate.Command Comment StringsUser comment strings can be embedded in any command without usually affecting processing.Enclose user comment strings in an entry delimiter followed by one of the following comment string delimiters:* = / \ < > ` 'If a command begins with any of these characters, the rest of that command line is ignored. Comment stringsdelimited in this manner can up to 344 characters and composition (except matching delimiters), and provide the userwith a convenient facility for documenting input files.Letters opposite in case to that set by the $CASE macro can also be used as embedded comments, since the programtreats them as blanks. Trailing comments can be entered after an exclamation point (!), since this character signals theprogram to stop decoding input from the command.Opposite case letters are treated as blanks.Last entry, stop parsing is indicated by an exclamation point (!).Command Description NotationShows format or syntax of each <strong>ASAP</strong> command in the command topics. Syntax can be followed by a detailedexplanation of the command’s function.A standard notation is used for the quantities shown.• UPPER CASE letters or numbers represent the actual literal form of the entry.• Single lower case letters represent numerical entries to be determined by the user.• Lower case words represent literal entries that can take on the described set of values.• Trailing lower case letters on literals and anything enclosed within square brackets are optional and will nottrigger a program error if omitted.• The default value for most optional numeric entries is zero, unless otherwise stated. Alternate forms for an entryare shown in the same vertical column.Entries Repeated and <strong>Inc</strong>rementedThis topic provides rules and examples of command entries that are repeated and incremented.Use an at symbol @ embedded between two entries to enter redundant data in an efficient manner. For example,3@1.4 ==> 1.4 1.4 1.4-4@1.4 ==> -1.4 1.4 -1.4 1.4Use a colon : between two integer entries to represent an increasing or decreasing sequence of integers; for example,3:7 ==> 3 4 5 6 74:-1 ==> 4 3 2 1 0 -1If one or both of the entries are less than one in magnitude, use an increment that is also less than one in magnitude.For example,.1:.5 ==> .1 .2 .3 .4 .5

<strong>ASAP</strong> | Kernel Capabilities Overview | 434.11:.08 ==> .11 .10 .09 .08Use a colon : between two literal entries that differ by only one character or a set of contiguous integers to generate asimple sequence, for example,ALITERAL:DLITERAL ==> ALITERAL BLITERAL CLITERAL DLITERALR11:R0 ==>R11 R10 R9 R8 R7 R6 R5 R4 R3 R2 R1 R0Distribution Data Files Overview<strong>ASAP</strong> has several commands for calculating the irradiance, intensity, radiance, etc., for a set of files, some of whichproduce immediate results of these calculations in the form of plots directly on the screen.For example, geometric spot diagrams display plotted points representing the geometric location of rays in a spatial orangular coordinate system.As this display occurs, <strong>ASAP</strong> simultaneously creates data files called distribution data files. These files contain moreinformation from the calculation than the information displayed on the screen. Furthermore, some <strong>ASAP</strong> commandsonly produce output contained in the distribution data files that must be displayed with other graphical tools.Distribution data files can be read into a special graphical viewing area in <strong>ASAP</strong> called DISPLAY, which is akeyword-like SURFACE or OBJECT that has its own set of commands. These commands are for general plotting,editing, and analysis of the data contained in a distribution data file.Distribution data files are referenced by LOGICAL unit numbers or file names for some of the commands. Thedefault distribution file is BRO009.DAT. This file defaults to overwrite each time a calculation is performed. Youcan control how the information is accumulated in the distribution data files by the sign of the unit number. If the unitnumber has a negative sign in front of it, any data previously stored in the file is overwritten. If the unit number ispositive, the newly generated data is added pixel by pixel to the current contents of the data file.The WINDOW command sets the physical area over which the irradiance, intensity and others, is computed. ThePIXEL command sets the resolution of the calculation and hence the number of data values in the distribution datafiles. For example:• If the WINDOW command defines a square area, the data file is an nxn array where n is set with the PIXELcommand. The pixels are square in size.• If the WINDOW command defines a rectangular area, the data file is n pixels across (as set with the PIXELcommand) and αn pixels down (where α is the ratio of the down direction (horizontal screen dimension) to theacross direction (vertical screen dimension) of the current window settings). In the situation where αn is not aninteger, the size of the pixels in the horizontal screen dimension are scaled to accommodate the smallest integernumber of pixels that fit the window.Distribution Data Files DisplayMany analysis commands (SPOTS, OPDMAP and others) create distribution data files. These files contain matricesof various forms of data (flux data, optical path difference data and others) and are stored on disk in binary format forefficiency as they can become quite large.DISPLAY is a top-level <strong>ASAP</strong> command, like SURFACE and OBJECT that provides storage, retrieval, editing,graphical display, and post-processing of 2D distribution data files. Unlike other <strong>ASAP</strong> commands, DISPLAY isalmost a separate program operating within <strong>ASAP</strong>, and it has its own rich set of commands specifically tailored forworking with distribution data files.If you enter a command that DISPLAY does not recognize, you are prompted with a dialog box showing thefollowing message:Unrecognized DISPLAY subcommand!

<strong>ASAP</strong> | Kernel Capabilities Overview | 435If you respond by clicking CANCEL, you are returned to DISPLAY mode; otherwise, <strong>ASAP</strong> attempts to execute thecommand, thereby placing you out of the DISPLAY portion of the program.Display OutputThe header of the distribution data file contains information about the data contained within it.• The first line identifies the distribution data file.• The next lines specify the type of data, units, the spatial (or directional) coordinates over which the data was taken,and the number of pixels (sample points).• The following lines report the data statistics, units, and locations of minimum, maximum, and average data values.If appropriate, the last line indicates the total integrated flux contained in the data.Opening OLD distribution file 9: bro009.dat4-record file header:Geometrical Ray SPOTS 11Z 0.000000E+00 FLUX / UNIT-AREAX -4.545455 4.545455 11Y -4.545455 4.545455 11Statistics on 11 by 11 data set:FLUX / UNIT-AREA Location Y XMinimum .0000000 1 1 -4.132232 -4.132231Maximum 1.209978 4 1 -1.652893 -4.132231Average .9699814 6 6 -.2980232E-07 .1192093E-06TOTAL FLUX = 80.164Distribution File StructureDistribution files are unformatted (binary) direct access files with a five-record header followed by the data array.The record length is fixed at LENR=NUMF*NUMX or seven words (4*LENR or 28 bytes), whichever is greater. Thestructure for the most common 2D format (NUMF positive) is listed below:Record Length (bytes) Content1 7 28 247+256*(4*LENR), 0, 0,0, 0, 0, 02 7 28 TITLE*24, NUMF3 7 28 ZLABEL*8, ZVAL,FLABEL*164 7 28 YLABEL*16, YMIN,YMAX, NUMY5 7 28 XLABEL*16, XMIN,XMAX, NUMX6 LENR 4*LENR F(1,1), F(2,1), ..., F(NUMX,1)7 LENR 4*LENR F(1,2), F(2,2), ..., F(NUMX,2):

<strong>ASAP</strong> | Kernel Capabilities Overview | 436Record Length (bytes) ContentNUMY+5 LENR 4*LENR F(1,NUMY), ...,F(NUMX,NUMY)[NUMY+6 X(1), X(2), ..., X(NUMX) ]NUMF specifies the size of each data point in real words; that is, the function F can be anything from a scalar tocomplex vectors:NUMF1 ScalarFUNCTION2 Complex3 Vector or Triplet4 Complex SemiVector6 Complex Vector7 Min Ray Data9 Norm Ray Data12 2 Complex VectorsThe optional last record can be used to override the normally equally spaced X coordinates with a set of arbitraryascending values. These coordinates are applicable only to output from a GRAPH command.The signs of NUMX and NUMY determine whether the sample points are at the center or edge of a cell; for example,respectively for X:if NUMX>0orif NUMX

<strong>ASAP</strong> | Kernel Capabilities Overview | 437• Spaces and dots are not allowed in an INR file name.• Spaces and dots are allowed in the string of a working path.Files Produced by <strong>ASAP</strong>This topic lists the file types that <strong>ASAP</strong> produces and uses.Certain files are produced only in response to particular commands (for example, a file with the extension, *.reg isproduced only by the $STO command). You may not see all these files in your directory after running <strong>ASAP</strong>. In thefollowing table, a number symbol (#) denotes a numerical file extension. The notes referenced in column 1 are listedafter the table.Command(s) to CreateFileExtension Format Description$IO output *.otr ASCII text output file; <strong>ASAP</strong> runin batch mode$IO OUTPUT *.out ASCII text output file; see Notes$ITERMAP*.dis direct-access binary distribution data file$STO *.reg binary variables storage fileAutomatically created by<strong>ASAP</strong>*.usr ASCII journal of user commandsCAD DXF *.dxf ASCII AutoCAD-format fileCAD IGS *.igs ASCII IGES-format fileEMITTINGGAUSSIANGRID...RAYSETENDSYSTEM TOFIELDOPDMAPMODEL ... PLOT...PLOTvirtual.pgs direct-access binary ray data storage filelastexec.sys binary system geometry filebro029.dat direct-access binary complex optical field*_#.dis direct-access binary BSDF dataNumerous commands *.dat binary/ASCII temporary data fileSAVE *.his direct-access binary ray history fileSAVE k *.# direct-access binary ray data fileSee Note 1 bro009.dat direct-access binary distribution data fileSee Note 2 *.plr ASCII screen graphics plot file

<strong>ASAP</strong> | Kernel Capabilities Overview | 438Command(s) to CreateFileExtension Format DescriptionSee Note 3 *.vcr ASCII 3D vector fileUser-defined *.ies ASCII IES-format data fileUser-defined *.inr ASCII text input fileUser-defined *.lib ASCII text macro libraryUser-definedCreated by <strong>ASAP</strong> whilereading the file, *.inrcontaining embeddedmacrosEXPLODE*.mac ASCII text macro libraryUser-defined usap3d.# ASCII apodization data fileWRITE *.din ASCII distribution data fileGUI (generated files)*.enxXMLXML file for the Builder*.enz*.plx*.inxXMLXMLXMLcompressed XML file forthe BuilderXML file for the ChartViewerXML file for the EditorPath Explorer (generatedfiles)*.gtx XML XML file type supportedfor importing to <strong>ASAP</strong>*.pxp binary Created and used internallyby the Path Explorer. Canbe safely deleted when nolonger needed.BIN *.dod binary Detector Object Data- created when an INRscript with the BIN objectmodifier is run, and usedby <strong>ASAP</strong> to visualizedistribution and propertiesof light on the underlyingdetector object.Notes1. Files other than *.inr, *.mac, or *.lib may not be backward compatible in <strong>ASAP</strong>.2. Commands creating files, bro009.dat include: FIELD, FMAP, MAP, OPDMAP, RADIANT, RENDER, andSPREAD.3. Commands creating files, *.plr (in some cases, specific options are required) include: CONTOUR,DIRECTIONAL, ENCLOSED, FFAD, GRAPH, HISTORY, ISOMETRIC, MODELS. . .PLOT, . . . PLOT, PLOT. . ., PLOT3D, PROFILES, RADIAL, RENDER, REPLOT, SPOTS,and TRACE.

<strong>ASAP</strong> | Kernel Capabilities Overview | 4394. Commands creating files, *.vcr (in some cases, specific options are required) include: CONTOUR, HISTORY,MESH, PLOT. . ., PROFILES, RADIANT, SPOTS, and TRACE.5. $IO OUTPUT text files of type *.out can be opened in a text file under Windows 7 only if you have associatedthis file type with a text editor. Right-click an existing *.out file, click Open with, and click Notepad orWordPad (or any other installed text editor). You can also assign a *.txt extension to the file name on the $IOOUTPUT command to assign that extension. For example:$IO OUTPUT JOE.TXT 2Alternatively, assign a file extension of *.txt in place of *.out.File Structure of <strong>ASAP</strong><strong>ASAP</strong> is a sophisticated set of 3D system modeling and optical ray/beam propagation algorithms. It performs theentire ray tracing and derivative calculations.Ray data is stored in an external file called VIRTUAL.PGS. <strong>ASAP</strong> performs a ray trace by reading and writing raydata from and to this file, while using the optical prescription data stored within data arrays. Since ray data is stored inan external file, the total number of generated rays is a function of your disk space.Optical fields calculated from a ray trace are stored in several files. If only scalar optical field data is calculated (suchas spot diagrams or irradiance patterns), it is stored in a file called BRO009.DAT. If complex or vector optical fielddata are calculated, (such as polarized field amplitudes), they are stored in a file called BRO029.DAT.Plots created in <strong>ASAP</strong>, whether of a ray trace or other derivative ray trace calculation (such as a spot diagram), arewritten to a plot file (unless you override this). This plot file typically is named filename.PLR, where filename is thelast loaded .INR file.Text information is not written to a file unless you specify this. The text information is typically stored infilename.OUT or filename.OTR. The latter is created when <strong>ASAP</strong> is run in batch mode. Every command that isinteractively entered from the keyboard is archived in a file typically called filename.USR.External editor: If you are not using the Windows dialog boxes to perform an <strong>ASAP</strong> analysis, you are most likelycreating ASCII files (*.INR) with an external editor. These files typically contain <strong>ASAP</strong> commands that describe theoptical system geometry and sources of radiation. Commands for performing an actual analysis may be included inthe files, or entered interactively via the keyboard. The Editor window in <strong>ASAP</strong> is accessible from <strong>ASAP</strong> Workspaceon the Views tab, or by opening an INR file.General Input TechniquesTechniques for <strong>ASAP</strong> input include: radian angle entries, relative and literal referencing, direction vectors, and lineartransformations.Radian Angle EntriesAngle entries that, by default, are in radians (that is, the PARABASAL divergence, ROUGHNESS RANDOM slope, andINTERFACE RMS/BSDF back cone angle) can also be entered in degrees by appending a "D" to the end of thenumber. For example, the following two entries are equivalent:2.5D 2.5/57.29578 radiansIf the entry is a direction cosine coordinate (CLIP DIR or SPOTS/SPREAD DIR window), the result is the sine ofthe angle; for example:2.5D SIN(2.5/57.29578)

<strong>ASAP</strong> | Kernel Capabilities Overview | 440Relative and Literal Referencing of EntitiesAlternate schemes are available when referencing surface/edge/lens, media, object, ray or source numbers withincommands. Instead of using the actual absolute number, you can specify a number relative to the largest numberdefined by using a decimal entry of the form ".i" where i is an integer between 1 and 9999 inclusive. ".i" is equivalentthe 1 plus largest number defined, minus i.Referencing Method Format DescriptionAbsolute n actual entity numberRelative .i max+1-iLiteral name exact or abbreviationSome examples of relative indexing are:.2 next to the largest number defined so far-.1 negative of the largest number definedAlso, for most commands that require the specification of a particular object, media or coating, the name can be usedin place of directly specifying the number or using the relative indexing described above. <strong>ASAP</strong> first attempts anexact match (ignoring blanks). Otherwise, the characters in an abbreviation must be present in the same order as inoriginal object, media or coating name but not necessarily consecutive; that is, any number of original characters canbe skipped to make the abbreviation small enough but unique. An underscore "_" in a literal media reference alwaysrequires an exact match and is also used to separate the catalog name (file with extension CAT) from the glass name;for example, "SCHOTT_BK7".Direction VectorsSee ...a,b,c... (<strong>ASAP</strong> Command Argument)Linear TransformationsLinear transformations change the scaling or orientation of a geometrical entity (surface, edge, lens, object, group,and rays) by applying a general 4-by-4 linear transformation matrix to it. Any number of the following elementaryoperations can be applied after any entity definition to build up the final matrix. The order in which these operationsare entered into the input stream is exactly the order in which they are applied to the entity. These commands must begrouped together following an entity definition and with no other commands between them (except for a comment).The LIST option causes the resulting 4-by-4 transformation matrix to be printed and decoded into simple operationsif possible. A general transformation for a position vector (X,Y,Z) has the form:Note:The A's are the rotation submatrix while the D's are the translation vector.The first row is a dummy used to make the matrix square (and thus invertable).For the transformation of a direction vector the dummy row contains all zeros.

<strong>ASAP</strong> | Kernel Capabilities Overview | 441Input RecordsThis topic describes how <strong>ASAP</strong> reads input data.Input data is read sequentially from records up to 344 characters long (<strong>ASAP</strong> ignores anything after this length or adouble exclamation point "!!"). <strong>ASAP</strong> first attempts to read input from a file named defsetup.in? (the last characterin the extension depends on the particular application program). This file must contain any default input settings thatwould normally be used in every program run.After processing the input from this file, <strong>ASAP</strong> starts reading either from the file specified as the first command lineargument or, in batch mode, from logical unit 1 (BRO001.DAT). The file that this unit is assigned to (or the systemdefault specification) must be created using the system editor.If an end-of-file is reached while reading the input disk file, and before a program run is stopped with the proper inputcommand, <strong>ASAP</strong> automatically switches over to prompting you (with a greater-than sign ">") for data entry directlyfrom the keyboard. This feature allows you to run <strong>ASAP</strong> from a file and/or in interactive mode.Maximum input record lengthPremature record terminator !!Startup fetching sequenceKeyboard input prompt ???>344 charactersdefsetup.in? -> command argument -> Keyboard(BRO001.DAT batch)Mathematical Functions SupportedDescribes the set of supported mathematical functions.Closing right character: ) ]INT Truncate to integer Round to nearest integerEXP Natural (base e) antilog Common (base 10) antilogLOG Natural (base e) logarithm Common (base 10) logarithmABS Absolute value Absolute valueSGN Sign (returns -1, 0, or +1) Sign (returns -1, 0, or +1)SQRT Square root Square rootCBRT Cube root with same sign Cube root with same signSIN Sine of angle in RADIANS Sine of angle in DEGREESCOS Cosine of angle in RADIANS Cosine of angle in DEGREESTAN Tangent of angle in RADIANS Tangent of angle in DEGREESASIN Arcsine of angle in RADIANS Arcsine of angle in DEGREESACOS Arccosine of angle in RADIANS Arccosine of angle in DEGREESATAN Arctangent of angle in RADIANS Arctangent of angle in DEGREESBJ# #th-order Bessel J function (# from 0to 9)BK#Modified Bessel K function (# from0 to 9)#th-order Bessel J function (# from 0to 9)Modified Bessel K function (# from0 to 9)

<strong>ASAP</strong> | Kernel Capabilities Overview | 442STEP 0 for X0 0 for X0RECT 0 for |X|>.5, 1 for |X|.5, 1 for |X|

<strong>ASAP</strong> | Kernel Capabilities Overview | 443The fractional part of the argument to RAN is the relative amount (total probability) of an additional uniform variatewith the same RMS or maximum; for example, RAN[2.6] has a probability distribution that looks like the shape of ahouse.TipThe ability to perform arithmetic operations during input decoding is a powerful feature when used with the macrofacility.ExamplesOLDNEW2.-1./2. ==> .52.-1./2. ==> 1.52.-(1./2) ==> 1.5 2.-(1./2) ==> 1.5SIN[A.]^2+(COS[A.]^2) ==> 1.0SIN[A]^2+COS[A]^2 ==> 1.0SQRT((X.^2)+(Y.^2))’(Y.%X.) ==> X.‘YSQRT(X^2+Y^2)’(Y%X)==> X‘Y(3.-1.)^4 ==> 16.(3.-1.)^4 ==> 16Mathematical OperatorsLists mathematical operators that affect entries in the program.If two entries are separated by one of the symbols listed in the table, the entries are replaced by the result of theoperation.+ ADD the two entries 4- SUBTRACT the second from first 4* MULTIPLY the two entries 5^ RAISE first TO second POWER 6/ DIVIDE first by second 5\ REMAINDER after dividing first bysecond6< Take LESSER of the two 6> Take GREATER of the two 6% ARCTANGENT (angle in degrees) ofthe first divided by second~ Uniformly distributed RANDOMnumber between first and second67`'Form complex number from REALand IMAGINARY partsForm complex number fromMODULUS and PHASE angle (indegrees)00

<strong>ASAP</strong> | Kernel Capabilities Overview | 444( [ Store value of expression andoperator to the left) ] Recall previous value and operator,evaluate new expression12• The two pair/complex operators, "`'" are found under the tilde (~) (REAL and IMAGINARY) and double quote(MODULUS and PHASE) keys on most keyboards.• Operator precedence is followed during input parsing:Negation - 1st precedenceExponentiation - 2nd precedenceMultiplication or division - 3rd precedenceAddition or subtraction - 4th precedence• Parentheses may be used to force a particular order of evaluation.• If $EXP is set to OLD, consecutive operations are always evaluated from left to right with no operator precedence,until a delimiter terminates the expression. Nested parentheses or brackets can be used if necessary.TipsSince curly braces { } are used in macro definitions, do not use them in mathematical expressions. Instead, useparenthesis ( ) and square brackets [ ] in mathematical expressions.Example of Operator Precedence2.0-1.0/4.0 is evaluated as 1.75(2.0-1.0)/4.0 is evaluated as 0.25Registers for Storing Arithmetic ResultsThis topic describes how arithmetic results in <strong>ASAP</strong> are stored in registers.<strong>ASAP</strong> has 286 direct registers designated by the letters A through Z by themselves or followed by the numbers 0through 9. (A special set of registers starting with an underscore "_", instead of a letter, are reserved for argumentpassing). These registers can be used for the storage of both intermediate arithmetic results and literals.Three pieces of information are associated with each of these registers:• location (A...Z9)• name (literal up to 16 characters)• number designation (double precision)In the following examples, R stands for any register. To store the value of any valid arithmetic expression or literal ina register (forming a null entry) or recall a value in a register as an input number, use the following formats:Old New Precedence LevelStore numeric in R expression=R R=expression 3Store literal in R literal=R R="literal" 0Recall numeric from R R. (R)Recall literal from R R" R"Recall number fromregister with literalliteral(literal)

<strong>ASAP</strong> | Kernel Capabilities Overview | 445where R is one of 286 registers A...Z or A0...Z9.Registers are zeroed and blanked out at program start up. The capability to recall the numeric in a register byreferencing the literal stored in that register allows the user to assign a register a variable name, and then use thatname (up to 32 characters), instead of the short-fixed register name.An unknown variable is automatically assigned to an unused indirect register location starting at 1768 and workingdown; that is, up to 1482 user variables can be created before any conflict with the normal direct register set occurs.As an example, the following input increments the contents of the register/variable, and uses the result as the currentinput entry:R.+1=R.(R=R+1)!increment register/variable and use result (OLD)!increment register/variable and use result (NEW)If the period is omitted at the end of the OLD expression or the parentheses omitted from the NEW, the register is stillincremented, but no input is passed to the program. The current contents of the registers/variables can be displayedusing the $REG predefined macro command.Single- and Double-Precision NumbersSingle-Precision (SP) uses 32-bit IEEE floating point numbers with seven decimal digits of accuracy. Double-Precision (DP) uses 64-bit IEEE floating point numbers with 15 decimal digits of accuracy. In the large number offloating point operations needed to trace a ray, a rounding error makes the accuracy in the final results much lower.For example, OPL (optical path length) accuracy is on the order of five decimal digits for SP and 11 for DP.Specifying Complex NumbersComplex numbers can be entered in some of the <strong>ASAP</strong> dialogs.For example, the Optical Properties dialog accepts a complex index of refraction. The two ways to specify a complexnumber are:1. The real and imaginary parts are separated by a forward quote `. For example, you can write0.1 + 0.2i as 0.1`0.2Note: No space is allowed between the real part (represented by the number 0.1) and the imaginary part,starting from the forward quote.2. An amplitude and phase (in degrees) separated by a backward quote '. For example, you can write:2.0ei3.0 as 2.0'3.0Variables<strong>ASAP</strong> has 1768 variable locations (memory cell locations or registers) available for intermediate arithmetic variableassignment. This collective group is referred to as variables, which are divided into two groups: internally named andexternally named variables.Variable SubstitutionA common use of the variables is simple substitution of a variable for a command argument. In this case, you assign avalue to a variable and proceed to use that variable throughout the input. Changes to the model may be accomplishedby simply changing the value of the variable.You do not have to delimit individual variables in an operational string. However, parentheses "(name)" or "name"are required when you want to use the numerical content of an isolated variable.

<strong>ASAP</strong> | Kernel Capabilities Overview | 446You can modify and use the contents of a variable.Externally Named VariablesExternally named variables allow you to select a variable name. <strong>ASAP</strong> then allocates a variable location for it. Thesevariables may be accessed only by the variable name. You can not directly address the particular variable locationassigned to that variable.<strong>ASAP</strong> has approximately 1500 externally named variables.Only two pieces of information are associated with each of these variables:• variable name (literal up to 32 characters)• number (double precision)At program start-up, these variables are zeroed and blanked.You may assign or retrieve information from any of these variables in the following way (the variable name XYZ isused as an example):Store number XYZ: XYZ=numberRecall number from XYZ: (XYZ)Remarks• No blank spaces are permitted in a variable assignment.• The variable assignments and arithmetic calculations all take place in the background (within the parser). Thecalculations or results are transparent to <strong>ASAP</strong>, unless they are used as arguments to <strong>ASAP</strong> commands.• Be careful when using internally named variables if you are also using the GET and PUT commands to accessray data from VIRTUAL.PGS. GET and PUT transfer ray data into and out of specific internal variable locations,potentially overwriting variables you may have intended for another purpose.Internally Named Variables<strong>ASAP</strong> has 286 internally named variable locations. They are designated by the letters A through Z9 (A, B, C,…, Z,A0, B0, C0,…, Z0, A1 B1, C1,…, A9, B9, C9,…, Z9).Three pieces of information are associated with each of these variables:• variable location (A…Z9)• variable name (literal up to 32 characters)• number designation (double precision)At program startup, the information assigned to all variable locations is zeroed and blanked. You may assign orretrieve information from any of these variable locations in the following way (the variable location designation R isused as an example):Assign a number to RAssign a variable name (literal) to RRecall number from RRecall literal from R R"Recall number assigned to a variable nameR=numberR="literal"(R)(literal)You may assign both a variable name and a number to a variable location, and use either the variable locationdesignation or the variable name to recall the number.

<strong>ASAP</strong> | Kernel Capabilities Overview | 447TipThe variable name may be used as a literal assignment, without a numerical value, to a variable location. The variablelocation designation may then be used to access the literal.

<strong>ASAP</strong> | Quick <strong>Reference</strong> <strong>Guide</strong> | 448Quick <strong>Reference</strong> <strong>Guide</strong>The Quick <strong>Reference</strong> <strong>Guide</strong> is a group of topics that summarizes key commands and user interface locations.The topics are not inclusive of all <strong>ASAP</strong> commands.<strong>ASAP</strong> Syntax - Quick <strong>Reference</strong>This topic provides a reference for commonly used <strong>ASAP</strong> syntax.!! Comment out everything on the line‘label’A=numberA=“literal”(A)Assign literal to database entry (MEDIA; 1.5 ‘GLASS’)Assign number to internal or external variablesAssign literal to internal variableRecall number from internal or external variableA” Recall literal from internal variable(literal)Recall number from literal1 2 3… Absolute database referencing0.1 0.2 … Relative database referencingMEDIA-MEDCommand abbreviations are allowed but should beunique: use four-letter minimumOptical System Model - Quick <strong>Reference</strong>Information in this topic can be applied to building an optical system model, and is based on starting a new Builderline, or entering command syntax in the Command Input window.Type Definition Menu FormatUNITS system units Builder > Units, or(UNITS MM ‘LUMENS’)Builder window pop-upmenu, System> Setup >UnitsWAVE wavelength units Builder main menu>Wavelengths, orBuilder window pop-upmenu, System> Setup>Units(WAVELENGTH…UM)Keywordsummary of databaseentriesCommand Modifiers apply to each entity Builder window pop-upmenu:Geometry>

<strong>ASAP</strong> | Quick <strong>Reference</strong> <strong>Guide</strong> | 449Edge ModifiersSurface ModifiersLens Modifiers andObject Control>Object ModifiersOptical PropertiesWAVE bandwidth (WAVE 0.5 0.6 0.7…)MEDIA indices (MEDIA; 1.5 1.6 1.7… ‘GLASS’)COATcoating propertyCommand Input only (d in fractionalwaves)(COAT; r t r’ t’ r” t” …’TRANS’)(COATING LAYERS d m d’ m’ …)(COATING LAYERS wref, d m d’m’ …GeometrySURFACEEDGELENSentity type keyword followed by command andmodifiersBuilder window pop-up menu:Geometry>Edge, Surface, or Lens and ModifiersSURFACEOPTICAL Z 0 -10 -1 ELLIPSE 2ASYM 1 0ObjectsOBJECTINTERFACEBOUNDSobject (the object is ray traced):OBJECT; 0.1 ‘LENS_SURF_1assign specular properties to object:INTERFACE COAT +TRANS AIR GLASS +=transmitonly, -=reflect only, no sign bothuse surface and edge entities to bound object:BOUNDS -0.1 0.2 ….Verifying Optical System Model - Quick <strong>Reference</strong>This topic provides a list of commonly used commands for verifying an optical system model.

<strong>ASAP</strong> | Quick <strong>Reference</strong> <strong>Guide</strong> | 450Numerical VerificationSHOWPRINTNUMBER Ndisplay current <strong>ASAP</strong> settings such as WINDOW,PIXELS, XMEMORYprint database informationdisplay database numbers and namesGraphical VerificationWINDOWplot window (<strong>ASAP</strong> autoscales if no values):WINDOW Y -5 5 Z -10 10PIXELSprofile resolution (does not affect PLOT FACETS):PIXEL 51PLOT FACETS parametric plot: PLOT FACETS 4 4PROFILE ray trace plot of system geometry: PROFILE 0 0 -10$VIEW3D Viewer (views contents of vector file - use $IOVECTOR REWIND to rewind)REPLOT replot contents of vector file (shift+left mouse key -curser coordinate; shift+right-click - object numbers)Source Models - Quick <strong>Reference</strong>This topic provides a list of commonly used commands for verifying an optical system model.<strong>Inc</strong>oherent/Coherent Point SourceXMEMORYSPECTRUMSet virtual.pgs file to full: XMEMORY FULLSpectrally weight sources: SPECTRUM VISUALPhysical PropertiesBEAMSBEAMS COHERENT DIFFWAVE Wavelength for monochromatic source WAVE 0.5PARABASAL Parabasal rays (coherent sources only): PARABASAL 4or 8WIDTHSParabasal ray modifier (coherent sources only): WIDTH1.6POLARIZ Polarization ray trace: POLARIZ X 1 0USERAPODFlux weighting (spatial/angular): USERAPOD POS/DIRSpatial PropertiesGRID2d grid coordinates: GRID POLAR …

<strong>ASAP</strong> | Quick <strong>Reference</strong> <strong>Guide</strong> | 451Angular PropertiesSOURCE Ray directions: SOURCE DIR 0 0 1Source ModifiersFLUXAPODIZESet absolute flux; flux weighting is different forcoherent/incoherent rays:a=0, b=new flux/old flux-from STATS; FLUX 0100/63.5Apodize rays before or after ray trace (less restrictivethan USERAPOD)<strong>Inc</strong>oherent Extended SourceXMEMORYSEEDSPECTRUMSet virtual.pgs file to minRandom number generator seed: SEED 1 QUASISpectrally weight sources: SPECTRUM VISUALPhysical PropertiesWAVE Wavelength for monochromatic source: WAVE 0.5USERAPODSource flux weighting (spatial/angular): USERAPODPOS/DIR; USERAPOD ANGLESSpatial/Angular PropertiesEMITTINGExtended source emitting typeSource ModifiersFLUXAPODIZESet absolute flux: a=0, b=new flux/old flux-fromSTATS; FLUX 0 100/63.5Apodize rays before or after ray trace (less restrictivethan USERAPOD)Verifying Source Model - Quick <strong>Reference</strong>Radiometric:Photometric UnitsMost CommomUnits<strong>ASAP</strong> CommandsPower Φ Watts(W):Lumens(L) STATS /POS/DIR; LISTIntensity:Luminous IntensityLI= W/sr:L/sr 1) WINDOW; PIXEL;SPOTS DIR ATT 0;DISPLAY; ANGLEdisplay commands

<strong>ASAP</strong> | Quick <strong>Reference</strong> <strong>Guide</strong> | 452(computation is in directioncosine space)2) RADIANT; $IOVECTOR REWINDDISPLAY; AVE; MESH;$VIEW (computation is inangle space)Irradiance:IlluminanceE,M= W/m²:L/m² WINDOW; PIXEL;SPOTS POS ATTRI 0(incoherent) orSPREAD NORM(coherent/incoherent)DISPLAY; displaycommandsRadiance:LuminanceL=W/m²sr:L/m²sr1. -WINDOW;PIXEL (pixel5)RADIANT…..AREA(angle res=1); DISPLAY;display commandsComplex FieldComponentsWINDOW; PIXEL;FIELD…;DISPLAY 29…Geometric Wavefront FOCUS MOVE r;WINDOW; PIXEL;OPDMAP; DISPLAYVerification CommandsCommandSTATS/LISTPreviewFOCUSSPOTSSPREADFIELDRADIANTOPDMAPDISPLAY<strong>ASAP</strong> MenuAnalysis> Calculate FluxPreview (when Builder is active and for SPOTPOSITION only)Analysis> Focus RaysAnalysis> Calculate Flux DistributionAnalysis> Calculate Field Energy DistributionAnalysis> Analyze Beams> Calculate Field PropertiesAnalysis> Radiant> <strong>Inc</strong>oherent Radiant CalculationAnalysis> Make OPD MapDisplay> File, Display> Graphics, Display> Processing

<strong>ASAP</strong> | Quick <strong>Reference</strong> <strong>Guide</strong> | 453Ray Tracing and Analysis - Quick <strong>Reference</strong>This topic provides a list of commonly used commands for ray tracing and analysis.Ray TracingFRESNEL AVESPLITTRACEMust be turned on before ray trace for angularlydependent reflection and transmission calculation:RETURN; FRESNEL AVEControls ray splitting (SPLIT 2 is usually good enoughfor most ghost image analysis:RETURN; SPLIT 2Trace rays (rays may be stepped through objectintersections. Remember that tracing rays is like taking apicture - to trace the rays again, you must run the sourcemodel again:TRACE or …TRACE PLOT as in PRO OVER; TRACEPLOTIsolate Ray DataCONSIDERSELECTIsolate ray data on object(s) of interest: CONSIDERONLY DETECTORIsolate ray data by ray properties: SELECT ONLYSOURCE 1AnalysisSame as Verification CommandsMiscellaneous Useful Commands - Quick <strong>Reference</strong>This topic provides a list of commonly used commands for re-initializing system databases and the virtual.pgs file, aswell as for restoring an <strong>ASAP</strong> session.SYSTEM NEWRAYS 0SYS FROM RAYSReinitialize system databasesReinitialize virtual.pgs fileThese sets of commands restore a properly exited <strong>ASAP</strong>session (enter in Command Input window)Macro Formatting - Quick <strong>Reference</strong>Macro format for both library (filename.LIB) and on-the-fly macro definitions: use the $IO LIBRARY filename toassociate that macro library with an <strong>ASAP</strong> session.n is the number of prompts following the macro : prompt 1 corresponds to macro argument #1, macro prompt 2corresponds to macro argument #2.

<strong>ASAP</strong> | Quick <strong>Reference</strong> <strong>Guide</strong> | 454$macroname echoes contents of macro.&macroname does not echo contents of macro.macroname { n::}n promptsSYSRAY { 1RAYS 0; EMITTING DISK Z 0 2@1 #1}ENTER NUMBER OF RAYS>

<strong>ASAP</strong> | Building Your System | 455Building Your System<strong>ASAP</strong> commands can be grouped by function. The functional categories are in the approximate order that you wouldfollow in a typical workflow to build your system.Define/Modify Entities or Single Entity ObjectsDefine/Modify Curvedge EntitiesDefine/Modify Surfunc EntitiesDefine/Modify Lens EntitiesCreate/Modify Media, Coatings, and Scatter ModelsCreate/Modify objectsSetup Plots and Verify SystemStandard Plot OptionsSetup Beam CreationCreate Rays/BeamsModify Ray/Beam DataSetup TraceTrace Ray/BeamsAnalyze Ray/Beam DataModify or use Internal Ray/Beam Data as InputCalculate Diffraction/Propagation EffectsDisplay/Modify Data DistributionsSave or Recover System Data and Control ExecutionYou can define your own commands via the macro input facility. By default, <strong>ASAP</strong> first checks your input keywordagainst the primary command list. If it does not find a match, it searches the current macros and library file (if itexists).If a match is found, the macro is expanded in the normal way, except that the $ or & prefix on the macro name is notneeded.The command line does not echo the internal macro lines. These new commands are therefore indistinguishable fromnormal program commands. This capability does not alter the normal macro expansion when the macro name prefix ispresent. This means that a macro can still be run and echoed even if its name conflicts with a primary command.Achieving Optimal Performance in <strong>ASAP</strong>When determining your computer requirements, BRO encourages you to select an operating system that supportsoptimal performance for <strong>ASAP</strong>, and uses processor resources intensively for its computation, analysis, and graphicaloutput.In particular, if you are running <strong>ASAP</strong> on Windows 7 operating systems with 64-bit versions, you can achieveoptimal performance from <strong>ASAP</strong> by adding as much memory as your budget allows. These operating systemsautomatically cache the virtual.pgs file in RAM up to the available amount of RAM memory. The virtual.pgs filecontains the rays used in the simulation. This is the file that <strong>ASAP</strong> uses to read and write rays during ray tracing, andit accesses this file for other analyses requiring ray data.As a general rule, each ray of an incoherent extended source uses approximately 64 bytes of memory. If you knowthe number of rays in your source, you can use this simple relationship to estimate the size of the virtual.pgs file. Forexample, if you create 70 million rays, <strong>ASAP</strong> uses approximately 4.5 GB of available memory. If your initial sourcesize exceeds the available memory, <strong>ASAP</strong> uses the hard disk space, which is considerably slower and consequentlyaffects certain performances. Similarly, some simulations such as deterministic stray light analyses create rays andadd to the size of the virtual.pgs file.

<strong>ASAP</strong> | Building Your System | 456The Windows operating system in 32-bit versions limits the memory available to 2 GB, regardless of the totalinstalled RAM. The operating system also requires memory of its own. A system with 2 GB of RAM typically canmake, at most, slightly over 1 GB of RAM available for ray data, before forcing <strong>ASAP</strong> to switch to a virtual.pgs fileon disk.For faster speed, you may want to consider using SSD (solid-state drive) disks, regardless of the Windows operatingsystem, instead of traditional magnetic disks such as hard disk drives (HDDs). If <strong>ASAP</strong> runs out of available systemmemory, it uses disk storage. Therefore, <strong>ASAP</strong> performance improves with the speed of the disk drive systems.Setting the Working DirectoryThe Working Directory in <strong>ASAP</strong> is the location where files are stored when you perform tasks such as runningscripts or translating files. This topic describes the default locations of this directory in Windows XP and Windows7 systems, which are different. Default settings are the recommended locations. The topic also describes how to set auser-designated location.BRO recommends that you use the default settings for the Working Directory. Do not use a shared network drivelocation.The default settings differ in Windows XP and Windows 7 systems. In Windows XP systems, alldirectories are writable, and the default location of the <strong>ASAP</strong> Working Directory is C:\Program Files\<strong>ASAP</strong>xxxxVxRx\Projects, where xxxxVxRx indicates the <strong>ASAP</strong> version you are using; for example,<strong>ASAP</strong>2012V1R1. In Windows 7 systems, security restrictions limit the location of writable files, and the WorkingDirectory path that is writable in Windows XP is not writable in Windows 7. For this reason, the default locationof the Working Directory in Windows 7 is C:\Users\username\AppData\Local\<strong>Breault</strong> <strong>Research</strong><strong>Organization</strong>\<strong>ASAP</strong>xxxx.x\Projects, where <strong>ASAP</strong>xxxx.x indicates the <strong>ASAP</strong> version you are using; forexample, 1202.1, where 12=year, 02=version, and .1 = release number.To set the Working Directory to a different location, the location must be writable. Follow these steps:1. Click File> Set Working Directory in <strong>ASAP</strong>.2. In the Windows dialog box, select the folder to write the files, and click OK. Note: If you select a non-writablelocation, unexpected behavior may result.Assuming that the location of the Working Directory that you selected is writable, it is set until you change it.Building the GeometryAs you build optical system models, <strong>ASAP</strong> creates and adds to optical property and system geometry databases.The databases have additional commands for direct data entry and commands called modifiers that allow you to alterthe databases. You then associate data from these databases to an object for ray tracing.Your system models are typically created either in <strong>ASAP</strong> with the Builder, the <strong>ASAP</strong> Editor, or with your computersystem editor, and then opened in <strong>ASAP</strong>.Define/Modify Entities or Single Entity ObjectsThis topic lists commands that are used when defining or modifying entities or single entity objects.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.UPDATEENTITIES, OBJECTSControl entity updating in storageStart streamlined entity/object input

<strong>ASAP</strong> | Building Your System | 457Define/Modify Curve/Edge EntitiesThis topic lists commands that are used when defining or modifying curve/edge entities.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.CURVES/EDGESPOINTSLINE, DASHEDELLIPSERECTANGLEOVALROUNDEDRACETRACKCHARACTERARCCONICSAWTOOTHHELIXBEZIERSPLINEUSERCURVCOMPOSITEREPEATSAGASCALEBegin defining curvedge(s)Enter line/arc/controlpoints directlyEqually divided straightlineElliptical (circular)polygonRectangular (square)Something between ellipseand rectangleRectangle with crudelyrounded cornersRectangle with preciselyrounded cornersEdge patterned after acharacterPortion or all of a circleQuadratic segment givenconic coefficientsShape and number of teethGeneral helical (coiled)curveExplicit polynomial assame order BezierCurvature (G2) continuouscubic segmentsParametric curve or surfaceusing $FCNCombine set of previousedges into oneRepeat a previous edgedefinitionSag the edgeNon-linear asymmetricscaling

<strong>ASAP</strong> | Building Your System | 458ALTER X,Y,Z,QSMOOTHCOARSENINVERTSWEEP POS/DIR/AXIS/OFFIMAGEPATCHESUVSPACEEXTENDMATRIX ; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQAlter specific edge point(s)dataSmooth a piecewise linearcurveOpposite of SMOOTHReverse curve's parametricdirectionSweep curve into a surfaceImage curve through aspecified lensPoints represent Beziersurface patchesCurve in parametric spaceof an objectLinearly extend one or bothends.Linear transformation ofedgeDefine/Modify Surface/Function EntitiesThis topic lists commands that are used when defining or modifying surface/function entities.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.SURFACES/FUNCTIONSHORNTUBEOPTICALBICONICTORUSREVOLUTION ,FITAXICONICCARTOVALBegin defining surfacefunction(s)Horn given profilesTube-like surface (cone,cylinder)Classic rotationallysymmetric opticSurface with two distinctconic profilesTorus (doughnut)Rotated 2D curveRotated conic curve withfociCartesian oval

<strong>ASAP</strong> | Building Your System | 459CONDUITSUPERCONICZERNIKESAMPLEDGENERAL/COEFFICIENTS,EXPLICITPLANEELLIPSOIDFITTEDUSERFUNCUSERSAGCORNERROOFREPEATASYMFCNFMAPMULTIPLEARRAY EXPON,BOUNDS/SEARCH/RANTEST OFF/POINT/DIRECTION/AXISBENDLOCALRENORMCircle swept along planarexplicit cubicSpecial asphere used inoptical designDistort an axiallysymmetric surfaceExplicit Zernikepolynomial surfaceExplicit surfaceinterpolated from samplesEnter surface coefficientsdirectlyPlanar surfaceOrthogonal ellipsoid(sphere)Least squares fit to a set ofpointsUser-programmablefunctionUser-programmable radialor toric profileAxis-aligned corner of acubeTwo rectangles "hinged" atcommon sideRepeat a previous surfacedefinitionWrap macro functionaround surfuncOutput a surface functionmapExpand surface intomultiple sheetsReplicate single patch intospatial arraySet test for particularbranchBend surface in givendirectionLocalize surface in a "box"Renormalize surfacecoefficients

<strong>ASAP</strong> | Building Your System | 460SOLIDPARAMETERIZEALTEREXPLICITMATRIX; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQBounding volume formedwith local boxSet local axis for meshingsurfaceAlter specific polynomialcoefficientsConvert to explicit formLinear transformation ofsurfaceDefine/Modify Lens EntitiesThis topic lists commands that are used when defining or modifying lens entities.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.LENSESSEQUENCE, CURV/RADIMIRRORSINGLET FL/CV/RD,APLANATMANGIN FL/CV/RDDOMEDOUBLETTELESCOPERIGHTPENTAWEDGEAFOCALCOMPOSITEPERFECTIDEALBegin defining lensentity(s)Arbitrary set of conicoidsurfaceSingle reflecting surfaceTwo refractive surface lensSecond surface mirrorRefractive with one side ahemisphereCemented (achromaticdoublet)1 or 2 mirror telescope andcorrectorRight-angle prismPenta prismWedge of glassAfocal beam expanderCombine set of previouslenses into oneFor object at infinity butrealisticSpecify matrices of anideal lens

<strong>ASAP</strong> | Building Your System | 461IMPORTREPEATALTER X, Y, Z, U, V, W,H, C/R, K, O, MIMAGERESTRICT FORWARD/BACKWARD/OFF lensImport a lens design(ZEMAX) fileDuplicate a previous lensAlter specific lensconicoid(s) dataImage a global pointthrough lensDisplay aberrations ofcentered lensABERRATIONS ,LIST,PLOTDisplay aberrations ofcentered lensVARY, TH, CV, CC, CP,AS, BN, GLMINIMIZE, DIST, TLEN,GLTHANALYZESTOREMATRIX; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQDeclare variables foroptimizing lensMinimize RMS spotsubject to constraintsChange 1st-orderconditions, re-evaluateStore design in <strong>ASAP</strong>,CODE V, or ZEMAXformatsLinear transformation oflensCreate/Modify Media, Coatings, Scatter ModelsThis topic lists commands that are used when creating or modifying media, coatings, and scatter models.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.UNITSWAVELENGTH, UNITSMEDIAMODELS, PLOTABSORB, GRIN, CRYSTAL,SCAT/USER, ACTIVBegin defining scatter modelsLAMBERTIANHARVEYPOLYNOMIAL/TRINOM/BINOM,FITSet system geometry length unitsSet MEDIA and COATINGwavelengthsBegin defining media (glasses)Indices, absorption, gradient, andbirefringenceSimple constantPolished (smooth) surfaceGeneral polynomial with data fitting

<strong>ASAP</strong> | Building Your System | 462NONLINEARCOATINGS PROPERTIES /LAYERS / MODELSABGBICKCORRELATIONMEDIA BIAXIALVANES, EDGESUSERBSDFPARTICLES/VOLUME, MIEVCAVITYBSDFDATA / RAW DATARMSPHYSICALSUMVane structureUser-programmableRandom scattering centers or smallspheresRough (random v-cavities) surfaceInterpolate from entered valuesEstimate scatter from surfacestatisticsComprehensive physical reflectivescatterSum of other modelsBegin defining optical coatingsCreates an isotropic ABg (linear shiftinvariant) scatter model.Creates a birefringent coating.Creates an isotropic K-Correlationscatter model.Creates a biaxial medium descriptionoptionally used by BICCreate/Modify ObjectsThis topic lists commands that are used when creating or modifying objects.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.BRANCHOBJECTSREDEFINE SURF/NORM,THICK, COLORDEFORM, AXISBOUNDS/RBOUNDS,MULTIPLE,POINTLIMITS AXIS/REPEAT/STATS/EXPANDFACETSSet position in object namehierarchyBegin defining objectsRedefine basic optionsAdd small userprogrammabledeformationComplex boundingsurfaces, curves, volumesSimple orthogonal limitingboxSet subdivision of patchesinto facets

<strong>ASAP</strong> | Building Your System | 463GROUPEXPLODECPEGUMJONESLCCMUELLERPOLARIZ RANDOMPRINT (PolarizationModels)RPMINTERFACE COATING,DIFFRACTROUGHNESS, RANDOMSCATTER MODEL/RMS/BSDF, RANDOMSPLITLEVELFRESNELHALTMATRIX; ROTATE;SHIFT; SCALE; SKEW;PLACE; ALIGN; XEQMATRIX; ROTATE;SHIFT, SCALE; SKEW;PLACE; ALIGN; XEQTOWARDSLinear transformation ofentire objectAssign optical properties toobjectAffect specular by surfaceroughnessAssign scatteringcharacteristicsPreferential randomscatteringSpecifies specula ray/beamsplittingSpecifies scattered ray/beam levelFlux variation withincidence angleSets conditions for haltinga traceTemporary collection ofobjectsLinear transformation ofentire groupCreate separate objectsfrom lens partsDefines a compoundpolarization device.Define a general uniaxialbirefringent media deviceDefines a Jones matrixelement polarization devicedefinitionDefines a liquid crystal celllayer device modelCreates a Mueller matrixelementRandomizes thepolarization state vector ofthe raysPrints defined surfacepolarization modifiersDefines a realistic polarizermodel

<strong>ASAP</strong> | Building Your System | 464RRMDefines a realistic retardermodelObject CreationThis topic lists commands that are used in object creation.MICROSTRUCTURECreates a replicated microstructurescattering geometry/objectBuilding the SourceA grid of rays with assigned directions or a collection of rays generated by an EMITTING command is referred to asa source.Rays are created on a 2D planar grid (GRID or RAYSET commands and EMITTING DISK/RECT command) or 3Dvolume in space. These rays may be rotated, shifted, or otherwise transformed for a given application.Rays created with the GRID or RAYSET commands cannot be traced until a direction is assigned to each ray; use theSOURCE command for this activity.Unique Properties of Rays and Sources• Each source is independent.• Each source can have either one wavelength or no wavelength assigned to it. Polychromatic sources in <strong>ASAP</strong> areactually superpositions of individual monochromatic sources.• Every ray in a source is associated with an object. Untraced are referenced as object 0.• An object can be isolated by using the CONSIDER command.• At the conclusion of tracing, each ray in a source is again associated with a particular object.TipsIf a ray encounters a totally absorbing object, it remains there.If a ray is redirected by an object but cannot find another object with which to intersect, it remains on that object.If the flux of a ray drops below thresholds set by the HALT and CUTOFF commands, the ray remains on thecurrent object.• Sources can be traced only once. Generally, it is best to store the source construction commands in a separate fileand read them into <strong>ASAP</strong> as needed.• <strong>ASAP</strong> calculates the absolute phase of every ray during the ray trace.• Use the Builder to create sources.Create Rays/BeamsThis topic lists commands that are used when creating rays or beams.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.RAYSETGRID RECT/POLAR/ELLIP/OBJECT/HEX/WIN/DATBegin defining a table of rays/beamsDefine a spatial grid of rays/beams

<strong>ASAP</strong> | Building Your System | 465SOURCE POSIT/DIREC/FOCUS/LINE/WAVEEMITTINGGAUSSIANDECOMPOSE POSITION/DIRECTIONSOURCE POLYCHROMATICPLOT POLARIZATIONPOLARIZ K (<strong>Reference</strong> RayDirection)POLARIZ (Polarization Vector)POLARIZ TREF (Transverse<strong>Reference</strong> Direction)SOURCE POLYCHROMATICEMIT DISK/RECTEMIT CONE PYRAMID/BOX/SPHEROIDEMIT FILAMENT/HELIXEMIT RAYSEMIT IESEMIT ENTITY/OBJECTEMIT DATASpecify source(s) for the rays/beamsComposite of random emittersSimulate a random emitting surfaceSimulate a random emitting volumeSimulate a random emitting curve(wire)Arbitrary collection of raysEmitter specified by IES file dataRandom emission from definedsurface(s)Emit according to distribution datafileRays for coherent astigmaticGaussian modelDecompose an existing coherentfieldCreates a polychromatic sourcePlots polarization state ellipsesSets the direction of the polarizationreference raySets the polarization vector in a raylocal polarization coordinate systemSets the polarization coordinatesystem's transverse referencedirectiorCreates a polychromatic sourceVerifying the System and SourcesUsing <strong>ASAP</strong>, you verify the system and sources after building the geometry and sources.The key to creating sophisticated graphics in <strong>ASAP</strong> is to understand the relationship between the various types ofgraphics commands and the data itself.<strong>ASAP</strong> has a complete 2D and 3D graphics capability that includes overlays, oblique views, annotation, staticand dynamic rendering, zoom in/out, interactive point-and-shoot ray tracing, and many other features. Graphicscommands are divided into two broad categories:1. Set defaults, operating status, options (PIXEL, WINDOW, OBLIQUE, and others.)2. Create graphical output (SPOTS, OPDMAP and others)Setup Plots and Verify SystemThis topic lists commands that are used when setting up plots and verifying the system.• A slash between entries indicates that only one of the entries is allowed at a time.

<strong>ASAP</strong> | Building Your System | 466• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.TITLEPIXELS, ON/OFF, FILLWINDOWOBLIQUEVIEW, CENTER, EYE, DOLLY, ZOOM, ORBITPRINT SURF/EDGE/LENS/COAT/MED/OBJSPRINT SURF/EDGE/LENS/COAT/MED/OBJQPRINT SURF/EDGE/LENS/COAT/MED/OBJDIMENSIONSNUMBERS, NAMES/SUMMARYPROFILES NOOPTIM,PLOTREPLOT, OPTIM, NORAYSDRAWING, DIMENSIONS, NORAYSVUFACETS, LISTCONSIDERARROWSSEGMENTSSHOW, ALLCOLORSLIGHTSRENDER, DEPTH, RAYS, MODELMAP, DEPTH, SLOPESTREE, ENTITIESSpecify user ID and/or default titleSampling number and aspectDefine 2D graphics window on 3D dataOblique (nonorthographic) viewsPerspective viewsFull display of system informationShorter display of system informationShortest display of system informationShow dimensions of main arraysList currently used entity numbersDraw system profiles (slices)Plot geometry and/or ray dataReplot all 3D vector graphicsDraw four views of 3D vector graphicsFacets and views current objectsLimit current set of objectsSet rescaling of arrows on plotsNumber of segments per arcDisplay current command settingsSet colors by object's interfaceSpecify light sources for renderRender current object surfacesMap current object surfacesDisplay object name hierarchyStandard Plot OptionsThis topic lists command arguments that are used when setting up standard plot options.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together....CLIP...OVERLAY...COLORSSpecifies limits boxes for clipping raysPlaces next plot on topOverrides normal colors

<strong>ASAP</strong> | Building Your System | 467...TEXT…PIXELS...XY[Z] and Other Plot Window OverridesAnnotates plot with 2-D or 3-D textTemporarily overrides number of PIXELSTemporarily overrides current WINDOWSetup Beam CreationThis topic lists commands that are used when setting up beam creation.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.PARABASAL ,CLIP Controls parabasal ray calculationsWIDTHS, EDGE Sets relative beam width factorsWAVELENGTH Set operating wavelengthCLIP POS/DIRBOUNDS/RBOUNDS, MULTIPLE,POINTUSERAPOD POS/DIR/ANG/BOTH/OFFClip rays during creation and forPOS:Complex boundingsurfaces,curves,volumesUser-programmable apodizationPOLARIZ Set polarization direction and valuesXMEMORY FULL/NORM/MIN Controls extended ray/beam pagingBEAMS INCOH/COHER/GEOM/DIFF, SHAPESPECTRUM VIS/SCO/THERM/PHOT/FCN/OFFIMMERSEPOLARIZSets future beam characteristicsSets spectral weighting for futurebeamsSets starting medium for futurebeamsSets the polarization properties forfuture ray creationModify Ray/Beam DataThis topic lists commands that are used to modify ray/ beam data.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.SELECT SOURCE/OBJECTSUBSET ,RESETFLUXSelect ray group for future operationsCreate subset of current rays/beamsAssign total flux (power) in rays/beams

<strong>ASAP</strong> | Building Your System | 468SHAPEREVERSEMOVE BY/TO, POINT/PLANE/SPHERE/FOCIBILATERALIMAGEAPODIZE POS/DIR/ANG/BOTHMATRIX;ROTATE;SHIFT;SCALE;SKEW;PLACE;ALIGN;XEQSpecify shape and coherence of beamsReverse current ray/beam directionsMove to new positions on rays/beamsFlip ray/beam data about a planeImage ray points through a specified lensUser-programmable apodizationLinear transformation of ray dataTracing the Rays OverviewRay tracing is probably the most basic operation in <strong>ASAP</strong> since all information regarding system performance isobtained with it.In <strong>ASAP</strong>, rays are points in space that propagate from object to object until they are absorbed or there are no otherobjects to intersect.Rays start on object zero, a fictitious object. At the end of a ray trace, the rays are on the last object that theyintersected.Rays are traced only once, and new rays must be defined if a retrace is desired. They are traced nonsequentially,where rays intersect objects in the physically correct order, regardless of the order the objects are entered into theprogram.Preparation StepsRay tracing can involve several preparation steps, depending upon the type of analysis to be done, beamcharacteristics, and the complexity of the system geometry. Most analyses require these steps:• Initializing settings used during ray generation (WAVELENGTH, PARABASAL, POLARIZ and others)• Ray generation (GRID, SOURCE, EMITTING)• Post-ray generation modifications (FLUX, SHAPE and others)• Ray tracing settings (SPLIT, LEVEL, AXIS, FRESNEL and others)• Ray tracing (RAY or TRACE)During ray tracing, rays follow physically realizable trajectories unless overridden by the SEARCH command. Thismeans that rays intersect objects regardless of the order in which the objects were entered, and that rays intersectobjects as many times as physically necessary.Completing a Ray TraceTracing a ray is completed when the flux of the ray has dropped below a certain threshold (set absolutely orrelatively), or the ray has:• intersected an absorbing object• intersected an object, but cannot find another object along its trajectory• encountered too many objects• encountered the same object too many times• encountered a total internal reflection condition but SPLIT has not been set• begun to propagate in an undesirable direction or the ray is not ALLOWED to propagate

<strong>ASAP</strong> | Building Your System | 469TipWhen a ray intersects an object, the object’s interface properties determine which trajectory it will follow. Also,depending upon your choice of interface properties, <strong>ASAP</strong> can split an incoming ray into transmitted, reflected,diffracted (by the grating equation), and scattered components. A single ray can potentially generate thousands ofchild rays. Energy conservation is determined by your inputs.Tracing a Group of Rays or BeamsAny number of rays or beams may be traced at one time. The procedure involves initializing the ray and beam data(coordinates, directions, and sizes) at a plane in the system, which the program designates as object zero.The commands RAYSET and GRID set the coordinates and sizes while the SOURCE command then sets the directionsand starting optical path lengths.The FLUX command initializes the energy flux per ray or beam.Actual performance of the ray/beam trace is accomplished with the TRACE command.At any time the new ray data may be analyzed using the STATS and SPOTS commands.Coherent beam data is analyzed using the SPREAD and FIELD commands.Setup TraceThis topic lists commands that are used when setting up a ray trace.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.WARNINGSAXISSEED, QUASISEARCH ALL/SEQUENTIAL/LISTALLOWED ALL/SEQUENTIAL/LISTHALTCUTOFFSAVE, file#SPLITLEVELFRESNELMISSED ARROWS/LINE/OFFACCURACY HIGH/MEDIUM/LOWVOXELS FL/AB/X/Y/Z/OFFDOPL STAIRCASE/WAVEFRONT/PHASE/OFFControls warning messagesLocal and/or cylindrical coordinatesInitializes random number seedObject intersection search patternObject intersection halt patternSets conditions for halting traceSet absolute flux and number thresholdSaves all intersection data to fileSpecifies specular ray/beam splittingSpecifies scattered ray/beam levelFlux variation with incidence angleControls missed ray plottingAccuracy of ray/surface intersectionsSetup volume energy tracking during traceControls OPL from DIFFRACTive INTERFACEsRay Tracing Data Saved by <strong>ASAP</strong>For each ray traced by <strong>ASAP</strong>, different types of data can be saved (in the virtual.pgs file), depending on theXMEMORY setting and your particular edition of <strong>ASAP</strong>. This topic lists these types of data.

<strong>ASAP</strong> | Building Your System | 470• Absolute X,Y,Z direction cosines of base ray• Average divergence angle of beam• Average height of beam centered on base ray• Beam shape factor or number of higher modes• Beam shape number (see SHAPE example command)• Components of unit polarization vector• Current facet or multiple sheets of an object• Current object at which ray/beam is located• Global X,Y,Z coordinates of base ray• Medium in which the ray/beam is located• Number of the parent ray from which this ray was split• Number of times ray/beam was split• Number of times ray/beam was scattered• Optical path length from start of base ray• Parametric coordinates of base ray positions• Relative coordinates of ith parabasal ray• Relative direction vector of ith parabasal ray• Relative moduli of polarization components• Relative modulus of fundamental beam mode• Relative phase angles of fundamental beam modes• Relative phase angles of polarization components• Source number from which ray/beam originated• The ith previous split object for ray/beam• Total flux in ray/beam• Total number of objects ray has intersected• Total number of original sources• Total number of rays/beams• Wavelength of ith source• Wavelength of ray/beamTrace Ray and BeamsThis topic lists commands that are used when performing a ray/beam trace.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.RAY, PLOT, DIR, SEARCH, GALOP, LENSTRACE, PLOT/GRA, LIST/DIR, STATS, STEPTrace a single rayTrace current set of rays/beamsAnalyzing the DataAt the conclusion of ray tracing, the rays have been acted upon by the system geometry and are ready for the nextoperation, which is usually an analysis function.Unlike most optical design programs that produce ray-tracing output, <strong>ASAP</strong> treats ray tracing as simply an operationon the ray data.The analysis commands in <strong>ASAP</strong> access the ray data stored in the file, VIRTUAL.PGS and operate on the ray dataaccordingly. In some cases, the action of the analysis command changes the ray data; for example, a MOVE command

<strong>ASAP</strong> | Building Your System | 471determines the position of best focus in three dimensions and translates the ray data along their trajectories to thiscoordinate.Alternatively, the command produces a plot of the ray coordinates within the currently defined window, and doesnot modify the ray data in any way. The action depends upon the specific command or the specific option within thecommand.Analyze Ray/Beam DataThis topic lists commands that are used when analyzing ray/beam data.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.LIST POS/DIR/RAY/SOU/INT/ELLEXTREMES POS/DIR/FLUX/LENSTATS POSITION/DIRECTIONPATHS AVE/PEAK/TOT/OBJHISTORY, PLOTSPOTS POSITION/DIRECTIONFOCUS, MODE, MOVEPLOT BEAMS, RAYS, POLARIZATIONFFAD, SPOTS, REFERENCEOPDMAP fileRADIANT, MAP/AREADUMPCOLLECTIONCHROMATICITY, CIEList specific data for all or some raysList data on extreme raysStatistics of ray/beam data by objectGrouping and listing of ray pathDisplay histories of rays in SAVE fileDistribution of current ray dataFind (and move to) best focusPlot beams, rays or polarizationFull Field Aberration (Spot) DisplayInterpolate OPDs into file for DISPLAYRadiant pattern in spherical coordinatesCurrently selected rays to binary fileEfficiency vs. aperture and cone angleColorimetry analysisModify or Use Internal Ray/Beam Data as InputThis topic lists commands that are used when modifying or using internal ray/beam data as input.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.GETPUTLoad ray data into input registersMove values in registers to storageCalculate Diffraction/Propagation EffectsThis topic lists commands that are used when calculating diffraction/propagation effects.• A slash between entries indicates that only one of the entries is allowed at a time.

<strong>ASAP</strong> | Building Your System | 472• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.IRRADIANCEVIOLATIONSPREAD DIR/POS/APROX/NOR, DOWN, CLIPFIELDSUM, DELT, ADD, MULT, COUPLE, CONTFIELDBPM, DELT, MULT, COUPLE, CONTSet irradiance definition directionControls paraxial/positivity/stability messagesSpecular/scattered energy distributionsCoherent beam summationFinite-difference beam propagationSave or Recover System Data and Control Execution• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.SAVESYSTEM NEW/TO/FROM fileRESETDOMACROS FIRST/LAST/NEVERLSQFIT ,NORM/OFF,LISTFTSIZECADEXPORT IGS/DXF/VCRRETURNEND ,OFFWrites future ray trace data to a fileRead/write system data to binary fileReinitialize all settingsTransparent macro execution controlControls SVSD fitting algorithmSets Fourier Transform sizeExport object surfaces to CAD fileReturn to previous command levelEnd execution or ignore future ENDsDisplay/Modify Data DistributionsThis topic lists commands that are used when displaying or modifying data distributions.• A slash between entries indicates that only one of the entries is allowed at a time.• Commas indicate that any combination of entries is acceptable.• A semi-colon indicates that the commands must be grouped together.• Indented commands indicate that they must follow the appropriate unindented command. The indented commandcan only be applied to commands above it in the listing.DISPLAYNORMALIZEFORMFFT, SIZERead distribution data,modify/displayNormalize by constant ormaximumSet to power or logarithmicformFourier Transform data

<strong>ASAP</strong> | Building Your System | 473ABEL, INVERSEAVERAGE, WEIGHTRADIAL, FUNC/INTEG/BOTHTRANSPOSEMODIFYCOMBINEREDUCEWRITEDMAPRANGETHRESHOLDPLOT3DISOMETRICGRAPH, APPENDCONTOUR, LOW/HIGH/TICS/VECTORDIRECTIONAL,UNWRAP, RADIANCEMESHENCLOSEDSECTIONTABLEANGLES, RADIANCEVALUESOFFSETAbel transform dataAverage data over severalpixelsRadially average about apointTranspose distributionarrayModify regions ofdistributionMultiply or add anotherdata fileReduce to a smaller subsetof dataWrite current data to <strong>ASAP</strong>files(s)Print a map of dataOverride min/max for dataplottingReset floor and/or ceilingdata valuesPlot in 3-D data plus majorprofilesIsometric plotPlot 1-D profiles of dataContour or "color" mapplotCreate polar plot of angulardistributionWrite distribution to 3Dsystem filePlot percent enclosedfunctionDisplay or transfer asection of dataDisplay a table of numericvaluesConvert direction cosinesto anglesList value(s) at actualcoordinatesShifts coordinate origin

<strong>ASAP</strong> | Building Your System | 474FOLD, FIRST/SECOND/BOTHPICTUREIESFILETEXTFILEHEADERREPLICATEAPPENDHISTOGRAMTERRAINREMOVEDATAEOFAverage data about one orboth centersProduce gray-scale pictureWrite IES file of angulardistributionCreate user-definable textfile of distributionWrite actual data inspecified formatEnd of text fileRedefine header (that is,labeling)Replicate distribution oneor more timesAppend current data togiven filePlot of data valuedistributionPeaks/valleys and FWHMstatisticsSubtract best-fitpolynomial

logo

products

Resources

Company

Terms of service
Privacy policy
Cookie policy
Cookie settings
Imprint
Change language
Made with love in Switzerland
© 2024 Yumpu.com all rights reserved

Hooray! Your file is uploaded and ready to be published.

Saved successfully!

Ooh no, something went wrong!