psls 1.7

PLATO Stellar Light-curve Simulator (SLS): Simulate stochastically-excited oscillations and associated stellar and instrumental background noises

================================================
PSLS: the PLATO Solar-like Light-curve Simulator
================================================

PSLS simulates solar-like oscillators representative for PLATO observations. The simulator includes planetary transits, stochastically-excited oscillations, granulation and activity background components, as well as instrumental systematic errors and random noises representative for PLATO. The program also manages the existence of a time shift between groups of cameras. Planetary transits are included following Mandel & Agol (2002) equations (see http://adsabs.harvard.edu/abs/2002ApJ...580L.171M) and using the Python implementation by Ian Crossfield (http://www.astro.ucla.edu/~ianc/) at UCLA.

For more details see http://psls.lesia.obspm.fr and also Samadi et al (2019, A&A, 624, 117).
 	
The package provides the code and various tables (files) storing the parameters describing the systematic errors representative for the PLATO cameras:

* PLATO_systematics_EOL_V2.npy: End Of Life (EOL) systematic errors (aperture mask, P5 sample)
* PLATO_systematics_BOL_V2.npy: Begining Of Life (BOL) systematic errors (aperture mask, P5 sample)
* PLATO_systematics_BOL/EOL_FixedMask_V2.npy: fixed aperture masks (P5 sample)
* PLATO_systematics_BOL/EOL_P1_V2.npy: systematic errors representative for the P1 sample (based on the PSF fitting method)

The systematic error parameters were derived from up-to-date simulations made with the Plato Image Simuator (PIS) and since version 1.2 using a realistic Gaia field.
Older systematic errors tables are also provided.

When systematic errors are enabled, PSLS picks from the table the systematic error parameters 
(see Samadi et al 2019) of the stars with magnitude close to the magnitude specified by the user
and with a drift amplitude taken in a given range specified by the DriftLevel parameter (low: 0-0.4 px/90days, medium: 0.4-0.8 px/90days, and high: >0.8 pix/90days).

Two working examples are also provided:

* a main sequence star (0012069449.yaml) with its associated theoretical frequencies (0012069449.gsm) generated by ADIPLS pulsation code
* a red giant star (0009882316.yaml), which does not require as input theoretical frequencies.

A couple of grids containing solar-like oscillation models can be downloaded from the PSLS website (http://psls.lesia.obspm.fr).
For the time being only old type of grids are provided (ModelType='grid-old'). The new ones (also computed with CESAM2K) will be stored in HDF5
and will be made available soon.

If you use PSLS in your research work, please make a citation to Samadi et al (2019, A&A, 624, 117, https://www.aanda.org/articles/aa/abs/2019/04/aa34822-18/aa34822-18.html)
and Marchiori et al (2019, A&A, 627, A71, https://www.aanda.org/articles/aa/abs/2019/07/aa35269-19/aa35269-19.html)

For more details about the recent releases please see the release notes included in the package.

Changes history

* 1.7 (29/9/24):
    - new option "--psd" permits to save the PSD associated with the averaged light-curve (averaged over all cameras).
      A double-sided PSD is assumed. The PSD is saved in a .npz file (compressed binary file).
      The data are saved as a dictionary. The frequencies are saved with the label 'nu' and are given in microHz while
      the PSD is saved with the label 'psd' and the unit is ppm2/microHz.
    - For the granulation component we have now the choice between Kallinger et al (2014)'s model (type=1, the model used so far)
     or a single Lorentzian component (type=0). Accordingly, there is a new parameter Type in the Granulation section.
    - option -M is now working properly
    - new CESAM2K grid format stored in HDF5 files, the old type of grids can be used  provided that ModelType = 'grid-old'
    - non-linear limb darkening can be used when 4 coefficients are defined for the parameter LimbDarkeningCoefficients (instead of 2 for a quadratic limb darkening).
    We acknowledge here Pierre Maxted ([e-mail]) for this improvement
    - new configuration file (not compatible with earlier versions)
* 1.6 (6/01/23):
    - the mode properties can now be specified with an input TEXT file (instead of using a .gsm generated with ADIPLS)
    - inclusion of a spot model based on Dorren (1987)'s model and implemented by Cilia Damiani
    - new configuration file (not compatible with earlier versions)
    - seed numbers can be controlled independently for the spot component and stellar component (=activity,granulation, oscillations)
* 1.5 (01/07/22): IMPORTANT bug correction: since version 1.0 a wrong value for the (square) visibility  of the l=1 modes was used (0.2 instead of the correct value of 1.5), this bug led to a large underestimation of the amplitude of the l=1 modes
* 1.4 (30/08/21): planetary transits generated with a vectorized code (credit: Leigh Smith) ; previous V-P relation was not (fully) compliant with Marchirori et al (2019) (bug reported by Leigh Smith) ; solve string compatibility issue when the pulsations are taken from a grid of stellar models
* 1.3 (18/12/20): New tables for systematic errors based on PIS simulations made for 24 cameras , input files are now stored in appropriated sub-directories  ; bug correction: LimbDarkeningCoefficients is now taken into account
* 1.2 (25/05/20): New tables for systematic errors, random noise can vary with mask shapes and mask updates, amplitude of the drift can be controlled  by the parameter Systematic/DriftLevel, mask updates are flagged
* 1.1 (03/02/20): Some Python3 compatibility issues corrected. New option "-m" generating merged light-curves, new option -M to perform Monte-Carlo simulations
* 1.0 (05/09/19): Implementation of the V-P color-magnitude relation from Marchiori et al (2019). The option -f saves now each individual light-curves. Oscillations can be turned off. New format for the input file (YAML). PLATO NSR values are now available down to magnitude P=15.6.
* 0.9 (20/05/19): the NSR table was incorrectly interpolated. V magnitudes ranging between 12 and 13 were affected.
* 0.85 (23/03/19): minor changes to make the code fully compatible with python3
* 0.8 (23/02/19): systematic errors are now modelled and simulated in the time domain. The jumps induced by the quasi-regular mask updates are now included. Version corresponding to the published paper Samadi et al (2019, A&A, 624, 117)
* 0.7 (10/12/18): inclusion of PLATO systematic errors and random noise as a function of the star V magnitude
* 0.6: minor problems fixed (missing file,  link problem)
* 0.5: can perform simulation for a given input set of theoretical frequencies (i.e. from a given .gsm file) ; new parameters included in the configuration file .yaml ; various minor improvements
* 0.4: minor changes
* 0.3: first working version

 	
Copyright (c) October 2017, Reza Samadi, LESIA - Observatoire de Paris

This is a free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
 
This software is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License
along with this code.  If not, see <http://www.gnu.org/licenses/>.