# Input files¶

## Parameters specified in the input file¶

In the following, the parameters which can be specified in the input file are listed:

### Length unit¶

Declare here the unit in which you want to specify all lengths. It has no influence on the calculations and can be chosen arbitrarily. This field is mainly there to remind the user that all lengths have to be specified in consistent units. In addition, it is used for the axis annotation of output plots:

```
length unit: nm
```

### Vacuum wavelength¶

The vacuum wavelength \(\lambda\) of the electromagnetic field, in the specified length unit:

```
vacuum wavelength: 550
```

### Layer system¶

Define the background geometry of the layered medium. A layer system consists of \(N\) layers, counted from bottom to top. Each layer is characterized by its thickness as well as its (real) refractive index \(n\) and extinction coefficient \(k\) (the latter is equivalent to the imaginary part of the complex refractive index \(\tilde{n}=n+jk\)). Provide the thickness information in the form of \([d_0, d_1, ..., d_N]\), where \(d_i\) is the thickness of the \(i\)-th layer. As the outermost layers are infinitely thick, specify them with a thickness of \(0\). Analogously, provide the refractive indices and extinction coefficients in the form of \([n_0, ..., n_N]\) and \([k_0, ..., k_N]\).

For example, the following entry:

```
layer system:
- thicknesses: [0, 500, 0]
refractive indices: [1.5, 2.1, 1]
extinction coefficients: [0, 0.01, 0]
```

would specify a single film of thickness \(500\), consisting of a material with complex refractive index \(n_1=2.1+0.01j\), located on top of a substrate with refractive index \(n_0=1.5\), and below air/vacuum (refractive index \(n_2=1\)).

### Scattering particles¶

The ensemble of scattering particles inside the layered medium.

For spherical particles, specify
`shape: sphere`

, the radius, refractive index, extinction coefficient
and the `[x, y, z]`

coordinates of the particle position.

For spheroids, specify
`shape: spheroid`

, the half axes along (half axis c) and transverse (half axis a) to the axis of revolution,
refractive index, extinction coefficient and the `[x, y, z]`

coordinates of the particle position, as well as the
Euler angles defining the rotation of the axis of revolution relative to the z axis (currently rotations other than
[0, 0, 0] are not implemented).

For finite cylinders, specify
`shape: finite cylinder`

, the cylinder height, cylinder radius, refractive index, extinction coefficient and the
`[x, y, z]`

coordinates of the particle position, as well as the
Euler angles defining the rotation of the axis of revolution relative to the z axis (currently rotations other than
[0, 0, 0] are not implemented).

The coordinate system is such that the interface between the first two layers defines the plane \(z=0\).

In addition, specify `l_max`

and `m_max`

, which refer to the maximal multipole degree and order used for the
spherical wave expansion of that particle’s scattered field. These parameters should be chosen with reference to the
desired accuracy and to the particle size parameter and refractive index contrast, see for example
https://arxiv.org/ftp/arxiv/papers/1202/1202.5904.pdf
A larger value leads to higher accuracy, but also to longer computation time. `l_max`

is a positive integer and
`m_max`

is a non-negative integer and not greater than `l_max`

.

In the case of non-spherical particles, you can also specify `use discrete sources`

(default is `True`

),
`nint`

(default is `200`

) and `nrank: 8`

(default is `l_max + 2`

). These parameters specify the
calculation of the T-matrix using the NFM-DS module. For further information about the meaning of these parameters, see
the NFM-DS documentation.

The parameters for the scattering particles can be listed directly in the input file, in the following format:

```
scattering particles:
- shape: sphere
radius: 100
refractive index: 2.4
extinction coefficient: 0.05
position: [0, 100, 150]
l_max: 3
m_max: 3
- shape: finite cylinder
cylinder radius: 120
cylinder height: 150
refractive index: 2.7
extinction coefficient: 0
position: [350, -100, 250]
euler angles: [0, 0, 0]
l_max: 4
m_max: 4
use discrete sources: true
nint: 200
nrank: 8
- shape: spheroid
semi axis c: 80
semi axis a: 140
refractive index: 2.5
extinction coefficient: 0.05
position: [-350, 50, 350]
euler angles: [0, 0, 0]
l_max: 3
m_max: 3
use discrete sources: true
nint: 200
nrank: 8
```

Alternatively, the scattering particles can be specified in a separate file, which needs to be located in the SMUTHI project folder. This is more convenient for large particle numbers. In that case, specify the filename of the particles parameters file, for example:

```
scattering particles: particle_specs.dat
```

The format of the particle specifications file is described below, see The particle specifications file.

### Initial field¶

Currently, only plane waves are implemented as the initial excitation.

Specify the initial field in the following format:

```
initial field:
type: plane wave
angle units: degree
polar angle: 0
azimuthal angle: 0
polarization: TE
amplitude: 1
reference point: [0, 0, 0]
```

Angle units can be ‘degree’ (otherwise, radians are used). For polarization, select either `TE`

or `TM`

.

The electric field of the plane wave in the layer from which it comes then reads

where \(A\) is the amplitude, \(\mathrm{j}\) is the imaginary unit,

is the wave vector in the layer from which the plane wave comes,
\(n_\mathrm{init}\) is the refractive index in that layer (must be real), \((\beta,\alpha)\) are the polar and azimuthal angle of the plane wave,
\(\mathbf{r_0}\) is the reference point and
\(\hat{\mathbf{e}}_j\) is the unit vector pointing into the \(\alpha\)-direction for `TE`

polarization
and into the in the \(\beta\)-direction for `TM`

polarization.

If the polar angle is in the range \(0\leq\beta\lt 90^\circ\), the k-vector has a positive \(z\)-component and consequently, the plane wave is incident from the bottom side. If the polar angle is in the range \(90^\circ\lt\beta\leq 180^\circ\), then the plane wave is incident from the top.

### Numerical parameters¶

Specify the contour of the sommerfeld integral in the complex `neff`

plane where `neff = k_parallel / omega`

refers to the effective refractive index of the partial wave. The contour is parameterized by its waypoints:

```
neff waypoints: [0, 0.5, 0.8-0.1j, 2-0.1j, 2.5, 4]
```

as well as its discretization scale:

```
neff discretization: 1e-3
```

The `neff waypoints`

define a piecewise linear trajectory in the complex plane. This trajectory should start at
`0`

and end at a suitable real truncation parameter (somewhere above the highest layer refractive index).
A simple contour would be for example `neff waypoints: [0, 4]`

. However
The trajectory can be deflected into the lower complex half plaen such that it does not come close to waveguide mode
resonances of the layer system.

### Post procesing¶

Define here, what output you want to generate. Currently, the following tasks can be defined for the post processing phase:

- evaluation of scattering and extinction cross sections
- evaluation of the electrical near field

Write for example:

```
post processing:
- task: evaluate cross sections
show plots: false
save plots: true
save data: false
- task: evaluate near field
show plots: false
save plots: true
save animations: true
save data: false
quantities to plot: [E_y, norm(E), E_scat_y, norm(E_scat), E_init_y, norm(E_init)]
xmin: -800
xmax: 800
zmin: -400
zmax: 900
spatial resolution: 50
interpolation spatial resolution: 5
maximal field strength: 1.2
```

The `show plots`

, `save plots`

and `save data`

flags deterimine, if the respective output
is plotted, if the plots are saved and if the raw data is exported to ascii files.

In the `evaluate near field`

task, the `save animations`

flags deterimines, if the near field figures are
exported as gif animations.

The `quantities to plot`

are a list of strings that can be:
`E_x`

, `E_y`

, `E_z`

or `norm(E)`

for the x-, y- and z-component or the norm of the total
electric field,
`E_scat_x`

, `E_scat_y`

, `E_scat_z`

or `norm(E_scat)`

for the x-, y- and z-component or the norm
of the scattered electric field,
or `E_init_x`

, `E_init_y`

, `E_init_z`

or `norm(E_init)`

for the x-, y- and z-component or the norm
of the initial electric field.

To specify the plane where the near field is computed, provide `xmin`

, `xmax`

, `ymin`

, `ymax`

,
`zmin`

and `zmax`

. If any of these is not given, it is assumed to be 0.
For exactly one of the coordinates x, y or z the min and max value should be identical, e.g. `ymin`

=
`ymax`

as in the above example. In that case, the field is plotted in the xz-plane.

`spatial resolution`

determines, how fine the grid of points is, where the near field is computed.
As `xmin`

etc., this parameter is specified in length units. If `interpolation spatial resolution`

is
specified, the near field will be interpolated to that finer value to allow for smoother looking field plots without the
long computing time of a fine grained actual field evaluation.

With `maximal field strength`

, you can set the color scale of the field plots to a fixed maximum.

### Further settings for the generation of output data¶

The path to the output folder can be specified as:

```
output folder: smuthi_output
```

This folder will be created and in it a subfolder with a timestamp that contains all file output of the simulation.

Finally, if:

```
save simulation: true
```

is specified, the simulation object will be saved as a binary data file from which it can be reimported at a later time.

## The particle specifications file¶

The file containing the particle specifications needs to be written in the following format:

```
# spheres
# x, y, z, radius, refractive index, exctinction coefficient, l_max, m_max
0 100 150 100 2.4 0.05 3 3
... ... ... ... ... ... ... ...
# cylinders
# x, y, z, cylinder radius, cylinder height, refractive index, exctinction coefficient, l_max, m_max
250 -100 250 120 150 2.7 0 4 4
... ... ... ... ... ... ... ... ...
# spheroids
# x, y, z, semi-axis c, semi-axis a, refractive index, exctinction coefficient, l_max, m_max
-250 0 350 80 140 2.5 0.05 3 3
... ... ... ... ... ... ... ... ...
```

An examplary particle specifiacations can be downloaded from
`here`

.

Back to main page