FMI-method for computer K index evaluation C language version Lasse Hakkinen Finnish Meteorological Institute Department of Geophysics P.O.Box 503 FIN-00101 Helsinki Finland e-mail : Lasse.Hakkinen@fmi.fi phone: (+358)-9-19294634 fax: (+358)-9-19294603 This text along with the accompanying source files contain the means of computing geomagnetic K indices by a method developed at the Finnish Meteorological Institute (FMI-method; Sucksdorff et al., 1991*). The programs included are written in C language according to ANSI C standard. Anyone with some experience in programming in C and access to a C compiler should be able to use the method to compute K indices for his/her own magnetic data. The programs have been tested with several different C compilers in various platforms. Format of magnetic data in user's C program ------------------------------------------- The FMI-method computes K indices for one day at a time using the X and Y components of the magnetic field. In addition to the data for this particular day the method requires data for the previous day and the following day. So in his/her program the user should load magnetic data for the three consecutive days before calling the K index computation routine. The C language data type used to store the field values in computer's memory is a long. The magnetic field values are therefore integers. This however doesn't mean that one is restricted to 1 nT accuracy as the K index computation routine doesn't care what the unit of the values is. One could for example use a 0.1 nT accuracy (49213.2 nT -> 492132). If one reads the data from a file using the float type it is easy to convert the float types to long types with expression: LongVariable = (long) FloatVariable. The fact that the routine is insensitive to the field unit is due to the fact that the K=9 limit for the observatory is passed to the computation routine as one of the parameters. The unit of this parameter must be the same as the field values. The FMI-method doesn't care what the sampling rate of the data is. One could as well use one-minute values or 10-second values. The sampling rate is passed to the K index computation routine as one of the parameters (see next page). All that the programmer needs to take care of is that the X and Y component data arrays really contain data for three full days. As the sampling rate becomes smaller the size of these arrays grows. If a fixed sampling rate is used one could for example define the data arrays in the program as: #define SampleStep 60 #define Size 3*24*3600/SampleStep long X[Size]; long Y[Size]; The FMI-method is able to evaluate K indices even though there are gaps in the data. If the gap is not too large the missing values are replaced by linear interpolation. Currently the largest allowed gap is set to 15 minutes which however can be changed by editing the source code. One must use a special value for missing data points (e.g. 999999) so that the K computation routine will identify the missing values. The missing data point value is passed as one of the parameters to the computation routine. Calling the K index computation function from user's program ------------------------------------------------------------ The C language header file 'K_index.h' contains the routines for computing K indices by the FMI-method. There are several functions defined in this file but a user who wants to apply the method to his/her own data need use only one of them. This function is named 'K_index' and its definition is: void K_index(long *X_data,long *Y_data,long SampleStep,long K9_limit, long Longitude,long MissingData,long *K_table) The meaning of various parameters is: X_data Pointer to the start of the data array containing the X-component of the field values. The field values are stored as long's. In order to compute the K indices for one day the FMI-method requires data for previous day and following day. Therefore the X_data array must contain data exactly for three days (i.e. if sampling rate is one minute the X_data array must have 3*1440 = 4320 elements). Y_data Pointer to the start of the data array containing the Y-component of the field values. SampleStep Time between successive data points in seconds (e.g. if minute values are used then SampleStep = 60) K9_limit K=9 limit for the particular observatory. Here the unit is the same as used in the field values. (e.g. if the K=9 limit is 750 nT for the observatory and field values are expressed with a 0.1 nT accuracy then K9_limit = 7500). Longitude The longitude of the observatory whose K indices are to be computed rounded to nearest integer. The FMI-method uses this to determine the time of local midnight. (e.g. Nurmijarvi longitude is 24.65 degrees, so Longitude = 25). MissingData Marker for a missing value (e.g. 999999). K_table This is the table where the eight computed K values are returned. So one should define in his/her program an array: long K[8]. If the program is unable to compute a K value (due to missing data) a value -1 is substituted for that particular element. A demo program -------------- Included is a short example program (demo.c) that computes the K indices for one day by calling the K_index function. Here it is assumed that the magnetic data is in a single file containing data for three days. The values of some parameters used in the program are for the Nurmijarvi observatory. This demo program and the accompanying data file (demo.dat) are also included in the 'K index computation, FMI-method'-disk. In Unix systems one should compile the program simply by the command cc demo.c -lm Here the option -lm is for including the mathlibraries. This command will create an executable file a.out which may then be executed by command ./a.out For this demo file the output of this command (K-indices and Ak value) should be 1 1 1 2 3 3 5 3 14 /********************************************************************/ /* A short demo program demonstrating the use of K_index.h file */ /* This program assumes that the data file is named as 'demo.dat' */ /* and is located in the same directory as the program itself. */ /* The computed K indices and Ak value should be: */ /* 1 1 1 2 3 3 5 3 14 */ /********************************************************************/ #include #include "K_index.h" #define SampleStep 60 /* Interval between data points in seconds */ #define Size 3*24*3600/SampleStep /* Size of data arrays */ #define Longitude 27 /* Longitude of the observatory */ #define K9limit 7500 /* K=9 limit, here 750 nT */ #define MissingData 999999 /* Marker for missing data point */ int main() { long i; /* Dummy index */ FILE *DataFile; /* File variable */ char *FileName = "demo.dat"; /* In real life one should read */ /* this from command line or ask user */ /* In Unix one could also use 'stdin' */ long X[Size]; /* Array for X component data */ long Y[Size]; /* Array for Y component data */ long K_array[8]; /* Computed K indices */ /* Read the data into the X and Y arrays */ if ((DataFile = fopen(FileName,"r")) == NULL) return(1); for (i=0;i