OpenMaXwell Reference Manual

AVI

Argument: Name

Meaning: Write the pixel information of the current window on the AVI movie file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: append the frame to  the current AVI file

• 0: set the number of the current filename equal to 0

• !: close the AVI file

Notes:

• Before the first AVI file of a OpenMaXwell session is written, a dialog pops up that lets you select the Video Compressor. The quality of the animation and the AVI file size depend considerably on this compressor. The list of available compressor depends on your graphics card and drivers. Some of the compressors might not work properly. Usually, good results are obtained with the Microsoft video 1 compressor.

• Any open AVI files are closed, unless Name is equal to /. To obtain a useful AVI movie, the AVI file should be opened first with a directive such as “write avi movie.avi”. Then several frames should be written with the directive “write avi /”. Finally, the AVI file should be closed with the directive “write avi !”.

 

BASis

Argument: Name

Meaning: Write the basis functions on the file Name. Note: if the current problem is of the eigenvalue type, the EET basis will be saved. Otherwise, the PET basis is saved. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

BITmap or BMP

Argument: Name

Meaning: Save the bitmap information of the current graphics window to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

BOUndary

Arguments: Name (n Name2)

Meaning: Save the boundaries to the file Name. When the arguments n Name2 are present, the locations of all matching points in the xy plane are written on an extra ASCII text file with the extension MAT. Special cases of Names (also for Name2):

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

CFIeld

Arguments: x y z a b na nb io id ii Name

Meaning: Compute the complex E and H field values on a regular grid with na by nb lines over a rectangular area of side lengths a and b and save the values to the file Name. The lower left corner with global coordinates x y z may be anywhere in space. the rectangle is parallel to the yz plane when io is equal to 1, parallel to the xz plane when io is equal to 2, parallel to the xy plane when io is equal to 3. The rectangle is assumed to be in domain id when id is positive. If the rectangle contains points in several domains, set a negative value for id. Then the domain numbers for all points will be evaluated from the boundary information of the model. You may specify an interpolation type ii when the field is already known on a grid that includes the rectangle. Sett ii=0 to suppress interpolation (recommended). The file header will have a header with the values x y z on the first line and a b na nb io on the second line. After the header, there will be a list of lines containing

id

Real(Ex) Imag(Ex) Real(Ey) Imag(Ey) Real(Ez) Imag(Ez)

Real(Hx) Imag(Hx) Real(Hy) Imag(Hy) Real(Hz) Imag(Hz)

...

for the na by nb points.

DIRective

Argument: Name

Meaning: Save the directives to the file Name. Special cases of Names:

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

DOMain

Argument: Name

Meaning: Save the domains to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

EXPansion

Argument: Name

Meaning: Save the expansions to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

FIEld

Arguments: Name (WHAt)

Meaning: Save the original field or the representation data to the file Name. When WHAt is missing, the representation data and the field values are saved. When WHAt is REPresentation, only the representation data is saved. When WHAt is VALue, only the original field values are saved. When WHAt is DERived, only the derived field values (scalar + vector components) are saved. When WHAt is VECtor, only the vector components of the derived field are saved. When WHAt is SCAlar, only the scalar part of the derived field is saved. When WHAt is any string starting with characters different form REP, VAL, DER, VEC, SCA, it is considered as an input filename. The corresponding input file must have the following structure. First line: N - number of points given in the following list (N lines); lines 2...N+1: iD x y z (domain number, x, y, z coordinates of the point in 3D space). OpenMaXwell will compute the field (complex E and H vectors) in all N field points using the current MMP expansions. It will write the corresponding data on the output file Name. When the domain number iD is negative, it will compute the domain number for each point using the boundary data available. Otherwise, it will compute the field in each point assuming that iD is the correct domain number. The output file will have N on the first line followed by 2N lines containing Re(Ex) Im(Ex) Re(Ey) Im(Ey) Re(Ez) Im(Ez) and Re(Hx) Im(Hx) Re(Hy) Im(Hy) Re(Hz) Im(Hz).

Special Names (only for output):

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

FITness

Arguments: WHAt (...)

Meaning: Write fitness values to the data exchange file OPT.xxx, where xxx is the process number. OPT.xxx is used by some optimizer software, e.g., OptPES. OPT.xxx contains the following data: number of fitness values, number of parameters, array of parameters, array of fitness values. It is simultatneously opened by OpenMaXwell and the optimizer. For this purpose, OpenMaXwell must run in the slave mode, i.e., must be called with the command "OpenMaXwell.exe yyy.PRO inf", where yyy.PRO ist the project file to be opened. Its directive file should contain the following directives:

WRIte FITness BEGin nnn - nnn is the number of fitness values to be written on nnn following directives of the form:

WRIte FITness ... - ... describes which value should be written as fitness value, e.g., PARameter n-1 1 SQUare

WRIte FITness END - this command writes all date to OPT.xxx. It should directly follow the nnn-th "WRIte FITness ..." directive. After "WRIte FITness END", all essential movie directives should have been finished, i.e., either the final "END" directive or an "EXIt" directive should follow.

Notes:

• WRIte FITness ... has the same syntax as WRIte FUNction / ..., but ... must define a single scalar (not complex!) value.

• The OPT file number xxx is determined when OpenMaXwell is launched. E.g., if the files OPT.000, OPT.001 exist already, xxx will be 002. Before you start an optimization, 1) delete all OPT.xxx files. 2) Then start OpenMaXwell N times with in slave mode using the command "OpenMaXwell.exe yyy.PRO inf". Usually, N is the number of available cores on your machine. 3) Then use the Windows Task manager to make sure that each OpenMaXwell solver runs on cores that are not heavily used by other processes: Select the Processes tab; right click each of the running OpenMaXwell processes, select "Set affinity ..." and select the CPU numbers in the dialog that pops up. 4) Check if the directives of all OpenMaXwell processes are correct. Note that when different processes are reading and writing identical files (specified in the directives of the project, i.e., in the yyy.DIR files) conflicts will occur during the optimization. Therefore, it may be neccessary to run different projects on each core. All of these projects will essentially be identical but the file names in the directives must be unique for each core.

• The number of parameters nPar, the number of fitness values nFit, and the limits of all parameters must be defined in the ASCII text file OPT.txt. Usually, nFit is equal to 1 and OpenMaXwell computes the fitness value that shall be maximized by the optimizer, but you may have nFit>1 and let the optimizer handle this.

• The number nFit in the optimization data file OPT.txt must coincide with the number of WRIte FITness ... commands (between "WRIte FITness BEGin nnn" and "WRIte FITness END") and with the number nnn in the "WRIte FITness BEGin nnn" command.

• OPT.txt contains nPar nFit on the first line, followed by nPar lines containing the upper and lower limit of each parameter. OpenMaXwell only reads the first line of OPT.txt and ignores the other lines, which are only used in the optimizer.

 

FLF

Argument: Name

Meaning: Save the field definition formula to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

FUNction

Arguments: Name (WHAt (...))

Meaning: Save current function values or the function representation data on the file Name. When WHAt is missing, the representation data and all current  function values are saved - except when Name is equal to ! (see below).  Special Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

• !: close the current function file

What (…) can be one of the following:

• ANGle n: Write the orientation angle of the expansion n to the function file.

• BOUndary n: Write the number of 2D boundaries + n to the function file.

• CLOse: Close the function file.

• CND: Write the current condition number of the rectangular MMP matrix to the function file.

• CONstant c1 (c2 …): Write the constants c1, c2,… to the function file. The maximum number of constants is 40.

• CPU (n): Write the CPU time (since the previous call of the CPU time) to the function file. If n is present and >1: write also the elapsed time to the function file. If n is present and <1: write the elapsed time instead of the CPU time to the function file.

• CXI: Write the imaginary part of CX (see periodic cell data of the Project dialog) to the function file.

• CXR: Write the real part of CX (see periodic cell data of the Project dialog) to the function file.

• CYI: Write the imaginary part of CY (see periodic cell data of the Project dialog) to the function file.

• CYR: Write the real part of CY (see periodic cell data of the Project dialog) to the function file.

• CZI: Write the imaginary part of CZ (see periodic cell data of the Project dialog) to the function file.

• CZR: Write the real part of CZ (see periodic cell data of the Project dialog) to the function file.

• DOMain n WHat: Write material properties of the domain number n to the function file. WHatspecifies what property shall be written. When the domain property is defined by a formula, the formula is evaluated and the resulting complex or real value is written on the file. WHatmay be one of the following: EC, EI, ER, SC, SI, SR, UC, UI, UR, TC, TI, TR, where the first character stands for Epsilon, Sigma, mUe, Tau and the second one for Complex (write 2 real values), Imaginary, or Real.

• EFFiciency (n m): Write the efficiency of the Rayleigh expansion number n on the function file Note that this directive makes no sense when expansion n is not a Rayleigh expansion. When the number m is given, the efficiency of the m-th parameter of expansion n is written. This is essentially the same as when you use the directive WRIte FUNction file PARameter n m SQUare. When m is missing, the sum of all efficiencies of all non-evanescent parts (orders) of expansion n is written on the function file. When both n and m are missing, the sum of all efficiencies of all Rayleigh expansions of all non-evanescent orders is written on the file. This number can be used as an error check. For a standard grating with an incident plane wave and two Rayleigh expansions (one for the transmitted and one for the reflected waves), the sum should be 1 – provided that the incident plane wave and the Rayleigh expansion are scaled correctly.

• ERRor (X Y): Write the current error on the function file. The optional attributes X and Y specify the kind of the error. When these attributes are missing, the error of the field is used. Otherwise, the error of the MMP computation is used. X may be A for "absolute" or R for "relative" and Y may be A for "average" or M for "maximum". Note that the relative MMP errors are given in percent. In MAX08A, X may also be F (average or maximum field value along the boundaries), S (average or maximum error / average field value), T (average or maximum error / maximum field value).

• ER2: Write the square root of the quadratic error of the field to the function file.

• EXPansion n: Write the number of 2D expansions + n to the function file.

• FIEld TYPE (x y z Dom n m): Write the specified field component in the point with the Cartesian (or cylindrical) coordinates x y z to the function file. Missing coordinates are set equal to zero. Dom specifies the domain number of the field point. If it is missing, it is computed from the current boundary data.

• n specifies the interpolation type for field points that are not on the grid when the derived field is written. When an original field or the complex Poynting field is written, no interpolation is used and the MMP expansion is evaluated in the point x,y,z. In this case, you may specify n and m. n denotes the expansion number to be used for the field evaluation and m is the parameter number of this expansion. Default values are n=0 and m=0, which corresponds to "all expansions" and "all parameters".

• TYPE is a string with up to 4 characters.

• The first character describes a (complex) vector v. It can be one of the following:

• A: The original vector potential A

• E: The original E field

• H: The original H field

• R: The derived field (In this case, the vector v is real!)

• S: The complex Poynting field S (original E ´ conjugate complex of original H)

• V: The original scalar potential V (in this case the y and z components of the vector v are 0)

• The second character describes how the vector v is manipulated in order to obtain a (complex) scalar s. It can be one of the following:

• F: The angular (phi) component the vector v in the xy plane

• R: The radial (r) component of the vector v in the xy plane

• X: The x component of the vector v

• Y: The y component of the vector v

• Z: The z component of the vector v

• 1: The square root of the scalar product of the vector v with its conjugate complex

• 2: The scalar product of the vector v with its conjugate complex

• The third character describes how the scalar s is manipulated. It can be one of the following:

• A: The absolute value of the scalar s

• C: Both, the real and imaginary parts of the scalar s. Warning: In this case, the movie command writes two values on the function file! Keep this in mind when you define the header data, namely the number of arguments!

• I: The imaginary part of the scalar s

• R: The real part of the scalar s

• 2: The square of the absolute value of the scalar s

• If the fourth character is equal to P, x y are considered to be the polar coordinates r and phi in the xy plane rather than the Cartesian coordinates.

• The default TYPE string is S1C, i.e., the vector v is the Poynting vector S, the scalar s is the square root of the scalar product of the vector v with its conjugate complex, and both real and imaginary parts are written. Since the fourth character P is missing by default, x y are Cartesian coordinates. Note that the default characters of the default TYPE string are also used when unknown characters are in the given string. For example, T3F would be the same as S1C.

• FREquency (PARt): Write the current frequency to the function file PARt specifies the part of the complex frequency that is used. It can be ABS, IMAginary, or REAl. If it is missing, both the real and imaginary parts are saved.

• GAMma (PARt): Write the propagation constant gamma to the function file. PARt specifies the part of the complex propagation constant that is saved. It can be ABS, IMAginary, or REAl. If it is missing, both the real and imaginary parts are saved.

• HEAder n m: Write the header to the function file. The header specifies the number of values n and the number of arguments m. If n is not known in advance, set the value to -1.

• IMA: Write the maximum integrand value that was detected during the integral evaluation to the function file.

• IMI: Write the minimum integrand value that was detected during the integral evaluation to the function file.

• INTegral: Write the value of the integral to the function file.

• IXA: Write the x coordinate of the point where the maximum integrand value that was detected during the integral evaluation to the function file.

• IXI: Write the x coordinate of the point where the minimum integrand value that was detected during the integral evaluation to the function file.

• IYA: Write the y coordinate of the point where the maximum integrand value that was detected during the integral evaluation to the function file.

• IYI: Write the y coordinate of the point where the minimum integrand value that was detected during the integral evaluation to the function file.

• IZA: Write the z coordinate of the point where the maximum integrand value that was detected during the integral evaluation to the function file.

• IZI: Write the z coordinate of the point where the minimum integrand value that was detected during the integral evaluation to the function file.

• KW0: Write the free-space wave number to the function file.

• LA0: Write the free-space wave length to the function file.

• LAM: Write the wave length of the current waveguide mode to the function file.

• LEN: Write the propagation length of the current waveguide mode to the function file.

• MAXimum: Write the maximum value of the derived field to the function file.

• MINimum: Write the minimum value of the derived field to the function file.

• MMP WHAt: Write the MMP data to the function file. WHAt specifies the data. It may be one of the following:

• AMPlitude: amplitude of MMP eigenvalue computations

• AVEr: average error on the boundaries

• CGIter: number of CG iterations that were performed

• CND: condition number of the MMP matrix (should have been computed first!)

• COLumns: number of columns of the MMP matrix

• EIGen: number of iterations of the eigenvalue search

• MATching: number of matching points

• MAXimum: maximum error on the boundaries

• RESidual (n): residual of the MMP solver (if n not present or <1) or eigenvalue search function value (n=1...9, depending on the search type)

• ROWs: number of rows of the MMP matrix

• OMEga (WHAt): Write the angular frequency omega to the function file. Note that omega is complex in general, i.e., the real and imaginary parts may be written to the file. WHAt may be one of the following: ABS (write the absolute value of omega), IMA (write the imaginary part of omega), REA (write the real part of omega). When WHAt is missing, both, the real and imaginary parts are written to the file.

• P2D n WHat: Write information on the 2D particle number n to the function file. WHat may be one of the following: AX (x coordinate of the acceleration), AY (y coordinate of the acceleration), FX (x coordinate of the force), FY (y coordinate of the force), MAss (mass), PX (x coordinate of the position), PY (y coordinate of the position), VX (x coordinate of the velocity), VY (y coordinate of the velocity).

• P3D n WHat: Write information on the 2D particle number n to the function file. WHat may be one of the following: AX (x coordinate of the acceleration), AY (y coordinate of the acceleration), AZ (z coordinate of the acceleration), FX (x coordinate of the force), FY (y coordinate of the force), FZ (z coordinate of the force), MAss (mass), PX (x coordinate of the position), PY (y coordinate of the position), PZ (z coordinate of the position), VX (x coordinate of the velocity), VY (y coordinate of the velocity), VZ (z coordinate of the velocity).

• PARameter n m (PARt nExc): Write the specified PARt of the complex parameter number m of the expansion number n on the function file. PARt can be ABSolute, ANGle, COMplex, IMAginary, REAl, or SQA. ANGle denotes the arctg(Imag/Real) in degrees and SQA denotes the square of the absolute value. When PARt  is missing or  COMplex, both, the real and imaginary parts are saved. When nExc is specified, the parameter of the corresponding excitation number will be written in case of projects with more than a single excitation (multiple right hand side problems). SPECIAL CASE: when the parameter number m is set equal to 0, the values of all parameters of expansion n will be written on the file.

• PFD n WHat: Write PFD sensor information to the function file

• PHI: Write the phase (of time-harmonic fields) to the function file

• REPresentation: Write the function representation data to the function file.

• RAYleigh n m: Write the angle (in degrees) of the Rayleigh term with expansion number n and parameter number m on the function file Note that two angles are written for 3D Rayleigh expansions, whereas a single angle is written in the 2D case.

• TEXt (String): Write the text String to the function file. If String is missing, it is set equal to an exclamation mark.

• TIMe: Write the current time to the function file.

• VALues: Write all function values the function file and close the file.

• VARiable (n): Write the variable number n to the function file. Default n=0.

• WAVelength: Write the current free space wavelength to the function file.

 

GMSh

Argument(s): Name (iB1 iB2 iD iC)

Meaning: Create 2D boundary data for the finite element mesher GMSH and write it to a *.GEO file Name. Only boundaries with numbers iB1 up to iB2, domain numbers iD (either on the left or on the right side) and color iC are used. Default values are iB1 = 1, iB2 = number of boundaries, iD = 0 (all domains), iC = 0 (all color numbers - color number 0 (white) cannot be used)

 

GRF

Argument: Name

Meaning: Save the grid definition formula to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

GRT

Argument: Name

Meaning: Save the grid transformation formula to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

INTegral

Arguments: Name (Type (….))

Meaning: Write the integral data to the integral file Name when Type is missing. Otherwise, compute the current integral of the type Type (….) and write the values of the integration to the Function file Name.

Note: any existing file data is overwritten. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

Type (….) can be one of the following:

• BOUndary (n i j k l a m):

• Integral over the boundary n. If n is missing: use current boundary. Special cases: n=0 – do for all boundaries. Use integrand component i, interpolation type j, integrand field k, maximum number of function calls l, desired accuracy a. (For details see Integral files.)

• You may specify the integral type m as the last argument. The integral type my be 0 for simple sum, 1 for GL, 2 for GK and 3 for HP integration (see  Integral dialog).

• OBJect (n iEc iHc):

• Integral over the 3D object number n. If n is missing: use current 3D object. Special case: n=0 – all 3D objects.

• If iEc is not zero, the real and imaginary parts of the original Ex, Ey, and Ez field components will be added to the output file for each integration point. If iHc is not zero, the real and imaginary parts of the original Hx, Hy, and Hz field components will be added to the output file for each integration point.

MATrix

Arguments: Name (What)

Meaning: Save the MMP matrix to the field file Name. What can be one of the following:

• Rectangular:          Save rectangular matrix

• Triangular:             Save triangular matrix

When What is missing, the triangular matrix is saved.

Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

MMP

Arguments: Name (What)

Meaning: Save the MMP data to the file Name.  What can be one of the following:

• All:                            Save all data (header + rectangular + triangular matrix)

• Error:                       Save the MMP error data to a function file

• E2d:                          Save the 2D MMP error data (also for 3D models) to a function file

• Header:                    Save the header only, ignore matrix data.

• Rectangular:          Save the header and the rectangular matrix

• Triangular:             Save the header and the triangular matrix

When What is missing, only the header is saved.

Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

OBJect

Argument: Name

Meaning: Save the 3D object data to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

OGL

Argument: Name

Meaning: Save the OpenGL window data to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

PFD

Argument: Name

Meaning: Save the PFD data to the file Name. Special cases of Names:

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

 

PROject

Argument: Name

Meaning: Save the project data to the file Name. Note: All associated data files (same file name but different file extension) will also be saved. Special cases of Names:

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0

RFIeld

Arguments: x y z a b na nb io id ii Name

Meaning: Compute the derived field (Specified in the Field dialog) on a regular grid with na by nb lines over a rectangular area of side lengths a and b and save the values to the file Name. The lower left corner with global coordinates x y z may be anywhere in space. the rectangle is parallel to the yz plane when io is equal to 1, parallel to the xz plane when io is equal to 2, parallel to the xy plane when io is equal to 3. The rectangle is assumed to be in domain id when id is positive. If the rectangle contains points in several domains, set a negative value for id. Then the domain numbers for all points will be evaluated from the boundary information of the model. You may specify an interpolation type ii when the field is already known on a grid that includes the rectangle. Sett ii=0 to suppress interpolation (recommended). The file header will have a header with the values x y z on the first line and a b na nb io on the second line. After the header, there will be a list of lines containing

id

Fx Fy Fz

...

for the na by nb points, where F is the derived field.

 

WINdow

Argument: Name

Meaning: Save the window data to the file Name. Special cases of Names:

• *: use the name of the current project and append the file extension

• +: increase the number of the current filename by one

• -: decrease the number of the current filename by one

• /: use the current filename

• 0: set the number of the current filename equal to 0