FAQ

This list is far from being complete, therefore please send your questions to adda-discuss@googlegroups.com.

• General
  • What is the official name of the code?
  • I am new to ADDA and want to simulate ... What should I start with?
  • How to actually run ADDA?
  • Do you have GUI/wrapper for ADDA? Can ADDA plot its results?
• Defining scattering problem
  • How to simulate light scattering by a particle which shape can not be described by any of the ADDA predefined shapes?
  • How to visualize shape files of ADDA?
  • How to simulate scattering of a beam, which is not implemented as one of ADDA predefined options?
  • How to simulate light scattering by a particle embedded in a homogeneous non-absorbing medium?
  • How to calculate scattering by a particle near or inside the infinite plane-parallel plane substrate?
• Calculated quantities
  • How is the Mueller matrix, produced by ADDA, defined and/or normalized?
  • How to calculate near-field using ADDA?
  • How to calculate the wavelength spectrum of extinction/scattering/etc.?
• Troubleshooting
  • I run ADDA and get strange output (different from my expectations)
  • Iterative solver breaks down
  • I have found a bug in ADDA

General

What is the official name of the code?

It is ADDA, traditionally pronounced /ˈɑddɑ/.

I am new to ADDA and want to simulate ... What should I start with?

• Read Home and other pages it links to.
• In particular, go through the Tutorial to understand basic ADDA functionality.
• Scan through the manual to understand where to get more details if needed.

How to actually run ADDA?

ADDA is a console application, which should be run from a terminal (not by clicking the mouse). On Windows either use built-in cmd.exe or install one of Linux-type shells (like MSYS Bash or Git Bash) or FAR File Manager. Most simulation parameters are specified from the command line, try adda -h for a start. You can also run ADDA through a system call from any programming/scripting language.

Do you have GUI/wrapper for ADDA? Can ADDA plot its results?

Yes, we do offer Java-based GUI for beginning users. Also a few other wrappers are available. Note, however, that development of ADDA is focused on its core functionality (that is efficient and large-scale simulations of interaction of electromagnetic waves with particles). Any kind of pre- and post-processing can be implemented by scripts or independent programs without changing the core code. Some examples can be found in misc/ folder.

Defining scattering problem

How to simulate light scattering by a particle which shape can not be described by any of the ADDA predefined shapes?

The simplest is to specify your particle by a shape file. This file can be produced any programming language/software, but a number of available options are listed here. ADDA itself contains a couple of auxiliary packages to produce shape files:

• Point-in-polyhedron (misc/pip, see description) allows transformation of .obj format (and several other common 3D formats) into the format readable by ADDA.
• Hyperfun (misc/hyperfun, see description) provides a toolchain for working with Hyperfun models.

Finally, if your shape can be easily described in some parametric form and you are going to simulate a lot of particles with shapes from this class or if you think other users will probably simulate the same shapes, you are encouraged to implement it inside ADDA.

How to visualize shape files of ADDA?

A general solution for Windows is freely available software LiteBil. It allows both quick testing of shape files produced by ADDA or other software, and producing nice pictures for publication. Visualization of built-in shapes (varying their parameters) is possible with ADDA GUI for any OS. Other options, including Python scripts are discussed in this discussion.

How to simulate scattering of a beam, which is not implemented as one of ADDA predefined options?

The simplest is to specify your incident field by a beam file. This file can be produced any programming language/software, but some available options are listed here. Moreover, if you are going to run a lot of simulations with beams from this class or if you think other users will probably find this beam class useful, you are encouraged to implement it inside ADDA.

How to simulate light scattering by a particle embedded in a homogeneous non-absorbing medium?

Just apply ADDA to an equivalent problem of a particle in vacuum with both wavelength and particle refractive index divided by the refractive index of the medium. Most of the calculated scattering quantities can then be used without modification. See section Applicability of the DDA of the manual for details.

How to calculate scattering by a particle near or inside the infinite plane-parallel plane substrate?

Starting from v.1.3b4 ADDA can rigorously and efficiently handle particles near the plane homogeneous substrate. Possible approximate approaches for more complicated cases, like multi-layered substrates or particles crossing the substrate, are discussed in Section Extensions of the DDA of the manual. See also remaining issues.

Calculated quantities

How is the Mueller matrix, produced by ADDA, defined and/or normalized?

It is defined as in Bohren & Huffman "Absorption and scattering of Light by Small Particles" (1983), and it is not normalized. Some other codes may compute Stokes scattering matrix, which is normalized so that 1,1-element is equal to 1 after averaging over the whole solid angle. This matrix should be multiplied by πC_sca/λ² to get Mueller matrix. C_sca is the scattering cross section for unpolarized light, equal to average of scattering cross sections for any two perpendicular incident polarizations. See section Mueller matrix of the manual for more details.

How to calculate near-field using ADDA?

We are currently working to implement this feature in a convenient manner (#10). For now there are two possible workarounds:

• (Recommended) You may save dipole polarizations to file by ADDA and then use auxiliary package misc/near_field (see description).
• Or you may extend the computational box with "dummy" dipoles located at points where you wish to calculate near-field (for a rectangular grid, see embed_and_join from ADDA geometry tools). Saving the internal fields by ADDA will then produce the desired result, but at expense of extra computational time. Please see the section Near-field of the manual for details.

How to calculate the wavelength spectrum of extinction/scattering/etc.?

Currently there is no automatic way to do it, although we plan to implement it (#35). Currently one may either perform separate simulation for each value of wavelength, or semi-automate this process by some kind of script or wrapper. The latter options are discussed in comments to #35.

Troubleshooting

I run ADDA and get strange output (different from my expectations)

• Make sure you are using the latest version of ADDA. Read carefully the relevant parts of the manual.
• Check this FAQ.
• If that does not help, you're encouraged to send your question to adda-discuss@googlegroups.com. Please try to make your question as specific as possible. If your question is based on a particular run, provide all relevant input and output files, at least log.

Iterative solver breaks down

Iterative solvers work reliably in the vast majority of cases. However, they are not guaranteed to converge always, which you may notice, e.g., when performing a lot of ADDA simulations (massive parameter sweeps). There are two types of break down:

• Random (or bad-luck) breakdowns happen for a certain unexpected combination of parameters. Usually, ADDA produces error message like <solver> fails: <parameter> is too small (<value>). Try to vary the simulation parameter (particle size or refractive index) by as small as 0.01%. Alternatively, use an iterative solver from a different family, e.g., Bi-CGStab or CSYM instead of the default QMR. Such change also helps for certain Bessel beams with very small half-cone angles (e.g., CS', TEL, and TML beams of order 2), which are almost proportional to circularly-polarized plane waves.
• Stagnation with message like Residual norm haven't decreased for maximum allowed number of iteration (<value>). This usually means that ADDA has reached its applicability limit in terms of particle sizes (relative to the wavelength) and refractive indices. Trying different iterative solvers may help somewhat, but there is no easy way to significantly extend the applicability limit. Increasing imaginary part of the refractive index (adding absorption) usually improves the convergence of the iterative solver. Note, however, that in rare cases the stagnation is caused by breakdown which is not properly detected by ADDA. Thus, trying the above advice for breakdowns is also an option.

More details are given in Section Iterative solver of the manual.

I have found a bug in ADDA

• Make sure you are using the latest version of ADDA. If you modified the code yourself, try the original release.
• Look at the list of known bugs at the issue tracker, maybe your bug is already known.
• Try to understand how exactly the bug occurs, write down the sequence of actions that lead to it.
• Please try to localize the bug, i.e. try to remove as much command line parameters as possible without removing the bug. Also try to use default versions of input files, which you have modified.
• Submit your bug to the issue tracker, including input files and makefiles that you used for compilation (if you changed any of the latter). Do not forget to include all the relevant output files, at least log. Please also include a brief description of your operation system and hardware. We will try to fix the bug as soon as possible.