**IMAGE (Imager for Magnetopause-to-Aurora Global Exploration)**

**LENA (Low Energy Neutral Atom)**

**Programmer's Reference Manual**

September 10, 2004

Goddard Space Flight Center

Greenbelt, Maryland

**LENA Data Processing System**

**Programmer's Reference Manual**

September 10, 2004

Responsible NASA officials:

Dr. Thomas E. Moore

Thomas.E.Moore@nasa.gov

Mission Scientist for IMAGE

LENA Lead Co-Investigator

Code 692.0

Goddard Space Flight Center

Dr. Michael R. Collier

Michael.R.Collier@nasa.gov

Lead Experiment Scientist, Heliospheric

And Operations Participating Scientist

Code 692.0

Goddard Space Flight Center

1.0 Introduction [1](#introduction)

1.1 Purpose and Scope [1](#purpose-and-scope)

1.2 LENA Data Flow Overview [1](#lena-data-flow-overview)

2.0 Commercial Off The Shelf (COTS) Software
[2](#commercial-off-the-shelf-cots-software)

2.1 UDF Kernel Software [2](#udf-kernel-software)

2.1.1 Tool to Install UDF data [2](#tool-to-install-udf-data)

2.1.2 UDF Dynamic Load Module (DLM) [2](#udf-dynamic-load-module-dlm)

2.1.3 UDF Database [3](#udf-database)

2.2 IDL [3](#idl)

2.3 PERL [3](#perl)

2.4 APACHE Web Server [3](#apache-web-server)

3.0 LENA Development Environment [3](#lena-development-environment)

3.1 Location of LDPS Developed Software
[4](#location-of-ldps-developed-software)

3.2 Location of UDF Software Applications
[4](#location-of-udf-software-applications)

3.3 LENA Environment Files [5](#lena-environment-files)

3.4 Makefiles [5](#makefiles)

3.4.1 LDPS IDL Makefile [5](#ldps-idl-makefile)

3.4.2 LDPS Fortran/C Makefile [5](#ldps-fortranc-makefile)

4.0 LDPS Processing Flow [5](#ldps-processing-flow)

5.0 UDF Data Files [6](#udf-data-files)

5.1 LENA Science Data [7](#lena-science-data)

5.2 LENA Housekeeping Data [7](#lena-housekeeping-data)

5.3 Orbit and Attitude Data [8](#orbit-and-attitude-data)

5.4 LENA PIDFs [8](#lena-pidfs)

5.5 LENA VIDFS [9](#lena-vidfs)

5.6 Schedule of LENA Data Availability and Major Bug Fixes in the UDF
Data
[9](#schedule-of-lena-data-availability-and-major-bug-fixes-in-the-udf-data)

6.0 Software Design Methodology [10](#software-design-methodology)

7.0 LENA Global Units [12](#lena-global-units)

7.1 LENA Time Manipulation [13](#lena-time-manipulation)

7.2 LENA Output Product Generation [14](#lena-output-product-generation)

7.3 LENA UDF Database Access [15](#lena-udf-database-access)

7.4 LENA Image Correction [15](#lena-image-correction)

7.5 LENA Unit Conversions [16](#lena-unit-conversions)

7.6 LENA Data Gap Handling [16](#lena-data-gap-handling)

7.7 LENA Color and Trace Indicator Routines
[16](#lena-color-and-trace-indicator-routines)

8.0 LENA Data Processing Units [18](#lena-data-processing-units)

8.1 LDPS Main Calling Procedure [19](#ldps-main-calling-procedure)

8.2 Process Singles Data [19](#process-singles-data)

8.3 Process Binned or Event Data [20](#process-binned-or-event-data)

8.4 Process Image/Binned Data [20](#process-imagebinned-data)

8.5 Process Event Data [21](#process-event-data)

8.6 Process Sectored Event/Sun Pulse Data
[22](#process-sectored-eventsun-pulse-data)

8.7 Process Apogee Data [22](#process-apogee-data)

8.8 Process Perigee Data [23](#process-perigee-data)

8.9 Process Region-Of-Interest Data
[23](#process-region-of-interest-data)

8.10 Process Browse Data [23](#process-browse-data)

8.11 Process Echo Data [25](#process-echo-data)

8.12 Process Housekeeping Data [26](#process-housekeeping-data)

8.13 Process Memory Dump Data [26](#process-memory-dump-data)

8.14 Process Power Supply Command Data
[27](#process-power-supply-command-data)

8.15 Process Power Supply Monitor Data
[27](#process-power-supply-monitor-data)

8.16 Process State Table Data [27](#process-state-table-data)

8.17 Process Instrument State Data [28](#process-instrument-state-data)

8.18 Process Long Term Trending Data
[28](#process-long-term-trending-data)

8.19 Process Orbit and Attitude Data
[28](#process-orbit-and-attitude-data)

8.20 Process Miscellaneous Combination Data Plots
[29](#process-miscellaneous-combination-data-plots)

8.21 Process Magnetic Field Values (Tsyganenko model)
[30](#process-magnetic-field-values-tsyganenko-model)

9.0 Portability Issues [30](#portability-issues)

Acronyms and Abbreviations [31](#acronyms-and-abbreviations)

# 1.0 Introduction

## 1.1 Purpose and Scope

This document provides a high level overview of the Low Energy Neutral
Atom (LENA) Data Processing System (LDPS) design methodology and
provides a description of the available software modules. This document
serves as an aid for programmers who maintain and implement enhancements
to the software.

The author assumes the reader possesses a basic knowledge of the UNIX
and Interactive Data Language (IDL) programming environment.

## 1.2 LENA Data Flow Overview

![](media/image1.wmf){width="6.35in" height="4.188888888888889in"}

The Science Mission Operations Center (SMOC) located at Goddard Space
Flight Center (GSFC) receives the instrument health and safety and Level
0 products from South West Research Institute (SWRI) and converts those
data into the Universal Data Format (UDF) format. The LDPS downloads the
UDF data from the SMOC and provides the science community with Level 0.5
data products on a daily basis.

# 2.0 Commercial Off The Shelf (COTS) Software

The LDPS uses four different COTS software products: the Universal Data
Format (UDF) kernel software and application tools, the IDL libraries,
the Practical Extraction and Report Language (PERL) libraries, and the
APACHE web server.

## 2.1 UDF Kernel Software

The UDF kernel includes the database, the archival system, the graphical
user interface (GUI) plot program, the ASCII text dump program, the
common data format (CDF) and IDL interfaces, and the algorithms to
access the instrument data. Chris Gurgiolo of BitterRoot Research
developed this software. A copy of the software and documentation is
available at the IMAGE software archive,
[http://image.gsfc.nasa.gov](http://image.gsfc.nasa.gov/).

### 2.1.1 Tool to Install UDF data

The UDF software provides two interfaces to install the UDF data: the
command line using the UDFInstall executable and the GUI interface
option, the UDFAdmin. The UDFAdmin also provides the capability to
create the project data tiers, to remove data sets, and to rebuild the
UDF database. The LDPS production code uses the UDFInstall to
automatically install the UDF data sets onto the database daily. These
executables are found on goewin.gsfc.nasa.gov in the
/archive4/LenaSW/LenaUDF/UDFTools/bin directory.

### 2.1.2 UDF Dynamic Load Module (DLM)

The UDF-DLM, a library of C routines, provides LDPS with direct access
to the UDF data format via IDL. This module eliminates the need to use
the UDF specific Plot or Dump GUI applications to access the data. A
copy of the DLM software is available at the IMAGE software archive at
[http://image.gsfc.nasa.gov](http://image.gsfc.nasa.gov/).

### 2.1.3 UDF Database

The UDF database houses the quicklook and the definitive data for
multiple instruments. In addition to the LENA data sets, these data sets
may include Medium Energy Neutral Atom (MENA) imager, High Energy
Neutral Atom (HENA) imager, Far Ultraviolet Imager (FUV), Extreme
Ultraviolet (EUV) imager, Radio Plasma Imaging (RPI), and orbit and
attitude (OA) data. The UDF database on goewin.gsfc.nasa.gov contains
only the LENA quicklook, definitive, and OA data.

## 2.2 IDL

The interactive data language (IDL) is used to implement the core LDPS
software. Please see the LENA User's Guide or Section 3.3 of this
document for more information regarding obtaining a license.

## 2.3 PERL

The automated LDPS daily product generation scripts are written using
PERL. These scripts include the download of the UDF data bundles from
the SMOC, the generation of the IDL plots, and the update of the gifwalk
products on the web site. These scripts can be found in
/space/cgi-bin/lena on goewin.gsfc.nasa.gov.

## 2.4 APACHE Web Server

LDPS uses the APACHE web server. The server allows LDPS to provide the
science community with a web page to generate custom plots. The users
can also peruse the LENA data without the need to install UDF specific
software on their machines. This sever is available from the APACHE
organization at http://www.apache.org.

# 3.0 LENA Development Environment

This section describes the location of the LENA software and the related
COTS applications that are on goewin.gsfc.nasa.gov. On the Tokyo
mirror-site, [http://lena.ice.uec.ac.jp](http://lena.ice.uec.ac.jp/),
the paths to the directories should be prefixed with /radar04/lena/html.

## 3.1 Location of LDPS Developed Software

/archive4/LenaSW/LDPS/src

## 3.2 Location of UDF Software Applications

/archive4/LenaSW/LenaUDF/udf/Archives

/archive4/LenaSW/LenaUDF/udf/PKGS

/archive4/LenaSW/LenaUDF/udf/bin

/archive4/LenaSW/LenaUDF/udf/config

/archive4/LenaSW/LenaUDF/udf/include

/archive4/LenaSW/LenaUDF/udf/lib

/archive4/LenaSW/LenaUDF/udf/src ==\>UDF Kernel Software

/archive4/LenaSW/LenaUDF/UDFTools ==\> UDF Admin, GUI tools

/archive4/LenaSW/LenaUDF/UDFTools/ADump

/archive4/LenaSW/LenaUDF/UDFTools/ALLPKGS

/archive4/LenaSW/LenaUDF/UDFTools/Admin

/archive4/LenaSW/LenaUDF/UDFTools/Archives

/archive4/LenaSW/LenaUDF/UDFTools/Gmenu

/archive4/LenaSW/LenaUDF/UDFTools/PKGS

/archive4/LenaSW/LenaUDF/UDFTools/PkgInst

/archive4/LenaSW/LenaUDF/UDFTools/Plots

/archive4/LenaSW/LenaUDF/UDFTools/UDFToCDF

/archive4/LenaSW/LenaUDF/UDFTools/UDFToIDL

/archive4/LenaSW/LenaUDF/UDFTools/bin

/archive4/LenaSW/LenaUDF/UDFTools/dBATools

/archive4/LenaSW/LenaUDF/UDFTools/dBTools

/archive4/LenaSW/LenaUDF/gph/PKGS

/archive4/LenaSW/LenaUDF/gph/ancillary

/archive4/LenaSW/LenaUDF/gph/c_kernal

/archive4/LenaSW/LenaUDF/gph/ctable

/archive4/LenaSW/LenaUDF/gph/datafiles

/archive4/LenaSW/LenaUDF/gph/drivers

/archive4/LenaSW/LenaUDF/gph/g_kernal

/archive4/LenaSW/LenaUDF/gph/include

/archive4/LenaSW/LenaUDF/gph/lib

/archive4/LenaSW/LenaUDF/gph/m_kernal

/archive4/LenaSW/LenaUDF/gph/maintenance

/archive4/LenaSW/LenaUDF/gph/mapdata

/archive4/LenaSW/LenaUDF/gph/p_kernal

/archive4/LenaSW/LenaUDF/gph/t_kernal

/archive4/LenaSW/LenaUDF/gph/testplots

## 3.3 LENA Environment Files

A copy of the environment file, lena_env, is available on
/archive4/LenaSW/LenaUDF on goewin.gsfc.nasa.gov. If the lena_env file
is not available, then please see the LENA User's Guide for set up
information. These environment variables must be set before using the
COTS products.

## 3.4 Makefiles

### 3.4.1 LDPS IDL Makefile

This file compiles all of the LDPS IDL routines. This file is located in
the LDPS software directory, /archive4/LenaSW/LDPS/src and is called
create_lena_plots.

### 3.4.2 LDPS Fortran/C Makefile

The LDPS uses various physical unit conversion algorithms that are
written in the Fortran programming language. In order for IDL to
interface with these algorithms, a C wrapper routine passes data
parameters between Fortran and IDL. The README files and compile_t96 are
available in the LDPS software directory, /archive4/LenaSW/LDPS/src.

# 4.0 LDPS Processing Flow

![](media/image2.wmf){width="5.9944444444444445in"
height="4.424305555555556in"}

Figure 2.0 LDPS Process Flow

Figure 2.0 describes the processing sequence of the LENA data. LENA data
plots are generated on a daily basis using the production scripts that
automatically download the most recent UDF data from the SMOC, calls the
LENAplot algorithms, and generates plots for the gifwalk that are stored
on the RAID archives. Users may also generate customized plots by
filling in web forms or directly modifying the runtime files.

# 5.0 UDF Data Files

The UDF database contains the following files: the virtual instrument
data file (VIDF), the plot instrument data file (PIDF), the UDF database
files, and the definitive and quicklook instrument data files. The VIDF
files contain algorithms to manipulate and process the data. The PIDF
files describe the execution sequence of algorithms and provide plot
specifications. The UDF database files provide a view of the most
current files available in the database. The definitive and quicklook
files contain the instrument data. The quicklook files contain two
passes a day and provides data to monitor the health and safety of the
instrument. The 24-hour definitive files are time sorted, time ordered,
and redundancies removed.

## 5.1 LENA Science Data

The location of the definitive LENA science data:

/archive4/UDFDATA/IMAGE/IMAGE1/LENA/LENASCI

The location of the quicklook LENA science data:

/archive4/UDFDATA/IMAGE/IMAGE1Q/LENA/LENASCI

The file names for both quicklook and definitive LENA science data:

IMLSNGLS singles data

IMLIMAGE image/binned data

IMLEVENT event data

IMLEVSP sectored events/sun pulse data

IMLROI0 region-of-interest 0 data

IMLROI1 region-of-interest 1 data

IMLROI2 region-of-interest 2 data

IMLROI3 region-of-interest 3 data

IMLROISM region-of-interest summation data

## 5.2 LENA Housekeeping Data

The location of the definitive LENA Housekeeping data:

/archive4/UDFDATA/IMAGE/IMAGE1/LENA/LENAHSKP

The location of the quicklook LENA Housekeeping data:

/archive4/UDFDATA/IMAGE/IMAGE1Q/LENA/LENAHSKP

The file names for both the quicklook and definitive LENA housekeeping
data:

IMLHSKP housekeeping data

IMLNAHSK normal-A housekeeping data

IMLECHO command record data

IMLDHSKP diagnostic housekeeping data

IMLHKPRT housekeeping performance data

IMLHVSTB high voltage power supply

IMLMEMD data read

IMLQLOOK quicklook housekeeping data

IMLSGMON segment format monitor data

IMLSTRCH housekeeping stripchart

## 5.3 Orbit and Attitude Data

The location of the definitive orbit and attitude data:

/archive4/UDFDATA/IMAGE/IMAGE1/OA/ORBIT

The location of the quicklook orbit and attitude data:

/archive4/UDFDATA/IMAGE/IMAGE1Q/OA/ORBIT

The file name for both the quicklook and definitive orbit and attitude
data:

IMLOORBIT

## 5.4 LENA PIDFs

The location of the definitive LENA PIDFS:

/archive4/UDFDATA/IMAGE/IMAGE1/PIDFS

The location of the quicklook LENA PIDFS:

/archive4/UDFDATA/IMAGE/IMAGE1Q/PIDFS

The file names for both the quicklook and definitive LENA PIDFS:

IMLDHSKP.pidf.v2\*

IMLECHO.pidf.v2\*

IMLERRPK.pidf.v2\*

IMLEVENT.pidf.v2\*

IMLEVSP.pidf.v2

IMLHKPRT.pidf.v2\*

IMLHSKP.pidf.v2

IMLHVSTB.pidf.v2\*

IMLIMAGE.pidf.v2\*

IMLMEMD.pidf.v2\*

IMLNAHSK.pidf.v2\*

IMLQLOOK.pidf.v2\*

IMLROI0.pidf.v2\*

IMLROI1.pidf.v2\*

IMLROI2.pidf.v2\*

IMLROI3.pidf.v2\*

IMLROISM.pidf.v2\*

IMLSGMON.pidf.v2

IMLSNGLS.pidf.v2\*

IMLSTRCH.pidf.v2\*

## 5.5 LENA VIDFS

The location of the definitive LENA VIDFS:

/archive4/UDFDATA/IMAGE/IMAGE1/VIDFS

The location of the quicklook LENA VIDFS:

/archive4/UDFDATA/IMAGE/IMAGE1Q/VIDFS

The file names for both the quicklook and definitive LENA VIDFS:

IMLDHSKP19980010000V\*

IMLECHO19980010000V\*

IMLERRPK19980010000V\*

IMLEVENT19980010000V\*

IMLEVSP19980010000V\*

IMLHKPRT19980010000V\*

IMLHSKP19980010000V\*

IMLHVSTB19980010000V\*

IMLIMAGE19980010000V\*

IMLMEMD19980010000V\*

IMLNAHSK19980010000V\*

IMLQLOOK19980010000V\*

IMLROI019980010000V\*

IMLROI119980010000V\*

IMLROI219980010000V\*

IMLROI319980010000V\*

IMLROISM19980010000V\*

IMLSGMON19980010000V\*

IMLSNGLS19980010000V\*

IMLSTRCH19980010000V\*

## 5.6 Schedule of LENA Data Availability and Major Bug Fixes in the UDF Data

Due to the flight software upload, various data sets are available at
different times during the mission and in different science data
packets. The table also includes any significant software bug fixes that
affect the LENA data.

  ----------------------------------- -----------------------------------
  Date                                Description

                                      

  March 25, 2000 -- July 31, 2000     No IMLROISM (ROI summation) and
                                      IMLEVSP (Sectored Events, Sun
                                      Pulse) science data

  July 31, 2000                       LENA Flight Software Upload

  July 31, 2000 -- October 16, 2000   IMLROISM and IMLEVSP science data
                                      available in the IMLMEMD data

  October 16, 2000                    IMLROISM and IMLEVSP are sent down
                                      as individual packets. No longer
                                      embedded in the IMLMEMD.

  October 16, 2000 -- December 5,     SMOC not aware of IMLROISM and
  2000                                IMLEVSP data availability. No
                                      IMLEVSP and IMLROISM data.

  December 6, 2000                    SMOC processes IMLROISM and
                                      IMLEVSP. These science packets are
                                      now available.

  January 11, 2001                    IMLEVENT (Event science data
                                      packets), time of flight data all
                                      zeros

  June 26, 2001                       SMOC adds IMLNAHSKP (Normal
                                      Housekeeping) to FEDS table. Begin
                                      receiving this housekeeping data
                                      packet.

  April 20, 2001                      Chris Gurgiolo fixes IMLEVENT
                                      problem of all zeros in time of
                                      flight data

  April 21, 2001                      SMOC reprocesses all of the LENA
                                      UDF data.
  ----------------------------------- -----------------------------------

# 6.0 Software Design Methodology

The LENA software was designed with the intent of flexibility and
modularity. All LENA data processing for the science and housekeeping
data packets are separated into reading, processing, and plotting data
routines.

All data packet related sub-routines and functions are stored in one
file. Several routines are considered global such that they are not
associated with a specific data packet and can be used as if a
\"global\" routine. The IDL common blocks are accessible to those
routines that also define those common blocks.

![](media/image3.wmf){width="5.997222222222222in"
height="4.254861111111111in"}Figure 3.0 LDPS Data Flow Level 0

![](media/image4.wmf){width="5.9944444444444445in"
height="3.6243055555555554in"}Figure 3.1 LDPS Data Flow Level

![](media/image5.wmf){width="5.993055555555555in"
height="4.301388888888889in"}Figure 3.2 LDPS Data Flow Level 2

# 7.0 LENA Global Units

The LENA Global Units includes the following categories:

1.  Time manipulation

2.  Output product generation

3.  UDF Database Access

4.  Image Correction

5.  Unit Conversion

6.  Data Gap Handling

7.  Color and trace indictors

## 7.1 LENA Time Manipulation

• l_TimeRtns.pro

This file contains all routines related to time checks and conversions.
The launch date March 25, 2000, day of year 85, is used as the Epoch
time.

> • l_ConvSec2DOYTime \-- convert the time given in seconds to the
> calendar day of year

• l_ConvDOY2YMD \-- convert the day of year to year, month, and day.

> • AddExtraTime2Start -- add a specified amount of time given in
> seconds to the user start time.
>
> • AddExtraTime2Stop -- add a specified amount of time given in seconds
> to the user stop time.
>
> • l_ConvYMD2DOY \-- convert year, month, and day to the day of year
> format.
>
> • l_GetTime---converts the UDF time
> (yyyy/doy/hour/minutes/seconds/microseconds) into seconds
>
> • l_InputTimeConv \-- determine user date/time input and convert the
> time into the UDF (year/day of year), if necessary.
>
> • ChckStartTime -- check if the user specified start time is after
> 00:00:00. If so, read the specified number of extra spins. Extra spins
> are needed when centering the sun, the earth, or the moon to zero
> degree spin angle.
>
> • ChckStopTime -- check if the user specified stop time is before
> 23:59:59. If so, read the specified number of extra spins. Extra spins
> are needed when centering the sun, the earth, or the moon to zero
> degree spin angle.
>
> • Convert -- convert user time into seconds using the IMAGE launch
> date as the epoch time.

• l_LeapYear -- determine if the current year is a leap year.

> • FindDOYSinceLaunch \-- determine the calendar day of year using the
> IMAGE launch day of year 85 (March 25, 2000) as day of year one.
>
> • MET2UTCSTR \-- convert the Mission Elapsed Time into Universal Time
> Coordinate. Return the string format HH:MM:SS.
>
> • ConvSec2Arr \-- converts seconds into the array format \[year, doy,
> hh, mm, ss\]
>
> • ConvToUtc \-- convert seconds to Universal Time Coordinate.
>
> • ConvArrTimeToSecs -- convert the time in the array format \[year,
> doy, hh, mm, sec\] into seconds

## 7.2 LENA Output Product Generation

• l_DumpRtns.pro

> • l_DumpHdrInfo -- generates a generic header of information
> pertaining to the file contents and the file creation.

• l_DumpData -- formats and writes data as an ASCII text file

• l_GenRtns.pro

• l_GenFileName -- builds an output file name

• l_GenGif -- generates a GIF image file

• l_GenPng -- generates a PNG image file

• l_PlotRtns.pro

> • l_SetUpDisplay -- initializes the user selected output device (X,
> PS, Z buffer, GIF/PNG) for output display

• l_DrawXTicks -- draws major and minor tick marks along the X-axis

• l_DrawXTickNLabels -- draws the major tick labels on the X-axis

• l_PlotTokarDisplay -- generates a Tokar plot

• l_PlotFrame -- generates the X-Y axis

• l_PlotStuff -- generates a line plot of the data

• l_PlotLttStuff -- generates a long term trending plot

• l_DrawLegend -- creates a data legend for a spectrogram plot

• l_CreatePlotHdr -- generates a standard plot information header/title

> • l_TrailerDoc -- draws earth and spacecraft distances and selected
> housekeeping parameters on the bottom of the plot page
>
> • l_TrailerLttDoc -- draws general plot information for long term
> trending plots
>
> • l_ChckCompPg -- determine if a new plot page is needed
>
> • l_SetUpZBuffer -- set up the IDL Z-buffer device to draw 2D graphics
> in a buffer contained in memory
>
> • l_AdjPlotSize -- determine the height and width of each plot given
> the total number of plots and the size of the plotting area. A
> predefined maximum of 6 plots are displayable per plot page.

• l_PlotImage.pro -- determines the type of browse image to create: a
three panel 12x45 image, a three panel image with earth-spacecraft
distance held constant, or a three panel 12x12 image.

## 7.3 LENA UDF Database Access

• l_ReadSetup.pro -- reads the user specified run-time setup file for
data and plot options.

• l_UdfRtns.pro

> • l_UdfGetDataHandle -- opens the UDF DB and determines if definitive
> or quicklook LENA UDF data are available. Returns a file handle.
>
> • l_UdfGetNumRec -- determines the number of data records available
> for a given time period

## 7.4 LENA Image Correction

• l_ImageCorrection.pro

> • l_CorrectImages -- correct the distorted images in the binned/image
> and event data

## 7.5 LENA Unit Conversions

• geopack_dip.pro \-- these FORTRAN routines are used for coordinate
transformations. The Science Mission Operations Center (SMOC) provides
updates to this file.

• l_ConversionRtns.pro -- includes routines to convert data to count
rate, log, flux, and temperature data to Celsius.

• l_NumFluxRtns.pro

• l_CalcEfficiency -- calculate the efficiency based on the instrument
state

> • l_GenEffTable -- generate a table of Hydrogen and Oxygen efficiency
> values
>
> • l_FindNomialEff -- determine the nominal efficiency for
>
> hydrogen or oxygen based on species and energy
>
> • l_WriteEff2File -- write the efficiency values to a text file

## 7.6 LENA Data Gap Handling

• l_HndlMissData.pro \-- fills in data gaps with filler data. Filler
data equals the NO_DATA parameter (-9999.).

• l_HndlMissOA.pro \-- interpolates missing OA data resulting from data
drop outs.

• l_Interpolate.pro \-- linear interpolation routine

• l_DataGap.pro -- determine if there is a data gap. Data gaps are
defined to be periods of no data greater than 120 seconds plus a
predefined threshold.

## 7.7 LENA Color and Trace Indicator Routines

• l_ColorRtns.pro

> • l_CreateColorBar -- creates a color bar based on the user selected
> color table
>
> • l_LoadRedTempCT -- generates RGB values for a red temperature color
> table

• l_LoadColor -- loads the user selected color table

> • l_DrawColorBar -- creates and plots a color bar along the side of a
> spectrogram

• l_ScaleColor -- scale the LENA data to the selected color table

• l_DetMjMnTicks.pro -- calculates the number of major and minor X-axis
tick marks needed, the delta time, and the time label string based on
the data start and stop time.

• l_Adj2SunOrEarth.pro

> • FindZeroDegBinNo -- determine which bin number (0-44) corresponds to
> zero degrees given the maximum spin angle

• MatchOA2Data -- synchronize sun sector data to the LENA data

> • l_Adj2SunOrEarth -- given the earth, sun, or moon location, center
> the user selected trace (earth, sun, or moon) to zero degree spin
> angle.

• l_SunPulseRtns.pro

> • l_CalcSunPulse \-- uses the OA data to determine which spin sector
> the sun is in
>
> • l_DetermineSunDir \-- determines the current location (spin sector)
> of the sun after the earth or the moon trace has been centered to zero
> degree spin angle
>
> • l_DrawSunDir -- draws the sun direction on the spectrogram plot
>
> • l_CalcSunDirection -- main procedure that calls the routines to
> calculate and draw the sun direction

• l_EarthRtns.pro

> • l_DrawEarthDirection -- draws the earth's limbs, the height/width of
> the earth, on the spectrogram. Used when the earth trace is centered
> at zero degree spin angle
>
> • l_DrawEarthCenter -- draw the location of the earth on the
> spectrogram when the earth is not centered at zero degree spin angle.
>
> • l_DetermineEarthDir -- determines the current location (spin sector)
> of the earth after the sun or the moon trace has been centered to zero
> degree spin angle
>
> • l_CalcEarthDirection -- main procedure used to call the routines to
> calculate and draw the earth direction

• l_RamRtns.pro

> • l_DrawRamDirection -- draws the RAM direction on the spectrogram.
>
> • l_DetermineRamDir -- determines the current location (spin sector)
> of the ram direction when the earth, the moon, or the sun is centered
> at zero degree spin angle.
>
> • l_CalcRamDirection -- main procedure used to call the routines to
> calculate and draw the ram direction

• l_MagFieldRtns.pro

> • l_DrawBDirection -- draws the magnetic field line on the spectrogram
>
> • l_DetermineBDir -- determines the current location (spin sector) of
> the magnetic field line when the earth, the moon, or the sun is
> centered at zero degree spin angle.
>
> • l_CalcBDirection -- calls the routines to calculate and draw the
> magnetic field lines

• l_MagField_c2idl.pro

> • l_CallT96Model -- IDL routine that calls the Fortran T96
> (Tsyganenko) model

# 8.0 LENA Data Processing Units

These routines are specific to a science or a housekeeping data type.

1.  Main Calling Procedure

2.  Process Singles Data

3.  Process Binned or Event Data

4.  Process Image/Binned Data

5.  Process Event Data

6.  Process Sectored Events/Sun Pulse Data

7.  Process Apogee Data

8.  Process Perigee Data

9.  Process ROI data

10. Process Browse Data

11. Process Echo Data

12. Process Housekeeping Data

13. Process Memory Dump Data

14. Process Power Supply Command Data

15. Process Power Supply Monitor Data

16. Process State Table Data

17. Process Instrument State Data

18. Process Long Term Trending Data

19. Process Orbit and Attitude Data

20. Process Miscellaneous Combination Data Plots

21. Process Magnetic Field Values (Tsyganenko model)

## 8.1 LDPS Main Calling Procedure

• l_LenaPlot.pro

This file contains routines responsible for defining and initializing
data structures, reading the user desired plot options, selecting the
routine to process the data, and generating a data plot selected by the
user.

## 8.2 Process Singles Data

• l_SnglsRtns.pro

This file contains routines related to singles data processing.

> • l_SnglsAdjExData -- determine if an extra spin's worth of data is
> needed when adjusting traces to zero degree spin angle.

• l_SnglsReadData -- read the UDF data

> • l_SnglsGetData -- initializes and defines data types needed to store
> the data

• l_SnglsReadSetup -- read the setup file and plot options

• l_SnglsHndlMissData -- handle data gaps in the data

• l_SnglsPlot -- plot the data

> • l_SnglsDump -- generate an ASCII text dump corresponding to the
> plotted data

• l_SnglsTerm -- terminate pointers allocated for the data

• l_SnglsProc -- main routine, called by l_LenaPlot

## 8.3 Process Binned or Event Data

• l_BinnedEventRtns.pro

This file includes routines to determine which data packet, Binned or
Event, the user has selected to process.

> • l_BinnedEventTerm -- terminate pointers allocated for data storage
>
> • l_BinnedEventSelect -- select Binned or Event data based on the
> user's selection
>
> • l_BinnedEventPlot -- plot the selected data based on the user's
> selection
>
> • l_BinnedEventProc -- routine called by l_LenaPlot to process data

## 8.4 Process Image/Binned Data

• l_BinnedReadData.pro

This file contains routines responsible for reading the Binned science
data.

• l_BinnedReadUdfDataByTime -- read the data on a spin basis

> • l_BinnedReadSVL -- read the steering voltage level from the
> Housekeeping data that corresponds to the spin Binned data

• l_BinnedReadSetup.pro

This file contains routines to read the setup and plot options for the
binned data. Binned specific options are prefixed with l_binned.

• l_BinnedRtns.pro

This file contains routines to read, dump, and plot the Binned data
packets.

> • l_BinnedGetData \-- defines the data structures needed to store the
> data and reads the data from the UDF database
>
> • l_BinnedDumpData \-- writes an ASCII text file of data corresponding
> to the data plotted.
>
> • l_BinnedProcData \-- processes and handles data gaps

• l_BinnedPlot -- generates plots of the data.

> • l_BinnedProc \-- main calling routine, called by either
> l_LenaPlot.pro or l_BinnedEventRtns.pro depending on the user's data
> selection. This routine is responsible for calling the appropriate
> routines to read, process, write, and cleanup the data buffers based
> on the user's options. It is also responsible for setting up the
> plotting displays.

• l_BinnedTerm.pro

This routine is responsible for de-allocating pointers created to store
the binned data.

## 8.5 Process Event Data

• l_EventRtns.pro

This file contains routines related to Event data processing.

> • l_EventReadSetup \-- read the setup and plot parameters.
>
> • CheckFiller -- determine if the event data was filled with a filler
> sequence of 12, 3, 0 for time of flight, energy, and polar,
> respectively.
>
> • CountEventsPerSector \-- counts the number of events occurring in
> each spin sector (a maximum of 64 events can occur per spin sector)
>
> • l_EventReadData -- reads and stores the data
>
> • l_EventGetData \-- defines and initializes data structures for data
> storage
>
> • l_Event_AdjExtraData -- determine if extra spins (a two minute spin)
> are needed at the beginning and at the end of the specified time range
> when centering traces (sun, earth, moon) to zero degree spin angle
>
> • l_Event_CorrBkgrnd \-- performs background correction on the
> hydrogen and oxygen data.

• l_EventPlot \-- plots the data.

> • l_DataGap \-- determines if there are data gaps. The data does not
> use the l_HndlMissData.pro described in Section 7.6 since it handles
> data that is formatted on a spin basis. The event data's format is on
> a spin sector basis.
>
> • SyncEvent2SectEvnts \-- synchronize the event data to the sectored
> events data packets
>
> • SyncEvent2OA \-- synchronize the event data to the orbit and
> attitude data
>
> • SyncEvent2Binned \-- synchronize the event data to the binned data
>
> • l_EventDump_Bef0731 -- create a text dump of the event data before
> the flight software upload of July 31, 2000. This text dump does not
> include the sectored event counts.
>
> • l_EventDump -- create a text dump of the data. This is data after
> the flight software upload of July 31, 2000. This text dump includes
> the sectored events counts.
>
> • l_EventTerm -- frees memory allocated for data storage
>
> • CheckAvailData \-- check if sectored events data packets are
> available and which data packet it is available in. Refer to the table
> in Section 5.6 for more information.
>
> • l_EventDumpBKData -- creates a text dump of the background corrected
> data
>
> • l_EventProc -- the routine called by l_LenaPlot.pro

## 8.6 Process Sectored Event/Sun Pulse Data

• l_EvSpRtns.pro

This file contains the routines responsible for Sectored Event/Sun Pulse
data processing.

> • l_EvSpGetData -- defines and initializes the data types for storage
> of the data
>
> • l_EvSpReadData -- reads the data from the UDF database and stores
> the data into local data structures
>
> • l_EvSpTerm -- free memory allocated for data storage

• l_EvSpProc -- the main routine, called by l_LenaPlot.pro

## 8.7 Process Apogee Data

• l_ApogeeRtns.pro

This file contains routines responsible for generating apogee plots.

> • l_ApogeeFind -- determines apogee
>
> • l_ApogeeProc -- initializes and defines structures and procedures to
> process and to generate the plots around apogee

## 8.8 Process Perigee Data

• l_PerigeeRtns.pro

This file contains routines responsible for generating perigee plots.

> • l_PerigeeFind -- determines perigee.
>
> • l_PerigeeProc -- initializes and defines structures and procedures
> to process and to generate the plots around perigee

## 8.9 Process Region-Of-Interest Data

• l_RoiRtns.pro

This file contains routines responsible for ROI data processing.

> • l_RoiGetData \-- defines and initializes data types for storage of
> data

• l_RoiReadData -- read the data from the UDF database

> • l_RoiReadSetup -- reads and stores the processing and plotting
> parameters for the ROI data

• l_RoiPlot \-- plots the data.

• l_RoiTerm \-- frees memory allocated for data storage.

> • l_RoiProc \-- the main routine, called by l_LenaPlot.pro

## 8.10 Process Browse Data

• l_BrowseRtns.pro

This file contains routines responsible for generating browse products.

> • l_BrowseProc -- read the binned data and sum over all masses,
> energies, and polar zones

• l_BrowsePlot -- plot the coincidence data

• l_BrowsePrintDump -- generate an ASCII text file of the Browse data

• l_ImageRtns.pro

> • calculate_sm_coord -- calculate the solar magnetic coordinates given
> the satellite spin and position
>
> • coord_transf_erad -- find the solar magnetic component of the image
> frame in which z-axis is along the satellite position, y-axis (spin
> angle) equals z-axis times SM satellite spin, and x-axis completes the
> right-hand rule.

• draw_auroral -- draw the aurora

• draw_continents -- draw the continents on the earth

• draw_dipole -- draw the dipole field lines

• draw_earth -- draw the earth

• draw_re_circles -- draw the circles at 3 and 6.6 Re at the equator

> • get_scale_minmax -- get the minimum and maximum values from the
> three images to be plotted

• load_color_table -- load a pre-defined color table

> • plot_3constant -- three panels of images (Hydrogen, Oxygen, and both
> masses) with earth and spacecraft distance held constant
>
> • plot_3full -- three panels (Hydrogen, Oxygen, and both masses) of
> 12x45 images
>
> • plot_3square -- three panels (Hydrogen, Oxygen, and both masses) of
> 12x12 images

• put_on_color_bar -- draw the color bar on the plot

• l_PlotImage.pro

• plot_ENAflux -- creates the earth/image browse products

• l_BrowseRtnsMovie.pro -- generates a movie using a series of browse
images

> • l_BrowseProc -- read the binned data and sum over all masses,
> energy, and polar zones

• l_BrowsePlot -- plot the browse images

> • l_BrowsePrintDump -- create an ASCII text dump of data corresponding
> to the data plotted

• l_PlotImageMovie.pro

• plot_ImageMovie -- creates the earth image/browse products as movies

## 8.11 Process Echo Data

• l_EchoRtns.pro

This file contains routines responsible for processing the Echo data.

• l_GenSysCmdTable \-- generates the system command table

• l_GenROICmdTable -- generates the region of interest command table

• l_GenPerfCmdTable \-- generates the performance command table

• l_GenTOFCmdTable -- generates the time of flight command table

• l_GenPSSCmdTable -- generates the PSS command table

• l_GenMemCmdTable -- generates the memory command table

> • l_GenHvpsCmdTable -- generates the high voltage power supply command
> table

• DetSysCmds -- determines which system command was sent

> • DetROICmds -- determines which region of interest data commands were
> sent

• DetPerfCmds -- determines which performance commands were sent

• DetTOFCmds -- determines which time of flight commands were sent

• DetPSSCmds -- determines which PSS commands were sent

• DetMemCmds -- determines which memory commands were sent

> • DetHvpsCmds -- determines which high voltage power supply commands
> were sent
>
> • l_EchoProcData -- call the procedures to do the echo data processing

• l_EchoDumpAllCmds -- writes all commands to an ASCII text file

• l_EchoTerm -- free allocated memory

## 8.12 Process Housekeeping Data

• l_HskpRtns.pro

This file contains routines responsible for processing the housekeeping
data.

> • l_HskpGetData -- defines and initializes the data types for storage
> of the housekeeping data
>
> • l_HskpReadSetup \-- reads the setup file for specific housekeeping
> processing and plotting parameters
>
> • l_HskpReadData -- reads the data from the UDF database

• l_HskpDumpData \-- dumps the data to a text file.

• l_HskpPlot -- generates a line plot of the data

> • l_HskpTerm \-- frees memory allocated for the data.
>
> • l_HskpProc \-- the main routine called by l_LenaPlot.pro

## 8.13 Process Memory Dump Data

• l_MemdRtns.pro

This file contains routines responsible for processing the memory dump
data.

> • l_MemdGetHskpFlag \-- determine if the ROI summation and Sectored
> Events/Sun Pulse data packets are available in the Memory Dump packet.
> The temperature 7 field in the housekeeping data indicates if the new
> data packets are available. A zero indicates the data are not
> available. A one indicates the data are available.
>
> • l_MemdReadData \-- read the data from the UDF database
>
> • l_MemdParseData -- parses the data in the memory dump packet into
> the ROI summation, sectored events, and HK monitor packets
>
> • l_MemdGetData -- defines and initializes the data types for storage
> of the data.
>
> • l_MemdTerm \-- frees memory allocated for the data
>
> • l_MemdProc \-- the main routine called by l_LenaPlot.pro

## 8.14 Process Power Supply Command Data

• l_PwSupCmdRtns.pro

This file contains routines to generate the power supply bars using the
housekeeping command data.

> • l_PwSupCmdReadData -- read the power supply command data
>
> • l_PwSupCmdTerm \-- frees memory allocated for data storage
>
> • l_PwSupCmdDump \-- generates a text dump of the data
>
> • l_CreateOpBars \-- create the power supply bars for the spectrograms
>
> • l_ChckDEBars \-- fills data gaps
>
> • l_DrawOpBars \-- draw the power supply status bars on the
> spectrograms
>
> • l_PwSupCmdProc \-- the main routine called by l_LenaPlot.pro

## 8.15 Process Power Supply Monitor Data

• l_PwSupMonRtns.pro

This file contains routines to process the housekeeping monitor data.

> • l_PwSupMonReadData -- read the power supply monitor values
>
> • l_PwSupMonTerm \-- frees memory allocated for data storage
>
> • l_PwSupMonDump \-- generates a text dump of the data.
>
> • l_PwSupMonProc \-- the main routine called by l_LenaPlot.pro

## 8.16 Process State Table Data

• l_NewStateTableRtns.pro

This file contains routines to generate an ASCII text dump of the
instrument state. These dumps include state information on a sub-spin
level, if it is available.

> • l_StateTableDocumentation -- generates documentation based on the
> current state for the text dumps
>
> • l_StateTableDumpAll \-- dumps the instruments state on a spin and
> sub-spin level. This routine is called only if the ECHO data and the
> HSKP data are available.
>
> • l_StateTableDumpHskpOnly -- dumps the instrument state on a spin
> level. This routine is called if only the HSKP data is available.

• l_StateTableDump \-- generates a text dump of the instrument state

> • l_StateTableProc \-- the main routine called by l_LenaPlot.pro

## 8.17 Process Instrument State Data

• l_InstData.pro

> Provides instrument state information at the bottom of a spectrogram.
> Those data include the TOF start CFD level, TOF stop CFD level, HVPS
> Optics Steering Command, and HVPS MCP Stop VMON.

## 8.18 Process Long Term Trending Data

• l_LttRtns.pro

This file contains routines responsible for generating the long-term
trending plots.

> • l_LttReadSetup \-- reads specific processing and plotting options
> for long term trending plots
>
> • l_LttGetData -- defines and initializes data types for data storage
>
> • l_LttPlot --generates data as a line plot or Tokar plot

• l_LttProc \-- the main routine called by l_LenaPlot.pro

## 8.19 Process Orbit and Attitude Data

• l_OARtns.pro

This file contains routines responsible for processing the orbit and
attitude data.

• l_OARead \-- read the OA data from the UDF database

• l_OATerm \-- free memory allocated for data storage

> • l_OAPlot -- plots the earth limbs

• l_OAEarthSize -- calculates the size of the earth

## 8.20 Process Miscellaneous Combination Data Plots

• l_ZC1Rtns.pro

This file contains routines to generate a start and stop singles line
plot and multiple housekeeping plots.

> • l_ZC1DumpData \-- generates a text dump of the data corresponding to
> the data plotted.
>
> • l_ZC1Proc \-- main routine called by l_LenaPlot.pro

• l_ZC2Rtns.pro

This file contains the routines to generate a start and stop singles
spectrogram with the option of plotting either the event or binned data
in the coincidence panel.

> • l_ZC2DumpData \-- generates a text dump of the data corresponding to
> the data plotted.
>
> • l_ZC2Proc \-- main routine called by l_LenaPlot.pro

• l_ZC3Rtns.pro

This file contains the routines to generate the image browse products.

• l_MassSpectRtns.pro

This file contains routines responsible for generating a mass spectrum
plot.

> • l_MassSpectParse -- a histogram of each energy, polar, and TOF bin,
> excludes filler data.
>
> • l_MassSpectTerm---free memory allocated for data storage

• l_MassSpectPlot -- plot the data

• l_MassSpectProc -- the main procedure called by l_LenaPlot.pro

## 8.21 Process Magnetic Field Values (Tsyganenko model)

> • T01_01.for -- a file of FORTRAN subroutines used to calculate the
> magnetic field from external magnetospheric sources of the geomagnetic
> field at a specified point in space (XGSM, YGSM, ZGSM).
>
> • T96.for -- Tsyganenko model, written in FORTRAN
>
> • l_T96.pro -- the IDL to FORTRAN sub-routine interface
>
> • t96_c.c -- a C routine used to pass IDL parameters to the FORTRAN
> routines.

# 9.0 Portability Issues

There are two possible portability issues:

1.  The UDF DB. The installed version of the LENA UDF DB is for a UNIX
    specific platform. If a user were to port the LDPS code to a PC or a
    MAC, the corresponding UDF DB for that platform needs to be
    installed.

2.  The CRON jobs. These are the scripts that the UNIX system
    automatically executes to generate the daily products. A different
    script will need to be written for the new platform, unless that
    platform includes a UNIX like operating system.

## 

# Acronyms and Abbreviations

CFD

CDF Common Data Format

COTS Commercial Off the Shelf

DB Database

DLM Dynamic Load Module

EUV Extreme Ultraviolet Imager

FEDS Front End Data System

FUV Far Ultraviolet Imager

GSFC Goddard Space Flight Center

GUI Graphical User Interface

HENA High Energy Neutral Atom

HSKP Housekeeping

HVPS High Voltage Power Supply

IDL Interactive Data Language

IMAGE Imager for Magnetopause-to-Aurora Global Exploration

LDPS LENA Data Processing System

LENA Low Energy Neutral Atom

MCP Micro Channel Plate

MENA Medium Neutral Energy Atom

NSSDC National Space Science Data Center

OA Orbit and Attitude

PERL Practical Extraction and Report Language

PIDF Plot Instrument Data File

ROI Region of Interest

RPI Radio Plasma Imagining

SMOC Science Mission Operations Center

SWRI Southwest Research Institute

TOF Time of Flight

VIDF Virtual Instrument Data File

VMON Voltage Monitor

UDF Universal Data Format

WWW World Wide Web