gbtds_optimizer

Tool for optimizing yields or metrics for the Roman Galactic Bulge Time Domain Survey

This repository contains two tools for optimizing and evaluating the field selection for the Roman Galactic Bulge Time Domain Survey:

• gbtds_optimizer.py is a general purpose optimizer that can take a map of survey yield for a single survey definition and provide contours yield for variations in pointing, exposure time and cadence.
• results_plotter.py is code to read in the results from gbtds_optimizer.py and plot/analyze it.
• optimizeSlew.py provides a tool to optimize and estimate slewing overheads in the GBTDS, and give a quick estimate of the impact of the field choice on the yield of bound Earth mass planets found via microlensing.

gbtds_optimizer.py

The basic inputs to this program are:

• a yield map. This can be the yield defined however you like, but is probably something like the number of detections of something of interest, or the number of a certain type of target observed.
• the exposure time and cadence that were used for calculating the yield map.
• (optional) power law indexes describing how the yield changes when the exposure time and cadence are changed.
• a field layout. This is a list of fixed and moveable fields that will be observed. The optimizer moves the moveable fields while keeping the fixed ones in place.
• (default provided) slew and settle times as a function of slew angle.
• (default provided) the detector layout.

Full options can be found by running the code with the help flag i.e., python gbtds_optimizer.py -h

An example of how to run the code for a chosen layout is

python gbtds_optimizer.py ffp_normmap_m+00v3_rate.yield.csv 14.7315 42.56 \
       field_layouts/layout_7f_3_gal-center.centers \
   	--lrange 2.2 -2.2 --brange -2.2 2.2 \
   	--lstep 0.2 --bstep 0.2 \
   	--cadence-bounds 7.0 15.0 \
   	--nread-bounds 10 40 \
   	--output-root ffp_normmap_m+00v3.layout_7f_3

The code will compute the yield of the field layout at various positions with all cadence and exposure times allowed within the requested bounts. The yield is scaled according to the $$Y_{\rm new} = Y_{\rm orig} (t_{\rm exp,new}/t_{\rm exp,orig})^{\alpha_{t_{\rm exp}}} (\Gamma_{\rm new}/\Gamma_{\rm orig})^{\alpha_{\Gamma}}$$ on a pixel-by-pixel basis if alphaTexp and alphaCadence columns are provided in the yield map file, or globally if --alpha-texp and --alpha-cadence arguments are given. Results are stored and can be visualized with the results_plotter.py script.

Getting the lrange and branges right can be tricky, as it depends on the size of the field layout. The gbtds_optimizer.sh script will calculate them automatically - these auto values will be incorporated in the python version at a later date.

results_plotter.py

This will load an output pickle generated by gbtds_optimizer.py and plot it, with various options. E.g.,

python results_plotter.py -i ffp_normmap_m+00v3.layout_7f_3

plotFields.py

This will plot a field layout on top of a yield map. Maps included in the reposi are the following:

1. free-floating planet yield maps for $$1 M_{\rm Earth}$$ and $$0.1 M_{\rm Earth}$$ (ffp_normmap_m+00v3_rate.yield.csv and ffp_normmap_m-10v3_rate.yield.csv), and
2. the reddening map of Gonzalez et al. (2012) converted to H band extinction (GonzalezExtinction.csv)

A working example of how to run it is

python plotFields.py ffp_normmap_m+00v3_rate.yield.csv \
	field_layouts/7fields/layout_7f_3f_gal-center.centers \
	--location 0.6 -1.4 \
	--sca-filename outline_sca_layout.txt \
	--save output/scen_163000_fields.png

Running it without arguments will display a help message.

If you just want to add field layouts to your own plot, a more portable piece of code without importing any of the package's modules is described next.

simple_field_plotting.py

This script is an uncomplicated example of how to plot field outlines given a field centers file. The code contained within it is

import matplotlib.pyplot as plt
import pandas as pd

sca = pd.read_csv('outline_sca_layout.txt',sep='\s+',header=None)
fields = pd.read_csv('field_layouts/layout_163000.centers',sep='\s+')

plt.figure()

for i,f in fields.iterrows():
    ls='k-'
    if f['fixed']==1:
        ls='r-'

    plt.plot(sca.iloc[:,1]+f['l'],sca.iloc[:,2]+f['b'],ls)
    

plt.xlabel('l (deg)')
plt.ylabel('b (deg)')
plt.gca().invert_xaxis()
plt.gca().set_aspect('equal')
plt.show()

optimizeSlew.py

The optimizeSlew.py script computes best path around a set of fields fields and a rough scaling of microlensing planet detection rates. Caution should be taken when increasing cadence beyond 15 minutes.

To run:

python optimizeSlew.py <fields> <slew-times (short axis)> {<slew-times (diagonal)> <slew-times (long-axis)>

The most up-to-date slew time file is slew_times_withResetReference_McEnery05232024.txt - this file is the slew_times_McEnery05232024.txt file provided by Julie McEnery with 6.12 seconds added to every slew to account for the reset read cycle (3.08 s) and the first reference read that is subtracted from the ramp (3.04 s). If you are using sample up the ramp signal to noise estimates the reference read is already accounted for in the exposure time, so you can remove it from the overheads.

Fields files should have 3 columns with: <Field_name> <l(deg)> <b(deg)>

construct_layout.py

This script will create a large number of layout centers files with a standard naming convention described in the field_layouts/field_naming_convention.md README.

Run as

python construct_layout.py