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

6.5 Simulation Space

Global variable: group SimulationSpace

The SimulationSpace group is where all the objects inside the simulation space are defined. If no SimulationSpace group is specified in the configuration file, the FDTD simulation space consists entirely of vacuum.

 
SimulationSpace:
{
    Objects:
    (
        …
        …
    );
    RandomMaterials:
    {
        …
        …
    };

    …
    …

};

In the above example, only two of the sub-variables of the SimulationSpace group, Objects and RandomMaterials, are shown. The sub-variable Objects is a list (see Lists), whereas RandomMaterials is a group (see Groups).

The definitions in the SimulationSpace group are processed in the order of placement. Thus, the user has complete control over which object is placed in the simulation space first. As a consequence of this first-come-first-serve policy, objects can overwrite regions of the simulation space occupied by other objects.


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

6.5.1 Objects

Sub-variable of SimulationSpace: list Objects

The Objects list defines material objects to be placed in the simulation grid. An object in this context is defined as a combination of two abstract ingredients: A previously-defined shape (see Shapes), and a previously-defined material to fill that shape (see Materials). The shape and material are referred to using their shape and material tags, which are string variables assigned to them in their definitions.

Here is an example:

 
SimulationSpace:
{
    Objects:
    (
        {
            material_tag = "this_material";
            shape_tag = "mysphere";
        },
        {
            …
            …
        }
    );
};
Sub-variable of Objects: string material_tag

This string variable specifies the material that makes up the object. It should match a previously-defined tag in a Materials definition (see section Materials).

Sub-variable of Objects: string shape_tag

This string variable specifies the geometrical shape of the object. It should match a previously-defined tag in a Shapes definition (see section Shapes).


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

6.5.2 Planar Layers

Sub-variable of SimulationSpace: list MaterialSlabs

The purpose of the MaterialSlab list is to introduce planar stratification into the simulation grid. Currently, Angora only supports planar stratification along the z direction. The handling of planar layers will be further improved in the future. Please send any comments, suggestions, and requests to help@angorafdtd.org.

Here is an example:

 
SimulationSpace:
{
    MaterialSlabs:
    (
        {
            material_tag = "material1";
            min_coord = 1e-6;
            max_coord = "max";
        },
        {
            …
            …
        }
    );
};

In the above example, a material slab composed of material1 is placed in the grid.

Sub-variable of MaterialSlabs: string material_tag

This variable specifies the material that makes up the slab. It should match a previously-defined tag in a Materials definition (see section Materials).

Sub-variable of MaterialSlabs: floating-point/string min_coord
Sub-variable of MaterialSlabs: floating-point/string max_coord
Sub-variable of MaterialSlabs: integer/string min_coord_in_cells
Sub-variable of MaterialSlabs: integer/string max_coord_in_cells

These two floating-point variables specify the lower and upper coordinates of the material slab with respect 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. These variables can also be assigned the string values "min" or "max"; which correspond to the lower and upper boundaries of the simulation grid, respectively. If the coordinates correspond to non-integer cell positions, they are rounded to the nearest multiple of the spatial step size. However, the tangential components of the electric tensor properties and the normal component of the magnetic tensor properties are suitably interpolated (see Hwang01).

If the FDTD grid is terminated by absorbing PML boundaries (see Perfectly-Matched Layer (PML)), then the MaterialSlab definitions effectively create infinite planar layers that extend horizontally toward infinity. When the "min" or "max" strings are assigned as lower or upper coordinates of the slab, the MaterialSlab definition amounts to placing a half space. When the MaterialSlab variable is used, the incident beams (see Incident Beams) and the scattered far field (see Near-Field-to-Far-Field Transformer) are both calculated as if the material slab horizontally extends toward infinity.


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

6.5.3 Random Materials

Sub-variable of SimulationSpace: group RandomMaterials

Independent samples from a random distribution of material properties with a specified correlation function can be generated and placed into the simulation grid using the RandomMaterials group. It contains sub-variables in the form of lists (see Lists) that correspond to specific correlation functions. Currently, only the Whittle-Matern family of correlation functions is supported. More correlation functions can be added in the future. Please send any comments, suggestions, and requests to help@angorafdtd.org.

Although the spatial correlation of the generated random material regions can vary, the joint probability density function of the material region is always a multivariate normal (Gaussian) function.

Sub-variable of RandomMaterials: list WhittleMaternCorrelated

The Whittle-Matern family of correlations (see Rogers09) is a three-parameter isotropic stochastic model that can represent a wide range of spatial correlations. The Whittle-Matern correlation function $B(r)$ for two points separated in space by a distance of $r$ is given by the formula

\begin{displaymath}
B(r) = \sigma^{2}
{{2^{5/2-m}(r/l_c)^{m-3/2}}\over{\Gamma(m-3/2)}}
K_{m-3/2}(r/l_c)\
\end{displaymath}

where $K_{m-3/2}(\cdot)$ is the modified Bessel function of the second kind and order (m-3/2).

  • $m$: The shape parameter that determines the overall behavior of the correlation function. As m->infinity, the function approaches a Gaussian distribution. If m=2, the function reduces to a decaying exponential. For m<3/2, the distribution acquires an inverse power law dependence near the origin; approximating a fractal distribution. For more details, see Rogers09.
  • $l_c$: (For m>3/2:) The correlation length. (For m<=3/2:) Loosely, the outer length scale where the fractal approximation no longer holds.
  • $\sigma$: (For m>3/2:) The standard deviation of the distribution at a given point (r=0). (For m<=3/2:) In this range, the correlation function enters the fractal regime with an inverse-power-law dependence at the origin (see Rogers09). The meaning of $\sigma$ becomes more subtle in this regime. It can loosely be associated with the amplitude of the correlation between two points separated by $l_c$.

The WhittleMaternCorrelated list creates regions with random material properties described by the Whittle-Matern correlation function above. Here is an example of its usage:

 
SimulationSpace:
{
    RandomMaterials:
    {
        WhittleMaternCorrelated:
        (
            {
                constitutive_param_type = "rel_permittivity";
                mean = 1.33;
                std_dev = 0.05;
                corr_len = 100e-9;
                m = 2.0;
                shape_tag = "rand_mat_shape";
                random_seed = 0;
            },
            {
                …
                …
            }
        );
    };

};
Sub-variable of WhittleMaternCorrelated: string constitutive_param_type

The Whittle-Matern correlation function can describe the relative permittivity, relative permeability, electric conductivity (in Siemens/m), or magnetic conductivity (Ohm/m) of the material region. This is specified by assigning "rel_permittivity", "rel_permeability", "electric_conductivity", or "magnetic_conductivity" to the constitutive_param_type string variable.

The constitutive parameters other than the one specified are not changed. As a result, different random constitutive parameter distributions can be superimposed using multiple random material definitions:

 
SimulationSpace:
{
    RandomMaterials:
    {
        WhittleMaternCorrelated:
        (
            {
                constitutive_param_type = "rel_permittivity";
                mean = 1.33;
                std_dev = 0.05;
                corr_len = 100e-9;
                m = 2.0;
                shape_tag = "rand_mat_shape";
            },
            {
                constitutive_param_type = "rel_permeability";
                mean = 1.1;
                std_dev = 0.05;
                corr_len = 100e-9;
                m = 2.0;
                shape_tag = "rand_mat_shape";
            }
        );
    };

};

Here, a random permittivity distribution and a random permeability distribution are overlaid within the same region in the grid.

Sub-variable of WhittleMaternCorrelated: floating-point mean (units: none or S/m)

A baseline constant value equal to mean is added to the constitutive parameter described by the Whittle-Matern correlation function. If mean=0, then the generated random distribution will have zero mean. However, this will not necessarily be reflected to the actual constitutive parameter values in the grid; since Angora will automatically clip the constitutive parameters (permittivity, permeability, conductivity, etc.) from below to either unity or zero to avoid instabilities. For this reason, mean should be high enough to avoid this clipping as much as possible. As a rule of thumb, mean should be 5 to 6 times the standard deviation (std_dev) above unity or zero.

Sub-variable of WhittleMaternCorrelated: floating-point std_dev (units: none or S/m)

This variable specifies the $\sigma$ parameter in the definition of the Whittle-Matern correlation function.

Sub-variable of WhittleMaternCorrelated: floating-point corr_len (units: m)
Sub-variable of WhittleMaternCorrelated: floating-point corr_len_in_cells

This variable specifies the $l_c$ parameter in the definition of the Whittle-Matern correlation function. The units are either in meters or grid cells. For the latter, the _in_cells suffix should be appended to the variable name.

Sub-variable of WhittleMaternCorrelated: floating-point m

This variable specifies the $m$ parameter in the definition of the Whittle-Matern correlation function.

Sub-variable of WhittleMaternCorrelated: string shape_tag

This string variable specifies the geometrical shape of the region occupied by the random material. It should match a previously-defined tag in a Shapes definition (see section Shapes).

Sub-variable of WhittleMaternCorrelated: integer/string random_seed (default: determined by system time)

If you would like to create exactly the same random distribution each time the simulation is run, you can assign an integer value to the random_seed variable. Otherwise, you should not define this variable. This value is used to initialize the random-number generator in Angora. If the same seed is used to initialize the random-number generator, the same sequence of random numbers will be generated each time, resulting in the same random distribution.

If multiple simulation runs are present (see Multiple Simulation Runs), you can create different random samples for each simulation run by assigning the string value "run_index" to random_seed. This will initialize the intenal random-number generator with the run index (ranging from 0 to number_of_runs-1) of each run. This way, a different random distribution will be obtained in each simulation run; but a distribution for a given simulation run will be fixed in subsequent executions of Angora.

In this figure, a 2D slice of an example zero-mean sample distribution generated by WhittleMaternCorrelated is shown in grayscale.

random_sample

Figure 6.2: A 2D slice of an example zero-mean sample distribution. This distribution can be assigned to different constitutive parameters of a material.


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

6.5.4 File Input

Sub-variable of SimulationSpace: list MaterialsFromFiles

Material information within rectangular regions of the FDTD simulation grid can be read from files using a MaterialsFromFiles list. This feature of Angora is still under development. The user interface for this feature may change in the future, or be superseded by another, more general interface. Currently, only a single constitutive parameter can be read from a file; and dispersive or anisotropic materials are not supported. These issues will be handled more comprehensively in a future version. Please send any comments, suggestions, and requests to help@angorafdtd.org.

The material file should be in a simple custom binary format that Angora can recognize. The order and type of each variable in the file is explained below:

Here is an example usage of MaterialsFromFiles:

 
SimulationSpace:
{
    MaterialsFromFiles:
    (
        {
            file_name = "path_to_file/materialfile";
            append_run_index_to_name = true;
            file_extension = "mat";
            constitutive_param_type = "rel_permittivity";
            anchor = "center";
            coord_x = 0;
            coord_y = 0;
            coord_z = 0;
            datatype = "double";
            max_new_materials = 1000;
        },
        {
            …
            …
        }
    );
};
Sub-variable of MaterialsFromFiles: string file_name

This string specifies the name of the binary file from which the material information will be read. Path information can be prepended to the file name, as shown in the example above. This path is interpreted as being relative to input_dir (see Paths), unless it is preceded by a slash ‘/’.

Sub-variable of MaterialsFromFiles: string file_extension (default: "")

This is the extension of the material file to be read. In the above example, the file to be read is ‘path_to_file/materialfile.mat’.

Sub-variable of MaterialsFromFiles: boolean append_run_index_to_name

This boolean flag becomes useful if there are multiple simulation runs (see Multiple Simulation Runs), and a different file needs to be read in each run. This can be accomplished by appending the run index (which ranges from 0 to number_of_runs-1) to the file name specified by file_name. For example, if there are 3 simulation runs (number_of_runs is 3) the above assignment will tell Angora to read the file ‘path_to_file/materialfile0.mat’ in the first run, ‘path_to_file/materialfile1.mat’ in the second, and ‘path_to_file/materialfile2.mat’ in the third.

This variable is required for all simulations (hence no default value) to help the user prevent easy mistakes such as reading the same file for all simulation runs unintentionally, reading ‘path_to_file/materialfile0.mat’ instead of ‘path_to_file/materialfile.mat’, etc.

Sub-variable of MaterialsFromFiles: string constitutive_param_type

The values read from the input file can be assigned to one of the following constitutive parameters: relative permittivity, relative permeability, electric conductivity, or magnetic conductivity. This is determined by assigning "rel_permittivity", "rel_permeability", "electric_conductivity", or "magnetic_conductivity" to the constitutive_param_type string variable. Electric conductivity is assumed to be in Siemens/m, and magnetic conductivity is assumed to be in Ohm/m.

The constitutive parameters other than the one specified are not changed. As a result, different constitutive parameter distributions can be superimposed using multiple file-input definitions:

 
SimulationSpace:
{
    MaterialsFromFiles:
    (
        {
            file_name = "permittivity_file";
            append_run_index_to_name = true;
            constitutive_param_type = "rel_permittivity";
            coord_x = 0;
            coord_y = 0;
            coord_z = 0;
            datatype = "double";
        },
        {
            file_name = "conductivity_file";
            append_run_index_to_name = true;
            constitutive_param_type = "electric_conductivity";
            coord_x = 0;
            coord_y = 0;
            coord_z = 0;
            datatype = "double";
        }
    );
};

Here, the contents of the files ‘permittivity_file’ and ‘conductivity_file’ are interpreted as the relative permittivity and electric conductivity of the same region, respectively.

Sub-variable of MaterialsFromFiles: string anchor (default: "center")

This string defines an anchor point inside the rectangular-box-shaped region that is to be read from this file. This anchor is then assigned a coordinate in the FDTD grid, determining the position of the rectangular box in the grid. Valid values for anchor are:

  • "center": center of the box
  • "BLL": back-left-lower corner of the box
  • "BLU": back-left-upper corner of the box
  • "BRL": back-right-lower corner of the box
  • "BRU": back-right-upper corner of the box
  • "FLL": front-left-lower corner of the box
  • "FLU": front-left-upper corner of the box
  • "FRL": front-right-lower corner of the box
  • "FRU": front-right-upper corner of the box

Here, as usual, "back"/"front" refers to the x coordinate, "left"/"right" refers to the y coordinate, and "lower"/"upper" refers to the z coordinate.

Sub-variable of MaterialsFromFiles: floating-point coord_x (units: m)
Sub-variable of MaterialsFromFiles: floating-point coord_y (units: m)
Sub-variable of MaterialsFromFiles: floating-point coord_z (units: m)
Sub-variable of MaterialsFromFiles: integer coord_x_in_cells
Sub-variable of MaterialsFromFiles: integer coord_y_in_cells
Sub-variable of MaterialsFromFiles: integer coord_z_in_cells

These values determine the Cartesian x,y, and z coordinates of the anchor point (see above) assigned to the rectangular region to be read from the file. The coordinates are measured with respect 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 coordinates correspond to non-integer cell positions, the closest integer positions are chosen.

Sub-variable of MaterialsFromFiles: string datatype

The datatype for the values read from the file is determined by this variable. It should be either "double" (8 bytes) or "float" (4 bytes).

Sub-variable of MaterialsFromFiles: integer max_new_materials (default: 1000)

Internally, Angora uses material indexing to reduce memory use for material arrays. Every constitutive parameter in the grid can only take a distinct set of values, represented by a variable of type unsigned short (2 bytes) that can range from 0 to 65,535. Instead of storing a floating-point value (which is usually 4 or 8 bytes) for a permittivity value at a point, Angora stores an index that represents the permittivity at that point. The same applies to other constitutive parameters (relative permeability, electric conductivity, etc.)

Each time a material region is read into the FDTD grid using MaterialsFromFiles, a fixed number of new constitutive parameter values are defined between the minimum and maximum values found in the file. Because of this discretization, some loss of information is inevitable. The number of new materials is determined by the variable max_new_materials; which is by equal to 1000 default. With the default value, the upper limit for the number of materials will be reached after about 65 material regions are inserted into the grid. If you wish to insert more material regions, and the dynamic ranges of constitutive parameters in your material files are not large, you can decrease max_new_materials. Alternatively, you may consider combining multiple material regions into a single region.


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

6.5.5 Ground Planes

Sub-variable of SimulationSpace: list GroundPlanes

Infinitely thin perfect-electric-conductor (PEC) sheets can be placed in the grid using a GroundPlanes list. Currently, only z-oriented (parallel to the xy plane) sheets at integer (full-cell) positions are supported.

 
SimulationSpace:
{
    GroundPlanes:
    (
        {
            coord = 0;
        },
        {
            …
            …
        }
    );
};
Sub-variable of GroundPlanes: floating-point coord (units: m)
Sub-variable of GroundPlanes: integer coord_in_cells

This variable specifies the z-coordinate of the ground plane with respect 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.

The GroundPlanes variable also updates the layering (stratification) information in the grid, much like MaterialSlabs (see section Planar Layers).


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

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