Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/31/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

pjlaenv

Called from the ScaLAPACK symmetric and Hermitian tailored eigen-routines to choose problem-dependent parameters for the local environment.

Syntax

MKL_INT pjlaenv (const MKL_INT* ictxt, const MKL_INT* ispec, const char* name, const char* opts, const MKL_INT* n1, const MKL_INT* n2, const MKL_INT* n3, const MKL_INT* n4);

Include Files
  • mkl.h
Description

pjlaenv is called from the ScaLAPACK symmetric and Hermitian tailored eigen-routines to choose problem-dependent parameters for the local environment. See ispec for a description of the parameters. This version provides a set of parameters which should give good, though not optimal, performance on many of the currently available computers. You are encouraged to modify this subroutine to set the tuning parameters for your particular machine using the option and problem size information in the arguments.

Input Parameters
ispec

(global input) Specifies the parameter to be returned as the value of pjlaenv.

= 1: the data layout blocksize;

= 2: the panel blocking factor;

= 3: the algorithmic blocking factor;

= 4: execution path control;

= 5: maximum size for direct call to the LAPACK routine.

name

(global input) The name of the calling subroutine, in either upper case or lower case.

opts

(global input) The character options to the subroutine name, concatenated into a single character string. For example, uplo = 'U', trans = 'T', and diag = 'N' for a triangular routine would be specified as opts = 'UTN'.

n1, n2, n3, and n4

(global input) Problem dimensions for the subroutine name; these may not all be required. At present, only n1 is used, and it (n1) is used only for 'TTRD'.

Output Parameters

result

(global or local output)

>= 0: the value of the parameter specified by ispec.

< 0: if pjlaenv = -k, the k-th argument had an illegal value. Most parameters set via a call to pjlaenv must be identical on all processors and hence pjlaenv will return the same value to all procesors (i.e. global output). However some, in particular, the panel blocking factor can be different on each processor and hence pjlaenv can return different values on different processors (i.e. local output).

Application Notes

The following conventions have been used when calling pjlaenv from the ScaLAPACK routines:

  1. opts is a concatenation of all of the character options to subroutine name, in the same order that they appear in the argument list for name, even if they are not used in determining the value of the parameter specified by ispec.

  2. The problem dimensions n1, n2, n3, and n4 are specified in the order that they appear in the argument list for name. n1 is used first, n2 second, and so on, and unused problem dimensions are passed a value of -1.

    1. The parameter value returned by pjlaenv is checked for validity in the calling subroutine. For example, pjlaenv is used to retrieve the optimal blocksize for STRTRI as follows:

      NB = pjlaenv( 1, 'STRTRI', UPLO // DIAG, N, -1, -1, -1 );
      IF( NB>=1 ) {
         NB = MAX( 1, N );
      }

pjlaenv is patterned after ilaenv and keeps the same interface in anticipation of future needs, even though pjlaenv is only sparsely used at present in ScaLAPACK. Most ScaLAPACK codes use the input data layout blocking factor as the algorithmic blocking factor - hence there is no need or opportunity to set the algorithmic or data decomposition blocking factor. pXYYtevx.f and pXYYtgvx.f and pXYYttrd.f are the only codes which call pjlaenv. pXYYtevx.f and pXYYtgvx.f redistribute the data to the best data layout for each transformation. pXYYttrd.f uses a data layout blocking factor of 1.