Keyword Substitution

In this section we parameterize the test problem of the previous section Project Setup. We want to vary the radius of the scatterer (the glass rod). For this, we rename the file layout.jcm to layout.jcmt to indicate that this file is a template .jcm file. We then replace line 23:

20
21
22
23
24
25
  # Scatterer (rod)
  Circle {
    DomainId = 2
    Radius = %(radius)e
    RefineAll = 4
  }

We give details on the syntax of this keyword substitution below. First we want to see how to use the parameterization in the driver script run.m:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
%% set problem parameter
keys.radius = 0.3;

%% run the project
results = jcmwave_solve('mie2D.jcmp', keys);

%% get scattering cross section
scattering_cross_section = ...
  results{2}.ElectromagneticFieldEnergyFlux{1};
fprintf('\nscattering cross section: %.8g\n', ...
        real(scattering_cross_section)); 

%% plot exported cartesian grid within matlab:
cfb = results{3};
amplitude = cfb.field{1};
intensity = sum(conj(amplitude).*amplitude, 3);
pcolor(cfb.X, cfb.Y, intensity); 
shading interp; view(0, 90); axis equal;

In line 2 we declare the actual parameter value. All parameter values (here it is only one) are gathered in the structure keys. In line 5, the key-value list containing the project parameter is passed to jcmwave_solve, which runs the project for the given set of parameters.

As in the previous project, you find a driver run_geo.m which only runs the mesh generation:

%% set geometry parameter
keys.radius = 0.3;

%% generate mesh file only
jcmwave_geo('.', keys);

%% open grid.jcm in JCMview
jcmwave_view('grid.jcm');

You can use this script to “play” with the radius parameter and to watch how the geometry is updated.

Syntax

Within a .jcmt file a template parameter is defined with the following type-dependent syntax:

  • %(key)d for integer parameters (also valid for arrays)
  • %(key)e for double parameters (also valid for complex double arrays)
  • %(key)s for string parameters.

key is a user-defined name of the parameter. With the syntax %(key)10e one further may set the floating point precision (here 10 digits) for a numerical parameter.

The actual parameter values must be passed to jcmwave_solve by a Matlab structure. For example, when the .jcmt input files contain the following placeholders,

%(c)e
%(lambda)d
%(k)s
%(source.eVector)e
%(material.permittivity)e

the following definitions are appropriate:

keys.c = 2.99792458e8;
keys.lambda = 550e-9;
keys.k = 2*pi/keys.lambda;
keys.source.eVector = [0 0 i];
keys.material.permittivity = [1 1e-2 0;
                              1e-2 1 0;
                              0 0 1];

The next section Parameter Scan shows how the parameterization is used to perform parameter scans.

Updated Input Files

  • layout.jcmt [ASCII]

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
    Layout {
  UnitOfLength = 1e-6

  MeshOptions {
    MaximumSidelength = 0.1
  }

  # Computational domain
  Parallelogram {
    DomainId = 1
    Width = 4
    Height = 4

    # set transparent boundary conditions
    BoundarySegment {
      BoundaryClass = Transparent
    }
  }

  # Scatterer (rod)
  Circle {
    DomainId = 2
    Radius = %(radius)e
    RefineAll = 4
  } 
}