:orphan: :mod:`astrohack.cassegrain_ray_tracing` ======================================= .. py:module:: astrohack.cassegrain_ray_tracing Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: astrohack.cassegrain_ray_tracing.create_ray_tracing_telescope_parameter_dict astrohack.cassegrain_ray_tracing.cassegrain_ray_tracing_pipeline astrohack.cassegrain_ray_tracing.plot_2d_maps_from_rt_xds astrohack.cassegrain_ray_tracing.plot_radial_projection_from_rt_xds astrohack.cassegrain_ray_tracing.apply_holog_phase_fitting_to_rt_xds .. function:: create_ray_tracing_telescope_parameter_dict(primary_diameter: Union[float, int] = 25, secondary_diameter: Union[float, int] = 2.5146, focal_length: Union[float, int] = 9.0, z_intercept: Union[float, int] = 3.14, foci_half_distance: Union[float, int] = 3.662, inner_radius: Union[float, int] = 2.0, horn_diameter: Union[float, int] = 0.2, length_unit: str = 'm') Create a dictionary with a cassegrain telescope parameters :param primary_diameter: Diameter of the primary mirror. :type primary_diameter: float, int, optional :param secondary_diameter: Diameter of the secondary mirror. :type secondary_diameter: float, int, optional :param focal_length: Focal length of the primary mirror. :type focal_length: float, int, optional :param z_intercept: Distance between the Z intercept of the secondary and the mid-point between the primary and secondary focus, usually refered to as 'a'. :type z_intercept: float, int, optional :param foci_half_distance: Half-distance between the primary and secondary foci, usually refered to as 'c'. :type foci_half_distance: float, int, optional :param inner_radius: Inner valid surface radius of the primary reflector, usually refered to as Blockage. :type inner_radius: float, int, optional :param horn_diameter: Diameter of the horn detecting the signals, used to determine if rays are detected or lost. :type horn_diameter: float, int, optional :param length_unit: Unit for the telescope dimensions, default is "m". :type length_unit: str, optional :return: A dictionary filled with the user inputs and also the horn position and orientation. :rtype: dict .. _Description: Create a basic description of a Cassegrain radio telescope from user inputs. This function assumes that the horn is positioned at the secondary focus and is pointed directly upwards, i.e. an axi-symmetric design. Default values reflect the values for the VLA available in EVLA memo 211. .. function:: cassegrain_ray_tracing_pipeline(output_xds_filename: str, telescope_parameters: dict, grid_size: Union[float, int] = 28, grid_resolution: Union[float, int] = 0.1, grid_unit: str = 'm', x_pointing_offset: Union[float, int] = 0, y_pointing_offset: Union[float, int] = 0, pointing_offset_unit: str = 'asec', x_focus_offset: Union[float, int] = 0, y_focus_offset: Union[float, int] = 0, z_focus_offset: Union[float, int] = 0, focus_offset_unit: str = 'mm', phase_offset: Union[float, int] = 0, phase_unit: str = 'deg', observing_wavelength: Union[float, int] = 1, wavelength_unit: str = 'cm', overwrite: bool = False) Execute the cassegrain ray tracing pipeline to determine phase effects caused by optical mis-alignments. :param output_xds_filename: Filename for the output Xarray dataset on disk using a Zarr container. :type output_xds_filename: str :param telescope_parameters: Dictionary containing the parameters of the cassegrain telescope in use. :type telescope_parameters: dict :param grid_size: Size of the grid onto which to compute phase effects in grid_unit. :type grid_size: float, int, optional :param grid_resolution: Resolution of the grid onto which to compute phase effects in grid_unit. :type grid_resolution: float, int, optional :param grid_unit: Length unit for grid_size and grid_resolution, default is "m". :type grid_unit: str, optional :param x_pointing_offset: X Pointing offset in pointing_offset_unit. :type x_pointing_offset: float, int, optional :param y_pointing_offset: Y Pointing offset in pointing_offset_unit. :type y_pointing_offset: float, int, optional :param pointing_offset_unit: Angle unit for pointing offsets, default is "asec". :type pointing_offset_unit: str, optional :param x_focus_offset: X offset of the secondary in focus_offset_unit. :type x_focus_offset: float, int, optional :param y_focus_offset: Y offset of the secondary in focus_offset_unit. :type y_focus_offset: float, int, optional :param z_focus_offset: Z offset of the secondary in focus_offset_unit, what is usually refered to as simply focus. :type z_focus_offset: float, int, optional :param focus_offset_unit: Length unit for focus offsets, default is "mm". :type focus_offset_unit: str, optional :param phase_offset: A phase offset to be applied to the phase image. :type phase_offset: float, int, optional :param phase_unit: Angle unit for the phase offset, default is "deg". :type phase_unit: str, optional :param observing_wavelength: Wavelength of the rays to be simulated in wavelength unit. :type observing_wavelength: float, int, optional :param wavelength_unit: Length unit for the observing wavelength, default is "cm". :type wavelength_unit: str, optional :param overwrite: Overwrite rt_xds file on disk, default is False. :type overwrite: bool, optional :return: X array dataset object with the results from the ray tracing. :rtype: xr.Dataset .. _Description: Calculate the total path for rays from the moment they pass the rim of the primary dish until they are detected at the horn and computes the resulting phase. .. rubric:: Code Outline - A Gridded representation of the primary dish and the normal to its surface are created and stored in an XDS. - The reflection between the incident light and the primary mirror is computed for each of the gridded points. - The reflected rays from the primary are progated and the intercept between them and the secondary is calculated. - Compute the reflection at the secondary for each ray reflected at the primary that touches it. - Check which rays from the secondary intercept the mouth of the horn. - Compute the total path from the rim of the primary up to horn for detected rays. - Compute the phase for each ray based on the total path. .. rubric:: Limitations - This ray tracing code only aims at estimating aperture phases, not its amplitude. - Detection from sidelobes is not estimated. - Beam shape estimations cannot be computed from the results as amplitudes are not modeled. - This model is axi-symmetric, i.e. it cannot be used to estimate the full range of phase effects present in VLA apertures. - If large pointing or focus offsets are chosen the rays may stop intercepting the horn and hence produce partially or fully blank phase images. .. function:: plot_2d_maps_from_rt_xds(rt_xds_filename: str, keys: Union[str, list], rootname: str, phase_unit: str = 'deg', length_unit: str = 'm', colormap: str = 'viridis', display: bool = True, dpi: int = 300) Plot 2D maps of keys in the ray tracing Xarray Dataset :param rt_xds_filename: Name on disk of the Xarray dataset containing the results of the Ray tracing pipeline :type rt_xds_filename: str :param keys: Key or keys in rt_xds to be plotted. :type keys: str, list :param rootname: Root name for the plots to be created. :type rootname: str :param phase_unit: Unit for the phase plot, default is "deg". :type phase_unit: str, optional :param length_unit: Unit for the plots of keys other than phase, default is "m". :type length_unit: str, optional :param colormap: Colormap to be used for plots, default is "viridis". :type colormap: str, optional :param display: Display plots inline or suppress, defaults to True :type display: bool, optional :param dpi: dots per inch to be used in plots, default is 300 :type dpi: int, optional .. _Description: Produce plots from the Xarray dataset containing ray tracing results for analysis. All Xarray dataset data variables except for the x and y axes can be plotted. .. function:: plot_radial_projection_from_rt_xds(rt_xds_filename: str, plot_filename: str, nrays: int = 20, display: bool = True, dpi: int = 300) Plot a radial projection of some of the rays simulated in the ray tracing Xarray Dataset. :param rt_xds_filename: Name on disk of the Xarray dataset containing the results of the Ray tracing pipeline :type rt_xds_filename: xr.Dataset :param plot_filename: Name of the file to contain the plot. :type plot_filename: str :param nrays: Number of random rays to be plotted, default is 20. :type nrays: int, optional :param display: Display plot inline or suppress, default is True :type display: bool, optional :param dpi: dots per inch to be used in plots, default is 300 :type dpi: int, optional .. _Description: Produce a plot of a random selection of nrays that are present on the input Xarray dataset. .. function:: apply_holog_phase_fitting_to_rt_xds(rt_xds_filename: str, phase_plot_filename: str, fit_pointing_offset: bool = True, fit_xy_secondary_offset: bool = True, fit_focus_offset: bool = True, phase_unit: str = 'deg', colormap: str = 'viridis', display: bool = True, dpi: int = 300) Feed phase image from ray tracing Xarray dataset to Astrohak's default phase fitting tool for VLA data. :param rt_xds_filename: Name on disk of the Xarray dataset containing the results of the Ray tracing pipeline :type rt_xds_filename: xr.Dataset :param phase_plot_filename: filename for the plot containing the RT phase image the fitted phase effects and the residuals :type phase_plot_filename: str :param fit_pointing_offset: Toggle to determine if pointing offsets are to be fitted, default is True. :type fit_pointing_offset: bool, optional :param fit_xy_secondary_offset: Toggle to determine if lateral displacements of the secondary are to be fitted, default is True. :type fit_xy_secondary_offset: bool, optional :param fit_focus_offset: Toggle to determine if vertical displacements of the secondary are to be fitted, default is True. :type fit_focus_offset: bool, optional :param phase_unit: Unit for the phase plot, default is "deg". :type phase_unit: str, optional :param colormap: Colormap to be used for plots, default is "viridis". :type colormap: str, optional :param display: Display plots inline or suppress, defaults to True :type display: bool, optional :param dpi: dots per inch to be used in plots, default is 300 :type dpi: int, optional .. _Description: Apply the phase fitting engine used in ``astrohack.holog.holog`` to the phase image computed by the ray tracing pipeline. At the end of the fitting produces a table so that fitting results can be compared to the inputs given for the ray tracing pipeline. Along with the table a plot is produced containing the ray tracing modelled phases, the correction derived from the phase fitting tool and the residuals of the fitting. For easier comparison simple statistics of each image are provided.