Before using this software, please read the Trainning and citation at the end of this documentation.
How to install#
K-Stacker requires Python>=3.7 and a C compiler (you can use e.g. Anaconda to get a recent Python if needed).
To install K-Stacker in your Python environment, from the git repository:
$ git clone https://github.com/kstacker/kstacker.git $ cd kstacker $ pip install -e .
Before running K-Stacker#
Create a directory where you will run K-Stacker.
In this directory, create a sub-directory called
images/(can be configured with the
In the images directory put your reduced images. The files must be names
image_n.fits(squared images, sorted by epochs).
parameters.ymlconfiguration file for your data (you can start from the example file
Adjust the numbers such as explained in the comments of
a_initmust be a value near the maximum you want to search (but smaller than
r_mask_extin a.u.); you don’t need to change the other
Adjust the range of the orbital parameters where you want to search for a planet :
t_0_minmust be equal to
- sqrt(a_max^3 / m0).
You can put your
parameters.ymlfile in the K-Stacker directory (at the same level than the images directory).
The first step is to compute noise, background, and SNR profiles:
kstacker noise_profiles parameters.yml
When the noise profiles computation has finished, adjust the size of the grid by counting the number of maximums (peaks) of each
snr_ksplot (see the PDF files in
profiles/snr_plot_steps_remove_noise_no_999999/snr_graph/) and report these numbers in the
parameters.ymlfile (Na, Ne, Nt0, etc.)
Then run the optimization step, which can be computationally intensive depending on the number of steps for the orbital parameters. To get an idea of the number of orbits that will be computed use the
--dry-runargument. If K-Stacker has been compiled with the support of OpenMP, which should be the case by default on Linux, you can use the
--nthreadsargument to specify the number of parallel threads.
kstacker optimize parameters.yml
When the optimization computation is finished, run the gradient by launching in a terminal:
kstacker reopt parameters.yml
Running on a Slurm cluster#
example/ directory contains some examples of Slurm scripts to run
slurm_launch_noise_prof.sh slurm_launch_brute_force.sh slurm_launch_reopt.sh
The results of your K-Stacker run will be in the values directory. In case of difficulty, you can contact us.
You can train you by launching K-Stacker on the data provided in the example directory.
The Parameters_test_HD95086.yml has been pre-configured to search for HD95086b in the field of view of the SPHERE-IFS images. The IFS (K-band) images of HD95086 provided in this example come from the SPHERE / SHINE survey ([Chauvin2018], [Desgrange2022])
Chauvin, Gratton, Bonnefoy, et al. 2018, A&A, 617, A76; Desgrange et al. 2022, accepted). They have been reduced by SPHERE-DC with an ASDI-TLOCI algorithm. These data are available in the HC-DC.DIVA data base (https://cesam.lam.fr/diva/).
We also provide an example of slurm files that you can use on a cluster.
The idea to search for hidden planets in series of observations was proposed during the Observatoire de Haute-Provence 2015 meeting (Le Coroller et al. 2015, ‘Twenty years of giant exoplanets’ Edited by I. Boisse, O. Demangeon, F. Bouchy & L. Arnold, p. 59-65). [Nowak2018] has written the first version of the K-Stacker algorithm and tested its capability for detecting hidden planets (snr_ks < 2 at each epoch) in simulated coronagraphic images. In [LeCoroller2020], K-Stacker was validated through a dry run where fake planets where injected and recovered in real SPHERE SHINE data. In this paper, we also discussed the capability for K-Stacker to recover the orbital parameters space. Recently, K-Stacker has been fully rewritten by Simon Conseil, a computer engineer working at CeSAM / Laboratoire d’Astrophysique de Marseille ([LeCoroller2022], a scientific paper on Alphacen A NEAR-VISIR survey, where this git repository link is given for the first time).
Students of L3-M2 had also contributed to the initial project: Antoine Schneeberger; Marie Devinat; Justin Bec-Canet; Dimitri Estevez
This research has been financed by PNP-INSU-CNRS
If you use this K-Stacker software for your research, please add this sentence in the acknowledgements of your paper:
“This work made use of the K-Stacker algorithm maintained by CeSAM at Laboratoire d’Astrophysique de Marseille”
You also have to cite the three original papers:
Nowak, M., Le Coroller, H., Arnold, L., et al. 2018, A&A, 615, A144, https://ui.adsabs.harvard.edu/abs/2018A%26A…615A.144N
Le Coroller, H., Nowak, M., Delorme, P., et al. 2020, A&A, 639, A113, https://ui.adsabs.harvard.edu/abs/2020A%26A…639A.113L
Le Coroller, H., Nowak, M., Wagner, K. et al. 2022, A&A, submitted
Papers describing the data used in the example directory:
If you need some help, you can contact us at this email address :
Our team would be happy to collaborate on scientific projects using K-Stacker.