OpenMaXwell Reference Manual

Home  General  Menues  Dialogs  Movie Directives  Formula Interpreter  File Structures

Abbreviations    General remarks    Syntax

Available functions with 1 argument, 2 arguments, 3 arguments, 4 arguments, 6 arguments, 7 arguments, n arguments

General remarks

Purpose

The OpenMaXwell formula interpreter allows one to define simple analytic formula. These formula can be used for defining

  1. any component of the original field in any point,
  2. the Cartesian coordinates of grid points of irregular grids,
  3. conformal mapping and 3D grid transformations,
  4. basis functions for the Parameter Estimation technique (PET),
  5. processing data contained in the function array, etc.

Real and complex formula

A formula can either be complex or real, depending on its purpose within OpenMaXwell. For example, conformal mapping formula are complex, whereas 3D grid transformation formula are real.

Syntax

The syntax of the OpenMaXwell formula interpreter is very simple. A OpenMaXwell formula consists of functions, constants, parameters, variables, and abbreviations. Note that not all of the OpenMaXwell formula allow the use of abbreviations.

Not case sensitive

Note that capital letters are used in the following, but the interpreter is not case sensitive.

Blanks ignored

Blanks in a formula are ignored, but in order to keep the size of the formula small, you should not introduce too many blanks.

Functions

Each function has at least one argument and is characterized by three characters followed by brackets. Within the brackets, the arguments are separated by commas. For example, ADD(1,2,3) is a function with three constant arguments.

Number of arguments

Some functions have a fid number of arguments, other functions can have a variable number of arguments. For example, SIN has exactly one argument, whereas ADD has two or more arguments.

Wrong number of arguments

If you specify more arguments than are required for a function with a fid number of arguments, only the first arguments are used and the remaining arguments are ignored. For example, SIN(1,2,3) is equal to SIN(1). The arguments 2,3 are ignored. When you specify less arguments than are required for a function with a fid number of arguments, the missing arguments are replaced by zero values. For example, SUB(2) is equal to SUB(2,0). The missing argument is replaced by 0.

Types of arguments

Each argument of a function can be a function, a constant, a parameter, a variable, or an abbreviation.

Explicit constants

Explicit constants are complex (for complex formula only), real, or integer numbers in standard Fortran notation. When a formula is complex, all constants are converted to complex numbers. Otherwise, all constants are converted to real numbers.

Implicit constants

For some frequently used constants, OpenMaXwell provides placeholders, i.e., abbreviations of the form C1, C2, etc. The value of implicit constants depends on the purpose of the formula and is indicated in the corresponding dialogs.

Parameters

Parameters are similar to implicit constants and have the form P1, P2, etc. The value of a parameter depends not only on the purpose of the formula, but also on the current program settings. Parameters can change their value when OpenMaXwell is running. Typical parameters are the frequency, the propagation constant, the material properties in a grid point, etc. Parameter meanings are indicated in the corresponding dialogs.

Variables

Variables have the form V1, V2, etc. Variable meanings depend on the formulas purpose. Since there can be many variables in a formula, V1, V2, etc. can sometimes be replaced by strings that are more meaningful. For example, T indicates the current time, X the x coordinate of a grid point, DX+ the distance of a grid point from its neighbor in the positive x direction. EX000 represents the x component of the E field vector at the current grid point, and HX0-0 the x component of the H field vector in the neighbor of the current grid point in the negative y direction. Note that the current grid point is internally set by OpenMaXwell. It can be any point of the grid. If you have defined a 3D grid with nx, ny, nz grid lines in the three directions, OpenMaXwell will have three nested loops for computing the field in all grid points, one with kx=1…nx, one with ky=1…ny, and one with kz=1…nz. The current grid point is then characterized by the numbers kx, ky, and kz. Its x coordinate is X(kx,ky,kz). HZ0-+ is the z component of the H field in the point (kx+0,ky-1,kz+1), and so on.

Field points and components

The OpenMaXwell field components are saved in three-dimensional arrays. A field point is characterized by the three indices i,j,k of these arrays and by its Cartesian coordinates x,y,z. Therefore, the field components can be considered as functions of the indices i,j,k. For irregular grids, 1) the Cartesian coordinates x,y,z of the corresponding field points, 2) the material properties, and 3) other values that depend on the location, can also be considered as functions of the indices i,j,k. Since the field formula and the field transformation formula are evaluated for all points of the grid, one usually wishes to obtain a value at a certain position with respect to a particular position on the grid. For example, you want to obtain the x coordinate of a point's neighbor in the y direction. If i0,j0,k0 are the indices of the current point, the indices of this neighbor would be i,j,k = i0+id,j0+jd,k0+kd with id=0, jd=1, kd=0. Instead of using the indices i,j,k, it is more reasonable to use the index differences id,jd,kd as the arguments of these functions. Therefore, the OpenMaXwell formula interpreter provides functions with three arguments that return locations, field components, etc. The arguments of these functions are the index differences. For example, EPS(0,0,0) is the permittivity epsilon at the current position, whereas FHY(-1,0,0) is the y component of the H field of a points neighbor one away in the negative x direction.

Hypercube field storage

When OpenMaXwell evaluates FD operators, the arguments of the arrays that store the locations and field components can be out of range. In order to avoid undesirable crashes, the grid is assumed to have hypercube structure. i.e., the neighboring point in the x direction of the last point in x direction is set equal to the first point in x direction. If one has nx grid lines in x direction, the array index i is strictly set in the range from 1 to nx with the formula i:=modulo(i-1,nx)+1. The same is done in the y and z directions. This makes the handling of 2D grids very easy. The only thing you have to do, is set the number of grid lines in the z direction equal to 1.

Formula abbreviations

When you write complicated FD operators or field definition formula, you may have some parts of the formula occurring in more than one formula. To avoid repetition you can define formula abbreviations for these parts. The OpenMaXwell formula interpreter recognizes the symbols Q1, Q2,… as abbreviations. For all abbreviations, an appropriate formula must be defined. OpenMaXwell provides 20 of these abbreviations in the Field formula dialog.

Abbreviations of functions

The OpenMaXwell formula interpreter provides several abbreviations that are listed below.

General form CCC(…,…..)

The Functions of the OpenMaXwell formula editor have the form CCC(argument1,…), where the three characters CCC represent the function.

Not case sensitive

Note that capital letters are used in the following, but the interpreter is not case sensitive.

Blanks ignored

Blanks in a formula are ignored, but in order to keep the size of the formula small, you should avoid introducing too many blanks.

Number of arguments

Some functions have a fid number of arguments, other functions can have a variable number of arguments. For example, SIN has exactly one argument, whereas ADD has two or more arguments.

Wrong number of arguments

When you specify more arguments than are required for a function with a fid number of arguments, only the first arguments are used and the remaining arguments are ignored. For example, SIN(1,2,3) is equal to SIN(1). The arguments 2,3 are ignored.

When you specify less arguments than are required for a function with a fid number of arguments, the missing arguments are replaced by zero values. For example, SUB(2) is equal to SUB(2,0). The missing argument Is replaced by 0.

Functions with 1 argument x

ABS (|x|)    ACS (arccos(x))    ASN (arcsin(x))    ATG (arctg(x))    CNJ (conjugate-complex(x) - complex formula only)    COS (cos(x))    CSH (cosh(x))    CTG ctg(x)    EXP (e^x)    INT (integer(x)    IMA (Imag(x) - complex formula only)    INV (1/x)    LOG (ln(x)    NEG (-x)    PHI (phase(x) - complex formula only)    REA (Real(x) - complex formula only) SGN (signum(x))    SIN (sin(x))    SNH (sinh(x))    SQR (x^2)    SRT (squareroot(x))    TAN (tg(x))    THN (tgh(x))

Functions with 2 arguments x,y

 AT2 (arctg(y/x))    BIT (return 1 if the bit at position y of the integr value x is one, otherwise, return 1)   DIV (x/y)    LGA (ln(y)/ln(x))    POW (x^y)    RAN or RND (random number between x and y)    SUB (x-y)    TA1 (x)    TA2 (y)    ZHC (Hy(x) - complex formula only)   ZHI (Imag(Hy(x)))    ZHR (Real(Hy(x)))    ZIC (Iy(x) - complex formula only)   ZII (Imag(Iy(x)))    ZIR (Real(Iy(x)))    ZJC (Jy(x) - complex formula only)   ZJI (Imag(Jy(x)))    ZJR (Real(Jy(x)))    ZKC (Ky(x) - complex formula only)   ZKI (Imag(Ky(x)))    ZKR (Real(Ky(x)))   ZYC (Yy(x) - complex formula only)   ZYI (Imag(Yy(x)))    ZKR (Real(Yy(x)))

Note: H, J, Y are the Hankel functions (first kind), Bessel functions, Neumann functions and K, I the modified Hamkel and Bessel functions.

Functions with 3 arguments x, y, z:

Material properties for GFD operators (x,y,z are integer numbers that indicate the index differences to the current grid point, e.g. EPS(1,-1,0) returns the permittivity of the grid point to the right (+1 in x direction) below (-1 in y direction) the current grid point): EPS (epsilon(x,y,z))    KAP (kappa(x,y,z))    KKK (wave number k(x,y,z))    MUE (mue(x,y,z))    SIG (sigma(x,y,z))    TAU (tau(x,y,z))

Field values for GFD operators (x,y,z are integer numbers that indicate the index differences to the current grid point, e.g. FEX(1,-1,0) returns the new value of the Ex component of the grid point to the right (+1 in x direction) below (-1 in y direction) the current grid point). The first character is either F (new field value) or G (old field value, i.e., value of previous iteration step). The second character is A (vector potential), E (electric field), H (magnetic induction), or V (scalar potential). The third character indicates the cartesian component X, Y or Z. For the scalar potential, the Cartesian component must by X. The following functions are available: FAX, FAY, FAZ, FEX, FEY, FEZ, FHX, FHY, FHZ, FVX, GAX, GAY, GAZ, GEX, GEY, GEZ, GHX, GHY, GHZ, GVX.

Lpcations of grid points for GFD operators (x,y,z are integer numbers that indicate the index differences to the current grid point, e.g. LOX(1,-1,0) returns the x coordinate of the grid point to the right (+1 in x direction) below (-1 in y direction) the current grid point). The functions LOX (x coordinate), LOY (y coordinate), and LOZ (z coordinate) are available.

Functions with 4 arguments

These functions define the following three if statements and dispersive materials (described in the following for epsilon):

IF>(x,y,a,b): if(x>y) the result is a otherwise the result is b. IF<(x,y,a,b): if(x<y) the result is a otherwise the result is b. IF=(x,y,a,b): if(x=y) the result is a otherwise the result is b.

DRF(frequency,epsilonD,omegaD,gammaD),     DRO(omega,epsilonD,omegaD,gammaD),     DRW(wavelength,epsilonD,omegaD,gammaD):

Extended Drude model, returns epsilon=epsilonD-omegaD*omegaD/(omega*(omega+i*gammaD)) or similar for mue. Note that the sign of gammaD changes when the time dependence exp(j*omega*t) is used instead of exp(-i*omega*t) as in OpenMaXwell.

LMF(frequency,epsS,epsilonS,sigmaS),     LMO(omega,epsS,epsilonS,sigmaS),     LMW(wavelength,epsS,epsilonS,sigmaS):

Lossy (sigma) model, returns epsilon=epsilonS+i*sigmaS/(epsS*omega) or similar for mue. Note that the sign of sigmaS changes when the time dependence exp(j*omega*t) is used instead of exp(-i*omega*t) as in OpenMaXwell.

Functions with 6 arguments

These functions define the following dispersive materials (described in the following for epsilon):

DSF(frequency,epsS,epsilonD,omegaD,gammaD,sigmaS),     DSO(omega,epsS,epsilonD,omegaD,gammaD,sigmaS),     DSW(wavelength,epsS,epsilonD,omegaD,gammaD,sigmaS):

Extended Drude + sigma model, returns epsilon=epsilonD-omegaD*omegaD/(omega*(omega+i*gammaD))+i*sigmaS/(epsS*omega) or similar for mue.

Note that some signs may change when the time dependence exp(j*omega*t) is used instead of exp(-i*omega*t) as in OpenMaXwell.

Functions with 7 arguments

These functions define the following dispersive materials (described in the following for epsilon):

DLF(frequency,epsilonD,omegaD,gammaD,epsilonL,omegaL,gammaL),     DLO(omega,epsilonD,omegaD,gammaD,epsilonL,omegaL,gammaL),     DLW(wavelength,epsilonD,omegaD,gammaD,epsilonL,omegaL,gammaL):

Extended Drude + Lorentz model, returns epsilon=epsilonD-omegaD*omegaD/(omega*(omega+i*gammaD))+epsilonL*omegaL*omegaL/(omegaL*omegaL-omega*omega-2*i*omega*omegaL*gammaL) or similar for mue.

Note that Lorentz models are sometimes defined with slightly different formulae. For example, one might have gammaL' instead of omegaL*gammaL or omegaL'*omegaL' instead of epsilonL*omegaL*omegaL, and so on. Note also that some signs may change when the time dependence exp(j*omega*t) is used instead of exp(-i*omega*t) as in OpenMaXwell.

Functions with n arguments a1,a2,a3,...

ADD (a1+a2+...)    COM (cos(a1*a2*...))    FCO (Fourier, cosine terms only: returns the sum a2+a3*cos(a1)+a4*cos(2*a1)+...)    FOU (Fourier, returns the sum a2+a3*cos(a1)+a4*sin(a1)+a5*cos(2*a1)+a6*sin(2*a1)+...)      FSI (Fourier, sine terms only: returns the sum a2*sin(a1)+a3*sin(2*a1)+...)     MAX (returns the bigges argument value)    MIN (returns the smallest argument value)    MUL (a1*a2*...)    SIM (sin(a1*a2*...))

For real valued functions, also CIR(v,p,nue,s1,s2,...sN) is available. It computes (Sum(abs(cos(nue*Pi*v+(n-1)*Pi/N))/sn)**p)**(-1/p) with summation over n=1...N. This function is useful to obtain nice, parametrized defeormations of circular boundaries - as proposed by Ralf Vogelgesang.

Abbreviations of functions and variables

Abbreviations reduce the size of formula and improve their readability.

Location and time

The Cartesian coordinates x,y,z of the current grid point with the indices i,j,k are stored in the variables V1, V2, and V3 respectively. Alternatively the abbreviations X, Y, and Z can be used. The current time is stored in the variable V0 and this has the abbreviation T.

Time steps and Distances

The abbreviations DX+ and DX- indicate the distance of the current grid point to its neighbor in +x and -x direction respectively. DX or DX0 is the average of DX+ and DX-. DY+, DY-, DY, DY0, DZ+, DZ-, DZ, DZ0 are the corresponding abbreviations for the distances in y and z directions. Similarly, DT+, DT-, DT, DT0 denote time steps.

Field components

General form - FCccc for vector fields - Sccc for the scalar potential

OpenMaXwell works with the three vector fields E, H, A and with the scalar potential V. Any component of these fields for the current grid point and its immediate neighbors can be accessed by abbreviations of the form FCccc, where F is a character that denotes the field. C denotes the Cartesian component, and ccc denotes the relative location. For the scalar potential, the character C is missing. Since Vccc is already used to denote a variable, the abbreviation of the scalar potential V is Sccc.

Current point: ccc=000

ccc denotes the distance of the point with respect to the current point in the three directions of the grid. These directions are called x,y,z although they do not always coincide with the directions of the global Cartesian coordinate system. The corresponding indices are i,j,k. Each of these three characters ccc can be 0, +, or -.

0 indicates the current index.

+ indicates the current index +1.

- indicates the current index -1.

The first character corresponds to x or i, the second one to y or j, and the third to z or k. For example, AZ-+0 denotes the z component of the vector potential A in the point i-1,j+1,k, when the indices of the current point are i,j,k.

 

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

Last update 17.02.2014