; fit_model_components.txt
;
; This text file contains a list of function components available in the fit_function 
; object in OSPEX.  It also describes the parameters for each component.
;
; The path to this file is in the env. var. OSPEX_MODELS_DIR.
; This file is read and parsed by the routine fit_model_components.
;
; To add a new function component, edit this file as described below.  In your IDL
; session, set the env. var OSPEX_MODELS_DIR to point to the directory in which you
; saved the file (via a command like setenv,'OSPEX_MODELS_DIR=C:/xxx/yyy'. The required 
; edits are to add the function component name and parameter information to this file 
; as follows (easier to just look at examples in file):
;
;   Line 1: The short name in column 0, followed by dash, followed by short description.
;   Line 2: Blank, short name in column 1, dash, longer description.  If need more than one
;     line, indent following lines.
;   Lines 3-n: Indent 3, a[n) - description of parameter n
; 
; You must also provide two functions, f_xxx and f_xxx_defaults as follows:
;  Provide a function called f_xxx that returns the computed function with the following arguments:
;    x_edges - 2xn array of values for the independent variable (energy in our case)
;    params - array of parameters needed by the function
;    _extra=_extra - in case the function is called with keywords, this will prevent it from crashing
;    Example: function f_vth, energy_edges, params, _extra=_extra
;  Provide a routine called f_xxx_defaults (no arguments) that returns a structure of default 
;  values for the function in a structure like (this is for f_vth):
;    defaults = { $
;     fit_comp_params: [1e0, 2], $
;     fit_comp_minima: [1e-20, 5e-1], $
;     fit_comp_maxima: [1e20, 5e1], $
;     fit_comp_free_mask: 1B+Bytarr(2)  }
; For example, for the vth component, the function routine is called f_vth and the function 
; to return defaults is f_vth_defaults.
;
; Written: Kim Tolbert April 2, 2003
; Modifications:
;  16-Jul-2004, Kim.  Added 3pow function
;  04-Aug-2004, Kim.  Added ion function
;  11-Oct-2005, Kim.  Added more info in header about how to add user functions.
;  01-May-2006, Kim.  Added 3rd and 5th param for vth, and 2 multi_therm funcs to allow
;    rel abun to be a fitting parameter.  Added comments to not use vth_noline anymore.
;  27-Jun-2006, Kim.  Added drm_mod function
;  06-Oct-2006, Kim.  Added pileup_mod function
;  15-Oct-2006, Kim.  Added 4th parameter for pileup_mod
;  13-Oct-2007, Kim.  Added f_template and positronium functions
;  16-Jan-2008, Kim.  Changed pileup_mod params for modified pileup_countrate routine
;  30-Jan-2008, Kim.  Added photon_thin, photon_thick
;  14-Apr-2008, Kim.  Added URLs for thin and thick target documentation
;  01-may-2008, ras,  replaced  Center Thickness Ratio with blanket_coeff in hsi_drm_mod
;  12-May-2008, Kim. Added f_vth_abun, and changed a[2] text for vth
;  30-Jun-2008, Kim. Added 2 additional params to vth_abun, multi_therm_abun_exp, multi_therm_abun_pow
;  12-Aug-2008, Kim. Added gain_mod
;  16-Jan-2009, Jana, Added thin_kappa
;
;--------------------------------------------------------------------------------

vth - Variable Thermal
 vth - Optically thin thermal bremsstrahlung radiation function
 as differential spectrum seen at Earth in units of photon/(cm2 s keV)
   a[0] - Emission measure in units of 1e49 cm^(-3)
   a[1] - KT, plasma temperature in keV
   a[2] - Relative abundance for Iron/Nickel, Calcium, Sulfur, Silicon
          Relative to coronal abundance for Chianti
          Relative to solar abundance for Mewe
          (unless user selects a different abundance table manually)
   Keyword options: full/continuum/lines    Chianti/Mewe

vth_abun - Variable Thermal, Separate Abundances
  vth_abun - Optically thin thermal bremsstrahlung radiation function
  as differential spectrum seen at Earth in units of photon/(cm2 s keV)
  with separate parameters for relative abundance for Fe/Ni, Ca, S, Si
   a[0] - Emission measure in units of 1e49 cm^(-3)
   a[1] - KT, plasma temperature in keV
   a[2] - Relative abundance for Iron and Nickel
   a[3] - Relative abundance for Calcium
   a[4] - Relative abundance for Sulfur
   a[5] - Relative abundance for Silicon
   a[6] - Relative abundance for Argon
   a[7] - Relative abundance for He, C, N, O, F, Ne, Na, Mg, Al, K 
          Relative to coronal abundance for Chianti
          Relative to solar abundance for Mewe
          (unless user selects a different abundance table manually)
   Keyword options: full/continuum/lines    Chianti/Mewe
   
multi_therm_exp - Multithermal, Exp Temp
 multi_therm_exp - Multithermal function, diff. emission measure has an exponential dependence on temperature
   a[0] - differential emission measure at T = 2 keV in units of 10^49 cm^(-3) keV^(-1)
   a[1] - minimum plasma temperature in keV
   a[2] - maximum plasma temperature in keV
   a[3] - temperature scale length in keV for calculating the differential emission measure
          at temperature T:  DEM(T) = a[0] * exp( (2. - T) / a[3] )
   a[4] - Relative abundance for Iron/Nickel, Calcium, Sulfur, Silicon
          Relative to coronal abundance for Chianti
          Relative to solar abundance for Mewe
          (unless user selects a different abundance table manually)
   Keyword options: full/continuum/lines    Chianti/Mewe

multi_therm_abun_exp - Multithermal, Exp Temp, Separate Abundances
 multi_therm_abun_exp - Multithermal function, diff. emission measure has an exponential dependence on temperature
   a[0] - differential emission measure at T = 2 keV in units of 10^49 cm^(-3) keV^(-1)
   a[1] - minimum plasma temperature in keV
   a[2] - maximum plasma temperature in keV
   a[3] - temperature scale length in keV for calculating the differential emission measure
          at temperature T:  DEM(T) = a[0] * exp( (2. - T) / a[3] )
   a[4] - Relative abundance for Iron and Nickel
   a[5] - Relative abundance for Calcium
   a[6] - Relative abundance for Sulfur
   a[7] - Relative abundance for Silicon
   a[8] - Relative abundance for Argon
   a[9] - Relative abundance for He, C, N, O, F, Ne, Na, Mg, Al, K 
          Relative to coronal abundance for Chianti
          Relative to coronal abundance for Chianti
          Relative to solar abundance for Mewe
          (unless user selects a different abundance table manually)
   Keyword options: full/continuum/lines    Chianti/Mewe
   
multi_therm_pow - Multithermal, Pow Temp
 multi_therm_pow - Multithermal function, diff. emission measure has an power-law dependence on temperature
   a[0] - differential emission measure at T = 2 keV in units of 10^49 cm^(-3) keV^(-1)
   a[1] - minimum plasma temperature in keV
   a[2] - maximum plasma temperature in keV
   a[3] - power-law index for calculating the differential emission measure at temperature T:
          DEM(T) = a[0] * (2./T)^a[3]
   a[4] - Relative abundance for Iron/Nickel, Calcium, Sulfur, Silicon
          Relative to coronal abundance for Chianti
          Relative to solar abundance for Mewe
          (unless user selects a different abundance table manually)
   Keyword options: full/continuum/lines    Chianti/Mewe

multi_therm_abun_pow - Multithermal, Pow Temp, Separate Abundances
 multi_therm_abun_pow - Multithermal function, diff. emission measure has an power-law dependence on temperature
   a[0] - differential emission measure at T = 2 keV in units of 10^49 cm^(-3) keV^(-1)
   a[1] - minimum plasma temperature in keV
   a[2] - maximum plasma temperature in keV
   a[3] - power-law index for calculating the differential emission measure at temperature T:
          DEM(T) = a[0] * (2./T)^a[3]
   a[4] - Relative abundance for Iron and Nickel
   a[5] - Relative abundance for Calcium
   a[6] - Relative abundance for Sulfur
   a[7] - Relative abundance for Silicon
   a[8] - Relative abundance for Argon
   a[9] - Relative abundance for He, C, N, O, F, Ne, Na, Mg, Al, K   
          Relative to coronal abundance for Chianti
          Relative to solar abundance for Mewe
          (unless user selects a different abundance table manually)
   Keyword options: full/continuum/lines    Chianti/Mewe
  
bpow - Broken Power Law
 bpow - Broken power-law function with/without discontinuities in the derivatives
   a[0] - normalization at epivot
   a[1] - negative power law index below break
   a[2] - break energy (keV)
   a[3] - negative power law index above break

3pow - Triple Power Law
 3pow - Triple broken power-law function with/without discontinuities in the derivatives
   a[0] - normalization at epivot, photon flux of first power-law at epivot
   a[1] - negative power law index below break energy1
   a[2] - break energy1 (keV)
   a[3] - negative power law index above break energy1, below break energy2
   a[4] - break energy2 (keV)
   a[5] - negative power law index above break energy2

line - Gaussian 
 line - Single Gaussian function (high quality), width in sigma
   a[0] - integrated intensity
   a[1] - centroid
   a[2] - sigma

thin - Thin Target Bremsstrahlung
 thin - Thin-Target Bremsstrahlung x-ray/gamma-ray spectrum from an isotropic electron distribution
        (see http://hesperia.gsfc.nasa.gov/hessi/flarecode/bremdoc.pdf)
   a[0] - normalization factor in 1.0d55 cm^(-2) sec^(-1),
          i.e. plasma density * volume of source * integrated nonthermal electron flux density
   a[1] - power-law index of the electron distribution function below eebrk
   a[2] - break energy in the electron distribution function (in keV)
   a[3] - power-law index of the electron distribution function above eebrk
   a[4] - low energy cutoff in the electron distribution function (in keV)
   a[5] - high energy cutoff in the electron distribution function (in keV)

thick - Thick Target Bremsstrahlung
 thick - Thick-Target Bremsstrahlung x-ray/gamma-ray spectrum from an isotropic electron distribution
         (see http://hesperia.gsfc.nasa.gov/hessi/flarecode/bremthickdoc.pdf)
   a[0] - Total integrated electron flux, in units of 10^35 electrons sec^(-1)
   a[1] - power-law index of the electron distribution function below eebrk
   a[2] - break energy in the electron distribution function (in keV)
   a[3] - power-law index of the electron distribution function above eebrk
   a[4] - low energy cutoff in the electron distribution function (in keV)
   a[5] - high energy cutoff in the electron distribution function (in keV)

ion - Non-uniform Target Ionization Spectrum
 ion - Non-uniform Target Ionization Spectrum
   a[0] - photon normalization
   a[1] - spectral index of electron flux
   a[2] - break energy in keV

vth_noline - Variable Thermal No Lines (DO NOT USE, use vth with /contin option)
 vth_noline - This function is included only for compatibility with existing Fit Results files. 
  As of May 5, 2006, please use the vth function with the continuum option for new work.
  Variable thermal continuum, no lines, as differential spectrum seen at
  Earth in units of photon/(cm2 s keV)
   a[0] - Emission measure in units of 1e49 cm^(-3)
   a[1] - KT, plasma temperature in keV

drm_mod - Pseudo function for fine-tuning RHESSI DRM parameters
 drm_mod - always returns a value of 0.  Parameters are varied during fit and used
  in apply_drm method to compute drm on the fly.
   a[0] - FWHM fraction
   a[1] - Gain offset
   a[2] - Blanket Coefficient - default is 1, multiplies xsec
   
gain_mod - Pseudo function for modifying energy bins in model
 gain_mod - always returns a value of 0.  Parameters are varied during fit and used
  in apply_drm method to modify energy bins for model on the fly.
  New edges are (1+a[0])*old_edges + a[1]
   a[0] - Gain delta
   a[1] - Offset in energy units (usually keV) at 0.0

pileup_mod - Pseudo function for correcting for pileup (Experts only)
 pileup_mod - always returns a value of 0. Parameters are varied during fit and used
  in apply_drm method to add pileup effects to model on the fly.
   a[0] - coefficient to increase or decrease probability of pileup for energies > cutoff
   a[1] - average fractional energy from piled up photon
   a[2] - smoothing parameter in keV (sigma)
   a[3] - cutoff energy in keV that defines two regions
   a[4] - effectiveness ratio for pileup for energy loss less than cutoff energy
   a[5] - sine-modulated fraction of flux

template - Template function
 template - Interpolates a template-defined function of energy into user's energy bins
   a[0] - Normalization in photon /cm2 at Earth
   Keyword options: nuc1, nuc2, vern, alpha, fline, bline, nline
     nuc1 - includes the broad nuclear de-excitation lines produced by
            proton, alpha, and heavier nuclei, does not include the 511 keV and 2.2
            MeV lines
     nuc2 - includes the narrow nuclear de-excitation lines produced by
            proton, alpha, and heavier nuclei, does not include the 511 keV and 2.2
            MeV lines
     vern - includes the calculated shape of the 511 keV annihilation line and 
            its positronium continuum produced in the conditions of a solar atmosphere 
            calculated by Vernazza et al for a temperature of 5000 K.
     alpha - includes the line feature produced by alpha-alpha collisions for a 
            downward isotropic distribution of accelerated particles with a power 
            spectrum with index 3.5 for a flare at 60 heliocentric angle. Note that 
            nuc1, nuc2, and vern contain this line so it is best not to 
            use both of these specific templates at the same time
     fline - includes broad and narrow nuclear lines
     bline - includes broad nuclear lines
     nline - includes narrow nuclear lines
     user -  user-supplied template in user_template.sav or user_template.txt file

positronium - Positronium + 511
 positronium - Positronium continuum with 511 keV line
   a[0] - Annihilation line flux
   a[1] - Positronium continuum flux
   a[2] - Annihilation line sigma
   a[3] - Annihilation line centroid

photon_thin - Thin target photon spectrum using Bethe-Heitler cross-section.
 photon_thin - Similar to "thin" function but ~2x faster. No integration
    over electron spectrum - photon spectrum is an analytical function of 
    electron distribution parameters.  Good approximation < low-energy cutoff,
    ~10% difference from "thick" for energies >~100 keV.
   a[0] - total electron flux (in 1d55 electrons/s/cm^2)
   a[1] - spectral index below break energy
   a[2] - break energy (in keV)
   a[3] - spectral index above break energy
   a[4] - low-energy cutoff (in keV)
   a[5] - high-energy cutoff (in keV)

photon_thick - Thick target photon spectrum using Bethe-Heitler cross-section.
 photon-thick - Similar to "thick" function but ~10x faster. No integration
    over electron spectrum - photon spectrum is an analytical function of 
    electron distribution parameters.  Good approximation < low-energy cutoff,
    ~10% difference from "thick" for energies >~100 keV.
   a[0] - total electron flux (in 1d35 electrons/s)
   a[1] - spectral index below break energy
   a[2] - break energy (in keV)
   a[3] - spectral index above break energy
   a[4] - low-energy cutoff (in keV)
   a[5] - high-energy cutoff (in keV)

thin_kappa - thin-target bremsstrahlung spectrum for electron kappa distribution
 thin_kappa - thin target spectrum for electron kappa distribution
   a[0] - "emission measure" (in 1d49 cm^-3, i.e. ambient proton density * volume * electron density in kappa distribution )
   a[1] - temperature (in keV)
   a[2] - kappa index
   a[3] - high-energy cutoff (in keV)