New Spectrograph

Here are notes on how to add a new spectrograph from scratch or to add a new mode. To do so, you should install PypeIt following the development path; see Installation and Development Procedures and Guidelines.

Entirely New

PypeIt defines instrument-specific behavior/parameters using a python class hierarchy; see Spectrograph for relevant documentation and the abstractions that will need to be defined for new spectrographs.

PypeIt reductions follow three different data-reduction paths: (1) single, long-slit, or multi-slit reductions (e.g., Keck DEIMOS), (2) echelle reductions for spectrographs that observe multiple, cross-dispersed orders (e.g., Keck NIRES), and (3) slit-based integral-field spectrographs (e.g., KCWI). When introducing a new spectrograph, it is helpful to start with the class for a supported spectrograph and alter it for the new spectrographs. All spectrograph classes are located in pypeit/spectrographs/, starting from the top-level of the repository. See Spectrographs for a table with the data-reduction (pipeline) path used for each spectrograph.

The class-hierarchy is used by PypeIt to specify certain instrument modes, like spectrograph arm, that inherit from a common base class. For example, KeckLRISSpectrograph implements many of the methods that are common to both arms (red and blue) of the spectrograph. These include methods used to read raw files, used to define header cards with required MetaData, and used to determine the type of frame (arc, dome, bias, etc) based on that MetaData. The Spectrograph instance for each LRIS arm inherits these methods common to them both by subclassing from KeckLRISSpectrograph. If your spectrograph has a similar set of modes, see pypeit/spectrographs/keck_lris.py for a demonstration.

Note

The class-hierarchy is not meant to capture different instrument configurations (gratings, filters, etc).
The name attribute of a spectrograph should be None if the class is only a base class.

Having said all of that, the basic steps one needs to follow to introduce a new spectrograph are as follows:

Build a new file called telescope_spectrograph.py file and put it in the pypeit/spectrographs/ directory.
Add the new module to the list imported by pypeit/spectrographs/__init__.py.
Generate a new Telescope object in (if new) pypeit/telescopes.py.
Add telescope name to valid_telescopes in pypeit/par/pypeitpar.py.
Set the algorithmic path: the class attribute, pypeline, must be 'MultiSlit', 'Echelle', or 'IFU'.
Set the default parameters PypeIt uses during the reduction; see User-level Parameters, and, e.g., default_pypeit_par().
Include a default bad-pixel mask; see, e.g., bpm().
Define the link between header keywords read from the raw fits files and the PypeIt-specific MetaData keys used throughout the code; see e.g., init_meta() and compound_meta().
Define the set of PypeIt-specific MetaData keys that are used to establish a unique instrument configuration; see, e.g., configuration_keys().
Define the method used to determine the frame type of a given file based on its MetaData; see, e.g., check_frame_type().
Set the MetaData for the instrument detector(s); see, e.g., get_detector_par().
Define the method used to read the raw data. See get_rawimage() and compare to, e.g., get_rawimage().
For echelle spectrographs, there are numerous methods required that provide details for the (currently fixed) format of the orders. See, e.g., VLTXShooterNIRSpectrograph.
You may need to generate wavelength solutions for your setups. You can use the pypeit_identify utility, and add this to the PypeIt archive by following the steps outlined in the Constructing a New Wavelength Template documentation. See Wavelength Calibration.

See this example PR for the SOAR/Goodman spectrograph.

Near-IR

If this is a near-IR instrument, you may wish to turn off calibration steps. See GeminiGNIRSSpectrograph for an example.

Tests

For a spectrograph to be supported going forth, we require a minimum set of tests. These are:

A full run of the pipeline for each grating/mode of the spectrograph in the PypeIt Development Suite.

A simple unit test that check an image can be loaded. This needs to be added to the PypeIt Development Suite; see here.

Docs

We request that the following docs be updated to advertise the new spectrograph:

Update the top-level CHANGES.rst
If specific advice is important/useful, add an instrument specific doc to the doc/spectrographs directory and link the doc in the doc/specrographs/spectrographs.rst doc.