# Sequence of Invoking PL Routines

### Note

This description always considers the solution process for the Helmholtz problem, because Fast Poisson Solver and Fast Laplace Solver are special cases of Fast Helmholtz Solver (see Poisson Library Implemented).

Computation of a solution of the Helmholtz problem using the PL interface is conceptually divided into four steps, each of which is performed via a dedicated routine. Table “PL Interface Routines” lists the routines and briefly describes their purpose.

Most PL 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 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`”

PL Interface Routines
Routine | Description
--- | ---
?_init_Helmholtz_2D/?_init_Helmholtz_3D/?_init_sph_p/?_init_sph_np | Initializes basic data structures of Poisson Library 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 user's data, creates and initializes data structures to be used by the Intel MKL FFT interface1, as well as other data structures needed for the solver.
?_Helmholtz_2D/?_Helmholtz_3D/?_sph_p/?_sph_np | Computes an approximate solution of 2D/3D/periodic/non-periodic Helmholtz problem (see Poisson Library Implemented) specified by the parameters.
free_Helmholtz_2D/free_Helmholtz_3D/free_sph_p/free_sph_np | Cleans the memory used by the data structures needed for calling the Intel MKL FFT interface1.

1 PL routines call the Intel MKL FFT interface for better performance.

To find an approximate solution of Helmholtz problem only once, the Intel MKL PL interface routines are normally invoked in the order in which they are listed in Table “PL Interface Routines”.

### Note

Though the order of invoking PL routines may be changed, it is highly recommended to follow the above order of routine calls.

The diagram in Figure “Typical Order of Invoking PL Routines” indicates the typical order in which PL routines can be invoked in a general case.

Typical Order of Invoking PL Routines

A general scheme of using PL routines for double-precision computations in a 3D Cartesian case is shown below. A similar scheme holds for single-precision computations with the only difference in the initial letter of routine names. The general scheme in a 2D Cartesian case differs form the one below in the set of routine parameters and the ending of routine names: “2D” instead of “3D”.

...

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 stored in f,

save it 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 PL routines for double-precision computations in a spherical periodic case is shown below. Similar scheme holds for single-precision computations with the only difference in the initial letter of routine names. The general scheme in a spherical non-periodic case differs from the one below in the set of routine parameters and the ending of routine names: “np” instead of “p”.

...

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 stored in f, save it 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 Fortran 90 and C code that use PL routines to solve Helmholtz problem (in both Cartesian and spherical cases) in Poisson Library Code Examples in the “Code Examples” Appendix.

Parent topic: Poisson Library Routines