VOLPIS CODE - A SHORT GUIDE FOR USERS
S. Cesca, University of Hamburg, June 2006


This version of the code, as well as additional files containing this
short guide, scripts and examples, are submitted to "Computers and Geosciences"
journal together with the submitted research paper: 
Cesca, S. and Dahm, T., 2006. "A frequency domain inversion code to retrieve 
time-dependent parameters of long period volcanic sources".

For further information, comments or reports of any bugs, please contact:
Dr. Simone Cesca
Institut fr Geophysik
University of Hamburg
simone.cesca@zmaw.de 


INTRODUCTION
VOLPIS is a Fortran code to invert source parameters of volcanic seismic
events. The code requires the previous processing of data, generation of
Greens functions (GF) and selection of numerical parameters. The output is given
in terms of 9 time-dependent source components: 6 components of Moment Tensor
(MT), 3 components of Single Force (SF).
This guide will not enter in the details of code structure and methodology, 
for which a large description is given in the research paper. In the following,
it will be explain the format of input/output data and the basic informations
needed to run the code in a linux system.


INPUT FILES
The code execution requires the previous preparation of different files:
1) data files (displ.c.n), 
2) GF files (MTx.c.n, SFy.c.n),
3) time windows file (retard.dat), 
4) numerical parameter file (volpis.input)

(1) DATA FILES
    Data files include time traces for data. They can either correspond to 
    displacements, velocity of acceleration, and can be referred to any of 
    the following axes: radial (r), transversal (t), vertical (z), north (n)
    and east (e).
    For each station, there should be a different file. Each station has to be
    numbered, and this numbering should be kept unchanged in the whole process.
    Data files have to be saved with the following naming:
       displ.c.n, where c stands for component and n for station number
       (ex. displ.z.4 will contain vertical component of station 4)
    Data can be saved either in SAC binary format or an ascii-compressed
    format related to reflectivity method.
    Concerning SAC format, the following parameters of sac header have to be set:
    	Set CMPAZ, CMPINC, STLO, STLA, EVLO, EVLA, DELTA and NPTS to proper values. 
	Set DELTA to the same value for all traces
	Set B to 0
	Set USER1 additional variable as:
	    1: radial component
            2: vertical component
            3: transversal component
	    7: north component
	    8: east component
  
(2) GREENS FUNCTIONS
    GF files include responses of simple excitations (etiher any of MT or SF 
    components). They consist of time traces. The following rules has to be
    followed:

    Time traces: use displacements, velocities or accelarations, in agreement with data. 

    Components: use the same reference axes as for data;

    Numbering of stations: same numbering as for data;

    Sampling rate: same as for data; the same for each trace;

    File naming: use names MTx.c.n for responses of Moment Tensor source components 
        (x number of source component, 1..6, see the research paper for conventions; 
        c, component; n, station number) and SFy.c.n for responses to single forces 
        (y number of SF component, 1..3, see the research paper for conventions; 
        c, component; n, station number);

    File format: either SAC binary format or an ascii-compressed format related to 
        reflectivity method.

    SAC binary files: parameters of SAC header have to be set as for data.

(3) TIME WINDOWS FILE
    This file is named retard.dat.
    First line is ./
    All other lines (one for each trace time data window to be used for the inversion) 
    have the following format:
    
    column 1     component (R,T,Z,N,E). Use capital letters;
    column 2-5   station number (in agreement with data and GF);
    column 7-10  station name (character, maximal length 4 characters);
    column 14    P (p-wave) or S (s-wave)
    column 18-22 (unused)
    column 25-28 beginning of time window for data (in number of points)
    column 31-34 beginning of time window for GF (in number of points)
    column 37-43 unused
    column 46-52 station azimuth (in degrees)
    column 54-57 length of data windows (in number of points)
    column 59-63 Weight of time trace data window
    
    Note: if running the inversion, lengths of data windows should be constant,
          if running the forward model option, they can be different.
    
(4) NUMERICAL PARAMETER FILE
    This file is named volpis.input
    Each line contain information for the numerical parameter of code execution:
    
    Line 1:
        - name of time windows file (e.g., retard.dat)
    
    Line 2:
        - number of points for FFT calculation (power of 2, larger than data 
          window length),
	- percentage of time window to be used for taper in time domain
          (negative values enlarge the original time-window size on both sides)
        - lower corner value for frequency bandpass filter
	- higher corner value for frequency bandpass filter
	- distance dependent weight (0=no scaling, 1=scaling proportional to r)
	- 2 (do not change)
	- 1 (do not change)
	 
    Line 3:
        - unused. Keep unchanged (1,1,99999,99999)
	
    Line 4:
        - Input format (0=13bit ascii format, 2=SAC binary)	
        - Output format (0=13bit ascii format, 1=GSE format)	 

    Line 5:
        - Execution mode swith (0=inversion, 1=forward modeling)
	- Length of STF (Fz. Brustle-Muller) to be used for the forward modeling;
          set to 0 if running inversion, or if STF is already included in GF.
        - Switch for forward modeling source type (if running inversion set to 0):
	  If running the forward modeling, accepted values are:
	     0: general source (MT+SF)
	     1: pure crack       
             2: pure double couple (DC)

    If running the forward modeling additional lines have to be included,
    depending on the selected source type:
     
        - If source type 0 (general source):
	     Line 6: M11, M12, M22, M13, M23, M33
	     Line 7: F1, F2, F3
	     
        - If source type 1 (pure crack):
	     Line 6: Strike angle, Dip angle, Mu, Lambda
	     (angles given in degrees, Mu and Lambda are Lame parameters)
	     
	- source type 2 (pure double couple):
	     Line 6: Strike angle, Dip angle, Rake angle
	     (angles given in degrees)       


EXECUTION
    At the moment of execution all input files have to be saved in the working
    directory.
    The code can be then executed by the command:
        volpis.exe <volpis.input
    
    Use the script testlocation.csh to run the inversion for a set of possible
    Greens functions (e.g., to test different locations). This need data files
    to be saved in the subdirectory DATA, each set of GF to be set in subdirectories
    named GREENn (n=number of GF set), and retard.dat files also saved in the
    same subdirectories GREENn. 


Output files
    Several output files are given as result of execution:
    dispf.c.n:  filtered data
    synth.c.n:  synthetic data for an unconstrained source
    syntc.c.n:  synthetic data for a source constrained to have a common time 
                history for all components (c.1)
    synt2.c.n:  synthetic data for a source constrained to have a common time 
                history for MT components and another for SF components (c.2)
    imtx.dat:   ascii file, x source component of MT for the unconstrained source
    isfy.dat:   ascii file, y source component of SF for the unconstrained source
    cmtx.dat:   ascii file, x source component of MT for the constrained (c.1) source
    csfy.dat:   ascii file, y source component of SF for the constrained (c.1) source
    mmtx.dat:   ascii file, x source component of MT for the constrained (c.2) source
    fsfy.dat:   ascii file, y source component of SF for the constrained (c.2) source 
    result.fit: contains the fit of data:
                   - fit of synthetic to data for solution unconstrained
                   - fit of synthetic to data for solution constrained (c.1)
                   - fit of synthetic to data for solution constrained (c.2)
                   - fit of constrained (c.1) solution to the unconstrained one
                   - fit of constrained (c.2) solution to the unconstrained one
    volpis.erg: control file
