Appendix I: Older Release Notes

New in v12.13.1

New features

• Parallelization
  • Added parallel processing to leven when usechainrule is no. Added xset usechainrule option to switch between fast and slow second derivatives so this can be done without changing Xspec.init and restarting xspec.
  • In the various models which use the apec code added option of multithreading over the temperatures for the calculation of lines in the spectrum. Multithreading here is turned on and off using xset APECMULTITHREAD. The default is off. For the basic apec model multithreading does not provide a speed advantage. However, if line broadening is selected (eg using bapec) then multithreading will speed up the calculation. Also, for models which combine multiple temperatures such as cooling flow or NEI models multithreading can provide a significant speed increase.

• Spectropolarimetry plotting
  • Changed the polangle plot so that the angles all lie between the mean angle $\pm$90 degrees. This avoids plots where values jump between the top and bottom of the plot as the angle wraps around.
  • The polangle and polfrac plots now take account of any plot grouping set. If any spectrum in a data group is in the same plot group as a spectrum in another data group then all the spectra in the second data group are added to the plot group for the purposes of these plots only.
  • If any of the polfrac values or errors are calculated as NaNs then these are replaced by the PLT NO value and will not be plotted.

• Mdefine
  • Fixed mdefine to handle the case when the user is mdefining a convolution model which consists only of an xspec convolution model.
  • Added support for table models using atable, mtable, or etable in mdefine expressions.
  • Added 2nd to 5th order Legendre polynomials to mdefine built-in functions.

• Updated Models:
  • bwcyc: Tightened the boundaries of parameters; now treats NaN as positive infinity
  • cevmkl, cemekl: Increased lower limits of Tmax parameter
  • gabs: Fixed units for Strength parameter
  • tbnew: Reduced stderr logging of non-error announcements

• Miscellaneous:
  • The syst command to set model systematic errors can now apply systematics to individual models (default or named) instead of to all models.
  • The precision of parameter values from tclout(r) has been increased to 10 figures.
  • The error command diagnostic output is now controlled by the chatter level.

Bug fixes

The following patches for 12.13.0 have been included:

• 12.13.0a. When the X axis is in energies or wavelengths, plot delchi and plot fitstat (or plot chisq) are not being scaled properly. When the X axis is in wavelengths and perhz is on, plot counts is unable to construct its Y axis label.
• 12.13.0b. If a model defined using mdefine calls another xspec model which requires a separate model calculation for each spectrum, that information is lost.
• 12.13.0c. plot delchi and plot fitstat/chisq are not being properly scaled when spectra have multiple models assigned to them. This also restores the insertion of systematic model error into plot delchi and plot fitstat/chisq, and adds it to other plots that were previously ignoring it.
• 12.13.0d. Fix to mdefine so that it can now include built-in Xspec convolution models as part of its expressions for additive and multiplicative mdefine components.
• 12.13.0e. Added chain proposal uniform deltas [factor] and chain proposal uniform limits options. For backwards compatibility, chain proposal uniform defaults to chain proposal uniform limits.
• 12.13.0f. The zkerrbb model undercalculates the flux (and luminosity) by a factor of (1+z)$^2$.
• 12.13.0g. The Voigt line model can have a small sub-bin offset and incorrect shape.

In addition the following bugs have been fixed:

• When the 'energies' command is in use for table models, a crash may occur if all data sets are cleared.
• The 'tabint' function (for external programs using Xspec's table interpolation code) is not properly handling the case when default LOELIMIT and HIELIMIT are in use.

New in v12.13.0

New features

• New Models:
  
  

  cglumin

  convolution model to calculate luminosity with the source distance in kpc

• Updated Models:
  • Improved parallelism between mdefine'd and built-in model components. Any mdefine'd models now appear in the "model ?" list indicated by a hash (#) sign.
  • Updated wrappers for change of ismabs, ismdust, and olivineabs to double precision Fortran in previous release.
  • Note that internal changes to model handling mean that initpackage should be rerun for any local models.

• Plotting:
  • Added plot fitstat option. This supersedes plot chisq and works correctly for all fit statistics.
  • Added (l)edata and (l)eedata plot options.
  • Fixed X-axis ranges when stacking plots vertically. Use common X-axis if plots are not disjoint by more than an order of magnitude.
  • Added setplot areascale/noareascale options which modify the data, background, and residual plots by dividing by the AREASCAL keyword or vector. This is mainly useful for the XMM RGS. If setplot area is in use then this has no effect because the AREASCAL values are included when dividing by the area.
  • Added setplot errortype option to specify how the error bars should be calculated for the plot (note - this has no effect on fitting). This can already been done as part of the setplot rebin option.

• MCMC:
  • Added new chain proposal uniform option which gives a uniform distribution between the parameter lower and upper limits. Useful for setting initial walkers in gw method.

• Miscellaneous:
  • Added comp and group options to show all parameters in a given component or group to show parm free, fixed, and linked.
  • Fixed simftest.tcl so that it returns the model to the state on input.
  • Added reducedchisq.tcl and writesimpars.tcl scripts.
  • Now stores DETNAM, FILTER, STOKESPR, STOKESWT keyword values for spectra and will give warnings about inconsistencies with background/correction, arfs, and rmfs.
  • Improved diagnostic output when ARF files fail to load.

Bug fixes

The following bugs have been fixed.

• Fixed case where all spectra are removed while using extended energies, and table models are in use.
• tclout datagrp now returns 0 rather than 1 when no spectra are loaded.

v12.12.1 February 2022

New features

• New Models:
  
  

  polconst	Polarization constant with energy.
  polpow	Polarization power law with energy.
  pollin	Polarization linear with energy.

• Updated Models:
  • rotpol has been renamed as polrot for consistency with the other spectropolarimetric models.
  • Replaced fixed size internal array in compbb with one which is allocatable. This fixes a potential problem with large numbers of energy bins.
  • Simplified code for ismabs model and fixed offset by one bin problem when using the tabulated data. Converted ismabs, ismdust, and olivineabs to double precision fortran models. Rationalized variable names and removed copies of subroutines.
  • Added new math operators atan2, sinh, sinhd, cosh, coshd, tanh, tanhd, sign, heaviside, boxcar, atan, asinh, acosh, atanh, erf, erfc, and gamma for use in mdefine and newpar.
  • mdefine expressions can now include other mdefined models.

• Plotting:
  • Added option to appropriate plots to specify the plot group numbers to use in the plot. eg plot 1 data resid makes the data and residuals plots for plot group 1 only.
  • Added plot polangle and plot polfrac options. These plot polarization angle and fraction. One set of data points and errors are produced for each data group. Each data group must have complete sets of I,Q,U Stokes parameter spectra.

• tclout stat now allows contributions to the fit statistic from individual spectra to be retrieved.

• Changes to internal functions:
  • Made a version of tableInterpolate which passes a map of XFLT values instead of a spectrum number. This allows other users of the library to run their code without a spectrum loaded.
  • Changed variables and comments in LinearInterp to improve clarity. Added C and Fortran wrappers in XSFunctions/Utilities for the LinearInterp routines. Fixed error in linInterpInteg in first bin(s) if target binning is much finer than current. Added double precision versions of LinearInterp wrappers.

Bug fixes

All bug fixes to v12.12 released as patches are included in v12.12.1. In addition, the following bugs have been fixed.

• Batch mode scripts which did not exit were leaving command echoing in a disabled state.
• When entering a Tcl control structure from the Xspec prompt, the new prompt string wrongly contained the “puts -nonewline” command.
• When calling setplot with an abbreviated option name, quotes and escape characters were not handled properly.
• Restored the ability for users to include header files from XSFunctions and XSFunction/Utilities in their local models, without having to also specify the path.
• Fix to mdefine expression parsing when using MIN or MAX in combination with xspec model functions.
• Fix to handling of errors associated with models. There was an inconsistency in whether errors were variance or sqrt(variance). Any such errors should be calculated as variance.

v12.12 July 2021

New features

• New Models:
  
  

  wdem	Power-law differential emission measure.
  grbjet	GRB prompt emission (Farinelli et al., 2021).
  rotpol	Rotate polarization.
  zxipab	Power-law distribution of ionized absorbers.

• Updated Models:
  • Table models have been enhanced to allow multiple spectra to be associated with each parameter grid point. The spectra to be used can then be selected using the XFLTnnnn keyword values. The keyword NFLTEXP gives the number of spectra at each grid point and the keywords XFXPnnnn hold the filter expression to determine which is used. At the moment the only filter expressions allowed are of the form “key:value” which match to XFLTnnnn keyword values in the spectra. The test application for this is spectropolarimetry.
  • A new keyword ESCALE can be added to table model files. If true this automatically adds an Escale parameter to the model which is used to scale the energy when reading the model spectrum from the table.
  • Table models with no interpolation parameters can now be read.
  • Table model parameter names containing spaces are modified to use underbars instead of spaces to avoid problems.
  • recorn has been changed from a multiplicative to a mixing model (this is for internal xspec reasons and should make no practical difference).
  • Mixing models can now be calculated if there is only one datagroup.
  • The creation of new mixing models has been simplified with the mixsetup program using the mixmodel.dat file to automatically create interface routines. In addition the MixUtility class now includes a number of useful methods which reduce the required knowledge of xspec internals.

• Markov Chain Monte Carlo:
  • For the G-W algorithm the initial walkers are now set using the proposal distribution.
  • Added new proposal distributions gauss deltas <value>and cauchy deltas <value>where <value>is a factor by which to multiply the parameter deltas.
  • Fixed an error in the calculation of the Geweke Convergence diagnostic which was too large by a factor of $\sqrt2$.

• Added lognormal, gamma, cauchy, beta, student's t, half-normal, power-law, isotropic, and shifted lognormal options for Bayesian priors.

• Removed the word normalization from the y-axis of plots. This will have little effect because the normalization is almost always one. For the other cases setplot area performs a similar function.

• The show command has new options frozen, linked, tied (the last two are identical) which print out the appropriate subsets of the parameters.

• An x preceding any xspec command name is interpreted as that command name (eg xfit can be used for fit). This can be useful if you want to alias a command name to do something else (eg if you want to write your own Tcl script for fit which does other things as well as running xfit).

• For the flux command when consecutive spectra in the same datagroup have the same energies, all of the spectrum numbers are now displayed rather than just the first.

• The ConvolutionInLnSpace template routine has been changed to pass the index into the parameter array for the energy instead of the energy itself. Also if the input energies are already log spaced then they are not rebinned onto an internal array.

• Added Lodders et al 2009 to the table of solar abundances in abund.

Bug fixes

All bug fixes to v12.11 and v12.11.1 released as patches are included in v12.12. In addition, the following bugs have been fixed.

• External Fortran programs calling Xspec's xsatbl/xsmtbl functions would crash when Xspec wrote table model diagnostic output.
• Running nested scripts would cause a misleading error message to appear if the nested scripts were in different directories.
• The vmcflow model could cause a plotting crash when its redshift parameter was set to zero.
• plot eff was not working for newly created faked spectra, unless the spectra were removed and reloaded.
• When using setplot area for datasets whose responses had EBOUNDS energies listed in descending order (usual for gratings), the plotted results were the negative of the correct values.

v12.11 Mar 2020

New features

• New Models:
  
  

  ismdust	Extinction due to silicate and graphite grains
  olivineabs	Extinction due to olivine grains
  agnslim	AGN super-Eddington accretion model.
  zkerrbb	Redshifted version of kerrbb
  thcomp	Thermally comptonized continuum convolution model.
  logconst	Convert normalization to log units
  log10con	Convert normalization to log10 units
  bwcycl	Self-consistent cyclotron line model.
  clmass	Mixing model assuming constant gravitational mass in each shell.
  monomass	Mixing model parameterized by differences of mass densities in adjacent shells.
  nfwmass	Mixing model with NFW gravitation potential.

• Updated Models:
  • Using the new 201 tabulated temperatures v3.0.9 AtomDB files for apec models. These CEI files reduce potential interpolation problems (see http://atomdb.org/interpolation/index.php). The interpolation scheme can be switched between log and linear interpolation using xset APECLOGINTERP. Another option to reduce interpolation errors is provided by xset APECUSENEI which switches all calculation of CEI spectra through the NEI code. This is slower but can be used to check calculations. To recover the older v3.0.9 files use xset APECROOT 3.0.9_51. If you do this and also want to use NEI models then you also need to use xset NEIAPECROOT 3.0.9.
  • The diskline, rdblur, kdblur, kdblur2, laor, laor2, kerrconv, kerrdisk have all been sped up using a new FFT-based convolution routine.
  • The xscat model has been updated to extend the range of the Rext parameter for MRN and ZDABAS options from 0-199 arcsec to 0-236 arcsec.

• Major overhaul to code calculating statistics. Main visible change is that each spectrum can have a different fit statistic but there is only a single test statistic.

• Added support for responses which have been split into parts with different resolution. This is very effective for responses which have high resolution but long tails down to low energies. In the case of the XRISM Resolve instrument this will provide speed increases of up to an order of magnitude. Note that if a file contains multiple response extensions then XSPEC will read and use them all unless a response extension is specified using e.g. resp.rsp{n}.

Bug fixes

All bug fixes to v12.10.1 released as patches are included in v12.11.

v12.10.1 Oct 2018

• New Models:
  
  

  zbknpower	redshifted broken power law
  zlogpar	redshifted modified power law
  agnsed	model for the SED of an AGN
  qsosed	simplified version of agnsed
  cph	cooling+heating model for cool core clusters
  vcph	cph with variable abundances
  relline	Relativistically broadened emission line
  rellinelp	relline with lamp-post geometry
  rellinelpext	relline with extended lamp-post geometry
  relconv	Convolve with relline profile
  relconvlp	Convolve with rellinelp profile
  relconvlpext	Convolve with rellinelpext profile

• Updated Models:
  • Added an xset LINECRITLEVEL option for the critical level for gaussian/lorentzian/voigt lines. If set this overrides the coded values.
  • Modified diskline, rdblur, kdblur, kdblur2, laor, laor2, kerrconv, kerrdisk for high resolution spectroscopy.
  • Added C/Fortran tabint wrapper for C++ tableInterpolate function.

• The statistic cstatbN where N is an integer calculates the C-statistic in the presence of background with both source and background spectra binned so that there are at least N counts in each background bin.

Bug fixes

All bug fixes to v12.10.0 released as patches are included in v12.10.1.

v12.10.0 Mar 2018

New features

• The mdefine command now allows new models to be defined by equations which include xspec model functions. Among the capabilities this enables is to redefine model parameters. For instance, suppose we want to use the pexrav model but have one parameter be the inclination instead of the cosine of the inclination, as defined in the model. Then we mdefine a new model:
  mdefine mypex pexrav(g,f,refl,z,A,FeA,cos(Incl))

• New Models:
  
  

  brnei	rnei models with line broadening
  grbcomp	GRB prompt emission model
  jet	Leptonic relativistic jet model
  ssa	Strangeon star atmosphere model

• Updated Models:
  • The default AtomDB version number is now 3.0.9.
  • The xset APECMINFLUX option for apec models now includes the $10^{14}$ normalization factor and the time dilation correction.
  • A new xset APECBROADPSEUDO option switches on line broadening of the pseudo-continuum (this contains low emissivity lines which are not individually tabulated in the AtomDB lines file).
  • Most of the model data files have been converted to FITS. In several cases multiple files have been merged into a single file with multiple extensions. This should make no difference to any results.
  • Uniform wrappers based on the model name are now available for all model functions. C++ wrappers are CXX_modelname, C wrappers are C_modelname, and Fortran wrappers are f_modelname.
  • The xscmdnewpar command can now handle multiple ranges specified on the command line.

• Markov Chain Monte Carlo:
  • MCMC chains now work with response parameters.
  • Geweke's convergence diagnostic and the Deviance Information Criterion have been added to the output.
  • When plotting multiple chains each is now placed in its own plot group (and hence plotted in a different color) instead of being concatenated.
  • plot options for running means and autocorrelations have been added.
  • The fraction column produced by the margin command can be written out using the tclout margin fraction option.

• CUSUM has been added to the test statistics.

• Options have been added to plot goodness to control the number of bins and whether the binning is linear or logarithmic.

• An option to set the background spectrum exposure time has been added to multifake.

Bug fixes

All bug fixes to v12.9.1 released as patches are included in v12.10.0. In addition, the following problems have been corrected:

• The pexrav model sometimes crashed with a negative or zero incomplete gamma value.
• steppar was mishandling parameters belonging to named models starting with an l or an n. It was mixing this up with the log and nolog options.
• The error command did not handle the unnamed specifier on the command line.
• mdefine model definitions were not handled correctly by the save command.
• XSPEC did not properly handle extended file syntax such as filename[n] and filename+n for cases where multiple HDUs shared the same EXTNAME and weren't differentiated by EXTVER.
• editmod did not correctly parse certain cases of table model filenames which included a hyphen.
• The goodness command when run in parallel processing mode failed if it had to prompt for continuation of a fit.
• tclout idline had a memory leak.
• chain best and chain info were using the currently variable parameters instead of the loaded chain files.

v12.9.1 Jan 2017

New features

• New Models:
  
  

  carbatm	NS non-magnetic C atmosphere
  clumin	calculates luminosity
  hatm	NS non-magnetic H atmosphere
  ismabs	High-resolution ISM absorption
  rfxconv	reflection from ionized disk
  slimbh	slim accretion disk
  snapec	galaxy cluster spectrum using SN yields
  (b)(v)(v)tapec	apec model with different temperatures for continuum and emission lines
  tbfeo	tbabs model with O and Fe only variable
  tbgas	tbabs model with no grains
  tbpcf	tbabs model with partial covering
  tbrel	tbabs model that allows negative columns
  vashift	velocity shift an additive component
  vmshift	velocity shift a multiplicative component
  voigt	emission line with a Voigt profile
  xilconv	reflection from ionized disk
  xscat	dust scattering out of the beam

• Updated Models:
  • apec models updated to AtomDB 3.0.7
  • nei models updated to AtomDB 3.0.4 eigen files
  • The apec code now has the ability to add new line shapes for broadening although at present only a single Gaussian line shape is operational.
  • A new xset option APECMINFLUX can be used to specify a minimum line flux below which lines are not broadened. Also the maximum flux in any line in the apec model is saved as apecmaxlineflux and this can be recovered using tcloutr modkeyval apecmaxlineflux. At the moment both this and APECMINFLUX do not include the 1e14 normalization factor and any time dilation correction.
  • The code for the various CEI models was rationalized and there is a new C++ routine calcMultiTempPlasma which can be used by other models. The old Fortran sumdem routine remains as a wrapper for old models.
  • tbabs model code has been updated. The old version is available by using xset TBABSVERSION 1.
  • Updated nsmaxg model with new tabulated model files.
  • Increased the speed for accessing values from table models.
  • Modified table model code to support new keywords LOELIMIT and HIELIMIT to specify model values to be taken below and above the tabulated energies.
• Plotting:
  • Added low and high energy limits to setplot id so lines are only shown for the specified energy range.
  • Added setplot (no)contimage option to turn on (off) the background image in contour plots.
  • The keV to Angstrom conversion value stored in Numerics.h has been updated to that from CODATA 2014.
• Fitting:
  • Added parallelization to chain walker calculations and to the goodness simulations.
  • The error command can now process parameters from more than 1 model in a single call.
  • In the various cstat statistics, any correction file spectrum is now taken account. This does implicitly assume that the correction file has Poisson statistics.
  • The Tcl script lrt.tcl now uses the fakeit nowrite option so intermediate faked files are not written out. Also, now works for multiple data groups.
• Input/Output:
  • Increased the precision of the reported output from the tclout command options.
  • Increased the allowed flux (counts) to beyond the 4-byte limit when running fakeit with counting statistics selected.
  • New tclout option fileinfo writes the value of the keyword given as the fileinfo argument. e.g. tclout fileinfo detnam returns the value of the detnam keyword in the spectrum extension.
• Xspec.init file:
  • Added PARALLEL to set default parallelization options
  • Added NEI_VERSION to set default version for NEI models
  • Added CONTOUR_IMAGE to set default for adding image to contour plots
  • Changed default cross-sections from bcmc to vern
• The manual has now been rewritten in LaTeX. The appendix on statistics has been expanded. Cross-referencing has been improved.

Bug fixes

All bug fixes to v12.9.0 released as patches are included in v12.9.1. In addition, the following problems have been corrected:

• A previous revision to the goodness command removed the requirement that the fit must be in a valid state at the start, however it was incorrectly marking the fit as being in a valid state at the end.
• When re-reading a previously loaded table model file, XSPEC was not correctly recognizing whether or not parameter error values existed.
• A spectrum's displayed net count rate variance needs to be updated when the fit weighting method gets changed.

v12.9.0 Jul 2015

New features

• Mix model components are no longer heavily restricted in their usage. Previously mix components could only be placed at the start of a model expression, to operate on the results of the rest of the expression. Now they can be inserted throughout the expression in the same manner as convolution components.
• Models with mix components can also be assigned to source numbers other than 1. A corollary of this is that a mix model is no longer required to operate on all currently loaded spectra.
• To allow more than one mix model at a time the syntax for XFLT#### keywords has been generalized. These keywords are now strings of form "key: value" with xspec maintaining an internal database of key, value pairs which mixing model code can access. Backward compatibility with the old version of XFLT#### containing only a value is maintained.
• Expanded the types of expressions allowed in parameter linking. It can now handle the same mathematical functionality supported in mdefine equations. Related to this, parameters can also be specified as p# and modelName:p# in link expressions, as well as the old # and modelName:#. The link expressions are now displayed using the p# format.
• The output of the plot margin command is now independent of the grid size. There is a new plot integprob command which also must be run after the margin command and which plots the integrated probability within the contours shown.
• The data and back commands now handle files with multiple SPECTRUM extensions. There are a number of ways of specifying a particular extension: filename{N} will use the Nth SPECTRUM extension; filename{SPECTRUM2} will look for an extension called SPECTRUM2; filename{back} will use the first SPECTRUM extension with the HDUCLAS2 keyword set to “BKG”; filename{name=value} will look for a SPECTRUM extension with keyword name set to value (in this case there must be no spaces within the {}). If the BACKFILE keyword in a source filename is set to the filename itself then XSPEC will get the background from the extension with HDUCLAS2 set to “BKG” (this, finally, makes Chandra level 3 files work seemlessly in XSPEC).
• The error command now has a nonew option. This determines whether to repeat the calculation when a new minimum is found. Previously it was relying on the query setting to make this decision.
• Added grey-scale image as background to to contour plots (to remove them use the image off command in PLT. plot dem now displays a histogram. The new plot eqw option shows the distribution of equivalent width values after running the eqwidth command with the err option.
• New model nlapec. There is also an APECNOLINES xset option which will turn off lines for all apec models.
• The models using AtomDB files now require the line files to be sorted in increasing order of energy within each element and ion. This allows a speed-up in the model calculation.
• Replaced the rescalecov script with the chain rescale command.
• The plot delc command now works for cstat, plotting (obs-mod)/error, however it is important to remember that this is not plotting contributions to the statistic.

Enhancements previously released as patches to 12.8.2

• A new -udmget64 option has been added to initpackage. This is intended for Mac platform users with local Fortran models which still make use of the udmget memory allocation function.
• tclout steppar can now retrieve values of the variable parameters as well has the fixed parameters which are being stepped through.

Bug fixes

All bug fixes to v12.8.2 released as patches are included in v12.9.0. In addition the following problems have been corrected:

• For the case where counting statistics are not applied, fakeit now outputs the spectrum in a RATE column rather than COUNTS. This is to remove bias caused by truncation errors. It also now outputs a STAT_ERR column and sets the POISSERR flag to false.
• Special characters have been removed from all model parameter names and (generally) replaced with underscores. This is to make their name strings more easily accessible in PyXspec.
• When calculating tclout peakrsid with Cstat, it should not make use of correction files.
• Redundant model fold calculations have been removed during certain update contexts.
• Fix to vequil model array assignment error.
• The default filenames for fakeit output should always be in the current run directory, even when the response file is in a different directory.
• A file-write race condition has been eliminated for the case of running lmod in parallel XSPEC sessions.
• the vvnei model had the tau and meankT parameters flipped.
• the AtomDB input files were being reopened unnecessarily often.

Changes to PyXSpec

New Features:

• Local models may now be written in Python and inserted into XSPEC's models library with new AllModels.addPyMod() function.
• The plot array retrieval interface (ie. Plot.x(), Plot.y()) has been expanded to allow retrieval from secondary plot panels in a mulit-panel plot.
• New Parameter.index attribute.
• New backscale attribute for Spectrum and Background classes.
• Added new function Fit.stepparResults() for retrieving results of most recent steppar run. (Previously available as a patch)
• New noWrite option added to AllData.fakeit (Previously available as patch)

Fixes:

• The Model.__call__ function now returns Parameter objects by reference rather than by value. This is to allow the returned object to retain any custom attributes the user may have added.
• Improved handling of Ctrl-c breaking in several prompting contexts.

V12.8.2 Jul 2014

New features

• The code underlying the NEI models has been rewritten to accommodate the new AtomDB 3.0 files, the beta version of which are included as the default when using any of the NEI models. Older versions can be recovered using xset NEIVERS. The CEI models (apec etc) use some of the same code but there should be no change in their behavior except for a slight speed-up.
• New models:
  • agauss - Gaussian model with units in Angstrom and a Gaussian shape in wavelength space.
  • nsx - Neutron star non-magnetic atmosphere model from Wynn Ho and collaborators.
  • nsmaxg - Neutron star magnetic atmosphere model.
  • rnei - NEI recombination model assuming an initial temperature.
  • vrnei - rnei with variable abundances for the common elements.
  • vvrnei - rnei with variable abundances for all elements (Z <= 30).
  • zagauss - The agauss model with a redshift parameter.
• The goodness command has added options fit|nofit. The fit option runs a fit on each simulation before calculating the test statistic.
• The cstat fit statistic can be modified by appending an integer eg. statistic cstat5. In this case the statistic will be evaluated as if the group min N had been used in grppha. This is not as efficient because the rebinning has to be done every statistic evaluation however it is useful for testing using simulations.
• The model command now checks that parameters are all within a reasonable order of magnitude ($\sim10^{10}$) of each other, and issues a warning if they are not.
• Improved the handling of new-best-fit cases when running the error command on parallel processes. The global new-best-fit is now automatically retained. Previously the user was prompted to re-run error in a single process.
• Models can now store (keyword,value) pairs using loadDbValue (C++)or PDBVAL (Fortran). These values can be recovered using the tclout <modkeyval> option. This provides a way to get internal information from the last invocation of a model. There is a manual XSFunctions_guide.pdf in Xspec/src/help describing some of the C++ classes used in the XSFunctions library. This is intended to make it easier to use these classes in other models.

Enhancements previously released as patches to 12.8.1

• PyXspec: added Fit.testStatistic attribute for retrieving the test statistic value from the most recent fit.
• PyXspec: added compiler macros for switching to <Python/Python.h> include paths when building on Mac platforms.

Bug fixes

All bug fixes to v12.8.1 released as patches are included in v12.8.2. In addition the following problems have been corrected:

• Fix for a particular case of non-associative expression evaluation. Models of the form C((M1*A)M2) or C(M1*A)M2, where C is a convolution component, were being wrongly evaluated as (C(M1*A))M2.
• For users with external programs linking to the XSPEC model library, the FNINIT function now properly initializes the AtomDB version to v2.0.2.
• Fix for an ignore command syntax evaluation that was causing a crash on OS X Mavericks.

V12.8.1 Aug 2013

New features

• New models:
  • cpflux - a variant of cflux for photon flux.
  • heilin - Voigt absorption profiles for the HeI series
  • lyman - Voigt absorption profiles for the HI or HeII series
  • zbabs - EUV ISM attenuation
• A new statistic, pgstat, has been added for the case of Poisson-distributed data with a Gaussian-distributed background. The whittle statistic can now be used when fitting averaged power density functions by appending an integer (so eg whittle5 is the statistic to use when fitting a pdf constructed by averaging those from 5 observations).
• The old CERN Minuit library, which is used for the migrad, minim, monte, and simplex fitting methods and the improve command, has been replaced by the new version. The minim and monte methods are no longer supported and the new version does not include an improve command. The output from the migrad and simplex fitting methods now looks the same as that from the leven method. Note however that the rules for when to write intermediate fit results are not directly comparable so do not provide a measure of the relative speed of the methods.
• fakeit now has a <nowrite> option to generate fake spectra without producing output files. This is also now available in the multifake.tcl script command.
• Parallel processing capability has been added to the steppar command and can be invoked using the parallel command.
• Markov Chain Monte Carlo (the chain command) now uses the Goodman-Weare algorithm by default. Previously the default was Metropolis-Hastings.
• After a chain run, the best-fit parameters and statistic are now displayed with chain info, and are available through the tclout chain option.
• The default AtomDB version used in apec models may now be modified with the ATOMDB_VERSION keyword in the user's Xspec.init file.
• steppar now has a <delta> option for performing grids centered on the best-fit parameters.
• The setplot delete option has been enhanced to allow removal of all or a range of commands.
• For external programs calling XSPEC, new wrapper functions have been added for retrieving XFLT keywords from data files.
• Norm parameters are now set with a default “soft” upper limit below their “hard” upper limit.
• In PyXspec, the Fit.statMethod and statTest attributes can now be set for individual spectra.

Enhancements previously released as patches to 12.8.0

• AtomDB has been upgraded to version 2.0.2.
• The tclout <stat> and <statmethod> options can now retrieve the test statistic as well as the fit statistic.
• The simftest Tcl script command now takes an optional filename argument for output.
• Attributes added to PyXspec classes: Xset.parallel, Fit.statTest.

Bug fixes

All bug fixes to v12.8.0 released as patches are included in v12.8.1. In addition the following problems have been corrected:

• The command history file xspec.hty (in the user's $\sim$/.xspec directory) is now updated when exiting XSPEC with the quit command. Previously it was only updated when exiting with exit.
• The chain command can now read/write files in ASCII format when running in the default Goodman-Weare mode. Previously this feature was only available for Metropolis-Hastings chains.
• Fix to an array access error in the nthcomp model.
• PyXspec fix removes error messages generated when accessing response parameters in Python versions 2.6.x.

v12.8.0 Dec 2012

New features

• Parallel-processing capability for specific tasks has been added by way of the new parallel command. This allows the user to set a maximum number of processes to spawn when running certain XSPEC commands. Currently the options for parallel-processing are limited to use with the fit and error and commands, though we plan to implement more in the near future. This first implementation is considered to be a BETA release, and we look forward to hearing your comments and suggestions.
• XSPEC now distinguishes between the fit statistic and the test statistic. The fit statistic is used to find the best-fit parameter values and errors while the test statistic is used to provide a goodness-of-fit. Consequently, the goodness command now uses the test statistic. Separating these two classes of statistic has allowed us to add a number of new test statistics. These include Kolmogorov-Smirnov and the related Anderson-Darling and Cramer-von Mises. Also new are the runs statistic, based on the number of runs of consecutive positive (or negative) residuals, and the Pearson Chi-Square (pchi) statistic, Pearson's original test statistic.
• The basic Levenberg-Marquardt fit algorithm has undergone a number of changes. The most visible is an additional column in the output during the fit. |beta|/N is the norm of the vector of derivatives of the statistic with respect to the parameters divided by the number of parameters. At the best fit this should be zero so provides another measure of how well the fit is converging. |beta|/N can also be used as the criterion to stop the fit instead of the statistic delta although this is still considered experimental.
• Other internal changes to the fit algorithm are to treat the first iteration as a special case where only normalizations are allowed to change and to add the option of using delayed gratification, which can speed up convergence.
• New models: compmag, comptb, rgsxsrc. The latter is reinstated from it use in XSPEC v11.
• New plotting command plot goodness, for plotting a histogram of the most recent goodness simulation.
• New tclout option <goodness sims>.
• Added the option of using the Goodman-Weare algorithm instead of Metropolis-Hastings when using the chains command to run MCMC.
• Added the Whittle statistic for fitting models to power density spectra.
• If a data file is read which has RESPFILE=”[]” then the response extensions (MATRIX, EBOUNDS) are read from the same file.
• Added support for a new type of model component: a mixing component which operates on the model pre-multiplied by the effective area. This is similar to the pile-up model type but allows for a models which require mixing between multiple spectra.
• Table model files can now have interpolated and additional parameters intermixed provided that additional parameters are indicated by METHOD=-1 in the PARAMETERS extension.

Enhancements previously released as patches to 12.7.1

• The "plot chain" has a new "thin" option for thinning the display of chain points.
• Added a "tclout ignore" option for easy retrieval of currently ignored channels. Similar capability added to PyXspec's Spectrum class.

Bug fixes

All bug fixes to v12.7.1 released as patches are included in v12.8.0. In addition the following problems have been corrected:

• The eqpair model used wrongly-sized arrays when multiple spectra were used with RMFs having varying numbers of photon energy bins. Eqpair (plus eqtherm and compth) also needed a new default value for its optical depth parameter, which fixes the problem if parameter 4 is zero.
• A fit parameter which started close to the minimum/maximum could under some circumstances be incorrectly pegged at the maximum/minimum.
• When the error command was run on a model with soft limits (ie. soft limits for some parameters set to a narrower range than hard limits), and the best fit value fell within the soft limit region, the displayed differences (in parentheses) were not consistent with the reported $\pm$ limits.
• Problem occurred in apec model when zero width lines were in the final energy bin.
• Fix to a potential normalization problem occurring in lorentz model with low-energy large-width lines.
• When running initpackage and lmod from PyXspec on certain Linux builds, local models calling functions in XSPEC's xslib library producing unresolved symbol link errors.

v12.7.1 March 2012

New features

• New models: gadem, vgadem, eplogpar, logpar, optxagn, optxagnf, and pexmon.
• The convolution models rdblur, rdblur2, kdblur and kerrconv have been sped up. They are now O(N) instead of O(N$^2$) where N is the number of energy bins in the response.
• Continued rationalization of Compton reflection routines. eqpair, eqtherm, compth, compps, ntee now all use the same routines as reflect and ireflct. For models with ionized reflector there may be changes in results because the new code uses the actual input spectrum to calculate the ionization fractions while the old code assumed a power-law.
• The parameter simulation arrays used for the calculation of eqwidth and flux error are now accessible through tclout.
• initpackage now works on Cygwin. The static_initpackage work-around is no longer needed and has been removed.
• New Fortran interface wrapper function RFLABD, for reading new abundance tables into external programs using the XSPEC models library.
• Added an xsetbl function for use in external programs. This provides access to XSPEC's internal exponential table model routines, similar to what xsatbl and xsmtbl do for additive and multiplicative table models.
• bayes command is now supported for response parameters (ie. gain).
• New show version option.
• Improved error command output messaging. The error results now have lower chatter level (5) than most of the warning messages (10), thus making it easier to filter out the warnings.
• PyXspec beta version upgraded to v1.0. See the PyXspec release notes for details.

Enhancements previously released as patches to 12.7.0

• New tclout options: <nullhyp>, <rerror>.

Bug fixes

All bug fixes to v12.7.0 released as patches a-u are included in v12.7.1. In addition the following problems have been corrected:

• Program aborted when attempting to fit with gain parameters attched to dummy responses.
• Program aborted when removing a spectrum with a response containing gain parameters, AND while that response was temporarily replaced with a dummy response.
• The save command did not add the default .xcm extension for file names that included a path.
• A crash could occur if the EBOUNDS array wasn't the right size.
• It was not possible to plot 2 or more models in a multi-panel plot model display.

v12.7.0 May 2011

New features

• The primary new feature of 12.7.0 is the addition of the Python module, PyXspec v0.9 beta. PyXspec is built and installed by default on most platforms along with the regular XSPEC build, and simply requires an import xspec statement to load into Python. XSPEC can now be run from object-oriented Python scripts, or interactively from a Python shell prompt. Detailed instructions can be found in PyXspec.pdf. While most features of standard XSPEC are already supported in this beta release, some still remain to be implemented. Please let us know if any missing feature is of particular importance to you, or if you have suggestions and ideas for improvement.
• New models:
  • cplinear: Piecewise linear non-physical background model for low-count spectra developed for Chandra by Patrick Broos.
  • eqpair, eqtherm, compth: Paolo Coppi's hybrid hot plasma emission models.
  • vvapec, bvvapec: APEC models allowing all 30 elemental abundances to vary (for use with AtomDB 2.0).
  • zigm: Multiplicative model, computes the mean attenuation of the optical/UV spectrum by the intergalactic medium.
  • zashift, zmshift: Convolution models for applying redshifts to additive and multiplicative models respectively.
• Also note that the default APEC model data files have been updated to AtomDB 2.0. This version of AtomDB includes contributions from more elements than earlier versions. When using the apec and vapec models these extra elements have Solar abundance by default. To change this use xset APEC_TRACE_ABUND.
• The statistic command may now be applied to individual spectra. This makes it possible to simultaneously fit spectra which require different fit statistics.
• Added the pgstat option to the statistic command. This is similar to using cstat with a background file except that the background is assumed to have Gaussian statistics (not Poisson) read from a STAT_ERR (and optionally SYS_ERR) column.
• Modified the pileup model for consistency with Sherpa and ISIS. A new parameter fracexpo is added which should be set to the FRACEXPO keyword value in the ARF.
• It is now possible to choose proportional or fixed fit deltas from the startup Xspec.init file. The initial default setting is now proportional deltas rather than fixed deltas.
• Improvements made to the output generated during a fit. The parameter names are listed at the top of columns, not just their numbers. Column alignment has been improved, and is no longer limited to a maximum width of 5 columns.
• Added reporting of the Bayesian contribution (if any) to the fit statistic output.

Enhancements previously released as patches to 12.6.0

• Initpackage now recognizes and builds files with .f03 extensions for Fortran 2003, and .f90 extensions for Fortran 90.
• Added a new fakeit option for setting the fake background exposure time.
• Added a new tclout version option for returning the XSPEC version string.
• Improved XSPEC's internal update mechanism to reduce the number of model calculations.

Bug fixes

All bug fixes to v12.6.0 released as patches a - ab are included in v12.7.0. In addition the following problems have been corrected:

• A crash occurred if tclout notice energies was performed on a spectrum containing only a dummy response with no channels.
• The 5 redundant xset options (those which merely duplicate other existing XSPEC commands) weren't passing their arguments to the command handlers correctly.
• Fit error messages were misleading for the case where the data was missing a suitable response, or when the only existing models were inactive.
• A fatal error could occur in fakeit when attempting to generate a background file while only a dummy was used for the response.
• The bayes command handler was not properly handling the case where the prior type option string was abbreviated.
• A crash occurred when flux was run in error mode and the specified energy was entirely outside the range of one or more spectra.

v12.6.0 March 2010

New features

• The main improvements in version 12.6.0 are to XSPEC's plotting capabilities:
  • Multi-panel plotting is now supported for all combinations except contour plots. For example, plot data model resid ratio will produce a 4-panel plot on a single page. Up to 6 panels can be plotted in this manner.
  • There are many choices for axis units. These can be selected using the setplot energy and setplot wave commands. For example, setplot energy GeV uses GeV on the x- and y-axes. setplot wave also has a new perhz option for displaying the Y-axis in 1/Hz units.
  • The setplot command has a new redshift <z> option for shifting displayed energies to the source frame.
• New models: ireflect is a convolution model based on the pexriv code. sirf is a multiblackbody self-irradiated funnel
• The normalizations on all power-law models (ie. powerlaw, bknpow, bkn2pow, cutoffpl)can be changed to a flux over an energy range by setting POW_EMIN and POW_EMAX keywords in xset. The powerlaw model then becomes equivalent to the pegpwlw model.
• The Compton reflection models (b/p)exr(a/i)v and (i)reflect have been restructured to use adaptive Gauss-Kronrod quadrature for the Greens' function integrals. The precision to which the integrals are calculated can be set allowing a trade-off between speed and precision.
• The wrapper functions additiveTable and multiplicativeTable give external C++ models access to XSPEC's table model interpolation routines (equivalent to the xsatbl and xsmtbl functions for Fortran models).
• The display of link expressions has been simplified to show only the parameter numbers and not the extraneous component information. Also show model will now only display the model components and not the individual parameters. The parameters can be seen with show parameters.

Additional enhancements previously released as patches to 12.5.1

• Added the solar abundance data set of Asplund, Grevesse, and Sauval (2006) to the list of available tables accessed with the abund command.
• New tclout nchan option for returning the number of channels in a spectrum. The save command now stores relative rather than absolute paths to allow easier porting to other machines.
• The recorn model component has been converted from a mixing to a multiplicative type. This allows a model to define multiple recorn components.
• A warning message is now issued if a user attempts to load a response for a source n when there are still slots to fill for source n-1. This is intended to catch cases where a user mistakenly reverses the source and spectrum number input to the response command.

Bug fixes

All bug fixes to v12.5.1 released as patches a - o are included in v12.6.0. In addition the following problems have been corrected:

• It was possible for the addition of a systematic model error to actually decrease the overall variance, when it was applied to a zero-variance bin that was artificially increased by XSPEC for chi-square fitting.
• Bug in plot ratio when using setplot wave with Hz units. Y-axis model values $\langle 10^{-20}$ were not displayed in plot.
• The comptt model no longer stops and prompts the user when it fails during its incomplete gamma calculation.
• The powerlaw model has been modified to avoid a numerical instability that could occur if the index were within $10^{-12}$ to $10^{-15}$ of 1.0.

v12.5.1 Aug. 2009

New features

• Gain parameters can now be used in the error, freeze, newpar, thaw, and untie commands by prefixing the command name with the letter “r” (for “response parameter”, the more general category to which gain parameters belong). steppar can now also handle gain parameters. Gain parameters can be displayed either with show parameters or the new show rparameters option.
• The gain command syntax has changed when using multiple sources. To better conform with the rest of XSPEC, it now requires <source number>:<spectrum number> rather than the reverse.
• Gain parameter limit values can be stored in response files, using the keywords GSLOP_MIN, GSLOP_MAX, GOFFS_MIN, and GOFFS_MAX.
• All input and output data filenames can now include CFITSIO/FTOOLS extended-syntax for specifying particular HDUs. As a result, XSPEC can now handle files which contain spectra, ARFs and RMFs in multiple extensions.
• Partial derivative calculations during fitting can now be performed numerically rather than with an approximated analytical expression. This option is chosen in the Xspec.init initialization file.
• If a new minimum is found during a steppar run, steppar now prompts the user for acceptance of the new values. Also the delta statistic column of a steppar run is now obtainable with the tclout steppar delstat option.
• The output warning message has been improved in the case where Levenberg-Marquardt fitting runs into a zero diagonal element in the second derivative matrix. Similarly, the more frequent pegged-parameter messages (due to running into hard limits) is now output at higher chatter levels only.
• All calls to the xanlib dynamic memory allocation function udmget have been removed from the Fortran models in XSPEC's models library. The relevant code has been converted to C++. If a user's local models library still requires the udmget code, they'll need to run initpackage with the new -udmget option.

Additional enhancements previously released as patches to 12.5.0

• Setplot wave x-axis units can be toggled from Hz to angstroms through WAVE_PLOT_UNITS entry in Xspec.init file.
• New tclout gain and tclout sigma options.
• New xs_getVersion function available for those linking their own programs to the XSPEC models library.
• The show parameters option can now take a range of parameters for displaying subsets.

Bug fixes

All bug fixes to v12.5.0 released as patches a - an are included in v12.5.1. In addition the following problems have been corrected.

• After running the arf command, any gain previously applied to the associated RMF will be removed. Previously it was erroneously applying the gain to the new ARF.
• Additional header file inclusions needed in code files to compile with g++-4.4.0
• Extra line-feed characters removed from Ascii text files in the modelData directory. These were causing problems on Solaris 10 w/f90.
• The nthcomp model's internal arrays were hardcoded to a maximum size of 5000 energy bins. The size is now dynamically allocated. (This also affects the diskir model.)
• A Levenberg-Marquardt fit now immediately stops if the fit statistic becomes NaN due to an erroneous model calculation.
• C++-style comments have been removed from xsFortran.h for the benefit of users compiling their own C programs with the models library.
• Plotting fix for case where setplot area is selected and no models are currently loaded.
• Model parsing fix for case of nested parentheses with no '+' operator, ie. A(B(C*D)).