XMM-Newton Science Analysis System


cal (cal-3.184) [xmmsas_20070308_1802-6.6.0]

Meta Index / Home Page / Developer's notes / Using CAL in a / Using CAL from Fortran-90 / Fortran90 Interface

CAL control/infrastructure functions

• CAL_ccfInfo -- query details about CCF constituent
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_ccfInfo(calType, calFileInfo)
      use CalTypes
      character(len=*), intent(in)    :: calType
      type(CalInfo), intent(out)      :: calFileInfo
  end subroutine

  DESCRIPTION

  
  A query function to obtain information about a constituent of the CCF previously opened with CAL_openCCF. The routine receives a string argument which must be a valid calibration data type name (see Table 2 in Interface Control Document for the Current Calibration File) which, together with the current instrument uniquely specifies a CCF constituent. Calibration file instances registered with CAL_setCalibrationFile override corresponding entries in the CCF initially opened.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  calType

  
  name of type of calibration file for which information is requested (must be a name from Table 2 in Interface Control Document for the Current Calibration File)

  
  

  Out:

  
  

  calFileInfo

  
  structure with fields describing the selected CCF constituent; see caltypes.f90 for the definition of this type.

  USED STATE VARIABLES

  
  instrument

  CCF ACCESS

  
  none

  
  
  

• CAL_getState -- retrieve CAL state variables
  

  
  

  SYNOPSIS

  
  
  

  identical to CAL_setState except that all input
  arguments become (optional) output arguments

  DESCRIPTION

  
  This function is the counterpart to CAL_setState for querying the state of the CAL.

  ARGUMENTS

  
  
  

  identical to CAL_setState except that all input arguments become (optional) output arguments.

  
  
  

• CAL_integerToReal -- convert an integer into a real array
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_integerToReal(intVector, realVector)
      use types
      integer(kind=int16), dimension(:), intent(in) :: intVector
      real(kind=single), dimension(:), pointer      :: realVector
  end subroutine

  DESCRIPTION

  
  Routine to convert an array with integer values into a corresponding real array. A randomization by $\pm0.5$ is taken into account if the state variable randomize is set to true. CAL_integerToReal can be used to convert integer-valued PHA column data from ODF sets into real numbers before these can be passed to the energy correction routines CAL_offsetCorrect or CAL_gainCorrect. For an example on the usage of CAL_integerToReal please consult the CAL example tasks mentioned above. Please note: The ``amount'' of randomization can be controlled via CAL_setRandom.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  intVector

  
  Input array with values to be converted to real

  
  

  Out:

  
  

  realVector

  
  Pointer to real-values output array - can be an uninitialized pointer in which case the CAL allocates the required memory as outlined in above.

  USED STATE VARIABLES

  
  randomize

  CCF ACCESS

  
  none

  
  
  

• CAL_openCCF -- open a Calibration Index File (CIF)
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_openCCF(cifName)
      character(len=*), intent(in)    :: cifName
  end subroutine

  DESCRIPTION

  
  Open a CCF represented by a Calibration Index File (CIF) on the local file system. Please note: The use of CAL_openCCF in normal SAS tasks is deprecated. The CCF to be used by the CAL will be transparently opened upon initialization. The name of the directory containing the CCF should be specified by either of the methods described above.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  cifName

  
  full name (absolute path + name) of CIF representing the CCF to be used; if cifName is empty ('') the environment variable SAS_CCF is inspected for the location of a CIF to be opened; if this fails either because the variable is not defined or the file it points to does not exist, execution is aborted.

  
  
  

• CAL_realToInteger -- convert a real into an integer array
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_realToInteger(realVector, integerVector)
      use types
      real(kind=single), dimension(:), intent(in)   :: realVector
      integer(kind=int16), dimension(:), pointer    :: integerVector
  end subroutine

  DESCRIPTION

  
  Counterpart of routine CAL_integerToReal to convert a real-valued array into an integer array. The conversion is done by rounding to the nearest integer value.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  realVector

  
  Input array with values to be converted to integer

  
  

  Out:

  
  

  integerVector

  
  Pointer to integer-values output array - can be an uninitialized pointer in which case the CAL allocated the required memory as outlined in above.

  
  
  

• CAL_setCalibrationFile -- define calibration file to be used
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_setCalibrationFile(calibrationFileName)
      character(len=*), intent(in)    :: calibrationFileName
  end subroutine

  DESCRIPTION

  
  This function registers an external FITS calibration file as a substitute for the corresponding one stored in the CCF in use (see CAL_openCCF). Subsequent CAL routines who need to access calibration information from a file of that type will not access the CCF but read from the previously specified file directly. The named file must be a valid CCF constituent as specified in Interface Control Document for the Current Calibration File. Please note: The use of CAL_setCalibration in normal SAS tasks is deprecated. A list of CCF constituents which should replace corresponding ones in the specified CCF can be passed to any task which utilizes the CAL via a command line option -ccffiles. Please consult the documentation of package taskmain for details.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  calibrationFileName

  
  full name (absolute path + name) of CCF constituent file

  
  
  

• CAL_setRandom -- control Random Number Generator used by CAL
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_setRandom(min, max)
      use types
      real(kind=double), intent(in)                 :: min, max
  end subroutine

  DESCRIPTION

  
  Define the lower and upper limit for random numbers generated within the CAL.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  min, max

  
  Lower and upper bound for random numbers generated within the CAL.

  
  
  

• CAL_setState -- define/modify the state of the CAL
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_setState1(instrument, ccdChipId, ccdNodeId, &
                           ccdModeId, filterId, &
                           accuracyLevel, &
                           temperature, temperatureCamera, &
                           exposureStartTime, exposureDuration, &
                           ocb, randomize, temperatureTracking, &
  auxiliaryParameter)
      use types
      integer(kind=int32), optional, intent(in)   :: &
              instrument, &           ! current instrument
              ccdChipId, &            ! CCD identifier (>=1)
              ccdNodeId, &            ! the readout node (>=0)
              ccdModeId, &            ! current mode
              filterId, &             ! a filter Id (>=0)
              ocb, &                  ! on-chip binning factor
              accuracyLevel, &        ! what it says
      real(kind=double), optional, intent(in)     :: &
              temperature, &          ! [K] CCD temperature
              temperatureCamera, &    ! [K] temp. of camera structure
              exposureStartTime, &    ! [d] exposure start time as MJD
              exposureDuration, &     ! in [s]
  auxiliaryParameter      ! auxiliaryParameter
      logical, optional, intent(in)               :: &
              randomize,              ! randomize input quantities
              temperatureTracking     ! perform T tracking?
  end subroutine

  DESCRIPTION

  
  The user-changeable part of the state of the CAL is defined/modified through this routine. All arguments are optional, i.e., state variables corresponding to omitted arguments retain their values assigned in previous invocations.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  instrument

  
  identifier ($>$=0) specifying an instrument

  ccdChipId

  
  numeric identifier ($>$=1) of a CCD chip, e.g. the central EMOS CCD is #1 (symbolic name: EMOS_CENTRAL)

  ccdNodeId

  
  numeric identifier ($>$=0) specifying a readout node on the currently defined CCD, e.g., node 0 is the prime readout node for all EMOS CCDs - the node Id is ignored in the case of EPIC PN where an event's x-coordinate signifies the readout node.

  ccdModeId

  
  numeric identifier ($>$=0) specifying an instrument data mode, e.g, 0 is PRIME_FULL_WINDOW mode (see file caloaldefs.f90 for a complete list of symbolic ccdModeId names)

  filterId

  
  numeric identifier ($>$=0) specifying a filter in front of the current instrument

  accuracyLevel

  
  an integer value in the range $[0,3]$ selecting one of three available accuracy levels for to be computed calibration entities; not relevant for all routines; symbolic names are: ACCURACY_LOW, ACCURACY_MEDIUM, ACCURACY_EXTENDED , ACCURACY_HIGH

  temperature

  
  the temperature of the currently defined CCD in Kelvin - if temperatureTracking is set to false the passed value will be used in all temperature-dependent calibration algorithms as the temperature of the CCD chip. If temperatureTracking is in effect, the temperature can be inquired via CAL_getState after a temperature-dependent quantity has been accessed.

  temperatureCamera

  
  the temperature of the camera frame (in Kelvin) holding the currently defined CCD - if temperatureTracking is set to false the passed value will be used in all temperature-dependent calibration algorithms as the temperature of the CCD chip. If temperatureTracking is in effect, the temperature can be inquired via CAL_getState after a temperature-dependent quantity has been accessed.

  exposureStartTime

  
  this defines the current exposure start time in number of seconds since the fixed mission reference date 1998-01-01T00:00:00 TT - must be given as Modified Julian Days.

  exposureDuration

  
  duration of the exposure in seconds

  ocb

  
  On-Chip-Binning factor in the range 1-5 for RGS and not applicable (i.e. 1) for all other instruments.

  randomize

  
  some data transformations in the spatial and spectral domain require the CAL to manipulate intrinsically integral quantities (such as pixel numbers) with other real numbers and converting the result back to integer. This cycle can lead to unphysical artifacts in the output data (saw-tooth curves) which can be avoided by a small randomization of the input quantities (e.g., $\pm0.5$ in the case of pixel numbers). In the absence of a sound mathematical basis for this approach this switch is foreseen as an experimental parameter which gives the greatest possible flexibility.

  temperatureTracking

  
  Setting this variable to true signals the CAL to do an automatic temperature tracking. The caller is then not required to set the state variables temperature/temperatureCamera explicitly but let the CAL do that (by accessing corresponding information in the HK files). Please note: The automatic temperature tracking is not yet implemented

  auxiliaryParameter

  
  General purpose parameter for exchanging auxiliary values between the cal and clients; e.g., the PN CTI correction in timing mode needs the position of the source on the CCDs which must be provided through auxiliaryParameter

  
  
  

• CAL_setState -- define the state of the CAL from
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_setState(dataSetName)
      character(len=*), intent(in)    :: dataSetName
  end subroutine
  
  

  
  subroutine CAL_setState(inSet)
      use dal
      type(DataSetT), intent(in)                      :: inSet
  end subroutine
  
  

  
  subroutine CAL_setState(inBlock)
      use dal
      type(BlockT), intent(in)                        :: inBlock
  end subroutine

  DESCRIPTION

  
  Routines to initialize the state of the CAL from the contents of a block in an ODF data set. All internal and user-changeable state variables will be defined by this except for accuracyLevel (ACCURACY_LOW), temperature ($120.0$), temperatureCamera ($120.0$), randomize (.false.), and temperatureTracking (.false.). These need to be set through an explicit call to CAL_setState otherwise they will get the above indicated default values.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  dataSetName, inSet, nBlock

  
  full name (absolute path + name)/or pointer to an ODF data set which shall be opened to initialize the CAL state variables from the values of corresponding attributes. If the first two forms are used, both the attributes applicable to the entire data set and those of the first block are being inspected. In the third form merely a pointer to a block is given and the required attributes are just looked for in that block. Note: The name of a valid ODF science data set can be retrieved via the routine OAL_selectFile in the ODF Access Layer.

  
  
  

• CAL_releaseMemory -- free-up allocated memory
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_releaseMemoryInt3OneDim(a1, a2, a3)
      use types
      integer(kind=int32), dimension(:), pointer     :: a1
      integer(kind=int32), dimension(:), pointer, optional &
                                                     :: a2, a3
  end subroutine
  
  

  
  subroutine CAL_releaseMemoryInt3TwoDim(a1, a2, a3)
      use types
      integer(kind=int32), dimension(:, :), pointer  :: a1
      integer(kind=int32), dimension(:, :), pointer, optional &
                                                     :: a2, a3
  end subroutine
  
  

  
  subroutine CAL_releaseMemoryLogicalOneDim(a1, a2, a3)
      use types
      logical, dimension(:), pointer                 :: a1
      logical, dimension(:), pointer, optional       :: a2, a3
  end subroutine
  
  

  
  subroutine CAL_releaseMemoryReal2OneDim(a1, a2, a3)
     use types
      real(kind=double), dimension(:), pointer       :: a1
      real(kind=double), dimension(:), pointer, optional &
                                                     :: a2, a3
  end subroutine

  DESCRIPTION

  
  Several CAL routines return entire arrays as output, memory for which has been allocated dynamically at run-time. Memory which is no longer needed shall be freed-up again with this generic subroutine which can be called with up to three pointer two one- or two-dimensional arrays of types real, integer, or logical.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  a1, a2, a3

  
  optional pointers to one or two dimensional arrays of type integer, logical, or real previously returned by other CAL routines.