44.1 Programmers guide and some test programs

SEISAN is conglomerate of programs and subroutines and it can be difficult to find out which routines to use and how to start a new SEISAN program. The most common method is to use an existing program and modify it. The intention with this section is to make it easier by providing a few sample programs which then can be modified to do specific tasks. The most common subroutines in LIB, which might be useful in other programs, are listed in Appendix D. The compilation of existing SEISAN programs has been described in section 3.10 and details of the commands are found in the Makefiles. In this distribution, sample programs have been included, which each illustrate the used of some SEISAN features. All programs are included in the Makefiles and can therefore be compiled directly, modified and recompiled.

Reading and writing S-files

A basic operation is to be able to read and write S-files, since all parameters are contained in the S-files. Starting with version 7.2, a new library (rea.for) and include block (rea.inc for definition of variables) has been included to make it easier to read and write data into S-files. Earlier, S-files were only read and written as text strings and individual parameters were then read/written to the text strings. Now the new routines do it all. These routines are now used in a few programs, but will be included whenever a program is substantially modified. The sample program is called sample_read_write_s.for. The program illustrates how to read all parameters in an S-file, make modifications and write out the file again. The program can be useful, if the user needs a program where special parameters are needed for a particular analysis or for output in another format. This program is written in Fortran.

The program can read from a file or a data base and therefore illustrates the different posibilities in SEISAN.

There is also a program available to read and write S-files in C. sample_read_write_s_c.cpp. The program will use the seisan fortran routines to read and write, and the data is placed into a C structure. This C-struction is equivalent with the correspondiong REA.INC common block in Fortran. In c++, the definitions are found in textttrea_c.h in INC but the definition of the variables are in rea.inc. All the c++ subroutines used are found in the main program. This program only read and write an S-file with one or many events. You need to compile sample_read_write_s_c.cpp in the PRO folder, it is not part of the standard compilation since additional libraries might be needed.

Putting two S-files into memory at the same time, sample_rea_to_rea2.

Sometimes it is useful to have two s-files with all parameters in memory at the same time for different manipulations. Normally the rea.inc struction is used for one file. However, there is also a rea2.inc structure containing the same element as the rea structure, but all names are now rea2_.... In rea2.for there are several subroutines that copy between rea and rea2 and the sample program illustrates this. The program operation is:

Data from 2 different s-files are read, one event at a time in each.

The two files are merged together, file 1 is inserted into file 2, so file 2 main header remins.

Id line from file 1 is converted to a comment line.

Locality line is only kept from file2, from file 1, it is converted to a comment.

If duplicate phases are found, they are deleted from file 1.

Reading and writing waveform files: SAMPLE_READ_WAV, SAMPLE_READ_CONT, SAMPLE_READ_ARC, SAMPLE_READ_WRITE_SEED, SAMPLE_WRITE_WAV

In SEISAN, waveform files can be in SEISAN, SAC, MiniSeed/SEED, Guralp or GSE format. SEISAN format is slightly different depending on which compute platform it is written and byte swapping has to be done in some cases. In order to automatically handle the reading of waveform files, irrespective of format and computer platform, a set of standard routines are used (waveform.for) and an include block where all parameters and data end up (waveform.inc). The sample reading program is called sample_read_wav.for.There is a similar program SAMPLE_WRITE_WAV for writing SEISAN waveform files.

The program illustrates how to read many waveform files belonging to one event as if it was one file, irrespective of format. It also demonstrates how to read just one waveform file. There is an output file which gives a listing of all different channels found in all the files read. Thsi listing is in the format used for defining channels in an achive. There is no detail on how to write a SEISAN binary file in this program, but some info is given under the format description in Appendix B and the program tsig.for described below illustrates a simple write. The sample program sample_read_cont illustrates how to extract out a time segment of the continuous data base. The program also shows how to write a Seisan file with all headers. The program is started from the command prompt:

sample_read_cont start_time interval

where start time is yyyymmddhhmmss and interval is interval in minutes.

There is a similar program for reading data from archives, sample_read_arc.

sample_read_write_seed interval

This program can read and write seed files using Chad and Rubens routines. it works independently of SEISAN subroutines.

There is also a routine in Java available to read all SEISAN binary formats. The program is called SFORMAT (written by T. Utheim). Similarly there is a sample program to read all SEISAN binary formats in Perl (written by Angel Rodriguez). The program is called seibinasc.pl and you need a Perl interpreter to run it. Before starting the program, a DIRF must first be made of waveform input files. The output is identical to a SEISAN ASCII file as made by SEIASC.

The sample write program is called sample_write_wav.for. It is a simple example of writing a straight line. The output formay is SEISAN.

Correction for instrument response, sample_instrument_correction

This program will mainly demonstrate how to make instrument correction, but is also demonstrates several other standard subroutine calls in SEISAN. The operations are:

Read S-file with readings and location

Get wave form files from S-file

Enter station and component for instrument correction

Find S-time from readings

Select out a time window for waveform channel around S-time

Find channel number in waveform file(s) corresponding to desired channel

Read the S-time window from waveform channel

Read response file

Prepare response removal, different filters and poles and zeros possible, the example is Wood-Anderson response

Correct for instrument response

Write out corrected data in an ASCII file in Helberger format

Automatically pick maximum amplitude and corresponding period

Write out results

Graphics in SEISAN

SEISAN uses a set of graphics routines, which are identical in call on all 3 platforms . These routines then call low level routines which are platform dependent (X on Unix and Windows calls on PC). The programmer only has to use the high level routines. The routines also generate a PostScript output if a given parameter is set. The program is called sample_grapichs.for. The program illustrates how to initiate graphics, make a few simple calls, get up and use the mouse and make a hard copy file. Most of the general graphics routines are located in file seiplot.for and common variables in seiplot.inc. The program can be useful for testing functionality of the mouse.

Program LSQ is a simple example of how to make xy-graphics. It also shows how to make the output files for gmtxy. In order to find more info (apart from manual in INF) on gmtxy, see file gmt.for in LIB and gmt_xy_par in INF.

Program for UDP communication SAMPLE_UDP_MESSAGE

This program shows how to communicate between two program using UDP signalling. It is so far only used in MULPLT to communicate with SE.

Program to make test signals, TSIG:

It is often useful to be able to work with controlled waveform data so a program making test signals is included. The program makes several traces, all with same length and sample rate and trace 1 is the sum of all traces. For each trace selected, the parameters selected are: Frequency, amplitude (remember this is integer numbers in file so use at least 1000), phase, delay (delay time when the signal appears on trace relative to start of trace, the data before is zero) and damping. The damping is used to simulate seismometer damping or simple a damped signal and has a similar physical meaning as the seismometer damping constant, but period is not recalculated to simulate changing period with damping. Zero damping is no damping.
An additional trace can be made with a Brune displacement pulse generated with parameters corner frequency (f0), Q and kappa (see MULPLT) and travel time. Travel time is used for Q-correction and also places the pulse at travel time distance from the origin (start of trace), so length of trace must be longer than travel time. If zero q and kappa, no attenuation is used. The program also write an S-file with relevant parameters. The program illustrates a simple writing of a SEISAN waveform file.

Java programs in SEISAN

The Java programs are each given as a Jar-file, the jar-files are located in the PRO directory. The jar-file contains all the Java source code, the Java classes and the project file so a user can decompress the jar file, change the script and make a new version of the program. The programs are started using a script file in the COM directory and no classpath has to be set, when SEISAN has been correctly installed.