ExoTransmitPy

Author - Joshua Hayes (joshua.hayes@postgrad.manchester.ac.uk), working on behalf of SPEARNET.

ExoTransmitPy is a Python 3 wrapper for ExoTransmit (Kempton et. al. 2017 (https://arxiv.org/abs/1611.03871)), an exoplanet transmission spectrum simulator. ExoTransmitPy_public is the stable public release.

Please follow the Installation instructions carefully, as you will be required to have installed a working copy of Exo-Transmit.

This wrapper is simple to use, has wide application, and multi-core functionality.

License and legal notice

Copyright (C) 2018 Joshua Hayes

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

ExoTransmitPy is 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.

ExoTransmitPy 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 ExoTransmitPy. If not, see http://www.gnu.org/licenses.

Installation instructions

Simple

1. 1. Download Exo-Transmit from https://github.com/elizakempton/Exo_Transmit and install it in a known location. I would recommend that you do this in a folder called something like ExoTransmit, as it will make your folder tree neater later on (see First time usage)
   2. Follow the installation instructions for Exo-Transmit. i.e. Navigate to the folder you installed Exo-Transmit to and compile the code by typing $ make.
2. In terminal, navigate to ExoTransmitPy top folder.
3. Run $ python setup.py install to install ExoSpy to your Python library. If this does not work, read alternate instructions below.

ExoTransmitPy should now be importable in Python with the line >>> import exotransmit (Please see First time usage for notes on how this works initially).

Advanced instructions if you are lacking permissions to run setup.py

1. Install Exo-Transmit as per steps 1 and 2 above.
2. In an area you have access to and permission to do so (home area or local drive is a good idea) create a directory called something identifiable. For the purposes of this, I will assume a folder called foo/
3. Move/copy the ExoTransmitPy/exotransmit folder (which contains all the subpackages) into foo/. The folder you move should be at the same level as this README.
4. 1. For CSH/TSCH: In your ~/.cshrc file, add the line setenv PYTHONPATH /path/to/foo/
   2. For BASH/KTH: In your ~/.bashrc file, add the line export PYTHONPATH=/path/to/foo/
5. Run $ source ~/.cshrc or $ source ~/.bashrc

ExoTransmitPy should now be importable in Python with the line >>> import exotransmit (Please see First time usage for notes on how this works initially).

Python package requirements

The following Python 3 packages must be installed for ExoTransmitPy to work:

astropy

numpy

Using ExoTransmitPy

First time usage

The first time that you run >>> import exotransmit it will require you to give the path to the installation of Exo-Transmit. The initial import will then create two folders at the same level as your installation of Exo-Transmit. These are

• ExoTransmitCluster: This contains n copies of Exo-Transmit, where n is the number of cores on your machine. This folder exists to allow multiple instances of Exo-Transmit to run simultaneously, which must all be separate due to the internal architecture of Exo-Transmit. Unlike with vanilla Exo-Transmit, the generated spectra are not stored within the /Spectra/ folder (See next point).
• ExoTransmitSpectra: This contains all spectra which are generated by ExoTransmitPy. This exists to centralise all generated spectra and make finding them easier. The file names and save location are standardised, as outlined in File naming convention.

Note that if there is an issue with config in first time set up, delete the file ExoTransmitPy_public/exotransmit/include/_config.txt and try again. If there is still an issue, redownload ExoTransmitPy_public and try again from the top.

General usage

In everyday usage, the only function you need to use is exotransmit.run. All other modules contain functions which feed into the functionality of this.

Here is a simple example of how to simulate a planet with the parameters

Equation of state: eos_1Xsolar_cond

Temperature: 400K

Surface gravity: 9.81 m/s2

Planet radius: 0.9 Jupiter radii

Star radius: 1.2 Solar radii

Cloud top pressure: 1000 Pa

Rayleigh scattering factor: 1:

import exotransmit
exotransmit.run([11, 400, 9.81, 0.9, 1.2, 1000, 1])

Once Exo_Transmit has finished running, the .dat file will be saved in the ExoTransmitSpectra folder, following the File naming convention. If the kwarg return_paths=True is used, then the full paths will be reurned by the function.

Note that the Equation of state is selected using a numerical code. To see a list of all the available equations of state and their associated code, type exotransmit.list_eos()

The current release of ExoTransmitPy can only deal with isothermal T-P profiles.

If you want to generate multiple spectra, you can pass a list of the parameters to exotransmit.run. For example, to run 3 planets with the same parameters as above, but changing the temperature, using 2 cores, one would type:

import exotransmit
exotransmit.run([[11, 400, 9.81, 0.9, 1.2, 1000, 1],
                 [11, 500, 9.81, 0.9, 1.2, 1000, 1],
         [11, 600, 9.81, 0.9, 1.2, 1000, 1]],
         ncores=2)

ExoTransmitPy will split the generation of parameters between the number of cores specified by ncores. By default, this will use all cores on a machine if there are more sets of parameters than cores.

ExoTransmitPy is also fairly intelligent with regards to duplication. If a spectrum file exists with the specified parameters (determined using the default file names, which is why you shouldn't change them usually), it will not overwrite unless passed the kwarg :code:`clobber=True`. Note though that if you specify thekwarg output_paths, ExoTransmitPy cannot see the output paths (in V0.1.3 at least, though this will be updated in the future).

File naming convention

DO NOT RENAME FILES MANUALLY ELSE EXOTRANSMITPY WILL NOT BE ABLE TO LOCATE THEM

The data files produced by Exo-Transmit are not intended to be read by a human. This is to say they are human readable, but aren't hugely useful in this format, except for sanity checking to see that you haven't got all NaNs or something.

All files are by default saved in ExoTransmitSpectra/{hostname}/{EoS_name}/{Temperature}/{file name}

The data file names are in the following convention:

A-B-C-D-E-F-G.dat

A - Equation of state number code. Run exotransmit.list_eos() to see full list of codes and associated EoS

B - Equilibrium temperature in K

C - surface gravity in m/s2

D - Planet radius in Jupiter radii

E - Stellar radius in Solar radii

F - Cloud top pressure in Pa

G - Rayleigh scattering factor

Development

ExoTransmitPy may get occasional updates. If there is a feature you would like implementing, then either email joshua.hayes@postgrad.manchester.ac.uk, and we will see what we can do, or raise a pull request and do it yourself!

If there are any bugs you find, please raise an issue and we will have a look at and fix them.

Acknowledgements

This wrapper was created for the code Exo-Transmit, written by Eliza Kempton.

Testers for this code were Eamonn Kerins, Iain MacDonald, Jake Staberg Morgan, and Joel Williams.

Citing

If you find ExoTransmitPy useful in your work, please cite us using the following BibTeX entry:

@misc{ExoTransmitPy,
  title={{ExoTransmitPy: A Python 3 wrapper for Exo-Transmit}},
      author={Joshua Hayes, Eamonn Kerins},
  howpublished={\url{http://github.com/joshjchayes/ExoTransmitPy}},
  year={2018},
  note={Accessed: 20XX-MM-DD}
  }