SILC User's Manual

The following pieces of software are required to compile a SILC server and run it in a Unix-like or Microsoft Windows environment:

You are able to use the following matrix computation libraries by building them into the SILC server.

SILC has been tested in the following computing environments (in the parentheses, templates of the make.inc file (described below) for each environment are shown), together with the operating systems and compilers shown in Table 1. The column "OpenMP" shows whether support for OpenMP is available in each platform.

You can obtain the source code of SILC (in a compressed archive file named silc-1.3.tar.gz) from the following location:

The contents of the compressed archive file can be extracted as follows. The source code of SILC is stored in the silc-1.3/src/ directory in the current working directory.

$ gzip -cd silc-1.3.tar.gz | tar xvf -

To compile the source code of SILC, you need to create a file named make.inc in the silc-1.3/src/ directory. This file defines environment-specific compiler options, locations of library files, and so on. There are template files for several computing environments in the silc-1.3/src/inc/ directory. See Table 1 for the names of the template files, target platforms, operating systems, and compilers to be used.

In the make.inc file, you define a series of macros that are referenced from Makefile, the input file of the make command. The macros are roughly divided into two groups, namely a group of general macros that do not depend on SILC (Table 2) and another of SILC-specific macros (Table 3).

Subroutines of BLAS and LAPACK are used through a driver file. There are three pairs of BLAS and LAPACK drivers shown below. Choose one of them according to the implementations of BLAS and LAPACK you want to use.

You have to define the following macros in the make.inc file to specify the drivers, compiler options and linker options.

Examples of macro definitions for the dumb drivers are shown below.

BLAS_DRIVER=    blas_dumb.c
BLAS_CFLAGS=
BLAS_LIBS=      /opt/LAPACK/blas.a

LAPACK_DRIVER=  lapack_dumb.c
LAPACK_CFLAGS=  $(BLAS_CFLAGS)
LAPACK_LIBS=    /opt/LAPACK/lapack.a $(BLAS_LIBS)

The SILC server and user programs will generate a lot of debugging messages, since the template files in the silc-1.3/src/inc/ directory define the CFLAGS macro with the -DDEBUG option enabled by default. You can suppress the messages by editing make.inc and removing the option.

After you have created make.inc in the silc-1.3/src/ directory, run the make command to compile the SILC server and related programs as follows.

$ make

Before you run a user program for SILC, you need to start a SILC server. Type the following command to run a SILC server (you also need to change the current working directory to the directory where the executable file of the SILC server exists). The server starts in the foreground.

$ cd src/server
$ ./server

In shared-memory parallel computing environments, you can use an OpenMP-based parallel SILC server. The OMP_NUM_THREADS environment variable is used to specify the number of threads as follows.

$ env OMP_NUM_THREADS=4 ./server

Unless explicitly specified, the port number through which the server accepts connections from user programs will vary every time you restart the server. The SILC_PORT environment variable is used to specify the port number as illustrated below.

$ env SILC_PORT=32000 ./server

The server creates a plain text file ~/.silc (if it does not exist) in your home directory and writes out the server's host name and port number. The SILC_INIT routine (Section 3.1) reads the file and establishes a connection to the server according to the host name and port number in the file. The contents of the file is as follows.

hostName portNumber [EOF]

If the SILC server and user programs run in different computing environments with separate file systems, you have to manually create ~/.silc in the file system from which the user programs (or precisely speaking, the SILC_INIT routine) will read the file. The echo command will do for this task, as shown in the following example.

$ echo hostName portNumber > ~/.silc

To stop the SILC server, simply type Ctrl-C or use the kill command as follows.

$ kill -9 processNumber

User programs for SILC establish a connection to a SILC server over networks, and make use of matrix computation libraries the SILC server maintains, by calling the following routines. These routines are referred as client routines in this document. The arguments of the client routines are described in detail in Section 5.

Client routines for C:

Client routines for Fortran:

The client routines for both C and Fortran are defined in silc-1.3/src/client/libsilc.a. By linking the library file to user programs, these client routines are made available. libsilc.a is built together with the SILC server.

In addition, data structures and constants used with the client routines (see Section 5). are defined in silc-1.3/src/client/client.h (for C) and silc-1.3/src/client/fortran/client.h (for Fortran).

Although user programs can be either sequential or multithreading parallel programs, all calls for client routines must be made in the same thread.

An example of a user program in C (solve.c) is shown below. This program solves a system of linear equation Ax = b, where A is a sparse matrix in the Compressed Row Storage (CRS) format.

#include "client.h"

int main(int argc, char *argv[])
{
  silc_envelope_t object;  /* a structure used for data communications */
  double *value, *b, *x;
  int *index, *row;

  /* Create sparse matrix A (in the CRS format) and vector b */

  SILC_INIT();

  object.v = value;
  object.type = SILC_MATRIX_TYPE;
  object.format = SILC_FORMAT_CRS;
  object.precision = SILC_DOUBLE;
  object.m = object.n = N;  /* dimensions */
  object.nnz = NNZ;  /* the number of non-zero elements */
  object.row = row;
  object.index = index;
  SILC_PUT("A", &object);

  object.v = b;
  object.type = SILC_COLUMN_VECTOR_TYPE;
  object.precision = SILC_DOUBLE;
  object.length = N;
  SILC_PUT("b", &object);

  /* Solve a system of linear equations Ax = b */
  SILC_EXEC("x = A \\ b");

  object.v = x;
  SILC_GET(&object, "x");

  SILC_FINALIZE();

  /* Output the solution (vector x) */
}

A Fortran program (solve.f) that carries out the same computation as the C program above is shown below.

    INCLUDE 'client.h'

    REAL *8 VALUE(NNZ), B(N), X(N)
    INTEGER *4 ROW(N+1), INDEX(NNZ), IERR

C   Create sparse matrix A (in the CRS format) and vector b

    CALL SILC_INIT(IERR)

    CALL SILC_PUT_MATRIX_CRS('A', VALUE, N, N, NNZ, ROW, INDEX,
   &                         SILC_DOUBLE, IERR)

    CALL SILC_PUT_COLUMN_VECTOR('b', B, N, SILC_DOUBLE, IERR)

C   Solve a system of linear equations Ax = b
    CALL SILC_EXEC('x = A \ b', IERR)

    CALL SILC_GET_COLUMN_VECTOR('x', X, IERR)

    CALL SILC_FINALIZE(IERR)

C   Output the solution (vector x)

To compile user programs for SILC with a C/Fortran compiler, you need to specify (1) compiler options for locating the header file (client.h) and library file (libsilc.a), and (2) linker options for specifying the libraries to be linked (libsilc.a and additional libraries described below).

For example, GNU C compiler is used to compile the C program (solve.c) in the previous section by running the gcc command as follows. In this example, it is assumed that the source code of SILC is placed in the ~/silc-1.3/src/ directory in your home directory.

$ gcc -I~/silc-1.3/src/client -c solve.c
$ gcc -L~/silc-1.3/src/client -o solve solve.o -lsilc

The -I and -L options specify the locations of client.h and libsilc.a respectively, and -lsilc is a linker option for linking libsilc.a to the user program.

For your convenience, if you repeatedly modify the user program and compile it, it is worth creating Makefile like the one shown below.

all: solve

CC=      gcc
CFLAGS=  -I$$HOME/silc-1.3/src/client
LDFLAGS= -L$$HOME/silc-1.3/src/client
LIBS=    

solve: solve.c
	$(CC) $(CFLAGS) -c solve.c
	$(CC) $(LDFLAGS) -o $@ solve.o -lsilc $(LIBS)

To compile solve.c using Makefile above, run the make command as follows:

$ make

GNU Fortran compiler is used to compile the Fortran program (solve.f) in the previous section by running the g77 command as follows:

$ g77 -I~/silc-1.3/src/client/fortran -fno-second-underscore -c solve.f
$ g77 -L~/silc-1.3/src/client -o solve solve.o -lsilc

As it is in the case of the aforementioned C program, it is convenient to create Makefile like the following one:

all: solve

FC=      g77 -fno-second-underscore
FFLAGS=  -I$$HOME/silc-1.3/src/client/fortran
LDFLAGS= -L$$HOME/silc-1.3/src/client
LIBS=    

solve: solve.f
	$(FC) $(FFLAGS) -c solve.f
	$(FC) $(LDFLAGS) -o $@ solve.o -lsilc $(LIBS)

Some computing environments require additional libraries to be linked to user programs together with libsilc.a in order to use networking facilities. Several computing environments and additional libraries to be required are shown below. In the case of Makefile for C and Fortran shown above, specify the additional libraries with the LIBS macro.

There are five types of data that are transferred between a SILC server and user programs. The constants (shown in the parentheses) are used to specify the data types when calling the PUT/GET routines. These constants are defined in client.h (see Section 5).

The table below summarizes precisions supported in SILC. The constants (shown in the parentheses) are used to specify the precisions when calling the PUT/GET routines. The corresponding data types in C and Fortran for each precision are also shown.

When transferring a matrix, you have to specify the storage format of the matrix together with the data type (SILC_MATRIX_TYPE). Two matrix storage formats are currently supported as described below.

There are two types of assignment statements.

The right-hand side of an assignment statement is an expression, whose components are described below. In the following descriptions, x, y, e1, e2, ..., and eN are arbitrary expressions. See Section 4.4 for the data types that are acceptable as operands of unary and binary operators, and Section 5.3 for available built-in functions and procedures.

A procedure call consists of a procedure name and a list of arguments, as illustrated below.

Procedures have three types of arguments as follows.

In the case of the procedure split above, the first argument is an in-argument, and the other three are out-arguments.

System statements are used to control a SILC server's behavior. There is only one system statement at the moment.

Although operands of an operator can be arbitrary expressions, valid data types of the operands vary according to the operator. The acceptable combinations of data types for each operator are summarized as follows. The same restrictions on binary operators are applied to augmented assignments (Section 4.1).

If the two operands of a binary operator have a different precision, they are converted to the same precision before computation. The following rules are applied to precision conversion.

You can use subscript with either a variable name on the left-hand side of an assignment statement, or arbitrary expressions (including variable names). A variable name with subscript takes one of the following three forms:

where x, y, and z are expressions whose values are either an integer scalar or an integer column vector. Expressions with other kinds of values result in a runtime error.

When you use a range as a subscript expression, you can omit the initial and/or end value(s) of the range. For example, if A is a vector of length N, then A[:5] equals to A[1:5], A[5:] to A[5:N], and A[:] to A[1:N], respectively.

The following table summarizes the functions of subscript, the contexts in which subscript can be used, and some examples of mathematical expressions with subscript.

Every operator, function, and procedure in the command language of SILC is carried out through a call for a module function, which is a "wrapper" that actually calls a library function. Related module functions are grouped into a module. There are several standard modules as shown below.

There are also a few experimental modules.

Every operator, function, and procedure is handled by one of module functions in the modules above. Some operators have multiple module functions that can handle them. For example, the three modules of leq_cg, leq_gs, and leq_lu contain a module function for the backslash operator (i.e., solution of systems of linear equations). Modules are maintained in a SILC server by means of a serial linked list. When the SILC server needs to handle an operator, the server picks a module function by searching one module after another from the beginning of the module list and selecting the first module function found in the list. Module functions for functions and procedures are also looked up in the same way.

You can change the order of modules in the module list using the prefer statement (Section 4.3) in a call for the SILC_EXEC routine. The prefer statement moves the specified module to the beginning of the list. By changing the order of modules, you can easily specify the relations between operators (functions, or procedures) and module functions.

The following client routines return 0 if no error occurs; otherwise, they return −1.

The following arguments are common to the client routines for Fortran.

In the following descriptions, type can be one of the following data types.

Built-in functions and procedures are defined in modules. If two or more functions or procedures have the same name, the function or procedure that is found first is called. By using the prefer statement (Section 4.3) to change the order of modules, you can use specific functions and procedures defined in particular modules.