Merge pull request #52 from matthewtownson/master

Updating turbulence documentation

Author: andrewpaulreeves

.travis.yml

@@ -1,6 +1,6 @@
 language: python
 sudo: true
-dist: xenial
+dist: bionic
 
 branches:
   only:
@@ -12,6 +12,7 @@ python:
 #- 3.5 Not in travis repositories
 - 3.6
 - 3.7
+- 3.8
 
 addons:
   apt:

aotools/turbulence/atmos_conversions.py

@@ -158,9 +158,17 @@ def r0_from_slopes(slopes, wavelength, subapDiam):
 
 
 def slope_variance_from_r0(r0, wavelength, subapDiam):
-    """Returns the expected slope variance for a given r0 ValueError
+    """
+    Uses the equation in Saint Jaques, 1998, PhD Thesis, Appendix A to calculate the slope variance resulting from a
+    value of r0.
+
+    Parameters:
+        r0 (float): Fried papamerter of turubulence in metres
+        wavelength (float): Wavelength of light in metres (where 1e-9 is 1nm)
+        subapDiam (float): Diameter of the aperture in metres
 
-    Uses the equation in Saint Jaques, 1998, PhD Thesis, Appendix A to calculate the slope variance resulting from a value of r0.
+    Returns:
+        The expected slope variance for a given r0 ValueError
 
     """
 

aotools/turbulence/infinitephasescreen.py

@@ -15,14 +15,15 @@
 
 __all__ = ["PhaseScreenVonKarman", "PhaseScreenKolmogorov"]
 
+
 class PhaseScreen(object):
     """
     A "Phase Screen" for use in AO simulation.  Can be extruded infinitely.
 
     This represents the phase addition light experiences when passing through atmospheric 
     turbulence. Unlike other phase screen generation techniques that translate a large static 
-    screen, this method keeps a small section of phase, and extends it as neccessary for as many 
-    steps as required. This can significantly reduce memory consuption at the expense of more 
+    screen, this method keeps a small section of phase, and extends it as necessary for as many
+    steps as required. This can significantly reduce memory consumption at the expense of more
     processing power required.
 
     The technique is described in a paper by Assemat and Wilson, 2006 and expanded upon by Fried, 2008.
@@ -55,7 +56,7 @@ class PhaseScreen(object):
     L is a diagonal matrix where the diagonal elements are w^(1/2).    
 
     On initialisation an initial phase screen is calculated using an FFT based method.
-    When 'addRows' is called, a new vector of phase is added to the phase screen.
+    When 'add_row' is called, a new vector of phase is added to the phase screen.
 
     Existing points to use are defined by a "stencil", than is set to 0 for points not to use
     and 1 for points to use. This makes this a generalised base class that can be used by 
@@ -180,11 +181,7 @@ def get_new_row(self):
 
     def add_row(self):
         """
-        Adds new rows to the phase screen and removes old ones.
-
-        Parameters:
-            nRows (int): Number of rows to add
-            axis (int): Axis to add new rows (can be 0 (default) or 1)
+        Adds a new row to the phase screen and removes old ones.
         """
 
         new_row = self.get_new_row()
@@ -195,6 +192,9 @@ def add_row(self):
 
     @property
     def scrn(self):
+        """
+        The current phase map held in the PhaseScreen object.
+        """
         return self._scrn[:self.requested_nx_size, :self.requested_nx_size]
 
 
@@ -204,8 +204,8 @@ class PhaseScreenVonKarman(PhaseScreen):
 
     This represents the phase addition light experiences when passing through atmospheric
     turbulence. Unlike other phase screen generation techniques that translate a large static
-    screen, this method keeps a small section of phase, and extends it as neccessary for as many
-    steps as required. This can significantly reduce memory consuption at the expense of more
+    screen, this method keeps a small section of phase, and extends it as necessary for as many
+    steps as required. This can significantly reduce memory consumption at the expense of more
     processing power required.
 
     The technique is described in a paper by Assemat and Wilson, 2006. It essentially assumes that
@@ -237,9 +237,9 @@ class PhaseScreenVonKarman(PhaseScreen):
     L is a diagonal matrix where the diagonal elements are w^(1/2).
 
     On initialisation an initial phase screen is calculated using an FFT based method.
-    When 'addRows' is called, a new vector of phase is added to the phase screen using `nCols`
+    When ``add_row`` is called, a new vector of phase is added to the phase screen using `nCols`
     columns of previous phase. Assemat & Wilson claim that two columns are adequate for good
-    atmospheric statistics. The phase in the screen data is always accessed as `<phasescreen>.scrn`.
+    atmospheric statistics. The phase in the screen data is always accessed as ``<phasescreen>.scrn``.
 
     Parameters:
         nx_size (int): Size of phase screen (NxN)
@@ -346,7 +346,8 @@ class PhaseScreenKolmogorov(PhaseScreen):
     and applied on each iteration such that the new phase equation becomes:
     
     On initialisation an initial phase screen is calculated using an FFT based method.
-    When 'addRows' is called, a new vector of phase is added to the phase screen.
+    When ``add_row`` is called, a new vector of phase is added to the phase screen. The phase in the screen data
+    is always accessed as ``<phasescreen>.scrn``.
 
     Parameters:
         nx_size (int): Size of phase screen (NxN)

aotools/turbulence/phasescreen.py

@@ -2,7 +2,7 @@
 Finite Phase Screens
 --------------------
 
-Creation of phase screens with Von Karmen Statistics.
+Creation of phase screens of a defined size with Von Karmen Statistics.
 
 """
 
@@ -18,7 +18,8 @@
     xrange = range
 
 def ft_sh_phase_screen(r0, N, delta, L0, l0, FFT=None, seed=None):
-    '''
+
+    """
     Creates a random phase screen with Von Karmen statistics with added
     sub-harmonics to augment tip-tilt modes.
     (Schmidt 2010)
@@ -32,7 +33,7 @@ def ft_sh_phase_screen(r0, N, delta, L0, l0, FFT=None, seed=None):
 
     Returns:
         ndarray: numpy array representing phase screen
-    '''
+    """
     R = random.SystemRandom(time.time())
     if seed is None:
         seed = int(R.random()*100000)
@@ -60,7 +61,7 @@ def ft_sh_phase_screen(r0, N, delta, L0, l0, FFT=None, seed=None):
         f = numpy.sqrt(fx**2 +  fy**2) # polar grid
 
         fm = 5.92/l0/(2*numpy.pi) # inner scale frequency [1/m]
-        f0 = 1./L0;
+        f0 = 1./L0
 
         # outer scale frequency [1/m]
         # modified von Karman atmospheric phase PSD
@@ -89,28 +90,8 @@ def ft_sh_phase_screen(r0, N, delta, L0, l0, FFT=None, seed=None):
     return phs
 
 
-def ift2(G, delta_f ,FFT=None):
-    """
-    Wrapper for inverse fourier transform
-
-    Parameters:
-        G: data to transform
-        delta_f: pixel seperation
-        FFT (FFT object, optional): An accelerated FFT object
-    """
-        
-    N = G.shape[0]
-
-    if FFT:
-        g = numpy.fft.fftshift( FFT( numpy.fft.fftshift(G) ) ) * (N * delta_f)**2
-    else:
-        g = fft.ifftshift( fft.ifft2( fft.fftshift(G) ) ) * (N * delta_f)**2
-
-    return g
-
-
 def ft_phase_screen(r0, N, delta, L0, l0, FFT=None, seed=None):
-    '''
+    """
     Creates a random phase screen with Von Karmen statistics.
     (Schmidt 2010)
     
@@ -123,7 +104,7 @@ def ft_phase_screen(r0, N, delta, L0, l0, FFT=None, seed=None):
 
     Returns:
         ndarray: numpy array representing phase screen
-    '''
+    """
     delta = float(delta)
     r0 = float(r0)
     L0 = float(L0)
@@ -136,22 +117,40 @@ def ft_phase_screen(r0, N, delta, L0, l0, FFT=None, seed=None):
 
     del_f = 1./(N*delta)
 
-    fx = numpy.arange(-N/2.,N/2.) * del_f
+    fx = numpy.arange(-N/2., N/2.) * del_f
 
-    (fx,fy) = numpy.meshgrid(fx,fx)
-    f = numpy.sqrt(fx**2 + fy**2)
+    (fx, fy) = numpy.meshgrid(fx,fx)
+    f = numpy.sqrt(fx**2. + fy**2.)
 
     fm = 5.92/l0/(2*numpy.pi)
     f0 = 1./L0
 
-    PSD_phi  = (0.023*r0**(-5./3.) * numpy.exp(-1*((f/fm)**2)) /
-                ( ( (f**2) + (f0**2) )**(11./6) ) )
+    PSD_phi = (0.023*r0**(-5./3.) * numpy.exp(-1*((f/fm)**2)) / (((f**2) + (f0**2))**(11./6)))
 
     PSD_phi[int(N/2), int(N/2)] = 0
 
-    cn = ( (numpy.random.normal(size=(N,N)) + 1j* numpy.random.normal(size=(N,N)) )
-                * numpy.sqrt(PSD_phi)*del_f )
+    cn = ((numpy.random.normal(size=(N, N))+1j * numpy.random.normal(size=(N, N))) * numpy.sqrt(PSD_phi)*del_f)
+
+    phs = ift2(cn, 1, FFT).real
+
+    return phs
+
 
-    phs = ift2(cn,1, FFT).real
+def ift2(G, delta_f, FFT=None):
+    """
+    Wrapper for inverse fourier transform
 
-    return phs
+    Parameters:
+        G: data to transform
+        delta_f: pixel seperation
+        FFT (FFT object, optional): An accelerated FFT object
+    """
+
+    N = G.shape[0]
+
+    if FFT:
+        g = numpy.fft.fftshift(FFT(numpy.fft.fftshift(G))) * (N * delta_f) ** 2
+    else:
+        g = fft.ifftshift(fft.ifft2(fft.fftshift(G))) * (N * delta_f) ** 2
+
+    return g

aotools/turbulence/slopecovariance.py

@@ -7,7 +7,7 @@
 WFS measurements in a required direction (where there might be an interesting science target but no guide stars),
 given some actual measurements in other directions (where the some suitable guide stars are).
 
-.. note::
+.. warning::
     This code has been tested qualitatively and seems OK, but needs more rigorous testing.
 
 .. codeauthor::

doc/source/index.rst

@@ -3,10 +3,28 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to AOTools's documentation!
-===================================
+Welcome to the AOtools Documentation!
+=====================================
 
-Contents:
+Introduction
+++++++++++++
+AOtools is an attempt to gather together many common tools, equations and functions for Adaptive Optics.
+The idea is to provide an alternative to the current model, where a new AO researcher must write their own library
+of tools, many of which implement theory and ideas that have been in existance for over 20 years. AOtools will hopefully
+provide a common place to put these tools, which through use and bug fixes, should become reliable and well documented.
+
+Installation
+------------
+AOtools uses mainly standard library functions, and all attempts have been made to avoid adding unneccessary dependencies.
+Currently, the library requires only
+
+- numpy
+- scipy
+- astropy
+- matplotlib
+
+Contents
+++++++++
 
 .. toctree::
    :maxdepth: 2

doc/source/turbulence.rst

@@ -1,32 +1,24 @@
 Atmospheric Turbulence
 ======================
 
-.. automodule:: aotools.turbulence
-   :members:
-   :undoc-members:
-   :imported-members:
-   :exclude-members: CovarianceMatrix, PhaseScreenKolmogorov, PhaseScreenVonKarman, calc_slope_temporalps,
-                     calculate_structure_function, calculate_wfs_seperations, circle, cn2_to_r0, cn2_to_seeing,
-                     coherenceTime, compute_covariance_xx, compute_covariance_xy, compute_covariance_yy,
-                     create_tomographic_covariance_reconstructor, fft, fit_tps, ft_phase_screen, ft_sh_phase_screen,
-                     get_tps_time_axis, ift2, isoplanaticAngle, mirror_covariance_matrix, numpy, optimize,
-                     plot_tps, pyplot, r0_from_slopes, r0_to_cn2, r0_to_seeing, scipy, seeing_to_cn2, seeing_to_r0,
-                     slope_variance_from_r0, structure_function_kolmogorov, structure_function_vk, wfs_covariance,
-                     wfs_covariance_mpwrap, xrange
-
 .. automodule:: aotools.turbulence.phasescreen
     :members:
     :undoc-members:
+    :exclude-members: ift2
     :show-inheritance:
 
 .. automodule:: aotools.turbulence.infinitephasescreen
     :members:
+    :inherited-members:
     :undoc-members:
+    :exclude-members: calc_seperations, set_stencil_coords, calc_seperations, makeAMatrix, makeBMatrix, set_X_coords,
+                      make_initial_screen, make_covmats, get_new_row
     :show-inheritance:
 
 .. automodule:: aotools.turbulence.slopecovariance
     :members:
     :undoc-members:
+    :exclude-members: compute_covariance_xx, compute_covariance_xy, compute_covariance_yy
     :show-inheritance:
 
 .. automodule:: aotools.turbulence.temporal_ps

setup.py

@@ -23,6 +23,7 @@
     install_requires=[
         'numpy',
         'scipy',
+        'matplotlib'
     ],
     classifiers=[
         "Programming Language :: Python",