Lund Dst Model Implementations


The Lund Dst Model has been implemented in Java and Matlab. The models can be downloaded and used freely for noncommercial purposes. However, we do appreciate that an acknowledgement to the Swedish Institute of Space Physics in Lund is included where the model is used.

First we have a short introduction to the model. Users only interested to download the model may skip the Introduction and go directly to the Matlab or Java implementations below.

1. Introduction

1.1 The model

The model consists of a recurrent neural network as shown in the figure below. This type of network is also known as an Elman neural network. At the top left of the figure one hour averages of the solar wind magnetic field component Bz, density n, and velocity V are fed into the model. The data are normalized to the new variables u1, u2, and u3 so that they approximately lie in the range -1 to +1 and are used as the input data to the input layer. The outputs x1 to x4 in the hidden layer are weighted sums of the input and context layers data passed through the tanh function. At the output layer y is the weighted sum of the hidden layer outputs. Finally, the predicted Dst is obtained from a normalization of y. The data at the context layer is a copy of the output from the hidden layer at the previous time step. The context layer acts as a memory and thus enables the network to model dynamic systems. The first time the model is run the context data are not known, so they are set to some default values. The next time the model is run with a new solar wind sample the context values are known.

1.2 The meaning of forecast time

The predicted Dst is a one hour forecast from solar wind data measured just upstream of the Earth's magnetosphere. As we use hourly averages as input and output we must clarify what the one hour forecast actually means. The real time data comes in a continuous stream. At the same time the model assumes that the data arrives as one hour averages with a one hour sampling rate. To be able to compute the latest one hour average input data we must collect data for that whole hour. In the figure below we assume that the current time is between 05UT to 06UT. The latest one hour input data is computed from the data in the interval 04UT-05UT. The forecasted Dst is then valid for the next one hour interval, in the example 05UT-06UT. This means that the one hour forecast actually varies from a 0 hour forecast to 1 hour forecast.

To improve on the forecast time an approximate one hour average may be computed for the hour interval containing the current time (see figure below). One has to decide on how far into the current hour interval data should be collected before the approximate average is computed. E.g., using only the latest 30 minutes of data to compute the approximate one hour average will increase the forecast time to 0.5 hour to 1.5 hours.

It is thus up to the user of the model to decide how the one hour average solar wind data should be computed. The only import thing to remember is that the data should have a one hour sampling interval.

When the ACE spacecraft, or another spacecraft at L1, is used then the solar wind is measured 1.5 million km upstream of the Earth. The forecast time can then be increased by about 30 minutes to more than an hour depending on the current solar wind velocity.

A complete description of the model is given in a recently submitted paper to Geophysical Research Letters. We will put it here as soon as it has been accepted for publication.

2. Matlab implementation

The Matlab implementation consists of two M-files. It is run from the Matlab command line and requires a solar-wind input file to work. It produces an output file with predicted Dst and, optionally, a file that stores the final context values.

  1. Download the two M-files calcDst.m and lundDst.m.
  2. Download the input example file input.txt.
  3. Make sure that the files are in the Matlab search path.
  4. Start Matlab.

To look at the available options, type calcDst from Matlab command line without any arguments.

Type help calcDst or type help lund to get more information.

To run the model using a Bz-n-V input file, type calcDst('input.txt','output.txt'). The application will read data from the input file and produce an output file with the predicted Dst. The model will be initialized with the default context values. To run the model with different initial context values, add an extra argument with the name of a context data file. Type calcDst('input.txt','output.txt','context.txt'). If the context file does not exist when the above command is executed then the default context values will be used. When the model has run through all the data in the input file the last context values will be written to the context file.

3. Java implementation

The Java Dst implementation is organized in a package called se.irf.lund.dst that has been put in the Jar file dst.jar. To run the Lund Dst model from command line it is sufficient to study Section 3.1. Anyone interested in the code or if the Lund Dst model should be incorporated in another program may also study Section 3.2.

3.1 Application

  1. Download the Lund Dst model Jar file dst.jar.
  2. Download the input example file input.txt. and/or the input example file with time information inputWithTime.txt.

There are two versions of the application. One that only uses Bz, n, and V as input (ModelApp), and another that also uses date and time as input (ModelWithTimeApp). To look at the command line options run the applications without any arguments

java -cp dst.jar se.irf.lund.dst.ModelApp

or

java -cp dst.jar se.irf.lund.dst.ModelWithTimeApp

To run the model using a Bz-n-V input file type

java -cp dst.jar se.irf.lund.dst.ModelApp input.txt output.txt

The application will read the data from the input file and produce an output file with the predicted Dst together with the prediction time. The model will be initialized with the default context values and assuming a solar wind monitor at L1. To use another distance to the monitor an additional argument may be given with the distance in millions of km. E.g. with a monitor close to the Earth one can type

java -cp dst.jar se.irf.lund.dst.ModelApp input.txt output.txt 0.0

To run the model with different initial context values add an extra argument with the context data file

java -cp dst.jar se.irf.lund.dst.ModelApp input.txt output.txt L1 context.txt

Also note that we have used a distance equal to the distance to L1. Valid distance arguments are double values or the string L1. If the context file does not exist when the above command is executed then the default context values will be used. When the model has run through all the data in the input file the last context values will be written to the context file.

To run the model using a date-time-Bz-n-V input file type

java -cp dst.jar se.irf.lund.dst.ModelWithTimeApp inputWithTime.txt outputWithTime.txt

or if context data should be used (distance must also be given)

java -cp dst.jar se.irf.lund.dst.ModelWithTimeApp inputWithTime.txt outputWithTime.txt L1 context.txt

3.2 Code

If you want to study the Java code unpack the Jar file with

jar xf dst.jar

which should create the directory structure se/irf/lund/dst containing the four classes Elman, Model, ModelApp, and ModelWithTimeApp. To use e.g. the Model class in your own code it may look like

import se.irf.lund.dst.*;

class MyClass {

private Model model;

public void MyClass() {

this.model = new Model();

}

//Some more code ...

}

3.3 Java Documentation

The Dst model documentation describes the Java classes.


For questions or comments contact Regional Warning Center Sweden.
Friday, August 30, 2002.