[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11 Recording

Angora can record field values computed during a simulation into a file in a variety of ways. Field values can be recorded on a cross-section of the grid, along a line through the grid, or at a given point in the grid. Currently, Angora only supports the recording of the electric or the magnetic field. Recording of other field-related quantities such as energy, flux, Poynting’s vector, etc. will be implemented in the future. Please send any comments, suggestions, and requests to help@angorafdtd.org.

Global variable: string recorder_output_dir (default: "recorder")

This determines the subdirectory in which all the recording-related stuff will be placed. Unless it has a slash ‘/’ up front; this path is interpreted as being relative to output_dir (see section Paths).

 
recorder_output_dir = "recorder";
Recorder:
{
        …
        …
};
Global variable: group Recorder

The Recorder group contains the sub-variables related to different types of field recording. These are explained in the following subsections.

 
Recorder:
{
    MovieRecorders:
    (
        {
            …
            …
        }
    );
    LineRecorders:
    (
        {
            …
            …
        }
    );
    FieldValueRecorders:
    (
        {
            …
            …
        }
    );
};

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.1 Movie Recording

Angora can record field components on a two-dimensional cross section of the grid into a custom movie file. The binary format used for movie recording is described in more detail in Movie File Format.

Sub-variable of Recorder: string movie_recorder_output_dir (default: "")

This determines the subdirectory in which all the recorded movie files will be placed. Unless it has a slash ‘/’ up front; this path is interpreted as being relative to recorder_output_dir (see recorder_output_dir).

 
Recorder:
{
    movie_recorder_output_dir = "movies";
    MovieRecorders:
    (
        …
        …
    );
};
Sub-variable of Recorder: list MovieRecorders

Field values on a two-dimensional cross section of the FDTD grid can be recorded using the MovieRecorders list.

 
Recorder:
{
    MovieRecorders:
    (
        {
            recorded_section = "xz";
            recorded_position = 0;
            recorded_component = "Ex";
            recording_scale = "dB";
            recording_type = "uchar1";
            movie_dir = "this_movie_dir";
            movie_file_name = "MovieFile"
            movie_file_extension = "amv";
            append_group_index_to_file_name = true;
            only_records_material_info = false;
        },
        {
            …
            …
        }
    );
};
Sub-variable of MovieRecorders: string recorded_section

This determines the cross section of the grid over which the field is recorded. Currently, only xz, yz, and xy cross sections are supported. These are represented by the string values "xz", "yz", and "xy", respectively.

Sub-variable of MovieRecorders: floating-point recorded_position (units: m)
Sub-variable of MovieRecorders: integer recorded_position_in_cells

This value specifies the coordinate of the recorded cross section along the perpendicular direction (e.g., the z direction if recorded_section is "xy"). The coordinate is relative to the grid origin (see section Coordinate Origin). The units are either in meters or grid cells. For the latter, the _in_cells suffix should be appended to the variable name. If the coordinate corresponds to a non-integer cell position, the closest integer position is chosen.

Sub-variable of MovieRecorders: string recorded_component

An individual movie recorder (in a group delineated by the curly brackets ‘{}’) only records a single scalar value extracted from the vector-valued electromagnetic field. This could be one of the Cartesian components or the absolute value of the electric or the magnetic field. These are represented by the string values "Ex", "Ey", "Ez", "E", "Hx", "Hy", "Hz", and "H". If you would like to record multiple Cartesian components of a vector field, simply add other movie recorders (i.e., other groups, see Groups) to the MovieRecorders list with the desired recorded_component values.

Sub-variable of MovieRecorders: string recording_scale

If "linear", the raw values are recorded. If "absolute", the absolute value is taken before recording. If "dB", the decibel value $(20\log_{10}(\vert\cdot\vert))$ is recorded.

Sub-variable of MovieRecorders: string recording_type

Movies can either be recorded either in raw floating-point format, or in a single-byte compressed format. This is specified by assigning the string values "dbl8" or "uchar1" to the recording_type variable, respectively. Using the single-byte format reduces the file size considerably, but results in some data loss.

If recording_type is "dbl8", then the field values are recorded in 8-byte double datatype, after processed in accordance with the recording_scale specification above. This provides practically lossless recording, albeit with increased computational burden and file size.

With the "uchar1" option, the field values are reduced to 256 discrete bins within a fixed dynamic range. This requires only a single byte per field value; reducing the storage requirement by a factor of 8.

  • If recording_type is "dB", the maximum and minimum values in this dynamic range are determined by the global variables max_field_value and dB_accuracy (see Dynamic Range):

    \begin{displaymath}{\bf max:\ }20\log_{10}(\vert{\rm max\_field\_value}\vert)
\q...
...og_{10}(\vert{\rm max\_field\_value}\vert)+({\rm dB\_accuracy})\end{displaymath}

    The dB_accuracy variable should always be negative; therefore the minimum value in the dynamic range is lower than the maximum.

  • If recording_type is "linear" or"absolute", the maximum and minimum values are determined only by the global variable max_field_value (see Dynamic Range):

    \begin{displaymath}{\bf max:\ }{\rm max\_field\_value}
\qquad {\bf min:\ } ({\rm -max\_field\_value})\ \ {\rm or }\ \ 0\end{displaymath}

Sub-variable of MovieRecorders: string movie_dir (default: "")

This determines the subdirectory in which this individual movie file will be placed. Unless it has a slash ‘/’ up front; this path is interpreted as being relative to movie_recorder_output_dir (see movie_recorder_output_dir). By default, no subdirectory is created inside movie_recorder_output_dir.

Sub-variable of MovieRecorders: string movie_file_name (default: "MovieFile")

This determines the base string in the full name of the movie file. Other information is appended to the name of the file to differentiate individual movie files (see the example below).

Sub-variable of MovieRecorders: string movie_file_extension (default: "amv")

This is the extension of the movie file name. If assigned the value "", no extension is added to the file.

Here is an example movie file name:

 
MovieFile_Ex_0_1.amv

The base string in the name of the file ("MovieFile") is specified by the movie_file_name variable. The second part of the file name, "Ex", is determined by the recorded field component. The two integers that follow are the run index (see Multiple Simulation Runs) and the index of the movie inside the MovieRecorders list. For example, if there are two groups (two movies) in the MovieRecorders list, the first one will write into

 
MovieFile_Ex_0_0.amv

while the second will write into

 
MovieFile_Ex_0_1.amv

If there are two simulation runs (i.e., number_of_runs is equal to 2 – see Multiple Simulation Runs), then the files created in the second run will have 1 instead of 0 as the first integer in the above file names. Finally, the extension ("amv") of the movie files is determined by the variable movie_file_extension.

Sub-variable of MovieRecorders: boolean append_group_index_to_file_name (default: true)

If this is set to false, the second integer in the filename (see above) and the underscore preceding it are not included in the filename. It is set to true by default. If this variable is set to false and there are multiple groups (movie recorders), there will be a name clash, and the output will be undefined.

Sub-variable of MovieRecorders: boolean only_records_material_info (default: false)

If set to true, only the material information is recorded into the file, and no field recording is performed during the simulation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.1.1 Movie File Format

Angora records movies in a custom binary format for better speed and performance. Please be aware that this format is subject to modification. The changes in the format will be documented in this manual as necessary. You may refer to the ‘ChangeLog’ file in the Angora distribution for recent changes in the movie recording format.

The MATLAB script ‘angora_movie.m’, distributed as part of the Angora package, reads an Angora movie file and displays it as a MATLAB movie. It can also save the movie in AVI format. This script is installed in the directory ‘$(prefix)/share/angora/’ (see Compilation and Installation). If Angora was installed without any $(prefix) configuration option, the default location is ‘/usr/local/share/angora/’. This script can also be downloaded directly from the Angora website (link here).

The movie file is composed of chunks of data, ordered as follows. For each chunk, a short explanation (and maybe an alias) is given, followed by a description of the datatype in parantheses.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.2 Line Recording

Angora can record field components along a line into a file. The binary format used for line recording is described in more detail in Line File Format.

Sub-variable of Recorder: string line_recorder_output_dir (default: "")

This determines the subdirectory in which all the recorded line files will be placed. Unless it has a slash ‘/’ up front; this path is interpreted as being relative to recorder_output_dir (see recorder_output_dir).

 
Recorder:
{
    line_recorder_output_dir = "lines";
    LineRecorders:
    (
        …
        …
    );
};
Sub-variable of Recorder: list LineRecorders
 
Recorder:
{
    LineRecorders:
    (
        {
            line_orientation = "y_directed";
            line_position_x1 = 0;
            line_position_x2 = 0;
            recorded_component = "Ex";
            recording_scale = "linear";
            line_dir = "this_line_dir";
            line_file_name = "LineFile";
            line_file_extension = "aln";
            append_group_index_to_file_name = true;
        },
        {
            …
            …
        }
    );
};
Sub-variable of LineRecorders: string line_orientation

There are three possible orientations for the line over which the field values are recorded .These orientations are along the three principal axes of the grid; namely, the x,y, and z directions. These are specified by the strings "x_directed", "y_directed", and "z_directed", respectively.

Sub-variable of LineRecorders: floating-point line_position_x1 (units: m)
Sub-variable of LineRecorders: integer line_position_x1_in_cells

This is the first of the remaining two coordinates that specify the position of the recorded line. The coordinate is relative to the grid origin (see section Coordinate Origin). For example, if the line is oriented in the y direction (line_orientation is "y_directed"), then line_position_x1_in_cells specifies the x coordinate of the line. The units are either in meters or grid cells. For the latter, the _in_cells suffix should be appended to the variable name. If the coordinate corresponds to a non-integer cell position, the closest integer position is chosen.

Sub-variable of LineRecorders: floating-point line_position_x2 (units: m)
Sub-variable of LineRecorders: integer line_position_x2_in_cells

This is the second of the remaining two coordinates that specify the position of the recorded line. The coordinate is relative to the grid origin (see section Coordinate Origin). For example, if the line is oriented in the y direction (line_orientation is "y_directed"), then line_position_x2_in_cells specifies the z coordinate of the line. The units are either in meters or grid cells. For the latter, the _in_cells suffix should be appended to the variable name. If the coordinate corresponds to a non-integer cell position, the closest integer position is chosen.

Sub-variable of LineRecorders: string recorded_component

An individual line recorder (in a group delineated by the curly brackets ‘{}’) only records a single scalar value extracted from the vector-valued electromagnetic field. This could be one of the Cartesian components or the absolute value of the electric or the magnetic field. These are represented by the string values "Ex", "Ey", "Ez", "E", "Hx", "Hy", "Hz", and "H". If you would like to record multiple Cartesian components of a vector field, simply add other line recorders (i.e., other groups, see Groups) to the LineRecorders list with the desired recorded_component values.

Sub-variable of LineRecorders: string recording_scale

If "linear", the raw values are recorded. If "absolute", the absolute value is taken before recording. If "dB", the decibel value $(20\log_{10}(\vert\cdot\vert))$ is recorded.

Sub-variable of LineRecorders: string line_dir (default: "")

This determines the subdirectory in which this individual line file will be placed. Unless it has a slash ‘/’ up front; this path is interpreted as being relative to line_recorder_output_dir (see line_recorder_output_dir). By default, no subdirectory is created inside line_recorder_output_dir.

Sub-variable of LineRecorders: string line_file_name (default: "LineFile")

This determines the base string in the full name of the line file. Other information is appended to the name of the file to differentiate individual line files (see the example below).

Sub-variable of LineRecorders: string line_file_extension (default: "aln")

This is the extension of the line file name. If assigned the value "", no extension is added to the file.

Here is an example line file name:

 
LineFile_Ey_Y_0_1.aln

The base string in the name of the file ("LineFile") is specified by the line_file_name variable. The second part of the file name, "Ey", is determined by the recorded field component. The following string "Y" indicates the orientation of the line, which is y-directed for this example. The two integers that follow are the run index (see Multiple Simulation Runs) and the index of the line recorder inside the LineRecorders list. For example, if there are two groups (two line recorders) in the LineRecorders list, the first one will write into

 
LineFile_Ey_Y_0_0.aln

while the second will write into

 
LineFile_Ey_Y_0_1.aln

If there are two simulation runs (i.e., number_of_runs is equal to 2 – see Multiple Simulation Runs), then the files created in the second run will have 1 instead of 0 as the first integer in the above file names. Finally, the extension ("aln") of the line files is determined by the variable line_file_extension.

Sub-variable of LineRecorders: boolean append_group_index_to_file_name (default: true)

If this is set to false, the second integer in the filename (see above) and the underscore preceding it are not included in the filename. It is set to true by default. If this variable is set to false and there are multiple groups (line recorders), there will be a name clash, and the output will be undefined.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.2.1 Line File Format

As with movies, Angora records the line files in a custom binary format for better speed and performance. Please be aware that this format is subject to modification. The changes in the format will be documented in this manual as necessary. You may refer to the ‘ChangeLog’ file in the Angora distribution for recent changes in the line recording format.

The MATLAB script ‘angora_line.m’, distributed as part of the Angora package, reads an Angora line file and displays it as a MATLAB movie. This script is installed in the directory ‘$(prefix)/share/angora/’ (see Compilation and Installation). If Angora was installed without any $(prefix) configuration option, the default location is ‘/usr/local/share/angora/’. This script can also be downloaded directly from the Angora website (link here).

The line file is composed of chunks of data, ordered as follows. For each chunk, a short explanation (and maybe an alias) is given, followed by a description of the datatype in parantheses.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.3 Field-Value Recording

Angora can record the time history of the field at a given position in the simulation grid. The format used for this sort of recording is HDF5 (Hierarchical Data Format) (http://www.hdfgroup.org/HDF5/). The HDF5 format was chosen for its standard interface, and the availability of free software tools for inspecting and modifying HDF5 output. The HDF5 output created by the field-value recorder is explained in more detail in Field-Value File HDF5 Content.

Sub-variable of Recorder: string field_value_recorder_output_dir (default: "")

This determines the subdirectory in which all the recorded field-value files will be placed. Unless it has a slash ‘/’ up front; this path is interpreted as being relative to recorder_output_dir (see recorder_output_dir).

 
Recorder:
{
    field_value_recorder_output_dir = "fieldvalues";
    FieldValueRecorders:
    (
        …
        …
    );
};
Sub-variable of Recorder: list FieldValueRecorders
 
Recorder:
{
    FieldValueRecorders:
    (
        {
            coord_x = 0;
            coord_y = 0;
            coord_z = 0;
            recorded_component = "Ex";
            recording_scale = "linear";
            field_value_dir = "this_field_value_dir";
            field_value_file_name = "FieldValueFile";
            field_value_file_extension = "hd5";
            append_group_index_to_file_name = true;
        },
        {
            …
            …
        }
    );
};
Sub-variable of FieldValueRecorders: floating-point coord_x (units: m)
Sub-variable of FieldValueRecorders: integer coord_x_in_cells

This is the x coordinate of the recorded position in the simulation grid. It is relative to the grid origin (see section Coordinate Origin). The units are either in meters or grid cells. For the latter, the _in_cells suffix should be appended to the variable name. If the coordinate corresponds to a non-integer cell position, the closest integer position is chosen.

Sub-variable of FieldValueRecorders: floating-point coord_y (units: m)
Sub-variable of FieldValueRecorders: integer coord_y_in_cells

This is the y coordinate of the recorded position in the simulation grid. It is relative to the grid origin (see section Coordinate Origin). The units are either in meters or grid cells. For the latter, the _in_cells suffix should be appended to the variable name. If the coordinate corresponds to a non-integer cell position, the closest integer position is chosen.

Sub-variable of FieldValueRecorders: floating-point coord_z (units: m)
Sub-variable of FieldValueRecorders: integer coord_z_in_cells

This is the z coordinate of the recorded position in the simulation grid. It is relative to the grid origin (see section Coordinate Origin). The units are either in meters or grid cells. For the latter, the _in_cells suffix should be appended to the variable name. If the coordinate corresponds to a non-integer cell position, the closest integer position is chosen.

Sub-variable of FieldValueRecorders: string recorded_component

An individual field-value recorder (in a group delineated by the curly brackets ‘{}’) only records a single scalar value extracted from the vector-valued electromagnetic field. This could be one of the Cartesian components or the absolute value of the electric or the magnetic field. These are represented by the string values "Ex", "Ey", "Ez", "E", "Hx", "Hy", "Hz", and "H". If you would like to record multiple Cartesian components of a vector field, simply add other field-value recorders (i.e., other groups, see Groups) to the FieldValueRecorders list with the desired recorded_component values.

Sub-variable of FieldValueRecorders: string recording_scale

If "linear", the raw values are recorded. If "absolute", the absolute value is taken before recording. If "dB", the decibel value $(20\log_{10}(\vert\cdot\vert))$ is recorded.

Sub-variable of FieldValueRecorders: string field_value_dir (default: "")

This determines the subdirectory in which this individual field-value file will be placed. Unless it has a slash ‘/’ up front; this path is interpreted as being relative to field_value_recorder_output_dir (see field_value_recorder_output_dir). By default, no subdirectory is created inside field_value_recorder_output_dir.

Sub-variable of FieldValueRecorders: string field_value_file_name (default: "FieldValueFile")

This determines the base string in the full name of the field-value file. Other information is appended to the name of the file to differentiate individual field-value files (see the example below).

Sub-variable of FieldValueRecorders: string field_value_file_extension (default: "hd5")

This is the extension of the field-value file name. If assigned the value "", no extension is added to the file. The HDF5 extension "hd5" is applied by default.

Here is an example field-value file name:

 
FieldValueFile_Ex_0_1.hd5

The base string in the name of the file ("FieldValueFile") is specified by the field_value_file_name variable. The second part of the file name, "Ex", is determined by the recorded field component. The two integers that follow are the run index (see Multiple Simulation Runs) and the index of the field-value recorder inside the FieldValueRecorders list. For example, if there are two groups (two field-value recorders) in the FieldValueRecorders list, the first one will write into

 
FieldValueFile_Ex_0_0.hd5

while the second will write into

 
FieldValueFile_Ex_0_1.hd5

If there are two simulation runs (i.e., number_of_runs is equal to 2 – see Multiple Simulation Runs), then the files created in the second run will have 1 instead of 0 as the first integer in the above file names. Finally, the extension ("hd5") of the line files is determined by the variable field_value_file_extension.

Sub-variable of FieldValueRecorders: boolean append_group_index_to_file_name (default: true)

If this is set to false, the second integer in the filename (see above) and the underscore preceding it are not included in the filename. It is set to true by default. If this variable is set to false and there are multiple groups (field-value recorders), there will be a name clash, and the output will be undefined.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.3.1 Field-Value File HDF5 Content

The HDF5 file created as the output of the field-value recorder can be viewed and modified using freely-available tools. One of these tools is HDFView, provided by the HDF Group. MATLAB also has built-in functions and tools that handle HDF5 files. For reference, a MATLAB script named ‘angora_fieldvalue.m’ is distributed as part of the Angora package, which reads an Angora field-value file and plots the recorded waveform. This script is installed in the directory ‘$(prefix)/share/angora/’ (see Compilation and Installation). If Angora was installed without any $(prefix) configuration option, the default location is ‘/usr/local/share/angora/’. This script can also be downloaded directly from the Angora website (link here).

The HDF5 datasets in the field-value file are the following:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Ilker Rafet Capoglu on December 12, 2012 using texi2html 1.82.