Update sphinx docs for Quantity and Unit

docs/conf.py

@@ -68,6 +68,7 @@
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.napoleon',
     'sphinx.ext.coverage',
+    'sphinx.ext.intersphinx',
     'breathe',
     'gh-link',
 ]
@@ -77,6 +78,11 @@
 breathe_default_project = "GalSim"
 breathe_default_members = ('members', 'undoc-members')
 
+# Link to astropy
+intersphinx_mapping = {
+    'astropy': ('http://docs.astropy.org/en/stable/', None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 #templates_path = ['_templates']
 

docs/config_image.rst

@@ -344,9 +344,9 @@ other types, including custom Bandpass types.
 * 'FileBandpass' is the default type here, and you may omit the type name when using it.
 
     * ``file_name`` = *str_value* (required)  The file to read in.
-    * ``wave_type`` = *str_value* (required)  The unit of the wavelengths in the file ('nm' or 'Ang' or variations on these -- cf. `Bandpass`)
-    * ``blue_limit`` = *float_value* (optional)  Hard cut off on the blue side.
-    * ``red_limit`` = *float value* (optional)  Hard cut off on the red side.
+    * ``wave_type`` = *str_value* or *unit_value* (required)  The unit of the wavelengths in the file ('nm' or 'Ang' or variations on these -- cf. `Bandpass`)
+    * ``blue_limit`` = *float_value* or *quantity_value* (optional)  Hard cut off on the blue side.
+    * ``red_limit`` = *float value* or *quantity_value* (optional)  Hard cut off on the red side.
     * ``zeropoint`` = *float_value* (optional)  The zero-point to use.
     * ``thin`` = *float_value* (optional)  If given, call `Bandpass.thin` on the Bandpass after reading in from the file, using this for the ``rel_err``.
 

docs/config_objects.rst

@@ -33,26 +33,26 @@ PSF Types
 * 'Airy'  A simple Airy disk. (Typically one would convolve this by some model of the atmospheric component of the PSF.  cf. 'Convolution' below.)
 
     * ``lam_over_diam`` = *float_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required)  Lambda / telescope_diameter converted to units of arcsec (or whatever units you want your profile to use).
-    * ``lam`` = *float_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the wavelength in nanometers.
-    * ``diam`` = *float_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the telescope diameter in meters.
+    * ``lam`` = *float_value* or *quantity_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the wavelength in nanometers.
+    * ``diam`` = *float_value* or *quantity_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the telescope diameter in meters.
     * ``obscuration`` = *float_value* (default = 0)  The linear size of an obstructing secondary mirror as a fraction of the full mirror size.
     * ``scale_unit`` = *str_value* (default = 'arcsec') Units to be used for internal calculations when calculating lam/diam.
 
 * 'Kolmogorov'  A Kolmogorov turbulent spectrum: :math:`T(k) \sim \exp(-D(k)/2)`, where :math:`D(k) = 6.8839 (\lambda k/2\pi r0)^{5/3}`.
 
     * ``lam_over_r0`` = *float_value* (exactly one of ``lam_over_r0``, ``fwhm`` or ``half_light_radius`` or both ``lam`` and ``r0`` is required) Lambda / r0 converted to units of arcsec (or whatever units you want your profile to use).
-    * ``lam`` = *float_value* (exactly one of ``lam_over_r0``, ``fwhm`` or ``half_light_radius`` or both ``lam`` and ``r0`` is required) The wavelength in nanometers.
-    * ``r0`` = *float_value* (exactly one of ``lam_over_r0``, ``fwhm`` or ``half_light_radius`` or both ``lam`` and ``r0`` is required) The Fried parameter in meters.
-    * ``r0_500`` = *float_value* (optional, in lieu of ``r0``).  The Fried parameter in meters at a wavelength of 500 nm.  The correct ``r0`` value will be calculated using the standard relation r0 = r0_500 * (lam/500)``1.2.
+    * ``lam`` = *float_value* or *quantity_value* (exactly one of ``lam_over_r0``, ``fwhm`` or ``half_light_radius`` or both ``lam`` and ``r0`` is required) The wavelength in nanometers.
+    * ``r0`` = *float_value* or *quantity_value* (exactly one of ``lam_over_r0``, ``fwhm`` or ``half_light_radius`` or both ``lam`` and ``r0`` is required) The Fried parameter in meters.
+    * ``r0_500`` = *float_value* or *quantity_value* (optional, in lieu of ``r0``).  The Fried parameter in meters at a wavelength of 500 nm.  The correct ``r0`` value will be calculated using the standard relation r0 = r0_500 * (lam/500)``1.2.
     * ``fwhm`` = *float_value* (exactly one of ``lam_over_r0``, ``fwhm`` or ``half_light_radius`` or both ``lam`` and ``r0`` is required)
     * ``half_light_radius`` = *float_value* (exactly one of ``lam_over_r0``, ``fwhm`` or ``half_light_radius`` or both ``lam`` and ``r0`` is required)
     * ``scale_unit`` = *str_value* (default = 'arcsec') Units to be used for internal calculations when calculating lam/r0.
 
 * 'OpticalPSF'  A PSF from aberrated telescope optics.
 
     * ``lam_over_diam`` = *float_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required)
-    * ``lam`` = *float_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the wavelength in nanometers.
-    * ``diam`` = *float_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the telescope diameter in meters.
+    * ``lam`` = *float_value* or *quantity_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the wavelength in nanometers.
+    * ``diam`` = *float_value* or *quantity_value* (either ``lam_over_diam`` or both ``lam`` and ``diam`` required).  This should be the telescope diameter in meters.
     * ``defocus`` = *float_value* (default = 0) The defocus value, using the Noll convention for the normalization. (Noll index 4)
     * ``astig1`` = *float_value* (default = 0) The astigmatism in the y direction, using the Noll convention for the normalization. (Noll index 5)
     * ``astig2`` = *float_value* (default = 0) The astigmatism in the x direction, using the Noll convention for the normalization. (Noll index 6)
@@ -85,9 +85,9 @@ PSF Types
     * ``zenith_coord`` = *CelestialCoord*  (optional)  The (ra,dec) coordinate of the zenith.
     * ``HA`` = *Angle_value* (optional)  Hour angle of the observation.
     * ``latitude`` = *Angle_value* (optional)  Latitude of the observatory.
-    * ``pressure`` = *float_value* (default = 69.328)  Air pressure in kPa.
-    * ``temperature`` = *float_value* (default = 293.15)  Temperature in K.
-    * ``H2O_pressure`` = *float_value* (default = 1.067)  Water vapor pressure in kPa.
+    * ``pressure`` = *float_value* or *quantity_value* (default = 69.328)  Air pressure in kPa.
+    * ``temperature`` = *float_value* or *quantity_value* (default = 293.15)  Temperature in K.
+    * ``H2O_pressure`` = *float_value* or *quantity_value* (default = 1.067)  Water vapor pressure in kPa.
 
 Galaxy Types
 ------------
@@ -410,11 +410,11 @@ other types, including custom SED types.
 * 'FileSED' is the default type here, and you may omit the type name when using it.
 
     * ``file_name`` = *str_value* (required)  The file to read in.
-    * ``wave_type`` = *str_value* (required)  The unit of the wavelengths in the file ('nm' or 'Ang' or variations on these -- cf. `SED`)
+    * ``wave_type`` = *str_value* or *unit_value* (required)  The unit of the wavelengths in the file ('nm' or 'Ang' or variations on these -- cf. `SED`)
     * ``flux_type`` = *str_value* (required)  The type of spectral density or dimensionless normalization used in the file ('flambda', 'fnu', 'fphotons' or '1' -- cf. `SED`)
     * ``redshift`` = *float_value* (optional)  If given, shift the spectrum to the given redshift.  You can also specify the redshift as an object-level parameter if preferred.
-    * ``norm_flux_density`` = *float_value* (optional)  Set a normalization value of the flux density at a specific wavelength.  If given, ``norm_wavelength`` is required.
-    * ``norm_wavelength`` = *float_value* (optional)  The wavelength to use for the normalization flux density.
+    * ``norm_flux_density`` = *float_value* or *quantity_value* (optional)  Set a normalization value of the flux density at a specific wavelength.  If given, ``norm_wavelength`` is required.
+    * ``norm_wavelength`` = *float_value* or *quantity_value* (optional)  The wavelength to use for the normalization flux density.
     * ``norm_flux`` = *float_value* (optional)  Set a normalization value of the flux over a specific bandpass.  If given, ``norm_bandpass`` is required.
     * ``norm_bandpass`` = *Bandpass* (optional)  The bandpass to use for the normalization flux.
 

docs/config_stamp.rst

@@ -182,16 +182,16 @@ The photon operator types defined by GalSim are:
     * ``zenith_coord`` = *sky_value* (optional; see above) the celestial coordinates of the zenith.
     * ``HA`` = *angle_value* (optional; see above) the local hour angle.
     * ``latitude`` = *angle_value* (optional; see above) the latitude of the telescope.
-    * ``pressure`` = *float_value* (default = 69.328) the pressure in kPa.
-    * ``temperature`` = *float_value* (default = 293.15) the temperature in Kelvin.
-    * ``H2O_pressure`` = *float_value* (default = 1.067) the water vapor pressure in kPa.
+    * ``pressure`` = *float_value* or *quantity_value* (default = 69.328) the pressure in kPa.
+    * ``temperature`` = *float_value* or *quantity_value* (default = 293.15) the temperature in Kelvin.
+    * ``H2O_pressure`` = *float_value* or *quantity_value* (default = 1.067) the water vapor pressure in kPa.
 
 * 'FocusDepth' adjusts the positions of the photons at the surface of the sensor to account for
   the nominal focus being either above or below the sensor surface.  The depth value is typically
   negative, since the best focus is generally somewhere in the bulk of the sensor (although for
   short wavelengths it is often very close to the surface).
 
-    * ``depth`` = *float_value* (required)  The distance above the surface where the photons are
+    * ``depth`` = *float_value* (required)  The distance (in pixels) above the surface where the photons are
       nominally in focus.  A negative value means the focus in below the surface of the sensor.
 
 * 'Refraction' adjusts the incidence angles to account for refraction at the surface of the

docs/config_values.rst

@@ -13,6 +13,8 @@ have been designating using the following italic names:
 - *pos_value* corresponds to a GalSim `PositionD` instance.  See `pos_value`
 - *sky_value* corresponds to a GalSim `CelestialCoord` instance.  See `sky_value`
 - *table_value* corresponds to a GalSim `LookupTable` instance.  See `table_value`
+- *quantity_value* corresponds to an Astropy :class:`~astropy.units.Quantity` instance.  See `quantity_value`
+- *unit_value* corresponds to an Astropy :class:`~astropy.units.Unit` instance.  See `unit_value`
 
 Each of the Python types can be given as a constant value using the normal Python conventions
 for how to specify such a value.  The GalSim *angle_value* and *pos_value* also have
@@ -571,6 +573,49 @@ Options are:
 
 * A string that starts with '$' or '@'.  See `Shorthand Notation`.
 
+quantity_value
+--------------
+
+These represent `astropy.units.Quantity` values, which are a combination of a float and a unit (specifically, an `astropy.units.Unit`).
+
+Options are:
+
+* An `astropy.units.Quantity` value (e.g. '8.7*u.m', where 'u' is the `astropy.units` module)
+* A string interpretable by `astropy.units.Quantity` (e.g. '8.7 m')
+* A dict with:
+
+    * ``type`` = *str* (required)  There is only one valid option:
+
+        * 'Quantity' Specify the value and unit separately.
+
+            * ``value`` = *float_value* (required)
+            * ``unit`` = *unit_value* (required)
+
+        * 'Eval'  Evaluate a string.  See `Eval type`.
+
+* A string that starts with '$' or '@'.  See `Shorthand Notation`.
+
+unit_value
+----------
+
+These represent `astropy.units.Unit` values.
+
+Options are:
+
+* An `astropy.units.Unit` value (e.g. 'u.m', where 'u' is the `astropy.units` module)
+* A string interpretable by `astropy.units.Unit` (e.g. 'm')
+* A dict with:
+
+    * ``type`` = *str* (required)  There is only one valid option:
+
+        * 'Unit' Specify the unit.
+
+            * ``unit`` = *str_value* (required)
+
+        * 'Eval'  Evaluate a string.  See `Eval type`.
+
+* A string that starts with '$' or '@'.  See `Shorthand Notation`.
+
 
 Eval type
 ---------