4. Suzaku Function Libraries

There will be software modules that are used repeatedly in various stages of the Suzaku mission, from the satellite operation to the scientific data analysis. In order to avoid overhead and inconsistency, functions supposed to be used by two or more tools will be included in the Suzaku function libraries.

There will be at least three such function libraries for Suzaku; aste_tool, which includes functions for Suzaku specific tasks, atFunctions, which includes functions for generic attitude and orbital related tasks^4.1, and xrrt, which is for XRT ray-tracing. They are implemented in the FTOOLS package as libastetool.a, libatFunctions.a, libxrrt.a, respectively^4.2.

4.1 Suzaku Specific Tasks (aste_tool)

4.1.1 Time Conversion

Routines to carry out conversion between Suzaku time and other time systems will be necessary. Suzaku time will be defined as the elapsed time from the beginning of year 2000 in UTC. The leap second table is referenced to take into account the leap seconds.

4.1.2 Coordinate Conversion

Since the XIS is an imaging instrument, coordinate systems for XIS images are must be defined. Functions to carry out conversion between these coordinates will be necessary (e.g., when making observation plans and calibrating FITS event files), and will be included in aste_tool.

4.1.3 Energy Calibration

Suzaku instruments measure X-ray photon energy as pulse heights; the raw measurements are referred to as the Pulse Height Analyzer (PHA) channels. Although PHA values are roughly proportional to the input energies, they vary with several conditions such as time, location on the detector, temperature, etc. After correcting these effects, we may define Pulse Invariant (PI), which should be perfectly proportional to the energy.

We will need to calculate PI from PHA for all the three instruments to fill the PI columns in the event FITS files (section 6.4). The routines to calculate PI from PHA shall be included in aste_tool. These routines need to access calibration files to get calibration information (chapter 7).

4.1.4 HK Information Acquisition

All satellite and instrument housekeeping (HK) parameters are stored in the HK FITS files (sections 2.4.2 and 6.3), which can become huge. However, only a small fraction of the HK parameters will be actually required for scientific data processing. In order to facilitate the use of HK files, HK file access routines shall be provided in aste_tool. Note that HK access routines need to be built with efficiency in mind.

HK parameters in the telemetry are digitized at discrete intervals, thus aste_tool routines may have to convert them to physical values, and interpolate or smooth them as needed. For example, we may require an aste_tool routine which gives instrument temperatures in degrees continuously by interpolating discretely measured temperatures in digitized units.

Parameters for conversion from the digitized HK telemetry to the physical units are stored in the multimission database named Satellite Information Base (SIB) located at ISAS. Although SIB itself is not portable, Suzaku related information in SIB will be necessary to interpret HK parameters in the telemetry. Therefore, essential parts of the SIB will be extracted and put in the calibration files (section 7.4.1).

4.1.5 Other Tasks

Functions for other tasks will be included in aste_tool as needed. For example, a random number generation function will be required so that the same sequence of random numbers are always obtained from the same seed.

4.2 Attitude and Orbit Related Tasks (atFunctions)

The attitude and orbit related functions in atFunctions will be used in various purposes such as; command planning, assignment of SKY coordinates to events (section 6.4), creation the Filter files (section 6.4.1), calculation of the exposure maps, and barycentric corrections (section 6.5.3). They may require the attitude files, the orbit files, or both (section 6.2). The following are examples of the tasks in atFunctions.

4.2.1 Attitude Information

• Obtain q-parameters and/or Euler angles for a given time.

• Determine the pointing direction of each telescope/sensor for a given time.

4.2.2 Orbit Information

• Obtain satellite orbital position for a given time.

• Obtain magnetic cut-off rigidity for a given time.

• Determine if the satellite is in day (sun-lit) or dark (not sun-lit) for a give time. Also obtain the elapsed time after the last day-to-dark or dark-to-day transition.

• Determine if the satellite is in the South Atlantic Anomaly (SAA) or not for a given time. Also obtain the elapsed time after the last SAA passage.

• Obtain sidereal direction of the magnetic field line for a given time.

4.2.3 Attitude and Orbit Information

• Output the angles from the earth rim and sun-lit part of the earth for a given time.

• Determine if the pointing direction is blocked by earth or not. If it is, determine if the earth is sun-lit or not.

4.3 Ray-Tracing Function Library (xrrt)

The Suzaku ray-tracing package named xrrt has been written in C++, and is available as a function library. This library provides function to load mirror, obstruction, and reflection tables from FITS files, and then to trace photons through the mirror sets and collect statistics about the results. See section 5.2.3 for detail.