Build and Install PyXspec

Requirements

Since we do not distribute Python with the HEASOFT packages, you'll need to have it already installed on your system (which it is with most Linux and Mac OSX distributions). PyXspec is compatible with Python 3.x. The python executable must be in your path, and with the library and header files located in the standard directories relative to the executable (see the Troubleshooting section for more info).

Building/Installing

PyXspec is fully integrated into the general HEASOFT build procedure, as described at http://heasarc.gsfc.nasa.gov/lheasoft/install.html . So it will be built and installed automatically with the rest of XSPEC/HEASOFT, requiring no additional effort from the user.

By default, the HEASOFT configure/build process will first search for python3 versions on your system, and only if it finds none will it then search for python. You can override this behavior by setting your PYTHON environment variable to the full path to your desired python executable before running the HEASOFT configure. You can also switch between python distributions after your original build. Please see Changing Python Versions After Original Build for details.

Once HEASOFT is finished building and installing, you should find PyXspec's code files and lib_pyXspec.so library in the directory $HEADAS/lib/python/xspec.

When you run the HEASOFT initialization script ($HEADAS/headas-init.csh or .sh), it will add $HEADAS/lib/python to your PYTHONPATH environment. This allows Python find the PyXspec module so that you may load it into your session from anywhere, using the import xspec statement.

Changing Python Versions After Original Build

If you wish to change the Python version from which PyXspec was built during the original HEASOFT configure/build, you can do so by manually editing the file: heasoft-<ver>/Xspec/BUILD_DIR/hmakerc. This file contains definitions for the 2 variables: PYTHON_INC and PYTHON_LIB, which set the compiler paths for the Python header file inclusion and dynamic library linkage, and these must be changed to point to your new Python location.

For example, to point to an Anaconda Python3 distribution on your system, your new settings might look something like:

PYTHON_INC="-I/path/to/your/anaconda3/include/python3.8m"
PYTHON_LIB="-L/path/to/your/anaconda3/lib -lpython3.8m"

Note

You can determine the Python path information with the python-config (or python3-config) utility. Call it with the --cflags option for the include path information, and with --ldflags for the library path information.

After making these edits, simply rebuild PyXspec by doing:

cd /path/to/heasoft-<ver>/Xspec/src/XSUser/Python/xspec
hmake clean
hmake
hmake install

cd ../mxspec
hmake clean
hmake
hmake install

Running on Mac OS

These issues apply only to Mac OS users. Linux users may skip this section.

As seen on the HEASOFT builds page for Mac OS https://heasarc.gsfc.nasa.gov/lheasoft/macos.html, one can build HEASOFT using XCode compilers (clang,clang++) for C/C++, with a 3rd party compiler (MacPorts, Homebrew) for Fortran. Or one can use the 3rd party package for all three C/C++/Fortran. We recommend building HEASOFT (and therefore PyXspec) using a Python distribution that matches your C/C++ compilers, ie. XCode in the first case and a Python from MacPorts or Homebrew in the second case.

It is also possible to succesfully build and run PyXspec from an Anaconda python distribution.

Troubleshooting

If the HEASOFT configuration stage fails when it's processing PyXspec, it will just issue a warning and continue. Its failure should not affect the rest of the XSPEC and HEASOFT build. Standard XSPEC will still be fully functional, but its Python interface won't be available.

The most likely cause of a PyXspec build failure is that the HEASOFT configuration script can't find a python executable and/or its accompanying library and header files. You should first check that the command "which python" can find an executable on your path (python is generally a symbolic link to a version-specific executable).

If you don't explicitly set the PYTHON environment variable, the configuration script first looks for python3 versions followed by python. Once it's found an executable, it looks for the files Python.h and libpython[m.n].so (or .dylib) with the help of the python-config (or python3-config) utility. The configuration fails if it is unable to find either file.

If you are manually trying to reset the PYTHON_INC and PYTHON_LIB variables (in heasoft-<ver>/Xspec/BUILD_DIR/hmakerc) to point to these files in a different Python distribution (for instance if switching between Python 2 and 3, or to a 3rd-party Python distribution installed on your system), we recommend using the python[3]-config utility to help you determine the correct path information.

Other Errors

If you are running on Mac OS X and get a Python "ImportError" message containing such statements as no suitable image found and mach-o, but wrong architecture, it's likely you are trying to run a 32-bit mode Python while your default HEASoft build is now 64-bit.

If you are running on a Mac and have built your HEASOFT installation with all 3 compilers (gcc, g++, gfortran) coming from Homebrew or MacPorts, AND you get a runtime error that begins with something like:

python(86419) malloc: *** error for object 0x574b160: pointer being
                          freed was not allocated

then it likely means there's a conflict between your default Python distribution and the compiler libraries used to build PyXspec. Please see the Changing Python Versions After Original Build section above for switching away from the default Xcode Python distribution.