NOTE: The text files in this archive are formatted for the Unix platform. Use a conversion utility for best results on Macintosh or Windows systems. ============ INTRODUCTION ============ This document describes how to use the program L1D2 for estimating the largest Lyapunov exponent and correlation dimension of a reconstructed attractor. The input to the program is a scalar time series along with several parameters that control the operation of the algorithm. More information can be found in the following papers as well as many other publications on nonlinear time series analysis: M.T. Rosenstein, J.J. Collins, and C.J. De Luca. A practical method for calculating largest Lyapunov exponents from small data sets. Physica D 65:117-134, 1993. M.T. Rosenstein, J.J. Collins, and C.J. De Luca. Reconstruction expansion as a geometry-based framework for choosing proper delay times. Physica D 73:82-98, 1994. ======================= WARRANTY and DISCLAIMER ======================= This software package is provided AS IS without guarantees or warranty, expressed or implied. THE AUTHOR SHALL NOT BE LIABLE IN ANY WAY, EVEN FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES, IN CONNECTION WITH, OR ARISING OUT OF THE FURNISHING, THE PERFORMANCE, OR THE USE OF THIS SOFTWARE PACKAGE. The author is under no obligation to provide technical support, corrections, or upgrades to this software package. ==================== PRECOMPILED BINARIES ==================== The zip archive for L1D2 contains four precompiled executable files: L1D2_A Dec Alpha L1D2_L Linux L1D2_W.exe Windows98 L1D2_M.sit MacOS (compressed as a StuffIt archive) ===================== ABOUT THE SOURCE CODE ===================== The core algorithm implemented in L1D2 has been around for a while and has been tested, although the source code itself is in a (messy) preliminary form. Modifying the code is NOT recommended. Use it only to compile the program AS IS or to get some ideas for developing your own implementation. ===================== COMPILING THE PROGRAM ===================== On Unix systems, the easiest way to compile the program is to use gcc to create the executable file L1D2: gcc -lm -o L1D2 l1d2.c The program is written in generic C code, so it should compile on other systems as well. For instance, Metrowerks CodeWarrior provides the SIOUX console library that makes it easy to implement text-based programs for graphics-based operating systems like MS Windows and MacOS. ================== SAMPLE PROGRAM RUN ================== The following is a sample run of the program when executed from the Unix command-line prompt (details below). ---------- start sample ---------- L1D2> nice +15 L1D2 *** L1D2: generates scaling information for L1 and D2 *** v1.0 Copyright (c) 1999 M.T. Rosenstein (mtr@cs.umass.edu) reference: M.T. Rosenstein, J.J. Collins, C.J. De Luca, A practical method for calculating largest Lyapunov exponents from small data sets, Physica D 65:117-134, 1993. Enter test file name: lorenz.l1d2 Reading Test File... detected 2 tests Enter output file root (no extension): lorenz Processing test 1 of 2: 0....1....2....3....4....5....6....7....8....9....10 Processing test 2 of 2: 0....1....2....3....4....5....6....7....8....9....10 Saving data for largest Lyapunov exponent... Saving data for correlation dimension... Success! ---------- end sample ---------- ============= PROGRAM NOTES ============= The following list is meant to act as a preliminary user's guide to the program: (1) Type L1D2 at the command prompt to run the program. Some runs can be computationally intensive, so if you share your machine with others you may want to 'nice' the program as shown above. (2) After displaying some information, the program prompts you to enter the name of a test file. (This example uses the test file 'lorenz.l1d2' which is included in the zip archive along with a sample data file called 'lorenz.dat'.) The test file contains a list of all the information needed to run a set of tests. More on this below. (3) After reading the test file and reporting the number of tests detected, the program prompts you to enter the file root for the output. The example above uses 'lorenz' and so the program will save its results in two files: 'lorenz.d2' for the correlation dimension, and 'lorenz.l1' for the largest Lyapunov exponent. (4) Next the program shows the progress on each test. Each dot represents roughly 2% of the computation and the numbers mark the 10% complete point, the 20% complete point, and so on. (5) The output files are ASCII text that can be read into a spread sheet program (or a custom program) for further analysis. The first column shows the independent variable for the scaling plots. For D2, the independent variable is ln(R), where R refers to the length scale or radius for the nearest neighbor test. For L1, the independent variable is divergence time; the units are "samples" so you need to multiply by your data sampling period to get "real" time. (6) The next group of columns in the data file contain the dependent variable for each test, in the order given by the test file. For D2, the dependent variable is the (normalized) natural log of the correlation sum, and for L1 the dependent variable is the natural log of the divergence. (7) The next block of columns in the output files is essentially a repeat of the first group of columns. This time, however, the dependent variable is the slope of the line computed by a 7-point least-squares fit to the "raw" data from the first group of columns. (The 7 points were centered about the corresponding independent variable.) Plots showing the slope are sometimes helpful with the analysis, although the choice of a 7-point window may not be best for some applications. The slope data are included only as a convenience. (8) The input data file should be ASCII text with one time series per column and with white space separating columns (tabs are okay). Each line of the input file contains one data sample vector. You can include header information only at the top of the file by making the first character of a line by an asterisk '*' as in the test file. (9) Each time you run the program it creates a test file called 'sample.l1d2'. You can edit 'sample.l1d2' to make a new test file, but be sure to change the file name because the program will overwrite the old sample file. Here's the contents of the sample test file: * Header info starts with an asterisk. * * Each line of the test file contains the name of a data file * followed by the parameters for the test: * file_name series# startIndex stopIndex m J W divergeT * * file_name = name of the data file * series# = time series number to use for delay * reconstruction * startIndex = index of first data point to read (usually 1) * stopIndex = index of last data point to read * (enter 0 for maximum) * m = embedding dimension * J = delay in samples * W = window size for skipping temporally close * nearest neighbors * divergT = total divergence time in samples * example: lorenz.dat 1 1 0 5 7 100 300 (10) The sample test file contains header information that describes the file format. You MUST be familiar with all of the parameters, like the embedding dimension and the window size from Theiler's work (not to be confused with the embedding window size). Here's the contents of the test file ('lorenz.l1d2') that's included in the zip archive: * file_name series# startIndex stopIndex m J W divergeT lorenz.dat 1 1 0 5 11 300 500 lorenz.dat 2 1 0 7 7 300 500 (11) The above test file contains two tests. The first is for the x-coordinate time series of the Lorenz system (time series #1 in the first column of the data file) and the second is for the y-coordinate series (series #2 in the second column of the data file). The zeros indicate that the program should read all the available data, although you can change this to limit the number of data points. You can also change the start index if you need the program to extract data from the middle of the data file. (12) The divergence time is usually a guess at how long it will take the nearest neighbors to reach maximum divergence (on average). Guessing a value that is too big will slow down the computation, but not by a whole lot. Guessing a value that is too small may keep you from seeing the scaling region in the L1 results. ==================== FOR MORE INFORMATION ==================== Please direct questions, comments, and bug reports to Mike Rosenstein via email to mtr@cs.umass.edu