Commit 438ac2c6 authored by Philipp Arras's avatar Philipp Arras
Browse files

Merge branch 'pypi_preparations' into 'NIFTy_7'

Add pypi related files and rework documentation

See merge request !654
parents 98e6c036 9d382e59
Pipeline #105208 passed with stages
in 17 minutes and 28 seconds
......@@ -6,15 +6,13 @@ RUN apt-get update && apt-get install -y \
# Packages needed for NIFTy
python3-scipy \
# Documentation build dependencies
python3-sphinx-rtd-theme dvipng texlive-latex-base texlive-latex-extra \
dvipng texlive-latex-base texlive-latex-extra \
# Testing dependencies
python3-pytest-cov jupyter \
# Optional NIFTy dependencies
python3-mpi4py python3-matplotlib \
# more optional NIFTy dependencies
&& pip3 install ducc0 \
&& pip3 install finufft \
&& pip3 install jupyter \
&& pip3 install ducc0 finufft jupyter sphinx pydata-sphinx-theme \
&& rm -rf /var/lib/apt/lists/*
# Set matplotlib backend
......
include ChangeLog.md
include demos/*.py
graft tests
global-exclude *.py[cod]
......@@ -4,7 +4,7 @@ NIFTy - Numerical Information Field Theory
[![coverage report](https://gitlab.mpcdf.mpg.de/ift/nifty/badges/NIFTy_7/coverage.svg)](https://gitlab.mpcdf.mpg.de/ift/nifty/-/commits/NIFTy_7)
**NIFTy** project homepage:
[http://ift.pages.mpcdf.de/nifty](http://ift.pages.mpcdf.de/nifty)
[https://ift.pages.mpcdf.de/nifty](https://ift.pages.mpcdf.de/nifty)
Summary
-------
......@@ -49,7 +49,7 @@ Installation
- [SciPy](https://www.scipy.org/)
Optional dependencies:
- [DUCC0](https://gitlab.mpcdf.mpg.de/mtr/ducc) for faster FFTs, spherical
- [ducc0](https://gitlab.mpcdf.mpg.de/mtr/ducc) for faster FFTs, spherical
harmonic transforms, and radio interferometry gridding support
- [mpi4py](https://mpi4py.scipy.org) (for MPI-parallel execution)
- [matplotlib](https://matplotlib.org/) (for field plotting)
......@@ -88,7 +88,7 @@ MPI support is added via:
sudo apt-get install python3-mpi4py
### Running the tests
### Run the tests
To run the tests, additional packages are required:
......@@ -102,29 +102,20 @@ following command in the repository root:
### First Steps
For a quick start, you can browse through the [informal
introduction](http://ift.pages.mpcdf.de/nifty/code.html) or
introduction](https://ift.pages.mpcdf.de/nifty/code.html) or
dive into NIFTy by running one of the demonstrations, e.g.:
python3 demos/getting_started_1.py
### Building the documentation from source
To build the documentation from source, install
[sphinx](https://www.sphinx-doc.org/en/stable/index.html) and the
[Read The Docs Sphinx Theme](https://github.com/readthedocs/sphinx_rtd_theme)
on your system and run
sh docs/generate.sh
### Acknowledgements
Please acknowledge the use of NIFTy in your publication(s) by using a
phrase such as the following:
Please consider acknowledging NIFTy in your publication(s) by using a phrase
such as the following:
> "Some of the results in this publication have been derived using the
> NIFTy package [(https://gitlab.mpcdf.mpg.de/ift/NIFTy)](https://gitlab.mpcdf.mpg.de/ift/NIFTy)"
and a citation to one of the [publications](http://ift.pages.mpcdf.de/nifty/citations.html).
and a citation to one of the [publications](https://ift.pages.mpcdf.de/nifty/citations.html).
### Licensing terms
......@@ -134,15 +125,6 @@ The NIFTy package is licensed under the terms of the
*without any warranty*.
Contributing
------------
Please note our convention not to use pure Python `assert` statements in
production code. They are not guaranteed to by executed by Python and can be
turned off by the user (`python -O` in cPython). As an alternative use
`ift.myassert`.
Contributors
------------
......
import nifty7
needs_sphinx = '3.2.0'
extensions = [
'sphinx.ext.napoleon', # Support for NumPy and Google style docstrings
'sphinx.ext.imgmath', # Render math as images
......@@ -26,8 +28,19 @@ language = None
exclude_patterns = []
add_module_names = False
html_theme = "sphinx_rtd_theme"
html_theme = "pydata_sphinx_theme"
html_logo = 'nifty_logo_black.png'
html_theme_options = {
"icon_links": [
{
"name": "PyPI",
"url": "https://pypi.org/project/nifty7",
"icon": "fas fa-box",
}
],
"gitlab_url": "https://gitlab.mpcdf.mpg.de/ift/nifty",
}
html_last_updated_fmt = '%b %d, %Y'
exclude_patterns = [
'mod/modules.rst', 'mod/nifty7.git_version.rst', 'mod/nifty7.logger.rst'
......
Contributing to NIFTy
=====================
Coding conventions
------------------
We do not use pure Python `assert` statements in production code. They are not
guaranteed to by executed by Python and can be turned off by the user
(`python -O` in cPython). As an alternative use `ift.myassert`.
Build the documentation
-----------------------
To build the documentation from source, install `sphinx
<https://www.sphinx-doc.org/en/stable/index.html>`_ and the `pydata sphinx theme
<https://github.com/pydata/pydata-sphinx-theme>`_ on your system and run
.. code-block:: sh
sh docs/generate.sh
NIFTy -- Numerical Information Field Theory
===========================================
NIFTy Manual
============
**NIFTy** [1]_ [2]_ [3]_, "\ **N**\umerical **I**\nformation **F**\ield **T**\heor\ **y**\ ", is a versatile library designed to enable the development of signal inference algorithms that are independent of the underlying grids (spatial, spectral, temporal, …) and their resolutions.
Its object-oriented framework is written in Python, although it accesses libraries written in C++ and C for efficiency.
NIFTy offers a toolkit that abstracts discretized representations of continuous spaces, fields in these spaces, and operators acting on these fields into classes.
This allows for an abstract formulation and programming of inference algorithms, including those derived within information field theory.
NIFTy's interface is designed to resemble IFT formulae in the sense that the user implements algorithms in NIFTy independent of the topology of the underlying spaces and the discretization scheme.
Thus, the user can develop algorithms on subsets of problems and on spaces where the detailed performance of the algorithm can be properly evaluated and then easily generalize them to other, more complex spaces and the full problem, respectively.
The set of spaces on which NIFTy operates comprises point sets, *n*-dimensional regular grids, spherical spaces, their harmonic counterparts, and product spaces constructed as combinations of those.
NIFTy takes care of numerical subtleties like the normalization of operations on fields and the numerical representation of model components, allowing the user to focus on formulating the abstract inference procedures and process-specific model properties.
References
----------
.. [1] Selig et al., "NIFTY - Numerical Information Field Theory. A versatile PYTHON library for signal inference ", 2013, Astronmy and Astrophysics 554, 26; `[DOI] <https://ui.adsabs.harvard.edu/link_gateway/2013A&A...554A..26S/doi:10.1051/0004-6361/201321236>`_, `[arXiv:1301.4499] <https://arxiv.org/abs/1301.4499>`_
.. [2] Steininger et al., "NIFTy 3 - Numerical Information Field Theory - A Python framework for multicomponent signal inference on HPC clusters", 2017, accepted by Annalen der Physik; `[arXiv:1708.01073] <https://arxiv.org/abs/1708.01073>`_
.. [3] Arras et al., "NIFTy5: Numerical Information Field Theory v5", 2019, Astrophysics Source Code Library; `[ascl:1903.008] <http://ascl.net/1903.008>`_
Contents
........
Welcome to the nifty7 documentation!
.. toctree::
:maxdepth: 2
:maxdepth: 1
ift
volume
Gallery <https://wwwmpa.mpa-garching.mpg.de/~ensslin/nifty-gallery/index.html>
installation
code
citations
Package Documentation <mod/nifty7>
User Guide <user/index>
API reference <mod/nifty7>
Development <dev/index>
IFT -- Information Field Theory
===============================
Information Field Theory
========================
Theoretical Background
----------------------
......@@ -145,14 +145,14 @@ Here, the uncertainty of the field and the power spectrum of its generating proc
+----------------------------------------------------+
| **Output of tomography demo getting_started_3.py** |
+----------------------------------------------------+
| .. image:: images/getting_started_3_setup.png |
| .. image:: ../images/getting_started_3_setup.png |
| |
+----------------------------------------------------+
| Non-Gaussian signal field, |
| data backprojected into the image domain, power |
| spectrum of underlying Gausssian process. |
+----------------------------------------------------+
| .. image:: images/getting_started_3_results.png |
| .. image:: ../images/getting_started_3_results.png |
| |
+----------------------------------------------------+
| Posterior mean field signal |
......
NIFTy user guide
================
This guide is an overview and explains the main idea behind nifty. More details
are found in the `API reference <../mod/nifty7.html>`_.
.. toctree::
:maxdepth: 1
whatisnifty
installation
ift
volume
code
citations
......@@ -29,7 +29,8 @@ MPI support is added via::
NIFTy documentation is provided by Sphinx. To build the documentation::
sudo apt-get install python3-sphinx-rtd-theme dvipng
sudo apt-get install dvipng texlive-latex-base texlive-latex-extra
pip3 install sphinx pydata-sphinx-theme
cd <nifty_directory>
sh docs/generate.sh
......@@ -39,4 +40,3 @@ To view the documentation in firefox::
(Note: Make sure that you reinstall nifty after each change since sphinx
imports nifty from the Python path.)
Discretisation and Volume in NIFTy
==================================
Discretisation and Volume
=========================
.. note:: Some of this discussion is rather technical and may be skipped in a first read-through.
......@@ -12,7 +12,7 @@ Fields are defined to be scalar functions on the manifold, living in the functio
Unless we find ourselves in the lucky situation that we can solve for the posterior statistics of interest analytically, we need to apply numerical methods.
This is where NIFTy comes into play.
.. figure:: images/inference.png
.. figure:: ../images/inference.png
:width: 80%
:align: center
......@@ -138,7 +138,7 @@ NIFTy is implemented such that in order to change resolution, only the line of c
It automatically takes care of dependent structures like volume factors, discretised operators and responses.
A visualisation of this can be seen in figure 2, which displays the MAP inference of a signal at various resolutions.
.. figure:: images/converging_discretization.png
.. figure:: ../images/converging_discretization.png
:scale: 80%
:align: center
......
What is NIFTy?
==============
**NIFTy** [1]_ [2]_ [3]_, "\ **N**\umerical **I**\nformation **F**\ield **T**\heor\ **y**\ ", is a versatile library designed to enable the development of signal inference algorithms that are independent of the underlying grids (spatial, spectral, temporal, …) and their resolutions.
Its object-oriented framework is written in Python, although it accesses libraries written in C++ and C for efficiency.
NIFTy offers a toolkit that abstracts discretized representations of continuous spaces, fields in these spaces, and operators acting on these fields into classes.
This allows for an abstract formulation and programming of inference algorithms, including those derived within information field theory.
NIFTy's interface is designed to resemble IFT formulae in the sense that the user implements algorithms in NIFTy independent of the topology of the underlying spaces and the discretization scheme.
Thus, the user can develop algorithms on subsets of problems and on spaces where the detailed performance of the algorithm can be properly evaluated and then easily generalize them to other, more complex spaces and the full problem, respectively.
The set of spaces on which NIFTy operates comprises point sets, *n*-dimensional regular grids, spherical spaces, their harmonic counterparts, and product spaces constructed as combinations of those.
NIFTy takes care of numerical subtleties like the normalization of operations on fields and the numerical representation of model components, allowing the user to focus on formulating the abstract inference procedures and process-specific model properties.
Examples of nifty applications can be found in the `nifty gallery (external link) <https://wwwmpa.mpa-garching.mpg.de/~ensslin/nifty-gallery/index.html>`_.
References
----------
.. [1] Selig et al., "NIFTY - Numerical Information Field Theory. A versatile PYTHON library for signal inference ", 2013, Astronmy and Astrophysics 554, 26; `[DOI] <https://ui.adsabs.harvard.edu/link_gateway/2013A&A...554A..26S/doi:10.1051/0004-6361/201321236>`_, `[arXiv:1301.4499] <https://arxiv.org/abs/1301.4499>`_
.. [2] Steininger et al., "NIFTy 3 - Numerical Information Field Theory - A Python framework for multicomponent signal inference on HPC clusters", 2017, accepted by Annalen der Physik; `[arXiv:1708.01073] <https://arxiv.org/abs/1708.01073>`_
.. [3] Arras et al., "NIFTy5: Numerical Information Field Theory v5", 2019, Astrophysics Source Code Library; `[ascl:1903.008] <http://ascl.net/1903.008>`_
[build-system]
requires = ["setuptools >= 40.6.0", "numpy >= 1.17.0", "scipy >= 1.4.1"]
build-backend = "setuptools.build_meta"
......@@ -11,7 +11,7 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
# Copyright(C) 2013-2019 Max-Planck-Society
# Copyright(C) 2013-2021 Max-Planck-Society
#
# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik.
......@@ -28,28 +28,35 @@ def write_version():
except FileNotFoundError:
print("Could not determine version string from git history")
res = "unknown"
with open(os.path.join("nifty7", "git_version.py"), "w") as file:
file.write('gitversion = "{}"\n'.format(res))
with open(os.path.join("nifty7", "git_version.py"), "w") as f:
f.write('gitversion = "{}"\n'.format(res))
write_version()
exec(open('nifty7/version.py').read())
with open("README.md") as f:
long_description = f.read()
description = """NIFTy, Numerical Information Field Theory, is a versatile
library designed to enable the development of signal inference algorithms that
operate regardless of the underlying grids and their resolutions."""
setup(name="nifty7",
version=__version__,
author="Theo Steininger, Martin Reinecke",
author="Martin Reinecke",
author_email="martin@mpa-garching.mpg.de",
description="Numerical Information Field Theory",
url="http://www.mpa-garching.mpg.de/ift/nifty/",
description=description,
long_description=long_description,
long_description_content_type="text/markdown",
url="https://ift.pages.mpcdf.de/nifty/",
project_urls={
"Bug Tracker": "https://gitlab.mpcdf.mpg.de/ift/nifty/issues",
"Documentation": "https://ift.pages.mpcdf.de/nifty/",
"Source Code": "https://gitlab.mpcdf.mpg.de/ift/nifty",
},
packages=find_packages(include=["nifty7", "nifty7.*"]),
zip_safe=True,
license="GPLv3",
setup_requires=['scipy>=1.4.1', 'numpy>=1.17'],
install_requires=['scipy>=1.4.1', 'numpy>=1.17'],
python_requires='>=3.6',
classifiers=[
"Development Status :: 4 - Beta",
"Topic :: Utilities",
"License :: OSI Approved :: GNU General Public License v3 "
"or later (GPLv3+)"],
)
......@@ -380,13 +380,12 @@ def MetricGaussianKL(mean, hamiltonian, n_samples, mirror_samples, constants=[],
these occasions but rather the minimizer is told that the position it
has tried is not sensible.
Notes
-----
Note
----
The two lists `constants` and `point_estimates` are independent from each
other. It is possible to sample along domains which are kept constant
during minimization and vice versa.
DomainTuples should never be created using the constructor, but rather
via the factory function :attr:`make`!
See also
--------
`Metric Gaussian Variational Inference`, Jakob Knollmüller,
......@@ -475,15 +474,16 @@ def GeoMetricKL(mean, hamiltonian, n_samples, minimizer_samp, mirror_samples,
these occasions but rather the minimizer is told that the position it
has tried is not sensible.
Notes
-----
Note
----
The two lists `constants` and `point_estimates` are independent from each
other. It is possible to sample along domains which are kept constant
during minimization and vice versa.
DomainTuples should never be created using the constructor, but rather
via the factory function :attr:`make`!
Note on MPI and mirror_samples:
Note
----
As in MGVI, mirroring samples can help to stabilize the latent mean as it
reduces sampling noise. But unlike MGVI a mirrored sample involves an
additional solve of the non-linear transformation. Therefore, when using
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment