Changes between Version 3 and Version 4 of Libsrc_functions

01/20/12 09:00:23 (10 years ago)



  • Libsrc_functions

    v3 v4  
    195195At the moment, the Earthworm library routines are not a true library. Instead, they exist as object files in the vx.x/lib directory. After a module is compiled, it must be linked with the library objects that contain the library functions that have been called within the module. In this section, we give a synopsis of the functions within each of the library source file listed above. More details can be found in the comments within the source code. Many library function prototypes are given in vx.x/include/earthworm.h. Others are given in separate include files in vx.x/include. 
    196 chron3.c 
     197=== chron3.c === 
    198199This file contains time-conversion routines written by Carl Johnson, modified by Will Kohler and Lynn Dietz. In these routines, `julian' refers to the number of days (or minutes or seconds) since January 1, 1600. `Gregorian' dates consist of the four-digit year (1997), month numbered 1 through 12, day of the month, hours, minutes, and fractional seconds. 
    199201#include <chron3.h> 
    239241double tnow( void ); 
    240242        Return current system time in julian seconds. 
    241 fft_prep.c 
     245=== fft_prep.c === 
    243247fft_prep contains routines for setting up the structures needed for the Singleton FFT package, sing.c. The Singleton FFT's can be applied to sequence that are multiples of any prime integers. This provides much greater flexibility than the usual power-of-2 FFTs. However, if the sequence size is a multiple of large primes, or is prime itself, then the `fft' is no longer a `fast' Fourier transform. So fft_prep is used to build up a list of numbers that are multiples of powers of 2, 3 and 5. Then for any given sequence size, you can do a Singleton FFT using the next largest number in this list, padding your data to make up the difference. This saves CPU time and space. prepFFT() is the main function of interest. Other functions are primarily for debugging or internal use. prepFFT() is not required for sing.c; it's just a convenience. 
    244249#include <fft_prep.h> 
    245250long prepFFT( long n, FACT **pf ) 
    257262 *           -2 on other errors, logged here 
    258263 */ 
    259 fft99.c 
     266=== fft99.c === 
    261268This file provides the Temperton FFT (Fast Fourier Transform) package, written by Cleve Temperton at ECMWF, modified and documented by Russ Rew at NCAR in 1980. This packages includes two important (but not unique) features: it will do FFTs on sequence that are multiples of any prime integers, not just powers of 2. Secondly, it will transform a sequence of real data efficiently. Theory tells us that the Fourier transform of a real sequence is a conjugate-symmetric complex sequence. So instead of calculating and saving the repeated conjugate-symmetric values, these routines save that time and space. (See Cooley, Lewis & Welch, J. Sound Vib. (1970) 12(3) or any digital signal processing text.) For use of these routines, see the extensive comments in the source file fft99.c. 
    262270#include <fft99.h> 
    290298        module ids, and message types from the file earthworm.d  
    291299        in the EW_PARAMS directory. 
    292 geo_to_km.c 
    293303Contributed by Harley Benz. 
    294304 PURPOSE:  To compute the distance and azimuth between locations. 
    305315Calculations are based upon the reference spheroid of 1968 and 
    306316are defined by the major radius (RAD) and the flattening (FL). 
    307 kom.c 
     317=== kom.c === 
    309319Functions in this file, written by Carl Johnson, are used to open and parse configuration files. 
    310321#include <kom.h> 
    337348long   k_long( void );     Return next token as a long integer. 
    338 logit.c 
     351=== logit.c === 
    340353Functions in logit.c maintain and write daily log files and optionally on-screen messages. First call logit_init(), then call logit(). 
    341354The logit functions are compiled in two versions, one is multi-thread safe, the other is not. When linking with the thread-safe version (logit_mt.o), the program must also link with time_ew.o and sema_ew.o. When linking with the non-thread-safe version (logit.o), the program only needs to link with time_ew.o. 
    343357#include <earthworm.h> 
    361375           If any character is 'd', output is stamped with the process id.  
    362376        The rest of calling sequence is identical to printf(). 
    363 mem_circ_queue.c 
     379=== mem_circ_queue.c === 
    365381This is son of in 'queue_max_size.c', which is son of queue, which Will got from Kelley and Pohl. These were clever linked list schemes which allocated as needed. This was too scary: the system could run out of memory and fail after running for a long time. So, out with the cleverness, and in with brute force: this version pre- allocates the max amount of memory it will ever use at startup, and does the buffering in an array of message slots. The buffering is circular, as before: When we run out of message slots, we overwrite the oldest message. 
    366383#include <mem_circ_queue.h> 
    383400        Returns 0 if no error;  
    384401               -1 if the queue is empty. 
    385 parse_trig.c 
     404=== parse_trig.c === 
    387406parseSnippet() parses a trigger message. Inspired by, and uses, strtok. Therefore, IT IS NOT MULTI-THREAD SAFE. It must be mutex protected against concurrent calls to strtok.