=======  LANL*  =======
-----------------------
Author: Josef Koller
Email: jkoller@lanl.gov
Date: 19-Nov-2008
Version: 1.0
-----------------------

DESCRIPTION: 
------------
This is a fortran library that can calculate L* based on the
Tsyganenko 2001 storm model using a forward feed neural network.
The current version should be used only for geosynchronous 
locations. 

This is a public domain software release. 
You may use and modify it as you wish. Please send us an email 
with request for features and bug reports. 
We'd be happy to work with you.


HOW TO CITE THIS WORK:
----------------------
Any work using this software should be cited in the following way:

J. Koller, G. D. Reeves, R. H. W. Friedel (2009) "LANL* V1.0: A
Radiation Belt Drift Shell Model Suitable for Real-Time and 
Reanalysis Applications", Journal for Geoscientific Model Development
 

IN THIS DIRECTORY:
------------------

README    - this file
LICENSE   - license language
example.f - sample main program calling L* model
Makefile  - config file for the make utility
lib/ - all fortran routines are in here




COMPILATION:
------------
Call the standard make to compile the source code into a fortran
library called LANLstar_GEO.a    (run make from ../source/fortran).

	> make

There's also an example source code included "example.f" describing
how a main program could call the subroutine properly and return L*.
To make the example, call

	> make example

Then run the example by

        > ./example

The result should be close to:  6.085766059999295 

If the spacecraft is not on a closed drift shell, the value -99.0 will
be reported.


USAGE WITH FORTRAN:
-------------------
If you have a fortran code that you would like to use and call the
LANLstar_GEO library, you should compile it like
          
	> pgf77 yourcode.f LANLstar_GEO.a -o yourcode

In your code you will need to obtain solar wind parameters and G1, G2,
G2 for the Tsyganenko 2001 model. You will also need the coordinates
in GEO (cartesian in units of Re = 6371.2 km). 

You will also need to pre-calculate the McIllwain L and MLT based on your 
spacecraft location. These are required as input.

Look at the file example.f to see what other input is required. They
all have to be in double precision (although that sometimes doesn't
make sense, e.g. YEAR). The input values are also explained below.



USAGE WITH IDL:
---------------

The IDL functionality is implemented and tested for Linux, Intel archtecture,
32 bit or 64 bit, and using g77 and pgf77 compiler.

Use the make command to compile and create the relocatable object file (.so) for
use with IDL's call_external. The Makefile will automatically determine your system
architecture (32 bit or 64 bit).

	> make

The created library is called LANLstar_GEO.so and can be used in IDL. Simply
call up IDL and run the test code lanlstar_geo.pro which is an example
implementation of the IDL routine calling the fortran shared object.
	
	> idl
	IDL> idl_example, lib_name='LANLstar_GEO.so'

You should also be able to call the library from IDL with the following
calling sequence. NOTE: all variables MUST be declared double floats in IDL.  

    IDL> result = call_external(lib_name, 'Lstar_nnet_idl_', YEAR, $
	          DOY, UT_hr, lm, mlt, PA, Kp, Dst, dens, velo, $
                  Pdyn, ByIMF, BzIMF, G1, G2, G3, Lstar, /f_value)    


EXAMPLE OF INPUT VALUES:
------------------------

The following is a list of input values with examples, their units, 
the FORTRAN variable type and a short explanation.


      Kp = 20.0  ! omni2 format
      Dst = -3.0 ! Dst index (nT)
      dens = 3.9 ! solar wind density (cm^-3)
      velo = 410.0 ! solar wind velocity (km/s)
      Pdyn = 1.38  ! solar wind dynamic pressure (nPA)
      ByIMF = -3.1 ! GSM y component of IMF magnetic field (nT)
      BzIMF = 2.5  ! GSM z component of IMF magnetic field (nT)
      G1 = -0.89255239550589571  ! as defined in Tsyganenko 2002
      G2 = 0.0 ! as defined in Tsyganenko 2002
      G3 = 0.0 ! as defined in Tsyganenko 2002
      
      YEAR = 2002.0  ! year (in double precision  but don't use fractions)
      DOY = 2.0      ! day of the year
      UT_hr = 9.0    ! UT in units of hours; include minutes and seconds as fractions

      lm = 6.5896831261717335   ! McIllwain L for 90 deg PA
      mlt = 9.243973522191073   ! magnetic local time in hours
    
      PA = 80.0 ! Pitch angle in degrees; should be between 10 < PA < 90


HOW TO USE THE LANL* NEURAL NETWORK:
------------------------------------

After installation, use the following steps for calling the LANL*
library.

1) Obtain the required Kp, Dst, and solar wind input parameters from
an omni data base (from e.g. http://omniweb.gsfc.nasa.gov )

2) Obtain the coordinates of the spacecraft and convert to geomagnetic
coordinates. This can be done with the ONERA-DESP library by calling
the coordinate transformation subroutine and is often included with
spacecraft ephemeris.

3) Decide on a pitch angle between 10-90 degress. 

4) Call the LANL* subroutine to obtain the L* value for the
requested spacecraft location. If the spacecraft is located outside
the last closed drift shell, L* is not defined and the number
-99.0 is reported. 

Since version 1.0 of the LANL* model was trained
only with values inside the artificial geosynchronous coordinate
torus, it should only be used for the geosynchronous region as
well. If the satellite location is far away from this region, the
results are expected to be invalid. Future versions (in progress) will
extend the LANL* model to the full three-dimensional volume of the
inner magnetosphere.


PUBLIC DOMAIN SOFTWARE:
----------------------
 
This software has been authored by an employee or employees of Los Alamos 
National Security, LLC, operator of the Los Alamos National Laboratory (LANL) 
under Contract No. DE-AC52-06NA25396 with the U.S. Department of Energy.  
The U.S. Government has rights to use, reproduce, and distribute this software.  
The public may copy, distribute, prepare derivative works and publicly display 
this software without charge, provided that this Notice and any statement of 
authorship are reproduced on all copies.  Neither the Government nor LANS makes 
any warranty, express or implied, or assumes any liability or responsibility for 
the use of this software.  If software is modified to produce derivative works, 
such modified software should be clearly marked, so as not to confuse it with the 
version available from LANL.

The library also includes the file lib/ffnet.net (copyright 2006 by Marek Wojciechowski
mwojc@p.lodz.pl) distributed under the terms of the GNU General Public License (GPL).
