Common Parameters

This section provides description of array parameters ipar, dpar and spar, which hold PL routine options in both Cartesian and spherical cases.

Note

Initial values are assigned to the array parameters by the appropriate ?_init_Helmholtz_2D/?_init_Helmholtz_3D/?_init_sph_p/?_init_sph_np and ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D/?_commit_sph_p/?_commit_sph_np routines.

ipar: int array of size 128, holds integer data needed for Fast Helmholtz Solver (both for Cartesian and spherical coordinate systems). Its elements are described in Table "Elements of the ipar Array":

Elements of the ipar Array
Index	Description
0	Contains status value of the last called PL routine. In general, it should be 0 to proceed with Fast Helmholtz Solver. The element has no predefined values. This element can also be used to inform the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D/?_commit_sph_p/?_commit_sph_np routines of how the Commit step of the computation should be carried out (see Figure ). A non-zero value of ipar[0] with decimal representation where each of `a`, `b`, and `c` is equal to 0 or 9, indicates that some parts of the Commit step should be omitted. If `c`=9, the routine omits checking of parameters and initialization of the data structures. If `b`=9, then in the Cartesian case, the routine omits the adjustment of the right-hand side vector f to the Neumann boundary condition (multiplication of boundary values by 0.5 as well as incorporation of the boundary function `g`) and/or the Dirichlet boundary condition (setting boundary values to 0 as well as incorporation of the boundary function `G`). In this case, the routine also omits the adjustment of the right-hand side vector f to the particular boundary functions. For the Helmholtz solver on a sphere, the routine omits computation of the spherical weights for the dpar/spar array. If `a`=9, then the routine omits the normalization of the right-hand side vector f. In the 2D Cartesian case, it is the multiplication by `hy`², where `hy` is the mesh size in the `y` direction (for details, see Poisson Library Implemented). In the 3D (Cartesian) case, it is the multiplication by `hz`², where `hz` is the mesh size in the `z` direction. For the Helmholtz solver on a sphere, it is the multiplication by `h`_θ², where `h`_θ is the mesh size in the θ direction (for details, see Poisson Library Implemented). Using ipar[0] you can adjust the routine to your needs and gain efficiency in solving multiple Helmholtz problems that differ only in the right-hand side. You must be cautious using this opportunity, because misunderstanding of the commit process may cause wrong results or program failure (see also Caveat on Parameter Modifications).
1	Contains error messaging options: ipar[1]=-1 indicates that all error messages will be printed to the file MKL_Poisson_Library_log.txt in the folder from which the routine is called. If the file does not exist, the routine tries to create it. If the attempt fails, the routine prints information that the file cannot be created to the standard output device. ipar[1]=0 indicates that no error messages will be printed. ipar[1]=1 is the default value. It indicates that all error messages will be printed to the preconnected default output device (usually, screen). In case of errors, the stat parameter will acquire a non-zero value regardless of the ipar[1] setting.
2	Contains warning messaging options: ipar[2]=-1 indicates that all warning messages will be printed to the file MKL_Poisson_Library_log.txt in the directory from which the routine is called. If the file does not exist, the routine tries to create it. If the attempt fails, the routine prints information that the file cannot be created to the standard output device. ipar[2]=0 indicates that no warning messages will be printed. ipar[2]=1 is the default value. It indicates that all warning messages will be printed to the preconnected default output device (usually, screen). In case of warnings, the stat parameter will acquire a non-zero value regardless of the ipar[2] setting.
3	Contains the number of the combination of boundary conditions. In the Cartesian case, it corresponds to the value that the BCtype parameter holds: In the 2D case, 0 corresponds to 'DDDD' 1 corresponds to 'DDDN' … 15 corresponds to 'NNNN' In the 3D case, 0 corresponds to 'DDDDDD' 1 corresponds to 'DDDDDN' ... 63 corresponds to 'NNNNNN'. The Helmholtz solver on a sphere uses this parameter only in a periodic case. The bp and bt parameters of the ?_init_sph_p/?_init_sph_np routine, which initializes ipar[3], determine its value: 0 corresponds to the problem without poles. 1 corresponds to the problem on the entire sphere.
Parameters 4 through 9 are used only in Cartesian case.
4	Takes the value of 1 if BCtype[0]='N', 0 if BCtype[0]='D', and -1 otherwise.
5	Takes the value of 1 if BCtype[1]='N', 0 if BCtype[1]='D', and -1 otherwise.
6	Takes the value of 1 if BCtype[2]='N', 0 if BCtype[2]='D', and -1 otherwise.
7	Takes the value of 1 if BCtype[3]='N', 0 if BCtype[3]='D', and -1 otherwise.
8	Takes the value of 1 if BCtype[4]='N', 0 if BCtype[4]='D', and -1 otherwise. This parameter is used only in the 3D case.
9	Takes the value of 1 if BCtype[5]='N', 0 if BCtype[5]='D', and -1 otherwise. This parameter is used only in the 3D case.
10	Takes the value of nx, that is, the number of intervals along `x`-axis, in the Cartesian case. np, that is, the number of intervals along φ-axis, in the spherical case.
11	Takes the value of ny, that is, the number of intervals along `y`-axis, in the Cartesian case nt, that is, the number of intervals along θ-axis, in the spherical case.
12	Takes the value of nz, the number of intervals along `z`-axis. This parameter is used only in the 3D case (Cartesian).
13	Takes the value of 6, which specifies the internal partitioning of the dpar/spar array.
14	Takes the value of ipar[13]+ipar[10]+1, which specifies the internal partitioning of the dpar/spar array.
Subsequent values of ipar depend upon the dimension of the problem or upon whether the solver on a sphere is periodic.
	2D case	3D case	Periodic case	Non-periodic case
15	Unused	Takes the value of ipar[14]+1, which specifies the internal partitioning of the dpar/spar array.
16	Unused	Takes the value of ipar[14]+ipar[11]+1, which specifies the internal partitioning of the dpar/spar array.
17	Takes the value of ipar[14]+1, which specifies the internal partitioning of the dpar/spar array.	Takes the value of ipar[16]+1, which specifies the internal partitioning of the dpar/spar array.
18	Takes the value of ipar[14]+3*ipar[10]/2+1, which specifies the internal partitioning of the dpar/spar array.	Takes the value of ipar[16]+3*ipar[10]/2+1, which specifies the internal partitioning of the dpar/spar array.	Takes the value of ipar[16]+3*ipar[10]/4+1, which specifies the internal partitioning of the dpar/spar array.	Takes the value of ipar[16]+3*ipar[10]/2+1, which specifies the internal partitioning of the dpar/spar array.
19	Unused	Takes the value of ipar[18]+1, which specifies the internal partitioning of the dpar/spar array.		Unused
20	Unused	Takes the value of ipar[18]+3*ipar[11]/2+1, which specifies the internal partitioning of the dpar/spar array.	Takes the value of ipar[18]+3*ipar[10]/4+1, which specifies the internal partitioning of the dpar/spar array.	Unused
Subsequent values of ipar are assigned regardless.
21	Contains message style options: ipar[21]=0 indicates that PL routines print all error and warning messages in Fortran-style notations. ipar[21]=1 (default) indicates that PL routines print the messages in C-style notations.
22	Contains the number of threads to be used for computations in a multithreaded environment. The default value is 1 in the serial mode, and the result returned by the mkl_get_max_threads function otherwise.
23 through 39	Unused in the current implementation of the Poisson Library.
40 through 59	Contain the first twenty elements of the ipar array of the first Trigonometric Transform that the Solver uses. (For details, see Common Parameters in the "Trigonometric Transform Routines" section.)
60 through 79	Contain the first twenty elements of the ipar array of the second Trigonometric Transform that the 3D and periodic solvers use. (For details, see Common Parameters in the "Trigonometric Transform Routines" section.)

Note

You may declare the ipar array in your code as int ipar[80]. However, for compatibility with later versions of Intel MKL Poisson Library, which may require more ipar values, it is highly recommended to declare ipar as int ipar[128].

Arrays dpar and spar are the same except in the data precision:

dpar

Holds data needed for double-precision Fast Helmholtz Solver computations.

For the Cartesian solver, double array of size 5*nx/2+7 in the 2D case or 5*(nx+ny)/2+9 in the 3D case; initialized in the d_init_Helmholtz_2D/d_init_Helmholtz_3D and d_commit_Helmholtz_2D/d_commit_Helmholtz_3D routines.
For the spherical solver, double array of size 5*np/2+nt+10; initialized in the d_init_sph_p/d_init_sph_np and d_commit_sph_p/d_commit_sph_np routines.

spar

Holds data needed for single-precision Fast Helmholtz Solver computations.

For the Cartesian solver, float array of size 5*nx/2+7 in the 2D case or 5*(nx+ny)/2+9 in the 3D case; initialized in the s_init_Helmholtz_2D/s_init_Helmholtz_3D and s_commit_Helmholtz_2D/s_commit_Helmholtz_3D routines.
For the spherical solver, float array of size 5*np/2+nt+10; initialized in the s_init_sph_p/s_init_sph_np and s_commit_sph_p/s_commit_sph_np routines.

As dpar and spar have similar elements in respective positions, the elements are described together in Table "Elements of the dpar and spar Arrays":

Elements of the dpar and spar Arrays
Index	Description
0	In the Cartesian case, contains the length of the interval along `x`-axis right after a call to the ?_init_Helmholtz_2D/?_init_Helmholtz_3D routine or the mesh size `h`_x in the `x` direction (for details, see Poisson Library Implemented) after a call to the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine. In the spherical case, contains the length of the interval along φ-axis right after a call to the ?_init_sph_p/?_init_sph_np routine or the mesh size `h`_φ in the φ direction (for details, see Poisson Library Implemented) after a call to the ?_commit_sph_p/?_commit_sph_np routine.
1	In the Cartesian case, contains the length of the interval along `y`-axis right after a call to the ?_init_Helmholtz_2D/?_init_Helmholtz_3D routine or the mesh size `h`_y in the `y` direction (for details, see Poisson Library Implemented) after a call to the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine. In the spherical case, contains the length of the interval along θ-axis right after a call to the ?_init_sph_p/?_init_sph_np routine or the mesh size `h`_θ in the θ direction (for details, see Poisson Library Implemented) after a call to the ?_commit_sph_p/?_commit_sph_np routine.
2	In the Cartesian case, contains the length of the interval along `z`-axis right after a call to the ?_init_Helmholtz_2D/?_init_Helmholtz_3D routine or the mesh size `h`_z in the `z` direction (for details, see Poisson Library Implemented) after a call to the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine. In the Cartesian solver, this parameter is used only in the 3D case. In the spherical solver, contains the coordinate of the leftmost boundary along θ-axis after a call to the ?_init_sph_p/?_init_sph_np routine.
3	Contains the value of the coefficient q after a call to the ?_init_Helmholtz_2D/?_init_Helmholtz_3D/?_init_sph_p/?_init_sph_np routine.
4	Contains the tolerance parameter after a call to the ?_init_Helmholtz_2D/?_init_Helmholtz_3D/?_init_sph_p/?_init_sph_np routine. In the Cartesian case, this value is used only for the pure Neumann boundary conditions ( BCtype="NNNN" in the 2D case; BCtype="NNNNNN" in the 3D case). This is a special case, because the right-hand side of the problem cannot be arbitrary if the coefficient q is zero. Poisson Library verifies that the classical solution exists (up to rounding errors) using this tolerance. In any case, Poisson Library computes the normal solution, that is, the solution that has the minimal Euclidean norm of residual. Nevertheless, the ?_Helmholtz_2D/?_Helmholtz_3D routine informs the user that the solution may not exist in a classical sense (up to rounding errors). In the spherical case, the value is used for the special case of a periodic problem on the entire sphere. This special case is similar to the above described Cartesian case with pure Neumann boundary conditions. So, here Poisson Library computes the normal solution as well. The parameter is also used to detect whether the problem is periodic up to rounding errors. The default value for this parameter is 1.0E-10 in case of double-precision computations or 1.0E-4 in case of single-precision computations. You can increase the value of the tolerance, for instance, to avoid the warnings that may appear.
ipar[13]-1 through ipar[14]-1	In the Cartesian case, contain the spectrum of the 1D problem along `x`-axis after a call to the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine. In the spherical case, contains the spectrum of the 1D problem along φ-axis after a call to the ?_commit_sph_p/?_commit_sph_np routine.
ipar[15]-1 through ipar[16]-1	In the Cartesian case, contain the spectrum of the 1D problem along `y`-axis after a call to the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine. These elements are used only in the 3D case. In the spherical case, contains the spherical weights after a call to the ?_commit_sph_p/?_commit_sph_np routine.
ipar[17]-1 through ipar[18]-1	Take the values of the (staggered) sine/cosine in the mesh points: along `x`-axis after a call to the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine for a Cartesian solver along φ-axis after a call to the ?_commit_sph_p/?_commit_sph_np routine for a spherical solver.
ipar[19]-1 through ipar[20]-1	Take the values of the (staggered) sine/cosine in the mesh points: along `y`-axis after a call to the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine for a Cartesian 3D solver along φ-axis after a call to the ?_commit_sph_p routine for a spherical periodic solver. These elements are not used in the 2D Cartesian case and in the non-periodic spherical case.

Note

You may define the array size depending upon the type of the problem to solve.

Caveat on Parameter Modifications

Flexibility of the PL interface enables you to skip calling the ?_init_Helmholtz_2D/?_init_Helmholtz_3D/?_init_sph_p/?_init_sph_np routine and to initialize the basic data structures explicitly in your code. You may also need to modify contents of ipar, dpar and spar arrays after initialization. When doing so, provide correct and consistent data in the arrays. Mistakenly altered arrays cause errors or wrong computation. You can perform a basic check for correctness and consistency of parameters by calling the ?_commit_Helmholtz_2D/?_commit_Helmholtz_3D routine; however, this does not ensure the correct solution but only reduces the chance of errors or wrong results.

Note

To supply correct and consistent parameters to PL routines, you should have considerable experience in using the PL interface and good understanding of the solution process as well as elements that the ipar, spar and dpar arrays contain and dependencies between values of these elements.

However, in rare occurrences, even advanced users might fail in tuning parameters for the Fast Helmholtz Solver. In cases like these, refer for technical support at http://www.intel.com/software/products/support/ .

Warning

The only way that ensures a proper solution of a Helmholtz problem is to follow a typical sequence of invoking the routines and not change the default set of parameters. So, avoid modifications of ipar, dpar and spar arrays unless a strong need arises.