Snapshots

The Snapshot module

This module defines the basic snapshots and some additional snapshot objects for convenience.

Deprecated notes. To be updated at some point.:

• IDEA:
  • main bfdtd class writer calls snap.write(file, mesh)
  • main snap class defines mainwrite(file, mesh, subwrite) (which writes one or multiple snap entries to file)
  • sub snap classes (freq,time,etc) define subwrite() (which just writes single snap entry to file)
  • sub snap classes define write(file, mesh) which calls mainwrite(file, mesh, subwrite)
• NOTES:
  • When P1,P2 do not form a plane, a single snapshot is created at X1 if plane=1, Y1 if plane=2, Z1 if plane=3, i.e. P1 is used for positioning the slice.
  • When coordinates in P1 or P2 do not correspond to a mesh point, they are snapped to the closest one.
  • When X1>X2 or similar: Behaviour unknown!!!
• Writing methods:
  • single plane if (P1,P2) form a plane.
  • 6 planes, one on each side if (P1,P2) form a box.
  • N planes in X, Y or Z based on mesh if (P1,P2) form a box.
  • 3 planes (X,Y,Z) intersecting at (P1+P2)/2.
• The main writing function should be the same for all snapshots and call the specific writing functions depending on an attribute defining which one is desired.
• The specific writing functions of the base class should be overridden in the child classes.

Snapshot objects

See also bfdtd.snapshot module.

Snapshot

class bfdtd.snapshot.Snapshot

Bases: object

Simple base class for all single-entry BFDTD snapshots.

Attributes:

• first: integer
• repetition: integer
• plane: integer
• P1: 3D vector
• P2: 3D vector
• E: 3D vector
• H: 3D vector
• J: 3D vector

Note

Plane snapshots will never output data for the upper edges of the simulation box.

Example: Box from (0,0,0) to (1,1,1) with Z snapshot from (0,0) to (1,1) -> Snapshot output will not contain any points along the x=1 and y=1 lines.

A Z snapshot at z=1 will however still output data!

getCentro()

getEfield()

getExtension()

Returns the extension, i.e. (lower, upper) = (P1,P2).

getFirst()

getHfield()

getJfield()

getLower()

Returns the lower corner (P1).

getMeshingParameters(xvec, yvec, zvec, epsx, epsy, epsz)

getName()

getPlaneBfdtdIndex()

getPlaneLetter()

return letter describing plane orientation (‘x’,’y’ or ‘z’)

getPlanePythonIndex()

getRepetition()

getSize()

getTypeBasedOnAttributes()

Returns class by default, but overloaded in the TimeSnapshot class to differentiate time and epsilon snapshots.

getUpper()

Returns the upper corner (P1).

plane

orientation of the snapshot plane

read_data(data3D, mesh=None, fsnap_numID=1, tsnap_numID=1, probe_ident='_id_', snap_time_number=0, dataPaths=['.'], testrun=False)

setCentro(centro_vec3)

Reposition the snapshot so that (P1+P2)/2 = centro_vec3, i.e. its centre is at centro_vec3.

setEfield(E_vec3)

setExtension(lowerCorner_vec3, upperCorner_vec3)

Set the extension of the snapshot, i.e. its lower and upper corners.

If you have an (L,U) tuple like the one you get from getExtension(), you can pass it directly via python’s unpacking feature as follows:

obj.setExtension(*sim.getExtension())

setExtensionFromSnapshot(snapshot_in)

Copies the P1, P2 and plane attributes from snapshot_in, i.e. the extension and the plane orientation.

setExtensionX(x1, x2)

setExtensionY(y1, y2)

setExtensionZ(z1, z2)

setFirst(first)

setFromSnapshot(snapshot_in)

Copies the properties from snapshot_in.

setFullExtensionOff()

setFullExtensionOn()

setGroup(group)

setHfield(H_vec3)

setJfield(J_vec3)

setLayer(layer)

setName(name)

setPlaneBfdtdIndex(bfdtd_index)

setPlaneLetter(plane_letter)

set plane orientation by passing ‘x’,’y’ or ‘z’

setPlaneOrientationX()

setPlaneOrientationY()

setPlaneOrientationZ()

setPlanePythonIndex(python_index)

setRepetition(repetition)

setSize(size_vec3)

Set the size of the snapshot, i.e. [size_x, size_y, size_z] = P2 - P1.

Parameters:size_vec3 – A list or array of length 3, or a scalar int or float value. If a scalar S is passed, the size vector [S, S, S] will be used.

setStartingSample(starting_sample)

dummy function, to be re-implemented in subclasses, such as FrequencySnapshot .. todo:: Why not just give it to all? no need for FrequencySnapshot defining it then…

setUseForMeshing(useForMeshing)

write_data(sampling_function, mesh=None, numID=0, probe_ident='_id_', snap_time_number=0, destdir='.')

write_entry(FILE=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, mesh=None)

TimeSnapshot

class bfdtd.snapshot.TimeSnapshot

Bases: bfdtd.snapshot.Snapshot

Simple base class for all single-entry BFDTD snapshots written as SNAPSHOT in .inp files.

Attributes:

• power: 0 or 1
• epsilon: 0 or 1

One or more field components may be sampled over a specified plane in the structure after a specified number of iterations. It is possible to take snapshots after every “n” iterations by setting the “iterations between snapshots” parameter to “n”.

For each snapshot requested a file is produced in one of two formats:

• List format which has a filename of the form “x1idaa.prn”, where “x” is the plane over which the snapshot has been taken, “1”is the snapshot serial number. ie. the snaps are numbered in the order which they appear in the input file.. “id” in an identifier specified in the “flags” object. “aa” is the time serial number ie. if snapshots are asked for at every 100 iterations then the first one will have “aa, the second one “ab” etc The file consists of a single header line followed by columns of numbers, one for each field component wanted and two for the coordinates of the point which has been sampled. These files can be read into Gema.
• Matrix format for each snapshot a file is produced for each requested field component with a name of the form “x1idaa_ex” where the “ex” is the field component being sampled. The rest of the filename is tha same as for the list format case. The file consists of a matrix of numbers the first column and first row or which, gives the position of the sample points in each direction. These files can be read into MathCad or to spreadsheet programs.

The format of the snapshot object is as follows:

• 1 : first: iteration number for the first snapshot
• 2 : repetition: number of iterations between snapshots
• 3 : plane: 1=x,2=y,3=z
• 4-9 : P1, P2: coordinates of the lower left and top right corners of the plane P1(x1,y1,z1), P2(x2,y2,z2)
• 10-18 : E, H, J: field components to be sampled E(Ex,Ey,Ez), H(Hx,Hy,Hz), J(Jx,Jy,Jz)
• 19 : power: print power? =0/1
• 20 : eps: create EPS (->epsilon->refractive index) snapshot? =0/1
• 21 : ???: write an output file in “list” format (NOT IMPLEMENTED YET)(default is list format)
• 22 : ???: write an output file in “matrix” format (NOT IMPLEMENTED YET)

Mode filtered probe files (Requires a template for the first excitation object!):

Mode filtered probe files are specified in the same way as a snapshot across the reference plane except that no field components are selected, i.e. E=H=J=power=eps=(0,0,0). In addition, the “repetition” parameter takes the role which the “step” parameter does on normal probes.

The output will have the same form as a probe file and will consist of the inner product at each time step of the field distribution across the reference plane with the template specified for the first excitation object. This template will normally be the wanted mode of the guiding structure and, thus, the output of this probe will be the amplitude of just this mode.

The effect of this is that the amplitude of the mode of interest is sampled across the whole waveguide cross-section. If a normal field probe had been used, then the unwanted effects of other modes would cause inaccuracies in the final result.

Note

JX,JY,JZ output does not seem to work. (Bristol FDTD issue)

The output columns are (assuming all columns were enabled):

• For X planes:

  #y z Ex Ey Ez Hx Hy Hz Pow material 
  

• For Y planes:

  #x z Ex Ey Ez Hx Hy Hz Pow material 
  

• For Z planes:

  #x y Ex Ey Ez Hx Hy Hz Pow material 
  

fillData(data3D, x_idx, y_idx, z_idx, header, row)

getEpsilon()

getFileNames(fsnap_numID=1, tsnap_numID=1, probe_ident='_id_', snap_time_number=0)

getOutputColumnHeaders()

getPower()

getTypeBasedOnAttributes()

Returns the “type” of the snapshot based on the selected output columns (E, H, J, power and epsilon).

• If all output columns are disabled: ModeFilteredProbe
• If all output columns are disabled, except epsilon: EpsilonSnapshot
• Else: TimeSnapshot

Or in table form:

Attributes					Output
E	H	J	Power	Epsilon	Type
000	000	000	0	0	ModeFilteredProbe
000	000	000	0	1	EpsilonSnapshot
*	*	*	*	*	TimeSnapshot

read_entry(entry)

setEpsilon(eps)

setPower(power)

write_data_row(csvwriter, sampling_function, x, y, z, t)

write_entry(FILE=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, mesh=None)

ModeFilteredProbe

class bfdtd.snapshot.ModeFilteredProbe

Bases: bfdtd.snapshot.TimeSnapshot

Child class of TimeSnapshot, which disables all output columns. This leads to a mode filtered probe behaviour.

Unlike usual time and epsilon snapshots, the ModeFilteredProbe output filenames start with “i” instead of “x/y/z” and start with a 0 index instead of 1, i.e. the first ModeFilteredProbe output file will be “i1_id_00.prn” instead of “x1_id_01.prn”.

Requires a “template”. The default template filename is “template.int”.

The output columns are always:

#Time inner_product_e inner_product_h inner_product_poynting sum difference

EpsilonSnapshot

class bfdtd.snapshot.EpsilonSnapshot

Bases: bfdtd.snapshot.TimeSnapshot

Child class of TimeSnapshot, which disables all output columns except epsilon.

setDefaults()

Sets the following properties:

• self.E = [0,0,0]
• self.H = [0,0,0]
• self.J = [0,0,0]
• self.power = 0
• self.eps = 1
• self.first = 1
• self.repetition = int(1e9)

setFromSnapshot(snapshot_in)

Copies the properties from snapshot_in, but then calls EpsilonSnapshot.setDefaults().

FrequencySnapshot

class bfdtd.snapshot.FrequencySnapshot

Bases: bfdtd.snapshot.Snapshot

Simple base class for all single-entry BFDTD snapshots written as FREQUENCY_SNAPSHOT in .inp files.

Attributes:

• interpolate: 0 or 1
• real_dft: 0 or 1
• mod_only: 0 or 1
• mod_all: 0 or 1
• frequency_vector: float vector
• starting_sample: integer

The format of a frequency snapshot object is:

• 1. first: iteration number for the first snapshot
• 2. repetition: number of iterations between snapshots
• 3. interpolate:
  • If set to 1 : the H field samples are interpolated to give the value at the plane of the E field nodes
  • If set to 2 : as above but the field values are multiplied by the area of the cell on the plane and interpolated to the centre of the square in the plane of the E field nodes..
  • If set to 3 : as above but the order of the field components in the output file is changed so that for the x,y and z planes the order is (yzx), (zxy) and (xyz) respectively instead of always being (xyz)
  • If set to 4 : as for 2 except that all 3 coordinates are given for each point
• 4. real_dft: Set this if it is not required to write the imaginary component to file
• 5. mod_only: Write only the modulus to file
• 6. mod_all: Write the modulus AND the real and imaginary parts to file
• 7. plane: 0=all, 1=x, 2=y, 3=z

• 8-13) P1,P2: coordinates of the lower left and top right corners of the plane P1(x1,y1,z1), P2(x2,y2,z2)

• 14. frequency_vector: frequency (in MHz! ). Will create a frequency snapshot for each frequency in the list/vector
• 15. starting_sample: iteration number at which to start the running fourier transforms

• 16-24) E,H,J: field components to be sampled E(Ex,Ey,Ez), H(Hx,Hy,Hz), J(Jx,Jy,Jz)

The output file is of the same format as the snapshot “list format” and the naming is the same except that the time serial number starts at “00” instead of “aa”.

Clarification on how real_dft, mod_only and mod_all work:

• if mod_only or mod_all: output mod
• if not(mod_only): output real part
• if not(real_dft) and not(mod_only): output imaginary part

Or in table form:

Inputs			Output
real_dft	mod_only	mod_all	|field|	real(field)	imag(field)
0	0	0	0	1	1
0	0	1	1	1	1
0	1	0	1	0	0
0	1	1	1	0	0
1	0	0	0	1	0
1	0	1	1	1	0
1	1	0	1	0	0
1	1	1	1	0	0

Note

J output does not work at the moment. This is a Bristol FDTD related issue.

fillData(data3D, x_idx, y_idx, z_idx, header, row)

getFileNames(fsnap_numID=1, tsnap_numID=1, probe_ident='_id_', snap_time_number=0)

getFrequencies()

getLambda()

Get the wavelength list.

getOutputColumnHeaders()

getOutputColumnHeadersSubFunction(field)

getStartingSample()

read_entry(entry)

setFrequencies(frequency_vector)

Set the frequencies of the frequency snapshot.

setFromSnapshot(snapshot_in)

Copies the properties from snapshot_in.

setStartingSample(starting_sample)

dummy function, to be re-implemented in subclasses, such as FrequencySnapshot .. todo:: Why not just give it to all? no need for FrequencySnapshot defining it then…

setWavelengths(wavelength_vector)

write_data_row(csvwriter, sampling_function, x, y, z, t)

write_entry(FILE=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, mesh=None)

ModeVolumeBox

class bfdtd.snapshot.ModeVolumeBox

Bases: bfdtd.snapshot.EnergySnapshot

This one is definitely necessary and should be as easy to use as possible.

The other necessity is an EpsilonBox for geometry checking. Perhaps with Nx,Ny,Nz specification for mesh independence.

setupEnergySnapshotBox()

write_data(sampling_function, mesh=None, numID=0, probe_ident='_id_', snap_time_number=0, destdir='.')

write_entry(FILE=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, mesh=None)