Contents

• Level 1 Data Organization
• Data Structures by Instrument
• Automatic HDF code generation - hdfgen.pl
• Step-by-Step Level 1 Data User Guide
• Level 1 Data Processing Changelog - Chronicle of changes in ASC Level 1 data processing software.

• A description of ACE data processing levels.

ACE Level 1 data are distributed by the ACE Science Center to each of the ACE instrument teams, and are permanently archived at NASA's National Space Science Data Center (the NSSDC). Since the ACE data are non-proprietary, no authorization for release of the data to the general science community is required.

However, ACE Level 1 data requires significant further processing to make them useful for scientific studies. The experience and expertise required to perform this processing rests with the instrument teams. Therefore, it is strongly recommended that users of Level 1 data from the ACE Science Center, or the permanent NASA archive at the NSSDC, contact the responsible instrument teams regarding correct usage of the data.

The ACE Level 1 data are organized to meet the individual requirements of the nine ACE instrument teams. Several (in some cases many) data structures are defined for each instrument, and several more are defined for the spacecraft engineering data. The data structures were defined by the Science Center in consultation with each instrument team. Therefore, the degree to which the raw data is massaged during Level 1 processing varies from instrument to instrument.

The basic elements of the Level 1 data produced by the Science Center are C data structures, each defined in their own include file. Based on the definition of a data structure, a library of C subroutines is created that make it quite easy to read/write that data structure from/to HDF format data files. All ACE Level 1 data are formatted in HDF (Version 4.1r2).

• CRIS

• EPAM

• MAG

• S3DPU

• SEPICA

• SIS

• SWEPAM Electron

• SWEPAM Ion

• SWICS

• SWIMS

• ULEIS

• Spacecraft Engineering Data

To simplify the process of converting data to HDF format, a perl program (hdfgen.pl) has been written which creates the code necessary to initialize and perform reads and writes of the HDF file, using a C structure as a template. Thus, minimal knowledge of HDF is needed to access the data in an ACE Level 1 file.

hdfgen.pl can be used to convert any data to HDF format, once one has defined a set of C data structures to contain the data. At ASC, hdfgen.pl is used to create Level 2, browse and ancillary HDF data files, as well as Level 1.

• An example showing how to use hdfgen.pl to create useful HDF routines from a C structure definition.
• Documentation of the HDF subroutines generated by hdfgen.pl.

Note: All ACE Level 1 data is in HDF format, so you can access the data using any of the scientific data analysis applications which support the HDF format (IDL, NOESYS, etc.). However, if you wish to take this route, be aware that the Science Center does not provide support for these applications.

The Science Center has put together a software package to enable you to access ACE Level 1, browse and ancillary HDF data files from C programs. The package contains source code and example programs which illustrate how to read most of the Level 1 data structures from a Level 1 HDF file. What follows is a step-by-step guide for obtaining, installing and using this software package.

1. Obtain and install the required tools on your system.

   • C compiler. The Science Center uses gcc, and our makefiles are tailored for use with GNU make, but most C compliers should work fine with our software.
   • HDF libraries. These may be obtained from the NCSA HDF Home Page
   . Unix, VMS, Windows NT/95, DEC Alpha NT and Macintosh platforms are supported.
2. Obtain the latest version of the ACE Level 1 software package, from

   ftp://mussel.srl.caltech.edu/pub/ace/software

   or if this is the CD version it will be in the top directory.

   The package is a zip-compressed archive, which unzips into a directory called "acetest". The acetest directory contains a number of subdirectories, whose contents are described in the accompanying README file. In particular, the "hdfsubs" directory contains all the low-level routines created automatically by our hdfgen.pl perl script (See the previous section, Automatic HDF Code Generation - hdfgen.pl). So, you do not need to have perl or hdfgen.pl installed on your system to use this software package.
3. Compile example programs.
   Let's imagine you are interested in data from the MAG instrument. MAG example programs are in the "magtest" subdirectory. Go there, edit the Makefile to suit your system, and run "make". If all goes well, five programs should be created - mag_avgvec_rd, mag_fft_rd, mag_hskp_rd, mag_snap_rd and mag_vec_rd. Each of these programs reads MAG data from a Level 1 HDF data file. mag_vec_rd reads data contained in the MagVectorSet data structure, defined in the include file mag_vector.h. The other programs read data from the other MAG Level 1 data structures.

   The procedure is the same for other instruments. EPAM example programs are in the "epamtest" subdirectory, etc., etc.

4. Test example programs. Run the test programs with a Level 1 HDF file as input. Each of the test programs prints a subset of the data. Check that this works and that the data make sense.
5. Use the example programs as templates to help you write routines to access Level 1 data from your own analysis programs. Each of the example programs makes calls to lower-level routines ASC has provided (in the hdfsubs directory). You will want to make similar calls to these routines from your own software.
   Documentation of the lower-level routines called by the example programs
6. If necessary, fold ACE ancillary data into your data analysis. ACE ancillary data include Attitude and Orbit data, and Clock Calibration data. These data allow one to

   • determine the ACE spacecraft attitude, position and velocity at any given time
   • convert vector data in spacecraft coordinates to other coordinate systems (ISTP provides a FORTRAN library to help with this).
   • accurately calculate ACEepoch from the spacecraft onboard clock. ACEepoch is seconds since 00:00:00Z on Jan 1, 1996.

   ACE ancillary data is provided in a HDF format data file which is updated daily by the Science Center. This file may be downloaded from

   ftp://mussel.srl.caltech.edu/pub/ace/ancil

   Examples illustrating how to access the ancillary data from C programs are in the "anciltest" subdirectory of the ACE Level 1 software package.

If you have any questions which are not answered here, please contact an ASC staff member.