Skip to content
No description, website, or topics provided.
Python TeX
Branch: master
Clone or download
gmorello Update paper.md
link to JOSS paper
Latest commit 99266a4 Feb 11, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.idea
Wavelength_bins_files Passbands and Wavelength_bins_files folders Mar 6, 2019
aux_files
examples
exotethys
target_list Add files via upload Sep 4, 2019
.gitignore gitignore Feb 12, 2019
.travis.yml
CONTRIBUTING.md Create CONTRIBUTING.md Dec 10, 2019
HISTORY.md Update HISTORY.md Dec 16, 2019
LICENSE
README.md Update README.md Dec 16, 2019
logo.png
paper.bib Update paper.bib Jan 10, 2020
paper.md
requirements.txt Add files via upload Dec 4, 2019
setup.py

README.md

ExoTETHyS

ExoTETHyS logo

Version 1.0.2 Build Status DOI

ExoTETHyS is an open-source package for modeling exoplanetary transits, eclipsing binaries and related phenomena.

If you use this code for your research, please consider citing Morello et al. 2019, ... (arXiv:1908.09599)

Dependencies

The code is consistent with python2/3. It makes use of

  • numpy, scipy

Download and installation

From Pypi

Type on the terminal: pip install exotethys
This command installs the latest stable version of the package.

From GitHub

The most updated version of the package is available on GitHub. As this version is constantly under development, stability is not guaranteed.

  1. Go to https://github.com/ucl-exoplanets/ExoTETHyS/ and click the green button "Clone or download", then click "Download ZIP" to download the whole repository. Alternatively type git clone https://github.com/ucl-exoplanets/ExoTETHyS in a terminal window.

  2. Access the root folder from terminal (you may need to unzip first).

  3. After accessing the root folder from terminal, type pip install .
    to install the package. Otherwise, you could import the package without installation, if you run python from the root folder.

  4. To test the installation, you can type:

    pytest PATH_TO_ROOT/exotethys/tests/test_sail.py  
    pytest PATH_TO_ROOT/exotethys/tests/test_trip.py 
    

NOTE: The root folder name depends on the download process. It appears to be "ExoTETHyS-master" if downloaded from the web browser interface, "ExoTETHyS" if git cloned from terminal.

List of subpackages

  1. SAIL (Stellar Atmosphere Intensity Limb)
    This subpackage can provide sets of stellar limb-darkening coefficients with

    • continuous ranges of the stellar parameters (effective temperature, surface log gravity, scaled solar metallicity);
    • built-in or user-defined passbands (with or without spectroscopic bins);
    • built-in or user-defined limb-darkening laws;
    • using different databases of stellar model-atmospheres.

    How to run:

    >>> from exotethys import sail  
    >>> sail.ldc_calculate('PATH_TO_ROOT/examples/sail_example1.txt')   
    
  2. TRIP (Transit Ring-Integrated Profile)
    This subpackage can compute transit light-curves by using stellar specific intensities rather than (approximate) limb-darkening coefficients.

    How to run:

    >>> from exotethys import trip  
    >>> trip.trip_calculate('PATH_TO_ROOT/examples/trip_example.txt')  
    

WARNING: running this trip_example will consume a lot of memory (>10 GB), because by default TRIP uses 100000 annuli to compute the integral stellar flux. The user can set a different number of annuli by uncommenting the line with "n_annuli" in the trip_example.txt and changing the relevant number (5000-10000 should be sufficient to get a nice looking light-curve, but the absolute precision is not guaranteed).
NOTE: The examples are written to be launched from root directory level. Alternatively, the paths in the examples need to be personalized by the user.

SAIL configuration file

The SAIL configuration file is a text file in which each line begins with a keyword followed by one or more values associated with the keyword. The lines starting with # are ignored; keyword values preceded by ! are also ignored. Examples of configuration files can be found in the "examples" folder.

Below I describe the available keywords:

calculation_type (MANDATORY)
values: "individual" (for specific targets) or "grid" (for database models)

stellar_models_grid (MANDATORY)
values: "Phoenix_2018", "Phoenix_2012_13" or "Atlas_2000" (choose only one of them)

limb_darkening_laws (MANDATORY)
values: "claret4", "power2", "square_root", "quadratic", "linear", "gen_claret" and/or "gen_poly"

gen_claret_orders (only if gen_claret, mandatory)
values: positive integer numbers

gen_poly_orders (only if gen_poly, mandatory)
values: positive integer numbers

passbands_path (OPTIONAL)
values: path to user passbands (it should end with /)

passbands (MANDATORY)
values: built-in passband names if not passbands_path ("Kepler", "TESS", "WFC3_G141", "STIS_G430L", "STIS_G750L", "irac1subarray", "irac2subarray", "irac3subarray", "irac4subarray", "uniform_phoenix_2012_13", "uniform_phoenix_2018", "uniform_atlas_2000") or user file names

wavelength_bins_path (OPTIONAL)
values: path to wavelength bins files (it should end with /)

wavelength_bins_files (OPTIONAL)
values: user file names or "no_bins"
This refers to a text file with 2 columns reporting the lower and upper limits of the desired wavelength bins (each row defines a wavelength bin).

user_output (OPTIONAL)
values: "basic" (default) or "complete"

output_path (OPTIONAL)
values: path to where to store the results (it should end with /)

targets_path (only if individual calculation_type, optional)
values: path to target file (it should end with /)

targets_file (only if individual calculation_type, optional)
values: user file name (examples are in the "target_list" folder)
This refers to a text file with up to 4 columns. The first row contains the keywords in arbitrary order: target_names (optional), star_effective_temperature (mandatory), star_log_gravity (optional) and star_metallicity (optional). The other rows contain the corresponding key values for the requested targets. If one of the optional parameters is not available, it should be reported as "X", so that all rows have the same number of elements.

target_names (only if individual calculation_type, if not targets_file, optional)
values: string type for target names

star_effective_temperature (only if individual calculation_type, if not targets_file, mandatory)
values: float type for stellar temperatures

star_log_gravity (only if individual calculation_type, if not targets_file, optional)
values: float type for stellar log(g) (default is 4.5)

star_metallicity (only if individual calculation_type, if not targets_file, optional)
values: float type for stellar [M/H] (default is 0.0)

star_minimum_effective_temperature (only if grid calculation_type, optional)
values: single float value

star_maximum_effective_temperature (only if grid calculation_type, optional)
values: single float value

star_minimum_log_gravity (only if grid calculation_type, optional)
values: single float value

star_maximum_log_gravity (only if grid calculation_type, optional)
values: single float value

star_minimum_metallicity (only if grid calculation_type, optional)
values: single float value

star_maximum_metallicity (only if grid calculation_type, optional)
values: single float value

NOTE: The parameters must be within the parameter space of the selected stellar_models_grid. Further information is provided in the "Description of examples".

TRIP configuration file

The TRIP configuration file is a text file in which each line begins with a keyword followed by one or more values associated with the keyword. The lines starting with # are ignored; keyword values preceded by ! are also ignored. Examples of configuration files can be found in the "examples" folder.

Below I describe the available keywords:

input_limb_type (MANDATORY)
values: "mu" or "radi" (specify first column of the input limb-darkening file)

input_limb_path (OPTIONAL)
values: path to input limb-darkening file (it should end with /)

input_limb_file (MANDATORY)
values: user file name (examples are in the "aux_files" folder) This refers to a text file with 2 columns. The first column reports the mu or radi coordinates that define the positions on the projected stellar disk (0 <= mu, radi <= 1). The second column reports the specific intensities with dimension [energy]/([area][time][wavelength][solid angle]).

input_series_type (MANDATORY)
values: "phi" (orbital phase values - integer numbers correspond to inferior conjunction) or "time" (Julian Dates or any other time units) or "z_sep" (sky-projected star-planet separations in units of the the stellar radius)

input_series_path (OPTIONAL)
values: path to input timeseries file (it should end with /)

input_series_file (MANDATORY)
values: user file name (examples are in the "aux_files" folder)
This refers to a text file with 1 column reporting the points at which to compute the light-curve.

rp_over_rs (MANDATORY) values: float type (non-negative)

sma_over_rs (only if phi or time input_series_type, mandatory) values: float type (sma_over_rs >= 1)

inclination (only if phi or time input_series_type, mandatory) values: float type (0 <= inclination <= 90)

eccentricity (only if phi or time input_series_type, optional) values: float type (0 <= eccentricity < 1.0, default is 0.0)

arg_pericenter (only if phi or time input_series_type, optional) values: float type (-180.0 < arg_pericenter < 360.0, default is 0.0)

period_orbital (only if time input_series_type, mandatory) values: float type (positive)

epoch_of_transit (only if time input_series_type, mandatory) values: float type
It must be in the same units of the input timeseries.

time_conversion_factor (only if time input_series_type, optional) values: float type (positive, default is 1)
It is the ratio between timeseries and orbital period units (e.g., time_conversion_factor = 1.157407407407407e-05 if timeseries in seconds and orbital period in days).

n_annuli (OPTIONAL) values: positive integer number (default is 100000)

interpolation_type (OPTIONAL) values: "linear" (default), "nearest", "zero", "slinear", "quadratic", "cubic", "previous" or "next"
Check scipy.interpolate.interp1d function for details.

interpolation_variable (OPTIONAL) values: "mu" (default) or "radi"

cutting_limb (OPTIONAL) values: "no_cut" (default), "radi_gradient", "mu_gradient" or "user_cut"
Different options for truncating the input limb-darkening model.

user_cut_mu (only if user_cut cutting_limb and no user_cut_radi, mandatory) values: float number (0 < user_cut_mu < 1)

user_cut_radi (only if user_cut cutting_limb and no user_cut_mu, mandatory) values: float number (0 < user_cut_radi < 1)

rescaling_limb (OPTIONAL) values: "as_cut" (default), "no_rescale" or "user_rescale"
Different options for rescaling the mu or radi coordinates of the input limb-darkening model.

user_rescale_mu (only if user_rescale rescaling_limb and no user_rescale_radi, mandatory) values: float number (0 < user_rescale_mu < 1)

user_rescale_radi (only if user_rescale rescaling_limb and no user_rescale_mu, mandatory) values: float number (0 < user_rescale_radi < 1)

rescaling_input_params (OPTIONAL) values: "no" (default) or "yes"
If yes, the rp_over_rs and sma_over_rs values are divided by the rescaling radius.

output_path (OPTIONAL)
values: path to where to store the results (it should end with /)

output_filename (OPTIONAL)
values: string type (without extension)

output_fileext (OPTIONAL)
values: ".pickle" (default) and/or ".txt"

Description of examples

sail_example1: This example is to compute the limb-darkening coefficients for a single stellar target and photometric passband. It creates a file named "teff6065.0_logg4.36_MH0.0_ldc.pickle".

sail_example2: This example is to test the complete output, including the stellar intensity profile and coefficients for the neighbour models. It creates three files named "teff28300.0_logg4.35_MH-0.23_ldc.pickle", "teff28300.0_logg4.35_MH-0.23_neighbour_ldc.pickle" and "teff28300.0_logg4.35_MH-0.23_neighbour_intensities.pickle".

sail_example3: This example contains stellar parameters just outside the covered parameter space. If running this example, the code will exit with 2 warnings (one for each neighbour not found) and one error:

WARNING: teff28300.0_logg2.6_MH-0.23 cannot be calculated. Neighbour 3 not found for the stellar_models_grid Atlas_2000 .
WARNING: teff28300.0_logg2.6_MH-0.23 cannot be calculated. Neighbour 4 not found for the stellar_models_grid Atlas_2000 .
ERROR: No legal targets to calculate.

In particular, the code searches for the 8 nearest neighbours that defines a volume containing the requested point (28000, 2.6, -0.23 ) in the following order:
neighbour 1: (+, +, +)
neighbour 2: (+, +, -)
neighbour 3: (+, -, +)
neighbour 4: (+, -, -)
neighbour 5: (-, +, +)
neighbour 6: (-, +, -)
neighbour 7: (-, -, +)
neighbour 8: (-, -, -)
where "+" and "-" denote a parameter value higher or lower than in the requested point. In this case the code fails to find neighbours with higher effective temperature and lower surface gravity, as they do not exist in the Atlas_2000 database. If more targets were requested, the code would just skip this target and move to the next one. Given there are no other requested targets, the code prints the error message and exits without producing any output.
The user can extract the information about all the available models in the grids by typing the following commands:

>>> from exotethys import sail  
>>> [files_Atlas_2000, params_Atlas_2000] = sail.get_grid_parameters('Atlas_2000') 
>>> [files_Phoenix_2012_13, params_Phoenix_2012_13] = sail.get_grid_parameters('Phoenix_2012_13') 
>>> [files_Phoenix_2018, params_Phoenix_2018] = sail.get_grid_parameters('Phoenix_2018') 

The first variable is the list of file names in the database, the second variable is the 3-column numpy array with the corresponding stellar parameters.

sail_example4: This example computes the limb-darkening coefficients for a grid of models. It creates a file named "grid_ldc.pickle".

sail_example5: This example computes the limb-darkening coefficients for a single stellar target over multiple spectroscopic bins within an instrument passband. It creates a file named "teff6065.0_logg4.36_MH0.0_ldc.pickle".

sail_example6: This example computes the limb-darkening coefficients for a single stellar target over multiple spectroscopic bins within an instrument passband and for another photometric passband. It creates a file named "teff6065.0_logg4.36_MH0.0_ldc.pickle".

sail_example7: This example computes the limb-darkening coefficients for two targets with names over multiple spectroscopic bins within an instrument passband. It creates two files named "HD209458b_ldc.pickle" and "WASP43b_ldc.pickle".

sail_example8: This example computes the limb-darkening coefficients for three targets read from file over multiple spectroscopic bins within an uniform passband. It creates three files named "HD209458b_ldc.pickle", "Sun_ldc.pickle" and "Cool_ldc.pickle".

trip_example: This example computes an "exact" transit light-curve based on some auxiliary input files. It creates two files named "trip_ld_Teff6100.0_logg4.5_MH0.0_TESS.pickle" and "trip_ld_Teff6100.0_logg4.5_MH0.0_TESS.txt".

You can’t perform that action at this time.