MUSE-PSFR - PSF reconstruction for MUSE WFM-AO

Warning

This documentation is for the version currently under development.

https://github.com/musevlt/muse-psfr/workflows/Run%20unit%20tests/badge.svg https://codecov.io/gh/musevlt/muse-psfr/branch/master/graph/badge.svg

The MUSE-PSFR code allows to reconstruct a PSF for the MUSE WFM-AO mode, using telemetry data from SPARTA.

Citation

The method is presented in the following publication: Fusco et al., A&A, 2020

Installation

MUSE-PSFR requires the following packages:

  • Numpy

  • Astropy

  • SciPy

  • MPDAF

  • Joblib

  • Matplotlib (optional, for the PSF plot)

  • Colorama (optional, for colored output)

The last stable release of MUSE-PSFR can be installed simply with pip:

pip install muse-psfr

Or to install with optional dependencies:

pip install muse-psfr[all]

Or into the user path with:

pip install --user muse-psfr

How it works

The algorithm is described in the article ([Fusco et al. in prep.]).

Inputs

The PSF reconstruction algorithm needs 3 values provided by SPARTA: the seeing, the Ground Layer fraction (GL), and the outer-scale (L0). These values can be provided directly as command-line arguments (see below), but the typical use is to provide a raw MUSE file.

Since the GLAO commissioning, the MUSE raw files contain a FITS table (SPARTA_ATM_DATA) containing the atmospheric turbulence profile estimated by SPARTA. This table contains the values for each laser, with one row every two minutes.

Number of reconstructed wavelengths

To reduce computation time, the muse-psfr command reconstructs the PSF at three wavelengths: 500, 700, and 900 nm. But it is possible to reconstruct the PSF at any wavelength, with the compute_psf_from_sparta function. This function reconstructs by default for 35 wavelengths between 490nm and 930nm (which can specified with the lmin, lmax, and nl parameters).

Number of reconstructed direction

Since the spatial variation is negligible over the MUSE field of view, the reconstruction is done by default only at the center of field. This can be changed in compute_psf_from_sparta with the npsflin parameter.

Usage

Command Line Interface

MUSE-PSFR can be used from the command line, either with a set of seeing, GL, and L0 values:

$ muse-psfr --no-color --values 1,0.7,25
[INFO] MUSE-PSFR version 1.1.dev18+g0c56a3d
[INFO] Computing PSF Reconstruction from Sparta data
[INFO] Processing SPARTA table with 1 values, njobs=1 ...
[INFO] Compute PSF with seeing=1.00 GL=0.70 L0=25.00
[INFO] --------------------------------------------------------------------
[INFO] Sparta Seeing: 1.00 arcsec GL: 0.70 L0:25.00 m
[INFO] LBDA 5000 7000 9000
[INFO] FWHM 0.85 0.73 0.62
[INFO] BETA 2.73 2.55 2.23
[INFO] --------------------------------------------------------------------
[INFO] Results saved to muse_psfr.log

Or with a MUSE raw FITS file which contains a SPARTA_ATM_DATA extension:

$ muse-psfr raw/MUSE.2018-08-13T07:14:11.128.fits.fz
MUSE-PSFR version 0.31
OB MXDF-01-00-A 2018-08-13T07:39:21.835 Airmass 1.49-1.35
Computing PSF Reconstruction from Sparta data
Processing SPARTA table with 13 values, njobs=-1 ...
4/13 : Using only 3 values out of 4 after outliers rejection
4/13 : seeing=0.57 GL=0.75 L0=18.32
Using three lasers mode
1/13 : Using only 3 values out of 4 after outliers rejection
1/13 : seeing=0.71 GL=0.68 L0=13.60
Using three lasers mode
6/13 : Using only 3 values out of 4 after outliers rejection
6/13 : seeing=0.60 GL=0.75 L0=16.47
Using three lasers mode
....

OB MXDF-01-00-A 2018-08-13T07:39:21.835 Airmass 1.49-1.35
--------------------------------------------------------------------
LBDA  5000 7000 9000
FWHM  0.57 0.46 0.35
BETA  2.36 1.91 1.64
--------------------------------------------------------------------

Results saved to muse-psfr.log

More information use of the command line interface can be found with the command:

$ muse-psfr --help
usage: muse-psfr [-h] [--values VALUES] [--logfile LOGFILE] [-o OUTFILE]
                 [--njobs NJOBS] [--verbose] [--no-color] [--plot] [--version]
                 [raw]

MUSE-PSFR version 1.1.dev18+g0c56a3d

positional arguments:
  raw                   observation raw file name

optional arguments:
  -h, --help            show this help message and exit
  --values VALUES       values of seeing, GL, L0, to use instead of the raw
                        file, comma-separated
  --logfile LOGFILE     name of log file
  -o OUTFILE, --outfile OUTFILE
                        name of a FITS file in which the results are saved:
                        table with individual and mean Moffat fits, and mean
                        reconstructed PSF
  --njobs NJOBS         number of parallel jobs (by default use all CPUs)
  --verbose, -v         verbose flag
  --no-color            no color in output
  --plot                plot reconstructed psf
  --version             show program's version number and exit

By default it saves the computed values in a log file (muse-psfr.log). It is also possible to save a FITS file with the fit results for all wavelengths and all SPARTA rows with the --outfile option.

Python interface

The main entry point for the Python interface is the compute_psf_from_sparta function. This function takes a file with a SPARTA table,

>>> from muse_psfr import compute_psf_from_sparta, create_sparta_table
>>> tbl = create_sparta_table(seeing=1, L0=25, GL=0.7)
>>> tbl.data
FITS_rec([(25, 1, 0.7, 25, 1, 0.7, 25, 1, 0.7, 25, 1, 0.7)],
         dtype=(numpy.record, [('LGS1_L0', '<i8'), ('LGS1_SEEING', '<i8'), ('LGS1_TUR_GND', '<f8'), ('LGS2_L0', '<i8'), ('LGS2_SEEING', '<i8'), ('LGS2_TUR_GND', '<f8'), ('LGS3_L0', '<i8'), ('LGS3_SEEING', '<i8'), ('LGS3_TUR_GND', '<f8'), ('LGS4_L0', '<i8'), ('LGS4_SEEING', '<i8'), ('LGS4_TUR_GND', '<f8')]))
>>> from astropy.io import fits
>>> hdul = fits.HDUList([tbl])
>>> out = compute_psf_from_sparta(hdul, lmin=500, lmax=900, nl=3, plot=True)
Processing SPARTA table with 1 values, njobs=1 ...
1/1 : seeing=1.00 GL=0.70 L0=25.00

(Source code, png, hires.png, pdf)

_images/index-1.png

Changelog

1.0 (05/02/2020)

  • Documentation and other minor updates.

  • Add verbose parameter to compute_psf and compute_psf_from_sparta.

  • Remove deprecated function reconstruct_psf.

1.0.rc2 (09/07/2019)

  • Add --version for the script.

  • Use logging for all terminal outputs.

1.0.rc1 (31/01/2019)

  • Skip SPARTA row when L0<10 or L0>30.

  • Merge individual Moffat fits in one table.

  • Add command-line options (--plot, --outfile).

  • Add documentation.

  • Rename package to muse-psfr.

0.3

  • Improve MUSE PSF model.

  • Better limits to reject aberrant values from SPARTA.

0.2

  • Replace empirical seeing correction with PSF models.

  • Better handling of files with invalid values

0.11

  • Add 3 lasers mode.

0.1

First release.

API

muse_psfr.compute_psf_from_sparta(filename, extname='SPARTA_ATM_DATA', npsflin=1, lmin=490, lmax=930, nl=35, lbda=None, h=(100, 10000), n_jobs=- 1, plot=False, mean_of_lgs=True, verbose=True)[source]

Reconstruct a PSF from SPARTA data.

Parameters
  • filename (str or astropy.io.fits.HDUList) – FITS file containing a SPARTA table.

  • extname (str) – Name of the SPARTA extension (defaults to SPARTA_ATM_DATA).

  • npsflin (int) – Number of points where the PSF is reconstructed (on each axis).

  • lmin (float) – Wavelength range (nm).

  • lmax (float) – Wavelength range (nm).

  • nl (int) – Number of wavelength planes to reconstruct.

  • lbda (array) – Array of wavelength values (nm). If not given it is computed from lmin, lmax and nl.

  • h (tuple of float) – Altitude of the ground and high layers (m).

  • n_jobs (int) – Number of parallel processes to process the rows of the SPARTA table.

  • plot (bool) – If True, plots the configuration if the AO system (positions of the LGS and the directions of reconstruction).

  • mean_of_lgs (bool) – If True (default), compute the mean seeing, GL and L0 over the 4 lasers. Otherwise a PSF is reconstructed for each laser.

  • verbose (bool) – If True (default), print more information.

muse_psfr.compute_psf(lbda, seeing, GL, L0, npsflin=1, h=(100, 10000), three_lgs_mode=False, verbose=True)[source]

Reconstruct a PSF from a set of seeing, GL, and L0 values.

Parameters
  • lbda (array) – Array of wavelength for which the PSF is computed (nm).

  • npsflin (int) – Number of points where the PSF is reconstructed (on each axis).

  • h (tuple of float) – Altitude of the ground and high layers (m).

  • three_lgs_mode (bool) – If True, use only 3 LGS.

  • verbose (bool) – If True (default) log informations

muse_psfr.create_sparta_table(nlines=1, seeing=1, L0=25, GL=0.7, bad_l0=False, outfile=None)[source]

Helper function to create a SPARTA table with the given seeing, L0, and GL values.

muse_psfr.fit_psf_with_polynom(lbda, fwhm, beta, deg=(5, 5), output=0)[source]

Fit MUSE PSF fwhm and beta with polynoms.

Parameters
  • lbda (array of float) – Wavelength in nm.

  • fwhm (array of float) – Moffat FWHM in arcsec.

  • beta (array of float) – Moffat beta parameter.

  • deg (tuple) – (fwhm_deg, beta_deg), polynomial degre in fwhm and beta.

  • output (int) – If set to 1, the fitted values are returned.

Returns

dictionary with fwhm_poly (array), beta_poly (array) if output=0 and lbda_fit, fwhm_fit, beta_fit if output=1

Return type

dict