pySPT 0.1

Package dedicated to the source position transformation in lens modeling.

pySPT - Source Position Transformation
======================================


.. image:: https://img.shields.io/badge/license-MIT-blue.svg?style=flat
:target: https://github.com/owertz/pySPT/blob/master/LICENSE

.. image:: https://readthedocs.org/projects/pyspt/badge/?version=latest
:target: http://pyspt.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

.. image:: https://travis-ci.org/owertz/pySPT.svg?branch=master
:target: https://travis-ci.org/owertz/pySPT

|

``pySPT`` is a package dedicated to the Source Position
Transformation (SPT). The main goal of ``pySPT`` is to provide
a tool to quantify the systematic errors that are introduced by
the SPT in lens modeling. ``pySPT`` is free, open source software
compatible with Python 2.7 and distributed under the terms of
the `MIT <https://github.com/owertz/pySPT/blob/master/LICENSE>`_ license.


Introduction
------------
The modern time-delay cosmography aims to infer the cosmological
parameters with a competitive precision from observing a multiply
imaged quasar. The success of this technique relies upon a robust
modeling of the lens mass distribution. Unfortunately strong
degeneracies between density profiles that lead to almost the same
lensing observables may bias precise estimate for the Hubble
constant. The SPT, which covers the well-known mass sheet
transformation (MST) as a special case, defines a new framework
to investigate these degeneracies.

Recently, a detailed analysis of how the SPT may affect the
time-delay cosmography has been presented in `Wertz, Orthen & Schneider (2017) <https://arxiv.org/abs/1712.05033>`_.
To address this question, we started by developing
a flexible numerical framework that encompasses well-tested and
efficient implementations of most of the analytical results published
in `Schneider & Sluse (2014) <https://arxiv.org/abs/1306.4675>`_
and `Unruh, Schneider & Sluse (2017) <https://arxiv.org/abs/1606.04321>`_.
Numerous additional features were then added, giving rise to ``pySPT`` .

The main repository of ``pySPT`` resides on `Github <https://github.com/owertz/pySPT>`_,
keeping an effective collaboration with Git as a version control system.
The code is under continuous development and feedback/suggestions/improvements
would be greatly appreciated. To do so, feel free to create an `issue <https://github.com/owertz/pySPT/issues>`_
to report a bug or send a `pull request <https://github.com/owertz/pySPT/pulls>`_
to submit your contribution.

Documentation
-------------
The full documentation for ``pySPT`` can be found here: http://pyspt.readthedocs.io.

Jupyter notebooks
-----------------
Several tutorials in the form of Jupyter notebooks can be found here: https://github.com/owertz/pySPT_tutorials

Installation and dependencies
-----------------------------
``pySPT`` relies on packages included in the python standard library
and the proven open-source libraries ``numpy``, ``scipy``, ``matplotlib``
and ``numdifftools``.

Using the setup.py file
^^^^^^^^^^^^^^^^^^^^^^^
First, you have to download ``pySPT`` from its Github repository as a
zip file and unzip it on your computer. Enter the ``pySPT`` root folder
where the setup.py file is located and use the command:

.. code-block:: bash

$ python setup.py install

Check the installation
^^^^^^^^^^^^^^^^^^^^^^
To check that the installation run smoothly, open Python and use the command:

.. code-block:: python

import pySPT

If everything went as planned, you will see a friendly welcome message.

C-shared libraries
------------------
For the sake of efficiency, a few methods of the class ``pySPT.spt.SPT`` (mainly ``tilde_alpha_fast`` and ``tilde_psi_fast``) make use of C shared libraries to compute the closest curl-free approximation of the SPT-modified deflection angle as well as the corresponding deflection potential. These libraries are provided with ``pySPT`` and are automatically installed in the sub-repository '.../pySPT/sources_C/' when you install ``pySPT``.

However, you will need a C-compiler pre-installed on your machine to run these methods.
I personally recommend `gcc <https://gcc.gnu.org/>`_. If your machine runs on MacOsX, the gcc compiler is
included with 'Xcode', which can be installed for free (see `here <https://developer.apple.com/xcode/>`_ for info about Xcode).
A step-by-step installation guide is given `here <https://www.mkyong.com/mac/how-to-install-gcc-compiler-on-mac-os-x/>`_.

How to deal with ``pySPT`` and C-shared libraries are discussed `here <https://github.com/owertz/pySPT_tutorials/blob/master/pySPT_tutorial_spt.ipynb>`_

Recompile the C files
^^^^^^^^^^^^^^^^^^^^^
In the case you want to recompile the C shared libraries on your computer, you need a C-compiler pre-installed on
your machine.

How to manually compile a *.c file:

(1) Open a terminal and go in the folder '~/pySPT/sources_C' where ~ is the absolute path where pySPT is installed.
(2) Run the following command in a terminal

.. code-block:: bash

$ gcc -shared -o osx/test.so -fPIC -lm -lgsl sources/test.c

where `test` is the filename of a C source file, e.g. IntegrandAlphaTilde_NISG_IS1.
Note that osx has to be changed depending on your platform: ``osx`` for Max OS X and
``linux`` for a Linux distribution. Windows is not yet supported. Note that ``-lgsl`` is only required
for a code (*.c file) which requires the gsl library (see below), and can thus be ignored when gsl is not required.

How to compile all the *.c files:

(1) Open a terminal and go in the folder '~/pySPT/sources_C/' where ~ is the absolute path where pySPT is installed.
(2) Run the bash script 'compile_shared_libraries.sh':

.. code-block:: bash

$ bash compile_shared_libraries.sh

GSL library
^^^^^^^^^^^
A few C shared libraries require the GNU Scientific Library (gsl) to work properly.
If you do not have this library pre-installed on your machine, ``pySPT`` will raise an exception telling you there
is a missing gsl*.so file. An easy way to obtain gsl is to run (in a terminal):

.. code-block:: bash

$ brew install gsl

General informations about ``gsl`` is given `here <https://www.gnu.org/software/gsl/>`_.
Additional informations to install and configure ``gsl`` are given `here <http://www2.lawrence.edu/fast/GREGGJ/CMSC210/gsl/gsl.html>`_.


Attribution
-----------
Most of ``pySPT`` capabilities and key features are reported in
`Wertz & Orthen 2017 <https://arxiv.org/abs/1801.04151>`_. Please cite that paper whenever you publish
results that made use of ``pySPT``.