C H A P T E R  1

Introduction

This chapter contains a quick-reference index to the routines in the Sun Scalable Scientific Subroutine Library (Sun S3L). The routines are organized into two tables:



Note - Many Sun S3L computational routines support the ScaLAPACK version 1.6 and PBLAS version 1.0 application programming interfaces (APIs). TABLE 1-3 lists the ScaLAPACK and PBLAS APIs that are supported.




Sun S3L Overview

TABLE 1-1 Sun S3L Core Mathematical Routines

Function

Description

Dense Matrix Operations

 

S3L_2_norm()
S3L_inner_prod()
S3L_mat_mult()
S3L_mat_vec_mult()
S3L_outer_prod()

Compute 2-norm of a vector.
Compute inner product of two vectors.
Compute product of two matrices.
Compute product of a matrix and vector.
Compute outer product of two vectors.

Sparse Matrix Operations

 

S3L_declare_sparse()
S3L_free_sparse()
S3L_convert_sparse()

S3L_rand_sparse()

S3L_matvec_sparse()

S3L_read_sparse()
S3L_write_sparse()
S3L_print_sparse()

Create an S3L handle for an S3L sparse array.
Free memory allocated to S3L sparse array.
Convert an S3L array from one sparse format
to another.
Create an S3L array with random values and
sparsity.
Compute the product of a sparse matrix and dense vector.
Read a sparse matrix from an ASCII file.
Write a sparse matrix to a file.
Print all nonzero values from a sparse matrix.

Gaussian Elimination for Dense Systems

 

S3L_lu_factor()
S3L_lu_invert()

S3L_lu_solve()

S3L_lu_deallocate()

Perform LU factorization of a matrix.
Compute inverse of square matrix instances of S3L array using S3l_lu_factor() results.
Solve system of linear equations (AX=B) for square matrix instances of S3L array.
Deallocate S3L_lu_factor() resources.

Walsh Transform

 

S3L_walsh()

S3L_walsh_setup()

S3L_walsh_free_setup()

Compute discrete Walsh/Hadamard transform of 1D and 2D S3L arrays.
Prepare internal data structure for discrete Walsh/Hadamard transform.
Free memory allocated to Walsh/Hadamard
transform.

Iterative Eigenpairs Computation

 

S3L_eigen_iter()

Compute selected eigenpairs of dense or sparse matrices.

Finite-Difference Stock Option Pricing

 

S3L_fin_fd_1D()

S3L_fin_fd_2D()

Solve 1D Black-Scholes PDE to compute prices of vanilla and several exotic stock options.
Solve 2D Black-Scholes PDE to compute prices of vanilla and several exotic stock options.

Discrete Cosine Transform

 

S3L_dct_iv()

S3L_dct_iv_setup()

S3L_dct_iv_free_setup()

Compute DCT Type IV of 1D, 2D, and 3D S3L arrays.
Prepare internal data structures for DCT Type IV operation.
Free memory allocated to DCT setup.

Discrete Sine Transform

 

S3L_dst()
S3L_dst_setup()
S3L_dst_free_setup()

Compute DST of 1D, 2D, and 3D S3L arrays.
Prepare internal data structures for DST.
Free memory allocated to DST setup.

QR Array Factoring/Solving

 

S3L_qr_factor()

S3L_get_qr()

S3L_qr_solve()

S3L_qr_free()

Compute QR decomposition of a real or complex S3L array.
Extract Q and R arrays from a QR- decomposed S3L array.
Compute the least-squares solution to an over-determined system of the form a*x=b.
Free memory allocated to QR decomposition.

Quadratic Programming Optimization

 

S3L_qp_attr_init()

S3L_qp_attr_destroy()
S3L_qp_attr_set()

S3L_qp()

Initialize a set of QP attributes with default values.
Destroy a specified set of QP attributes.
Specify the type of solver to be used and amount of error output.
Solve linear/quadratic optimization problem.

Cholesky Solver

 

S3L_cholesky_factor()

S3L_cholesky_solve()


S3L_cholesky_invert()

Perform Cholesky factorization for each square matrix in an S3L array.
Solve a system of distributed linear equations of the form AX = B for each square matrix in an S3L array.
Compute the inverse of each square matrix in an S3L array.

Sparse Linear System Solver

 

Direct Method
S3L_sparse_solve()

S3L_sparse_solve_free()

Iterative Method
S3L_gen_iter_solve()


A direct solver for solving sparse linear
systems of equations of the form A*x = y.
Free memory allocated to the direct solver.


An iterative solver for solving sparse linear
systems of equations of the form A*x =b.

Sparse Linear Problem Solver

 

S3L_lp_sparse()

Solve a linear/quadric optimization problem of the form min c'*x.

Fast Fourier Transforms

 

S3L_fft()
S3L_fft_detailed()

S3L_ifft()
S3L_rc_fft()
S3L_cr_fft()
S3L_fft_setup()

S3L_rc_fft_setup()

S3L_fft_free_setup()
S3L_rc_fft_free_setup()

Perform simple FFT on an S3L array.
Perform in-place forward or inverse FFT along a specified axis of an S3L array.
Perform the inverse FFT on an S3L axis.
Perform forward FFT of a real S3L array.
Perform inverse FFT of a complex S3L array.
Prepare internal data structure for FFT
operation.
Prepare internal data structure for real-to- complex and complex-to-real FFTs.
Free memory allocated to FFT setup.
Free memory allocated to real-to-complex or complex-to-real FFT setup.

Structured Solvers

 

S3L_gen_band_factor()

S3L_gen_band_solve()
S3L_gen_band_free_factors()

S3L_gen_trid_factor()
S3L_gen_trid_solve()
S3L_gen_trid_free_factors()

Perform LU factorization of an n x n general banded S3L array.

Solve a banded system.
Free resources allocated to factorization of
a general banded S3L array.
Compute factorization of a tridiagonal matrix.
Solve a tridiagonal system.
Free memory allocated to factorization of a tridiagonal matrix.

Dense Symmetric Eigenvalue Solver

 

S3L_sym_eigen()

Find eigenvalues and, optionally, eigenvectors in Hermitian matrices.

Condition Numbers

 

S3L_condition_number()

Compute the condition numbers of one or more instances of a square S3L array.

Parallel Random Number Generators

 

S3L_setup_rand_fib()

S3L_rand_fib()
S3L_rand_lcg()

S3L_free_rand_fib()

Initialize state table for the Lagged-Fibonacci random number generator (LFG).
Initialize an S3L array with an LFG.
Initialize an S3L array with a linear congruential random number generator.
Free memory allocated to the random number generator state table.

Least-Squares Solver

 

S3L_gen_lsq()

Find the least-squares solution of an overdetermined system or the minimum norm solution of an underdetermined system.

Dense Singular Value Decomposition

 

S3L_gen_svd()

Compute the singular value of an S3L array and, optionally, the right singular vector or left singular vector.

Autocorrelation

 

S3L_acorr_setup()

S3L_acorr()
S3L_acorr_free_setup()

Set up initial conditions for computing the autocorrelation of a signal.
Compute 1D or 2D autocorrelation of a signal.
Free memory allocated to a particular autocorrelation setup.

Convolution

 

S3L_conv_setup()

S3L_conv()
S3L_conv_free_setup()

Set up conditions for computing the convolution of a signal.
Compute 1D or 2D convolution of a signal.
Free memory allocated to a particular convolution setup.

Deconvolution

 

S3L_deconv_setup()

S3L_deconv()

S3L_deconv_free_setup()

Set up initial conditions for computing the deconvolution of an S3L array.
Compute 1D or 2D deconvolution of an S3L array.
Free memory allocated to a particular deconvolution setup.

Grade Elements of an Array

 

S3L_grade_up()

S3L_grade_down()

S3L_grade_detailed_up()

S3L_grade_detailed_down()

Grade all elements of an S3L array in ascending order.
Grade all elements of an S3L array in descending order.
Grade elements along one axis of an S3L array in ascending order.
Grade elements along one axis of an S3L array in descending order.

Sort Elements of an Array

 

S3L_sort()

S3L_sort_up()

S3L_sort_down()



S3L_sort_detailed()


S3L_sort_detailed_up
()

S3L_sort_detailed_down
()

Sort all elements of a one-dimensional array in ascending order.
Sort all elements of a one-dimensional or multidimensional array in ascending order.
Sort all elements of a one-dimensional or multidimensional array in descending

order.
Sort elements along one axis of an S3L array in either ascending or descending order using quicksort or radixsort algorithm.
Sort elements along one axis of an S3L array in ascending order.

Sort elements along one axis of an S3L array in descending order.

Parallel Transpose

 

S3L_trans()

Perform generalized transposition of an S3L array.


 

TABLE 1-2 Sun S3L Toolkit Routines

Function

Description

Create/Exit Sun S3L Environment

 

S3L_init()
S3L_exit()

Set up Sun S3L environment.
Leave Sun S3L environment.

Create Sun S3L Array Handles

 

S3L_declare()
S3L_declare_detailed()

Declare an S3L array (basic method).
Declare S3L array (control more parameters).

Release Sun S3L Array Handles

 

S3L_free()

Release an S3L array.

Control Sun S3L Process Grids

 

S3L_set_process_grid()
S3L_free_process_grid()

Define an S3L process grid.
Release resources allocated to a process grid.

Perform Operations on Sun S3L Arrays

 

S3L_array_op1()
S3L_array_op2()
S3L_array_scalar_op2()
S3L_cshift()
S3L_forall()

S3L_reduce()
S3L_reduce_axis()

S3L_set_array_element()
S3L_set_array_element_on_proc()


S3L_get_array_element()

S3L_get_array_element_on_proc()

S3L_zero_elements()

Perform operation on one array.

Perform operation on two arrays.
Perform operation on array and scalar value.
Perform circular shift along a specified axis.
Apply a user-defined function to some or all elements in an array.
Perform a reduction function across an array.
Perform a reduction function along one axis of an array.
Set the value of an element of an S3L array.
Set the value of an element of an S3L array,
using the value supplied on a specific
process.
Retrieve the value of an element of an S3L
array.
Retrieve the value of an element of an S3L
array, as supplied by a specified process.
Set all elements in an S3L array to zero.

Get Information About Sun S3L Arrays

 

S3L_describe()

S3L_get_attribute()
S3L_read_array()
S3L_read_sub_array()
S3L_print_array()
S3L_print_sub_array()

S3L_write_array()
S3L_write_sub_array()

Get information about an S3L array or process grid.
Get the value of an S3L array attribute.
Read an S3L array from a file.

Read part of an S3L array from a file.
Print an S3L array to standard output.
Print part of an S3L array to standard output.
Write an S3L array to a specified file.
Write part of an S3L array to a specified file.

Miscellaneous Tools

 

S3L_copy_array()
S3L_copy_array_detailed()

S3L_from_ScaLAPACK_desc()

S3L_to_ScaLAPACK_desc()

S3L_thread_comm_setup()

S3L_set_safety()
S3L_get_safety()

Copy an S3L array into another S3L array.
Copy a section of an S3L array into another
S3L array.
Convert ScaLAPACK descriptor to S3L handle.
Convert S3L handle to ScaLAPACK descriptor.
Prepare S3L environment for thread-safe operation.
Set error-checking level for S3L operations.
Get S3L error-checking level.


TABLE 1-3 Supported ScaLAPACK 1.6 and PBLAS 1.0 APIs

Category

Routines

PBLAS 1,2,3

p{s,d}dot, p{c,z}dotu, p{s,d}nrm2, p{sc,dz}nrm2, p{s,d}ger, p{c,z}geru, p{s,d,c,z}gemv, p{s,d,c,z}gemm

LU factor, solve,

inverse

p{s,d,c,z}getrf,p{s,d,c,z}getrs,p{s,d,c,z}getri

Tridiagonal solvers

p{s,d,c,z}dttrf, p{s,d,c,z}dttrs

Banded solvers

p{s,d,c,z}gbsv, p{s,d,c,z}gbtrf, p{s,d,c,z}gbtrs

Symmetric

eigensolver

p{s,d}syevx, p{c,z}heevx

Singular value

decomposition

p{s,d,c,z}geqrf

Least-squares solver

p{s,d,c,z}gels

Condition number

p{s,d,c,z}gecon