AddingShape.md

This page describes how to add new shape, defined by a relatively small number of parameters. These shapes provide a high-level description, which is automatically discretized by ADDA into a set of dipoles (voxels). If you just want ADDA to read voxel structure from file, please consider adding support for new format of shape file instead.

All places in the code, where something should be added, are commented. These comments start with "TO ADD NEW SHAPE" and contain detailed description; the text below is less detailed. Added code should be analogous to shapes already present. The procedure is the following:

• Add new shape descriptor in the file const.h. Starting descriptor name with SH_ is recommended, as well as adding a descriptive comment.
• Add information about the new shape in the file param.c. It should be a new row in the constant array shape_opt. This line should contain: the shape name (it will be used in a command line), usage string (the description of possible input parameters), help string (it will be shown when -h option is used), possible number of parameters (real values), shape descriptor. If this shape can accept variable number of parameters use UNDEF instead of a number and then check the number of parameters explicitly in function PARSE_FUNC(shape) (below in the same file). If shape accepts a single parameter with a file name, use FNAME_ARG instead.
• Add initialization of the new shape as a new case in the long switch in function InitShape in file make_particle.c (in alphabetical order). This initialization should save all parameters from the array sh_pars to local variables, which should be defined in the beginning of the file (the place for that is shown by a comment). Then test all input parameters for consistency (for that you are encouraged to use functions from param.h since they would automatically produce informative output in case of error). If the shape breaks any symmetry, corresponding variables should be set to false. Then initialize the following variables:
  • sh_form_str – descriptive string that would be shown in the log;
  • either yx_ratio (D_y/D_x) or n_boxY (n_y);
  • either zx_ratio (D_z/D_x) or n_boxZ (n_z);
  • Nmat_need – number of different domains in this shape;
  • volume_ratio – ratio of particle volume (in units of dipoles) to n_x³, it is used for dpl correction;
  • n_boxX - grid size for the particle, defined by shape (only when relevant);
  • n_sizeX – absolute size of the particle, defined by shape (only when relevant);
  • all other auxiliary variables that are used in shape generation (below).

If you do not initialize yx_ratio and/or zx_ratio set it explicitly to UNDEF. If you need temporary local variables (which are used only in this part of the code), either use tmp1 – tmp3 or define your own (with more informative names) in the beginning of InitShape function.

• Add definition of the new shape as a new case in the long switch in function MakeParticle in file make_particle.c (in alphabetical order). This definition should set the variable mat – index of domain – for each point, specified by (xr,yr,zr) – coordinates divided by D_x. Do not set mat for void dipoles. If you need temporary local variables (which are used only in this part of the code), either use tmp1 – tmp3 or define your own (with more informative names) in the beginning of MakeParticle function.

Please refer to section Defining a Scatterer of the manual for description of the above-mentioned variables and for general overview of how the particle shape is treated inside ADDA.

If you add a new predefined shape to ADDA according to the described procedure, please consider contributing your code to be incorporated in future releases.