Grating projections

FDTD, MODE

grating - Script command

FDTD MODE

Returns the fraction of transmitted power to each physical grating orders for a given simulation. Results are normalized such that the sum of all the orders is equal to 1. To convert these values into fractions of the source power, multiply by the the transmission script function.

3D simulations: Data is returned in a NxMxP matrix where N,M are the number of grating orders, and P is the number of frequency points.

2D simulations: Data is returned in a NxP matrix where N is the number of grating orders, and P is the number of frequency points.

Syntax	Description
out = grating("monitorname",f, index, direction );	Returns the strength of all physical grating orders from monitorname.

Parameter		Default value	Type	Description
monitorname	required		string	name of the monitor from which far field is calculated
f	optional	1	vector	Index of the desired frequency point. This can be a single number or a vector.  Multithreaded projection to allow multiple frequency points to be calculated simultaneously was introduced in R2016b.
index	optional	value at monitor center	number	The index of the material to use for the projection.
direction	optional	direction of max power flow	number	Direction: this can be +1 or -1.

The following table summarizes how to interpret the coordinate vector properties for various monitor orientations.

Monitor orientation	Monitor surface normal	'N', 'ux', 'gratingn', 'gratingperiod1', 'gratingu1', 'gratingbloch1', correspond to	'M', 'uy', 'gratingm', 'gratingperiod2', 'gratingu2', 'gratingbloch2' correspond to
XY plane	Z	x axis	y axis
XZ plane	Y	x axis	z axis
YZ plane	X	y axis	z axis

Example

This 2D example plots the relative strength of the grating orders.

mname="T";          # monitor name
theta=gratingangle(mname);  # angle of each grating order
G=grating(mname);      # power to each order (fraction of transmitted power)
plot(theta,G,"theta (deg)","relative power","grating orders","plot points");

This 3D example calculates various grating quantities.

mname="T";       # monitor name
N=gratingn(mname);   # grating order numbers
M=gratingm(mname);
u1=gratingu1(mname);  # grating unit vectors (can be converted to theta,phi)
u2=gratingu2(mname);
G=grating(mname);   # power to each order (fraction of transmitted power)
T=transmission(mname); # total power transmitted through monitor (fraction of source power)
# Print all grating orders to prompt. Results will sum to 1.
# Then normalize grating results to the injected source power.
?G;  # grating results
?G*T; # normalized to source power
# find strength and direction of 0,0 grating order
nx=find(N,0); # find 0th grating order
ny=find(M,0); # find 0th grating order
?"Grating order 0,0 strength: " + num2str( G(nx,ny) );
?"Grating order 0,0 direction: Ux=" +num2str(u1(nx)) + " Uy=" +num2str(u2(ny));
# image all grating orders, using log scale
image(u1,u2,G,"ux","uy","Grating order strength","logplot");

Calculate the zeroth grating order transmission from a monitor that recorded multiple frequency points. The grating function operates on one frequency point at a time, so a for loop is required.

mname="T";       # monitor name
f=getdata(mname,"f");  # get frequency vector
T=transmission(mname); # get total transmission
G00 = matrix(length(f)); # initialize matrix
# get 0,0 grating order for each frequency
for (i=1:length(T)) {
 N=gratingn(mname,i);  # grating order numbers
 M=gratingm(mname,i); 
 temp=grating("T2",i);
 G00(i) = temp(find(N,0),find(M,0)); # select 0,0 grating order
}
plot(c/f*1e6,T,G00*T,"wavelength (um)","power");
legend("total transmission","0,0 grating transmission"); 

gratingn - Script command

FDTD MODE

Returns a vector of the grating order numbers (i.e. zeroeth order, first order) corresponding to the data from the grating function. gratingn gives the order numbers for the first dimension of the data (2D and 3D). gratingm gives the order numbers for the 2nd dimension (3D only). See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingn( "monitorname",...);	Same arguments as grating function.

Example

This example calculates various grating quantities.

mname="T";       # monitor name
N=gratingn(mname);   # grating order numbers
M=gratingm(mname);
u1=gratingu1(mname);  # grating unit vectors (can be converted to theta,phi)
u2=gratingu2(mname);
G=grating(mname);   # power to each order (fraction of transmitted power)
T=transmission(mname); # total power transmitted through monitor (fraction of source power)
# Print all grating orders to prompt. Results will sum to 1.
# Then normalize grating results to the injected source power.
?G;  # grating results
?G*T; # normalized to source power
# find strength and direction of 0,0 grating order
nx=find(N,0); # find 0th grating order
ny=find(M,0); # find 0th grating order
?"Grating order 0,0 strength: " + num2str( G(nx,ny) );
?"Grating order 0,0 direction: Ux=" +num2str(u1(nx)) + " Uy=" +num2str(u2(ny));
# image all grating orders, using log scale
image(u1,u2,G,"ux","uy","Grating order strength","logplot");

 

gratingm - Script command

FDTD MODE

Returns a vector of the grating order numbers (i.e. zeroeth order, first order) corresponding to the data from the grating function. gratingn gives the order numbers for the first dimension of the data (2D and 3D). gratingm gives the order numbers for the 2nd dimension (3D only). See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingm( "monitorname",...);	Same arguments as grating function.

Example

This example calculates various grating quantities.

mname="T";       # monitor name
N=gratingn(mname);   # grating order numbers
M=gratingm(mname);
u1=gratingu1(mname);  # grating unit vectors (can be converted to theta,phi)
u2=gratingu2(mname);
G=grating(mname);   # power to each order (fraction of transmitted power)
T=transmission(mname); # total power transmitted through monitor (fraction of source power)
# Print all grating orders to prompt. Results will sum to 1.
# Then normalize grating results to the injected source power.
?G;  # grating results
?G*T; # normalized to source power
# find strength and direction of 0,0 grating order
nx=find(N,0); # find 0th grating order
ny=find(M,0); # find 0th grating order
?"Grating order 0,0 strength: " + num2str( G(nx,ny) );
?"Grating order 0,0 direction: Ux=" +num2str(u1(nx)) + " Uy=" +num2str(u2(ny));
# image all grating orders, using log scale
image(u1,u2,G,"ux","uy","Grating order strength","logplot");

gratingpolar - Script command

FDTD MODE

Returns the relative strength of all physical grating orders where vector field information is returned in spherical coordinates. This is useful when studying the polarization effects. The data is normalized such that the sum of |Er|^2+|Etheta|^2+ |Ephi|^2 over all grating orders equals 1. See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

3D simulations: Data is returned in a NxMxPx3 matrix where N,M are the number of grating orders. P is the number of frequency points. The third dimension is Er, Etheta, Ephi.

2D simulations: Data is returned in a NxPx3 matrix where N is the number of grating orders. P is the number of frequency points. The second dimension is Er, Etheta, Ephi.

The results are returned on hemisphere 1m away. For more information on the basis used please refer to Understanding field polarization in far field projections

Syntax	Description
out = gratingpolar( "mname", f, index, direction);	Returns the strength of all physical grating orders from the monitor. Output is in spherical coordinates.

Parameter		Default value	Type	Description
mname	required		string	name of the monitor from which far field is calculated
f	optional	1	vector	Index of the desired frequency point. This can be a single number of a vector.
index	optional	value at monitor center	number	The index of the material to use for the projection.
direction	optional	direction of max power flow	number	Direction: this can be +1 or -1.

Examples

This 2D result shows that gratingpolar gives the same result as the grating function when we calculate |Er|^2+|Etheta|^2+ |Ephi|^2.

?Gp=gratingpolar("monitor1");
result: 
-3.06956e-017+0i -0.069704-0.32201i 0+0i 
-3.66784e-018-1.46714e-017i -0.0813186-0.381864i 0+0i 
2.97089e-017+1.48545e-017i -0.670119-0.442682i 0+0i 
-4.78864e-018-3.83091e-017i -0.0585844-0.30093i 0+0i 
?sum(abs(Gp)^2,2);
result: 
0.108549 
0.152433 
0.645027 
0.093991 
?G=grating("monitor1");
result: 
0.108549 
0.152433 
0.645027 
0.093991 

 

gratingvector - Script command

FDTD MODE

Returns the relative strength of all physical grating orders where vector field information is returned in Cartesian coordinates. This is useful when studying the polarization effects. The data is normalized such that the sum of |Ex|^2+|Ey|^2+ |Ez|^2 over all grating orders equals 1. See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

3D simulations: Data is returned in a NxMxPx3 matrix where N,M are the number of grating orders. P is the number of frequency points. The third dimension is Ex, Ey, Ez.

2D simulations: Data is returned in a NxPx3 matrix where N is the number of grating orders. P is the number of frequency points. The second dimension is Ex, Ey, Ez.

The results are returned on hemisphere 1m away. For more information on the basis used please refer to Understanding field polarization in far field projections

Syntax	Description
out = gratingvector( "mname", f, index, direction);	Returns the strength of all physical grating orders from monitorname. Output is in Cartesian coordinates.

Parameter		Default value	Type	Description
mname	required		string	name of the monitor from which far field is calculated
f	optional	1	vector	Index of the desired frequency point. This can be a single number or a vector.
index	optional	value at monitor center	number	The index of the material to use for the projection.
direction	optional	direction of max power flow	number	Direction: this can be +1 or -1.

Examples

This 2D result shows that gratingvector gives the same result as the grating function when we calculate |Ex|^2+|Ey|^2+ |Ez|^2.

?Gv=gratingvector("monitor1");
result: 
0.0476203+0.219991i 0.0509014+0.235148i 0+0i 
0.0794422+0.373053i 0.0173684+0.0815601i 0+0i 
0.638599+0.42186i -0.203101-0.134169i 0+0i 
0.0335526+0.172349i -0.0480246-0.246687i 0+0i 
?sum(abs(Gv)^2,2);
result: 
0.108549 
0.152433 
0.645027 
0.093991 
?G=grating("monitor1");
result: 
0.108549 
0.152433 
0.645027 
0.093991 

gratingperiod1 - Script command

FDTD MODE

Returns the grating period (i.e. the simulation span) used in the grating calculations. gratingperiod1 gives the grating period for the first dimension (2D and 3D). gratingperiod2 gives the period of the 2nd dimension (3D only). See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingperiod1( "monitorname", ...);	Same arguments as grating function.

 

gratingperiod2 - Script command

FDTD MODE

Returns the grating period (i.e. the simulation span) used in the grating calculations. gratingperiod1 gives the grating period for the first dimension (2D and 3D). gratingperiod2 gives the period of the 2nd dimension (3D only). See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingperiod2( "monitorname", ...);	Same arguments as grating function.

 

gratingbloch1 - Script command

FDTD MODE

Returns the bloch vector (k in_1 and k in_2 ) used in the grating calculation. This corresponds to the bloch vector setting in the simulation region. gratingbloch1 gives the bloch vector for the first dimension (2D and 3D). gratingbloch2 gives the bloch vector for the 2nd dimension (3D only). See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingbloch1( "monitorname", ...);	Same arguments as grating function.

 

gratingbloch2 - Script command

FDTD MODE

Returns the bloch vector (k in_1 and k in_2 ) used in the grating calculation. This corresponds to the bloch vector setting in the simulation region. gratingbloch1 gives the bloch vector for the first dimension (2D and 3D). gratingbloch2 gives the bloch vector for the 2nd dimension (3D only). See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingbloch2( "monitorname", ...);	Same arguments as grating function.

 

gratingu1 - Script command

FDTD MODE

Returns the grating order direction unit vectors (u 1 and u 2 ) corresponding to the data from the grating function from 3D simulation. For 2D simulations, use the gratingangle function. See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingu1( "monitorname", ...);	Same arguments as grating function.

Examples

This example calculates various grating quantities.

mname="T";       # monitor name
N=gratingn(mname);   # grating order numbers
M=gratingm(mname);
u1=gratingu1(mname);  # grating unit vectors (can be converted to theta,phi)
u2=gratingu2(mname);
G=grating(mname);   # power to each order (fraction of transmitted power)
T=transmission(mname); # total power transmitted through monitor (fraction of source power)
# Print all grating orders to prompt. Results will sum to 1.
# Then normalize grating results to the injected source power.
?G;  # grating results
?G*T; # normalized to source power
# find strength and direction of 0,0 grating order
nx=find(N,0); # find 0th grating order
ny=find(M,0); # find 0th grating order
?"Grating order 0,0 strength: " + num2str( G(nx,ny) );
?"Grating order 0,0 direction: Ux=" +num2str(u1(nx)) + " Uy=" +num2str(u2(ny));
# image all grating orders, using log scale
image(u1,u2,G,"ux","uy","Grating order strength","logplot");

 

gratingu2 - Script command

FDTD MODE

Returns the grating order direction unit vectors (u 1 and u 2 ) corresponding to the data from the grating function from 3D simulation. For 2D simulations, use the gratingangle function. See the grating function documentation for information on interpreting N, M, ux, uy for various monitor orientations.

Syntax	Description
out = gratingu2( "monitorname", ...);	Same arguments as grating function.

Examples

This example calculates various grating quantities.

mname="T";       # monitor name
N=gratingn(mname);   # grating order numbers
M=gratingm(mname);
u1=gratingu1(mname);  # grating unit vectors (can be converted to theta,phi)
u2=gratingu2(mname);
G=grating(mname);   # power to each order (fraction of transmitted power)
T=transmission(mname); # total power transmitted through monitor (fraction of source power)
# Print all grating orders to prompt. Results will sum to 1.
# Then normalize grating results to the injected source power.
?G;  # grating results
?G*T; # normalized to source power
# find strength and direction of 0,0 grating order
nx=find(N,0); # find 0th grating order
ny=find(M,0); # find 0th grating order
?"Grating order 0,0 strength: " + num2str( G(nx,ny) );
?"Grating order 0,0 direction: Ux=" +num2str(u1(nx)) + " Uy=" +num2str(u2(ny));
# image all grating orders, using log scale
image(u1,u2,G,"ux","uy","Grating order strength","logplot");

gratingangle - Script command

FDTD MODE

Returns the angle vector corresponding to the values returned by grating, in degrees, for 2D simulations. For 3D simulations, use gratingu1 and gratingu2.

If Bloch boundary conditions are used, the Bloch vector must be properly set for this command to return the correct results. To make sure the Bloch vector is properly set, turn on the "set based on source angle" option in the "Boundary conditions" tab of the FDTD solver settings.

Syntax	Description
out = gratingangle( "monitorname", ...);	Same arguments as grating function.

Example

This example plots the relative strength of the grating orders.

mname="T";          # monitor name
theta=gratingangle(mname);  # angle of each grating order
G=grating(mname);      # power to each order (fraction of transmitted power)
plot(theta,G,"theta (deg)","relative power","grating orders","plot points");

 

gratingordercount - Script command

FDTD MODE

Returns the total number of supported grating numbers.

Syntax	Description
out = gratingordercount( "monitorname", f, index, direction);	Returns the total number of supported grating orders. Same arguments as grating script command.

Example

This example calculates power to each order only if grating orders are supported.

mname="T";       # monitor name
if(gratingordercount > 0){
N=gratingn(mname);   # grating order numbers
M=gratingm(mname);
u1=gratingu1(mname);  # grating unit vectors (can be converted to theta,phi)
u2=gratingu2(mname);
G=grating(mname);   # power to each order (fraction of transmitted power)
}

DGTD 

getperiodicity - Script command

DGTD

Returns the periodicity vector(s) associated with the active periodic boundary conditions in the specified solver.

Syntax	Description
out = getperiodicity("solvername");	Returns the periodicity vector(s) of the system based on the active periodic boundary conditions in the named solver. The output is a [3XN] matrix where N is the number of dimensions that have active periodic boundary conditions (typically one or two).

Parameter		Default value	Type	Description
solvername	required		string	Name of the solver from which to extract the periodicity vector(s).

Example

This example retrieves the periodicity vectors from a DGTD simulation with periodic boundary conditions.

period = getperiodicity("DGTD"); 

 

getsourcedirection - Script command

DGTD

Returns a unit vector in the direction of the wave vector (or k-vector) of the specified source. The unit vector has three elements corresponding to the X,Y and Z directions.

Syntax	Description
out = getsourcedirection("sourcename");	Returns a [3x1] matrix with a unit vector in the direction of the specified source wave vector.

Parameter		Default value	Type	Description
sourcename	required		string	Name of the source.

Example

This example computes a unit vector in direction of the k-vector of the plane wave source named "source".

source_k = getsourcedirection("DGTD::source"); 

gratingorders - Script command

DGTD

Returns a matrix data set with the propagating grating orders, a unit vector in the direction of the wave vector (or k-vector) of each order, and the grating angles. The grating orders are the same as those used by the gratingprojection command to perform a projection.

Syntax

Description

out = gratingorders(period, source, frequency, index);

Returns a matrix data set with the propagating grating orders (integers n and m), a unit vector in the direction of the k-vector of each order (call them u (n,m)) and their corresponding angles (theta and phi). The parameters of the data set are n,m and frequency. Indexes n and m correspond to the first and second periodicity directions specified by the input periodicity vectors. The attributes of the data set are the unit vectors u (n,m) and their corresponding angles (theta and phi). The grating angles are defined with respect to the normal incidence direction of the source (call it the n -axis). The first angle (theta) is an elevation from the n -axis and the and the second angle (phi) is a rotation around the n -axis starting from the first periodicity vector. Angle phi is only returned when two periodicity vectors are specified.

Parameter		Default value	Type	Description
period	required		vector	[3x1] or [3x2] matrix with the periodicity vectors. These are typically retrieved using the getperiodicity command.
source	required		vector	[3x1] vector with the normalized source k-vector. This is typically retrieved using the getsourcedirection command.
frequency	required		vector	Vector of frequencies (in Hz).
index	optional	1.0	number or vector	Refractive index of the background medium (typically the substrate or superstrate). It can be a scalar or a vector of the same size as the frequency vector.

Example

This example shows how to find the propagating grating orders from a DGTD simulation with periodic boundary conditions. The source k-vector and frequency are obtained from and plane wave source object named "source" and a frequency domain monitor named "monitor", respectively.

# frequency vector of the near fields
fields = getresult("DGTD::monitor","fields");
frequency = fields.f; 
# periodicity vectors
period = getperiodicity("DGTD");
# source k-vector
source_k = getsourcedirection("DGTD::source");
# propagating grating orders
go = gratingorders(period,source_k,frequency,1.0);
visualize(go); 

 

gratingprojection - Script command

DGTD

Takes the near fields from a frequency domain monitor together with the periodicity vectors of the system, the source wave vector and the background refractive index and performs a far field projection to determine the relative power in each propagating grating order.

Syntax

Description

out = gratingprojection(nearfield, period, source, index);

Returns a matrix data set with all the projection results. The parameters of the data set are the grating orders (integers n and m) and frequency. Indexes n and m correspond to the first and second periodicity directions specified by the input periodicity vectors. The attributes of the data set are the same as those returned by the gratingorders command with the addition of the relative power into each propagating grating order (called projection). The projection result is normalized so that its sum over all grating orders is always equal to one. The frequency parameter is the same as that of the input field data.

Parameter		Default value	Type	Description
nearfield	required		unstructured data set	Field data from a frequency domain monitor.
period	required		vector	Periodicity vector(s) as returned by the getperiodicity command.
source	required		vector	Source unit wave vector as returned by the getsourcedirection command.
index	optional	1.0	number or vector	Refractive index of the background medium (typically the substrate or superstrate). It can be a scalar or a vector of the same size as the frequency vector.

Example

This example demonstrates how to calculate the relative power into each propagating grating order for a DGTD simulation with periodic boundary conditions. The near fields are collected from a frequency domain monitor named "monitor". The source wave vector is collected from a plane wave source named "source". The periodicity vectors are collected from the DGTD simulation object.

# unstructured data set with the near field
fields = getresult("DGTD::monitor","fields");
# periodicity vector
period = getperiodicity("DGTD");
# normalized source k-vector
source_k = getsourcedirection("DGTD::source");
# grating projection
gp = gratingprojection(fields,period,source_k);
visualize(gp);