Fiber Acceptance Fraction Calculations ====================================== Overview -------- Fiber acceptance refers to the fraction of photons incident on the focal plane from an astrophysical source that enter the fiber. The fiber acceptance fraction is also referred to as the "fiberloss", and depends on: * The source profile on the sky, modeled as a sum of point-like, disk (Sersic n=1), and bulge (Sersic n=4) components. * The atmospheric PSF, modeled with a Moffat function with an adjustable beta value, and assuming a Kolmogorov exponent (-1/5) for the wavelength dependence of the astmospheric seeing FWHM. * The instrumental PSF which has both blur and offset components and generally depends on position in the focal plane and wavelength. * The mapping of sky coordinates to physical coordinates at the fiber entrance face, which are expressed via radial and azimuthal plate scales, and generally transform a round fiber into an elliptical view of the sky. Further details specific to DESI are provided in `DESI-doc-2720 `_. The jupyter notebook in ``docs/nb/FiberlossExamples.ipynb`` was used to create the plots for this document and provide code examples for fiberloss calculations. Configuration ------------- The fiberloss calculation combines many different aspects of the simulation, so its configuration data is spread among different components: ``atmosphere``, ``instrument``, ``source`` and ``observation``. Details of how fiberloss should be calculated are specified in the ``instrument.fiberloss`` configuration. There are currently two supported methods selected by the value of ``instrument.fiberloss.method``: * The ``table`` method reads fiberloss arrays for different object types (QSO, LRG, etc) from files during initialization. The ``source.type`` parameter is then used to select the appropriate array. This mode is fast but inflexible. Configuration parameters related to the source profile, atmospheric seeing, the instrumental PSF, and plate scales are not used to calculate the fiberloss with this method. * The ``galsim`` method calculates fiberloss arrays on the fly using the `galsim `_ external package to build and convolve models of the source and the atmospheric and instrumental PSFs. Models are built in physical sky coordinates, using the plate scales to transform the on-sky source and atmospheric models. This mode is the most flexible and slowest, and uses all of the relevant configuration parameters. * The ``fastsim`` method is based on an interpolation of fiber acceptance values pre-computed with ``galsim`` using the script ``fitgalsim``, which assumes a fixed axis ratio of 0.7 (for extended objects), a fixed Moffat PSF model with beta=3.5 (but variable FWHM) for the atmosphere, and a fixed fiber diameter of 107um. The interpolation parameters/axis are source profile (point source, exponential disk, De Vaucouleurs bulge), sigma (atmosphere+telescope blur, in um on focal surface), fiber offset from source (in um on focal surface), and half light radius (in arcsec) from extended source. This interpolation is performed with the class ``fastfiberacceptance.FastFiberAcceptance``. The accuracy is about 1 percent when the assumptions above are valid. Refer to the comments in the sample configuration files for more information about the available parameters. GalSim Dependency ----------------- The GalSim package is only required when the ``galsim`` method is selected. As of GalSim version 2.0, this package can be easily install using either conda or pip. Fiberloss arrays calculated with GalSim can be saved for later table-based simulations. For example, first run the :ref:`quickspecsim` script to use GalSim to calculate and save the fiberloss for a specific configuration of the source, atmosphere, etc, with:: quickspecsim -c desi-elg --save-fiberloss desi-elg-fiberloss Next, update your configuration file to select the ``table`` method and read the new tabulated fiberloss array:: instrument: ... fiberloss: method: table format: ascii.ecsv paths: elg: .../desi-elg-fiberloss.ecsv API --- Refer to the :mod:`specsim.fiberloss` documentation for details on the API for performing fiberloss calculations. The source code of the :ref:`quickfiberloss` script provides a simple example of calculating fiberloss arrays with GalSim, starting from arrays of galaxy sizes and shapes. GalSim Accuracy and Speed ------------------------- The accuracy and speed of the GalSim calculations are primarily determined by the ``instrument.fiberloss.num_wlen`` and ``instrument.fiberloss.num_pixels`` configuration parameters. The first parameter determines the number of wavelengths at which the calculations are performed, and the time scales linearly with its value. Lower values are faster but require more interpolation in wavelength, leading to larger errors. The second parameter determines the resolution of the pixel grid used to cover a fiber in the calculations. The timing is non-linear in this parameter, with the default value of 16 giving a local optimum speed, with relative errors in fiberloss at the 1e-3 level. The :ref:`quickfiberloss` command-line script is primarily intended for benchmarking different numerical parameters.