README.md 7.37 KB
Newer Older
Jait Dixit's avatar
Jait Dixit committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
NIFTY - Numerical Information Field Theory
==========================================
[![build status](https://gitlab.mpcdf.mpg.de/ift/NIFTy/badges/master/build.svg)](https://gitlab.mpcdf.mpg.de/ift/NIFTy/commits/master)
[![coverage report](https://gitlab.mpcdf.mpg.de/ift/NIFTy/badges/master/coverage.svg)](https://gitlab.mpcdf.mpg.de/ift/NIFTy/commits/master)

**NIFTY** project homepage:
[http://www.mpa-garching.mpg.de/ift/nifty/](http://www.mpa-garching.mpg.de/ift/nifty/)

Summary
-------

### Description

**NIFTY**, "**N**umerical **I**nformation **F**ield **T**heor**y**", is
a versatile library designed to enable the development of signal
inference algorithms that operate regardless of the underlying spatial
grid and its resolution. Its object-oriented framework is written in
Python, although it accesses libraries written in Cython, C++, and C for
efficiency.

NIFTY offers a toolkit that abstracts discretized representations of
continuous spaces, fields in these spaces, and operators acting on
fields into classes. Thereby, the correct normalization of operations on
fields is taken care of automatically without concerning the user. This
allows for an abstract formulation and programming of inference
algorithms, including those derived within information field theory.
Thus, NIFTY permits its user to rapidly prototype algorithms in 1D, and
then apply the developed code in higher-dimensional settings of real
world problems. 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.

### Class & Feature Overview

The NIFTY library features three main classes: **spaces** that represent
certain grids, **fields** that are defined on spaces, and **operators**
that apply to fields.

-   [Spaces](http://www.mpa-garching.mpg.de/ift/nifty/space.html)
    -   `rg_space` - *n*-dimensional regular Euclidean grid
    -   `lm_space` - spherical harmonics
    -   `gl_space` - Gauss-Legendre grid on the 2-sphere
    -   `hp_space` - [HEALPix](http://sourceforge.net/projects/healpix/)
        grid on the 2-sphere
-   [Fields](http://www.mpa-garching.mpg.de/ift/nifty/field.html)
    -   `field` - generic class for (discretized) fields

<!-- -->

51
52
    field.conjugate     field.dim          field.norm
    field.dot           field.set_val      field.weight
Jait Dixit's avatar
Jait Dixit committed
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

-   [Operators](http://www.mpa-garching.mpg.de/ift/nifty/operator.html)
    -   `diagonal_operator` - purely diagonal matrices in a specified
        basis
    -   `projection_operator` - projections onto subsets of a specified
        basis
    -   `propagator_operator` - information propagator in Wiener filter
        theory
    -   (and more)
-   (and more)

*Parts of this summary are taken from* [1] *without marking them
explicitly as quotations.*

Installation
------------

### Requirements

-   [Python](http://www.python.org/) (v2.7.x)
    -   [NumPy](http://www.numpy.org/)
    -   [Cython](http://cython.org/)

### Download

Martin Reinecke's avatar
updates    
Martin Reinecke committed
78
The current version of Nifty3 can be obtained by cloning the repository:
Jait Dixit's avatar
Jait Dixit committed
79
80
81

    git clone https://gitlab.mpcdf.mpg.de/ift/NIFTy.git

Martin Reinecke's avatar
updates    
Martin Reinecke committed
82
83
84
85
86
and switching to the "master" branch:

    cd NIFTy
    git checkout master

Jait Dixit's avatar
Jait Dixit committed
87
88
89
90
91
92
93
94
95
### Installation on Ubuntu

This is for you if you want to install NIFTy on your personal computer
running with an Ubuntu-like linux system were you have root priviledges.
Starting with a fresh Ubuntu installation move to a folder like
`~/Downloads`:

-   Install basic packages like python, python-dev, gsl and others:

96
        sudo apt-get install curl git autoconf
Martin Reinecke's avatar
updates    
Martin Reinecke committed
97
        sudo apt-get install python-dev python-pip gsl-bin libgsl0-dev libfreetype6-dev libpng-dev libatlas-base-dev python-numpy cython
Jait Dixit's avatar
Jait Dixit committed
98

Martin Reinecke's avatar
updates    
Martin Reinecke committed
99
    (MR: do we really need all of those? I would have expected something like "git autoconf python-dev python-pip python-numpy cython")
Jait Dixit's avatar
Jait Dixit committed
100

101
-   Install pyHealpix:
Jait Dixit's avatar
Jait Dixit committed
102

Martin Reinecke's avatar
Martin Reinecke committed
103
        git clone https://gitlab.mpcdf.mpg.de/ift/pyHealpix.git
104
        cd pyHealpix
Martin Reinecke's avatar
updates    
Martin Reinecke committed
105
        autoreconf -i && ./configure --prefix=$HOME/.local && make -j4 && make install
Jait Dixit's avatar
Jait Dixit committed
106
107
108
109
110
        cd ..

-   Finally, NIFTy:

        git clone https://gitlab.mpcdf.mpg.de/ift/NIFTy.git
Martin Reinecke's avatar
updates    
Martin Reinecke committed
111
112
113
        cd NIFTy
        git checkout master
        python setup.py install --user
114
        cd ..
Jait Dixit's avatar
Jait Dixit committed
115

Martin Reinecke's avatar
updates    
Martin Reinecke committed
116
### Installation on Linux systems in general
Jait Dixit's avatar
Jait Dixit committed
117

Martin Reinecke's avatar
updates    
Martin Reinecke committed
118
119
120
121
122
123
Since all the "unconventional" packages (i.e. pyHealpix and NIFTy) listed in the
section above are installed
within the home directory of the user, the installation instructions for these
should also work on any Linux machine where you do not have root access.
In this case you have to ensure with your system administrators that the
"standard" dependencies (python, numpy, etc.) are installed system-wide.
124

Jait Dixit's avatar
Jait Dixit committed
125
126
### Installation on OS X 10.11

127
We advise to install the following packages in the order as they appear
Jait Dixit's avatar
Jait Dixit committed
128
129
130
131
132
133
below. We strongly recommend to install all needed packages via
MacPorts. Please be aware that not all packages are available on
MacPorts, missing ones need to be installed manually. It may also be
mentioned that one should only use one package manager, as multiple ones
may cause trouble.

134
-   Install basic packages numpy and cython:
Jait Dixit's avatar
Jait Dixit committed
135
136
137
138

        sudo port install py27-numpy
        sudo port install py27-cython

139
-   Install pyHealpix:
Jait Dixit's avatar
Jait Dixit committed
140

Martin Reinecke's avatar
Martin Reinecke committed
141
        git clone https://gitlab.mpcdf.mpg.de/ift/pyHealpix.git
142
        cd pyHealpix
Martin Reinecke's avatar
Martin Reinecke committed
143
        autoreconf -i && ./configure --prefix=`python-config --prefix` && make -j4 && sudo make install
Jait Dixit's avatar
Jait Dixit committed
144
145
        cd ..

Martin Reinecke's avatar
updates    
Martin Reinecke committed
146
147
148
149
    (The third command installs the package system-wide. User-specific
    installation would be preferrable, but we haven't found a simple recipe yet
    how to determine the installation prefix ...)

Jait Dixit's avatar
Jait Dixit committed
150
151
152
-   Install NIFTy:

        git clone https://gitlab.mpcdf.mpg.de/ift/NIFTy.git
Martin Reinecke's avatar
updates    
Martin Reinecke committed
153
154
155
        cd NIFTy
        git checkout master
        python setup.py install --user
156
        cd ..
Jait Dixit's avatar
Jait Dixit committed
157
158
159

### Installation using pypi

Martin Reinecke's avatar
updates    
Martin Reinecke committed
160
(MR: I'm not sure whether this approach works ... pyHealpix is not registered
Martin Reinecke's avatar
updates    
Martin Reinecke committed
161
with pypi and I'm not sure it can be.)
Martin Reinecke's avatar
updates    
Martin Reinecke committed
162

Jait Dixit's avatar
Jait Dixit committed
163
164
165
166
167
168
169
170
171
NIFTY can be installed using [PyPI](https://pypi.python.org/pypi) and
**pip** by running the following command:

    pip install ift_nifty

Alternatively, a private or user specific installation can be done by:

    pip install --user ift_nifty

Theo Steininger's avatar
Theo Steininger committed
172
173
174
175
176
177
### Running the tests

In oder to run the tests one needs two additional packages:

    pip install nose
    pip install parameterized
178
179

Afterwards the tests (including a coverage report) are run using the following
Theo Steininger's avatar
Theo Steininger committed
180
command in the repository root:
181

Theo Steininger's avatar
Theo Steininger committed
182
183
184
    nosetests --exe --cover-html


Jait Dixit's avatar
Jait Dixit committed
185
186
187
188
189
190
### First Steps

For a quickstart, you can browse through the [informal
introduction](http://www.mpa-garching.mpg.de/ift/nifty/start.html) or
dive into NIFTY by running one of the demonstrations, e.g.:

191
    python demos/wiener_filter.py
Jait Dixit's avatar
Jait Dixit committed
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219

Acknowledgement
---------------

Please, acknowledge the use of 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 [Selig et al., 2013]."*

### References

Release Notes
-------------

The NIFTY package is licensed under the
[GPLv3](http://www.gnu.org/licenses/gpl.html) and is distributed
*without any warranty*.

* * * * *

**NIFTY** project homepage:
[](http://www.mpa-garching.mpg.de/ift/nifty/)

[1] Selig et al., "NIFTY - Numerical Information Field Theory - a
versatile Python library for signal inference", [A&A, vol. 554, id.
A26](http://dx.doi.org/10.1051/0004-6361/201321236), 2013;
[arXiv:1301.4499](http://www.arxiv.org/abs/1301.4499)