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

Calibration of data -- RGS-specific

• CAL_rgsCtiCorrect -- CTI correction of energy data (RGS)
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_rgsCtiCorrect(time, rawX, rawY, nodes, eIn, eOut)
      use types
      real(kind=double), dimension(:), intent(in)     :: time        
      integer(kind=int16), dimension(:), intent(in)   :: rawX, rawY
      integer(kind=int8), dimension(:), intent(in)    :: nodes
      integer(kind=int8), dimension(:), intent(in)    :: shape
      integer(kind=int16), dimension(:), intent(in)   :: separation
      real(kind=single), dimension(:), intent(in)     :: eIn
      real(kind=single), dimension(:), pointer        :: eOut
  end subroutine

  DESCRIPTION

  
  This routine corrects for a list of RGS events the energy values for the effect of CTI. The effect is position dependent, i.e., the routine receives spatial event coordinates in addition to the uncorrected energies. The routines operates on real-valued arrays, i.e., integer-valued PHA channels from ODF data sets must be converted to corresponding real arrays with routine CAL_integerToReal before it can be passed to CAL_rgsCtiCorrect.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  time

  
  array with event time coordinates in the TIMCOORD time frame. This input is required to account for time dependent CTI drifts which the CAL shall monitor - currently not in effect.

  rawX, rawY

  
  arrays with CCD pixel coordinates in the PIXCOORD1 reference frame

  nodes

  
  array with readout nodes values

  shape

  
  array with shape codes of events as determined during split event reconstruction; the shape of the events are relative to the readout node see Calibration Access and Data Handbook details

  separation

  
  array with separation values, i.e., the distances each event has to its preceding event in number of parallel transfers; see Calibration Access and Data Handbook for details

  eIn

  
  array with uncorrected energies, i.e., read-out charge values

  
  

  Out:

  
  

  eOut

  
  arrays with computed CTI-corrected PHA values

  USED STATE VARIABLES

  
  instrument, ccdChipId, temperature

  CCF ACCESS

  
  CTI

  
  
  

• CAL_rgsGetCrossPSF -- the PSF in cross-dispersion direction
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_rgsGetCrossPSF(time, beta, sourceXdisp, distribution, &
                                channels)
      use types
      real(kind=double), intent(in)                 :: time
      real(kind=double), intent(in)                 :: beta, sourceXdisp
      real(kind=double), dimension(:), pointer      :: distribution
      integer(kind=int16), intent(out), optional    :: channels
  end subroutine CAL_rgsGetCrossPSF

  DESCRIPTION

  
  Routine to construct the PSF distribution in the cross dispersion direction.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  time

  
  time at which the cross-PSF is requested in the TIMCOORD frame; Please note: This argument is currently ignored.

  beta

  
  $\beta$ angle at which the cross-PSF is to be constructed (in radians)

  sourceXdisp

  
  position of the celestial target in the cross dispersion direction in units of radians (0 corresponds to the centerline of the image area of the RFC)

  
  

  Out:

  
  

  distribution

  
  one-dimensional array with the cross PSF distribution in channels; normalized to 1

  channels

  
  optionally returned array with PSF channel numbers corresponding to returned distribution array.

  USED STATE VARIABLES

  
  instrument, ocb

  CCF ACCESS

  
  CrossPSF

  
  
  

• CAL_rgsGetEventThresholds -- retrieve event thresholds
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_rgsGetEventThresholds(grade, &
                                       rejectionThresholds, &
                                       acceptanceThresholds, &
                                       node)
      use types
      integer(kind=int32), intent(in)           :: grade
      real(kind=single), dimension(:), pointer  :: rejectionThresholds, &
                                                   acceptanceThresholds
      integer(kind=int8), intent(in), optional  :: node
  end subroutine

  DESCRIPTION

  
  Routine to retrieve PI event thresholds corresponding to the four possible event grades 1-4.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  node

  
  optional node identifier; if omitted it defaults to the current value of the state variable nodeId.

  
  

  Out:

  
  

  rejectionThresholds, acceptanceThresholds

  
  two one-dimensional arrays of size 4 corresponding to the rejection and acceptance thresholds of events with grades 1-4;

  USED STATE VARIABLES

  
  instrument, ccdId, nodeId

  CCF ACCESS

  
  ADUconv

  
  
  

• CAL_rgsGetLSF -- the RGS Line-Spread-Function
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_rgsGetLSF(lambda, theta, phi, diffOrder, &
                           lambdaMin, lambdaMax, lambdaGrid, lsfProf)
      use types
      real(kind=double), intent(in)             :: lambda, theta, phi, &
                                                   lambdaMin, lambdaMax
      integer(kind=int32), intent(in)           :: diffOrder
      real(kind=double), dimension(:), pointer  :: lambdaGrid, lsfProf
  end subroutine

  DESCRIPTION

  
  Routine to obtain the RGS line-spread-function in wavelength space.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  lambda

  
  Nominal wavelength in nm for which LSF is inquired.

  theta, phi

  
  specification of a position in the focal plane of the EMOS camera system (TELCOORD reference system) associated with the currently defined RGS camera.

  diffOrder

  
  diffraction order

  lambdaMin, lambdaMax

  
  specification of wavelength range for which the LSF is to be constructed

  
  

  Out:

  
  

  lambdaGrid

  
  one-dimensional array containing wavelengths in the range lambdaMin$\ldots$lambdaMax; sample points at which the LSF has been constructed

  lsfProf

  
  one-dimensional array with values of the sought LSF sampled at the wavelengths in lambdaGrid

  USED STATE VARIABLES

  
  instrument

  CCF ACCESS

  
  LSF

  
  
  

• CAL_rgsGetEffectiveArea -- effective area curve
  

  
  

  SYNOPSIS

  
  
  

  function CAL_rgsGetEffectiveArea(E, order, theta, phi) result(area)
      use types
      real(kind=double), intent(in)                   :: E, &
                                                         theta, phi
      integer(kind=int32), intent(in)                 :: order
      real(kind=double)                               :: area
  end function
  
  

  
  function CAL_rgsGetEffectiveArea(Efrom, Eto, order, theta, phi) result(area)
      use types
      real(kind=double), intent(in)                   :: Efrom, Eto, &
                                                         theta, phi
      integer(kind=int32), intent(in)                 :: order
      real(kind=double)                               :: area
  end function

  DESCRIPTION

  
  Function to compute mirror part of the effective area value at a requested energy and field of view position and for a given spectral order. The second form returns the effective area curve integrated over a given energy interval weighted by $1/(Ehi-Elo)$.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  E, Efrom, Eto

  
  energy in eV at which transmission is requested or energy range over which transmission curve is to be integrated.

  theta, phi

  
  position in the focal plane in the TELCOORD reference system at which transmission is requested

  order

  
  spectral order in the range $[-5, 0]$.

  RETURNS

  
  Effective area value/integrated value in square cm for requested energy/position and spectral order.

  USED STATE VARIABLES

  
  instrument

  CCF ACCESS

  
  XareaEf, QuantumEf

  
  
  

• CAL_rgsGetRedistribution -- return CCD redistribution for an input energy
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_rgsGetRedistribution(E, rawX, rawY, rejectionThreshold,&
                                      redistribution, channel)
      use types
      real(kind=double), intent(in)             :: E, rejectionThreshold
      real(kind=int16), intent(in)              :: rawX, rawY
      real(kind=double), dimension(:), pointer  :: redistribution
      real(kind=int16), intent(out), optional   :: channels
  end subroutine

  DESCRIPTION

  
  Routine to obtain the ideal, unperturbed (no pile-up effects), CCD response to an X-ray event of a given energy.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  E

  
  input energy in eV for which the redistribution is requested

  rawX/rawY

  
  coordinates in PIXCOORD1 frame (currently ignored)

  rejectionThreshold

  
  value of the rejection threshold (currently ignored)

  
  

  Out:

  
  

  redistribution

  
  one-dimensional array with extent equal to the number of available channels of RGS; the entire array represents a probability distribution: redistribution(i) is the probability that an X-ray event with energy E is detected in PI channel i; Pile-up and other effects which influence the detector response are not taken into account. The normalization of array response is 1.

  channel

  
  optionally returned array with PI channel numbers corresponding to returned redistribution array.

  USED STATE VARIABLES

  
  instrument

  CCF ACCESS

  
  Redist

  
  
  

• CAL_rgsGetRefinedWaveScale -- refine RGS wavelength scale
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_rgsGetRefinedWaveScale(time, diffOrder, waveLength)
      use types
      real(kind=double), intent(in)                 :: time
      integer(kind=int16), dimension(:), intent(in) :: order
      real(kind=double), dimension(:), intent(inout):: waveLength
  end subroutine

  DESCRIPTION

  
  Routine to refine the RGS wavelength scale.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  time

  
  Time specification in the TIMCOORD reference frame.

  diffOrder

  
  integral diffraction order ($<=0$)

  
  

  InOut:

  
  

  waveLength

  
  one-dimensional array containing wavelength value to be refined - updated on exit.

  USED STATE VARIABLES

  
  instrument

  
  
  

• CAL_rgsOffsetCorrect -- offset correction for RGS
  

  
  

  SYNOPSIS

  
  
  

  subroutine CAL_rgsOffsetCorrect(time, rawX, rawY, shape, nodes, &
                                  eIn, eOut)
      use types
      real(kind=double), dimension(:), intent(in)    :: time
      integer(kind=int16), dimension(:), intent(in)  :: rawX, rawY
      integer(kind=int8), dimension(:), intent(in)   :: grade, nodes
      integer(kind=int16), dimension(:), intent(in)     :: eIn
      real(kind=single), dimension(:), pointer       :: eOut
  end subroutine

  DESCRIPTION

  
  Routine to offset-correct an array of energy channels. It operates on real-valued arrays, i.e., integer-valued PHA channels from ODF data sets must be converted to corresponding real arrays with routine CAL_integerToReal before it can be passed to CAL_rgsOffsetCorrect.

  ARGUMENTS

  
  
  

  
  

  In:

  
  

  time

  
  array with event time coordinates in the TIMCOORD time frame. This input is required to account for time dependent offset drifts which the CAL shall monitor - currently not in effect.

  rawX, rawY

  
  arrays with PIXCOORD1 coordinates of events

  shape

  
  array with SHAPE values (number of pixels in a reconstructed event)

  nodes

  
  array with node identifiers in the range $[0, 1]$

  eIn

  
  input array with energy channels to correct for offset; will be randomized according to setting of state variable randomize

  
  

  Out:

  
  

  eOut

  
  array with offset corrected energy channels; size is equal to input arrays; can be an uninitialized pointer in which case the CAL allocates the required memory as outlined in above.

  USED STATE VARIABLES

  
  instrument, ccdChipId

  CCF ACCESS

  
  ADUConv