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.

Adding an entirely new spectrograph

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, to define header cards with required MetaData, and 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 name of the new module to the __all__ list defined in pypeit/spectrographs/__init__.py. E.g.
```
__all__ = [
    ...
    'keck_lris',
    ...
]
```
Please maintain the alphabetical ordering of the modules listed.
Generate a new Telescope object in pypeit/telescopes.py, as needed.
Add the telescope name to the list of valid_telescopes in pypeit/par/pypeitpar.py.
Set the algorithmic path: the class attribute, pypeline, must be 'MultiSlit', 'Echelle', or 'SlicerIFU'.
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 fixed-format echelle spectrographs, there are numerous methods that provide details for the expected 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 designated as being “supported” by PypeIt, 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 checks that 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:

Include a comment noting the addition of the relevant spectrograph module in the most recent release doc in doc/releases. There is typically a section for “Instrument-specific” changes.
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.
It will be helpful to users to have a tutorial to follow when using PypeIt to reduce data from the newly supported spectrograph. Please either add a new tutorial (see, e.g., doc/tutorials/lris_howto.rst) or add a comment in doc/tutorials/tutorials.rst pointing users to a spectrograph tutorial that is very similar (or identical) to the procedures that should be used for the new spectrograph.