XSPEC 12.5.1 release notes Aug. 2009 ___________________ New features in v12.5.1 - 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 parameter" or the new "show rparameter" option. - The gain command syntax has changed when using multiple sources. To better conform with the rest of XSPEC, it now requires : 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 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. - 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)). XSPEC 12.5.0 release notes Nov. 2008 ------------------- *** IMPORTANT IMPORTANT IMPORTANT *** Please note that this is the last distribution of HEAsoft in which we intend to include xspec v11. It is becoming increasingly hard to keep v11 up-to-date for new compilers and we do not have the resources to support two different versions. If there are v11 features that you are using and that we have omitted in the current version please let us know as soon as possible. *** IMPORTANT IMPORTANT IMPORTANT *** New features in v12.5.0. - Two of the remaining unimplemented v11 commands have now been added. * mdefine allows dynamic definition of models that can be expressed algebraicly. * recornrm has been replaced by the recorn model. This allows the correction norm to be treated as a fit parameter, a better solution than the v11 recornrm command. - The complete HTML help files are included in a tar file. These can be made available on a local machine if remote access is not available and selected in the Xspec.init file. - Convolution components can now operate on multiplicative components. For example, in the model = (CM)A, the convolution component acts on only the multiplicative component. Previously this would have been treated the same as C(MA). The partcov partial convolution model takes advantage of this new capability. - There is a new simple way of estimating fluxes (and their errors) from parts of the model. Apply the cflux convolution model to the component(s) for which the flux is required. - The following models have been added as standard * diskir : irradiated disk * kerrdisk : broad iron line from a disk around a Kerr BH * nsmax : NS magnetic atmosphere * nthcomp : thermally Comptonized continuum * spexpcut : super-exponential cut-off * swind1 : partially ionized absorbing material with velocity shear * zxipcf : partial covering of partially ionized absorbing material * cflux : calculate the flux from model component(s) * kerrconv : broadening due to rotation around a Kerr BH * partcov : partial covering modifier for absorption models * simpl : Comptonization of a seed spectrum * recorn : Vary the correction file normalization - The lrt.tcl and simftest.tcl scripts perform the likelihood ratio and F-tests, respectively. - The writeFITS.tcl script writes filenames and current fit parameters and errors to a single row of a FITS file. This script can be used as a template for saving other information. - A response of "/*" to a "y/n" prompt will jump out of the current operation and return to the XSPEC command prompt. This is particularly useful for escaping nested fits during an error command run. - The units have been changed for setplot wave plots. model and ufspec have a y-axis in photons/cm^2/s/Hz, emodel and eufspec in Jy (10^-23 erg/cm^2/s/Hz), eemodel and eeufspec in erg/cm^2/s. - Fakeit can now work with multiple-extension response files. It also works correctly when multiple models are in use (this was released in patch v12.4.0r). - The active|inactive|options can be applied to the default (unnamed) model (released in patch v12.4.0v). - Support for GLAST GBM extensions to the standard file formats including multiple response matrix extensions in the same file (released in patch 12.4.0am). - There are additional diagnostics available at high chatter levels from MCMC chain runs. User's custom proposal classes have access to information about acceptances and rejections. - Initial support for multicore processors using the OpenMP parallel processing compiler option. Multiplication of the model and response is performed in parallel across the multiple spectra in a datagroup. All bug fixes to v12.4.0 released as patches a - ar are included in v12.5.0. In addition the following problems have been corrected. - When a runtime error is encountered during the calculation of a parameter's error bounds (using the error command), the value is now filled in with 0.0 rather than retaining its previous value. - Steppar will now correctly step in reverse direction if the range values were entered in high-to-low order. - Model expression parsing has been improved for nested expressions. - Log file output has been fixed so '#' comments are placed correctly. - The chi-square calculation includes the corfile contribution even if there is no background file associated with the spectrum. - There are minor plotting fixes to the confidence line in 1-D steppar/margin plots, the rescaling of the Y=0 green line in lower-panel plots, and the Y-axis label in plot delchi. - Tclout peakrsid no longer fails for a spectrum whose model was not assigned to source 1. Other Changes: - The XSFunctions library now also depends on XSModel, requiring the addition of a -lXSModel flag to the Makefile of external programs linking with the XSPEC model functions library. (See manual Appendix F) - The modelIonData model data files directory has been renamed to modelData. - Portions of some model functions have been translated from Fortran to C++ to reduce use of the udmget memory allocation function. New for XSPEC version 12.4.0 12/07 Version 12.4.0 incorporates all of the fixes and enhancements that were originally distributed as patches (a-ap) for v12.3.1 (see the XSPEC final issues/patches page for 12.3.1 for details). It also contains the following improvements: Monte Carlo Markov Chain The MCMC code run by the chain command has been greatly expanded with many new options. - The default output format is FITS (with an option to use the old ASCII text file). - Proposal distributions can now be defined in a variety of ways and new proposal classes can be loaded dynamically. - A temperature option enables annealed chains. - The error, flux error, lum error, and eqwidth error commands all use information from chains if they are loaded. This should make these commands more reliable. - New tclout options chain and margin provide access to chain information. - plot mcmc has been renamed plot chain. - The tclout covar option previously output the values in order of the upper half of the covariance matrix. This has been changed to the lower half matrix order so that it may be directly input into the new "chain proposal matrix" command. - The chain stat option now assumes to be an XSPEC parameter index, of the usual form [:]. Previously it was treating this as a number indicating the column position in the chain file. Fitting - The xset delta command sets parameter fit delta values proportional to the parameter values. This should eliminate the problem that the fit delta can end up too large relative to the parameter value leading to convergence problems. - The method command has new options minim, simplex, and monte from the Minuit lbrary. A new command improve can be used with the Minuit methods to test for local minima. Models - The projct mix model can now run on a subset of the loaded spectra. Previously it expected all loaded spectra to have XFLT keywords even if they were not intended to take part in the mixing. - Very large table models are no longer loaded in their entirety into RAM, but instead accessed by deferred read from disk. - There is a new (experimental) cyclical designation for those parameters which are periodic (for instance inclination angles) - The XSPEC v11 rgsxsrc model (which was missing in XSPEC 12), is now implemented with the new ftool rgsrmfsmooth. This applies the correction to the XMM RGS response for an extended source, removing the need to have the model inside XSPEC. Other - XSPEC recognises the home directory path '~/' notation when running scripts (using the '@' method), - Initpackage can take relative paths for its 3rd argument. Also, initpackage will append the prefix "lpack_" to the C++ library init file it produces. This should eliminate name conflicts with local model files. - Fakeit output has channel columns with type J rather than I. - Doing "xset " with no value argument now removes from the string database rather than leaving it in with an empty value. Fixes: - Plot sensitivity/insensitivity was crashing when used on spectra with ignored channels. - Fix made to table model's out-of-range and exactness testing for cases of negative value parameters. - Editmod was not recognizing blank spaces as separators between multiple values entered for a parameter in a script. It was only allowing commas to be separators. - Some cases of editmod on multiple-nested models were being prevented due to incorrectly identifying the operation as attempting to change more than one component. - In the data command, entering the invalid 0:0 for : was causing a segmentation fault. - Specific only to Mac Leopard with fink-installed gcc-4.2.1: the data group number was improperly read in from the data command's : syntax. New for version 12.3.1 02/07 Version 12.3.1 incorporates all of the bug fixes that were originally distributed as patches (a-am) for v12.3.0 (see the Xspec final issues/patches page for 12.3.0 for details). It also incorporates the following enhancements, also originally released as 12.3.0 patches: - "extend" option added to the energies command to reproduce the behavior of the old extend command in v11. - New "plot background" command to plot isolated background files (with folded models if they exist). New "setplot background" option for plotting the background in addition to the source spectra during a "plot data" command. - New tclout options: statmethod, weight, noticed, and noticed energy. - New Fortran-callable wrapper functions equivalent to v11's xsatbl and xsmtbl routines. This allows users writing local models in Fortran to access xspec12's table model interpolation functionality, and is required in order to use the swind1 model which was recently added to the "Additional Models" page. - Calculation efficiency improvement when fitting table models. New enhancements and fixes NOT previously released as patches: - Now compiles with gfortran. - All plots now receive the PLT "SCR WHITE" command, which makes the default plot background white instead of black. - Fixed data and fakeit command handling of cases where the user includes an absolute path with the file name. - Fixed possible memory access error for Fortran model functions calling the FGMSTR wrapper function. - Bug fix to projct mix component for case where par1 and/or par2 (major and minor axes of inner-most ellipse) change from zero to non-zero. - Modified behavior of tclout options: modcomp and modpar no longer throw an error when they can't find model, but just return 0. param no longer returns sigma as a seventh value. New for version 12.3.0 07/06 Version 12.3.0 incorporates the fixes and enhancements from all of the patch files (a-ap) for v12.2.1, in addition to the following key changes: Enhancements and Modifications: -- Full support for models with multiple responses (previously only available for Integral/SPI data formats). This replaces and enhances the v11 technique of specifying '/b' for background models. -- New command "energies." This is a more general and flexible replacement to the "extend" command of v11. -- 6 new models added to the standard XSPEC models library. Additive: diskpbb, laor2, nsatmos Convolution: kdblur, kdblur2, rdblur -- First-time support of XSPEC12 on Windows platform via Cygwin (except for initpackage and lmod commands for loading model libraries, see manual). -- First-time support on Intel Mac platform. -- New "show" command option, "show plot", displays all current "setplot" settings. -- New handling of zero variance during chi-square fits. Previously a minimum variance was ALWAYS applied to zero-variance channels for any type of fitting. Now it is only applied for chi-square fitting. -- Gaussian randomization is now applied in "fakeit" for non-Poisson type spectra. Previously Poisson randomization was applied in all cases. -- Enhancements to output of "tclout" flux and lumin options. Fixes: -- The "weight" command's model weighting option is now working. -- The STAMP option for the "log" command is now implemented for the first time in v12. -- During C-statistic fitting, the Poisson data warning is now issued only when the data are not Poisson. -- Fix to "undo" command for partial data removals. -- Fix to variance calculation for case where Poisson errors are selected and data (source and/or background) is given in RATES. -- For (e)emodel and (e)eufspec in setplot wave mode, the "e" multiplier is now in energy units, not wavelengths. -- A new implementation of model command parser should fix various parsing problems that arose with certain complicated model expressions. -- No longer using a start-up xspec script file to launch executable. This had been causing problems on Linux with the ctrl-z suspend mechanism. New for version 12.2.1 11/05 Version 12.2.1 incorporates the fixes and enhancements from all of the patch files (a-ck) for v12.2.0, in addition to the following key changes: Fixes: -- The Mac OS X Tiger build difficulties that had been causing runtime crashes have now been solved. XSPEC libraries that were built as shared on other platforms are now also shared on OS X Tiger. -- OS X Tiger users should now also be able to dynamically load their Fortran local model libraries, even if they share the XSFunctions COMMON block. Enhancements and Modifications: -- Runtime HELP can now be accessed ONLINE in html format, rather than just with the distributed PDF documents. The selection for this is made in the new Xspec.init file. -- Users can manually re-seed XSPEC's pseudo random number generator at any point in the program using the new "xset seed" command option. The default initial seed is taken from the time at program start-up. -- Uses new global_customize.tcl file (in Xspec/src/scripts) for storing customized start-up commands that are to be run for all system-wide users. Previously these commands had to be appended to the bottom of the xspec.tcl file, and hence had to be re-applied if xspec.tcl was ever patched. -- Model and model-related plots (ufspec and its variants) now always default to logarithmic scaling for both axes. -- New model components added, additive: nsagrav, multiplicative: zdust and zsmdust. New for version 12.2.0 4/11/05 Version 12.2.0 is the first official release of Xspec12, the redesigned and rewritten (from Fortran to C++) version of Xspec. This entry only documents the differences between v12.2.0 and the most recent (and final) beta version, v12.1.2. For documentation on the differences between v11 and v12, please see the HEASOFT release notes and the Xspec12 manual. All of the patches (a-h) for v12.1.2 have been incorporated into the new release. Documentation: -- Manual updated to include several new models, and descriptions of commands that were implemented since the beta release (see Enhnancements). Other minor changes/fixes/typo corrections also made. Enhancements: -- Covariance matrix now displayed at the end of successful fit. Covariance values are now also accessible through tclout. -- Added an 'undo' command. -- New plotting option: 'setplot area' -- Added 'tclout simpars' The following existed in Xspec v11.3x but were never implemented in the Xspec 12 alpha and beta test versions: -- Implemented 'chain' and 'margin' commands for generating Monte Carlo Markov chains. Also added related plot commands, 'plot mcmc' and 'plot margin'. -- 'bayes' command implemented to set up Bayesian inference. Relating to this, also implemented 'lstat' stat method option. Fixes: -- Numerous fixes to 'fakeit' command: It previously was not able to simulate data for 2 separate model sources. It now prompts in same order as v11 for all cases to provide backwards compatibility. As with v11, if original data had Poisson errors then so will faked data. -- Removed array out-of-bounds accesses that occurred in some quality and grouping settings. -- Removed artificial limit that was preventing files from loading which had more than 1023 consecutive channels with the same grouping or quality value. -- Removed bug that prevented accessing local models with names specified in upper-case letters. -- Bug fixes made to 'initpackage': Was wrongly interpreting all fortran model function names beginning with cap letters to mean double-precision. Only those beginning with 'F_' are now treated as double-precision. Fixed model.dat parsing problem when part of parameter name strings happen to match a component type name. Initpackage now copies xspec.inc file to user's local mod directory if it doesn't already find it there. -- Bug fixes made to execscript.cxx dealing with some cases of failing during input of multi-line xspec commands from script files. -- Fixed 'error' command when using 'migrad' fit method. -- 'xsect' command was causing xautosav scripts to stop processing. -- 'tclout peakrsid' was not dividing by proper effective area for calculating strengths of the max/min residuals. -- Removed 'goodness' seg-fault when run before valid fit is run. -- Removed 'flux' command requirement that 1 spectrum must be loaded. -- Plot ufspec now matches results in v11. -- Removed restriction that prevented linking of parameter to another param within the same model during the initialization stage of the model. -- Obscure comma counting problems in 'data' command fixed. -- During program exit, responses were deleted prior to being accessed during spectral data cleanup. This was causing seg-fault on Mac. -- 'backgrnd' command now adds ".pha" rather than ".bck" to filenames without a suffix. -- 'editmod' now prompts for param values when new component is added. Screen output is also cleaned up. -- 'help' command now properly handles case where partial name of command is given, previously was requiring entire name to be entered. -- 'eqwidth' was giving wrong values for the error bounds, fit parameters needed to be reset for each randomization. -- To make things easier for those not entering 'acroread' as their PDF viewer in the Xspec.init file, code no longer automatically appends window title to the user's entry. Instead, it only does this if it detects presence of "tempFileTitle" flag in user's entry. -- When 'error' command finds a new minimum, it now resets fit and prompts user for restart. Previously it would just exit. -- Fixed 'setplot device /xw' which was creating a file rather than opening a window. -- When running a script, commands are now echoed to screen. Previously they were only echoed to log file. -- Error messages are now sent to log file and not just the screen. -- More specific information is now given for RMFs that fail to load. -- Fixed bug in Xspec's custom pgplot postscript driver that was causing seg-faults when 'cpd' file command was repeatedly issued in a session.