├── pyftp
    ├── __init__.py
    ├── gatspy_template_modeler.py
    ├── rrlyrae.py
    ├── fast_template_periodogram.py
    ├── pseudo_poly.py
    └── modeler.py
├── plots
    ├── timing_vs_ndata.png
    ├── timing_vs_nharm.png
    ├── correlation_with_gatspy.png
    ├── correlation_with_large_H.png
    └── templates_and_periodograms.png
├── CONTRIBUTING
├── .gitignore
├── setup.py
├── README.md
└── LICENSE.txt


/pyftp/__init__.py:
--------------------------------------------------------------------------------
1 | __version__ = "0.3.0"
2 | 


--------------------------------------------------------------------------------
/plots/timing_vs_ndata.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jakevdp/FastTemplatePeriodogram_old/master/plots/timing_vs_ndata.png


--------------------------------------------------------------------------------
/plots/timing_vs_nharm.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jakevdp/FastTemplatePeriodogram_old/master/plots/timing_vs_nharm.png


--------------------------------------------------------------------------------
/plots/correlation_with_gatspy.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jakevdp/FastTemplatePeriodogram_old/master/plots/correlation_with_gatspy.png


--------------------------------------------------------------------------------
/plots/correlation_with_large_H.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jakevdp/FastTemplatePeriodogram_old/master/plots/correlation_with_large_H.png


--------------------------------------------------------------------------------
/plots/templates_and_periodograms.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jakevdp/FastTemplatePeriodogram_old/master/plots/templates_and_periodograms.png


--------------------------------------------------------------------------------
/CONTRIBUTING:
--------------------------------------------------------------------------------
 1 | Last updated: Oct 31, 2016; John Hoffman; jah5@princeton.edu
 2 | 
 3 | To contribute to this project, you will need to install several libraries/programs.
 4 | 
 5 | See the [github page](https://github.com/PrincetonUniversity/FastTemplatePeriodogram) for more details and for the latest version.
 6 | 
 7 | * [NFFT](https://www-user.tu-chemnitz.de/~potts/nfft/) <= 3.2.4
 8 | 	* Requires [FFTW3](http://www.fftw.org)
 9 | 		* For FFTW3, use `./configure --enable-threads --enable-openmp` to make sure you have the multithreaded FFTW3 libraries
10 | 	* Install NFFT using `./configure --enable-openmp && make && sudo make install`
11 | * [pyNFFT](https://pypi.python.org/pypi/pyNFFT)
12 | 	* Do not run `pip install pynfft`; this will not work.
13 | 	* First install NFFT (version <= 3.2.4)
14 | 	* Then run `pip download pynfft && tar xvf pyNFFT-<VERSION>-tar.gz && cd pyNFFT-<VERSION>/`
15 | 	* From this directory, you may need to manually edit the `setup.py` file to add relevant directories to `include_dirs` (like `/usr/local/include`)
16 | 	* Run `python setup.py install` once this is done.
17 | * [gatspy](https://pypi.python.org/pypi/gatspy)
18 | 	* Python library, for unit testing. Includes `N^2` template periodogram
19 | * The 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | # Byte-compiled / optimized / DLL files
 2 | __pycache__/
 3 | *.py[cod]
 4 | 
 5 | # C extensions
 6 | *.so
 7 | 
 8 | # Distribution / packaging
 9 | .Python
10 | env/
11 | build/
12 | develop-eggs/
13 | dist/
14 | downloads/
15 | eggs/
16 | .eggs/
17 | lib/
18 | lib64/
19 | parts/
20 | sdist/
21 | var/
22 | *.egg-info/
23 | .installed.cfg
24 | *.egg
25 | 
26 | # PyInstaller
27 | #  Usually these files are written by a python script from a template
28 | #  before PyInstaller builds the exe, so as to inject date/other infos into it.
29 | *.manifest
30 | *.spec
31 | 
32 | # Installer logs
33 | pip-log.txt
34 | pip-delete-this-directory.txt
35 | 
36 | # Unit test / coverage reports
37 | htmlcov/
38 | .tox/
39 | .coverage
40 | .coverage.*
41 | .cache
42 | nosetests.xml
43 | coverage.xml
44 | *,cover
45 | 
46 | # Translations
47 | *.mo
48 | *.pot
49 | 
50 | # Django stuff:
51 | *.log
52 | 
53 | # Sphinx documentation
54 | docs/_build/
55 | 
56 | # PyBuilder
57 | target/
58 | 
59 | # emacs backups
60 | *~
61 | \#*\#
62 | 
63 | .ipynb_checkpoints
64 | .idea/*
65 | tools/repos
66 | Untitled*.ipynb
67 | 
68 | # vim backups
69 | *.swp
70 | 
71 | # LaTeX
72 | *.aux
73 | *.pdf
74 | 
75 | # misc
76 | scripts/saved_results
77 | .DS_Store
78 | 


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import io
 4 | import os
 5 | import re
 6 | 
 7 | try:
 8 |     from setuptools import setup
 9 | except ImportError:
10 |     from distutils.core import setup
11 | 
12 | 
13 | def read(path, encoding='utf-8'):
14 |     path = os.path.join(os.path.dirname(__file__), path)
15 |     with io.open(path, encoding=encoding) as fp:
16 |         return fp.read()
17 | 
18 | 
19 | def version(path):
20 |     """Obtain the packge version from a python file e.g. pkg/__init__.py
21 | 
22 |     See <https://packaging.python.org/en/latest/single_source_version.html>.
23 |     """
24 |     version_file = read(path)
25 |     version_match = re.search(r"""^__version__ = ['"]([^'"]*)['"]""",
26 |                               version_file, re.M)
27 |     if version_match:
28 |         return version_match.group(1)
29 |     raise RuntimeError("Unable to find version string.")
30 | 
31 | 
32 | VERSION = version('pyftp/__init__.py')
33 | 
34 | setup(name='pyftp',
35 |       version=VERSION,
36 |       description="Fast template periodogram",
37 |       author='John Hoffman',
38 |       author_email='jah5@princeton.edu',
39 |       url='https://github.com/PrincetonUniversity/FastTemplatePeriodogram',
40 |       package_dir={'pyftp' : './pyftp' },
41 |       packages=['pyftp'],
42 |       requires=[ 'numpy', 'scipy', 'pynfft' ],
43 | )
44 | 


--------------------------------------------------------------------------------
/pyftp/gatspy_template_modeler.py:
--------------------------------------------------------------------------------
 1 | from gatspy.periodic.template_modeler import BaseTemplateModeler
 2 | 
 3 | class GatspyTemplateModeler(BaseTemplateModeler):
 4 | 	"""
 5 | 	Convenience class for the gatspy BaseTemplateModeler
 6 | 	"""
 7 | 	def __init__(self, templates=None, **kwargs):
 8 | 		assert(not templates is None)
 9 | 
10 | 		self.ftp_templates = {}
11 | 		self.add_templates(templates)
12 | 		
13 | 
14 | 		#if len(self.ftp_templates) > 0:
15 | 		BaseTemplateModeler.__init__(self, **kwargs)
16 | 
17 | 
18 | 	def _template_ids(self):
19 | 		return self.ftp_templates.keys()
20 | 
21 | 	def add_template(self, template, template_id=None):
22 | 		if template_id is None:
23 | 			if template.template_id is None:
24 | 				i = 0
25 | 				while i in self.ftp_templates:
26 | 					i+= 1
27 | 				self.ftp_templates[i] = template
28 | 			else:
29 | 				self.ftp_templates[template.template_id] = template
30 | 		else:
31 | 			self.ftp_templates[template_id] = template
32 | 		return self
33 | 
34 | 	def add_templates(self, templates, template_ids=None):
35 | 
36 | 		if isinstance(templates, dict):
37 | 			for ID, template in templates.iteritems():
38 | 				self.add_template(template, template_id=ID)
39 | 
40 | 		elif isinstance(templates, list):
41 | 			if template_ids is None:
42 | 
43 | 				for template in templates:
44 | 					self.add_template(template)
45 | 			else:
46 | 				for ID, template in zip(template_ids, templates):
47 | 					self.add_template(template, template_id=ID)
48 | 
49 | 		elif not hasattr(templates, '__iter__'):
50 | 			self.add_template(templates, template_id=template_ids)
51 | 
52 | 		else:
53 | 			raise Exception("did not recognize type of 'templates' passed to add_templates")
54 | 
55 | 		return self
56 | 
57 | 	def _get_template_by_id(self, template_id):
58 | 		assert(template_id in self.ftp_templates)
59 | 		t = self.ftp_templates[template_id]
60 | 
61 | 		return t.phase, t.y


--------------------------------------------------------------------------------
/pyftp/rrlyrae.py:
--------------------------------------------------------------------------------
 1 | from modeler import FastTemplateModeler, Template, approximate_template, rms_resid_over_rms_fast
 2 | import cPickle as pickle
 3 | import gatspy.datasets.rrlyrae as rrl
 4 | import os
 5 | 
 6 | def get_rrlyr_templates(template_fname=None, errfunc=rms_resid_over_rms_fast, 
 7 | 	                    stop=1E-2, filts='r', nharmonics=None, redo=False):
 8 | 	"""
 9 | 	read templates for a given filter(s) from 
10 | 	the gatspy.datasets.rrlyrae package, approximate each 
11 | 	template with the minimal number of harmonics such 
12 | 	that `errfunc(Cn, Sn, T, Y)` < `stop` and save values
13 | 	in a pickled file given by template_fname if template_fname
14 | 	is not None.
15 | 	"""
16 | 	
17 | 	# Obtain RR Lyrae templates
18 | 	templates = rrl.fetch_rrlyrae_templates()
19 | 	
20 | 	# Select the right ID's
21 | 	IDs = [ t for t in templates.ids if t[-1] in list(filts) ]
22 | 
23 | 	# Get (phase, amplitude) data for each template
24 | 	Ts, Ys = zip(*[ templates.get_template(ID) for ID in IDs ])
25 | 
26 | 	ftp_templates = None
27 | 	if not template_fname is None \
28 | 	      and os.path.exists(template_fname) \
29 | 	      and not redo:
30 | 		ftp_templates = pickle.load(open(template_fname, 'rb'))
31 | 	else:
32 | 		#print "loading ftp_templates"
33 | 		ftp_templates = { ID : Template(phase=T, y=Y, errfunc=errfunc, 
34 | 			                            nharmonics=nharmonics, stop=stop).precompute() \
35 | 		                            for ID, T, Y in zip(IDs, Ts, Ys) }
36 | 		#print "done"
37 | 		if not template_fname is None:
38 | 			pickle.dump(ftp_templates, open(template_fname, 'wb'))
39 | 
40 | 	return ftp_templates
41 | 
42 | 
43 | class FastRRLyraeTemplateModeler(FastTemplateModeler):
44 | 	"""
45 | 	RR Lyrae Template modeler
46 | 
47 | 	Parameters
48 | 	----------
49 | 	x: np.ndarray, list
50 | 		independent variable (time)
51 | 	y: np.ndarray, list
52 | 		array of observations
53 | 	err: np.ndarray
54 | 		array of observation uncertainties
55 | 	filts: str (default: 'r')
56 | 		string containing one or more of 'ugriz'
57 | 	loud: boolean (default: True), optional
58 | 		print status
59 | 	ofac: float, optional (default: 10)
60 | 		oversampling factor -- higher values of ofac decrease 
61 | 		the frequency spacing (by increasing the size of the FFT)
62 | 	hfac: float, optional (default: 1)
63 | 		high-frequency factor -- higher values of hfac increase
64 | 		the maximum frequency of the periodogram at the 
65 | 		expense of larger frequency spacing.
66 | 	stop: float, optional (default: 2E-2)
67 | 		will pick minimum number of harmonics such that 
68 | 		rms(trunc(template) - template) / rms(template) < stop
69 | 	nharmonics: None or int, optional (default: None)
70 | 		Keep a constant number of harmonics
71 | 	template_fname: str, optional
72 | 		Filename to load/save template
73 | 	errfunc: callable, optional (default: rms_resid_over_rms)
74 | 		A function returning some measure of error resulting
75 | 		from approximating the template with a given number 
76 | 		of harmonics
77 | 	redo : bool (optional)
78 | 		Recompute templates even if they are saved
79 | 
80 | 	"""
81 | 	def __init__(self, filts='ugriz', redo=False, **kwargs):
82 | 		FastTemplateModeler.__init__(self, **kwargs)
83 | 		self.filts = filts
84 | 		self.params['redo'] = redo
85 | 		self.params['filts'] = self.filts
86 | 		self._load_templates()
87 | 
88 | 	def _load_templates(self):
89 | 		pars = [ 'filts', 'template_fname', 'errfunc', 'stop', 'nharmonics', 'redo' ]
90 | 		kwargs = { par : self.params[par] for par in pars if par in self.params }
91 | 		self.templates = get_rrlyr_templates(**kwargs)
92 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | Fast Template Periodogram
  2 | =========================
  3 | 
  4 | John Hoffman, Jake Vanderplas
  5 | (c) 2016
  6 | 
  7 | Description
  8 | -----------
  9 | 
 10 | ![examples](plots/templates_and_periodograms.png "Examples")
 11 | 
 12 | The Fast Template Periodogram extends the Generalized Lomb-Scargle
 13 | periodogram ([Zechmeister and Kurster 2009](http://adsabs.harvard.edu/cgi-bin/bib_query?arXiv:0901.2573])) 
 14 | for arbitrary (periodic) signal shapes. A template is first approximated
 15 | by a truncated Fourier series of length `H`. The Non-equispaced Fast Fourier Transform
 16 | [NFFT](https://www-user.tu-chemnitz.de/~potts/nfft/) is used
 17 | to efficiently compute frequency-dependent sums.
 18 | 
 19 | Because the FTP is a non-linear extension of the GLS, the zeros of 
 20 | a polynomial of order `~6H` must be computed at each frequency.
 21 | 
 22 | The [gatspy](http://www.astroml.org/gatspy/) library has an implementation of
 23 | both single and multiband template fitting, however this implementation
 24 | uses non-linear least-squares fitting to compute the optimal parameters 
 25 | (amplitude, phase, constant offset) of the template fit at each frequency. That
 26 | process scales as `N_obs*N_f`, where `N` is the number of observations and
 27 | `N_f` is the number of frequencies at which to calculate the periodogram.
 28 | 
 29 | This process is extremely slow. [Sesar et al. (2016)](https://arxiv.org/abs/1611.08596) applied a similar
 30 | template fitting procedure to multiband Pan-STARRS photometry and found that
 31 | (1) template fitting was significantly more accurate for estimating periods
 32 | of RR Lyrae stars, but that (2) it required a substantial amount of 
 33 | computational resources to perform these fits.
 34 | 
 35 | However, if the templates are sufficiently smooth (or can be adequately 
 36 | approximated by a sufficiently smooth template) the template can be
 37 | represented by a short truncated Fourier series of length `H`. Using this 
 38 | representation, the optimal parameters (amplitude, phase, offset) 
 39 | of the template fit can then be found exactly after finding the roots of 
 40 | a polynomial at each trial frequency.
 41 | 
 42 | The coefficients of these polynomials involve sums that can be efficiently
 43 | computed with (non-equispaced) fast Fourier transforms. These sums
 44 | can be computed in `HN_f log(HN_f)` time.
 45 | 
 46 | In its current state, the root-finding procedure is the rate limiting step.
 47 | This unfortunately means that for now the fast template periodogram scales as 
 48 | `N_f*(H^4)`. We are working to reduce the computation time so that the entire 
 49 | procedure scales as `HN_f log(HN_f)` for reasonable values of `H` (`< 10`).
 50 | 
 51 | However, even for small cases where `H=6` and `N_obs=10`, this procedure is 
 52 | about twice as fast as the `gatspy` template modeler. And, the speedup over
 53 | `gatspy` grows linearly with `N_obs`! 
 54 | 
 55 | 
 56 | How is this different than the multi-harmonic periodogram?
 57 | ----------------------------------------------------------
 58 | 
 59 | 
 60 | The multi-harmonic periodogram ([Schwarzenberg-Czerny (1996)](http://iopscience.iop.org/article/10.1086/309985/meta)) is another 
 61 | extension of Lomb-Scargle that fits a truncated Fourier series to the data 
 62 | at each trial frequency. This is nice if you have a strong non-sinusoidal signal 
 63 | and a large dataset. This algorithm can also be made to scale as
 64 | `HN_f logHN_f` ([Palmer 2009](http://iopscience.iop.org/article/10.1088/0004-637X/695/1/496/meta)).
 65 | 
 66 | However, the multi-harmonic periodogram is fundamentally different than template fitting. 
 67 | In template fitting, the relative amplitudes and phases of the Fourier series are *fixed*. 
 68 | In a multi-harmonic periodogram, the relative amplitudes and phases of the Fourier series are 
 69 | *free parameters*. These extra free parameters mean that (1) you need a larger
 70 | number of observations `N_obs` to reach the same signal to noise, and (2) you are
 71 | more likely to detect a multiple of the true frequency. For a discussion of this
 72 | effect, possible remedies with Tikhonov regularization, and an illuminating review
 73 | of periodograms in general, see [Vanderplas et al. (2015)](http://adsabs.harvard.edu/abs/2015ApJ...812...18V).
 74 | 
 75 | Requirements
 76 | ------------
 77 | 
 78 | * [pyNFFT](https://pypi.python.org/pypi/pyNFFT) is required, but this program is thorny to install.
 79 | 	* Do NOT use `pip install pynfft`; this will almost definitely not work.
 80 | 	* You need to install [NFFT](https://www-user.tu-chemnitz.de/~potts/nfft/) <= 3.2.4 (NOT the latest version)
 81 | 	* use `./configure --enable-openmp` when installing NFFT
 82 | 	* NFFT also requires [FFTW3](http://www.fftw.org)
 83 | 	* You may have to manually add the directory containing NFFT `.h` files to the `include_dirs` variable in the pyNFFT `setup.py` file.
 84 | * The [Scipy stack](http://www.scipy.org/install.html)
 85 | * [gatspy](http://www.astroml.org/gatspy/) 
 86 | 	* RRLyrae modeler needs this to obtain templates
 87 | 	* Used to check accuracy/performance of the FTP
 88 | 
 89 | Installation
 90 | ------------
 91 | These instructions assume a `*nix` operating system (i.e. Mac, Linux, BSD, etc.). 
 92 | 
 93 | #### If you have a **Mac** operating system
 94 | 
 95 | * I have not tested the default `clang` compilers; I would highly recommend 
 96 |   installing [macports]() and installing `gcc` compilers.
 97 | 	`sudo port install gcc`
 98 | * After this, you may need to 'select' the gcc compilers: run 
 99 |     `sudo port select --list gcc`
100 |   then pick the option that is not "none" by running 
101 |     `sudo port select --set gcc mp-gcc6`
102 |   where `mp-gcc6` is the option besides `none` (it may be different if you 
103 |   install another version).
104 | * If you run into any other trouble or find other dependencies, please let us know!
105 | 
106 | #### Installing FFTW3
107 | 
108 | * First download the FFTW3 [source](http://www.fftw.org), (the latest version should be fine, I have `3.3.5` on my machine)
109 | * Unzip the downloaded `.tar.gz` file
110 | * `./configure --enable-openmp --enable-threads` from inside the directory
111 | * `sudo make install`
112 | 
113 | #### Installing NFFT
114 | 
115 | * Download [NFFT](https://www-user.tu-chemnitz.de/~potts/nfft/) **version <= 3.2.4** (NOT the latest version)
116 | * unzip `.tar.gz` file
117 | * `./configure --enable-openmp --with-fftw3-includedir=/usr/local/include --with-fftw3-libdir=/usr/local/lib`
118 | 	* optionally, use `--with-window=gaussian`, which should be faster (I haven't actually tested this).
119 | * `sudo make install`
120 | 
121 | #### Installing pyNFFT
122 | * `pip download pynfft`
123 | * unzip `.tar.gz` file
124 | * open the `setup.py` file in a text editor, add `/usr/local/include` to the `include_dirs` variable; i.e., change
125 | 	```python
126 | 	# Define utility functions to build the extensions
127 | 	def get_common_extension_args():
128 | 	    import numpy
129 | 	    common_extension_args = dict(
130 | 	        libraries=['nfft3_threads', 'nfft3', 'fftw3_threads', 'fftw3', 'm'],
131 | 	        library_dirs=[],
132 | 	        include_dirs=[numpy.get_include()], #THIS LINE
133 | 	```
134 | 
135 | 	to 
136 | 
137 | 	```python
138 | 	# Define utility functions to build the extensions
139 | 	def get_common_extension_args():
140 | 	    import numpy
141 | 	    common_extension_args = dict(
142 | 	        libraries=['nfft3_threads', 'nfft3', 'fftw3_threads', 'fftw3', 'm'],
143 | 	        library_dirs=[],
144 | 	        include_dirs=[numpy.get_include(), '/usr/local/include'], #added /usr/local/include
145 | 	```
146 | 
147 | * then `python setup.py install`.
148 | 
149 | #### Installing gatspy
150 | * `pip install gatspy` should work!
151 | 
152 | #### Installing this code
153 | * `git clone https://github.com/PrincetonUniversity/FastTemplatePeriodogram.git`
154 | * Change into the newly created `FastTemplatePeriodogram` directory
155 | * `python setup.py install`
156 | 
157 | Example usage
158 | -------------
159 | 
160 | ```python
161 | from pyftp import modeler
162 | import numpy as np
163 | 
164 | # define your template by its Fourier coefficients
165 | cn = np.array([ 1.0, 0.5, 0.2 ])
166 | sn = np.array([ 1.0, -0.2, 0.5 ])
167 | 
168 | # create a Template object
169 | template = modeler.Template(cn=cn, sn=sn)
170 | 
171 | # Precompute some quantities for speed
172 | template.precompute()
173 | 
174 | # create a FastTemplateModeler
175 | model = modeler.FastTemplateModeler()
176 | 
177 | # add the template(s) to your modeler
178 | model.add_templates([ template ])
179 | 
180 | # get some data
181 | t, mag, err = get_your_data()
182 | 
183 | # feed the data to the modeler
184 | model.fit(t, mag, err)
185 | 
186 | # get your template periodogram!
187 | # ofac -- the oversampling factor: df = 1 / (ofac * (max(t) - min(t)))
188 | # hfac -- the nyquist factor: f_max = hfac * N_obs / (max(t) - min(t))
189 | freqs, periodogram = model.periodogram(ofac=20, hfac=1)
190 | 
191 | # What are the parameters of the best fit?
192 | template, params = model.get_best_model()
193 | ```
194 | 
195 | There is also a built-in RR Lyrae modeler that pulls RR Lyrae templates 
196 | from Gatspy (templates are from [Sesar et al. (2010)](http://iopscience.iop.org/article/10.1088/0004-637X/708/1/717/meta)).
197 | 
198 | ```python
199 | from pyftp import rrlyrae
200 | 
201 | # create a FastTemplateModeler
202 | model = rrlyrae.FastRRLyraeTemplateModeler(filts='r')
203 | 
204 | # get some data
205 | t, mag, err = get_your_data()
206 | 
207 | # feed the data to the modeler
208 | model.fit(t, mag, err)
209 | 
210 | # get your template periodogram!
211 | freqs, periodogram = model.periodogram(ofac=20, hfac=1)
212 | 
213 | ```
214 | 
215 |  
216 | Updates
217 | -------
218 | 
219 | * See the [issues](https://github.com/PrincetonUniversity/FastTemplatePeriodogram/issues) 
220 | section for known bugs! You can also submit bugs through this interface.
221 | 
222 | Timing
223 | ------
224 | 
225 | ![timing](plots/timing_vs_ndata.png "Timing compared to gatspy")
226 | 
227 | The Fast Template Periodogram seems to do better than Gatspy
228 | for virtually all reasonable cases (reasonable meaning a small-ish
229 | number of harmonics are needed to accurately approximate the template,
230 | small-ish meaning less than about 10).
231 | 
232 | It may be surprising that FTP appears to scale as `NH`, instead of
233 | `NH log NH`, but that's because the NFFT is not the limiting factor (yet).
234 | Most of the computation time is spent calculating polynomial coefficients,
235 | and this computation scales as roughly `NH^4`. 
236 | 
237 | ![timingnh](plots/timing_vs_nharm.png "Timing vs harmonics")
238 | 
239 | The FTP scales sub-linearly to linearly with the number of harmonics `H`
240 | for `H < 10`, and for larger number of harmonics scales as `H^4`. This
241 | is the main limitation of FTP.
242 | 
243 | 
244 | Accuracy
245 | --------
246 | 
247 | Compared with the Gatspy template modeler, the FTP provides improved accuracy as well as speed. 
248 | For large values of `p(freq)`, the FTP correlates strongly with the Gatspy template algorithm; however,
249 | since Gatspy uses non-linear function fitting (Levenberg-Marquardt), the predicted value for
250 | `p(freq)` may not be optimal if the data is poorly modeled by the template. FTP, on the other 
251 | hand, solves for the optimal solution directly, and thus tends to find equally good or 
252 | better solutions when `p(freq)` is small.
253 | 
254 | ![corrwithgats](plots/correlation_with_gatspy.png "Correlation to gatspy")
255 | ![accuracy](plots/correlation_with_large_H.png "How many harmonics do we need?")
256 | 
257 | For some frequencies, the Gatspy modeler finds no improvement over a constant fit 
258 | (`p_gatspy(freq) = 0`). However, for these frequencies, the FTP consistently finds better 
259 | solutions.
260 | 
261 | At frequencies where the template models the data at least moderately well (`p(freq) ~> 0.01`),
262 | the Gatspy modeler and the FTP are in good agreement.
263 | 
264 | Assuming, then, that the FTP is indeed producing the "correct" periodogram, we can then
265 | ask how many harmonics we must use in order to achieve an estimate of the periodogram to
266 | a given accuracy.
267 | 
268 | TODO
269 | ----
270 | 
271 | * Extending this to a multiband template periodogram is a top priority after fixing bugs and
272 |   providing adequate documentation!
273 | * Unit testing
274 | * Improve performance!
275 | 


--------------------------------------------------------------------------------
/pyftp/fast_template_periodogram.py:
--------------------------------------------------------------------------------
  1 | """ 
  2 | FAST TEMPLATE PERIODOGRAM (prototype)
  3 | 
  4 | Uses NFFT to make the template periodogram scale as H*N log(H*N) 
  5 | where H is the number of harmonics in which to expand the template and
  6 | N is the number of observations.
  7 | 
  8 | Previous routines scaled as N^2 and used non-linear least-squares
  9 | minimization (e.g. Levenberg-Marquardt) at each frequency.
 10 | 
 11 | (c) John Hoffman 2016
 12 | 
 13 | """
 14 | import sys
 15 | import os
 16 | import cmath
 17 | from math import *
 18 | from time import time
 19 | import numpy as np
 20 | from collections import namedtuple
 21 | from scipy.special import eval_chebyt,\
 22 |                           eval_chebyu
 23 | 
 24 | from pynfft.nfft import NFFT
 25 | from pseudo_poly import compute_polynomial_tensors,\
 26 |                         get_polynomial_vectors,\
 27 |                         compute_zeros
 28 | 
 29 | 
 30 | Summations = namedtuple('Summations', [ 'C', 'S', 'YC', 'YS', 
 31 |                                         'CCh', 'CSh', 'SSh'])
 32 | 
 33 | ModelFitParams = namedtuple('ModelFitParams', [ 'a', 'b', 'c', 'sgn' ])
 34 | 
 35 | # shortcuts for the Chebyshev polynomials
 36 | Un = lambda n, x : eval_chebyu(n, x) if n >= 0 else 0
 37 | Tn = lambda n, x : eval_chebyt(n, x) if n >= 0 else 0
 38 | 
 39 | # A (or B) and dA (dB) expressions
 40 | Afunc    = lambda n, x, p, q, sgn=1 :      \
 41 |             p * Tn(n, x) - sgn * q * Un(n-1, x) * np.sqrt(1 -  x*x) 
 42 | 
 43 | dAfunc   = lambda n, x, p, q, sgn=1 : \
 44 |             n * (p * Un(n-1, x) + sgn * q * Tn(n, x) / np.sqrt(1 -  x*x))
 45 | 
 46 | 
 47 | 
 48 | # returns vector expressions of A, B and their derivatives
 49 | Avec        = lambda x, c, s, sgn=1 :  np.array([  \
 50 |                           Afunc(n, x, c[n-1],  s[n-1], sgn=sgn) \
 51 |                                  for n in range(1, len(s)+1) ])
 52 | Bvec        = lambda x, c, s, sgn=1 :  np.array([ \
 53 |                           Afunc(n, x, s[n-1], -c[n-1], sgn=sgn) \
 54 |                                  for n in range(1, len(s)+1) ])
 55 | dAvec       = lambda x, c, s, sgn=1 :  np.array([ \
 56 |                          dAfunc(n, x, c[n-1],  s[n-1], sgn=sgn) \
 57 |                                  for n in range(1, len(s)+1) ])
 58 | dBvec       = lambda x, c, s, sgn=1 :  np.array([ \
 59 |                          dAfunc(n, x, s[n-1], -c[n-1], sgn=sgn) \
 60 |                                  for n in range(1, len(s)+1) ])
 61 | 
 62 | def getAB(b, cn, sn):
 63 |     """ efficient computation of A, B vectors for both +/- sin(wtau) """
 64 |     SQ =  sqrt(1 - min([ 1-1E-8, b*b ]))
 65 |     H = len(cn)
 66 |     TN = np.array([ Tn(n+1, b) for n in range(H) ])
 67 |     UN = np.array([ Un(n, b) * SQ for n in range(H) ])
 68 |     snUN, cnUN = sn * UN, cn * UN
 69 |     Ap = cn * TN - snUN
 70 |     An = Ap + 2 * snUN
 71 | 
 72 |     Bp = sn * TN + cnUN
 73 |     Bn = Bp - 2 * cnUN
 74 |     
 75 |     return Ap, An, Bp, Bn
 76 | 
 77 | def M(t, b, omega, cn, sn, sgn=1):
 78 |     """ evaluate the shifted template at a given time """
 79 | 
 80 |     A = Avec(b, cn, sn, sgn=sgn)
 81 |     B = Bvec(b, cn, sn, sgn=sgn)
 82 |     Xc = np.array([ np.cos(n * omega * t) for n in range(1, len(cn)+1) ])
 83 |     Xs = np.array([ np.sin(n * omega * t) for n in range(1, len(cn)+1) ])
 84 | 
 85 |     return np.dot(A, Xc) + np.dot(B, Xs)
 86 | 
 87 | def fitfunc(x, sgn, omega, cn, sn, a, b, c):
 88 |     """ aM(t - tau) + c """
 89 |     m = lambda b_ : lambda x_ : M(x_, b_, omega, cn, sn, sgn=sgn)
 90 |     return a * np.array(map(m(b), x)) + c
 91 | 
 92 | def weights(err):
 93 |     """ converts sigma_i -> w_i \equiv (1/W) * (1/sigma_i^2) """
 94 |     w = np.power(err, -2)
 95 |     w/= np.sum(w)
 96 |     return w
 97 | 
 98 | def get_a_from_b(b, cn, sn, sums, A=None, B=None, 
 99 |                  AYCBYS=None, sgn=1):
100 |     """ return the optimal amplitude & offset for a given value of b """
101 | 
102 |     if A is None:
103 |         A = Avec(b, cn, sn, sgn=sgn)
104 |     if B is None:
105 |         B = Bvec(b, cn, sn, sgn=sgn)
106 |     if AYCBYS is None:
107 |         AYCBYS = np.dot(A, sums.YC) + np.dot(B, sums.YS)
108 | 
109 |     a = AYCBYS / (       np.einsum('i,j,ij', A, A, sums.CCh) \
110 |                    + 2 * np.einsum('i,j,ij', A, B, sums.CSh) \
111 |                    +     np.einsum('i,j,ij', B, B, sums.SSh))
112 |     return a
113 | 
114 | 
115 | def shift_t_for_nfft(t, ofac):
116 |     """ transforms times to [-1/2, 1/2] interval """
117 | 
118 |     r = ofac * (max(t) - min(t))
119 |     eps = 1E-5
120 |     a = 0.5 - eps
121 | 
122 |     return 2 * a * (t - min(t)) / r - a
123 | 
124 | def compute_summations(x, y, err, H, ofac=5, hfac=1):
125 |     """ 
126 |     Computes C, S, YC, YS, CC, CS, SS using
127 |     pyNFFT
128 |     """
129 |     # convert errs to weights
130 |     w = weights(err)
131 | 
132 |     # number of frequencies (+1 for 0 freq)
133 |     N = int(floor(0.5 * len(x) * ofac * hfac))
134 |     
135 |     # shift times to [ -1/2, 1/2 ]
136 |     t = shift_t_for_nfft(x, ofac)
137 | 
138 |     # compute angular frequencies
139 |     T = max(x) - min(x)
140 |     df = 1. / (ofac * T)
141 | 
142 |     omegas = np.array([ 2 * np.pi * i * df for i in range(1, N) ])
143 |     
144 |     # compute weighted mean
145 |     ybar = np.dot(w, y)
146 | 
147 |     # subtract off weighted mean
148 |     u = np.multiply(w, y - ybar)
149 |     
150 |     # weighted variance
151 |     YY = np.dot(w, np.power(y - ybar, 2))
152 | 
153 |     # plan NFFT's and precompute
154 |     plan = NFFT(4 * H * N, len(x))
155 |     plan.x = t
156 |     plan.precompute()
157 | 
158 |     plan2 = NFFT(2 * H * N, len(x))
159 |     plan2.x = t
160 |     plan2.precompute()
161 | 
162 |     # evaluate NFFT for w
163 |     plan.f = w
164 |     f_hat_w = plan.adjoint()[2 * H * N + 1:]
165 | 
166 |     # evaluate NFFT for y - ybar
167 |     plan2.f = u
168 |     f_hat_u = plan2.adjoint()[H * N + 1:]
169 | 
170 |     all_computed_sums = []
171 |     # Now compute the summation values at each frequency
172 |     for i in range(N-1):
173 | 
174 |         computed_sums = Summations(C=np.zeros(H),
175 |                                    S=np.zeros(H),
176 |                                    YC=np.zeros(H),
177 |                                    YS=np.zeros(H),
178 |                                    CCh=np.zeros((H,H)),
179 |                                    CSh=np.zeros((H,H)),
180 |                                    SSh=np.zeros((H,H)))
181 | 
182 |         C_, S_ = np.zeros(2 * H), np.zeros(2 * H)
183 |         for j in range(2 * H):
184 |             # This sign factor is necessary 
185 |             # but I don't know why.
186 |             s = (-1 if ((i % 2)==0) and ((j % 2) == 0) else 1)
187 |             C_[j] =  f_hat_w[(j+1)*(i+1)-1].real * s
188 |             S_[j] =  f_hat_w[(j+1)*(i+1)-1].imag * s
189 |             if j < H:
190 |                 computed_sums.YC[j] =  f_hat_u[(j+1)*(i+1)-1].real * s
191 |                 computed_sums.YS[j] =  f_hat_u[(j+1)*(i+1)-1].imag * s
192 | 
193 |         for j in range(H):
194 |             for k in range(H):
195 |                 
196 |                 Sn, Cn = None, None
197 | 
198 |                 if j == k:
199 |                     Sn = 0
200 |                     Cn = 1
201 |                 else:
202 |                     Sn =  np.sign(k - j) * S_[int(abs(k - j)) - 1] 
203 |                     Cn =  C_[int(abs(k - j)) - 1]
204 | 
205 |                 Sp = S_[j + k + 1]
206 |                 Cp = C_[j + k + 1]
207 | 
208 |                 computed_sums.CCh[j][k] = 0.5 * ( Cn + Cp ) - C_[j] * C_[k]
209 |                 computed_sums.CSh[j][k] = 0.5 * ( Sn + Sp ) - C_[j] * S_[k]
210 |                 computed_sums.SSh[j][k] = 0.5 * ( Cn - Cp ) - S_[j] * S_[k]
211 | 
212 |         computed_sums.C[:] = C_[:H]
213 |         computed_sums.S[:] = S_[:H]
214 | 
215 |         all_computed_sums.append(computed_sums)
216 |         
217 |     return omegas, all_computed_sums, YY, w, ybar
218 | 
219 | 
220 | def fast_template_periodogram(x, y, err, cn, sn, ofac=10, hfac=1, 
221 |                               pvectors=None, ptensors=None,
222 |                               omegas=None, summations=None, YY=None, w=None, 
223 |                               ybar=None, loud=False, return_best_fit_pars=False,
224 |                               allow_negative_amplitudes=True):
225 | 
226 |     H = len(cn)
227 |     
228 |     if pvectors is None:
229 |         pvectors = get_polynomial_vectors(cn, sn, sgn=  1)
230 | 
231 |     if ptensors is None:
232 |         ptensors = compute_polynomial_tensors(*pvectors)
233 | 
234 |     t0 = None
235 |     if loud: 
236 |         t0 = time()
237 | 
238 |     if summations is None:
239 |         # compute sums using NFFT
240 |         omegas, summations, YY, w, ybar = \
241 |             compute_summations(x, y, err, H, ofac=ofac, hfac=hfac)
242 | 
243 |     if loud: 
244 |         dt = time() - t0
245 |         print "*", dt / len(omegas), " s / freqs to get summations"
246 | 
247 |     FTP = np.zeros(len(omegas))
248 |     best_fit_pars = []
249 | 
250 |     # Iterate through frequency values (sums contains C, S, YC, ...)
251 |     for i, (omega, sums) in enumerate(zip(omegas, summations)):
252 |                
253 |         if loud and i == 0: 
254 |             t0 = time()
255 | 
256 |         # Get zeros of polynomial (zeros are same for both +/- sinwtau)
257 |         zeros = compute_zeros(ptensors, sums, loud=(i==0 and loud))
258 | 
259 |         # Check boundaries, too
260 |         if not  1 in zeros: zeros.append(1)
261 |         if not -1 in zeros: zeros.append(-1)
262 |         
263 |         if loud and i == 0:
264 |             dt = time() - t0
265 |             print "*", dt, " s / freqs to get zeros"
266 |             t0 = time()
267 | 
268 |         bfpars = None
269 |         max_pz = None
270 | 
271 |         # compute phase shift due to non-zero x[0]
272 |         tshift = (omega * x[0]) % (2 * np.pi)
273 | 
274 |         for bz in zeros:
275 |             for sgn_ in [ -1, 1 ]:
276 |                 A = Avec(bz, cn, sn, sgn=sgn_)
277 |                 B = Bvec(bz, cn, sn, sgn=sgn_)
278 | 
279 |                 AYCBYS = np.dot(A, sums.YC[:H]) + np.dot(B, sums.YS[:H])
280 |                 ACBS   = np.dot(A, sums.C[:H])  + np.dot(B, sums.S[:H])
281 | 
282 |                 # Obtain amplitude for a given b=cos(wtau) and sign(sin(wtau))
283 |                 amplitude = get_a_from_b(bz, cn, sn, sums, A=A, B=B, AYCBYS=AYCBYS)
284 |     
285 |                 # Skip negative amplitude solutions
286 |                 if amplitude < 0 and not allow_negative_amplitudes: continue
287 | 
288 |                 # Compute periodogram
289 |                 pz = amplitude * AYCBYS / YY
290 | 
291 |                 # Record the best-fit parameters for this template 
292 |                 if max_pz is None or pz > max_pz:
293 |                     if return_best_fit_pars:
294 | 
295 |                         # Get offset
296 |                         c = ybar - amplitude * ACBS
297 | 
298 |                         # Correct for the fact that we've shifted t -> t - t0
299 |                         # during the NFFT
300 |                         wtauz = np.arccos(bz) 
301 |                         if sgn_ < 0:
302 |                             wtauz = 2 * np.pi - wtauz
303 |                         wtauz += tshift
304 | 
305 |                         # Store best-fit parameters
306 |                         bfpars = ModelFitParams(a=amplitude, b=np.cos(wtauz), c=c, sgn=int(np.sign(np.sin(wtauz))))
307 | 
308 |                     max_pz = pz
309 | 
310 |         if return_best_fit_pars and bfpars is None:
311 |             # Could not find any positive amplitude solutions ... usually means this is a poor fit,
312 |             # so instead of a more exhaustive search for the best positive amplitude solution, 
313 |             # we simply set parameters to 0 and periodogram to 0
314 |             FTP[i] = 0
315 |             bfpars = ModelFitParams(a=0, b=1, c=ybar, sgn=1)
316 |             raise Warning("could not find positive amplitude solution for omega = %.3e (ftp[%d])"%(omega, i))
317 | 
318 | 
319 |         if loud and i == 0:
320 |             dt = time() - t0
321 |             print "*", dt, " s / freq to investigate each zero"
322 | 
323 |         # Periodogram value is the global max of P_{-} and P_{+}.
324 |         FTP[i] = max_pz
325 |         if return_best_fit_pars:
326 |             best_fit_pars.append(bfpars)
327 |             
328 |     if not return_best_fit_pars:
329 |         return omegas / (2 * np.pi), FTP
330 |     else:
331 |         return omegas / (2 * np.pi), FTP, best_fit_pars
332 |     
333 | 


--------------------------------------------------------------------------------
/pyftp/pseudo_poly.py:
--------------------------------------------------------------------------------
  1 | import numpy as np
  2 | from time import time
  3 | from scipy.special import chebyu, chebyt
  4 | from numbers import Number, Integral
  5 | from scipy.optimize import newton, brentq
  6 | from numpy.polynomial.polynomial import Polynomial
  7 | import numpy.polynomial.polynomial as pol
  8 | 
  9 | 
 10 | # ZERO FINDING UTILITIES. #################################################
 11 | # Using Sturm chains and bracketing zeros
 12 | #    this method is slower than the numpy polyroots() function that uses
 13 | #    the eigenvalues of the polynomial companion matrix.
 14 | 
 15 | def linzero(xlo, xhi, ylo, yhi):
 16 | 	""" approximate the location of the zero contained within
 17 | 	    (xlo, xhi)
 18 | 	"""
 19 | 	m = (yhi - ylo) / (xhi - xlo)
 20 | 	b = ylo - m * xlo
 21 | 	return -b/m
 22 | 
 23 | def hone_in(p, lo, hi, stop, count, max_count=10):
 24 | 	""" improve estimate of the location of a zero
 25 | 	    by iteratively applying the secant method
 26 | 	    and refining the bracket
 27 | 	"""
 28 | 
 29 | 	y_hi = pol.polyval(hi, p)
 30 | 	y_lo = pol.polyval(lo, p)
 31 | 
 32 | 	if y_hi * y_lo >= 0:
 33 | 		raise Exception("y_lo and y_hi need different signs.")
 34 | 
 35 | 	zero = linzero(lo, hi, y_lo, y_hi)
 36 | 
 37 | 	fz = pol.polyval(zero, p)
 38 | 	if zero - lo < stop or hi - zero < stop \
 39 | 	           or fz == 0 or count == max_count:
 40 | 		return zero, count
 41 | 
 42 | 	if fz * y_lo < 0:
 43 | 		return hone_in(p, lo, zero, stop, count+1, max_count)
 44 | 
 45 | 	else:
 46 | 		return hone_in(p, zero, hi, stop, count+1, max_count)
 47 | 
 48 | def secant_zero(p, lo, hi, acc=1E-5):
 49 | 	z, c = hone_in(p, lo, hi, acc, 0, max_count=100)
 50 | 	return z
 51 | 	
 52 | def brent_zero(p, lo, hi, acc=1E-5):
 53 | 	f = lambda x, p=p : pol.polyval(x, p)
 54 | 	return brentq(f, lo, hi)
 55 | 
 56 | def newton_zero(p, lo, hi, acc=1E-5):
 57 | 
 58 | 	ylo = pol.polyval(lo, p)
 59 | 	yhi = pol.polyval(hi, p)
 60 | 
 61 | 	x0 = linzero(lo, hi, ylo, yhi)
 62 | 
 63 | 	dp = pol.polyder(p)
 64 | 	f = lambda x, p=p : pol.polyval(x, p)
 65 | 	df = lambda x, dp=dp : pol.polyval(x, dp)
 66 | 
 67 | 	return newton(f, x0, fprime=df)
 68 | 
 69 | def rem(p, d):
 70 | 	return pol.polydiv(p, d)[1]
 71 | 
 72 | def n_sign_changes(p):
 73 | 	n = 0
 74 | 	for i in range(len(p) - 1):
 75 | 		if p[i] * p[i+1] < 0: n += 1
 76 | 	return n
 77 | 
 78 | def sigma(schain, x):
 79 | 	return n_sign_changes([ pol.polyval(x, p) for p in schain ])
 80 | 
 81 | def sturm_chain(p):
 82 | 	# Sturm chains:
 83 | 	#   p0, p1, p2, ..., pm
 84 | 	#
 85 | 	#   p0 = p
 86 | 	#   p1 = dp/dx
 87 | 	#   p2 = -rem(p0, p1)
 88 | 	#   p3 = -rem(p1, p2)
 89 | 	#     ...
 90 | 	#    0 = -rem(p(m-1), pm)
 91 | 	#
 92 | 	chains = [ p, pol.polyder(p) ]
 93 | 	while True:
 94 | 		pn = -rem(chains[-2], chains[-1])
 95 | 		if len(pn) == 1 and abs(pn[0]) < 1E-14:
 96 | 			break
 97 | 		chains.append(pn)
 98 | 	return chains
 99 | 
100 | def bisect(a, b):
101 | 	d = 0.5 * (b - a)
102 | 	return [ (a, a + d), (a + d, b) ]
103 | 
104 | def sturm_zeros(p, a, b, acc=1E-5, zero_finder=brent_zero):
105 | 	chains = sturm_chain(p)
106 | 
107 | 	brackets = [ (a, b) ]
108 | 	zeros = []
109 | 	while len(brackets) > 0:
110 | 		#print brackets
111 | 		x1, x2 = brackets.pop()
112 | 		if x2 - x1 < acc:
113 | 			zeros.append(x1)
114 | 			continue
115 | 
116 | 		# use Sturm's theorem to get # of distinct
117 | 		# real zeros within [ x1, x2 ]
118 | 		n = sigma(chains, x1) - sigma(chains, x2)
119 | 		#print n, x1, x2
120 | 
121 | 		if n == 0:
122 | 			continue
123 | 		elif n == 1 and pol.polyval(x1, p) * pol.polyval(x2, p) < 0:
124 | 			zeros.append(zero_finder(p, x1, x2, acc=acc))
125 | 		else:
126 | 			brackets.extend(bisect(x1, x2))
127 | 
128 | 	return zeros
129 | 
130 | class PseudoPolynomial(object):
131 | 	""" 
132 | 	Convenience class for doing algebra with rational functions
133 | 	containing factors of $\sqrt{1 - x^2}$ and with (1 - x^2)^(-r)
134 | 	in the denominator
135 | 
136 | 	PP = (1 - x^2)^r * [polynomial(coeffs_1) 
137 | 	                    + (1 - x^2)^(1/2) * polynomial(coeffs_2)]
138 | 
139 | 	Parameters
140 | 	----------
141 | 	p : np.ndarray
142 | 		Coefficients of polynomial (1)
143 | 	q : np.ndarray
144 | 		Coefficients of polynomial (2)
145 | 	r : int <= 0
146 | 		Factor in $(1 - x^2)^r * (p(x) + sqrt(1 - x^2)*q(x))$.
147 | 
148 | 	"""
149 | 	def __init__(self, p=None, q=None, r=None):
150 | 
151 | 		# Uses arrays instead of Polynomial instances
152 | 		# for better performance
153 | 		assert(p is None or isinstance(p, np.ndarray))
154 | 		assert(q is None or isinstance(q, np.ndarray))
155 | 		assert(r is None or isinstance(r, Integral))
156 | 
157 | 		assert(r <= 0)
158 | 
159 | 		self.p = np.array([0]) if p is None else p
160 | 		self.q = np.array([0]) if q is None else q
161 | 		self.r = 0 if r is None else r
162 | 
163 | 	def __add__(self, PP):
164 | 
165 | 		if not (isinstance(PP, type(self)) or isinstance(PP, np.ndarray)):
166 | 			raise TypeError("Can only add Polynomial or PseudoPolynomial "
167 | 							"to another PseudoPolynomial, not %s"%(str(type(PP))))
168 | 		PP_ = PP
169 | 		if not isinstance(PP, type(self)):
170 | 			PP_ = PseudoPolynomial(p=PP)
171 | 
172 | 		p1, p2 = (self, PP_) if self.r <= PP_.r else (PP_, self)
173 | 		
174 | 		x = 1 if p1.r == p2.r else pol.polypow((1, 0, -1), p2.r - p1.r)
175 | 
176 | 		p = pol.polyadd(p1.p, pol.polymul(x, p2.p))
177 | 		q = pol.polyadd(p1.q, pol.polymul(x, p2.q))
178 | 		r = p1.r
179 | 
180 | 		return PseudoPolynomial(p=p, q=q, r=r)
181 | 
182 | 
183 | 	def __mul__(self, PP):
184 | 
185 | 		if isinstance(PP, np.ndarray) or isinstance(PP, Number):
186 | 			return PseudoPolynomial(p=pol.polymul(self.p, PP), 
187 | 				                    q=pol.polymul(self.q, PP), 
188 | 				                    r=self.r)
189 | 		
190 | 		if not isinstance(PP, type(self)):
191 | 			raise TypeError("Can only multiply PseudoPolynomial "
192 | 			                "by a number, numpy Polynomial, or "
193 | 			                "another PseudoPolynomial, not %s"%(str(type(PP))))
194 | 
195 | 		p1, p2 = (self, PP) if self.r <= PP.r else (PP, self)
196 | 
197 | 		x1 = pol.polypow((1, 0, -1), p1.r + p2.r + 1)
198 | 		x2 = 1 if p2.r == p1.r else pol.polypow((1, 0, -1), p2.r - p1.r)
199 | 
200 | 		p = pol.polyadd(pol.polymul(p1.p, p2.p), 
201 | 			            pol.polymul(pol.polymul(x1, p1.q), p2.q))
202 | 		q = pol.polyadd(pol.polymul(pol.polymul(x2,p1.p), p2.q), 
203 | 			            pol.polymul(p2.p, p1.q))
204 | 		r = p1.r
205 | 
206 | 		return PseudoPolynomial(p=p, q=q, r=r)
207 | 
208 | 
209 | 	def __sub__(self, PP):
210 | 		return self.__add__(PP * (-1))
211 | 
212 | 	def __repr__(self):
213 | 		return 'PseudoPolynomial(p=%s, q=%s, r=%s)'%(repr(self.p), repr(self.q), repr(self.r))
214 | 
215 | 	def deriv(self):
216 | 		""" compute first derivative
217 | 
218 | 		Returns
219 | 		-------
220 | 		dPP : PseudoPolynomial
221 | 			d(PP)/dx represented as a PseudoPolynomial
222 | 		"""
223 | 		dp = pol.polyder(self.p)
224 | 		dq = pol.polyder(self.q)
225 | 
226 | 		
227 | 		p = pol.polysub(pol.polymul((1, 0, -1), dp), pol.polymul((0, 2 * self.r), self.p))
228 | 		q = pol.polysub(pol.polymul((1, 0, -1), dq), pol.polymul((0, 2 * self.r + 1), self.q))
229 | 		r = self.r - 1
230 | 
231 | 		return PseudoPolynomial(p=p, q=q, r=r)
232 | 
233 | 
234 | 	def root_finding_poly(self):
235 | 		""" (1 - x^2)^(-(2 * r + 1)) * p^2 - q^2 
236 | 
237 | 		Returns
238 | 		-------
239 | 		coef : np.ndarray
240 | 			Coefficients of a polynomial that has the
241 | 			same number of roots as the PP
242 | 
243 | 		"""
244 | 		return  pol.polysub(pol.polymul(pol.polymul(self.p, self.p), (1, 0, -1)), 
245 | 			                pol.polymul(self.q, self.q))
246 | 
247 | 	def roots(self):
248 | 		return self.root_finding_poly().roots()
249 | 
250 | 	def eval(self, x):
251 | 		a = 1./pol.polyval((1, 0, -1), -self.r)
252 | 
253 | 		return a * (pol.polyval(x, self.p) + sqrt(1 - x*x) \
254 | 		                                * pol.polyval(x, self.q))
255 | 
256 | 
257 | # An (or Bn) as a PseudoPolynomial
258 | Afunc_pp = lambda n, p, q, sgn : PseudoPolynomial(   \
259 |                                         p=         p * np.array(chebyt(n).coef)[::-1], 
260 | 	                                    q= - sgn * q * np.array(chebyu(n-1).coef)[::-1] \
261 | 	                                           if n > 0 else np.array([0]),
262 | 	                                    r=   0)
263 | 
264 | # Vector A or B in PseudoPolynomial form
265 | ABpoly = lambda c, s, sgn, alpha : [ Afunc_pp(n+1, C if alpha == 0 else  S, 
266 | 	                                             S if alpha == 0 else -C, sgn) \
267 |                                        for n, (C, S) in enumerate(zip(c, s)) ]
268 | 
269 | # Hardcoded, should probably be double checked but this 
270 | # empirically works
271 | get_poly_len = lambda H : 6 * H + 2
272 | 
273 | def pseudo_poly_tensor(P1, P2, P3):
274 | 	""" 
275 | 	Compute coefficients of all products of P1, P2, P3
276 | 
277 | 	Parameters
278 | 	----------
279 | 	P1: list of PseudoPolynomial
280 | 		Usually A or B (represented as PseudoPolynomial)
281 | 	P2: list of PseudoPolynomial
282 | 	P3: list of PseudoPolynomial
283 | 		Usually d(A)/dx or d(B)/dx
284 | 	
285 | 	Returns
286 | 	-------
287 | 	P: np.ndarray, shape=(H,H,H,L)
288 | 		L is defined by `get_poly_len`. (P) Polynomial coefficients
289 | 		for outer product of all 3 vectors of PseudoPolynomials
290 | 	Q: np.ndarray, shape=(H,H,H,L)
291 | 		L is defined by `get_poly_len`. (Q) Polynomial coefficients
292 | 		for outer product of all 3 vectors of PseudoPolynomials
293 | 
294 | 	"""
295 | 	H = len(P1)
296 | 	L = get_poly_len(H)
297 | 	P, Q = np.zeros((H, H, H, L)), np.zeros((H, H, H, L))
298 | 	for i, p1 in enumerate(P1):
299 | 		for j, p2 in enumerate(P2):
300 | 			PP = p1 * p2
301 | 			for k, p3 in enumerate(P3):
302 | 				PPP = PP * p3
303 | 
304 | 				#print len(P[i][j][k]), len(PPP.p), len(PPP.q)
305 | 				P[i][j][k][:len(PPP.p)] = PPP.p[:]
306 | 				Q[i][j][k][:len(PPP.q)] = PPP.q[:]
307 | 
308 | 	return P, Q
309 | 
310 | 
311 | def compute_polynomial_tensors(A, B, dA, dB):
312 | 	"""
313 | 	returns coefficients of all 
314 | 	
315 | 	(A or B)_n * (A or B)_m * d(A or B)_k, 
316 | 	
317 | 	pseudo polynomial products
318 | 	"""
319 | 	AAdAp, AAdAq = pseudo_poly_tensor(A, A, dA)
320 | 	AAdBp, AAdBq = pseudo_poly_tensor(A, A, dB)
321 | 	ABdAp, ABdAq = pseudo_poly_tensor(A, B, dA)
322 | 	ABdBp, ABdBq = pseudo_poly_tensor(A, B, dB)
323 | 	BBdAp, BBdAq = pseudo_poly_tensor(B, B, dA)
324 | 	BBdBp, BBdBq = pseudo_poly_tensor(B, B, dB)
325 | 	
326 | 	return AAdAp, AAdAq, AAdBp, AAdBq, ABdAp, ABdAq, \
327 | 	       ABdBp, ABdBq, BBdAp, BBdAq, BBdBp, BBdBq
328 | 
329 | def get_polynomial_vectors(cn, sn, sgn=1):
330 | 	""" 
331 | 	returns list of PseudoPolynomials corresponding to
332 | 	A_n, B_n, and their derivatives
333 | 	"""
334 | 	A = ABpoly(cn, sn, sgn, 0)
335 | 	B = ABpoly(cn, sn, sgn, 1)
336 | 
337 | 	dA = [ a.deriv() for a in A ]
338 | 	dB = [ b.deriv() for b in B ]
339 | 
340 | 	return A, B, dA, dB
341 | 
342 | 
343 | 
344 | def compute_zeros(ptensors, sums, loud=False):
345 | 	""" 
346 | 	Compute frequency-dependent polynomial coefficients, 
347 | 	then find real roots 
348 | 		
349 | 	Parameters
350 | 	----------
351 | 	ptensors: np.ndarray
352 | 		generated by :compute_polynomial_tensors: and contains
353 | 		coefficients unique to each template
354 | 	summations: tuple or array-like
355 | 		C, S, YC, YS, CChat, CShat, SShat; see documentation for
356 | 		definitions of these quantities.
357 | 	loud: bool (default: False)
358 | 		Print timing information
359 | 
360 | 	Returns
361 | 	-------
362 | 	roots: list
363 | 		list of cos(omega * tau) values corresponding to
364 | 		(real) roots of the generated polynomial.
365 | 
366 | 	"""
367 | 	t0 = None
368 | 	if loud: t0 = time()
369 | 
370 | 	AAdAp, AAdAq, \
371 | 	AAdBp, AAdBq, \
372 | 	ABdAp, ABdAq, \
373 | 	ABdBp, ABdBq, \
374 | 	BBdAp, BBdAq, \
375 | 	BBdBp, BBdBq = ptensors
376 | 
377 | 	H = len(AAdAp)
378 | 
379 | 	if loud:
380 | 		dt = time() - t0
381 | 		print "   ", dt, " seconds for bookkeeping"
382 | 
383 | 	if loud: t0 = time()
384 | 	Kaada = np.einsum('i,jk->ijk', sums.YC[:H], sums.CCh[:H,:H]) - np.einsum('k,ij->ijk', sums.YC, sums.CCh[:H,:H])
385 | 	Kaadb = np.einsum('i,jk->ijk', sums.YC[:H], sums.CSh[:H,:H]) - np.einsum('k,ij->ijk', sums.YS, sums.CCh[:H,:H])
386 | 	Kabda = np.einsum('i,kj->ijk', sums.YC[:H], sums.CSh[:H,:H]) + np.einsum('j,ik->ijk', sums.YS, sums.CCh[:H,:H])
387 | 	Kabdb = np.einsum('i,jk->ijk', sums.YC[:H], sums.SSh[:H,:H]) + np.einsum('j,ik->ijk', sums.YS, sums.CSh[:H,:H])
388 | 	Kbbda = np.einsum('i,kj->ijk', sums.YS[:H], sums.CSh[:H,:H]) - np.einsum('k,ij->ijk', sums.YC, sums.SSh[:H,:H])
389 | 	Kbbdb = np.einsum('i,jk->ijk', sums.YS[:H], sums.SSh[:H,:H]) - np.einsum('k,ij->ijk', sums.YS, sums.SSh[:H,:H])
390 | 	
391 | 	if loud: 
392 | 		dt = time() - t0
393 | 		print "   ", dt, " seconds to make constants"
394 | 
395 | 
396 | 	# Note: the first and last einsums for both Pp and Pq might not be necessary.
397 | 	#       see the docs for more information
398 | 
399 | 	if loud: t0 = time()
400 | 	Pp  = np.einsum('ijkl,ijk->l', AAdAp, Kaada)
401 | 	Pp += np.einsum('ijkl,ijk->l', AAdBp, Kaadb)
402 | 	Pp += np.einsum('ijkl,ijk->l', ABdAp, Kabda)
403 | 	Pp += np.einsum('ijkl,ijk->l', ABdBp, Kabdb)
404 | 	Pp += np.einsum('ijkl,ijk->l', BBdAp, Kbbda)
405 | 	Pp += np.einsum('ijkl,ijk->l', BBdBp, Kbbdb)
406 | 
407 | 	Pq  = np.einsum('ijkl,ijk->l', AAdAq, Kaada)
408 | 	Pq += np.einsum('ijkl,ijk->l', AAdBq, Kaadb)
409 | 	Pq += np.einsum('ijkl,ijk->l', ABdAq, Kabda)
410 | 	Pq += np.einsum('ijkl,ijk->l', ABdBq, Kabdb)
411 | 	Pq += np.einsum('ijkl,ijk->l', BBdAq, Kbbda)
412 | 	Pq += np.einsum('ijkl,ijk->l', BBdBq, Kbbdb)
413 | 	if loud:
414 | 		dt = time() - t0
415 | 		print "   ", dt, " seconds to make coefficients of pseudo-polynomial"
416 | 
417 | 	if loud: t0 = time()
418 | 	P = pol.polysub(pol.polymul((1, 0, -1), pol.polymul(Pp, Pp)), pol.polymul(Pq, Pq))
419 | 	if loud:
420 | 		dt = time() - t0
421 | 		print "   ",dt, " seconds to get final polynomial"
422 | 
423 | 	if loud: t0 = time()
424 | 
425 | 	#c = max(np.absolute(P))
426 | 	#c = 1./c if c > 0 else 1.0
427 | 	#if P[-1] < 0: c *= -1
428 | 	c = 1.0
429 | 	R = pol.polyroots(np.array(P) * c)
430 | 	#R = sturm_zeros(P, -1, 1)
431 | 	if loud:
432 | 		dt = time() - t0
433 | 		print "   ", dt, " seconds to find roots of polynomial"
434 | 
435 | 	small = 1E-5
436 | 	return [ min([ 1.0, abs(r.real) ]) * np.sign(r.real) for r in R if abs(r.imag) < small and abs(r.real) < 1 + small ]


--------------------------------------------------------------------------------
/pyftp/modeler.py:
--------------------------------------------------------------------------------
  1 | import os
  2 | import sys
  3 | from time import time
  4 | from math import *
  5 | import numpy as np
  6 | import fast_template_periodogram as ftp
  7 | from scipy.optimize import curve_fit
  8 | import cPickle as pickle
  9 | 
 10 | def LMfit(x, y, err, cn, sn, omega, sgn=1):
 11 | 	""" fits a, b, c with Levenberg-Marquardt """
 12 | 
 13 | 	ffunc = lambda X, *pars : ftp.fitfunc(X, sgn, omega, cn, sn, *pars)
 14 | 	p0 = [ np.std(y), 0.0, np.mean(y) ]
 15 | 	bounds = ([0, -1, -np.inf], [ np.inf, 1, np.inf])
 16 | 	popt, pcov = curve_fit(ffunc, x, y, sigma=err, p0=p0, 
 17 |                             absolute_sigma=True, bounds=bounds, 
 18 |                             method='trf')
 19 | 	a, b, c = popt
 20 | 
 21 | 	return a, b, c
 22 | 
 23 | def rms_resid_over_rms(cn, sn, Tt, Yt):
 24 | 	# This is fairly slow; is there a better way to get best fit pars?
 25 | 	a, b, c = LMfit(Tt, Yt, np.ones(len(Tt))*0.0001, cn, sn, 2 * np.pi, sgn=True)
 26 | 	Ym = ftp.fitfunc(Tt, 1, 2 * np.pi, cn, sn, a, b, c)
 27 | 
 28 | 	S = sqrt(np.mean(np.power(Yt, 2)))
 29 | 
 30 | 	Rp = sqrt(np.mean(np.power(Ym - Yt, 2))) / S
 31 | 
 32 | 	a, b, c = LMfit(Tt, Yt, np.ones(len(Tt))*0.0001, cn, sn, 2 * np.pi, sgn=False)
 33 | 	Ym = ftp.fitfunc(Tt, -1, 2 * np.pi, cn, sn, a, b, c)
 34 | 
 35 | 	Rn = sqrt(np.mean(np.power(Ym - Yt, 2))) / S
 36 | 	return min([ Rn, Rp ])
 37 | 
 38 | rms = lambda x : sqrt(np.mean(np.power(x, 2)))
 39 | 
 40 | def match_up_truncated_template(cn, sn, Tt, Yt):
 41 | 	Ym = ftp.fitfunc(Tt, 1, 2 * np.pi, cn, sn, 2.0, 0.0, 0.0)
 42 | 
 43 | 	# Align the maxima of truncated and full templates
 44 | 	di = np.argmax(Ym) - np.argmax(Yt)
 45 | 
 46 | 	# Add some 'wiggle room', since maxima may be offset by 1
 47 | 	Ym = [ np.array([ Ym[(j + (di + k))%len(Ym)] for j in range(len(Ym)) ]) for k in [ -1, 0, 1 ] ]
 48 | 
 49 | 	# Align the heights of the truncated and full templates
 50 | 	Ym = [ Y + (Yt[0] - Y[0]) for Y in Ym ]
 51 | 
 52 | 	# Keep the best fit
 53 | 	return Ym[np.argmin( [ rms(Y - Yt) for Y in Ym ] )]
 54 | 
 55 | def rms_resid_over_rms_fast(cn, sn, Tt, Yt):
 56 | 	Ym = match_up_truncated_template(cn, sn, Tt, Yt)
 57 | 	return rms(Yt - Ym) / rms(Yt)
 58 | 
 59 | def approximate_template(Tt, Yt, errfunc=rms_resid_over_rms, stop=1E-2, nharmonics=None):
 60 | 	""" Fourier transforms template, returning the first H components """
 61 | 
 62 | 	#print "fft"
 63 | 	fft = np.fft.fft(Yt[::-1])
 64 | 	
 65 | 	cn, sn = None, None
 66 | 	if not nharmonics is None and int(nharmonics) > 0:
 67 | 		#print "creating cn and sn"
 68 | 		cn, sn = zip(*[ (p.real/len(Tt), p.imag/len(Tt)) for i,p in enumerate(fft) \
 69 | 		             if i > 0 and i <= int(nharmonics) ])
 70 | 		
 71 | 	else:
 72 | 
 73 | 		cn, sn = zip(*[ (p.real/len(Tt), p.imag/len(Tt)) for i,p in enumerate(fft) \
 74 | 		             if i > 0 ])
 75 | 
 76 | 		h = 1
 77 | 		while errfunc(cn[:h], sn[:h], Tt, Yt) > stop:
 78 | 			#print "h -> ", h
 79 | 			h+=1
 80 | 
 81 | 		cn, sn = cn[:h], sn[:h]
 82 | 	return cn, sn
 83 | 
 84 | normfac = lambda cn, sn : 1./np.sqrt(sum([ ss*ss + cc*cc for cc, ss in zip(cn, sn) ]))
 85 | 
 86 | class Template(object):
 87 | 	"""
 88 | 	Template class
 89 | 	
 90 | 	y(t) = sum[n]( c[n]cos(nwt) + s[n]sin(nwt) )
 91 | 
 92 | 	Parameters
 93 | 	----------
 94 | 	cn: array-like, optional
 95 | 		Truncated Fourier coefficients (cosine) 
 96 | 	sn: array-like, optional
 97 | 		Truncated Fourier coefficients (sine) 
 98 | 	phase: array-like, optional
 99 | 		phase-values, must contain floating point numbers in [0,1]
100 | 	y: array-like, optional
101 | 		amplitude of template at each phase value
102 | 	stop: float, optional (default: 2E-2)
103 | 		will pick minimum number of harmonics such that 
104 | 		rms(trunc(template) - template) / rms(template) < stop
105 | 	nharmonics: None or int, optional (default: None)
106 | 		Keep a constant number of harmonics
107 | 	fname: str, optional
108 | 		Filename to load/save template
109 | 	errfunc: callable, optional (default: rms_resid_over_rms)
110 | 		A function returning some measure of error resulting
111 | 		from approximating the template with a given number 
112 | 		of harmonics
113 | 	template_id: str, optional
114 | 		Name of template
115 | 
116 | 	"""
117 | 	def __init__(self, cn=None, sn=None, phase=None, y=None, 
118 | 		               stop=2E-2, nharmonics=None, fname=None,
119 | 				       errfunc=rms_resid_over_rms, template_id=None):
120 | 
121 | 		self.phase = phase
122 | 		self.y = y
123 | 
124 | 		self.fname = fname
125 | 		self.stop = stop
126 | 		self.nharmonics = nharmonics
127 | 		self.errfunc = errfunc
128 | 		self.cn = None
129 | 		self.sn = None
130 | 		self.pvectors = None
131 | 		self.ptensors = None
132 | 		self.template_id = template_id
133 | 		self.best_fit_y = None
134 | 
135 | 		self.cn_full = None
136 | 		self.sn_full = None
137 | 
138 | 		
139 | 		self.defined_by_ty = cn is None and sn is None
140 | 		if self.defined_by_ty and (phase is None or y is None):
141 | 			raise Exception("Need to define either (phase, y) or (cn, sn) for template")
142 | 
143 | 		if not self.defined_by_ty:
144 | 
145 | 			assert(not (cn is None or sn is None))
146 | 
147 | 			self.cn_full = np.array(cn).copy()
148 | 			self.sn_full = np.array(sn).copy()
149 | 
150 | 			if nharmonics is None:
151 | 				self.nharmonics = len(cn)
152 | 
153 | 			assert(self.nharmonics <= len(cn))
154 | 
155 | 			self.cn = self.cn_full[:self.nharmonics].copy()
156 | 			self.sn = self.sn_full[:self.nharmonics].copy()
157 | 
158 | 
159 | 			self.cn *= normfac(self.cn, self.sn)
160 | 			self.sn *= normfac(self.cn, self.sn)
161 | 		
162 | 	def is_saved(self):
163 | 
164 | 		return (not self.fname is None and os.path.exists(self.fname))
165 | 
166 | 	def precompute(self):
167 | 		
168 | 
169 | 		if self.defined_by_ty:
170 | 			#print "approximating template"
171 | 			self.cn, self.sn = approximate_template(self.phase, self.y, 
172 | 			                            stop=self.stop, errfunc=self.errfunc, 
173 | 										nharmonics=self.nharmonics)
174 | 
175 | 			#print "getting best fit y"
176 | 			self.best_fit_y = match_up_truncated_template(self.cn, self.sn, self.phase, self.y)
177 | 
178 | 			#print "computing rms_resid/rms"
179 | 			self.rms_resid_over_rms = rms(self.best_fit_y - self.y) / rms(self.y)
180 | 
181 | 		else:
182 | 
183 | 			assert(self.nharmonics <= len(self.cn_full))
184 | 
185 | 			self.cn = self.cn_full[:self.nharmonics].copy()
186 | 			self.sn = self.sn_full[:self.nharmonics].copy()
187 | 
188 | 			self.cn *= normfac(self.cn, self.sn)
189 | 			self.sn *= normfac(self.cn, self.sn)
190 | 
191 | 			nph = 100
192 | 			self.phase = np.linspace(0, 1, nph)
193 | 			self.y = ftp.fitfunc(self.phase, 1, 2 * np.pi, self.cn_full, self.sn_full, 2.0, 0.0, 1.0)
194 | 			self.best_fit_y = ftp.fitfunc(self.phase, 1, 2 * np.pi, self.cn, self.sn, 2.0, 0.0, 1.0)
195 | 
196 | 			self.rms_resid_over_rms = rms(self.best_fit_y - self.y) / rms(self.y)
197 | 
198 | 		#print "computing pvectors"
199 | 		#print self.cn
200 | 		#print self.sn
201 | 		self.pvectors = ftp.get_polynomial_vectors(self.cn, self.sn, sgn=1)
202 | 
203 | 		#print "computing ptensors"
204 | 		self.ptensors = ftp.compute_polynomial_tensors(*self.pvectors)
205 | 
206 | 		return self
207 | 
208 | 	def load(self, fname=None):
209 | 		fn = fname if not fname is None else self.fname
210 | 		self.__dict__.update(pickle.load(open(fn, 'rb')))
211 | 
212 | 	def save(self, fname=None):
213 | 		fn = fname if not fname is None else self.fname
214 | 		pickle.dump(self.__dict__, open(fn, 'wb'))
215 | 
216 | 	def add_plot_to_axis(self, ax):
217 | 		ax.plot(self.phase, self.y, color='k', label="original")
218 | 		ax.plot(self.phase, self.best_fit_y,
219 | 			      label="truncated (H=%d)"%(self.nharmonics))
220 | 
221 | 	def set_nharmonics(self, nharmonics):
222 | 		self.nharmonics = nharmonics
223 | 		self.precompute()
224 | 		return self
225 | 
226 | 	def plot(self, plt):
227 | 		f, ax = plt.subplots()
228 | 		self.add_plot_to_axis(ax)
229 | 		ax.set_xlim(0, 1)
230 | 		#ax.set_ylim(0, 1)
231 | 		ax.set_xlabel('phase')
232 | 		ax.set_ylabel('y')
233 | 		ax.set_title('"%s", stop = %.3e, H = %d'%(self.template_id, 
234 | 			                                 self.stop, self.nharmonics))
235 | 		ax.legend(loc='best', fontsize=9)
236 | 		plt.show()
237 | 		plt.close(f)
238 | 
239 | class FastTemplateModeler(object):
240 | 
241 | 	"""
242 | 	Base class for template modelers
243 | 
244 | 	Parameters
245 | 	----------
246 | 
247 | 	loud: boolean (default: True), optional
248 | 		print status
249 | 	ofac: float, optional (default: 10)
250 | 		oversampling factor -- higher values of ofac decrease 
251 | 		the frequency spacing (by increasing the size of the FFT)
252 | 	hfac: float, optional (default: 3)
253 | 		high-frequency factor -- higher values of hfac increase
254 | 		the maximum frequency of the periodogram at the 
255 | 		expense of larger frequency spacing.
256 | 	errfunc: callable, optional (default: rms_resid_over_rms)
257 | 		A function returning some measure of error resulting
258 | 		from approximating the template with a given number 
259 | 		of harmonics
260 | 	stop: float, optional (default: 0.01)
261 | 		A stopping criterion. Once `errfunc` returns a number
262 | 		that is smaller than `stop`, the harmonics up to that point
263 | 		are kept. If not, another harmonic is added.
264 | 	nharmonics: None or int, optional (default: None)
265 | 		Number of harmonics to keep if a constant number of harmonics
266 | 		is desired
267 | 
268 | 	"""
269 | 	def __init__(self, **kwargs):
270 | 		self.params = { key : value for key, value in kwargs.iteritems() }
271 | 		self.templates = {}
272 | 		self.omegas = None
273 | 		self.summations = None
274 | 		self.YY = None
275 | 		self.max_harm = 0
276 | 		self.w = None
277 | 		self.ybar = None
278 | 
279 | 		defaults = dict(ofac=10, hfac=3)
280 | 
281 | 		# set defaults
282 | 		for key, value in defaults.iteritems():
283 | 			if not key in self.params:
284 | 				self.params[key] = value
285 | 		if 'templates' in self.params:
286 | 			self.add_templates(self.params['templates'])
287 | 			del self.params['templates']
288 | 
289 | 	def _get_template_by_id(self, template_id):
290 | 		assert(template_id in self.templates)
291 | 		return self.templates[template_id]
292 | 
293 | 	def _template_ids(self):
294 | 		return self.templates.keys()
295 | 
296 | 	def get_new_template_id(self):
297 | 		i = 0
298 | 		while i in self.templates:
299 | 			i += 1
300 | 		return i
301 | 
302 | 	def add_template(self, template, template_id=None):
303 | 		if template_id is None:
304 | 			if template.template_id is None:
305 | 				ID = self.get_new_template_id()
306 | 				self.templates[ID] = template
307 | 			else:
308 | 				self.templates[template.template_id] = template
309 | 		else:
310 | 			self.templates[template_id] = template
311 | 		return self
312 | 
313 | 	def add_templates(self, templates, template_ids=None):
314 | 
315 | 		if isinstance(templates, dict):
316 | 			for ID, template in templates.iteritems():
317 | 				self.add_template(template, template_id=ID)
318 | 
319 | 		elif isinstance(templates, list):
320 | 			if template_ids is None:
321 | 				for template in templates:
322 | 					self.add_template(template)
323 | 			else:
324 | 				for ID, template in zip(template_ids, templates):
325 | 					self.add_template(template, template_id=ID)
326 | 		elif not hasattr(templates, '__iter__'):
327 | 			self.add_template(templates, template_id=template_ids)
328 | 		else:
329 | 			raise Exception("did not recognize type of 'templates' passed to add_templates")
330 | 			
331 | 		return self
332 | 
333 | 	def remove_templates(self, template_ids):
334 | 		for ID in template_ids:
335 | 			assert ID in self.templates
336 | 			del self.templates[ID]
337 | 		return self
338 | 
339 | 	def set_params(self, **new_params):
340 | 		self.params.update(new_params)
341 | 		return self
342 | 
343 | 	def fit(self, x, y, err):
344 | 		"""
345 | 		Parameters
346 | 		----------
347 | 		x: np.ndarray, list
348 | 			independent variable (time)
349 | 		y: np.ndarray, list
350 | 			array of observations
351 | 		err: np.ndarray
352 | 			array of observation uncertainties
353 | 		"""
354 | 		self.x = x
355 | 		self.y = y
356 | 		self.err = err
357 | 		
358 | 		# Set all old values to none
359 | 		self.summations = None
360 | 		self.freqs_ = None
361 | 		self.best_template_id = None
362 | 		self.best_template = None
363 | 		self.best_model_params = None
364 | 		self.periodogram_ = None
365 | 		self.model_params_ = None
366 | 		self.periodogram_all_templates_ = None
367 | 		return self
368 | 
369 | 	def compute_sums(self):
370 | 		
371 | 		self.omegas, self.summations, \
372 | 		self.YY, self.w, self.ybar = \
373 | 			ftp.compute_summations(self.x, self.y, self.err, self.max_harm, 
374 | 								ofac=self.params['ofac'], hfac=self.params['hfac'])
375 | 
376 | 		return self
377 | 
378 | 
379 | 		
380 | 	def periodogram(self, **kwargs):
381 | 		self.params.update(kwargs)
382 | 
383 | 		#if self.summations is None:
384 | 		#	self.compute_sums()
385 | 		loud = False if not 'loud' in self.params else self.params['loud']
386 | 		
387 | 		all_ftps = []
388 | 		for template_id, template in self.templates.iteritems():
389 | 			args = (self.x, self.y, self.err, template.cn, template.sn)
390 | 			kwargs = dict(ofac       = self.params['ofac'], 
391 | 						  hfac       = self.params['hfac'], 
392 | 						  ptensors   = template.ptensors, 
393 | 						  pvectors   = template.pvectors, 
394 | 						  omegas     = self.omegas, 
395 | 						  summations = self.summations, 
396 | 						  YY         = self.YY, 
397 | 						  ybar       = self.ybar, 
398 | 						  w          = self.w,
399 | 						  loud       = loud,
400 | 						  return_best_fit_pars=True)
401 | 			all_ftps.append((template_id, ftp.fast_template_periodogram(*args, **kwargs)))
402 | 		
403 | 		template_ids, all_ftps_ = zip(*all_ftps)
404 | 		freqs, ftps, modelpars  = zip(*all_ftps_)
405 | 		freqs = freqs[0]
406 | 		
407 | 		self.periodogram_ = np.array([ max([ f[i] for f in ftps ]) for i in range(len(freqs)) ])
408 | 		self.freqs_ = freqs
409 | 		self.periodogram_all_templates_ = zip(template_ids, ftps)
410 | 		self.model_params_ = zip(template_ids, modelpars)
411 | 
412 | 		# Periodogram is the maximum periodogram value at each frequency
413 | 		return self.freqs_, self.periodogram_
414 | 
415 | 	def get_best_model(self, **kwargs):
416 | 
417 | 		ibest = np.argmax(self.periodogram_)
418 | 		tbest = np.argmax([ f[ibest] for t, f in self.periodogram_all_templates_ ])
419 | 
420 | 		self.best_freq = self.freqs_[ibest]
421 | 		self.best_template_id, self.best_model_params = self.model_params_[tbest]
422 | 	
423 | 		self.best_model_params = self.best_model_params[ibest]
424 | 		self.best_template = self.templates[self.best_template_id]
425 | 		
426 | 		return self.best_template, self.best_model_params
427 | 


--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
  1 |                     GNU GENERAL PUBLIC LICENSE
  2 |                        Version 3, 29 June 2007
  3 | 
  4 |  Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
  5 |  Everyone is permitted to copy and distribute verbatim copies
  6 |  of this license document, but changing it is not allowed.
  7 | 
  8 |                             Preamble
  9 | 
 10 |   The GNU General Public License is a free, copyleft license for
 11 | software and other kinds of works.
 12 | 
 13 |   The licenses for most software and other practical works are designed
 14 | to take away your freedom to share and change the works.  By contrast,
 15 | the GNU General Public License is intended to guarantee your freedom to
 16 | share and change all versions of a program--to make sure it remains free
 17 | software for all its users.  We, the Free Software Foundation, use the
 18 | GNU General Public License for most of our software; it applies also to
 19 | any other work released this way by its authors.  You can apply it to
 20 | your programs, too.
 21 | 
 22 |   When we speak of free software, we are referring to freedom, not
 23 | price.  Our General Public Licenses are designed to make sure that you
 24 | have the freedom to distribute copies of free software (and charge for
 25 | them if you wish), that you receive source code or can get it if you
 26 | want it, that you can change the software or use pieces of it in new
 27 | free programs, and that you know you can do these things.
 28 | 
 29 |   To protect your rights, we need to prevent others from denying you
 30 | these rights or asking you to surrender the rights.  Therefore, you have
 31 | certain responsibilities if you distribute copies of the software, or if
 32 | you modify it: responsibilities to respect the freedom of others.
 33 | 
 34 |   For example, if you distribute copies of such a program, whether
 35 | gratis or for a fee, you must pass on to the recipients the same
 36 | freedoms that you received.  You must make sure that they, too, receive
 37 | or can get the source code.  And you must show them these terms so they
 38 | know their rights.
 39 | 
 40 |   Developers that use the GNU GPL protect your rights with two steps:
 41 | (1) assert copyright on the software, and (2) offer you this License
 42 | giving you legal permission to copy, distribute and/or modify it.
 43 | 
 44 |   For the developers' and authors' protection, the GPL clearly explains
 45 | that there is no warranty for this free software.  For both users' and
 46 | authors' sake, the GPL requires that modified versions be marked as
 47 | changed, so that their problems will not be attributed erroneously to
 48 | authors of previous versions.
 49 | 
 50 |   Some devices are designed to deny users access to install or run
 51 | modified versions of the software inside them, although the manufacturer
 52 | can do so.  This is fundamentally incompatible with the aim of
 53 | protecting users' freedom to change the software.  The systematic
 54 | pattern of such abuse occurs in the area of products for individuals to
 55 | use, which is precisely where it is most unacceptable.  Therefore, we
 56 | have designed this version of the GPL to prohibit the practice for those
 57 | products.  If such problems arise substantially in other domains, we
 58 | stand ready to extend this provision to those domains in future versions
 59 | of the GPL, as needed to protect the freedom of users.
 60 | 
 61 |   Finally, every program is threatened constantly by software patents.
 62 | States should not allow patents to restrict development and use of
 63 | software on general-purpose computers, but in those that do, we wish to
 64 | avoid the special danger that patents applied to a free program could
 65 | make it effectively proprietary.  To prevent this, the GPL assures that
 66 | patents cannot be used to render the program non-free.
 67 | 
 68 |   The precise terms and conditions for copying, distribution and
 69 | modification follow.
 70 | 
 71 |                        TERMS AND CONDITIONS
 72 | 
 73 |   0. Definitions.
 74 | 
 75 |   "This License" refers to version 3 of the GNU General Public License.
 76 | 
 77 |   "Copyright" also means copyright-like laws that apply to other kinds of
 78 | works, such as semiconductor masks.
 79 | 
 80 |   "The Program" refers to any copyrightable work licensed under this
 81 | License.  Each licensee is addressed as "you".  "Licensees" and
 82 | "recipients" may be individuals or organizations.
 83 | 
 84 |   To "modify" a work means to copy from or adapt all or part of the work
 85 | in a fashion requiring copyright permission, other than the making of an
 86 | exact copy.  The resulting work is called a "modified version" of the
 87 | earlier work or a work "based on" the earlier work.
 88 | 
 89 |   A "covered work" means either the unmodified Program or a work based
 90 | on the Program.
 91 | 
 92 |   To "propagate" a work means to do anything with it that, without
 93 | permission, would make you directly or secondarily liable for
 94 | infringement under applicable copyright law, except executing it on a
 95 | computer or modifying a private copy.  Propagation includes copying,
 96 | distribution (with or without modification), making available to the
 97 | public, and in some countries other activities as well.
 98 | 
 99 |   To "convey" a work means any kind of propagation that enables other
100 | parties to make or receive copies.  Mere interaction with a user through
101 | a computer network, with no transfer of a copy, is not conveying.
102 | 
103 |   An interactive user interface displays "Appropriate Legal Notices"
104 | to the extent that it includes a convenient and prominently visible
105 | feature that (1) displays an appropriate copyright notice, and (2)
106 | tells the user that there is no warranty for the work (except to the
107 | extent that warranties are provided), that licensees may convey the
108 | work under this License, and how to view a copy of this License.  If
109 | the interface presents a list of user commands or options, such as a
110 | menu, a prominent item in the list meets this criterion.
111 | 
112 |   1. Source Code.
113 | 
114 |   The "source code" for a work means the preferred form of the work
115 | for making modifications to it.  "Object code" means any non-source
116 | form of a work.
117 | 
118 |   A "Standard Interface" means an interface that either is an official
119 | standard defined by a recognized standards body, or, in the case of
120 | interfaces specified for a particular programming language, one that
121 | is widely used among developers working in that language.
122 | 
123 |   The "System Libraries" of an executable work include anything, other
124 | than the work as a whole, that (a) is included in the normal form of
125 | packaging a Major Component, but which is not part of that Major
126 | Component, and (b) serves only to enable use of the work with that
127 | Major Component, or to implement a Standard Interface for which an
128 | implementation is available to the public in source code form.  A
129 | "Major Component", in this context, means a major essential component
130 | (kernel, window system, and so on) of the specific operating system
131 | (if any) on which the executable work runs, or a compiler used to
132 | produce the work, or an object code interpreter used to run it.
133 | 
134 |   The "Corresponding Source" for a work in object code form means all
135 | the source code needed to generate, install, and (for an executable
136 | work) run the object code and to modify the work, including scripts to
137 | control those activities.  However, it does not include the work's
138 | System Libraries, or general-purpose tools or generally available free
139 | programs which are used unmodified in performing those activities but
140 | which are not part of the work.  For example, Corresponding Source
141 | includes interface definition files associated with source files for
142 | the work, and the source code for shared libraries and dynamically
143 | linked subprograms that the work is specifically designed to require,
144 | such as by intimate data communication or control flow between those
145 | subprograms and other parts of the work.
146 | 
147 |   The Corresponding Source need not include anything that users
148 | can regenerate automatically from other parts of the Corresponding
149 | Source.
150 | 
151 |   The Corresponding Source for a work in source code form is that
152 | same work.
153 | 
154 |   2. Basic Permissions.
155 | 
156 |   All rights granted under this License are granted for the term of
157 | copyright on the Program, and are irrevocable provided the stated
158 | conditions are met.  This License explicitly affirms your unlimited
159 | permission to run the unmodified Program.  The output from running a
160 | covered work is covered by this License only if the output, given its
161 | content, constitutes a covered work.  This License acknowledges your
162 | rights of fair use or other equivalent, as provided by copyright law.
163 | 
164 |   You may make, run and propagate covered works that you do not
165 | convey, without conditions so long as your license otherwise remains
166 | in force.  You may convey covered works to others for the sole purpose
167 | of having them make modifications exclusively for you, or provide you
168 | with facilities for running those works, provided that you comply with
169 | the terms of this License in conveying all material for which you do
170 | not control copyright.  Those thus making or running the covered works
171 | for you must do so exclusively on your behalf, under your direction
172 | and control, on terms that prohibit them from making any copies of
173 | your copyrighted material outside their relationship with you.
174 | 
175 |   Conveying under any other circumstances is permitted solely under
176 | the conditions stated below.  Sublicensing is not allowed; section 10
177 | makes it unnecessary.
178 | 
179 |   3. Protecting Users' Legal Rights From Anti-Circumvention Law.
180 | 
181 |   No covered work shall be deemed part of an effective technological
182 | measure under any applicable law fulfilling obligations under article
183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or
184 | similar laws prohibiting or restricting circumvention of such
185 | measures.
186 | 
187 |   When you convey a covered work, you waive any legal power to forbid
188 | circumvention of technological measures to the extent such circumvention
189 | is effected by exercising rights under this License with respect to
190 | the covered work, and you disclaim any intention to limit operation or
191 | modification of the work as a means of enforcing, against the work's
192 | users, your or third parties' legal rights to forbid circumvention of
193 | technological measures.
194 | 
195 |   4. Conveying Verbatim Copies.
196 | 
197 |   You may convey verbatim copies of the Program's source code as you
198 | receive it, in any medium, provided that you conspicuously and
199 | appropriately publish on each copy an appropriate copyright notice;
200 | keep intact all notices stating that this License and any
201 | non-permissive terms added in accord with section 7 apply to the code;
202 | keep intact all notices of the absence of any warranty; and give all
203 | recipients a copy of this License along with the Program.
204 | 
205 |   You may charge any price or no price for each copy that you convey,
206 | and you may offer support or warranty protection for a fee.
207 | 
208 |   5. Conveying Modified Source Versions.
209 | 
210 |   You may convey a work based on the Program, or the modifications to
211 | produce it from the Program, in the form of source code under the
212 | terms of section 4, provided that you also meet all of these conditions:
213 | 
214 |     a) The work must carry prominent notices stating that you modified
215 |     it, and giving a relevant date.
216 | 
217 |     b) The work must carry prominent notices stating that it is
218 |     released under this License and any conditions added under section
219 |     7.  This requirement modifies the requirement in section 4 to
220 |     "keep intact all notices".
221 | 
222 |     c) You must license the entire work, as a whole, under this
223 |     License to anyone who comes into possession of a copy.  This
224 |     License will therefore apply, along with any applicable section 7
225 |     additional terms, to the whole of the work, and all its parts,
226 |     regardless of how they are packaged.  This License gives no
227 |     permission to license the work in any other way, but it does not
228 |     invalidate such permission if you have separately received it.
229 | 
230 |     d) If the work has interactive user interfaces, each must display
231 |     Appropriate Legal Notices; however, if the Program has interactive
232 |     interfaces that do not display Appropriate Legal Notices, your
233 |     work need not make them do so.
234 | 
235 |   A compilation of a covered work with other separate and independent
236 | works, which are not by their nature extensions of the covered work,
237 | and which are not combined with it such as to form a larger program,
238 | in or on a volume of a storage or distribution medium, is called an
239 | "aggregate" if the compilation and its resulting copyright are not
240 | used to limit the access or legal rights of the compilation's users
241 | beyond what the individual works permit.  Inclusion of a covered work
242 | in an aggregate does not cause this License to apply to the other
243 | parts of the aggregate.
244 | 
245 |   6. Conveying Non-Source Forms.
246 | 
247 |   You may convey a covered work in object code form under the terms
248 | of sections 4 and 5, provided that you also convey the
249 | machine-readable Corresponding Source under the terms of this License,
250 | in one of these ways:
251 | 
252 |     a) Convey the object code in, or embodied in, a physical product
253 |     (including a physical distribution medium), accompanied by the
254 |     Corresponding Source fixed on a durable physical medium
255 |     customarily used for software interchange.
256 | 
257 |     b) Convey the object code in, or embodied in, a physical product
258 |     (including a physical distribution medium), accompanied by a
259 |     written offer, valid for at least three years and valid for as
260 |     long as you offer spare parts or customer support for that product
261 |     model, to give anyone who possesses the object code either (1) a
262 |     copy of the Corresponding Source for all the software in the
263 |     product that is covered by this License, on a durable physical
264 |     medium customarily used for software interchange, for a price no
265 |     more than your reasonable cost of physically performing this
266 |     conveying of source, or (2) access to copy the
267 |     Corresponding Source from a network server at no charge.
268 | 
269 |     c) Convey individual copies of the object code with a copy of the
270 |     written offer to provide the Corresponding Source.  This
271 |     alternative is allowed only occasionally and noncommercially, and
272 |     only if you received the object code with such an offer, in accord
273 |     with subsection 6b.
274 | 
275 |     d) Convey the object code by offering access from a designated
276 |     place (gratis or for a charge), and offer equivalent access to the
277 |     Corresponding Source in the same way through the same place at no
278 |     further charge.  You need not require recipients to copy the
279 |     Corresponding Source along with the object code.  If the place to
280 |     copy the object code is a network server, the Corresponding Source
281 |     may be on a different server (operated by you or a third party)
282 |     that supports equivalent copying facilities, provided you maintain
283 |     clear directions next to the object code saying where to find the
284 |     Corresponding Source.  Regardless of what server hosts the
285 |     Corresponding Source, you remain obligated to ensure that it is
286 |     available for as long as needed to satisfy these requirements.
287 | 
288 |     e) Convey the object code using peer-to-peer transmission, provided
289 |     you inform other peers where the object code and Corresponding
290 |     Source of the work are being offered to the general public at no
291 |     charge under subsection 6d.
292 | 
293 |   A separable portion of the object code, whose source code is excluded
294 | from the Corresponding Source as a System Library, need not be
295 | included in conveying the object code work.
296 | 
297 |   A "User Product" is either (1) a "consumer product", which means any
298 | tangible personal property which is normally used for personal, family,
299 | or household purposes, or (2) anything designed or sold for incorporation
300 | into a dwelling.  In determining whether a product is a consumer product,
301 | doubtful cases shall be resolved in favor of coverage.  For a particular
302 | product received by a particular user, "normally used" refers to a
303 | typical or common use of that class of product, regardless of the status
304 | of the particular user or of the way in which the particular user
305 | actually uses, or expects or is expected to use, the product.  A product
306 | is a consumer product regardless of whether the product has substantial
307 | commercial, industrial or non-consumer uses, unless such uses represent
308 | the only significant mode of use of the product.
309 | 
310 |   "Installation Information" for a User Product means any methods,
311 | procedures, authorization keys, or other information required to install
312 | and execute modified versions of a covered work in that User Product from
313 | a modified version of its Corresponding Source.  The information must
314 | suffice to ensure that the continued functioning of the modified object
315 | code is in no case prevented or interfered with solely because
316 | modification has been made.
317 | 
318 |   If you convey an object code work under this section in, or with, or
319 | specifically for use in, a User Product, and the conveying occurs as
320 | part of a transaction in which the right of possession and use of the
321 | User Product is transferred to the recipient in perpetuity or for a
322 | fixed term (regardless of how the transaction is characterized), the
323 | Corresponding Source conveyed under this section must be accompanied
324 | by the Installation Information.  But this requirement does not apply
325 | if neither you nor any third party retains the ability to install
326 | modified object code on the User Product (for example, the work has
327 | been installed in ROM).
328 | 
329 |   The requirement to provide Installation Information does not include a
330 | requirement to continue to provide support service, warranty, or updates
331 | for a work that has been modified or installed by the recipient, or for
332 | the User Product in which it has been modified or installed.  Access to a
333 | network may be denied when the modification itself materially and
334 | adversely affects the operation of the network or violates the rules and
335 | protocols for communication across the network.
336 | 
337 |   Corresponding Source conveyed, and Installation Information provided,
338 | in accord with this section must be in a format that is publicly
339 | documented (and with an implementation available to the public in
340 | source code form), and must require no special password or key for
341 | unpacking, reading or copying.
342 | 
343 |   7. Additional Terms.
344 | 
345 |   "Additional permissions" are terms that supplement the terms of this
346 | License by making exceptions from one or more of its conditions.
347 | Additional permissions that are applicable to the entire Program shall
348 | be treated as though they were included in this License, to the extent
349 | that they are valid under applicable law.  If additional permissions
350 | apply only to part of the Program, that part may be used separately
351 | under those permissions, but the entire Program remains governed by
352 | this License without regard to the additional permissions.
353 | 
354 |   When you convey a copy of a covered work, you may at your option
355 | remove any additional permissions from that copy, or from any part of
356 | it.  (Additional permissions may be written to require their own
357 | removal in certain cases when you modify the work.)  You may place
358 | additional permissions on material, added by you to a covered work,
359 | for which you have or can give appropriate copyright permission.
360 | 
361 |   Notwithstanding any other provision of this License, for material you
362 | add to a covered work, you may (if authorized by the copyright holders of
363 | that material) supplement the terms of this License with terms:
364 | 
365 |     a) Disclaiming warranty or limiting liability differently from the
366 |     terms of sections 15 and 16 of this License; or
367 | 
368 |     b) Requiring preservation of specified reasonable legal notices or
369 |     author attributions in that material or in the Appropriate Legal
370 |     Notices displayed by works containing it; or
371 | 
372 |     c) Prohibiting misrepresentation of the origin of that material, or
373 |     requiring that modified versions of such material be marked in
374 |     reasonable ways as different from the original version; or
375 | 
376 |     d) Limiting the use for publicity purposes of names of licensors or
377 |     authors of the material; or
378 | 
379 |     e) Declining to grant rights under trademark law for use of some
380 |     trade names, trademarks, or service marks; or
381 | 
382 |     f) Requiring indemnification of licensors and authors of that
383 |     material by anyone who conveys the material (or modified versions of
384 |     it) with contractual assumptions of liability to the recipient, for
385 |     any liability that these contractual assumptions directly impose on
386 |     those licensors and authors.
387 | 
388 |   All other non-permissive additional terms are considered "further
389 | restrictions" within the meaning of section 10.  If the Program as you
390 | received it, or any part of it, contains a notice stating that it is
391 | governed by this License along with a term that is a further
392 | restriction, you may remove that term.  If a license document contains
393 | a further restriction but permits relicensing or conveying under this
394 | License, you may add to a covered work material governed by the terms
395 | of that license document, provided that the further restriction does
396 | not survive such relicensing or conveying.
397 | 
398 |   If you add terms to a covered work in accord with this section, you
399 | must place, in the relevant source files, a statement of the
400 | additional terms that apply to those files, or a notice indicating
401 | where to find the applicable terms.
402 | 
403 |   Additional terms, permissive or non-permissive, may be stated in the
404 | form of a separately written license, or stated as exceptions;
405 | the above requirements apply either way.
406 | 
407 |   8. Termination.
408 | 
409 |   You may not propagate or modify a covered work except as expressly
410 | provided under this License.  Any attempt otherwise to propagate or
411 | modify it is void, and will automatically terminate your rights under
412 | this License (including any patent licenses granted under the third
413 | paragraph of section 11).
414 | 
415 |   However, if you cease all violation of this License, then your
416 | license from a particular copyright holder is reinstated (a)
417 | provisionally, unless and until the copyright holder explicitly and
418 | finally terminates your license, and (b) permanently, if the copyright
419 | holder fails to notify you of the violation by some reasonable means
420 | prior to 60 days after the cessation.
421 | 
422 |   Moreover, your license from a particular copyright holder is
423 | reinstated permanently if the copyright holder notifies you of the
424 | violation by some reasonable means, this is the first time you have
425 | received notice of violation of this License (for any work) from that
426 | copyright holder, and you cure the violation prior to 30 days after
427 | your receipt of the notice.
428 | 
429 |   Termination of your rights under this section does not terminate the
430 | licenses of parties who have received copies or rights from you under
431 | this License.  If your rights have been terminated and not permanently
432 | reinstated, you do not qualify to receive new licenses for the same
433 | material under section 10.
434 | 
435 |   9. Acceptance Not Required for Having Copies.
436 | 
437 |   You are not required to accept this License in order to receive or
438 | run a copy of the Program.  Ancillary propagation of a covered work
439 | occurring solely as a consequence of using peer-to-peer transmission
440 | to receive a copy likewise does not require acceptance.  However,
441 | nothing other than this License grants you permission to propagate or
442 | modify any covered work.  These actions infringe copyright if you do
443 | not accept this License.  Therefore, by modifying or propagating a
444 | covered work, you indicate your acceptance of this License to do so.
445 | 
446 |   10. Automatic Licensing of Downstream Recipients.
447 | 
448 |   Each time you convey a covered work, the recipient automatically
449 | receives a license from the original licensors, to run, modify and
450 | propagate that work, subject to this License.  You are not responsible
451 | for enforcing compliance by third parties with this License.
452 | 
453 |   An "entity transaction" is a transaction transferring control of an
454 | organization, or substantially all assets of one, or subdividing an
455 | organization, or merging organizations.  If propagation of a covered
456 | work results from an entity transaction, each party to that
457 | transaction who receives a copy of the work also receives whatever
458 | licenses to the work the party's predecessor in interest had or could
459 | give under the previous paragraph, plus a right to possession of the
460 | Corresponding Source of the work from the predecessor in interest, if
461 | the predecessor has it or can get it with reasonable efforts.
462 | 
463 |   You may not impose any further restrictions on the exercise of the
464 | rights granted or affirmed under this License.  For example, you may
465 | not impose a license fee, royalty, or other charge for exercise of
466 | rights granted under this License, and you may not initiate litigation
467 | (including a cross-claim or counterclaim in a lawsuit) alleging that
468 | any patent claim is infringed by making, using, selling, offering for
469 | sale, or importing the Program or any portion of it.
470 | 
471 |   11. Patents.
472 | 
473 |   A "contributor" is a copyright holder who authorizes use under this
474 | License of the Program or a work on which the Program is based.  The
475 | work thus licensed is called the contributor's "contributor version".
476 | 
477 |   A contributor's "essential patent claims" are all patent claims
478 | owned or controlled by the contributor, whether already acquired or
479 | hereafter acquired, that would be infringed by some manner, permitted
480 | by this License, of making, using, or selling its contributor version,
481 | but do not include claims that would be infringed only as a
482 | consequence of further modification of the contributor version.  For
483 | purposes of this definition, "control" includes the right to grant
484 | patent sublicenses in a manner consistent with the requirements of
485 | this License.
486 | 
487 |   Each contributor grants you a non-exclusive, worldwide, royalty-free
488 | patent license under the contributor's essential patent claims, to
489 | make, use, sell, offer for sale, import and otherwise run, modify and
490 | propagate the contents of its contributor version.
491 | 
492 |   In the following three paragraphs, a "patent license" is any express
493 | agreement or commitment, however denominated, not to enforce a patent
494 | (such as an express permission to practice a patent or covenant not to
495 | sue for patent infringement).  To "grant" such a patent license to a
496 | party means to make such an agreement or commitment not to enforce a
497 | patent against the party.
498 | 
499 |   If you convey a covered work, knowingly relying on a patent license,
500 | and the Corresponding Source of the work is not available for anyone
501 | to copy, free of charge and under the terms of this License, through a
502 | publicly available network server or other readily accessible means,
503 | then you must either (1) cause the Corresponding Source to be so
504 | available, or (2) arrange to deprive yourself of the benefit of the
505 | patent license for this particular work, or (3) arrange, in a manner
506 | consistent with the requirements of this License, to extend the patent
507 | license to downstream recipients.  "Knowingly relying" means you have
508 | actual knowledge that, but for the patent license, your conveying the
509 | covered work in a country, or your recipient's use of the covered work
510 | in a country, would infringe one or more identifiable patents in that
511 | country that you have reason to believe are valid.
512 | 
513 |   If, pursuant to or in connection with a single transaction or
514 | arrangement, you convey, or propagate by procuring conveyance of, a
515 | covered work, and grant a patent license to some of the parties
516 | receiving the covered work authorizing them to use, propagate, modify
517 | or convey a specific copy of the covered work, then the patent license
518 | you grant is automatically extended to all recipients of the covered
519 | work and works based on it.
520 | 
521 |   A patent license is "discriminatory" if it does not include within
522 | the scope of its coverage, prohibits the exercise of, or is
523 | conditioned on the non-exercise of one or more of the rights that are
524 | specifically granted under this License.  You may not convey a covered
525 | work if you are a party to an arrangement with a third party that is
526 | in the business of distributing software, under which you make payment
527 | to the third party based on the extent of your activity of conveying
528 | the work, and under which the third party grants, to any of the
529 | parties who would receive the covered work from you, a discriminatory
530 | patent license (a) in connection with copies of the covered work
531 | conveyed by you (or copies made from those copies), or (b) primarily
532 | for and in connection with specific products or compilations that
533 | contain the covered work, unless you entered into that arrangement,
534 | or that patent license was granted, prior to 28 March 2007.
535 | 
536 |   Nothing in this License shall be construed as excluding or limiting
537 | any implied license or other defenses to infringement that may
538 | otherwise be available to you under applicable patent law.
539 | 
540 |   12. No Surrender of Others' Freedom.
541 | 
542 |   If conditions are imposed on you (whether by court order, agreement or
543 | otherwise) that contradict the conditions of this License, they do not
544 | excuse you from the conditions of this License.  If you cannot convey a
545 | covered work so as to satisfy simultaneously your obligations under this
546 | License and any other pertinent obligations, then as a consequence you may
547 | not convey it at all.  For example, if you agree to terms that obligate you
548 | to collect a royalty for further conveying from those to whom you convey
549 | the Program, the only way you could satisfy both those terms and this
550 | License would be to refrain entirely from conveying the Program.
551 | 
552 |   13. Use with the GNU Affero General Public License.
553 | 
554 |   Notwithstanding any other provision of this License, you have
555 | permission to link or combine any covered work with a work licensed
556 | under version 3 of the GNU Affero General Public License into a single
557 | combined work, and to convey the resulting work.  The terms of this
558 | License will continue to apply to the part which is the covered work,
559 | but the special requirements of the GNU Affero General Public License,
560 | section 13, concerning interaction through a network will apply to the
561 | combination as such.
562 | 
563 |   14. Revised Versions of this License.
564 | 
565 |   The Free Software Foundation may publish revised and/or new versions of
566 | the GNU General Public License from time to time.  Such new versions will
567 | be similar in spirit to the present version, but may differ in detail to
568 | address new problems or concerns.
569 | 
570 |   Each version is given a distinguishing version number.  If the
571 | Program specifies that a certain numbered version of the GNU General
572 | Public License "or any later version" applies to it, you have the
573 | option of following the terms and conditions either of that numbered
574 | version or of any later version published by the Free Software
575 | Foundation.  If the Program does not specify a version number of the
576 | GNU General Public License, you may choose any version ever published
577 | by the Free Software Foundation.
578 | 
579 |   If the Program specifies that a proxy can decide which future
580 | versions of the GNU General Public License can be used, that proxy's
581 | public statement of acceptance of a version permanently authorizes you
582 | to choose that version for the Program.
583 | 
584 |   Later license versions may give you additional or different
585 | permissions.  However, no additional obligations are imposed on any
586 | author or copyright holder as a result of your choosing to follow a
587 | later version.
588 | 
589 |   15. Disclaimer of Warranty.
590 | 
591 |   THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
592 | APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
596 | PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
597 | IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
599 | 
600 |   16. Limitation of Liability.
601 | 
602 |   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
610 | SUCH DAMAGES.
611 | 
612 |   17. Interpretation of Sections 15 and 16.
613 | 
614 |   If the disclaimer of warranty and limitation of liability provided
615 | above cannot be given local legal effect according to their terms,
616 | reviewing courts shall apply local law that most closely approximates
617 | an absolute waiver of all civil liability in connection with the
618 | Program, unless a warranty or assumption of liability accompanies a
619 | copy of the Program in return for a fee.
620 | 
621 |                      END OF TERMS AND CONDITIONS
622 | 
623 |             How to Apply These Terms to Your New Programs
624 | 
625 |   If you develop a new program, and you want it to be of the greatest
626 | possible use to the public, the best way to achieve this is to make it
627 | free software which everyone can redistribute and change under these terms.
628 | 
629 |   To do so, attach the following notices to the program.  It is safest
630 | to attach them to the start of each source file to most effectively
631 | state the exclusion of warranty; and each file should have at least
632 | the "copyright" line and a pointer to where the full notice is found.
633 | 
634 |     <one line to give the program's name and a brief idea of what it does.>
635 |     Copyright (C) <year>  <name of author>
636 | 
637 |     This program is free software: you can redistribute it and/or modify
638 |     it under the terms of the GNU General Public License as published by
639 |     the Free Software Foundation, either version 3 of the License, or
640 |     (at your option) any later version.
641 | 
642 |     This program is distributed in the hope that it will be useful,
643 |     but WITHOUT ANY WARRANTY; without even the implied warranty of
644 |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
645 |     GNU General Public License for more details.
646 | 
647 |     You should have received a copy of the GNU General Public License
648 |     along with this program.  If not, see <http://www.gnu.org/licenses/>.
649 | 
650 | Also add information on how to contact you by electronic and paper mail.
651 | 
652 |   If the program does terminal interaction, make it output a short
653 | notice like this when it starts in an interactive mode:
654 | 
655 |     <program>  Copyright (C) <year>  <name of author>
656 |     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
657 |     This is free software, and you are welcome to redistribute it
658 |     under certain conditions; type `show c' for details.
659 | 
660 | The hypothetical commands `show w' and `show c' should show the appropriate
661 | parts of the General Public License.  Of course, your program's commands
662 | might be different; for a GUI interface, you would use an "about box".
663 | 
664 |   You should also get your employer (if you work as a programmer) or school,
665 | if any, to sign a "copyright disclaimer" for the program, if necessary.
666 | For more information on this, and how to apply and follow the GNU GPL, see
667 | <http://www.gnu.org/licenses/>.
668 | 
669 |   The GNU General Public License does not permit incorporating your program
670 | into proprietary programs.  If your program is a subroutine library, you
671 | may consider it more useful to permit linking proprietary applications with
672 | the library.  If this is what you want to do, use the GNU Lesser General
673 | Public License instead of this License.  But first, please read
674 | <http://www.gnu.org/philosophy/why-not-lgpl.html>.


--------------------------------------------------------------------------------