Installation¶
If you are in a rush, and to make a long story short, as of version 29.2.0 ixpeobbsim is hosted on PyPI and you can install it via pip
pip install ixpeobssim --user
This should install all the necessary dependences and work out of the box
(we recommend using the --user
option not to pollute everybody else’s
environment on the host machine, but you’re definitely free to opt for
a system-wide installation by simply omitting this specific option).
Warning
ixpeobssim includes NumPy as a binary dependence, and it is generally not recommended to install Numpy from pip. Should you encounter problems with the Numpy installation, you might consider to use a science-ready version of Python that comes with NumPy (and the associated Python scientific ecosystem) built-in, like the Anaconda distribution.
That said, most of the remaining of this section is left to the reader for historical reasons, and in the hope it will be useful to debug installation problems, should any arise.
Prerequisites¶
The package is based on the Python scripting language and the SciPy Python-based ecosystem. You will need a working Python installation including several different third-party packages, most notably:
NumPy: the fundamental package for scientific computing with Python.
SciPy: a Python-based ecosystem of open-source scientific software.
matplotlib: a Python 2D plotting library.
Astropy: a Python astronomy package (including tools to manipulate FITS files).
regions: an Astropy affiliated package for handling region (including ds9 region files).
skyfield: a package computing positions for stars, planets and satellites.
PyXspec: the Python binding for XSPEC (optional).
Loosely speaking you should be able to open the Python terminal and execute the
following import
statements with no errors.
>>> import numpy
>>> import scipy
>>> import matplotlib
>>> import astropy
>>> import regions
>>> import skyfield
If any of the required packages fails to import, take a deep breath and fix the issue before you move on.
Dependencies in depth¶
Warning
ixpeobbsim as a project started in late 2015 when requiring users to install Python 3 was more a political decision that anything else. Over the years, it has evolved along with the Python ecosystem and the Python language itself.
Although we have not deliberately taken any action to break backward compatibility with older versions of the dependencies (and in fact, you might very well find that ixpeobbsim is still working with Python 2), you are strongly encouraged to make sure that your setup matches the indications in this section, as new features will not be tested against older environments.
We recommend installing Python 3.6 or later. In case you missed it, the Python 2x series reached the end of life on January 1, 2020, which means that no new bug reports, fixes, or changes will be made to Python 2, and Python 2 is no longer supported. If you are still using it, you should definitely consider upgrading to Python 3 for your projects.
As far as the dependencies are concerned, our requirement specification reads:
numpy>=1.17
scipy>=1.4
matplotlib>=3.0
astropy>=4.0
regions>=0.4
skyfield>=1.23
You can easily find out which version of any specific package you are using through the interactive Python interpreter, e.g.:
[lbaldini@nblbaldini ixpeobssim]$ python
Python 3.8.3 (default, May 15 2020, 00:00:00)
[GCC 10.1.1 20200507 (Red Hat 10.1.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>> numpy.__version__
'1.18.4'
>>>
In addition, there is a unit test in the test folder (test/test_environment.py
)
that you can run to diagnose your environment.
Installing Python through Anaconda¶
Tip
Making a long story short: we encourage people to use Python 3 and install Python and the associated ecosystem through Anaconda. If you know what you are doing you can find your way through the framework through alternative ways (e.g., the Python installation provided by your GNU/Linux distribution) feel free to do so, but we do recommend Anaconda as a decent, platform-independent Python experience.
You can download the installer for your os from the download page (make sure you pick the Python 3 branch) and follow the installation instructions.
In a nutshell, Anaconda will create on your hard drive a self-contained
directory structure with the Python executable and associated goodies, and all
you have to do to use it is to prepend the folder containing the Python
executable itself to your PATH
environmental variable. The installer is
pretty simple in that it comes in the form of a single bash script (under
GNU/Linux and Mac) or a self-extracting installer (under Windows) that you
execute and does everything for you—just follow the instructions.
It is your responsibility to have the proper environment set up for Anaconda
Python. As mentioned in the previous paragraph, this simply boils down to have
the PATH
environmental variable pointing to the folder containing the
Python executable, which is
the
bin
folder in the Anaconda installation folder under GNU/Linux and Mac;the top-level Anaconda installation folder under Windows.
Once you have correctly done that, you should be able to launch Python from the shell or the command prompt and see something in response along these lines:
[lbaldini@nblbaldini doc]$ python
Python 3.6.4 |Anaconda, Inc.| (default, Jan 16 2018, 18:10:19)
[GCC 7.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
Installing the Python dependencies¶
The default Anaconda installer comes with most of the Python scientific ecosystem that you need (i.e., numpy, scipy, matplotlib and astropy among many other packages).
For the missing bits, Anaconda comes with the pip
utility that allows you
to install them in a matter of seconds (with the exception of the Python
bindings for Xspec, see the following section). If you’re starting from a fresh
installation you will typically need to do
pip install regions --user
pip install skyfield --user
and you should be all set.
Warning
If you have an error when trying and install regions, you might want to try and do
pip install wheel --user
(There are more extensive resources on the web about this very issue, including this)
Under Windows, depending on your installation, you might come across the infamous
error: Unable to find vcvarsall.bat
while installing regions or skyfield. This is essentially because pip is trying to compile part of the library, and you can find all the gory details of the issue here. In a nutshell, assuming that you are using Python 3.5 or later, you will need to install the Visual C++ Build Tools 2015.
Installing the Xspec Python bindings¶
This is an interesting corner of the pre-requisite installation, as PyXspec is used in some of the ixpeobssim analysis-related modules, and it is not readily available through Anaconda.
Note
Getting PyXspec up and running might prove less than trivial depending on your OS and the details of your installation. It is important to point out that you can get away through the vast majority of the ixpeobssim functionalities without PyXspec, and if you have Xspec installed you might use that netively after all.
If, on the other end, you are interested in making full use of the ixpeobbsim analysis pipelines, detailed instructions about how get the Xspec Python bindings up and running follow.
At any time you can check whether you have PyXspec up and running on your ixpeobssim installation by doing something along the lines of
>>> from ixpeobssim.utils.environment import PYXSPEC_INSTALLED
>>> if PYXSPEC_INSTALLED:
>>> import ixpeobssim.evt.xspec_ as xspec_
Please keep in mind to protect the PyXspec-related sections of your code with a similar guard in order not to break everything for the users who do not have PyXspec installed.
The PyXspec Python bindings for Xspec are fully integrated into the general HEASOFT build procedure and they will be built and installed automatically with the rest of XSPEC/HEASOFT. Note that the source code distribution of XSPEC is required for using PyXspec. What you want to do is to go to the HEASOFT download page and:
select the source code distribution software type (STEP 1) for your target architecture;
select the desired packages (XANADU/Xspec at the very minimum) at STEP 2;
click the submit button to get the installation tarball tailored to your choices.
At this point you will have an archive, say heasoft-<version>src.tar.gz
,
that you should decompress into your target installation folder. There are
detailed installation instructions for all the major platforms,
including
You should look carefully at the list of prerequisites for your target OS before you start compiling the code.
Compiling PyXspec under GNU/Linux¶
Compiling is pretty easy, the only real thing to pay attention to being the fact that by default Xspec will try to create the bindings for Python 2 by default, which is not what you want if you have been following the instructions upstream. In order to use Python 3 the correct sequence of events is to configure the build process
cd BUILD_DIR/
./configure
and, before you start the compilation, tweak the Xspec configuration file
heasoft-<version>/Xspec/BUILD_DIR/hmakerc
and explicitly set the
PYTHON_INC
and PYTHON_LIB
variables along the lines of
PYTHON_INC="-I/path/to/your/anaconda_py3/include/python3.6m"
PYTHON_LIB="-L/path/to/your/anaconda_py3/lib -lpython3.6m"
At this point you are ready to trigger the actual build process, i.e.,
make
make install
Refer to the PyXspec installation page for all the gory details and the troubleshooting information. Once everything is compiled and installed you will have to source the proper setup file, e.g.
export HEADAS=/path/to/your/installed/heasoft-<version>/<platform>
. $HEADAS/headas-init.sh
See the section about XSPEC support for a more in-depth discussion about the interactions between ixpeobssim and XSPEC.
Installing ixpeobssim¶
As mentioned at the beginning, the easiest way to install ixpeobssim is via pip. If you plan on actively contributing to the software development (as opposed to just using it) you will need to clone the github repository, as explained in the Code development page.
Installing ixpeobssim as a user¶
Installing ixpeobbsim as a user should be as simple as doing
pip install ixpeobssim --user
Loosely speaking, if at this point you can open a Python prompt and do
>>> import ixpeobssim
without getting back an error message like this
>>> import ixpeobssim
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named ixpeobssim
>>>
you should be all set. You should be able to call all the executables from their entry points (without the .py extension) as well, e.g.
xpobssim --help
In case, for any reason, you do need to uninstall the package, just type
pip uninstall ixpeobssim
If you installed PyXspec and you want to use it, make sure also to define the HEADAS path to HEASOFT package and run the corresponding setup script, e.g.
export HEADAS=/path/to/your/installed/heasoft-<version>/<platform>
. $HEADAS/headas-init.sh
Warning
When you install ixpeobbsim
in user mode you want to make sure you
don’t have any leftover from previous installation, as that is bound to
lead to cryptic errors that would be hard to debug. Make sure you uninstall
any old version and you don’t leave any .pyc file behind.
Likewise, if you ever decide to switch from user to developer mode (see next section), make sure you clean up any previous installation first.
Up and running in development mode¶
If you are actively developing code, having it installed (possibly within
system folders) is unlikely to be what you want. Once you have cloned the
github repository all you really need to do in this case is to make sure that
the root folder of the repository is included in the PYTHONPATH
environmental variable.
ixpeobssim comes with its own minimal shell ([github]/setup.sh, for GNU/Linux or Mac) and batch ([github]/setup.bat, for Windows) setup scripts that you’re welcome to take advantage of—you should be up and running by just doing
source setup.sh
under GNU/Linux or Mac, and
setup.bat
under Windows. (Mind this will also add the path to the folder with the
ixpeobssim executable scripts to the PATH
evironmental variable.)
Warning
If you’re operating in development mode you won’t have the entry points for the ixpeobssim applications installed, e.g., you won’t be able to call the executables without the .py extensions.
Most of the documentation is written from the user standpoint, so keep this in mind: whenever you read, e.g.,
xpobssim --help
if you’re working in developer mode you will actually need to type
xpobssim.py --help
Changing the default output directory¶
By default, ixpeobssim will create an ixpeobssimdata
folder in your
HOME
directory and stuff all the output files (e.g., FITS event lists)
in there—unless you specify the path to the output files from the command
line.
If you want to change the default behavior and select your favourite directory
for storing all the output files, you just need to define the
IXPEOBSSIM_DATA
environmental variable pointing to the directory itself.
export IXPEOBSSIM_DATA=/path/to/the/new/output/folder