psls 1.8

================================================
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).
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)

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.


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

Wit the option --hdf5, the following data are saved (depending on the configuration and where the options -f and -m are also activated):
 ACTIVITY_LC: shape=(N, Ng)
    the (stochastic) activity component
    zero centered in ppm
 GRANULATION_LC: shape=(N, Ng)
    the granulation component
    zero centered in ppm
 MEAN_LC: shape=(N, 2)
    the mean LC (averaged over the groups)
    zero centered flux in ppm
 INDIVIDUAL_LC: shape=(N, Ng, Nc, 4)
    the individual LCs (relative flux variation)
    zero centered flux in ppm
 OSCILLATIONS_LC: shape=(N, Ng)
    the oscillations component
    zero centered in ppm
 RANDOM_LC: shape=(N, Ng, Nc)
    the random noise component
    zero centered in ppm
 SPOT_LC: shape=(N, Ng)
    the spot component
    normalized flux
 STELLAR_LC: shape=(N, Ng)
    the sum of all the stellar components
    normalized flux
 SYSTEMATICS_LC: shape=(N, Ng, Nc)
    the systematics component
    zero centered in ppm
 TRANSIT_LC: shape=(N, Ng)
    the transit component
    normalized flux
 MERGED_LC: shape=(N*Ng,3)
    the merged LC
    zero centered flux in ppm

Here N is the number of data point, Ng is the number of groups (1-4) and Nc the number of cameras per group (1-6).
The first column is the flux (zero centred or the normalized depending on the data)
For MEAN_LC, the second column is a flag: flag > 0 when a mask update occurs or when we change the quarter
For MERGED_LC:
    second column: group number
    third column: flag
For INDIVIDUAL_LC
    second column: group number
    third column: camera number
    fourth column: flag

The relative flux variation (in ppm)  is calculated for a given camera  on the basis of the following formula:
INDIVIDUAL_LC = ( ( 1 +  ( O + G + A ) * s ) * ( 1 + (RSE + R)*s ) * S * T  - 1)/s
where:
  O: oscillations (ppm)
  G: granulation (ppm)
  A: (stochastic) activity (ppm)
  RSE: residual systematic error (ppm)
  R:  random error (ppm)
  S: spot (normalized flux)
  T: transit (normalized flux)
and s = 10^(-6)
Note that by nature, the terms O,G, A and R have zero mean.

Changes history
* 1.8 (29/01/25):
    - the duration of each quarter has now to be specified (in days) ; the total duration of the simulation is now the sum of the quarter durations
    - the option --hdf5 saves in a HDF5 file the light-curves (LC) and the various simulation components and data
    (systematics, transit, random noise, spot, PSD, individual LC, merged LC, ...etc).
    - the oscillations, granulation and (stochastic) activity components are now simulated independently and then added
    in the time-domain, allowing them to be recorded separately ;
    - seed numbers can be controlled independently for the stochastic activity, granulation, and oscillations components ;
    - introduce gaps due to the inter-quarter interruptions, random gaps, and nearly periodic gaps ;
    - introduce modulations in the spot radii, specified by a period in days ;
    - groups of simulated cameras can be specified individually (for instance the simulation can be limited to the
    groups 1 and 3 instead of simulating all the 4 groups [1,2,3,4] ; this is useful when one want to assess the
    impact of different configurations in terms of time shifts between light-curves) ;
    - the option --proto-sas saves the data in a HDF5 file and in format compatible with the prototype SAS pipeline
    - when sampling >25s, the systematic errors were not correctly averaged (systematic errors were increased by a factor Sampling/25)
* 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 (p.maxted@keele.ac.uk) 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

January 2025, R. Samadi (LIRA, Observatoire de Paris)

Contributors: Alexis Deru (LIRA), Emmanuel Grolleau (LIRA), Daniel Reese (LIRA),
Leigh Smith (University of Cambridge),  Cilia Damiani (MPSSR, Gottingen), Lucie Degott (IAS),
Pierre Maxted (Keele University), Jordan Philidet (LIRA)

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/>.