NAME:   hxrs_drm2fits


 PURPOSE:  write a HXRS drm to a FITS file


 CATEGORY: SPEX, spectral analysis


 CALLING SEQUENCE:
	examples

	hxrs_drm2fits, edges_in, drm

	hxrs_drm2fits, edges_in, drm, edges_out=edges_out, file=outfile, origin='NASA/GSFC LASP'


 INPUTS:
	edges_in - input energy bins
	drm - response matrix to be written to file.  Dimensioned number of detector channels by
		number of input energies.
	edges_out - edge energies of detector channels.  If not set, then edges_hxrs is called.
	file - optional name of FITS file to create.
	origin - optional name of institution making the rmf.  If not set, defaults to CU - Boulder.

 OUTPUTS:
	Detector Response Matrix is written to FITS file.

 SIDE EFFECTS:
	none

 RESTRICTIONS:
	drm elements are assumed to have dimesnions of counts/cm^2/kev per photon/cm^2.  The drm
   elements will be mulitplied by detector channel energy width before being written to the FITS file.

 PROCEDURE:
	none

 CALLS: ***
	FXADDPAR [1], FXADDPAR [2], FXBADDCOL [1], FXBADDCOL [2], FXBCREATE [1]
	FXBCREATE [2], FXBFINISH [1], FXBFINISH [2], FXBHMAKE [1], FXBHMAKE [2]
	FXBWRITE [1], FXBWRITE [2], FXHMAKE [1], FXHMAKE [2], FXWRITE [1], FXWRITE [2]
	anytim [1], anytim [2], anytim [3], anytim [4], anytim [5], edges_hxrs [1]
	edges_hxrs [2], edges_hxrs [3]
 MODIFICATION HISTORY:

 NAME:   hxrs_fits2drm


 PURPOSE:  read a HXRS drm from a FITS file into a Spex-compatible form


 CATEGORY: SPEX, spectral analysis


 CALLING SEQUENCE:
	examples

	hxrs_fits2drm, file=file, sfile=scatter_file, edges_out=edges_out, $
		edges_in=edges_in, area=area, drm=drm


 INPUTS:
	file - name of FITS file to read
	sfile - dummy input for spex compatibility


 OUTPUTS:
	edges_out - energy edges of detector channels
	edges_in - input energy bins
	area - HXRS instrument area, cm^2.
	drm - response matrix.  Dimensioned number of detector channels by
		number of input energies.


 SIDE EFFECTS:
	none


 RESTRICTIONS:
	drm elements are assumed to have dimensions of counts/cm^2 per photon/cm^2.  The drm
   elements will be divided by detector channel energy width (counts/cm^2/keV per photon/cm^2)
	before being output.


 PROCEDURE:
	none


 CALLS: ***
	MRDFITS [1], MRDFITS [2]
 MODIFICATION HISTORY:

 NAME:
	hxrs_response

 PURPOSE:
       hxrs response function, count rate per channel as a function of
		incident photon spectrum.

 CATEGORY:
       HXRS, Spectral analysis, fitting

 CALLING SEQUENCE:

 	hxrs_response, edges_out=edges_out, edges_in=edges_in, area=area, drm=drm, $
	flux=flux, em_flux=em_flux, gain=gain, newflux=newflux, con_factors=con_factors, $
	un_con=un_con, error=error

 CALLED BY:
 	drm_4_spex

 CALLS TO:
	none

 Inputs:
   FLUX
       - photons/cm2/s/keV defined at EM_FLUX,
		  optional- only needed to obtain conversion factors
	EM_FLUX
		- energy in keV for FLUX
		  optional- default is the energies of the loss matrix

	GAIN
		- HXRS gain state

 Inputs/Outputs:
	EDGES_OUT(2,8)
		- Energy edges of HXRS 8 channels in keV
   EDGES_IN(2,500)
		- Energy edges for HXRS input in keV
   AREA
       - HXRS area, 4.91 cm^2
	DFILE
		- Name of response matrix fits file to read (optional)
	NEWFLUX(I)
		- Photon flux defined midpoints of EDGES_IN,
		- Interpolated to FLUX and EM_FLUX on midpoints of EDGES_IN
		- if not input

 Outputs:
	DRM(I,J)
		- Probability of an input flux in units of photon/cm^2/s in
		- bin J resulting in a rate of counts/cm2/keV/s in bin I
	CON_FACTORS(I)
		- Conversion factors.  Ratio of the (Integrated flux/bin width)
		to NEWFLUX(I)
	UN_CON(I)
		- Uncertainties on the conversion factors.  An expression
		of the uncertainty in the detector response
	ERROR	- set if a parameter is entered out of range

 CALLS: ***
	CHECKVAR [1], INTERPOL, RESP_CALC, X_EOUT_DRM [1], X_EOUT_DRM [2], checkvar [2]
	edge_products, edges_hxrs [1], edges_hxrs [2], edges_hxrs [3]
 COMMON BLOCKS:
	None.

 SIDE EFFECTS:
	none

 RESTRICTIONS:
	none

 PROCEDURE:

  CALCULATE THE HXRS RESPONSE MATRIX AND/OR COUNT RATE.

  Intended use:

  This procedure calculates the pulse-height response.  The matrix is computed
  from an energy-loss matrix obtained by running the program RESP_CALC, for a
  set of 100 narrow line input functions.  The energy loss matrix is broadened
  for the resolution of the detector to yield the pulse-height response matrix.
  The pulse-height response matrix may be  thought as the detector pulse-height
  spectrum in each of the 8 energy channels for an incident spectrum of a mono-
  energetic beam at one of the 100 incident energies.

  This procedure may be used in several ways:

  To obtain a pulse-height response matrix:

  HXRBS_RESPONSE, EDGES_OUT=EDGES_OUT, EDGES_IN=EDGES_IN, DRM=DRM

  This gives the pulse-height response matrix, DRM, the edges of its energy
  input photon bins, EDGES_IN, the edges of the 8 HXRS channels, EDGES_OUT.  Using OMATRIX and
  an incident flux integrated over the E_MATRIX bins, one can compute the count
  rate in the 8 HXRS channels, i.e.

  COUNTS (counts/keV/cm2/sec) = DRM#(FLUX (Ph/cm2/s/keV) * (EDGES_IN(1:*)-EDGES_IN))

  This calculation of the count rate is extremely quick after DRM is
  obtained.

  CONVERSION FACTOR calculation

  CONVERSION FACTORS allow a simple transformation from the photon flux at a
  given energy to the count rate in a given energy channel for a specified
  model spectrum.  In general, they are defined as the ratio
  of the count rate spectrum in counts/s/keV/cm^2 to the photon spectrum in
  photons/s/keV/cm^2 provided an incident spectrum is given.  Specifically,
  the CONVERSION FACTORS used in the DECONVOLVE section of DCPFIT are the ratio
  of two quantities for a given channel I:

  		Count rate(counts/sec) in channel I
  		-----------------------------------
  		Model Photon Flux at EMID(I) * Area * Width(I)

  where EMID(I) is the mid-point energy in channel I, Area is the HXRS area
  of 4.91 cm^2, and Width(I) is the channel width in keV.

  This procedure will also return the CONVERSION FACTORS as follows:

  On the first pass:

  HXRS_RESPONSE, EDGES_OUT=EDGES_OUT, EDGES_IN=EDGES_IN, GAIN=GAIN

  Then, compute the photon flux, FLUX, on the midpoints of EDGES_IN and
  the photon flux, NEWFLUX, on the midpoints of EDGES_OUT outside of this procedure.
  The units of the photon flux must be photons/s/keV/cm^2.

  you can get the conversion factors by calling:

  HXRS_RESPONSE, FLUX=FLUX, NEWFLUX=NEWFLUX, $
  		 CON_FACTORS=CON_FACTORS, UN_CON=UN_CON

  where the 8 CONVERSION FACTORS and their fractional uncertainties are given by
  CON_FACTORS and UN_CON, respectively.

  If the energy edges are already known, then these arguments FLUX, NEWFLUX,
  CON_FACTORS, and UN_CON can be entered on the first pass throught the program.

  As with the calculation of the response matrix , DRM, detailed above,
  this calculation is quick after the first pass.


  NON-STANDARD LIBRARY ROUTINES NEEDED:
	EDGE_PRODUCTS
	X_EOUT_DRM

 MODIFICATION HISTORY:
 Paul Bilodeau, NASA GSFC / RITSS, 31-May-2000 modified hxrbs_response for the HXRS instrument