Dump Box Property

Introduction
Adding a field dump in openEMS is a two stage process. First, a dump property is added to the CSX structure with a given name and properties. Here one defines which fields will be saved and other options such as the file type, interpolation mode, etc. In the second step the geometry of the field dump is defined by adding a primitive to the field dump.

Invoke field dump
A field dump is invoked by CSX = AddDump(CSX, name, varargin)

Note: The name given to a dump box will be used as filename or part of a series of filenames (e.g. vtk time domain dump).

Variable arguments for usage with openEMS are:
 * DumpType:
 * 0: for E-field time-domain dump (default)
 * 1: for H-field time-domain dump
 * 2: for electric current time-domain dump
 * 3: for total current density (rot(H)) time-domain dump
 * 10: for E-field frequency-domain dump
 * 11: for H-field frequency-domain dump
 * 12: for electric current frequency-domain dump
 * 13: for total current density (rot(H)) frequency-domain dump
 * 20: local SAR frequency-domain dump
 * 21: 1g averaging SAR frequency-domain dump
 * 22: 10g averaging SAR frequency-domain dump
 * 29: raw data needed for SAR calculations (electric field FD, cell volume, conductivity and density)


 * Frequency: specify a frequency vector (required for dump types >=10)
 * DumpMode:
 * 0: no-interpolation
 * 1: node-interpolation (default, see warning below)
 * 2: cell-interpolation (see warning below)
 * FileType:
 * 0: vtk-file dump     (default)
 * 1: hdf5-file dump
 * SubSampling:  field domain sub-sampling, e.g. '2,2,4', which means, dump only every second line in x- and y- and only every forth line in z-direction.
 * OptResolution: field domain dump resolution, e.g. '10' or '10,20,5', which means, choose lines to dump in such a way, that they are about 10 (drawing units) apart from another (or e.g. 10 in x-, 20 in y- and 5 in z-direction). This can mean in some area that every line is dumped (as they may be about 10 drawing units or more apart), or maybe only every second, or tenth etc. line to result in an average distance of <10 drawing units apart. The first and last line inside the dump box are always choosen. Note: The dumped lines must not be homogeneous, they only try to be as much as possible. This option may be useful in case of a very inhomogeneous FDTD mesh to create a somewhat more homogeneous field dump.

Add primitive to the field dump
The coordinates that are used for the field dump can be defined with a box primitive. Other primitives may be used by their bounding box or result in an invalid field dump. The property name assigned to the box is the name of the field dump defined before.

Examples
CSX = AddDump(CSX,'Et'); CSX = AddBox(CSX,'Et',10,[0 0 0],[100 100 200]); %assign box This saves the electric field for each time step (time domain) inside the box.

CSX = AddDump(CSX,'Ef', 'DumpType', 10, 'Frequency',[1e9 2e9]); CSX = AddBox(CSX,'Ef',10,[0 0 0],[100 100 200]); %assign box This saves the complex field amplitudes at the frequencies 1e9 and 2e9 for each point inside the box.

CSX = AddDump(CSX,'Ht','SubSampling','2,2,4','DumpType',1); CSX = AddBox(CSX,'Ht',10,[0 0 0],[100 100 200]); %assign box This saves the time-domain magnetic field with sub sampling.

Warnings
There are some common FDTD interpolation abnormalities:
 * no-interpolation: fields are located on the edges of the Yee-cell (FDTD), the dumped mesh only specifies E- or H-Yee-nodes --> use node- or cell-interpolation or be aware of the offset
 * E-/J-field dump & node-interpolation: normal electric fields on boundaries will have false amplitude due to forward/backward interpolation in case of (strong) changes in material permittivity or on metal surfaces --> use no- or cell-interpolation in this case
 * H-field dump & cell-interpolation: normal magnetic fields on boundaries will have false amplitude due to forward/backward interpolation in case of (strong) changes in material permeability --> use no- or node-interpolation