Merge pull request #334 from mperrin/master

release notes for 0.9 and documentation improvements

.travis.yml

@@ -39,7 +39,7 @@ matrix:
         - python: 3.6
           env: SETUP_CMD='build_sphinx'
                CONDA_DEPENDENCIES='scipy matplotlib nbsphinx pandoc'
-               PIP_DEPENDENCIES='sphinx_rtd_theme stsci_rtd_theme sphinx-automodapi'
+               PIP_DEPENDENCIES='sphinx_rtd_theme stsci_rtd_theme sphinx-automodapi sphinx-issues'
 
 
         # Try Astropy development version

docs/about.rst

@@ -30,19 +30,21 @@ list of contributors.
 Direct contributors to POPPY code
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
- * Marshall Perrin (@mperrin)
- * Joseph Long (@josephoenix)
- * Ewan Douglas (@douglase)
- * Shannon Osborne (@shanosborne)
- * Neil Zimmerman (@neilzim)
- * Anand Sivaramakrishnan (@anand0xff)
- * Maciek Grochowicz (@maciekgroch)
- * Phillip Springer (@daphil)
- * Ted Corcovilos (@corcoted)
- * Kyle Douglass (@kmdouglas)
- * Christine Slocum (@cslocum)
- * Matt Mechtley (@mmechtley)
- * Scott Will (@sdwill)
+ * Marshall Perrin (:user:`mperrin`)
+ * Joseph Long (:user:`josephoenix`)
+ * Ewan Douglas (:user:`douglase`)
+ * Shannon Osborne (:user:`shanosborne`)
+ * Neil Zimmerman (:user:`neilzim`)
+ * Anand Sivaramakrishnan (:user:`anand0xff`)
+ * Maciek Grochowicz (:user:`maciekgroch`)
+ * Phillip Springer (:user:`daphil`)
+ * Ted Corcovilos (:user:`corcoted`)
+ * Kyle Douglass (:user:`kmdouglas`)
+ * Christine Slocum (:user:`cslocum`)
+ * Matt Mechtley (:user:`mmechtley`)
+ * Scott Will (:user:`sdwill`)
+ * Iva Laginja (:user:`ivalaginja`)
+ * Mike Fitzgerald (:user:`astrofitz`)
 
 Indirect Contributors (algorithms, advice, ideas, inspirations)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/conf.py

@@ -71,6 +71,7 @@ def setup(app):
     'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
     'sphinx_automodapi.automodapi',
+    'sphinx_issues'
     ]
 numpydoc_show_class_members = False
 
@@ -107,6 +108,14 @@ def setup(app):
 
 # -- Project information ------------------------------------------------------
 
+
+# Github integration via sphinx-issues plugin
+# See https://github.com/sloria/sphinx-issues
+
+# Github repo
+issues_github_path = "spacetelescope/poppy"
+
+
 # This does not *have* to match the package name, but typically does
 project = setup_cfg['package_name']
 author = setup_cfg['author']

docs/examples.rst

@@ -16,6 +16,10 @@ if you first enable Python's logging mechanism to display log messages to screen
         import logging
         logging.basicConfig(level=logging.DEBUG)
 
+
+.. contents:: :local:
+
+
 A simple circular pupil
 --------------------------
 
@@ -286,3 +290,58 @@ options can be set directly in the initialization of such elements::
    :scale: 100%
    :align: center
    :alt: Sample calculation result
+
+
+Adjusting Display of Intermediate Wavefronts
+----------------------------------------------
+
+
+When calculating a wavefront, you can display each intermediate wavefront plane, which often helps to visualize what's happening in a given propagation calculation. This is done by setting `display_intermediates=True`::
+
+        psf = osys.calc_psf(display_intermediates=True)
+
+Poppy attempts to guess reasonable defaults for displaying each intermediate planes, but sometimes you may wish to override these defaults. This can be done by setting
+"display hint" attributes on the planes of your optical system. Available options include
+
+ * `wavefront_display_hint` = `"intensity"` or `"phase"` to set what kind of display is shown for the complex wavefront at that plane
+ * `wavefront_display_vmax_hint` and `wavefront_display_vmin_hint` to adjust the parameters of the display scale
+ * `wavefront_display_imagecrop` to adjust the cropping or zoom of how much of a wavefront is displayed (by default, 
+   pupil planes are not cropped, while image planes are cropped to 5 arcseconds to better show the details of the inner core region of a PSF).
+ * `display_annotate` can be set to an arbitrary function to be called in order to apply custom annotations, or any other plot adjustment outside of the scope of
+   the above display hints.
+
+For instance, here's a variation of the above coronagraph calculation with some of the display parameters adjusted::
+
+    radius = 6.5/2 * u.m
+    lyot_radius = 6.5/2.5 *u.m
+    pixelscale = 0.060 *u.arcsec/u.pixel
+    osys = poppy.OpticalSystem(oversample=4)
+    pupil = poppy.CircularAperture(radius=radius)
+
+    occulter = poppy.CircularOcculter(radius = 0.1*u.arcsec)
+    # adjust display size and color scale after the occulter
+    occulter.wavefront_display_imagecrop = 1.0
+    occulter.wavefront_display_vmin_hint=1e-6
+
+    lyotstop = poppy.CircularAperture(radius=lyot_radius)
+    # hint that we would like to see intensity rather than phase after Lyot stop
+    lyotstop.wavefront_display_hint='intensity'
+
+    osys.add_pupil( pupil)
+    osys.add_image( occulter)
+    osys.add_pupil( lyotstop)
+    osys.add_detector(pixelscale=pixelscale, fov_arcsec=2.0)
+    # you can also set hints onto optics in the planes list
+    osys.planes[-1].wavefront_display_vmin_hint =  1e-6   
+
+    plt.figure(figsize=(8,8))
+    psf = osys.calc_psf(wavelength = 1*u.micron, display_intermediates=True)
+
+.. image:: ./example_display_hints.png
+   :scale: 100%
+   :align: center
+   :alt: Sample calculation result
+
+
+
+

docs/relnotes.rst

@@ -5,6 +5,88 @@ Release Notes
 
 For a list of contributors, see :ref:`about`.
 
+0.9.0
+-----
+
+.. _rel0.9.0:
+
+*2019 August 15*
+
+**New Functionality:**
+
+ * **Chaining together multiple propagations calculations:** Multiple `OpticalSystem` instances can now be chained together into a `CompoundOpticalSystem`. This includes mixed
+   propagations that are partially Fresnel and partially Fraunhofer; Wavefront objects will be cast between types as
+   needed. (:pr:`290` by :user:`mperrin`)
+ * **Gray pixel subsampling of apertures:** Implemented "gray pixel" sampling for circular apertures and stops, providing more precise models of aperture edges.
+   For circular apertures this is done  using a fast analytic geometry implementation adapted from open-source IDL code
+   originally by Marc Buie. (:pr:`325` by :user:`mperrin`, using Python code contributed by :user:`astrofitz`).
+   For subpixel / gray pixel sampling of other optics in general, a new function `fixed_sampling_optic` takes any
+   AnalyticOpticalElement and returns an equivalent ArrayOpticalElement with fixed sampling. This is useful for instance
+   for taking a computationally-slow optic such as MultiHexagonAperture and saving a discretized version for future
+   faster use. (:pr:`307` by :user:`mperrin`)
+ * **Modeling tilted optics:** New feature to model geometric projection (cosine scaling) of inclined optics, by setting an  `inclination_x` or
+   `inclination_y` attribute to the tilt angle in degrees. For instance `inclination_x=30` will tilt an optic by 30
+   degrees around the X axis, and thus compress its apparent size in the Y axis by cosine(30 deg). Note, this
+   transformation only applies the cosine scaling to the optic's appearance, and does *not* introduce wavefront for
+   tilt. (:pr:`329` by :user:`mperrin`)
+
+ * **Many improvements to the Continuous Deformable Mirror class**: 
+
+    * Enhance model of DM actuator influence functions for more precise subpixel spacing of DM actuators, rather than
+      pokes separated by integer pixel spacing. This applies to the 'convolution by influence function' method for
+      modeling DMs (:pr:`329` by :user:`mperrin`)
+    * Support distinct radii for the active controllable mirror size and the reflective mirror size (:pr:`293` by :user:`mperrin`)
+    * ContinuousDeformableMirror now supports `shift_x` and `shift_y` to translate / decenter the DM, consistent with
+      other optical element classes. (:pr:`307` by :user:`mperrin`)
+    * ContinuousDeformableMirror now also supports `flip_x` and `flip_y` attributes to flip its orientation along one or
+      both axes, as well as the new `inclination_x` and `inclination_y` attributes for geometric projection.
+
+ * **Improved models of certain kinds of wavefront error:**
+
+   * New class `StatisticalPSDWFE` that models random wavefront errors described by a power spectral density, as is
+     commonly used to specify and measure typical polishing residuals in optics. (:pr:`315` by :user:`ivalaginja`;
+     :pr:`317` by :user:`mperrin`)
+   * `FITSOpticalElement` can now support wavelength-independent phase maps defined in radians, for instance for modeling
+     Pancharatnam-Berry phase as used in certain vector coronagraph masks. (:pr:`306` by :user:`joseph-long`)
+
+ * `add_optic` in Fresnel systems can now insert optics at any index into an optical system, rather than just appending
+   at the end (:pr:`298` by :user:`sdwill`)
+
+**Software Infrastructure Updates and Internals:**
+
+ * PR :pr:`290` for CompoundOpticalSystem involved refactoring the Wavefront and FresnelWavefront classes to both be child classes of a new abstract base class BaseWavefront. This change should be transparent for most/all users and requires no changes in calling code.
+ * PR :pr:`306` for wavelength-independent phase subsequently required refactoring of the optical element display code to correctly handle all cases. As a result the display code internals were clarified and made more consistent. (:pr:`314` and :pr:`321`  by :user:`mperrin` with contributions from :user:`ivalaginja` and :user:`shanosborne`). Again this change should be transparent for users. 
+ * Removed deprecated / unused decorator function in WFE classes, making their `get_opd` function API consistent with the rest of poppy. (:pr:`322` by :user:`mperrin`)
+ * Accomodate some upstream changes in astropy (:pr:`294` by :user:`shanosborne`, :pr:`330` by :user:`mperrin`)
+ * The `poppy.Instrument._get_optical_system` function, which has heretofore been an internal method (private, starting with
+   underscore) of the Instrument class, has been promoted to a public part of the API as
+   `Instrument.get_optical_system()`.
+
+**Bug Fixes and Misc Improvements:**
+
+ * Correctly assign BUNIT keyword after rescaling OPDs (:issue:`285`, :pr:`286` by :user:`laurenmarietta`).
+ * New header keywords in output PSF files for `OPD_FILE` and `OPDSLICE` to more cleanly record the information
+   previously stored together in the `PUPILOPD` keyword (:pr:`316` by :user:`mperrin`)
+ * Update docs and example notebooks to replace deprecated function names with the current ones (:pr:`288` by :user:`corcoted`).
+ * Improvements in resampling wavefronts onto Detector instances, particularly in cases where the wavefront is already at the right plane so no propagation is needed. (Part of :pr:`290` by :user:`mperrin`, then further improved in :pr:`304` by :user:`sdwill`)
+ * Allow passthrough of "normalize" keyword to measure_ee and measure_radius_at_ee functions (:pr:`333` by
+   :user:`mperrin`; :issue:`332` by :user:`ariedel`)
+ * Fix `wavefront.as_fits` complex wavefront output option (:pr:`293` by :user:`mperrin`)
+ * Stricter checking for consistent wavefront type and size parameters when summing wavefronts (:pr:`313` and :pr:`326` by :user:`mperrin`)
+ * Fix an issue with MultiHexagonAperture in the specific case of 3 rings of hexes (:issue:`303` by :user:`LucasMarquis` and :user:`FredericCassaing`; :pr:`307` by :user:`mperrin`)
+ * Fix an issue with BaseWavefront class refactor (:pr:`311` by :user:`douglase` and :user:`jlumbres`)
+ * Fix an issue with indexing in HexSegmentedDeformableMirror when missing the center segment (:issue:`318` by :user:`ivalaginja`; :pr:`320` by :user:`mperrin`)
+ * Fix title display by OpticalElement.display function (:pr:`299` by :user:`shanosborne`)
+ * Fix display issue in SemiAnalyticCoronagraph class (:pr:`324` by :user:`mperrin`).
+ * Small improvements in some display labels (:pr:`307` by :user:`mperrin`)
+
+*Note*, the new functionality for gray pixel representation of circular apertures does not work precisely for elliptical
+apertures such as from inclined optics. You may see warnings about this in cases when you use `inclination_y` or
+`inclination_x` attributes on a circular aperture. This warning is generally benign; the calculation is still more
+accurate than it would be without the subpixel sampling, though not perfectly precise. This known issue will likely be
+improved upon in a future release. 
+
+
 0.8.0
 -----
 

poppy/geometry.py

@@ -204,7 +204,8 @@ def filled_circle_aa(shape, xcenter, ycenter, radius, xarray=None, yarray=None,
     area_per_pix = pixscale**2
 
     if np.abs(pixscale -1.0) > 0.01:
-        _log.warning('filled_circle_aa may not yield exact results for grey pixels when pixel scale <1')
+        import warnings
+        warnings.warn('filled_circle_aa may not yield exact results for grey pixels when pixel scale <1')
     border = np.where( np.abs(r-radius) < pixscale)
 
     weights = pixwt(xcenter, ycenter, radius, xarray[border], yarray[border])

poppy/instrument.py

@@ -607,6 +607,14 @@ def _get_optical_system(self, fft_oversample=2, detector_oversample=None, fov_ar
 
         return optsys
 
+    def get_optical_system(self, *args, **kwargs):
+        """ Return an OpticalSystem instance corresponding to the instrument as currently configured.
+
+        """
+        # Note, this has historically been an internal private API function (starting with an underscore)
+        # As of version 0.9 it is promoted to a public part of the API for the Instrument class and subclasses.
+        return self._get_optical_system(*args, **kwargs)
+
     def _check_for_aliasing(self, wavelengths):
         """ Check for spatial frequency aliasing and warn if the
         user is requesting a FOV which is larger than supported based on

setup.py

@@ -53,7 +53,7 @@
 metadata = dict(conf.items('metadata'))
 
 PACKAGENAME = metadata.get('package_name', 'packagename')
-DESCRIPTION = metadata.get('description', 'Astropy affiliated package')
+DESCRIPTION = metadata.get('description', 'unknown')
 AUTHOR = metadata.get('author', '')
 AUTHOR_EMAIL = metadata.get('author_email', '')
 LICENSE = metadata.get('license', 'unknown')
@@ -70,7 +70,7 @@
 builtins._ASTROPY_PACKAGE_NAME_ = PACKAGENAME
 
 # VERSION should be PEP386 compatible (http://www.python.org/dev/peps/pep-0386)
-VERSION = '0.8.1dev'
+VERSION = '0.9.0dev'
 
 # Indicates if this version is a release version
 RELEASE = 'dev' not in VERSION