Developer Reference for Intel® oneAPI Math Kernel Library for C
Sequence of Invoking Poisson Solver Routines
The Poisson Solver interface enables you to compute a solution of the Helmholtz problem in four steps. Each step is performed by a dedicated routine. The table Poisson Solver Interface Routines lists the routines and briefly describes their purpose.
Most Poisson Solver routines have versions operating with single-precision and double-precision data. Names of such routines begin respectively with s and d. The wildcard “?” stands for either of these symbols in routine names. The routines for the Cartesian coordinate system have 2D and 3D versions. Their names end respectively in 2D and 3D. The routines for spherical coordinate system have periodic and non-periodic versions. Their names end respectively in p and np.
Routine |
Description |
|---|---|
?_init_Helmholtz_2D/?_init_Helmholtz_3D / ?_init_sph_p/?_init_sph_np |
Initializes basic data structures for Fast Helmholtz Solver in the 2D/3D/periodic/non-periodic case, respectively. |
?_commit_Helmholtz_2D/?_commit_Helmholtz_3D / ?_commit_sph_p/?_commit_sph_np |
Checks consistency and correctness of input data and initializes data structures for the solver, including those used by the Intel® oneAPI Math Kernel Library (oneMKL) FFT interface 1. |
Computes an approximate solution of the 2D/3D/periodic/non-periodic Helmholtz problem (see Poisson Solver Implementation) specified by the parameters. |
|
free_Helmholtz_2D/free_Helmholtz_3D / free_sph_p/free_sph_np |
Releases the memory used by the data structures needed for calling the Intel® oneAPI Math Kernel Library (oneMKL) FFT interface 1. |
- [1]
-
Poisson Solver routines call the Intel® oneAPI Math Kernel Library (oneMKL) FFT interface for better performance.
To find an approximate solution of Helmholtz problem only once, the Intel® oneAPI Math Kernel Library (oneMKL) Poisson Solver interface routines are normally invoked in the order in which they are listed in the table Poisson Solver Interface Routines.
The diagram in the figure Typical Order of Invoking Poisson Solver Routines indicates the typical order in which Poisson Solver routines can be invoked in a general case.
Typical Order of Invoking Poisson Solver Routines
Initialize
|
|<--------------------+
| |
Change routine parameters (manually) |
| |
Commit |
| |
|<--------------------+
| |
Fast Helmholtz Solver |
| |
|<--------------------+
|
Free memoryA general scheme of using Poisson Solver routines for double-precision computations in a 3D Cartesian case is shown below. You can change this scheme to a scheme for single-precision computations by changing the initial letter of the Poisson Solver routine names from “d” to “s”. You can also change the scheme below from the 3D to 2D case by changing the ending of the Poisson Solver routine names.
// ...
d_init_Helmholtz_3D(&ax, &bx, &ay, &by, &az, &bz, &nx, &ny, &nz, BCtype, ipar, dpar, &stat);
// change parameters in ipar and/or dpar if necessary.
// note that the result of the Fast Helmholtz Solver will be in f.
// If you want to keep the data that is stored in f,
// save it to another location before the function call below
d_commit_Helmholtz_3D(f, bd_ax, bd_bx, bd_ay, bd_by, bd_az, bd_bz, &xhandle, &yhandle, ipar, dpar, &stat);
d_Helmholtz_3D(f, bd_ax, bd_bx, bd_ay, bd_by, bd_az, bd_bz, &xhandle, &yhandle, ipar, dpar, &stat);
free_Helmholtz_3D (&xhandle, &yhandle, ipar, &stat);
// here you may clean the memory used by f, dpar, ipar
// ...A general scheme of using Poisson Solver routines for double-precision computations in a spherical periodic case is shown below. You can change this scheme to a scheme for single-precision computations by changing the initial letter of the Poisson Solver routine names from “d” to “s”. You can also change the scheme below to a scheme for a non-periodic case by changing the ending of the Poisson Solver routine names from “p” to “np”.
// ...
d_init_sph_p(&ap,&bp,&at,&bt,&np,&nt,&q,ipar,dpar,&stat);
// change parameters in ipar and/or dpar if necessary.
// note that the result of the Fast Helmholtz Solver will be in f.
// If you want to keep the data that is stored in f,
// save it to another location before the function call below
d_commit_sph_p(f,&handle_s,&handle_c,ipar,dpar,&stat);
d_sph_p(f,&handle_s,&handle_c,ipar,dpar,&stat);
free_sph_p(&handle_s,&handle_c,ipar,&stat);
// here you may clean the memory used by f, dpar, ipar
// ...You can find examples of code that uses Poisson Solver routines to solve Helmholtz problem (in both Cartesian and spherical cases) in the c/pdepoisson/source directory within the share/doc/mkl/examples/examples_core_c.tgz archive in your Intel® oneAPI Math Kernel Library (oneMKL) installation directory.