Date: June 9, 2016.

This document is available in PDF format

The package can be downloaded at the url

This cookbook describes the procedure to install the BW (Becker & Wolff) model, whose application details are reported in C. Ferrigno, P. A. Becker, A. Segreto, T. Mineo & A. Santangelo, Study of the accreting pulsar 4U 0115+63 using a bulk and thermal Comptonization model, 2009, A&A, 498, 825. The original model is described in P. A. Becker & M. Wolff Thermal and Bulk Comptonization in Accretion-powered X-Ray Pulsars 2007, ApJ 654, 435B.

1. System requirements

In order to run BW, it is required to have:

2. Compiling and installing the BW model

To compile the BW model, you must first choose the directory in which you want to put the source code of the model and the model description file (model_bw.dat). Let us call this directory, e.g., /home/username/BW. IMPORTANT: you must have write permissions to the directory, as the local model library file and some additional object files will be produced there.

The model needs the linking of GSL libraries. This can be achieved for the full Xspec installation by following the instructions at the section “Third-Party Libraries In Local Models Build” at the page

After these instructions, it should be possible to compile and use the model in a standard way. To compile the model:

  1. cd /home/username/BW
  2. wget ""
  3. tar xfz bwmod_dist.tgz; rm bwmod_dist.tgz
  4. mv model_bw.dat model.dat
  5. Run xspec from shell
  6. From the XSPEC prompt, type:
    1. XSPEC12>initpackage bwmod lmodel.dat /home/username/BW
    2. XSPEC12>lmod bwmod /home/username/BW

If the compilation works successfully, you should find the shared library file in the directory /home/username/BW. Remember, however, that even if the compilation of the model worked successfully, you have to reload the model library every time you run xspec. In order to avoid that, go into $HOME/.xspec directory, which is automatically created for each user at first xspec running, edit (or newly create if it does not exist) the file xspec.rc, and add the line lmod bwmod /home/username/BW.

It is also worth pointing out that when you run xspec in batch mode, reading of the $HOME/.xspec/xspec.rc file is skipped. Thus if for example you want to load some spectra and the best-fit model (with BW) you cannot just give the command
> xspec - data.xcm model.xcm
but rather the following command
> xspec - load_bwmod.xcm data.xcm model.xcm
where the file load_bwmod.xcm, as xspec.rc, contains the line lmod compmag /home/username/BW.

2.1. No GSL support in Xspec.

If you did not recompile XSPEC with support for the GSL, you should edit the Makefile of the local model directory.

  1. cd /home/username/BW
  2. wget ""
  3. tar xfz bwmod_dist.tgz; rm bwmod_dist.tgz
  4. mv model_bw.dat model.dat
  5. initpackage bwmod model.dat /home/username/BW
  6. Issue the commands
    1. gsl-config --cflags (The output is, e.g., -I/opt/local/include)
    2. gsl-config --libs (The output is, e.g., -L/opt/local/lib -lgsl -lgslcblas -lm)
  7. Edit the Makefile
    1. Add the output of 6a to the variable HD_CFLAGS (not necessary for standard include locations)
    2. Add the output of 6b to the variable HD_SHLIB_LIBS.
  8. Type hmake
  9. Run xspec from shell
  10. From the XSPEC prompt, type:
  11. XSPEC12> lmod bwmod /home/username/BW

3. Usage guidelines

The BW model has a large set of parameters and not all of them can be constrained in the fit. These parameters are in Table 1.

Table 1: Model parameters.

RNS Neutron star radius in km (to be fixed)
MNS Neutron star mass in M (to be fixed)
ξ a parameter linked to the photon escape time (order of some unities)
δ the ratio between bulk and thermal Comptonization importances
B magnetic field in units of 1012 Gauss
Mass accretion rate in units of 1017gs-1
Te Electron temperature in units of keV
r0 column radius in units of m
D source distance in units of kpc (to be fixed)
BBnorm Normalization of the Black body seed photon component (fix it to zero at first)
CYCnormNormalization of the Cyclotron emission seed photon component (fix it to one)
FFnorm Normalization of the Breemstrahlung emission seed photon component (fix it to one)

We suggest here a procedure to use the model. It is mandatory to:

  1. freeze the model normalization to one;
  2. set the source distance in kpc;
  3. set and freeze the neutron star parameters (default values are a good choice).
  4. select which source terms should be computed.

The computation of the black-body source term is time consuming, because it involves the numerical solution of an integral. Since the contribution of this component is generally negligible, we strongly suggest to set the parameter BBnorm to zero and then to fix it to one for the final runs. The parameters FFnorm and CYCnorm should be fixed to one.1

The mass accretion rate is strongly degenerate with the accretion column radius and the parameter ξ: it is therefore advisable to fix to a suitable value, which can be derived by equaling the X-ray luminosity to the accretion luminosity. For source in which the magnetic field is well above the plasma temperature and the contribution by the cyclotron emission term is minor, it is suggested to link the magnetic filed of the continuum model to the one derived by the cyclotron scattering absorption feature(s).

For particular combinations of the parameters ξ and δ, the special functions used in the GSL libraries do not converge and an error is issued. For examples if δ is very low and ξ very high, or vice-versa. The model returns NAN values to XSPEC in these cases and a message is prompted, but the program is not exited. We noticed that this happened mostly for large values of r0. It is therefore important to limit the parameter ranges in a customary way and maybe tune the mass accretion rate to a value which keeps these parameters in the range suggested by physical considerations. We notice that equaling the accretion and the X-ray luminosities is not granted to yield meaningful results for all sources.


For any problem and suggestions, please contact
Carlo Ferrigno email: