Ligo.skymap

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

- 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.

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

- Update installation instructions to state that installation with pip requires
pip 19.3 or newer. This has been the case since ligo.skymap 0.1.16.

- Teach BAYESTAR to respect the ``f_final`` column in the ``sngl_inspiral``
table for pre-merger, early warning templates.

- Ensure that BAYESTAR's arrival time prior is long enough to contain at least
half a cycle of the template autocorrelation sequence. Previously, the
duration of the arrival time prior was calculated solely from the light
travel times between the participating detectors. This fixes an issue where
SNR time series for early-warning events could have been cropped to only 1-3
samples.

- Change BAYESTAR's strategy for evaluating SNR time series from Catmull-Rom
interpolation of the real and imaginary parts to Catmull-Rom interpolation of
the amplitude and phase. The old interpolation method could produce
oscillatory artifacts in the SNR amplitude if the data are nearly critically
sampled, as is the case for early-warning BNS events. The new interpolation
method is immune to this kind of artifact, and also has much faster
convergence as a function of sample rate.

- Lift the code to apply time shifts to SNR series outside of BAYESTAR's inner
loop because there are no data dependencies on the variables of integration.
This is seen to speed up BAYESTAR by 30%.

- Add software version and command line arguments metadata to the output of
``ligo-skymap-plot-stats``.

- Fix a bug in the Lanczos sub-sample arrival time interpolant: the Lanczos
kernel should be zero for ``abs(t) >= a``.

- Remove ``requirements.txt`` file and list dependencies in ``setup.cfg``
instead.

- The ``bayestar-localize-coincs`` will no longer create HTCondor user log
files because the large number of open log files could strain the filesystem
if submitting from an NFS mount. This should reduce issues with held jobs on
certain LIGO Data Grid clusters.

- Fix deprecation warning in ``ligo-skymap-stats``.

- Remove the deprecated ``ligo.skymap.postprocess.find_injection_moc`` method,
which has been renamed to ``ligo.skymap.postprocess.crossmatch``.

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

- Update the compiler version that is used to build Linux wheels to icc
19.1.0.166 from Intel Parallel Studio XE 2020u0. Due to C ABI requirements,
the wheels are now built for the `manylinux2014
<https://www.python.org/dev/peps/pep-0599/>`_ standard.

- Fix a unit test failure with astropy < 4.0.0.

- Add support for all combinations of map projection options, including
``geo degrees globe`` and ``geo degrees zoom``. Also, ``astro`` by itself is
shorthand for ``astro hours``, and ``geo`` by itself is short for
``geo degrees``.

- ``ligo-skymap-plot`` now supports a variety of projections using the
``--projection`` option.

- Turn on continuous integration testing for Python 3.8.

- Change the license for the project as a whole to GPL 3.0 or later (GPLv3+).
Previously, the source files had been a mix of GPLv2+ and GPLv3+.

- Add ``ligo-skymap-contour-moc`` command line to create a credible region
in a MOC (Multi Order Coverage) data structure. The input can be either a
multiresolution or a flattened HEALPix probability map.