1.. _applications: 2 3************ 4Applications 5************ 6 7This document briefly summarises the current applications included in the 8OSKAR package. It assumes that OSKAR has already been built and installed. 9 10Currently, there are 12 OSKAR application binaries available, listed below 11in alphabetical order. Applications that can be used to perform simulations 12with OSKAR are marked with ``*``. 13 14#. `oskar`_ ``*`` 15#. `oskar_binary_file_query`_ 16#. `oskar_fit_element_data`_ 17#. `oskar_fits_image_to_sky_model`_ 18#. `oskar_imager`_ 19#. `oskar_sim_beam_pattern`_ ``*`` 20#. `oskar_sim_interferometer`_ ``*`` 21#. `oskar_system_info`_ 22#. `oskar_vis_add`_ 23#. `oskar_vis_add_noise`_ 24#. `oskar_vis_summary`_ 25#. `oskar_vis_to_ms`_ 26 27For a description of each of these applications, please refer to their 28respective subsections. When running applications, usage syntax as 29well as some usage examples can be obtained by specifying the ``--help`` 30flag as a command line argument to the binary 31(e.g. ``oskar_sim_interferometer --help``). 32The OSKAR package version number from which the binary was built can be 33obtained for all applications by specifying the ``--version`` flag. 34 35Application binaries are built into the ``<build directory>/apps`` 36folder and installed into ``/usr/local/bin`` by default. 37 38oskar 39----- 40This application provides a simple graphical user interface that can be used 41to configure and run simulations. It can be started by optionally giving the 42name of a settings file as the first argument, as follows: 43 44 .. code-block:: bash 45 46 oskar [settings file path] 47 48oskar_binary_file_query 49----------------------- 50This utility displays a summary of the contents of an OSKAR binary file, and 51can be run using the syntax: 52 53 .. code-block:: bash 54 55 oskar_binary_file_query <binary file path> 56 57oskar_fit_element_data 58---------------------- 59This application must be used if numerically-defined element pattern data 60should be used in a simulation. It performs spline fitting to tabulated data, 61and stores the fitted coefficients to files inside the telescope model. All 62options are configured using the element fit group of the specified settings 63file. The application is run using the following syntax: 64 65 .. code-block:: bash 66 67 oskar_fit_element_data [--set] <settings file path> [key] [value] 68 69Note that this application can be configured and run via the oskar GUI 70application, described above. If required, settings files can be modified 71via the command line using the --set option, with the key and new value given 72after the path to the settings file. 73 74oskar_fits_image_to_sky_model 75----------------------------- 76This utility can be used to convert a standard radio astronomy FITS image 77(made using the orthographic projection) to an OSKAR sky model file. It takes 78the following command line syntax: 79 80 .. code-block:: bash 81 82 oskar_fits_image_to_sky_model [OPTIONS] <Input FITS file> \ 83 <Output sky model file> 84 85[OPTIONS] consists of flags to specify how much of the input image is 86converted. The downsample factor, noise floor, and minimum peak fraction can 87all be set here. 88 89oskar_imager 90------------ 91An application that can be used to make raw (dirty) FITS images or image cubes 92from visibility data stored in OSKAR binary visibility data files or 93CASA Measurement Sets. 94All options are configured in the image group of a specified OSKAR settings 95file, and the imager is run with the following syntax: 96 97 .. code-block:: bash 98 99 oskar_imager [--set] <settings file path> [key] [value] 100 101Note that this application can be configured and run via the oskar GUI 102application, described above. If required, settings files can be modified 103via the command line using the --set option, with the key and new value given 104after the path to the settings file. 105 106oskar_sim_beam_pattern 107---------------------- 108This is a command line application for simulating station beam patterns, which 109is configured by providing an OSKAR settings file as the first command line 110argument. Beam patterns produced by this application are simulated using the 111same algorithms used in the interferometry simulation. The application is run 112with the following syntax: 113 114 .. code-block:: bash 115 116 oskar_sim_beam_pattern [--set] <settings file path> [key] [value] 117 118Note that this application can be configured and run via the oskar GUI 119application, described above. If required, settings files can be modified 120via the command line using the --set option, with the key and new value given 121after the path to the settings file. 122 123oskar_sim_interferometer 124------------------------ 125This is a command line application for simulating interferometer data. 126Visibility data sets produced by the simulator are written in CASA Measurement 127Set and/or OSKAR binary visibility format. The simulation is configured using a 128variety of options, which are specified in an OSKAR settings file provided as 129the first command line argument: 130 131 .. code-block:: bash 132 133 oskar_sim_interferometer [--set] <settings file path> [key] [value] 134 135Note that this application can be configured and run via the oskar GUI 136application, described above. If required, settings files can be modified 137via the command line using the --set option, with the key and new value given 138after the path to the settings file. 139 140Parallelisation and multi-GPU usage 141""""""""""""""""""""""""""""""""""" 142Interferometer simulations operate on units of computation known as a 143visibility block. This is a unit of the final output visibility data set 144containing all baselines and all channels, but a limited number of times. 145Computation and writing of these visibility blocks is overlapped by using 146multiple CPU threads. In addition, if multiple GPUs are available and assigned 147in the simulation settings, they will cooperate on filling each visibility 148block. The division of work which results by using this scheme to simulate a 149data set on a system with two GPUs is illustrated in the figure below. 150In this illustration, after a short period of loading the simulator settings 151and input model data (marked 'Setup & load'), three threads are launched to 152perform overlapping compute and write of blocks of visibility data. 153Note that the number of threads used by the simulator will be one larger than 154the number of GPUs used for the computation. Computation within each 155visibility block is split between each of the available GPUs, and proceeds by 156sharing out independent units of the visibility block which correspond to the 157visibilities for one chunk of sources for one time. 158The size of the chunk of sources, which has an impact on the number of compute 159units shared between the GPUs, is configurable in the simulation settings. 160In order to achieve good performance, it is advisable to ensure that the 161number of source chunks multiplied by the number of times in a visibility 162block is large enough to hide any variation in compute times between the 163different compute units, while at the same time having enough sources in a 164chunk to fully occupy the GPU (i.e. several thousand sources in each chunk). 165 166.. figure:: sim_interferometer_timing.png 167 :width: 10cm 168 :align: center 169 :alt: Rotation measure definition 170 171The division of compute and write operations for a simulation running on a system with two GPUs to evaluate a number of blocks of visibility data. 172 173Interpreting timing information 174""""""""""""""""""""""""""""""" 175Upon completion of an interferometer simulation, the log will contain the 176results of a number of timers. These are the following: 177 178* **Total wall time** is the total execution time for the simulation. This 179 is a combination of the time taken in loading input data, all computation, 180 and writing the output files. Where possible, compute and write operations are 181 overlapped, so the total compute time will equal the largest of either write 182 or compute, and the balance between these will give an indication of whether 183 the simulation is limited by available computing power or filesystem 184 performance. 185* **Load** is the time taken in loading the simulation input data. This time 186 is always a contribution to the total wall time. 187* **Compute time** (displayed per GPU) is the total time taken simulating 188 visibility blocks. This is usually the dominant part of the total simulation 189 wall time, in which case the simulation performance is limited by available 190 computing power. 191* **Write time** indicates the total time taken in writing visibility 192 data files (CASA Measurement Set and/or OSKAR binary format). If the compute 193 time is larger than this value, write operations will have very little impact 194 on the overall simulation wall time. The only exception to this is writing the 195 last visibility block, which cannot overlap with any compute operations. 196 197Notable components of the simulation compute time are also listed, with 198their average percentage contribution to the total computation cost. 199 200* **Copy** represents the cost of setting up and moving data to the GPU. 201* **Horizon clip** is the process of removing sources below the horizon as 202 a function of time. 203* **Jones E** is the evaluation of the station beam pattern as a function 204 of station and source direction. 205* **Jones K** is the evaluation of the interferometric phase per station 206 and per source. 207* **Jones join** is the cost of combining individual Jones terms. 208* **Jones correlate** forms the visibility amplitudes as a function of 209 baseline (station pair), time and frequency, by collapsing the source dimension 210 of the Jones matrices after combining with the source brightness matrix. 211* **Other** is the cost of all other computing components and overheads 212 that have not been individually timed. 213 214oskar_system_info 215----------------- 216This utility displays a summary of the installed GPU hardware. 217It takes no command line arguments. 218 219oskar_vis_add 220------------- 221This application combines two or more OSKAR binary visibility files. It is 222intended for combining simulations made with different sky model components, 223so the visibility data files being combined must have been generated using 224identical telescope configurations and observation parameters (i.e. share 225common baseline coordinates, time and frequency axes). The application is 226run with the following syntax: 227 228 .. code-block:: bash 229 230 oskar_vis_add [OPTIONS] <OSKAR visibility files...> 231 232[OPTIONS] consists of flags for specifying the output (combined) visibility 233data file name, and a flag for suppressing log messages. 234 235oskar_vis_add_noise 236------------------- 237This application adds noise to the specified OSKAR binary visibility file(s). 238The noise to be added is configured according to the noise settings found in 239the interferometer group of the provided OSKAR simulation settings file (for 240details of these settings please refer to the OSKAR Settings documentation). 241The application is run with the following syntax: 242 243 .. code-block:: bash 244 245 oskar_vis_add_noise [OPTIONS] <OSKAR visibility files...> 246 247[OPTIONS] consists of flags for specifying the settings file in which the 248noise parameters are defined, whether noise should be added in-place or to a 249copy of the input visibility file(s), and a flag to enable verbose output. 250 251oskar_vis_summary 252----------------- 253This application prints a summary of the data contained within an OSKAR 254visibility binary file. The application is run with the following syntax: 255 256 .. code-block:: bash 257 258 oskar_vis_summary [OPTIONS] <OSKAR visibility files...> 259 260[OPTIONS] consists of flags to display the settings used to generate the 261visibility file and the run log generated during the simulation. 262 263oskar_vis_to_ms 264--------------- 265This application can be used to convert one or more OSKAR visibility binary 266file(s) to Measurement Set format. If more than one input OSKAR visibility 267file is provided, they are concatenated. The application is run with the 268following syntax: 269 270 .. code-block:: bash 271 272 oskar_vis_to_ms [OPTIONS] <OSKAR visibility files...> 273
