Sun S3L 3.0 Programming and Reference Guide

Autocorrelation

`S3L_acorr_setup`

Description

S3L_acorr_setup sets up the initial conditions necessary for computation of the autocorrelation C = acorr(A). It returns an integer setup value that can be used by subsequent calls to S3L_acorr and S3L_acorr_free_setup.

Syntax

The C and Fortran syntax for S3L_acorr_setup are shown below.

C/C++ Syntax

Example 8-84

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_acorr_setup(a, c, setup_id)
    S3L_array_t        a
    S3L_array_t        c
    int                setup_id
    <type>            *rparm

F77/F90 Syntax

Example 8-85

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_acorr_setup(a, c, setup_id, ier)
    integer*8          a
    integer*8          c
    integer*4         setup_id
    integer*4         ier

where <type> is real*4 or real*8 for both C/C++ and F77/F90.

Input

a - S3L internal array handle for the parallel 1D or 2D array of real or complex type whose autocorrelation is to be computed.
c - S3L internal array handle for the parallel 1D or 2D array of the same type as A, used to store the result of the autocorrelation. Its extents along each axis must be at least equal to two times the corresponding extent of A minus 1.

Output

This function uses the following arguments for output:

setup - Integer value retuned by this function. Use this value for the setup_id argument in subsequent calls to S3_acorr and S3L_acorr_free_setup.

ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_acorr_setup returns S3L_SUCCESS.

S3L_acorr_setup performs generic checking of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions cause the function to terminate and return one of the following codes:

S3L_ERR_ARG_DTYPE - The data type of one of the array arguments is invalid. It must be one of:
- S3L_float
- S3L_double
- S3L_complex
- S3L_double_complex

S3L_ERR_MATCH_DTYPE - The array arguments are not all of the same type.

S3L_ERR_MATCH_RANK - The array arguments are not all of the same rank.

S3L_ERR_ARG_RANK - The rank of one of the array arguments is not 1 or 2.

S3L_ERR_ARG_EXTENTS - The extents of c are less than the extents of a.

Examples

../examples/s3l/acorr/ex_acorr.c
../examples/s3l/acorr-f/ex_acorr.f

Related Functions

S3L_acorr(3)
S3L_acorr_free_setup(3)

`S3L_acorr_free_setup`

Description

S3L_acorr_free_setup invalidates the ID specified by the setup_id argument. This deallocates the internal memory that was reserved for the autocorrelation computation associated with that ID.

Syntax

The C and Fortran syntax for S3L_acorr_free_setup are shown below.

C/C++ Syntax

Example 8-86

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_acorr_free_setup(setup_id)
    int                *setup_id

F77/F90 Syntax

Example 8-87

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_acorr_free_setup(setup_id, ier)
    integer*4          setup_id
    integer*4          ier

where <type> is real*4 or real*8 for both C/C++ and F77/F90.

Input

setup_id - Valid autocorrelation setup ID as returned from a previous call to S3L_acorr_setup.

Output

This function uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_acorr_free_setup returns S3L_SUCCESS.

In addition, the following condition causes the function to terminate and return the associated code:

S3L_ERR_ARG_SETUP - Invalid setup_id value.

Examples

../examples/s3l/acorr/ex_acorr.c
../examples/s3l/acorr-f/ex_acorr.f

Related Functions

S3L_acorr(3)
S3L_acorr_setup(3)

`S3L_acorr`

Description

S3L_acorr computes the 1D or 2D autocorrelation of a signal represented by the parallel array described by S3L array handle a. The result is stored in the parallel array described by the S3L array handle c.

a and c are of the same real or complex type.

For the 1D case, if a is of length ma, the result of the autocorrelation will be of length 2*ma-1. In the 2D case, if a is of size [ma,na], the result of the autocorrelation is of size [2*ma-1,2*na-1].

The size of c has to be at least equal to the size of the autocorrelation for each case, as described above. If it is larger, the excess elements of c will contain zero or non-significant entries.

The result of the autocorrelation of a is stored in wrap-around order along each dimension. If the extent of c along a given axis is lc, the autocorrelation at zero lag is stored in c(0), the autocorrelation at lag 1 in c(1), and so forth. The autocorrelation at lag -1 is stored in c(lc-1), the autocorrelation at lag -2 is stored in c(lc-2), and so forth.

Side Effects

Following calculation of the autocorrelation of a, a may be destroyed, since it is used internally as auxiliary storage. If its contents will be reused after autocorrelation is performed, first copy it to a temporary array.

Note -

S3L_acorr is most efficient when all arrays have the same length and when this length is one that can be computed efficiently via S3L_fft, or S3L_rc_fft. See "S3L_fft " and "S3L_rc_fft and S3L_cr_fft " for more information about execution efficiency.

Restriction

The dimensions of array c must be such that a 1D or 2D complex-to-complex FFT or real-to-complex FFT can be computed.

Syntax

The C and Fortran syntax for S3L_acorr are shown below.

C/C++ Syntax

Example 8-88

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_acorr(a, c, setup_id)
    S3L_array_t       a
    S3L_array_t       c
    int               setup_id

F77/F90 Syntax

Example 8-89

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_acorr(a, c, setup_id, ier)
    integer*8         a
    integer*8         c
    integer*4         setup_id
    integer*4         ier

where <type> is real*4 or real*8 for both C/C++ and F77/F90.

Input

a - S3L internal array handle for the parallel array upon which the autocorrelation will be performed. a is of size ma (1D case) or ma x na (2D case).
setup_id - Integer value returned by a previous call to S3L_acorr_setup.

Output

This function uses the following arguments for output:

c - S3L internal array handle for the parallel array that contains the results of the autocorrelation. Its length must be at least 2*ma-1 (1D case) or 2*ma-1 x 2*na-1 (2D case).
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_acorr_setup returns S3L_SUCCESS.

In addition, the following conditions cause the function to terminate and return one of the following codes:

S3L_ERR_ARG_DTYPE - The data type of one of the array arguments is invalid. It must be one of:
- S3L_float
- S3L_double
- S3L_complex
- S3L_double_complex

S3L_ERR_MATCH_DTYPE - The array arguments are not of the same data type.

S3L_ERR_MATCH_RANK - The array arguments are not of the same rank.

S3L_ERR_ARG_RANK - The rank of one of the array arguments is not 1 or 2 as required.

S3L_ERR_ARG_EXTENTS - The extents of c are smaller than 2*ma-1 (1D case) or 2*ma-1 x 2*na-1 (2D case).

In addition, since S3L_fft or S3L_rc_fft is used internally to compute the autocorrelation, if the dimensions of c are not suitable for S3L_fft or S3L_rc_fft, an error code indicating this unsuitability is returned. For more details, refer to the man pages for S3L_fft and S3L_rc_fft.

Examples

../examples/s3l/acorr/ex_acorr.c
../examples/s3l/acorr-f/ex_acorr.f

Related Functions

S3L_acorr_setup(3)
S3L_acorr_free_setup(3)