Merge pull request #81 from GalSim-developers/u/rmandelb/dox

Updates in preparation for making repo public

README.md

@@ -2,16 +2,22 @@
 
 Helper functions to generate simulations of Euclid-like images using GalSim.
 
-This package contains information about the Euclid space telescope and survey that is needed to
+This repository contains information about the Euclid space telescope and survey that is needed to
 produce simulations using [GalSim](https://github.com/GalSim-developers/GalSim).  Some of the
 information provided is approximate, aimed towards fast simulations rather than full accuracy in
 representation of Euclid images.  Places where the information is only approximate are flagged and
-fully described in the docstring, and we particularly highlight that the PSF is only approximate;
+described in the docstring, and we particularly highlight that the PSF is only approximate;
 for details, see the docstring of the `getPSF()` method.  This library should enable generation of
 Euclid-like images of sufficient fidelity for preliminary exploration of object detection,
-photometry, deblending, and joint analysis with ground-based observatories.  However, for
+photometry, deblending, and joint analysis with ground-based observatories.  For
 applications requiring high precision such as weak lensing, the higher fidelity simulations
-available within the Euclid consortium should be used.
+available within the Euclid Consortium should be used.
+
+The repository includes two distinct packages:
+* `euclidlike` has basic observatory, instrumentation, and survey information for Euclid.
+This package can be used on its own along with GalSim to produce Euclid-like simulations.
+* `euclidlike_imsim` has configuration scripts to produce large-scale Euclid-like simulation runs
+based on the information in `euclidlike`.  It is based heavily on [`roman_imsim`](https://github.com/matroxel/roman_imsim).
 
 ## References
 
@@ -32,7 +38,7 @@ astropy>=2.0,
 ```
 
 NOTE:
-At the moment `GalSim` has to be installed manually to have acces to chromatic PSF interpollation that we need (see [here](https://github.com/GalSim-developers/GalSim/pull/1296)).  
+At the moment `GalSim` has to be installed manually to have access to chromatic PSF interpolation that we need (see [here](https://github.com/GalSim-developers/GalSim/pull/1296)).  
 To install GalSim:
 ```
 git clone [email protected]:GalSim-developers/GalSim.git
@@ -41,19 +47,19 @@ git checkout 1294_from_images
 pip install .
 ```
 
-The source code has not been published to pypi. To install from source code:
+The source code for GalSim-Euclid-Like has not been published to pypi. To install from source code:
 ```
 git clone [email protected]:GalSim-developers/GalSim-Euclid-Like.git
 ```
-and install by 
+and install by running
 ```
 conda create -n euclidlike python=3.10
 cd GalSim-Euclid-Like
 conda activate euclidlike
 pip install -e .
 ```
 
-To make sure installation is successful
+To make sure the installation is successful, do the following:
 ```
 $ python
 >>> import euclidlike

euclidlike/backgrounds.py

@@ -87,7 +87,7 @@ def getSkyLevel(bandpass, world_pos=None, exptime=None, epoch=2025, date=None):
 
 def getZodiBackground(ecl_lat, ecl_dlon, lambda_min, lambda_max, Tlambda, T):
     """
-    This helper routine comes from Chris Hirata's Exposure Time Calculator and enables the
+    This helper routine is used with permission from Chris Hirata's Exposure Time Calculator and enables the
     calculation of the zodiacal light in photons/m^2/arcsec^2/sec. The ETC may be found here:
 
     http://www.tapir.caltech.edu/~chirata/web/software/space-etc/

euclidlike/euclidlike_psf.py

@@ -14,7 +14,8 @@
 @file euclidlike_psf.py
 
 Part of the Euclid-like simulation module. This file includes routines needed
-to define a Euclid-like PSF.
+to define a Euclid-like PSF.  All PSF creation routines are quite approximate, and their limitations
+are specified in the routine's docstring.
 """
 
 meta_dir = files("euclidlike.data")
@@ -62,20 +63,38 @@ def __get_quadrant_psf(ccd, bandpass, psf_dir):
 
 _get_quadrant_psf = LRU_Cache(__get_quadrant_psf)
 
-
 def getPSF(
         ccd, bandpass,
         ccd_pos=None, wcs=None,
         wavelength=None, gsparams=None,
         logger=None, psf_dir = None
 ):
-    """Get a single PSF for Euclid like simulation.
-
-    For applications that require very high accuracy in the modeling of the
-    PSF, with very limited aliasing, you may want to lower the
-    folding_threshold in the gsparams.  Otherwise very bright stars will show
-    some reflections in the spider pattern and possibly some boxiness at the
-    outskirts of the PSF.  Using ``gsparams =
+    """Get a single PSF for a Euclid-like simulation.
+
+    These PSFs are based on precomputed, oversampled (by 3x) PSF images on a grid in wavelength and
+    focal plane position.  These images were provided by Lance Miller and Chris Duncan.  They are
+    meant to provide an approximately correct description of the PSF size and shape without the
+    level of accuracy needed for precision tests of weak lensing shear inference.  The precomputed
+    images are combined in a way that accounts for the bandpass and (if provided) SED.  The effects
+    of detector linear charge diffusion, a simplified model for guiding errors, and wavefront error
+    due to measured surface figure errors are incorporated in the precomputed images.  The telescope
+    focus is set to a value from September 2023, and is therefore within a realistic range but does
+    not reflect variation over time for any particular observation.
+
+    Several important effects were omitted in these images, including the following:
+    * the effect of the dichroic;
+    * polarization aberrations; 
+    * non-linear detector effects such as charge-transfer inefficiency, the brighter-fatter effect,
+      and readout nonlinearity;
+    * the effects of decontamination by ice.
+
+    Functionally the lack of non-linear detector effects means the images produced should be thought
+    of as post-instrument signature removal (assuming the ISR process is carried out perfectly).
+
+    For applications that require very high accuracy in the modeling of the PSF, with very limited
+    aliasing, you may want to lower the `folding_threshold` in the gsparams.  Otherwise very bright
+    stars will show some reflections in the spider pattern and possibly some boxiness at the
+    outskirts of the PSF due to the size of the precomputed images.  Using ``gsparams =
     GSParams(folding_threshold=1.e-4)`` generally provides good results.
     
     Note that before using, the oversampled PSF images used to create the
@@ -100,9 +119,9 @@ def getPSF(
     bandpass (str): Single string specifying the bandpass to use when
         defining the pupil plane configuration and/or interpolation of
         chromatic PSFs.
-    ccd_pos:  Single galsim.PositionD indicating the position within the ccd
+    ccd_pos:  Single galsim.PositionD indicating the position within the CCD
         for which the PSF should be created. If None, the exact center of the
-        ccd is chosen. [default: None]
+        CCD is chosen. [default: None]
     wcs:  The WCS to use to project the PSF into world coordinates. [default:
         galsim.PixelScale(euclid_like.roman.pixel_scale)]
     wavelength (float):  An option to get an achromatic PSF for a single
@@ -178,19 +197,19 @@ def getBrightPSF(
     gsparams=None,
     logger=None,
 ):
-    """Get a fake optical PSF for really bright objects in Euclidlike simulations.
-    Depending on the inputs, returns a chromatic or achromatic PSF using the
+    """Get a fake optical PSF for very bright objects in Euclid-like simulations.
+    Depending on the inputs, this routine returns a chromatic or achromatic PSF using the
     Euclid telescope diameter and Euclid-like aperture.
     
     Args:
-    ccd (int):  Single value specifying the ccd for which the PSF should be
+    ccd (int):  Single value specifying the CCD for which the PSF should be
         loaded.
     bandpass (str): Single string specifying the bandpass to use when
         defining the pupil plane configuration and/or interpolation of
         chromatic PSFs.
-    ccd_pos:  Single galsim.PositionD indicating the position within the ccd
+    ccd_pos:  Single galsim.PositionD indicating the position within the CCD
         for which the PSF should be created. If None, the exact center of the
-        ccd is chosen. [default: None]
+        CCD is chosen. [default: None]
     wcs:  The WCS to use to project the PSF into world coordinates. [default:
         galsim.PixelScale(euclidlike.pixel_scale)]
     n_waves (int): Number of wavelengths to use for setting up interpolation of the
@@ -248,7 +267,6 @@ def getBrightPSF(
 
     return psf
 
-
 def _get_single_psf_obj(ccd, bandpass, ccd_pos, wavelength, psf_dir, gsparams, logger):
     """
     Routine for making a single PSF.  This gets called by `getPSF` after it

euclidlike/euclidlike_wcs.py

@@ -91,10 +91,11 @@ def getWCS(world_pos, PA=None, date=None, CCDs=None, PA_is_FPA=False, SAA=None):
     The Euclid CCDs are labeled 0-35, so these numbers are used as the keys in
     the dict.  Alternatively the user can request a subset of the CCDs using
     the ``CCDs`` option.  The basic instrument parameters used to create the
-    WCS correspond to those in ERO data and are likely to change in the future.
+    WCS correspond to those in Early Release Observations (ERO) data and are 
+    likely to change in the future.
 
     The user must specify a position for observation, at which the center of
-    the focal plane array will point. This must be supplied as aCelestialCoord
+    the focal plane array will point. This must be supplied as a CelestialCoord
     ``world_pos``.  In general, only certain positions are observable on
     certain dates, and for a given position there is an optimal position angle
     for the observatory (with the solar panels pointed as directly towards the
@@ -103,11 +104,6 @@ def getWCS(world_pos, PA=None, date=None, CCDs=None, PA_is_FPA=False, SAA=None):
     for the focal plane (using ``PA_is_FPA`` to indicate this).  But otherwise,
     the routine will simply choose the optimal position angle for a given date.
 
-    TODO: update this part
-    To fully understand all possible inputs and outputs to this routine, users
-    may wish to consult the diagram on the GalSim wiki,
-    https://github.com/GalSim-developers/GalSim/wiki/GalSim-Roman-module-diagrams
-
     Parameters:
         world_pos:      A `galsim.CelestialCoord` indicating the position to
                         observe at the center of the focal plane array (FPA).
@@ -229,11 +225,6 @@ def convertCenter(world_pos, CCD, PA=None, date=None, SAA=None, PA_is_FPA=False,
     its initial result based on empirical tests.  The ``tol`` kwarg can be used to adjust how
     careful it will be, but it always does at least one iteration.
 
-    TODO: update thiis part
-    To fully understand all possible inputs and outputs to this routine, users may wish to consult
-    the diagram on the GalSim wiki,
-    https://github.com/GalSim-developers/GalSim/wiki/GalSim-Roman-module-diagrams
-
     Parameters:
         world_pos:  A galsim.CelestialCoord indicating the position to observe at the center of the
                     given CCD.  Note that if the given position is not observable on