I Overview
----------

  Computation of path delay for altimetery is implemented in
a server-client model. The server runs two processes: the
data acquisition process that is scheduled by cron every hour
and the daemon process that is running continuously.

  The data acquisition process checks whether the new output 
of numerical weather model became available on a remote server.
If the new output became available, the data acquisition process
downloads the output of the numerical weather models, prepossesses
it and stores results.

  In the framework of this approach, the bouncing point can be 
everywhere between the height 1000 m below the reference ellipsoid
and 80000 m. The emitter can be everywhere above the reference
ellipsoid.

  Computation time in seconds is approximately 20 + 5000*points.
Therefore, spd_client should be called with large blocks of points.
Calling it for every point will cause gigantic loss of efficiency
and should be by all means avoided.

  The SPD daemon process accepts connections from a client on the 
specified port, executes a command get, ping, or shutdown, and 
sends the result to the client. The SPD server itself does not
implement authentication and cryptography. It is assumed that 
the client has an account with ssh privilege on the SPD server 
computer and set an ssh tunnel to the SPD server.

  Package SPD_CLIENT provides a Fortran, C, and MATLAB interface to 
a client. The client sends a request to the SPD server for computation 
of path delay, waits for completion of the request,  and retrieves 
the output. The client assumes that the server is running. For checking
whether the server is running, the client may send command PING. 
If no answer is received for the time out defined in the client-side 
configuration file, an error message is generated. In a similar way, 
if the the client does not receive a response from the server 
for a timeout, an error message is issued.

  There are three routines that implement the interface:

1) spd_cli_init -- initializes the interface, allocates memory
                   for the transport data structure spd_2p, and
                   checks, weather the server is running.

2) spd_cli_get_2pd -- sends a request to the server, waits for 
                      processing the request and returns 
                      the result.
2) spd_get_delay -- sends a request to the server, waits for 


The data to and from the server are shipped in the array
of SPD_2P data structures. Here is the description:

spd_2p.tai           (IN,Real)  -- Time in seconds after the midnight
spd_2p.mjd           (IN,Intg)  -- Integer number of days from 2000.01.01 
                                   epoch
spd_2p.emi_1         (IN,Real)  -- X-coordinate of the emitter  in meters
spd_2p.emi_2         (IN,Real)  -- Y-coordinate of the emitter  in meters
spd_2p.emi_3         (IN,Real)  -- Z-coordinate of the emitter  in meters
spd_2p.rec_1         (IN,Real)  -- X-coordinate of the receiver in meters
spd_2p.rec_2         (IN,Real)  -- Y-coordinate of the receiver in meters
spd_2p.rec_3         (IN,Real)  -- Z-coordinate of the receiver in meters
spd_2p.del_1st       (OUT,Real) -- Path delay in the first wavelength range,
                                   in meters.          
spd_2p.del_2nd       (OUT,Real) -- Path delay in the second wavelength range,
                                   in meters.          
spd_2p.del_rder_1st  (OUT,Real) -- Partial derivative of path delay of the
                                   first wavelength range on the height of 
                                   the receiver.             
spd_2p.del_rder_2nd  (OUT,Real) -- Partial derivative of path delay of the
                                   first wavelength range on the height of 
                                   the receiver.             
spd_2p.del_eder_1st  (OUT,Real) -- Partial derivative of path delay of the
                                   first wavelength range on the height of 
                                   the emitter.              
spd_2p.del_eder_2nd  (OUT,Real) -- Partial derivative of path delay of the
                                   second wavelength range on the height of 
                                   the emitter.              

SPD_CLIENT, depending on configuration, can compute path delay at one or
two wavelength simultaneously.


II Installation
---------------


  Read INSTALL file file in spd_client to learn how to install SPD_CLIENT.

  SPD_CLIENT installs the shared librarry libspc into $prefix/lib, 
and include files spd.i, spd_local.i and spc.h in $prefix/include. The matlab
code is put in directory $prefix/spd/script, where $prefix is the name of 
the installation directory. It also installs libspc library in $prefix/lib 
and the matlab header file libspc.h into $prefix/lib directory.

  In order to run spd client from matlab, you need to define
environment variable LD_PRELOAD for Linux or DYLD_INSERT_LIBRARY
for MACOS. That variable should define the full path names of there 
shared libraries: spc, petools, lapack, and gfortran (strictly 
in this order). 

  In order to define this environment variable, source
one of these files 

source  $prefix/bin/libspc_vars.csh
source  $prefix/bin/libspc_vars.sh

A file with extensions .csh is used for csh or tcsh shell, 
and a file with extensions .sh is used for any other shells.

Please check, whether variable DYLD_INSERT_LIBRARY or LS_PRELOAD is defined
NB: A failure to define properly DYLD_INSERT_LIBRARY or LS_PRELOAD will 
result in an error with the obscure message.


III Detailed routine description
--------------------------------

1) spd_init

   Routine spd_init initializes interface to SPD client. It creates   
an array of structures spd_2p that is used for transport of        
time tag, coordinates of the emitter and the receiver as input and 
path delay and its partial derivatives as the output. Then         
spd_init checks whether the SPD server is running. If the server   
is not not running, spd_init issues and error message and          
sets iuer>0.                                                       
                                                                      
FORTRAN or C:
~~~~~~~~~~~~~

Input parameters: 

                                                                         
    SPD_CLI_CONF ( CHARACTER ) -- name of the SPD Client configuration   
                                  file.                                  
                                                                         
Output parameters: _______________________ 
                                                                         
    SPD_CLI ( SPD_CLI__TYPE  ) -- internal SPD Client data structure that 
                                  is used in every SPD Client operation. 
                                                                         
Modified parameters: 
                                                                         
        IUER ( INTEGER*4, OPT ) -- Universal error handler.              
                              Input: switch IUER=0 -- no error messages  
                                     will be generated even in the case  
                                     of error. IUER=-1 -- in the case of 
                                     error the message will be put on    
                                     stdout.                             
                              Output: 0 in the case of successful        
                                      completion and non-zero in the     
                                      case of error.                     


MATLAB:
~~~~~~~

Input parameters: 
                                                                      
   np           ( int  ) -- maximum size of the buffer spd_2p for     
                            transferring parameters to and back       
                            the SPD server.                           
   cli_conf     ( char ) -- name of the configuration file for        
                            spd_client.                               
   spd_lib_path ( char ) -- Installation prefix of the SPD_CLIENT     
                            library.                                  
   mjd_beg      ( int  ) -- MJD of the beginning the interval for     
                            path delay computation.                   
   tai_beg      ( int  ) -- TAI time of the beginning the interval    
                            for path delay computation.               
   mjd_end      ( int  ) -- MJD of the end of the interval for        
                            path delay computation.                   
   tai_end      ( int  ) -- TAI time of the end of the interval       
                            for path delay computation.               
   ivrb         ( int  ) -- Verbosity parameter.                      
                            0 -- silent mode. Only error messages are 
                                 printed.                             
                            1 -- normal verbosity. Progress messages  
                                 are printed.                         
                            2 -- debugging mode.                      
                                                                      
Output parameters: 
                                                                      
   spd_2p    ( struct  ) -- Array of np data data structures for      
                            transferring data to and back SPD server. 
  cli_ptr    ( pointer ) -- Pointer to the internal data structure    
                            of the SPD_CLIENT.                        
  iuer       ( int     ) -- Error parameter.                          
                            0 -- no mistakes.                         
                            1 -- failure to communicate with the      
                                 server.                              

2) spd_get_delay 

   Routine spd_get_delay communicates with the SPD server. It sends   
the request to compute path delays, waits for processing the       
quest and returns the results.                                     
                                                                      
   Array of data structures spd_2p is used for transport of time      
tags, coordinates of the emitter and the receiver as input and     
path delay and its partial derivatives as the output.              
                                                                      
Meaning of the spd_2p array fields:                                
                                                                      
   spd_2p(k).tai           TAI time after the midnight, in seconds.   
   spd_2p(k).emi_1         X-coordinate of emitter position in the    
                           crust fixed coordinate system, in meters.  
   spd_2p(k).emi_2         Y-coordinate of emitter position in the    
                           crust fixed coordinate system, in meters.  
   spd_2p(k).emi_3         Z-coordinate of emitter position in the    
                           crust fixed coordinate system, in meters.  
   spd_2p(k).rec_1         X-coordinate of receiver position in the   
                           crust fixed coordinate system, in meters.  
   spd_2p(k).rec_2         Y-coordinate of receiver position in the   
                           crust fixed coordinate system, in meters.  
   spd_2p(k).rec_3         Z-coordinate of receiver position in the   
                           crust fixed coordinate system, in meters.  
   spd_2p(k).del_1st       Path delay in the first wavelength range,
                           in meters.          
   spd_2p(k).del_2nd       Path delay in the second wavelength range,
                           in meters.          
   spd_2p(k).del_rder_1st  Partial derivative of path delay of the
                           first wavelength range on the height of 
                           the receiver.             
   spd_2p(k).del_rder_2nd  Partial derivative of path delay of the
                           first wavelength range on the height of 
                           the receiver.             
   spd_2p(k).del_eder_1st  Partial derivative of path delay of the
                           first wavelength range on the height of 
                           the emitter.              
   spd_2p(k).del_eder_2nd  Partial derivative of path delay of the
                           second wavelength range on the height of 
                           the emitter.              
   spd_2p(k).mjd           Integer (sic!) Modified Julian Date on the 
                           midnight preceding the event.              
   spd_2p(k).filler_1      4-bite long filler.                        
                                                                      

FORTRAN, C:
~~~~~~~~~~~

   Routine  SPD_CLI_GET_2PD  sends a request to the SPD server to     
   compute path delays, waits for completion of computation and       
   retrieves the result.                                              
                                                                      
Input parameters: 
                                                                      
 SPD_CLI ( SPD_CLI__TYPE  ) -- internal SPD Client data structure that 
                               is used in every SPD Client operation. 
   N_DEL ( INTEGER*4      ) -- The number of points.                  
    IVRB ( INTEGER*4      ) -- verbosity level.                       
                               0 -- silent: no messages are printed.  
                               1 -- message will be printed about     
                                    executed operations.              
                               2 -- message will be printed about     
                                    executed operations and the       
                                    progress counter will be updated  
                                    every second.                     
                                                                      
Modified parameters: 
                                                                      
   SPD_2P ( SPD_2P__TYPE   ) -- Array of transport data structures    
                                This array is sent to the server and  
                                is retrieved back.                    
   input fields:                                                      
                                                                      
       SPD_2P%MJD     ( INTEGER*4  ) -- Modified Julian date on       
                                        midnight of the epoch.        
                                        Units: days.                  
       SPD_2P%TAI     ( REAL*8     ) -- TAI time of photom reaching   
                                        the receiver. Units: sec.     
       SPD_2P%COO_EMI ( REAL*8     ) -- Cartesian coordinates of the 
                                        emitter. Units: meters.       
       SPD_2P%COO_REC ( REAL*8     ) -- Cartesian coordinates of the 
                                        receiver. Units: meters.      
   output fields:                                                     
                                                                      
       SPD_2P%DEL      ( REAL*8     ) -- Path delays for two          
                                         wavelengths. Units: meters.  
       SPD_2P%DEL_RDER ( REAL*8     ) -- Partial derivatives of path  
                                         delays with respect to       
                                         the height of the receiver   
                                         for two wavelengths.         
                                         Dimensionless.                
       SPD_2P%DEL_EDER ( REAL*8     ) -- Partial derivatives of path  
                                         delays with respect to       
                                         the height of the emitter    
                                         for two wavelengths.         
                                         Dimensionless.                
   The server reads the input fields and write into the output        
   fields.                                                            
                                                                      
     IUER ( INTEGER*4, OPT ) -- Universal error handler.              
                           Input: switch IUER=0 -- no error messages  
                                  will be generated even in the case  
                                  of error. IUER=-1 -- in the case of 
                                  error the message will be put on    
                                  stdout.                             
                           Output: 0 in the case of successful        
                                   completion and non-zero in the     
                                   case of error.                     

MATLAB:
~~~~~~~

Input parameters: 
                                                                      
   np           ( int  ) -- maximum size of the buffer spd_2p for     
                            transferring parameters to and back       
                            the SPD server.                           
   spd_2p    ( struct  ) -- Array of np data data structures for      
                            transferring data to and back SPD server. 
   cli_ptr   ( pointer ) -- Pointer to the internal data structure    
                            of the SPD_CLIENT.                        
   ivrb         ( int  ) -- Verbosity parameter.                      
                            0 -- silent mode. Only error messages are 
                                 printed.                             
                            1 -- normal verbosity. Progress messages  
                                 are printed.                         
                            2 -- debugging mode.                      
                                                                      
Output parameters: 
                                                                      
   spd_2p    ( struct  ) -- Array of np data data structures for      
                            transferring data to and back SPD server. 
   iuer      ( int     ) -- Error parameter.                          
                            0 -- no mistakes.                         
                            1 -- failure to communicate with the      
                                 server.                              
3) spd_cli_quit

Auxiliary routine SPD_CLI_QUIT deallocates dynamic memory grabbed for 
SPD client. MATLAB version also unloads the shared library.

Fortran, C:
----------

Input parameters: 
                                                                      
 SPD_CLI ( SPD_CLI__TYPE  ) -- internal SPD Client data structure that 
                               is used in every SPD Client operation. 

Input parameters: 

  spd_2p    ( struct  ) -- Array of np data data structures for      
                           transferring data to and back SPD server. 
  cli_ptr   ( pointer ) -- Pointer to the internal data structure    
                           of the SPD_CLIENT.                        


IV Configuration
----------------


The first line of a valid configuration file should have 
line SPD_CLIENT  Format version of 2015.01.10

The configuration file should define 6 parameters. The format:

    key: value

Lines that starts with # are considered as comments and are
discarded by the parser. All parameters should be defined. 
No implicit defaults are allowed. The following parameters 
should be defined

SERVER_NAME:  name of the server. If you use a tunnel to access
              the server, the server name should be local

SERVER_PORT:  Port number whether the server is running. Consult
              the server administrator to learn which port he has
              selected.

CONN_TIMEOUT: Connection timeout. 40.0 second is recommended

READ_TIMEOUT: Connection timeout. 10.0 second is recommended

SPD_LIB_PATH: path to the library path 

SPD_TYPE_1:   The first wavelength range. One of 532nm, 1064nm,
              and radio. "radio" range is valid for 100MHz -- 100GHz.

SPD_TYPE_2:   The second wavelength range. One of 532nm, 1064nm,
              radio, and none. If "none" is selected, spd_get_delay
              will put nothing in spd_2p.del_2nd, spd_2p.del_rder_2nd,
              spd_2p.del_eder_2nd. This will save time.


V Example of the configuration file
-----------------------------------


SPD_CLIENT  Format version of 2015.01.10
#
#  SPD client configuration file example
#
SERVER_NAME:  localhost
SERVER_PORT:  16000
CONN_TIMEOUT: 40.0
REQAD_TIMEOUT: 10.0
SPD_LIB_PATH: /opt64/lib
SPD_TYPE_1:   532nm
SPD_TYPE_2:   radio
