Sun S3L 3.0 Programming and Reference Guide

Convolution/Deconvolution

`S3L_conv_setup`

Description

S3L_conv_setup sets up the initial conditions necessary for computation of the convolution C = A conv B. It returns an integer setup value that can be used by a subsequent call to S3L_conv.

S3L array handles A, B, and C each describe a parallel array that can be either one- or two-dimensional. The extents of C along each axis i, must be such that they are greater than or equal to two times the sum of the corresponding extents of A and B, minus 1.

Syntax

The C and Fortran syntax for S3L_conv_setup are shown below.

C/C++ Syntax

Example 8-90

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_conv_setup(A, B, C, setup_id)
    S3L_array_t       A
    S3L_array_t       B
    S3L_array_t       C
    int               *setup_id

F77/F90 Syntax

Example 8-91

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_conv_setup(A, B, C, setup_id, ier)
    integer*8         A
    integer*8         B
    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 array handle describing a parallel array of size ma (1D case) or ma x na (2D) case. A contains the input signal that will be convolved.
B - S3L array handle describing a parallel array that contains the convolution filter.
C - S3L array handle describing a parallel array in which the convolved signal is stored. Its length must be at least ma+mb-1 (1D case) or ma+mb-1 x na+nb-1 (2D case).

Output

This function uses the following arguments for output:

setup_id - Integer value retuned by this function. Use this value for the setup_id argument in subsequent calls to S3_conv and S3L_conv_free_setup.
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_conv_setup returns S3L_SUCCESS.

S3L_conv_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_RANK - The rank of one of the array arguments is not 1 or 2.

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

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

S3L_ERR_ARG_EXTENTS - The extents of c are less two times the sum of the corresponding extents of A and B minus 1.

Examples

../examples/s3l/conv/ex_conv.c
../examples/s3l/conv-f/ex_conv.f

Related Functions

S3L_conv(3)
S3L_conv_free_setup(3)

`S3L_conv_free_setup`

Description

S3L_conv_free_setup invalidates the ID specified by the setup_id argument. This deallocates the internal memory that was reserved for the convolution computation represented by that ID.

Syntax

The C and Fortran syntax for S3L_conv_free_setup are shown below.

C/C++ Syntax

Example 8-92

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

F77/F90 Syntax

Example 8-93

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_conv_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 - Integer value returned by a previous call to S3L_conv_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_conv_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 value.

Examples

../examples/s3l/conv/ex_conv.c
../examples/s3l/conv-f/ex_conv.f

Related Functions

S3L_conv(3)
S3L_conv_setup(3)

`S3L_conv`

Description

S3L_conv computes the 1D or 2D convolution of a signal represented by a parallel array using a filter contained in a second parallel array. The result is stored in a third parallel array. These parallel arrays are described by the S3L array handles: a (signal), b (filter), and c (result). All three arrays are of the same real or complex type.

For the 1D case, if the signal a is of length ma and the filter b of length mb, the result of the convolution, c, will be of length ma + mb - 1. In the 2D case, if the signal is of size [ma,na] and the filter is of size [mb,nb], the result of the convolution is of size [ma+mb-1,na+nb-1].

Side Effects

Because a and b are used internally for auxiliary storage, they may be destroyed after the convolution calculation is complete. If the contents of a and b must be used after the convolution, they should first be copied to temporary arrays.

Note -

S3L_conv is most efficient when all arrays have the same length and when this length can be computed efficiently via S3L_fft, or S3L_rc_fft. See "S3L_fft " and "S3L_rc_fft and S3L_cr_fft " for additional information.

Restriction

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

Syntax

The C and Fortran syntax for S3L_conv are shown below.

C/C++ Syntax

Example 8-94

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

F77/F90 Syntax

Example 8-95

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_conv(a, b, c, setup_id, ier)
    integer*8         a
    integer*8         b
    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 array handle describing a parallel array of size ma (1D case) or ma x na (2D) case. a is the input signal that will be convolved.
b - S3L array handle describing the parallel array that contains the filter.
setup_id - Valid convolution setup ID as returned from a previous call to S3L_conv_setup.

Output

This function uses the following arguments for output:

c - S3L array handle describing a parallel array containing the convolved signal. Its length must be at least ma+mb-1 (1D case) or ma+mb-1 x na+nb-1 (2D case).
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_conv returns S3L_SUCCESS.

S3L_conv 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_MATCH_DTYPE - a, b, and c do not have the same data type.

S3L_ERR_MATCH_RANK - a, b, and c do not have the same rank.

S3L_ERR_ARG_RANK - The rank of an array argument is larger than 2.

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_ARG_EXTENTS - The extents of c are smaller than two times the sum of the corresponding extents of a and b minus 1.

Examples

../examples/s3l/conv/ex_conv.c
../examples/s3l/conv-f/ex_conv.f

Related Functions

S3L_conv_setup(3)
S3L_conv_free_setup(3)

`S3L_deconv_setup`

Description

S3L_deconv_setup sets up the initial conditions required for computing the deconvolution of A with B. It returns an integer setup value that can be used by subsequent calls to S3L_deconv or S3L_deconv_free_setup.

Syntax

The C and Fortran syntax for S3L_deconv_setup are shown below.

C/C++ Syntax

Example 8-96

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_deconv_setup(A, B, C, setup_id)
    S3L_array_t       A
    S3L_array_t       B
    S3L_array_t       C
    int               *setup_id

F77/F90 Syntax

Example 8-97

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_deconv_setup(A, B, C, setup_id, ier)
    integer*8         A
    integer*8         B
    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 that contains the input signal to be deconvolved.
B - S3L internal array handle for the parallel array that contains the vector.
C - S3L internal array handle for the parallel array that will store the deconvolved signal.

Output

This function uses the following arguments for output:

setup_id - Integer value retuned by this function. Use this value for the setup_id argument in subsequent calls to S3_deconv and S3L_deconv_free_setup.
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_deconv_setup returns S3L_SUCCESS.

S3L_deconv_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_RANK - The rank of one of the array arguments is not 1 or 2.

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

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

S3L_ERR_ARG_EXTENTS - The extents of C are less than the corresponding extents ext(A) - ext(B) + 1, or the extents of A are less than the corresponding extents of B.

Examples

../examples/s3l/deconv/ex_deconv.c
../examples/s3l/deconv-f/ex_deconv.f

Related Functions

S3L_deconv(3)
S3L_deconv_free_setup(3)

`S3L_deconv_free_setup`

Description

S3L_deconv_free_setup invalidates the ID specified by the setup_id argument. This deallocates internal memory that was reserved for the deconvolution computation represented by that ID.

Syntax

The C and Fortran syntax for S3L_deconv_free_setup are shown below.

C/C++ Syntax

Example 8-98

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

F77/F90 Syntax

Example 8-99

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_deconv_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 - Integer value returned by a previous call to S3L_deconv_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_deconv_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 value.

Examples

../examples/s3l/deconv/ex_deconv.c
../examples/s3l/deconv-f/ex_deconv.f

Related Functions

S3L_deconv(3)
S3L_deconv_setup(3)

`S3L_deconv`

Description

If a can be expressed as the convolution of an unknown vector c with b, S3L_deconv deconvolves the vector b out of a. The result, which is returned in c, is such that conv(c,b)=a.

In the general case, c will only represent the quotient of the polynomial division of a by b.

The remainder of that division can be obtained by explicitly convolving with b and subtracting the result from a.

If ma, mb, and mc are the lengths of a, b, and c respectively, ma must be at least equal to mb. The length of mc will be such that mc+mb-1=ma or, equivalently, mc=ma-mb+1.

Note -

S3L_deconv is most efficient when all arrays have the same length and when this length is such that it can be computed efficiently by S3L_fft or S3L_rc_fft. See "S3L_fft " and "S3L_rc_fft and S3L_cr_fft " for additional information.

Restriction

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

Scaling

The results of the deconvolution are scaled according to the underlying FFT that is used. In particular, for multiple processes, if a and b are real 1D, the result is scaled by n/2, where n is the length of c. For single processes, it is scaled and by n. In all other cases, the result is scaled by the product of the extents of c.

Side Effects

Because a and b are used internally for auxiliary storage, they may be destroyed after the deconvolution calculation is complete. If a and b must be used after the deconvolution, they should first be copied to temporary arrays.

Syntax

The C and Fortran syntax for S3L_deconv are shown below.

C/C++ Syntax

Example 8-100

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

F77/F90 Syntax

Example 8-101

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_deconv(a, b, c, setup_id, ier)
    integer*8         a
    integer*8         b
    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 array handle describing a parallel array that contains the convolution of an unknown vector c with b. Its length must be at least ma+mb-1 (1D case) or ma+mb-1 x na+nb-1 (2D case).
b - S3L array handle describing the parallel array that contains the vector.
setup_id - Valid convolution setup ID as returned from a previous call to S3L_deconv_setup.

Output

This function uses the following arguments for output:

c - S3L array handle describing a parallel array. Its length must be at least ma+mb-1 (1D case) or ma+mb-1 x na+nb-1 (2D case). Upon successful completion, the results of deconvolving a will be stored in c.
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_deconv returns S3L_SUCCESS.

S3L_deconv 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_MATCH_DTYPE - a, b, and c do not have the same data type.

S3L_ERR_MATCH_RANK - a, b, and c do not have the same rank.

S3L_ERR_ARG_RANK - The rank of an array argument is larger than 2.

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_ARG_EXTENTS - The extents of c are smaller than two times the sum of the corresponding extents of a and b minus 1.

In addition, since S3L_fft or S3L_rc_fft is used internally to compute the deconvolution, if the dimensions of c are not appropriate for using S3L_fft or S3L_rc_fft, an error code indicating the unsuitability is returned. See "S3L_fft " and "S3L_rc_fft and S3L_cr_fft " for more details.

Examples

../examples/s3l/deconv/ex_deconv.c
../examples/s3l/deconv-f/ex_deconv.f

Related Functions

S3L_deconv_setup(3)
S3L_deconv_free_setup(3)