roman_pointing package

Submodules

roman_pointing.roman_observability module

roman_pointing.roman_observability.compute_keepout(coords_dict, start_date, days, time_step, min_sun=54, max_sun=126)

Determine observability windows for multiple targets based on solar constraints.

Calculates when targets are observable by Roman Space Telescope based on solar exclusion angle limits. The allowed solar angle range avoids thermal and stray light issues while keeping the solar panels properly oriented (default: 54-126 degrees).

Parameters:

• coords_dict (dict) – Dictionary mapping target names (str) to SkyCoord objects.

• start_date (str) – Start date in ISO format (e.g., ‘2027-01-01T00:00:00’).

• days (int or float) – Duration of observation window in days.

• time_step (int or float) – Time interval between calculations in days.

• min_sun (int or float, optional) – Minimum allowed solar angle in degrees. Default: 54.

• max_sun (int or float, optional) – Maximum allowed solar angle in degrees. Default: 126.

Returns:

A tuple containing:

• ts_global (astropy.time.Time): Array of time values

• keepout (dict): Dictionary mapping target names to boolean arrays indicating observability (True = observable, False = in keepout zone)

• solar_angles (dict): Dictionary mapping target names to solar angle arrays in degrees

Return type:

tuple

roman_pointing.roman_observability.compute_roman_angles(coord, start_date, days, time_step)

Calculate Roman Space Telescope pointing angles for a target over time.

Computes the solar angle, yaw, and pitch angles required for Roman to observe a given celestial coordinate over a specified time period, accounting for the telescope’s position at the Sun-Earth L2 Lagrange point.

Parameters:

• coord (astropy.coordinates.SkyCoord) – Target celestial coordinates in BarycentricMeanEcliptic frame.

• start_date (str) – Start date in ISO format (e.g., ‘2027-01-01T00:00:00’).

• days (int or float) – Duration of observation window in days.

• time_step (int or float) – Time interval between calculations in days.

Returns:

A tuple containing:

• ts (astropy.time.Time): Array of time values

• sun_ang (astropy.units.Quantity): Solar angles in degrees

• yaw (astropy.units.Quantity): Yaw angles in degrees

• pitch (astropy.units.Quantity): Pitch angles in degrees

Return type:

tuple

roman_pointing.roman_observability.compute_visibility_fraction(keepout_dict)

Calculate the percentage of time each target is observable.

Computes the fraction of the observation period during which each target falls within the allowed solar angle range (54-126 degrees) and is therefore observable by the Roman Space Telescope.

Parameters:

keepout_dict (dict) – Dictionary mapping target names (str) to boolean arrays where True indicates the target is observable and False indicates it is in a keepout zone.

Returns:

Dictionary mapping target names (str) to visibility percentages

(float), representing the fraction of time the target is observable expressed as a percentage (0-100).

Return type:

dict

roman_pointing.roman_observability.create_download_button(csv_string, filename='roman_keepout_data.csv')

Create browser download button for CSV data.

Generates an HTML download link that triggers the browser’s native download dialog when clicked. The CSV data is base64-encoded and embedded directly in the link’s data URI.

Parameters:

• csv_string (str) – CSV-formatted data string to be downloaded.

• filename (str, optional) – Desired filename for the downloaded file. Defaults to ‘roman_keepout_data.csv’. The .csv extension is automatically added if not present.

Returns:

HTML object containing a styled download button

that triggers browser download when clicked.

Return type:

IPython.display.HTML

Note

The button uses HTML5’s download attribute with a data URI. This works in all modern browsers (Chrome, Firefox, Edge, Safari) and allows users to save the file anywhere on their system.

roman_pointing.roman_observability.generate_csv(ts, keepout_dict, solar_angles_dict, pitch_dict, visibility_dict)

Generate CSV file containing complete observability analysis data.

Creates a CSV-formatted string with metadata header, visibility summary, and time-series data for all targets. Suitable for further analysis in spreadsheet applications or data science tools.

Parameters:

• ts (astropy.time.Time) – Array of time samples.

• keepout_dict (dict) – Maps target names to boolean observability arrays.

• solar_angles_dict (dict) – Maps target names to solar angle arrays.

• pitch_dict (dict) – Maps target names to pitch angle arrays.

• visibility_dict (dict) – Maps target names to visibility percentages.

Returns:

CSV-formatted string with the following structure:

• Header lines (starting with #) containing:

  • Start and end dates

  • Time step size

  • Visibility percentages for each target

• Column headers

• Data rows with one row per time step

Return type:

str

CSV Columns:

• Date: ISO 8601 timestamp

• Days_from_Start: Decimal days since start_date

• For each target:

  • {Target}_Solar_Angle_deg: Solar angle in degrees (4 decimal places)

  • {Target}_Pitch_Angle_deg: Pitch angle in degrees (4 decimal places)

  • {Target}_Observable: Binary flag (1 = observable, 0 = not observable)

roman_pointing.roman_observability.get_target_coords(target_names)

Query SIMBAD for astronomical target coordinates and proper motions.

Retrieves celestial coordinates, parallax, proper motion, and radial velocity data from SIMBAD database for specified astronomical objects. Transforms coordinates to Barycentric Mean Ecliptic frame for Roman Space Telescope pointing calculations.

Parameters:

target_names (list of str) – List of astronomical object names recognizable by SIMBAD (e.g., ‘Proxima Cen’, ‘Sirius’, ‘Betelgeuse’). Target names containing ‘bulge’ will use hardcoded galactic bulge coordinates.

Returns:

Dictionary mapping target names (str) to astropy SkyCoord objects in

BarycentricMeanEcliptic frame. Targets not found in SIMBAD are excluded from the returned dictionary.

Return type:

dict

Note

This function prints a message to stdout when a target cannot be found in SIMBAD. Special handling exists for galactic bulge targets. Any missing proper motion/radial velocity data will be set to 0

roman_pointing.roman_observability.launch_ui()

Launch interactive Jupyter widget interface for Roman keepout analysis.

Creates and displays a comprehensive user interface for analyzing Roman Space Telescope target observability. The interface includes:

• Target input field for SIMBAD-recognized astronomical objects

• Date range and time step configuration

• Preset target collections (bright stars, exoplanet hosts)

• Collapsible help documentation

• Real-time visualization generation

• CSV download functionality

The UI generates three plots when “Generate Maps & Plots” is clicked: 1. Keepout map showing observability windows for all targets 2. Solar angle evolution over time (with transition markers for single targets) 3. Pitch angle requirements over time

Additionally displays visibility statistics showing the percentage of time each target is observable during the specified observation period.

Interface Components:

• Target Input: Multi-line text area for entering target names (one per line)

• Preset Buttons: Quick-load curated lists of 40 bright stars or 25 exoplanet hosts

• Start Date: ISO 8601 formatted date/time (YYYY-MM-DDTHH:MM:SS)

• Days Slider: Analysis duration (1-730 days, up to 2 years)

• Time Step Slider: Calculation interval (1-10 days)

• CSV Filename: Customizable output filename

• Generate Maps & Plots: Creates visualizations and downloadable CSV

• Generate CSV Only: Skips plotting for faster data export

• Help Toggle: Shows/hides detailed usage instructions

Requirements:

• Must be run in a Jupyter notebook environment

• Requires ipywidgets for the interface

• Requires matplotlib for plotting

• Requires astropy and astroquery for astronomical calculations

• Requires roman_pointing library for telescope angle calculations

Returns:

Displays the widget interface directly in the notebook output.

Return type:

None

Note

• Single-target analysis provides detailed window transition dates

• Multi-target analysis shows comparative observability across all targets

• SIMBAD queries may take several seconds for multiple targets

• Processing time scales with (number of targets) × (days / time_step)

roman_pointing.roman_observability.plot_keepout(keepout_dict, ts)

Create a visibility map showing when targets are observable.

Generates a color-coded heatmap displaying observability windows for one or more targets over time. Observable periods are shown in green, while keepout periods are shown in black. For single-target analysis, the x-axis ticks are positioned at transition points between observable and non-observable states.

Parameters:

• keepout_dict (dict) – Dictionary mapping target names (str) to boolean arrays where True indicates the target is observable and False indicates it is in a keepout zone.

• ts (astropy.time.Time) – Array of time values corresponding to the keepout data points.

Returns:

A tuple containing:

• fig (matplotlib.figure.Figure): The figure object

• ax (matplotlib.axes.Axes): The axes object

Return type:

tuple

Note

For single targets, close transitions are slightly extended in the x-axis tick positioning to prevent label overlap. Font size is automatically adjusted based on tick density. Labels may be staggered vertically when spacing is less than 20 days.

roman_pointing.roman_observability.plot_pitch(ts, pitch_dict)

Plot spacecraft pitch angle requirements for target observation.

Creates a line plot showing the pitch angle Roman must maintain to observe each target over time. Pitch angle represents the spacecraft’s orientation relative to its reference frame.

Parameters:

• ts (astropy.time.Time) – Array of time samples.

• pitch_dict (dict) – Maps target names (str) to arrays of pitch angles (astropy.units.Quantity in degrees).

Returns:

Two-element tuple containing:

• fig (matplotlib.figure.Figure): Figure object

• ax (matplotlib.axes.Axes): Axes object

Return type:

tuple

Note

• Different targets may require significantly different pitch angles

• Useful for understanding spacecraft slew requirements between targets

roman_pointing.roman_observability.plot_solar_angle(ts, solar_angles_dict)

Plot solar angle evolution for multiple targets over time.

Creates a line plot showing how the Sun-target angle changes over the observation period for each target. Includes visual indicators for Roman’s 54° and 126° solar angle constraints (keepout zone boundaries).

Parameters:

• ts (astropy.time.Time) – Array of time samples.

• solar_angles_dict (dict) – Maps target names (str) to arrays of solar angles (astropy.units.Quantity in degrees).

Returns:

Two-element tuple containing:

• fig (matplotlib.figure.Figure): Figure object

• ax (matplotlib.axes.Axes): Axes object

Return type:

tuple

Note

• Regions below 54° and above 126° are hatched to indicate keepout zones

• Each target is plotted with a different color and labeled in the legend

• X-axis labels are auto-formatted and rotated for readability

roman_pointing.roman_observability.plot_solar_angle_with_windows(ts, solar_angles_dict, keepout_dict)

Plot solar angle with vertical lines marking observability transitions.

Creates a detailed plot for a single target showing solar angle evolution with red vertical lines indicating exact dates when the target enters or exits Roman’s observable zone. Optimized for single-target analysis.

Parameters:

• ts (astropy.time.Time) – Array of time samples.

• solar_angles_dict (dict) – Single-entry dict mapping target name to solar angles.

• keepout_dict (dict) – Single-entry dict mapping target name to boolean observability array.

Returns:

Two-element tuple containing:

• fig (matplotlib.figure.Figure): Figure object

• ax (matplotlib.axes.Axes): Axes object

Return type:

tuple

Raises:

ValueError – If solar_angles_dict contains more than one target.

Note

• Red dotted lines mark transitions between observable/unobservable states

• X-axis ticks are positioned at transition dates for precise identification

• Includes 5% padding on time axis for better visualization

roman_pointing.roman_observability.print_visibility_windows(ts, keepout_dict)

Print formatted list of observability windows for a single target.

Displays start and end dates for each continuous observability window, along with the duration of each window. Only processes single-target keepout dictionaries; returns silently for multiple targets.

Parameters:

• ts (astropy.time.Time) – Array of time samples.

• keepout_dict (dict) – Single-entry dict mapping target name to boolean observability array.

Returns:

Prints formatted output directly to console.

Return type:

None

Note

• If target is always observable, prints single continuous window

• If target is never observable, prints unavailability message

• Durations calculated in days with one decimal place precision

roman_pointing.roman_pointing module

roman_pointing.roman_pointing.applyRollAngle(B_C_I, roll_angles)

Apply roll angles to the spacecraft body-centered inertial frame

Parameters:

• B_C_I (numpy.ndarray(float)) – Matrix of spacecraft body-centered unit vectors in the inertial reference frame. Should have dimension 3x3xn where n is the number of time steps. The last axis represents time. Typically computed by calcRomanAngles().

• roll_angles (numpy.ndarray(float) or astropy.units.Quantity) – Roll angles to apply at each time step. Should have length n matching the time dimension of B_C_I. Roll is rotation about the b_1 body axis.

Returns:

Updated 3x3xn matrix of body-centered unit vectors after applying roll

Return type:

numpy.ndarray(float)

roman_pointing.roman_pointing.calcRomanAngles(target, ts, r_obs_G, r_sun_G=None)

Compute Roman’s pointing and sun angles for a particular target

Parameters:

• target (astropy.coordinates.SkyCoord) – Target coordinates

• ts (astropy.time.Time) – Observation time(s) - can be an array of times

• r_obs_G (astropy.unitsQuantity(numpy.ndarray(float))) – Observatory position wrt solar system barycenter for each observation time. Should have dimension 3xn where n is the size of ts.

• r_sun_G (astropy.unitsQuantity(numpy.ndarray(float)), optional) – Sun position wrt solar system barycenter for each observation time. Should have dimension 3xn where n is the size of ts. If None, will be computed automatically

Returns:

sun_ang, yaw, pitch, B_C_I

Return type:

tuple

roman_pointing.roman_pointing.f(x, mustar)

roman_pointing.roman_pointing.fsunearth(x)

roman_pointing.roman_pointing.getEXCAMPositionAngle(B_C_I)

roman_pointing.roman_pointing.getL2Positions(ts)

Retrieve the barycentric position of L2 for given observing times

Parameters:

ts (astropy.time.Time) – Observation time(s) - can be an array of times

Returns:

3xn array of approximate L2 barycentric positions where n is the size of ts

Return type:

numpy.ndarray(float)

roman_pointing.roman_pointing.getRomanPositionAngle(B_C_I)

Compute the position angle of the Roman observatory +Z axis (b_3 body vector)

with respect to celestial North, projected onto the instrument focal plane.

Parameters:

B_C_I (numpy.ndarray(float)) – Matrix of spacecraft body-centered unit vectors in the inertial reference frame. Should have dimension 3x3xn where n is the number of time steps. The last axis represents time. Typically computed by calcRomanAngles().

Returns:

Array of position angles at each time. Position angle is measured counter-clockwise from celestial North to the observatory +Z (b_3 body vector) axis.

Return type:

astropy.units.Quantity(numpy.ndarray(float))

roman_pointing.roman_pointing.getSunPositions(ts)

Retrieve the barycentric position of the sun for given observing times

Parameters:

ts (astropy.time.Time) – Observation time(s) - can be an array of times

Returns:

3xn array of sun barycentric positions where n is the size of ts

Return type:

numpy.ndarray(float)

Module contents