Ligo.skymap

==================

- Add ``--f-high`` option to ``bayestar-realize-coincs`` in order to simulate
early warning triggers.

- In sky maps produced by ``bayestar-localize-coincs``, the FITS headers now
contain ``OBJECT`` identifiers that are integer event IDs (such as ``1``)
rather than strings (such as ``coinc_event:coinc_event_id:1``).

- The ``ligo-skymap-stats`` tool now recognizes FITS headers with either
integer or string ``OBJECT`` identifiers.

- Use Astropy rather than LAL for GPS to UTC time conversion in FITS headers so
that LALSuite is not a requirement for reading and writing FITS files.

- Refactor ``ligo-skymap-stats`` to unify its multiprocessing and progress bar
implementation with other command line tools.

- Update the compiler version that is used to build Linux wheels to icc
19.1.2.254 from Intel Parallel Studio XE 2020u2.

- Port the Python C extension to the limited stable Python API so that one
binary wheel works for all supported Python versions for any given operating
system. See `PEP 384 <https://www.python.org/dev/peps/pep-0384/>`_.

- Eliminate global static variables from the Python C extension to enable
compatibility with Python subinterpreters. See
`PEP 3121 <https://www.python.org/dev/peps/pep-3121/>`_.

- Improve the numerical stability of the method
:meth:`ligo.skymap.distance.conditional_ppf` by reparametrizing the equation
that is being solved. This method, which calculates the inverse of the
distance CDF, works by solving the equation :math:`f(x) - p = 0` for
:math:`x`, where :math:`f(x)` is the distance CDF, and :math:`p` is the
desired probability.

The reparametrized equation is :math:`log(1 - f(x)) - log(1 - p) = 0` if
:math:`p > 1/2` and :math:`log(f(x)) - log(p) = 0` otherwise. This
reparametrization is effective because it improves the dynamic range in the
tails of the distribution. This same reparametrization had already proven
effective in the related method :meth:`ligo.skymap.distance.marginal_ppf`.

This change also fixes some rare corner cases where
:meth:`~ligo.skymap.distance.marginal_ppf` returned silly values becauses it
uses :meth:`~ligo.skymap.distance.conditional_ppf` internally to create its
own initial guess. One example was the median distance for the binary neutron
star candidate S191205ah. Before this patch, the result was negative and
invalid::

>>> from ligo.skymap.distance import marginal_ppf
>>> from ligo.skymap.moc import uniq2pixarea
>>> from ligo.skymap.io import read_sky_map
>>> url = 'https://gracedb.ligo.org/apiweb/superevents/S191205ah/files/bayestar.multiorder.fits'
>>> s = read_sky_map(url, moc=True)
>>> marginal_ppf(0.5, s['PROBDENSITY'] * uniq2pixarea(s['UNIQ']),
... s['DISTMU'], s['DISTSIGMA'], s['DISTNORM'])
/Users/lpsinger/src/ligo.skymap/ligo/skymap/util/numpy.py:46: RuntimeWarning: invalid value encountered in marginal_ppf
return func(*args, **kwargs)
-223357.8508233767

After this patch, the result is positive and sensible::

>>> marginal_ppf(0.5, s['PROBDENSITY'] * uniq2pixarea(s['UNIQ']),
... s['DISTMU'], s['DISTSIGMA'], s['DISTNORM'])
362.7485740018039

- Increase the range of validity of the solver used in
:meth:`ligo.skymap.distance.moments_to_parameters` for low-probability pixels
that are very prior dominated. Sky maps that have many such pixels could have
credible volumes repoted as infinity. The incidence of such cases should now
be decreased.

- Correct the alignment of Numpy record arrays passed to
:func:`ligo.skymap.moc.rasterize` in order to avoid possibly undefined
behavior that was detected by UBSan.

==================

- Normalize column names when an ASCII file is passed to
``ligo-skymap-from-samples``.

- Migrate LIGO-LW XML support from the ``glue.ligolw`` module to the newer and
better maintained ``ligo.lw`` module.

- Teach BAYESTAR to accept either string row IDs (such as
``sngl_inspiral:event_id:1``) or integer row IDs (such as ``1``).

- The parallel ``map()`` implementation that is used by a number of the
package's command line tools will now yield results in order as quickly as
they arrive, rather than sorting all of the results at the end. This should
provide a very modest speedup in some command line tools.

==================

- Replace a call to the ``aligned_alloc`` function with the ``posix_memalign``
function. The ``aligned_alloc`` function is part of the C11 standard library,
but is missing on some platforms, particularly very old versions of macOS.

This fixes an issue with building Conda packages.

==================

- Fix an out of bounds access in the bicubic interpolation function that
BAYESTAR uses to evaluate the integral over distance. Due to the relationship
between the lookup table bounds and BAYESTAR's distance limits of
integration, the corner case that caused out of bounds access was never
triggered. This bug had no impact on localizations generated by BAYESTAR.

- More performance improvements in BAYESTAR providing a 2x speedup.
For benchmark results, see the new `How fast is BAYESTAR?`_ section in the
manual.

- The function ``bicubic_interp_eval`` had not being effectively
autovectorized by the compiler. Rewrite it in explicitly vector form using
the `GCC vector extension`_ (which is also supported by clang and icc) and
selected vector intrinsics. In x86_64 builds, gcc, clang, and icc will now
emit SSE2, SSE4.1, and FMA instructions for this code.

- Pre-evaluate the SNR=0 limit of the distance integral to move some
conditionals and logarithms out of BAYESTAR's innermost loop.

- Add loop count hints to improve the efficacy of loop unrolling.

- Perform manual loop fission in ``bayestar_sky_map_toa_phoa_snr_pixel``.

- Update ligo.skymap to the latest version of the Astropy affiliated package
template. Migrate package infrastructure from `APE 4`_ to `APE 17`_. The
astropy-helpers submodule has been removed, and the package now includes a
pyproject.toml file (see `PEP 517`_ and `PEP 518`_).

- As a consequence of migrating to `APE 17`_ and switching to
`setuptools_scm`_, the version of ligo.skymap will be reported slightly
differently. The ``ligo.skymap.__githash__`` variable has been removed, and
instead the git hash will be part of the ``ligo.skymap.__version__`` version
string for unreleased, local versions.

- Correspondingly, ``ligo.skymap`` tools that generate FITS files
(``bayestar-localize-lvalert``, ``bayestar-localize-coincs``,
``ligo-skymap-from-samples``) will no longer populate the ``VCSREV`` and
``DATE-BLD`` keys in FITS headers.

.. _`GCC vector extension`: https://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html
.. _`How fast is BAYESTAR?`: https://lscsoft.docs.ligo.org/ligo.skymap/performance.html
.. _`APE 4`: https://github.com/astropy/astropy-APEs/blob/master/APE4.rst
.. _`APE 17`: https://github.com/astropy/astropy-APEs/blob/master/APE17.rst
.. _`PEP 517`: https://www.python.org/dev/peps/pep-0517/
.. _`PEP 518`: https://www.python.org/dev/peps/pep-0518/
.. _`setuptools_scm`: https://github.com/pypa/setuptools_scm

==================

- Fix incorrect legends on histograms generated by ``ligo-skymap-plot-stats``.

- When the ``bayestar-localize-coincs`` or ``bayestar-localize-lvalert``
scripts are called with ``--loglevel=info`` or higher, they will now output
additional runtime measurements. Specifically, they will output the "real"
time (wall clock time), "user" time (total time spent in userland across all
threads), and "sys" time (total time spent in kernel land across all
threads), similar to the UNIX :manpage:`time(1)` tool. Here is an example of
the formatting::

2020-05-12 18:57:12,024 INFO finished computationally-intensive section in real=0.918s, user=36.339s, sys=0.293s

==================

- Speed up ``import ligo.skymap`` by up to a second by replacing uses of
``pkg_resources`` with the new Python standard library module
``importlib.resources`` (or, for Python < 3.7, the backport
``importlib_resources``). The old ``pkg_resources`` module is known to be
slow because it does a lot of work on startup. (See, for example,
https://github.com/pypa/setuptools/issues/926 and
https://github.com/pypa/setuptools/issues/510.)

- Drop dependency on seaborn.

- Move some rarely used imports (``networkx`` and ``astropy.convolution``) from
module scope to function scope to speed up imports by up to half a second on
NFS filesystems.