modelflux

Synopsis

Calculate model flux or count rate

modelflux  arf rmf model paramvals emin emax [absmodel] [absparams]
[oemin] [oemax] [rate] [pflux] [flux] [urate] [upflux] [uflux] [opt]

Description

Convert between the absorbed energy flux, photon flux and count rate for any Sherpa model, given a set of spectral response files. The method assumes the model has an overall linear normalization. The default behaviour is to return the absorbed flux given an input count rate.

An additional, optional absorption model may also be supplied, in which case the corresponding unabsorbed fluxes and count rates are also calculated.

For a given set of model parameters, the base model energy spectrum F(E) is multiplied by the absorption model spectrum A(E) to give the absorbed flux spectrum F'(E) (A=1 if no absorption model is supplied). The total absorbed flux F' is then calculated as the integral over E of F'(E), and the unabsorbed flux F is the integral of F(E). F'(E) is then multiplied by the product of the supplied ARF and RMF and integrated over E (via the emin and emax parameters) and summed over channel (via the oemin and oemax parameters) to yield a predicted total observed count rate R'.

The unabsorbed photon flux spectrum P(E) = (F(E)/E) and its absorbed counterpart P'(E), with integrals P and P', are also calculated from F(E) and F'(E).

The model/params and absmodel/absparams paradigm corresponds to a scenario in which a source of flux F would have given rise to a count rate R, but because an intervening absorber reduces the flux by a factor A to F', a reduced count rate R' is seen. Typically, given an observed R', we wish to find F and A.

When opt=rate, the total rate R' is compared to the supplied count rate to scale the normalization of F and F', and P and P'. When opt=flux, F' is compared to the supplied flux to scale the normalization of the other quantities. When opt=pflux, P' is compared to the supplied pflux to scale the normalization of the other quantities. The results are written to the screen (for verbose > 0) and stored in the corresponding parameters.

The output from modelflux is stored in its own parameter file. The standard parameter tools pget and plist can be used to retrieve the values.

Examples

Example 1

modelflux arf.fits rmf.fits "xsphabs.abs1*powlaw1d.p1"
paramvals="abs1.nh=0.07;p1.gamma=2.26" emin=0.5 emax=7.0

The default use is to convert from rate to flux. This example calculates the flux of the source in [0.5,7.0] keV corresponding to a count rate of 1 count/second in the same band.

The conversion factor can be retrived using the pget tool

% pget modelflux rate pflux flux
1
0.0023089
5.1917e-12

Which shows for this model with this ARF, a count rate of 1.0 cts/sec yields a photon flux of 0.0023 photon/cm^2/sec or 5.19e-12 erg/cm^2/sec over 0.5 to 7.0 keV energy range.

Example 2

modelflux arf.fits rmf.fits "xsphabs.abs1*powlaw1d.p1"
paramvals="abs1.nh=0.07;p1.gamma=2.26;p1.ampl=0.0003" emin=0.5 emax=7.0
rate=0.1

Here we specify an explicit count rate of 0.1 count/s and calculate the energy flux and photon flux that would generate that count rate, given the model.

Even though we specified an amplitude parameter for the power law, it does not affect the result, since the output is linearly rescaled to match the requested count rate.

Example 3

modelflux arf.fits rmf.fits "xsphabs.abs1*powlaw1d.p1"
paramvals="abs1.nh=0.07;p1.gamma=2.26;p1.ampl=0.0003" emin=0.1
emax=10.0 oemin=0.5 oemax=2.0 rate=0.1

This example finds out what flux in the energy range 0.1-10 keV would produce a 0.5-2 keV count rate of 0.1 count/s. The emin and emax parameters always specify the energy range for the flux; the oemin and oemax parameters can be used to specify a different energy band for the rate.

Example 4

modelflux arf.fits rmf.fits
model="xsphabs.abs1*(powlaw1d.p1+xsgaussian.g)"
paramvals="abs1.nh=0.07;p1.gamma=2.26;p1.ampl=0.0003;g.sigma=0.1;g.line=
1.0;g.norm=1.0e-5" emin=0.5 emax=2.0 flux=1E-12 opt=flux

This example uses "opt=flux" to tell modelflux we are giving it the flux and want to know the count rate (opt="rate" is the default). Calculates the count rate of the source in [0.5,2.0] keV where a flux of 1E-12 ergs/cm^2/s is observed in the same band. Although the overall normalization is scaled to the requested flux, the relative normalizations of the two components are set using the p1.ampl and g.norm parameters.

Example 5

modelflux arf.fits rmf.fits powlaw1d.p1 paramvals="p1.gamma=2.26"
absmodel=xsphabs.abs1 absparams="abs1.nh=0.8" emin=0.1 emax=10.0
oemin=0.5 oemax=2.0 rate=0.1 opt=rate

This example is like Example 3 but moves the absorption model to the absmodel parameter so that unabsorbed fluxes may also be calculated. The conversion factors can be retrieved with standard parameter tools such as plist:

% plist modelflux

Parameters for /home/user/cxcds_param4/modelflux.par

           arf = arf.fits         Ancillary Response File (ARF)
           rmf = rmf.fits         Response File (RMF)
         model = powlaw1d.p1      Sherpa model definition string
     paramvals = p1.gamma=2.26    ';' delimited string of (parameter=value) pairs
          emin = 0.1              Energy range lower bound for flux (keV)
          emax = 10               Energy range upper bound for flux (keV)
     (absmodel = xsphabs.abs1)    Absorption model for calculating unabsorbed flux
    (absparams = abs1.nh=0.8)     ';' delimited string of (parameter=value) pairs for absorption model used to calculate unabsorbed flux
        (abund = angr)            XSPEC abundance table (if relevant to absorption model)
        (oemin = 0.5)             Energy range lower bound for rate (keV), default=emin
        (oemax = 2)               Energy range upper bound for rate (keV), default=emax
         (rate = 0.1)             count rate in counts s^-1, default=1.0
        (pflux = 0.0003483)       photon flux in energy range in photon cm^-2 s^-1
         (flux = 1.5484e-12)      energy flux in energy range in erg cm^-2 s^-1
        (urate = 0.49759)         Unabsorbed count rate in counts s^-1 (if absmodel defined)
       (upflux = 0.0027655)       Unabsorbed photon flux in energy range in photon cm^-2 s^-1 (if absmodel defined)
        (uflux = 3.855e-12)       Unabsorbed energy flux in energy range in erg cm^-2 s^-1 (if absmodel defined)
          (opt = rate)            input type: (use this to determine the others)
      (verbose = 1)               verbosity setting
         (mode = ql)              

which shows a conversion factor of 0.1 cts/sec (absorbed) gives in this example an unabsorbed rate (urate) roughly 5 times brighter at 0.5 cts/sec.

Example 6

modelflux arf.fits rmf.fits powlaw1d.p1 paramvals="p1.gamma=2.26"
absmodel=xsphabs.abs1 absparams="abs1.nh=0.8" emin=0.5 emax=7.0
flux=1e-11 opt=flux

This example illustrates the calculation of absorbed and unabsorbed fluxes and rates given an input observed flux. (Input of unabsorbed flux is not supported).

Parameters

Detailed Parameter Descriptions

Parameter=arf (file required filetype=input)

Ancillary Response File (ARF)

Parameter=rmf (file required filetype=input)

Response File (RMF)

Parameter=model (string required default=)

Sherpa model definition string, e.g. xsphabs.abs1*xspowerlaw.p1

Note that not all names can be used - that is the user name given to each model, after the "." character - as it cannot be an existing Python function. This is why the example is xsphabs.abs1 and not xsphabs.abs, as the latter would cause the tool to exit with an error.

Parameter=paramvals (string required default=)

semicolon-delimited (';') string of (id.parameter=value) pairs, e.g. abs1.nh=0.07;p1.gamma=2.26

Parameter=emin (real required default=INDEF)

Lower bound of flux energy range in keV

Parameter=emax (real required default=INDEF)

Upper bound of flux energy range in keV

Parameter=absmodel (string not required)

Sherpa model definition string for extra absorption, e.g. xsphabs.abs1.

If this parameter is set, the program calculates the absorbed flux using the product of this model and that given in the base model in the 'model' parameter. It then also gives the unabsorbed flux derived by omitting the absmodel but keeping the base model's normalization unchanged.

Parameter=absparams (string not required)

Semicolon-delimited (';') string of (id.parameter=value) pairs, e.g. abs1.nh=0.07 that defines the parameters for the model specified in absmodel.

Parameter=oemin (real not required default=INDEF)

Lower bound of energy range for count rate in keV, default=emin

Parameter=oemax (real not required default=INDEF)

Upper bound of energy range for count rate in keV, default=emin

Parameter=rate (real not required default=1.0)

count rate in counts s^-1

Parameter=pflux (real not required default=INDEF)

photon flux in energy range in photon cm^-2 s^-1

Parameter=flux (real not required default=INDEF)

energy flux in energy range in erg cm^-2 s^-1

Parameter=urate (real not required default=1.0)

unabsorbed count rate in counts s^-1

Parameter=upflux (real not required default=INDEF)

unabsorbed photon flux in energy range in photon cm^-2 s^-1

Parameter=uflux (real not required default=INDEF)

unabsorbed energy flux in energy range in erg cm^-2 s^-1

Parameter=opt (string not required default=rate)

Input type: (rate|flux|pflux), rate->flux,pflux or flux->rate,pflux

This parameter is used to control whether modelflux calculates a rate from the flux or pflux parameters, or vice versa.

Changes in CIAO 4.14

If the verbose parameter is set to 2 or higher then screen messages from XSPEC models will be displayed. At verbose=2 it is equivalent to the default XSPEC chatter setting of 10, and at verbose=5 it changes to the maximum XSPEC chatter value (25). This can be used to identify problems with the ~/.xspec/Xspec.init file, such as ATOMDB or NEI versions that are not supported by the XSPEC version included in CIAO (see ahelp xs).

Bugs

Missing file names are not included in the error messages.

modelflux does not check for empty model nor empty parameter strings which will cause the tool to exit with a possibly confusing error message.

See Also

tools::response

color_color

tools::statistics

aprates

utilities

calc_chisqr, calc_energy_flux, calc_model_sum, calc_photon_flux, calc_source_sum, calc_stat, gamma, igam, igamc, incbet, lgam