Setup Instructions

Setup of runtime environment

This code base was developed within the context of a Python3 virtual environment which supports Python 3.9+, Scikit-Learn, TensorFlow, Keras, lightkurve, astropy and any further libraries upon which the code is dependent. The dependencies are documented in the requirements.txt file.

Having first cloned this GitHub repo, open a Terminal at the root of the local repo and run the following commands. First to create and activate the venv;

$ python -m venv .ebop_maven

$ source .ebop_maven/bin/activate

Then run the following to set up the required packages:

$ pip install -r requirements.txt

You may need to install the jupyter kernel in the new venv:

$ ipython kernel install --user --name=.ebop_maven

To replicate the published results it is necessary to avoid the use of any CUDA compliant GPU cores. This is done by hiding the cores from the TensorFlow library with the following environment variable setting;

$ export CUDA_VISIBLE_DEVICES=-1

JKTEBOP

These codes have a dependency on the JKTEBOP tool for generating and fitting lightcurves. The installation media and build instructions can be found here. The JKTEBOP_DIR environment variable is used by the training and testing code to locate the executable at runtime.

$ export JKTEBOP_DIR=~/jktebop/

Set this to match the location where JKTEBOP has been set up.

Alternative, conda virtual environment

To set up an ebop_maven conda environment, from the root of the local repo run the following command;

$ conda env create -f environment.yaml

You will need to activate the environment whenever you wish to run any of these modules. Use the following command;

$ conda activate ebop_maven

The conda environment sets the JKTEBOP_DIR and CUDA_VISIBLE_DEVICES environment variables to ~/jktebop/ and -1 respectively.

The ebop_maven package

Finally there is support for installing ebop_maven as a pip package. Simply run the following within the context of your own base or custom environment:

$ pip install git+https://github.com/SteveOv/ebop_maven

This will install the Estimator class, a pre-built default model and the required support libraries (basically anything within the ebop_maven subdirectory). This supports the use of the Estimator with the default model within a client application. The code used in the following steps for training and testing models is not installed.

Generation of training and testing datasets

These steps will take roughly two hours on a moderately powerful system, with the resulting datasets taking up ~8.5 GB of disk space within the ./datasets/ directory.

The formal training dataset

To generate the datasets which will be used to train and test the machine learning model, first open a terminal at the local root of the repo then run (within the context of the venv);

$ python3 make_training_dataset.py

This will generate the the formal-training-dataset-500k and save it within the ./datasets/ directory. This is a synthetic training dataset built by randomly sampling distributions of JKTEBOP model parameters across its entire parameter space. It generates 500,000 instances split 80:20 between training and validation sets.

The synthetic MIST/TESS test dataset

The module to generating the test dataset depends on MIST isochrone files which are not distributed as part of this GitHub repo. You will need to download and extract a pre-built model grid by following the instructions in readme.txt.

With the isochrones set up, next run (within the context of the venv);

$ python3 make_synthetic_test_dataset.py

to build the synthetic-mist-tess-dataset and save it within the ./datasets/ directory. This is the full dataset of synthetic light-curves generated from physically plausible systems based on MIST stellar models and the TESS photometric bandpass. It generates 20,000 randomly oriented instances based on an initial random selection of metallicity, age and initial masses supplemented with lookups of stellar parameters in the isochrones.

The formal test dataset of real systems

Finally run (within the context of the venv);

$ python3 make_formal_test_dataset.py

to build the formal-test-dataset and save it within the ./datasets/ directory. These are set of real, well-characterized systems from DEBCat selected on the availability of TESS light curves, suitability for fitting with JKTEBOP and a published characterization from which parameters may be taken as labels. The chosen systems are configured in the file ./config/formal-test-dataset.json which contains the search criteria, labels and supplementary information for each.

Training and testing the machine learning model

The default machine learning model can be built and tested by running the following command (within the context of the venv) from the root of the local repo:

$ python3 make_trained_cnn_model.py

This will create the default CNN/DNN model, trained and validated on the formal-training-dataset to predict the $r_A+r_B$, $k$, $J$, $e\cos{\omega}$, $e\sin{\omega}$ and $b_P$ labels. Once trained it is evaluated on the synthetic-mist-tess-dataset before a final evaluation on the real systems of the formal-test-dataset.

By default CUDA cores are disabled so that training and testing is repeatable. This is achieved by setting the CUDA_VISIBLE_DEVICES environment variable to -1 (the default setting for a conda env created from environment.yaml). In this configuration the process above takes about three hours on my laptop with an 8 core 11th gen Intel i7 CPU.

If you wish to use cores then you will need to change this setting.

Note: there are recorded incidents where TensorFlow v2.16.1 does not "see" installed GPUs (me for one) and under these circumstances the above change may have no effect. The issue is resolved with v2.17 which is the version used to produce the published results.

The newly compiled and trained model will be saved to the ./drop/training/cnn-new-ext0-bp-4096-none-500k/default-model.keras file with an accompanying log file. Plots of the learning curves and the model structure are written to a plots sub-directory.

A detailed evaluation of any models can be invoked with the following command (within the context of the venv);

$ python3 model_testing.py [model_files ...]

This will initially evaluate model predictions against the synthetic-mist-tess-dataset and the formal-test-dataset. Subsequently it will run the full end-to-end testing of model predictions and JKTEBOP fitting against the formal-test-dataset. Testing output files and a log file will be written to a testing sub-directory alongside any tested models.

You can test the pre-built model, at ./ebop_maven/data/estimator/default-model.keras, by running model_testing without any arguments. In this case, the results will be written to the ./drop/training/published/testing/ directory.

Interactive model tester

This is a jupyter notebook which can be used to download, predict and fit any target system selected from the formal-test-dataset against the pre-built default-model within the ./ebop_maven/data/estimator directory or any model found within ./drop/training/. It can be run with (within the context of the venv):

$ jupyter notebook model_interactive_tester.ipynb

A second jupyter notebook called quick_fit allows fitting against any target but requires the user to supply detailed configuration of the search criteria and pre-processng required. By default this is set configured to fit ZZ Boo.

$ jupyter notebook quick_fit.ipynb