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