OpenMaXwell Reference Manual

Home  General  Menues  Dialogs  Movie Directives  Formula Interpreter  File Structures

Available directives

ADApt ADD BLOw CLEar CONvert COPy DELete DRAw END EXChange EXIt GENerate GET GOTo IF> IF< IF= INCrease ITEterate LABel LOOp MMP MOVe MULtiply PROcess REAd REFlect REName ROTate RUN SET SORt SUBtract WRIte

! Comments    Argument strings     Constants    File names   Formula string    Functions array    General remarks    Movie variables    N-m strings    Object   Range strings     Syntax    String separators    Text strings    Verb

General Remarks

OpenMaXwell uses directives to generate movies and solve complex computational tasks. The directives are displayed in the Info and movie directives dialog. In the corresponding edit box, you can edit all directives. The Movie dialog allows you to read directives from Movie files, to save them on Movie files, to check a single directive, and to run a single directive.

One directive per text line

OpenMaXwell directives consist of ASCII text lines. On each line, there is a single directive.

Two nested loops (obsolete since 2015)

Until 2015, OpenMaXwell used two nested loops for generating movies. Before each of the loops was started, the preprocessing directives were executed, and after each of the loops, the post-processing directives were executed. For more information see Directive files, *.DIR.

Five blocks of directives (obsolete since 2015)

Until 2015, there were five blocks of directives that were executed in the following order: 1) Preprocessing of the outer loop, 2) Preprocessing of the inner loop, 3) Inner loop ecution, 4) Post-processing of the inner loop, 5) Post-processing of the outer loop.

More complex tasks

Since 2015, the directives LOOp, END, GOTo, LABel, IF>, IF<, IF= provide rather much frexibility for compex tasks, but you might still use the directives REAd DIRective… and REAd PROject… (see below) for chaining directives contained in different directive files.

Syntax

Blanks are directive string separators

A directive consists of one or several strings. Usually, the strings are separated by blanks. Therefore, the strings cannot contain blank characters.

Exception: Pure text strings

Pure text strings can contain blanks. These strings are written within double quotes. The directive DRAw TEXt "Number of iterations =" is an example.

First string: Verb with 3 characteristic characters

All directives start with a verb characterized by three characters, with the following exceptions:

Exception: ! Comments

An exclamation mark as the first character indicates a comment, i.e., it makes the remaining characters of the directive line inactive.

Exception: ? Conditional directives

An question mark as the first character indicates a conditional directive that is only executed when the condition specified after the question mark and before a second question mark is true. A typical example is the following:

? bit(v0,1) < 1 ? del col 21

The condition is: "bit(v0,1) < 1". If it is true, the directive "del col 21" is executed, otherwise it is skipped. Note that the function bit(v0,1) returns the first bit of the variable v0 (that should be an integer). Currently, only the comparisons "<", ">", and "=" are available in conditional directives.

Exception: % Model Based Parameter Estimation (MBPE) directives

The MBPE routines allow you to efficiently compute the frequency response with a minimum of frequency points. MBPE provides efficient interpolations. In order to run MBPE, you first specify the MBPE parameters by means of SET MBPe directives. Then you start MBPE with the RUN MBPe directive. After this, you specify several % directives that tell MBPE how to compute the frequency response. This may look as follows:

set mbpe calculations 101
set mbpe error 1.0e-4
set mbpe limits -1e300 1e300
set mbpe order 10
set mbpe output 1
set mbpe overdet 1.1
set mbpe range 5e-7 15e-7 10 5e-7 15e-7 501
set mbpe var 1 2 3 ! movie variables for x, freal, fimag
run mbpe adaptive 0 0 0 0 0 0 ccav000.fun
% set wav v1
% dra win
% mmp sol
% cle all
% dra fie
% dra bou
% dra var 10 10 5 wav
% set var 2 field ezr 6.4334e-7 4.4664e-7 0 1
% set var 3 field ezi 6.4334e-7 4.4664e-7 0 1
rea fun ccav000.fun

In this example, the function file ccav000.fun will contain the frequency response of the field values EZR and EZI in the wavelength range from 500nm to 1500nm, sampled in 501 points.

Second string: Object with 3 characteristic characters

After the verb, most of the OpenMaXwell directives have an object characterized by three characters, with the following exceptions:

Exceptions: EXIt, EXIt ?

The EXIt directives require no object. All characters after EXI are ignored and can be used as comments. You may add a question mark after EXIt. In this case, a dialog will pop up as soon as the directive EXIt ? is encountered. Answer in the affirmative when you want that the execution of the directives is stopped. When you answer in the negative, the EXIt directive is ignored and the execution is continued.

Argument strings

Many directives have one or several arguments after the object. Arguments can be text strings - like the verbs and objects - or constants (real or integer).

Constants

Constants are most frequently real or integer values in scientific notation (e.g., 12, -32, 3.4, -2E5), or complex values (e.g. (0.,1.)) when a complex formula is defined.

When you want to select a certain expansion, it is not possible to know its number while writing the directive because the generate expansion command and similar commands may modiy the number of expansions and insert new expansions before the desired one. Therefore, it is sometimes desirable to select the last expansion N or - more general - the expansion N-m where N is the not yet known number of the last expansion and m is a constant. OpenMaXwell evaluates this number when you enter the string N-m, where m must be a positive integer, e.g. N-1. Note that no blanks are allowed in such a string. N-m strings may also be used for boundary and domain numbers but only for certain directives. Therefore, you best check first if the desired directive with the N-m string is performed correctly by running it once before you start the movie.

Sometimes, you wish to select several objects within a certain range, for example, the boundaries 3 up to 6. You then need to define a sequence of similar directives with the desired object numbers. In many cases, you may abbreviate this by defining a single directive with an object number of the form n-m, where n is the first number of the sequence and m is the last one, e.g. 3-6. Both n and m must be positive integers. If n is equal to 1, it may also be omitted. Note that no blanks are allowed in such range strings. Since range strings may only be used in certain directives, you best check first if the desired directive with the range string is performed correctly by running it once before you start the movie.

OpenMaXwell can also read constants from an array containing up to 1000 user-definable movie variables. Then, the constant has the form V or Vn, where n denotes an integer number in the range 0…999. Note that 996-999 is usually used for MBPE. Note also that no blank is allowed between the character V and the integer number n. V is the same as V0. Remark: The movie variables are set with commands such as "SET VARiable …", "INCrease VARiable …", etc.

OpenMaXwell can also read real or integer constants from the functions array. For example, F(7,3) denotes the array element in the row number 7 and column number 3. No spaces are allowed in this definition. For example, F(7, 3) would cause an error because spaces are used as delimiters in movie directives. The character F may be replaced by f. The numbers of the row and column may be replaced by +, -, or /. + stands for "increase by 1", - for "decrease by 1", and / for "same as before. For example, F(/,-) would be equal to F(7,2) if F(7,3) had been evaluated before F(/,-).

In the case of real values you often may use a slash in front oft the value (without any blank in between) in order to specify its inverse. For example, /3 stands for 1/3=0.333... and /V2 stands for 1/V2.

Sometimes, it is convenient to let OpenMaXwell evaluate a constant using its formula editor. For example, when you would like to enter e, you may specify EXP(1).  OpenMaXwell can correctly evaluate such a formula when the constant should have a real or complex value, whereas numerical problems and undesired results might occur when an integer constant is expected. Therefore, you best check first if the desired directive with the formula string is performed correctly by running it once before you start the movie.

Characteristic text strings

Text string arguments can be of the same form as verbs and objects. OpenMaXwell reads only the first characteristic characters of these characteristic text strings and compares them with a list of known strings. In most cases, the first three characters are characteristic, the remaining characters are ignored. In this manual, the characteristic characters are indicated by capitals. For example, in the command "DRAw WINdow", DRA and WIN are characteristic. Therefore, you could also write "DRA WIN" or DRAmatic WINner". For OpenMaXwell there is no difference between these commands.

Case sensitivity of characteristic text strings

In order to give the user more freedom, OpenMaXwell converts all characteristic text strings to lower case. I.e., the strings END, EnD, End, end, etc. are identical for OpenMaXwell.

Characteristic characters

OpenMaXwell checks only the first few, characteristic characters of characteristic text strings. All remaining characters before the next blank are ignored and can be used for improving the readability of directives. For example, the strings DEL, DELete, DELude, etc. are identical for OpenMaXwell.

Notation of characteristic text strings

In the following, upper-case characters are used to indicate the characteristic characters and lower-case characters are appended to indicate ambiguous, additional characters. Note that this notation is not used in the directive files. For example, in the default directives you find the string "Draw Field V x". This will be noted as "DRAw FIEld V X", which indicates that the verb DRAw and the object FIEld have two characteristic characters, whereas the two arguments have only one.

Variable number of characteristic characters

Sometimes, a characteristic text string can have a variable number of characteristic characters. For these cases, the number of capitals cannot indicate the number of characteristic characters. Therefore, only a single capital letter is used for the placeholder in the following descriptions. For example, for the directive DRAw FIEld, one can have the arguments 'Type' and 'Component'. 'Type' and 'Component' are placeholders for characteristic strings of variable length. 'Type' can have a single character (e.g. E, H, S, etc.) or two characters (e.g. We, Wm, etc.). To avoid undesired results, you should not append additional dummy characters to characteristic text strings of variable length.

File names

Sometimes, an argument of a directive is a file name. File names can contain the entire path to the file. The length of these strings is always variable. Moreover, these strings may not contain any blanks. Therefore, these strings are similar to characteristic strings of variable length. It is often convenient to use file names with a three digit number at the end, e.g., PROBLEM000.PRO. Note that only 3 digit numbers immeadiately before the "." are allowed and thet the file extension must have 3 characters. OpenMaXwell can maipulate the file number as follows:

For example, REAd PROject + with the file name + means "increase the current file number by one (this results in the file name PROBLEM001.PRO) and execute the directive (REAd PROblem)". Another example: WRIte AVI *, writes an avi file with the same name as the current project but the extensionAVI instead of PRO.

OpenMaXwell can append data to an open *.AVI or *.FUN file. This is done with the file name "/". To close the avi file for writing, use WRIte AVI !, i.e., use the special file name "!".

 

Responsible for this web page:  Ch. Hafner, Computational Optics Group, IEF, ETH, 8092 Zurich, Switzerland

Last update 27.10.2015