Index: /trunk/doc/release.2015/ps1.analysis/analysis.tex
===================================================================
--- /trunk/doc/release.2015/ps1.analysis/analysis.tex	(revision 40076)
+++ /trunk/doc/release.2015/ps1.analysis/analysis.tex	(revision 40077)
@@ -1878,7 +1878,155 @@
 \section{Forced Photometry Modes}
 
+\note{too much detail in this section; balance relative to psphot}
+
+Traditionally, projects which use multiple exposures to increase the
+depth and sensitivity of the observations have generated something
+equivalent to the \ippstage{stack} images produced by the IPP analysis
+(c.f, CFHT Legacy survey, COSMOS, etc).  In theory, the photometry of
+the \ippstage{stack} images produces the ``best'' photometry catalog,
+with best sensitivity and the best data quality at all magnitudes.  In
+practice, these images have some significant limitations due to the
+difficulty of modelling the PSF variations.  This difficulty is
+particularly severe for the Pan-STARRS $3\pi$ survey stacks due to the
+combination of the substantial mask fraction of the individual input
+exposures, the large instrinsic image quality variations within a
+single exposure, and the wide range of image quality conditions under
+which data were obtained and used to generate the $3\pi$ PV3 stacks.
+
+For any specific stack, the point spread function at a particular
+location is the result of the combination of the point spread
+functions for those individual exposures which went into the stack at
+that point.  Because of the high mask fraction, the exposures which
+contributed to pixels at one location may be somewhat different just a
+few tens of pixels away.  In the end, the \ippstage{stack} images have
+a effective point spread function which is not just variable, but
+changing significantly on small scales in a highly textured fashion.
+
+Any measurement which relies on a good knowledge of the PSF at the
+location of an object either needs to determine the PSF variations
+present in the \ippstage{stack} image, or the measurement will be
+somewhat degraded.  The highly textured PSF variations make this a
+very challenging problem: not only would such a PSF model require an
+unusually fine-grained PSF model, there would likely not be enough PSF
+stars in a given \ippstage{stack} image to determine the model at the
+resolution required.  The IPP photometry analysis code uses a PSF
+model with 2D variations using a grid of at most $6\times 6$ samples
+per skycell, a number reasonably well-matched to the density of stars
+at most moderate Galactic latitudes.  This scale is far too large to
+track the fine-grained changes apparent in the stack images.
+
+Thus PSF photometry as well as convolved galaxy models in the stack
+are degraded by the PSF variations.  Aperture-like measurements are in
+general not as affected by the PSF variations, as long as the aperture
+in question is large compared to the FWHM of the PSF.
+
+%% The IPP team initially explored the option of convolving each input
+%% warp to a single target PSF chosen to match the worst of the input
+%% images for a given stack.  
+
+The PV3 $3\pi$ analysis solves this problem by using the sources
+detected in the stack images and performing forced photometry on the
+individual warp images used to generate the stack.  This
+\ippstage{fullforce} analysis is performed on all warps for a single
+skycell and filter as a single unit, as this matches the arrangement
+of the input source catalog from the \ippstage{skycal} stage.  When
+processing is queued for this stage, an entry is added to the
+\ippdbtable{fullForceRun} primary database table linking to the
+specific \ippdbcolumn{skycal\_id} entry that will be used as the
+catalog for the photometry.  The \ippdbcolumn{warp\_id} values for the
+input \ippstage{warp} stage images that contributed to the
+\ippstage{stack} associated with that \ippdbcolumn{skycal\_id} are
+then added to the \ippdbtable{fullForceInput} table, linked to the
+primary table by the \ippdbcolumn{ff\_id} identifier.  The individual
+jobs for each warp are then run, which passes the \ippstage{warp}
+stage image products along with the \ippstage{skycal} catalog to the
+\ippprog{psphotFullForce} program.
+
+In this program, the positions of sources are loaded from the input
+catalog.  PSF stars are pre-identified \note{how?} and a PSF model
+generated for each \ippstage{warp} image based on those stars, using
+the same stars for all warps to the extent possible (PSF stars which
+are excessively masked on a particular image are not used to model the
+PSF).  \note{this doesn't seem correct, as each warp is run
+  independently. EAM: not true!}  The PSF model is fitted to all of the known source
+positions in the warp images.  Aperture magnitudes, Kron magnitudes,
+and moments are also measured at this stage for each warp.  Note that
+the flux measurement for a faint, but significant, source from the
+stack image may be at a low significance (less than the $5\sigma$
+criterion used when the photometry is not run in this forced mode) in
+any individual warp image; the flux may even be negative for specific
+warps.  When combined together, these low-significance measurements
+will result in a signficant measurement as the signal-to-noise
+increases by the square root of the number of measurements.
+
+Upon completion of the forced photometry (for point sources as well as
+galaxies, discussed below), an entry is added to the
+\ippdbtable{fullForceResult} table with the processing statistics for
+that combination of \ippdbcolumn{ff\_id} and \ippdbcolumn{warp\_id}.
+Once all of the entries in the \ippdbtable{fullForceInput} table have
+finished, a summary operation is run to generate an appropriate
+average value for each measurement, by combining the measurements from
+each of the inputs.  The output catalogs listed in the
+\ippdbtable{fullForceResult} table are passed to the
+\ippprog{psphotFullForceSummary} to do this averaging.  \note{describe
+  what is done} When this completes, an entry is added to the
+\ippdbtable{fullForceSummary}, and the \ippdbtable{fullForceRun} entry
+is marked as completed.
+
 \subsection{Forced Photometry : PSFs}
 
 \subsection{Forced Photometry : galaxies}
+
+The convolved galaxy models are also re-measured on the
+\ippstage{warp} images by the \ippstage{fullforce} stage analysis.  In
+this analysis, the galaxy models determined by the
+\ippstage{staticsky} photometry analysis are used to seed the analysis
+in the individual \ippstage{warp} images.  The purpose of this
+analysis is the same as the \ippstage{fullforce} PSF photometry: the
+PSF of the \ippstage{stack} image is poorly determined due to the
+masking and PSF variations in the inputs.  Without a good PSF model,
+the PSF-convolved galaxy models are of limited accuracy.
+
+In the \ippstage{fullforce} galaxy model analysis, we assume that the
+galaxy position and position angle, along with the Sersic index if
+appropriate, have been sufficiently well determined in the
+\ippstage{staticsky} analysis.  In this case, the goal is to determine
+the best values for the major and minor axis of the elliptical contour
+and at the same time the best normalization corresponding to the best
+elliptical shape, and thus the best galaxy magnitude value.
+
+For each \ippstage{warp} image, the \ippstage{staticsky} value for the
+major and minor axis are used as the center of a $7\times{} 7$ grid
+search of the major and minor axis parameter values.  The grid spacing
+is defined as a function of the signal-to-noise of the galaxy in the
+stack image so that bright galaxies are measured with a much finer
+grid spacing that faint galaxies \note{need to quantify this}.  For
+each grid point, the major and minor axis values at that point are
+determined for the model.  The model is then generated and convolved
+with the PSF model for the \ippstage{warp} image at that point.  The
+resulting model is then compared to the \ippstage{warp} pixel data
+values and the best fit normalization value is defined.  The
+normalization and the $\chi^2$ value for each grid point is recorded.
+
+For a given galaxy, the result is a collection of $\chi^2$ values for
+each of the grid points spanning all \ippstage{warp} images.  A single
+$\chi^2$ grid can then be made by combining each grid point across the
+inputs.  The combined $\chi^2$ for a single grid point is simply the
+sum of all $\chi^2$ values at that point.  If, for a single \ippstage{warp}
+image, the galaxy model is excessively masked, then that image will be
+dropped for all grid points for that galaxy.  The reduced $\chi^2$
+values can be determined by tracking the total number of pixels
+used across all inputs to generate the combined $\chi^2$ values.  From
+the combined grid of $\chi^2$ values, the point in the grid with the
+minimum $\chi^2$ is found.  Quadratic interpolation is used to
+determine the major, minor axis values for the interpolated minimum
+$\chi^2$ value.  The errors on these two parameters is then found by
+determining the contour at which the \note{reduced?} $\chi^2$
+increases by 1.
+
+Thus the \ippstage{fullforce} galaxy analysis uses the PSF information
+from each \ippstage{warp} to determine a best set of convovled galaxy
+models for each object in the \ippstage{skycal} catalog.
+\note{discuss the subset of galaxy models and objects}.
 
 \section{Difference Image Photometry}
@@ -2013,2 +2161,3 @@
 * put engineering docs (psLib, psModules) on public website 
 
+