docs/notebooks/introduction.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "introduction.ipynb",
      "provenance": [],
      "toc_visible": true
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "O5t-PZotJYp1"
      },
      "source": [
        "# Release Information \n",
        "\n",
        "These are the release notes for CASA 6.4. Changes compared to the [CASA 6.3 release](https://casadocs.readthedocs.io/en/v6.3.0/notebooks/introduction.html) are listed below.\n",
        "\n",
        "\n",
        "\n",
        "***\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4fHFiOpGc90G"
      },
      "source": [
        "## Highlights\n",
        "\n",
        "- **tclean:** a new *experimental* deconvolution algorithm \"Adaptive Scale Pixel\" has been added to tclean. *(CASA 6.4.4)*\n",
        "- **plotms:** improvements for changing the phasecenter on-the-fly, which now relies on absolute (rather than relative) position. *(CASA 6.4.4)*\n",
        "- **plotms:** colorization now assigns a color for each point based on unique values in a list, to ensure that the colors vary (e.g., for spw in ALMA spectral scans) *(CASA 6.4.4)*\n",
        "- **tclean:** new/unknown observatory names can now trigger the generation of Airy disk primary beams. *(CASA 6.4.4)*\n",
        "- **ft:** The componentlist tool and task ft now support models with spectral curvature. *(CASA 6.4.4)*\n",
        "- **fft:** the tool method ia.fft() now handles brightness units properly. *(CASA 6.4.4)*\n",
        "- ALMA array configuration files for Cycle-9 were added to the CASA data repository. *(CASA 6.4.4)*\n",
        "- *almahelpers.py* was removed from the almatasks package, because its functions are duplicates of those that can be found in *casarecipes*. *(CASA 6.4.4)*\n",
        "- **tclean:** now handles mixed polarization setups in imaging. *(CASA 6.4.3)* \n",
        "- **gencal:** a new caltype parameter *'jyperk'* has been added.  *(CASA 6.4.3)*\n",
        "- **flagdata:** some improvements were made, and bugs were fixed then flagging with *time* or *channel* averaging. *(CASA 6.4.3)*\n",
        "- **OS Support:** CASA now supports RedHat 8, and Mac OSX with Python 3.8, for both monolithic and modular versions. Note the Linux tarballs with different Python versions will extract to the same directory name. *(CASA 6.4.0)*\n",
        "- **plotcal/plotms:** funtionality for plotcal has been migrated to plotms, and plotcal was deprecated. *(CASA 6.4.0)*\n",
        "- **plotms:** calibration table averaging with channel selection is now supported. *(CASA 6.4.0)*\n",
        "- **fringefit:** memory usage of fringefit has been reduced, allowing larger datasets to be processed. *(CASA 6.4.0)*\n",
        "- **imhead:** updated to display microsecond precision. *(CASA 6.4.0)*\n",
        "- **caltables:** the storage of frequency meta information in caltables improved, making certain frequency-dependent calibration solutions more accurate. *(CASA 6.4.0)*\n",
        "- **sdintimaging:** now adds information to the history of produced images.  *(CASA 6.4.0)*\n",
        "- **T+dT** timerange selection improved in accuracy. *(CASA 6.4.0)*\n",
        "\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gxYrgSLDJYp2"
      },
      "source": [
        "## Release Notes\n",
        "\n",
        "**Installation and operation**\n",
        "\n",
        "- **OS Support:** CASA now supports RHEL8 for both modular and monolithic CASA.  Both modular and monolithic CASA is now supported on Mac OSX with Python 3.8.  Additional monolithic Linux and MacOS packages are now produced with Python 3.8 included. *Note that the Linux tarballs with different Python versions will extract to the same directory name.* *(CASA 6.4.0)*\n",
        "\n",
        "- **almahelpers.py:** was removed from the *almatasks* pkg because its functions are duplicates of those found in *casarecipes*. Users who depend on almatasks.tsysspwmap should use: *from casarecipes.almahelpers import tsysspwmap*  *(CASA 6.4.4)*\n",
        "\n",
        "- **ALMA config files:** ALMA array configuration files for Cycle-9 were added to the CASA data repository. The Cycle-9 configurations files are identical to those for Cycle-8. (CASA 6.4.4)\n",
        "\n",
        "\n",
        "**Information**\n",
        "\n",
        "- **imhead:** *mode='summary'* in **imhead** has been updated to display *\"Date observation\"* to microsecond precision. *mode=\"get\"*, *hdkey='obs-date'* returns value with microsecond precision. *(CASA 6.4.0)*\n",
        "\n",
        "**Import/export**\n",
        "\n",
        "- **importasdm/exportasdm:** deprecated parameters (*showversion, useversion*) were removed from the **importasdm** and **exportasdm** tasks, as well as the *sdm* tool. *(CASA 6.4.3)*\n",
        "\n",
        "**Calibration**\n",
        "\n",
        "- **gencal:** a new caltype parameter *'jyperk'* has been added. With *caltype=\"jyperk\"*, the calibration tables for ALMA Total Power observations are generated from ALMA internal Jy/K database. *(CASA 6.4.3)*\n",
        "\n",
        "- **flagdata:** input checks have been improved and it is now possible to execute complex commands with data visualization, such as *rflag+extendflags+antint+display='data'*. *(CASA 6.4.3)*  \n",
        "\n",
        "- **fringefit:** The memory usage of the **fringefit** task has been significantly reduced, allowing larger datasets to be processed. *(CASA 6.4.0)*\n",
        "\n",
        "- **caltables:** Improvements have been made in the accuracy of the frequency meta information stored in *caltables*.  This is most relevant when using *combine='spw'* among heterogeneous spws (different total bandwidths); the aggregate centroid frequency is now weighted by constituent spectral window bandwidth.  This should make use of frequency-dependent interpolation of gain solutions more accurate in these contexts, e.g., when using *interp='linearPD'*, where the *PD* part depends on this frequency value.  Calibration types which require frequency information to calculate the solutions phases (e.g. delays) will also be more accurate, in principle.  Also, the frequency meta information is now set globally according to the effective aggregate spectral window selection, and time-dependent spectral window representation in *combine='spw'* contexts will not throw and exception.  Compared to prior casa versions, which would implicitly recognize (in a single solve task execution) separate non-overlapping spectral window groups when using *combine='spw'*;  it is now necessary to specific each separate group in separate solve task executions (using *append=True*) to get each group combined and identified properly in the output caltable.  *(CASA 6.4.0)*\n",
        "\n",
        "**Imaging**\n",
        "\n",
        "- **ft/componentlist:** The *componentlist* tool now supports spectral models with \"spectral curvature\" (power log polynomial). This new spectral model is supported by the *image.fromcomponentlist()* tool method and task ft. *(CASA 6.4.4)*\n",
        "\n",
        "- **tclean:** A new **experimental** deconvolution algorithm has been added to tclean. The *'Adaptive Scale Pixel'* or *'asp'* algorithm may be invoked via the *deconvolver* parameter of tclean. An initial comparison of results, convergence profiles, and runtimes from different algorithms is provided in [an ASP Demo notebook](https://github.com/urvashirau/Simulation-in-CASA/blob/master/Multiscale_Wideband_Imaging/Sim_Asp_Demo.ipynb). *(CASA 6.4.4)*\n",
        "\n",
        "- **tclean:** A feature was addition in tclean that allows handling mixed pol setups in imaging (i.e. different SPWs or different time ranges within the same imaging run have different Corr setups). Modes tested were Stokes I, Stokes U, and Stokes IQUV, each for 9 ways of running tclean (single MS, list of MS, concat MS, partition in time vs freq), with the *standard* gridder and *specmode='mfs'*. Tests with full stokes mosaics will be done as part of a separate ongoing effort in a subsequent release. *(CASA 6.4.3)* \n",
        "\n",
        "- **sdintimaging:** sdintimaging adds itself to the history for produced images. *(CASA 6.4.0)*\n",
        "\n",
        "- **ftt:** The tool method *ia.fft()* now handles brightness units properly. In particular:\n",
        "  1. The phase image always has units of radians.\n",
        "For the other output images,\n",
        "  2. if the input image has units of Jy/beam or Jy/pixel\n",
        "(ie it is an image-plane image), the output (uv-plane) images will have units\n",
        "of Jy. In the case of the input image having a synthesized beam, the beam\n",
        "will be copied to the output images (which is important for transforming back).\n",
        "  3. If the input image has units of Jy (ie is a uv-plane image), the output\n",
        "images will have either units of Jy/beam or Jy/pixel, depending on if the\n",
        "input image has a beam or not. *(CASA 6.4.4)*\n",
        "\n",
        "\n",
        "**Analysis**\n",
        "\n",
        "- **spxfit:** writing of task parameters to the history keyword of the output images was enabled. *(CASA 6.4.4)*\n",
        "\n",
        "- **plotprofilemap:** this task now works on macOS. *(CASA 6.4.4)*\n",
        "\n",
        "\n",
        "**Visualization**\n",
        "\n",
        "- **plotprofilemap:** now works on macOS. *(CASA 6.4.4)*\n",
        "\n",
        "- **plotms:** The feature to change phasecenter on-the-fly was made more accurate (for wide fields) and is now synchronized with the phase-center rotation code used by task phaseshift. The user parameter to control this in plotms has changed from a relative offset to an absolute position specification, also to synchronize behavior between tasks. *(CASA 6.4.4)*\n",
        "\n",
        "- **plotms:** colorization now assigns a color for each point based on unique values in a list to ensure that the colors vary. This fixes the problem where spectral scans with ALMA previously rendered all spw in the same color. *(CASA 6.4.4)*\n",
        "\n",
        "\n",
        "- **plotcal/plotms:** Funtionality for the GUI-based application **plotcal** has been migrated to **plotms**, and plotcal has been deprecated in CASA 6. *(CASA 6.4.0)*\n",
        "\n",
        "- **plotms:** calibration table averaging with channel selection is now supported. *(CASA 6.4.0)*\n",
        "\n",
        "\n",
        "\n",
        "**Single Dish**\n",
        "\n",
        "- **sdutil:** Helper module sdutil.py has been refactored. As well as the general refactoring, many unused functions have been removed. *(CASA 6.4.0)*\n",
        "\n",
        "- **T+dT syntax:** Improved the accuracy of *time range* selection with *\"T+dT\"* syntax. A previous bug with handling data selection with sub-second precision has been fixed. *(CASA 6.4.0)* \n",
        "\n",
        "\n",
        "**Bug fixes**\n",
        "\n",
        "- **tclean:** a bug was fixed where in parallel mode any gridders other than AWproject were wrongly checking for the existence of the cfcache folder. *(CASA 6.4.4)*\n",
        "\n",
        "- **plotms:** channel selection with a step was fixed to select the correct number of channels in the range. *(CASA 6.4.4)*\n",
        "\n",
        "- **CTRF files:** a bug was fixed for CRTF files, which caused a seg fault when parsing a polygon region definition with a very large number of points. *(CASA 6.4.4)*\n",
        "\n",
        "- **tclean:** detection of peak residuals for edge pixels in the hogbom and mtmfs deconvolvers was fixed, and checks were added for stopping criteria before any major cycles have been run. *(CASA 6.4.4)*\n",
        "\n",
        "- **tclean:** an error was fixed that could be thrown when the mask parameter was given a very long string. *(CASA 6.4.4)*\n",
        "\n",
        "- **sdbaseline:** a bug in the *dosubtract* parameter in task sdbaseline has been fixed. An MS is no longer being created as output when *dosubtract=False*. *(CASA 6.4.4)*\n",
        "\n",
        "- **tclean:** a bug was fixed to allow new/unknown observatory names to trigger the generation of Airy disk primary beams from the antenna diameters listed in the *ANTENNA* subtable. In addition, a bug was fixed to allow the use of *vp.setpbimage()* in both float and complex formats, when specified for lists of antennas, in a vptable. A demo of these usage modes for ALMA and ngVLA can be found [here](https://github.com/urvashirau/Simulation-in-CASA/tree/master/Heterogeneous_Array_Simulation_and_Imaging) *(CASA 6.4.4)*\n",
        "\n",
        "- **fft:** for the tool method ia.fft(), a casacore-level bug was fixed in the image -> uv transform step, where if the input image did not have axis units of radians, the resulting images produced by *ia.fft()* had incorrect pixel sizes. *(CASA 6.4.4)*\n",
        "\n",
        "- **setjy:** a bug was fixed whereby in parallel mode using Multi-MS the task could return empty results instead of the expected dictionary of flux densities (this was more likely in sparse MSs, i.e., small datasets or small selections of datasets). *(CASA 6.4.3)*\n",
        "\n",
        "- **uvsub:** a bug was fixed whereby the MS history was not being updated (and a warning message was printed when trying to update the history). *(CASA 6.4.3)*\n",
        "\n",
        "- **mstransform:** an issue was fixed when running in parallel mode with MMS and using *timeaverage*, *scan* selection and *timespan='scan'* simultaneously. *(CASA 6.4.3)*\n",
        "\n",
        "- **tclean:** in CASA 6.2 and 6.3, a bug was present in tclean where under certain conditions (some restart situations) an updated or modified mask was not being taken into account when computing the peak residual required for iteration control decisions. This has been fixed in CASA 6.4.3. *(CASA 6.4.3)* \n",
        "\n",
        "- **tclean:** a bug with model saving was fixed in tclean when run in its PredictOnly mode. In CASA 6.3, if *nsigma, mask, interactive* were changed from their defaults, model prediction was erroneously skipped, even in PredictOnly mode. This has been fixed.  *(CASA 6.4.3)*\n",
        "\n",
        "- **flagdata**, with *channel* and *time* average: a bug was fixed whereby flags were being un-set when propagating the flags back to the MS (as plotms would do). After this fix, flagdata with *channel* or *time* average only adds flags to the existing set of flags, or never un-sets flags that were already set. *(CASA 6.4.3)* \n",
        "\n",
        "- **flagdata,** with *time* average: bugs were fixed in the *on-the-fly time* averaging infrastructure whereby, depending on the input MS structure, the flags were either not written for a small fraction of chunks of data, or the flags written for some chunks of data were not correct. These fixes have also enabled the usage mode of autoflag with on-the-fly averaging, writing the correct expanded flags to the original MS. *(CASA 6.4.3)*  \n",
        "\n",
        "- **importfitsidi:** A bug was fixed where the time range of the observation was calculated incorrectly if more than two FITS-IDI files were specified. *(CASA 6.4.3)*\n",
        "\n",
        "- **sdcal:** a bug was fixed where the task sdcal crashed on systems where *'en_US'* locale is not available, e.g. Ubuntu. *(CASA 6.4.3)*\n",
        "\n",
        "- **libcrypt.so.2:** Included libcrypt.so.2 in the Python 3.6 Linux packages. This fixes an import error when importing the Python module *\"crypt\"*. *(CASA 6.4.0)*\n",
        "\n",
        "- **Pipeline:** The init_pipeline.py script was being added twice to the list of scripts to be run by ipython at startup resulting in the pipeline initialization being done twice. It is now being done only once when pipeline started up is requested in config.py or on the command line. *(CASA 6.4.0)*\n",
        "\n",
        "- **tclean history:** a bug was fixed whereby **tclean** would try to write *history* to files and directories that are not tclean output images (including MSs or png files that have the same name as the *imagename* used in tclean). This would cause confusing although harmless error messages. Another bug, whereby the history of images with special characters in their prefix name (such as *'+'*) was not being updated, was also fixed. *(CASA 6.4.0)*\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0iNo4MAGJYp3"
      },
      "source": [
        "## Known Issues \n",
        "\n",
        "**Summary Most Important Issues**\n",
        "\n",
        "- **Mac OS 12:** A bug prevents the monolithic Python 3.8 version for OS 11 to open CASA 6.4.4 in OS 12. Please use the Python 3.6 version instead.\n",
        "- The **Adaptive Scale Pixel (asp)** deconvolution algorithm in **tclean** is experimental, and we welcome user [feedback](https://casa.nrao.edu/index_contact.shtml).\n",
        "-   The task **clean** is no longer being actively maintained; instead, **tclean** is now the recommended task for imaging.\n",
        "-   **CASA 6 startup** may fail on some **Mac OS** where users have set up a file system that is *case-sensitive*. \n",
        "-   There are generic problems putting multiple MSs into **tclean** that have mismatches in their shape.\n",
        "-   Wideband and widefield imaging in **tclean** are only partially validated - please use at own risk and read [wideband](synthesis_imaging.ipynb#Wide-Band-Imaging) and [widefield](synthesis_imaging.ipynb#Wide-Field-Imaging) documentation.\n",
        "-   In **tclean**, *uvtaper* does not work with *natural* weighting.\n",
        "-   When imaging large mosaics with *mosweight* in **tclean**, an error *\\\"too many open files\\\"* may occur that may require to increase the limit for open files.\n",
        "-   **stawt** may fail when the correlator integration time changes within an MS and statwt is run with timebin set to an integer value.\n",
        "-   CASA is not using *LD_LIBRARY_PATH* anymore but *CASALD_LIBRARY_PATH* to avoid confusion.      \n",
        "-   **cvel** is calculating the velocity incorrectly for ephemeris objects. We recommend to use **mstransform** or its offspring **cvel2**, although the latter should be used with care as it is not fully commissioned yet.\n",
        "-   **fixvis** uses the small angle approximation and may be incorrect for large phase shifts. Use the new task **phaseshift** instead, or use **tclean** for phase center shifts during imaging when applicable. \n",
        "-   With parallel calibration on MMS files, **fixvis** does not write out the the new MMS specified in *outputvis* correctly, hence fixvis solutions are not applied when writing to a new MMS.\n",
        "-   In **fringefit**, calibration tables created with CASA 5.5 and before cannot be used with CASA 5.6 and later.\n",
        "-   In **tclean**, defining image cubes in optical velocity in some cases is known not to work.\n",
        "-   In **tclean**, using the mosaic gridder with the default *nchan=-1* is in some cases known to produce errors.\n",
        "- Ionospheric TEC corrections are currently validated in CASA only for VLA data. \n",
        "- *ephemeris* objects are not correctly supported by *virtual model columns*.\n",
        "- In **tclean**, the combination of *specmode='cube'* and *gridder=\"awproject\"* has not been commissioned for use and may result in errors.\n",
        "\n",
        "\n",
        "### General\n",
        "\n",
        "Several issues have been encountered for CASA 6:\n",
        "\n",
        "- inp/go syntax does not reset hidden parameters to default between consecutive calls. The most notable issue occurs with the *selectdata* parameters; once set at *selectdata=True*, any associated subparameters that are changed from default (e.g., *spw*, or *field*) will remain even after re-setting to *selectdata=False*. Generally this should not matter as hidden parameters are not used. However, known exceptions exist in **tclean**, **sdintimaging**, **apparentsens**, **setjy**, **listvis**, **sdcal**, and **sdfit** where the value of hidden selection parameters does in fact matter. We are currently investigating the extent of this problem. As a workaround, users can call *default* to manually reset all their parameters.\n",
        "\n",
        "- inp/go does not work for the following tasks: msuvbin, browsetable, imview, msview, deconvolve, uvcontsub3, testconcat. Please invoke the arguments directly when running these tasks in CASA 6.\n",
        "\n",
        "### Installation\n",
        "\n",
        "- For Mac OS 12, a bug in CASA 6.4.4 causes the monolithic Python 3.8 version for OS 11 to crash on OS 12. Please use instead the Python 3.6 version of CASA 6.4.4, or a previous CASA version. This bug will be fixed in the next CASA release.\n",
        "- CASA 6 startup may fail on some Mac OS where users have set up a file system that is *case-sensitive* (as shown [here](https://support.apple.com/lt-lt/guide/disk-utility/dsku19ed921c/mac)). As a temporary work-around, please manually update the casapy script in /Applications/CASA.app/Contents/MacOS/casapy, by replacing the string \"Macos\" with \"MacOS\", which occurs in lines 36 and 39 of the casaspy script.\n",
        "- For Mac OS, the default behavior when downloading multiple versions of CASA is to call it \"CASA\\ X.app\" (i.e., including a space). However, CASA is unable to find the viewer when a space exists in the application name. The workaround is to rename the application excluding the space. \n",
        "\n",
        "- If you use a version of RHEL6 with a kernel version that is older than 2.6 you may encounter an error like:\n",
        "    \n",
        "```\n",
        "    E0324 17:24:18.576966686   27444 tcp_server_posix.cc:65]     check for SO_REUSEPORT: \n",
        "    {\"created\":\"@1585038258.576951288\",\"description\":\"OS Error\",\"errno\":92,\"file\":\n",
        "    \"src/core/lib/iomg/socket_utils_common_posix.cc\",\"file_line\":168,\"os_error\":\"Protocol \n",
        "    not available\",\"syscall\":\"setsockopt(SO_REUSEPORT)\"}\n",
        "```\n",
        "\n",
        "- NFS mounted disks\n",
        "    - It is not recommended that you run CASA (e.g. have your data) on disks that are NFS mounted. It can be done, but in some cases the files will be NFS locked and this can crash CASA or its tasks. In this case, you have to restart CASA.\n",
        "    \n",
        "    - If you receive messages like xvfb timeout you may try to clean out your /tmp folder, then restart CASA.\n",
        "\n",
        "- Python:\n",
        "    - Environment variables set for personal use may be incompatible with CASA 6, given that the CASA comes with a Python version that may be different from the one installed for regular use. It is still unclear which specific errors can occur, but one workaround solution for these types of errors is to unset *PYTHONSTARTUP* before starting casa. We are looking into possible solutions.\n",
        "\n",
        "    - Files in the current directory with the same name as ipython files will cause errors like this error that occurs when a *new.py* file exists in the current directory:    ```python\n",
        "\n",
        "```\n",
        "    AttributeError                            Traceback (most recent call last) \n",
        "    /lib/python2.7/site-packages/IPython/core/interactiveshell.pyc in enable_matplotlib(self, gui)                                                                                                             \n",
        "       2945                 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)                                            \n",
        "       2946                                                                                                                          \n",
        "    -> 2947         pt.activate_matplotlib(backend)                                                                                  \n",
        "       2948         pt.configure_inline_support(self, backend)                                                                       \n",
        "       2949                                                                                                                          \n",
        "\n",
        "    /lib/python2.7/site-packages/IPython/core/pylabtools.pyc in activate_matplotlib(backend)                                                                                                                   \n",
        "        292     matplotlib.rcParams['backend'] = backend                                                                             \n",
        "        293                                                                                                                          \n",
        "    --> 294     import matplotlib.pyplot                                                                                             \n",
        "        295     matplotlib.pyplot.switch_backend(backend)                                                                            \n",
        "        296                                                                                                                          \n",
        "\n",
        "    /lib/python2.7/site-packages/matplotlib/pyplot.py in <module>()\n",
        "         21 from matplotlib.cbook import dedent, silent_list, is_string_like, is_numlike                                  \n",
        "         22 from matplotlib import docstring                                                                              \n",
        "    ---> 23 from matplotlib.figure import Figure, figaspect                                                               \n",
        "         24 from matplotlib.backend_bases import FigureCanvasBase                                                         \n",
        "         25 from matplotlib.image import imread as _imread                                                                \n",
        "\n",
        "    /lib/python2.7/site-packages/matplotlib/figure.py in <module>()\n",
        "         16 import artist                                                                                                 \n",
        "         17 from artist import Artist, allow_rasterization                                                                \n",
        "    ---> 18 from axes import Axes, SubplotBase, subplot_class_factory                                                     \n",
        "         19 from cbook import flatten, allequal, Stack, iterable, is_string_like                                          \n",
        "         20 import _image                                                                                                 \n",
        "\n",
        "    /lib/python2.7/site-packages/matplotlib/axes.py in <module>()\n",
        "       8452                                                                                                             \n",
        "       8453 #This is provided for backward compatibility                                                               \n",
        "    -> 8454 Subplot = subplot_class_factory()                                                                           \n",
        "       8455                                                                                                             \n",
        "       8456 docstring.interpd.update(Axes=martist.kwdoc(Axes))                                                          \n",
        "```\n",
        "\n",
        "\n",
        "### Scripting\n",
        "\n",
        "- Starting CASA 6: For *\"execfile\"* calls within a script which itself is run via *\"execfile\"*, it is necessary to add *globals()* as the second argument to those *\"execfile\"* calls in order for the nested script to know about the global variables of the calling script. For example, within a script *'mainscript.py'*, calls to another script *'myscript.py'* should be written as follows: *execfile('myscript.py', globals())*.\n",
        "- There are cases where two scripts call on each other (i.e., where script \\\"a\\\" uses script \\\"b\\\" and vice versa). In casa 6, the only way to execute these scripts is by running the first script twice: \n",
        "\n",
        "```\n",
        "execfile(\"a.py\",globals())\n",
        "execfile(\"b.py\",globals())\n",
        "execfile(\"a.py\",globals())\n",
        "```\n",
        " \n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "9Z8ksWqNNU80"
      },
      "source": [
        "### statwt\n",
        "-    In some circumstances when an MS data selection is specified, *chanbin* is not equal to the default value of *spw*,  and the WEIGHT_SPECTRUM or SIGMA_SPECTRUM columns don\\'t exist, the **statwt** task may need to be run twice in order to complete successfully due to a known issue with initializing the WEIGHT_SPECTRUM and/or SIGMA_SPECTRUM columns in the code. In these circumstances, an exception will be raised with instructions to restart the task. If you are using the tool method, first close the ms tool, then reopen it using the same data set, apply the same selection, and then run **ms.statwt()**.\n",
        "\n",
        "### mstransform\n",
        "-    SPW combination (*combinespws=True*) requires that all the SPWs selected have the same number of channels.\n",
        "-    Some inconsistencies are present in CASA in the SIGMA/WEIGHT columns (and their _SPECTRUM variants) when splitting on datacolumn='data', such as: \n",
        "    -    For an MS with WEIGHT_SPECTRUM but no SIGMA_SPECTRUM (as obtained from initweights), SIGMA_SPECTRUM is created and initialized to SIGMA. While split/mstransform correctly initializes the output WEIGHT to 1/SIGMA^2, it does not initialize the output WEIGHT_SPECTRUM to 1/SIGMA_SPECTRUM^2 (instead it copies the original WEIGHT_SPECTRUM).\n",
        "    -    For an MS with both WEIGHT_SPECTRUM and SIGMA_SPECTRUM, the output WEIGHT_SPECTRUM is again a copy of the input instead of being initialized to 1/SIGMA_SPECTRUM^2.\n",
        "\n",
        "    Future work in CASA is planned to address such inconsistencies. \n",
        "\n",
        "### cvel\n",
        "-    **cvel** is calculating the velocity incorrectly for ephemeris objects. We recommend to use **mstransform** or its offspring **cvel2**, although the latter should be used with care as it is not fully commissioned yet.\n",
        "-    **cvel** fails on MMS files used for parallel processing. We recommend to use **mstransform** or its offspring **cvel2**, although the latter should be used with care as it is not fully commissioned yet.\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zHZ31YzPJYp4"
      },
      "source": [
        "### bandpass\n",
        "-    Currently, **bandpass** will not find good solutions if any correlation (including cross-correlation) in the data is completely flagged. As an interim solution one may split the unflagged data in a separate file and then perform **bandpass**\n",
        "\n",
        "### polcal\n",
        "-    Polarization position angle calibration *poltype='X'* or *'Xf'* will be sensitive to any unmodelled position shift in the specified calibrator linear polarization model relative to the centroid location of total intensity (typically the phase center).  Excess phase due to the position shift will introduce a bias in the cross-hand phase calibration (which is the same as position angle calibration in the circular feed basis).   For this reason, it is best to use truly point-like (in all polarizations) calibrators, if possible, or accurate resolved models.\n",
        "\n",
        "### setjy\n",
        "-    Sometimes **setjy** does not properly overwrite a current model in the header of the ms (virtual scratch column). It is recommended to use **delmod** if a model exists and shall be overwritten.\n",
        "\n",
        "    -    *virtual model columns* in the MS do not correctly support *ephemeris* objects, although they will run without generating errors or warnings. If any of your calibrators exhibit significant celestial motion on the timescale of your observation (e.g. , any solar system object), you must set *'usescratch=True'* in calls to **setjy()**.\n",
        "\n",
        "### uvcontsub\n",
        "-    *fitorder* should be kept low (\\<= 1) unless the line band is relatively narrow compared to the fit bands. If the image rms markedly rises in the middle line channels after **uvcontsub**, fito*rder* should probably be lowered.\n",
        "-    *fitorder* \\> 0 does not work with *solint* \\> \\'int\\'\n",
        "\n",
        "### cal library\n",
        "-    The CASA cal library (*docallib=True* in **applycal**, **gaincal**, **bandpass**, etc.) may exhibit problems when calibration is unavailable for a subset of MS spectral windows.  Use of *spwmap* to (transparently, harmless) supply nominal calibration for these spectral windows may help avoid this problem.  For antenna position corrections, try *spwmap*=\\[0\\] to relieve a variety of this problem.\n",
        "\n",
        "### VLA Switched Power\n",
        "-    In CASA v4.2.2 and higher, the weight calibration for EVLA switched power/Tsys corrections is still being investigated. Visibility corrections are ok. Since switched power calibration is not used by the EVLA pipeline (except for requantizer gain corrections, for which this problem is irrelevant), and since *calwt=F* remains the general recommendation, users should rely on **statwt** to generate appropriate data weights.\n",
        "\n",
        "### fringefit\n",
        "-    For task **fringefit**, calibration tables created with CASA 5.5 and before cannot be applied with CASA 5.6 and later. Attempting to do so will fail with an error about non-confirming array sizes.\n",
        "\n",
        "### fixvis\n",
        "-     **fixvis** uses the small angle approximation and may be incorrect for large phase shifts. This may result in sources shifting position if large phase shifts are being applied (shifts up to a few beam sizes have been reported). Please use the new task **phaseshift** instead, or use **tclean** for phase center shifts during imaging when applicable. \n",
        "-    With parallel calibration on multi-MS (MMS) files, **fixvis** does not write out the *outputvis* correctly, hence fixvis solutions are not applied when writing to a new MMS. The recommended work-around solution is to over-write the input MMS by leaving the *outputvis* parameter empty. This will change the input MMS, so if you are concerned about that, we recommend to make a copy before running fixvis in parallel mode. Writing output MS files in serial mode is not affected by this bug.\n",
        "\n",
        "### tec_map\n",
        "-     Ionospheric TEC corrections in CASA are currently validated only for the VLA. TEC corrections for other observatories are experimental and should be done at your own discretion.\n",
        "-     Do not use CASA 6.1.0 for tec_map corrections.\n",
        "\n",
        "### fixplanets\n",
        "-    To supply JPL-Horizons ephemeris data, a query function, which construct an email query request, can be used but it is only available to CASA 5.8. Constructing a query request manually via email as described in the **fixplanets** task section should still work for CASA 6.3 as long as the data file is saved in MIME format. An alternative function to query for ephemeris data via JPL-Horizons web interface and CASA readable format directly is planned for the future releases.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Ws5ABCMuJYp5"
      },
      "source": [
        "### tclean\n",
        "-    In **tclean**, the *uvtaper* parameter does not work with *natural* weighting in CASA 5.8/6.2 and later. As a workaround solution, please approach the desired outcome by using *uvtaper* with *briggs* weighting and *robust=+2*, or use CASA 5.6.\n",
        "\n",
        "- For the experimental *'Adaptive Scale Pixel (asp)'* deconvolution algorithm in **tclean**:\n",
        "    - This algorithm implementation is experimental and has had limited testing. We are currently investigating some intermittent failures on some flavors of Mac OSX. We have follow-up development and test efforts, and encourage users to provide [feedback](https://casa.nrao.edu/index_contact.shtml) on what they find.\n",
        "    -  3rd party code used for the core optimization (lbfgs) is known to produce different numerical results depending on the compiler/build options. We have tested this on all CASA's supported platforms for the use cases included in our [characterization demo](https://github.com/urvashirau/Simulation-in-CASA/blob/master/Multiscale_Wideband_Imaging/Sim_Asp_Demo.ipynb) and for these tests the results are scientifically equivalent.\n",
        "\n",
        "-    Generic problems putting multiple MSs into **tclean** that have mismatches in their shape: Recently, generic problems have been found with putting multiple MSs into **tclean** when there are mismatches in shape across the data set. For example, certain data columns may cause a segment fault if they are present in only some of the input data sets. And for mosaics, please specify the phasecenter explicitly, otherwise tclean will select the first pointing from the first MS. Other mismatches in shape across multiple input MSs may cause similar problem in tclean. The CASA team is in the process of coherently addressing these issues for CASA 5.8/6.2. Please contact the [Helpdesk](https://casa.nrao.edu/../help_desk_all.shtml) if you experience related issues that you cannot otherwise solve.\n",
        "\n",
        "-    The *gridder='awproject'* has not been fully commisisoned for use with *specmode='cube'* in **tclean**.  The following message appears: *The gridder='awproject' has not been fully tested for 'cube' imaging (parallel=True or False). Formal commissioning of this mode is expected in a subsequent release, where 'awproject' will be aligned with recent framework changes.* Until then, please report errors/crashes if seen.\n",
        "\n",
        "-    In **tclean**, if *gridder='awproject'* is run with *psterm=True*, the output Primary Beam currently still includes the Prolate Spheroidal function. In order to do a primary beam correction, a separate PB needs to be made with *psterm=False*. See the CASA pages on [AWproject](synthesis_imaging.ipynb#Wide-Field-Imaging) for more information.\n",
        "    \n",
        "-    For widefield imaging in **tclean**, the following features still need to implemented and commissioned (for *usepointing=True*, with full heterogenous pointing support):\n",
        "    -    *gridder='mosaic'* : Enable accurate pointing corrections for baselines with antennas pointing in different directions\n",
        "\n",
        "-    In **tclean**, the gridders *'mosaic'* and *'awproject'* include aperture illumination functions in the gridding convolution functions used for the PSF generation.  Although this strictly follows the math, it has several undesirable features especially in the situation where data are not uniform across all axes across which they are being combined (i.e. if the mosaic pattern is not relatively flat, if the center of the image has no mosaic pointing, if different pointings have drastically different uv-coverages or frequency coverages). All such variations cause the PSFs to be position-dependent and could relate to potential instabilities during deconvolution, either requiring many major cycles to converge or diverging.  For spectral-cube imaging, the effects are lower because PSFs are normalized to peak 1 no matter what their raw peak values are. For multi-term imaging, the ratios between the spectral PSF central values matter and the effect/error is enhanved. When all these uv-coverage variations are avoided (in careful simulations), both algorithms perform as expected for joint wideband mosaics (both with *conjbeams=True* or *False*). For CASA 6.3, the guidelines are:    \n",
        "    -    For the standard gridder, full-field, single pointing imaging (spectral cube as well as multi-term) will be accurate as long as the image phase center matches the PB pointing center.  \n",
        "    -    For multi-term wideband joint mosaics, we recommend the use of *gridder=\\'awproject\\'* with *conjbeams=True* as that is the only combination that has demonstrated accurate wideband pb-correction (at *niter=0*) especially in the presence of position-dependent uv-coverage. All other options will need monitoring and several major cycles to ensure convergence.  The image should ideally be centered on a PB center.\n",
        "-    In **tclean**, the mosweight parameter for multi-field imaging has a new default value of *mosweight=True* as of CASA 5.4. The new default setting of *mosweight=True* in tclean optimizes noise characteristics for Briggs/uniform weighting, but one should be aware that it has the following disadvantages:\n",
        "    -    it may potentially cause memory issues for large VLA mosaics\n",
        "    -    the major and minor axis of the synthesized beam may be up to \\~10% larger than with *mosweight=False*\n",
        "    -    Please change to *mosweight=False* to get around these issues.\n",
        "\n",
        "-    When imaging mosaics with a large number of fields and many MSs in **tclean**, an error can occur that specifies *too many open files*. This can happen for both manual and pipeline imaging when using the *mosweight=True* parameter. The reason is that in CASA 5.5, a trade-off was made to reduce memory demands in tclean when using mosweight, by placing the weights on disk using multiple files. Unfortunately, this memory fix may cause open file problems for data sets consisting of many MSs and fields. The problem has been characterized based on the number of MSs and fields: with respect to earlier CASA releases, the imager code now uses *#MSs x #fields x 2* additional files. In CASA 6.2 and 6.3, the number of open files required for the default *perchanweightdensity=True* case has been dramatically reduced, though *perchanweightdensity=False* imaging runs are more limited. While the CASA team is working on a permanent solution for future CASA versions, the recommended work-around solution is to manually increase the limit for the number of open files, e.g.: *ulimit -Sn 8000* or *ulimit -Sn 16000*. In some cases, increasing the hard-limit on number of open files may be necessary, which requires admin/root permissions. As a rule of thumb, each MS requires ~54 simultaneously open files. With a 16k limit and a maximum of 150 fields per MS, for a use case with *perchanweightdensity=False*, *mosweight=True* tclean will encounter too many open files with ~46 MSs or more, while with *perchanweightdensity=True*, *mosweight=True* tclean will encounter too many open files with ~300 MSs or more. \n",
        "\n",
        "-    There are small, systematic offsets known to occur when using **tclean**. Our initial tests show that the offset in dec is of the order \\~50 milli-arcsec, while the offset in RA is a function of declination, but also amounting to \\~50mas. This issue is currectly being investigated.\n",
        "\n",
        "-    Currently the parameter type of *niter* is defined as an integer, therefore the integer value larger than 2147483647 will not be set properly as it causes an overflow.\n",
        "\n",
        "-    Using *deconvolver='mtmfs'*, *nterms=1* and *specmode=cube* does not yet work in parallel imaging mode. Use *specmode='mfs'* instead.\n",
        "\n",
        "-    In **tclean**, defining image cubes in optical velocity in some cases is known not to work. This problem is under investigation.\n",
        "    \n",
        "-    The *awproject* gridder in **tclean** does not support the virtual model scheme.\n",
        "    \n",
        "-    Interactive **tclean** only works when a region or mask is selected in the CASA Viewer. There is a known bug that when a region is first selected, and then de-selected to produce an empty mask (filled with zeros), the CASA Viewer that runs interactive tclean will still allow you to proceed, and tclean will detect an empty mask and stop. Please always mark a region/mask to continue interactive tclean (if the entire image should be cleaned, draw a box around the entire image), and do not forget to double-click inside the green contours to select the region.\n",
        "    \n",
        "-    When using interactive **tclean**, hand-edited cyclethresholds do not change back to the auto-calculated values in the GUI until two major cycles later. However, the logger contains the most accurate information about what was used, and the expected behaviour (of hand-edited cyclethresholds applying to only the current minor cycles) is seen and has been tested. Therefore, iteration control and imaging will proceed as expected. This known issue affects CASA versions 5.6 and 5.7/6.1\n",
        "    \n",
        "-    For imaging of cubes using the *mosaic* gridder, a seg-fault can be triggered if the default *nchan=-1* is used and channel selection is set with *spw*. This can result in either a seg-fault, or image planes with NaN values. It is not yet clear what is the root cause of this issue. The problem was found in VLA data, but it is not clear whether it can affect data from other telescopes. We expect this problem to be fixed in CASA 6.3. As a work-around solution, we recommend to set the *nchan* parameter to anything different than -1.        \n",
        "    \n",
        "-    In the **makemask** task, region files using the minus sign ( - ) to create cutouts are known not to work.\n",
        "\n",
        "-    The combined imaging of different large MSs where differences in the topo-centric frequencies are large compared to the channel width can fail in **tclean** as a result of memory issues, in particular when imaging in parallel mode. A potential workaround solution is to use the task **concat** to first combined the MSs before running tclean, although further testing is needed to ensure that this solution is valid for all cases. This issue will be fixed in a next CASA release.\n",
        "\n",
        "### imregrid\n",
        "-    Position-velocity (PV) images are not supported by **imregrid**, because their coordinate systems are nonstandard, lacking a direction coordinate and having a linear coordinate.\n",
        "-    When converting from between coordinate system that require rotation (e.g., from celestial to galactic coordinates), CASA is known to introduce deviations in position from other software packages that can be several tenths of an arcsec. This could be because the rotation of the rectangular grid in a non-cartesian coordinate system is imperfect, possibly due to internal inconsistencies in the conversion matrices. The conversion between one frame and another in general becomes less accurate as distance from the output image\\'s reference pixel increases. The imregid task and Measures tool suffer from this Known Issue (see [imregrid task page](../api/casatasks.rst)).\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "BHkht7adJYp5"
      },
      "source": [
        "### viewer\n",
        "-    The CASA **viewer** does not yet support the entire region shapes and parameters at this stage.\n",
        "\n",
        "-    For equatorial cubes, i.e. data cubes that include dec=0 (exact), the **viewer** only gives spectra for sources at dec \\> 0. No spectra are produced for any points with `dec <0`. \n",
        "\n",
        "-    **Viewer** may not properly open saved region files.\n",
        "\n",
        "-    With the new *region* panel being used now, It may be advisable to rename the *\\$HOME/.casa/viewer/rc* file that stores previous configurations of the **viewer**.          \n",
        "\n",
        "-    **Viewer** - labels are not shown - this can be caused by a conflict between an installed version of *PGPLOT* and the version of *PGPLOT* that comes with the non-root version of CASA. If you do have *PGPLOT* installed in a standard location (e.g. */usr/lib*), you may try moving it aside and see if it resolves the problems. If you do encounter this problem, please report it to the CASA team.\n",
        "\n",
        "-    Some *X11* settings can make the viewer unstable. We identified that the line                *Load \\\"glx\\\"*                in */etc/X11/xorg.conf*    is such a setting. If you don\\'t need this line for aother applications, it would be better to have it removed.\n",
        "\n",
        "-    The viewer can only load MeasurementSets (MS) for which all spectral windows have the same channel width. If this is not the case, an *ArrayColumn* error will appear. To get around this, use *SPLIT*`` to place the spectral windows of interest in a separate MS, or try the *table browser* tool.\n",
        "\n",
        "-    When exiting CASA after using the viewer, a message similar to the following may appear: *proc vtool_1EziEss1P2tH0PxJbGHzzQ is being killed*. This is a cosmetic issue and can be ignored.\n",
        "    \n",
        "-    For some OSs and window managers, parts of the display may be eclipsing interactive elements. We recommend to change the window manager styles for these cases. \n",
        "    \n",
        "-    When multiple animators are open, it can happen that it is not possible to make them active, when the \\'Images\\' animator is inactive. Active the \\'Images\\' animator first to enable the other animators. \n",
        "    \n",
        "-    MeasurementSet with sizes of tens of Gb may not visualize the full data set properly on all machines, which can give the appearance that part of the data is flagged.\n",
        "    \n",
        "-    The line tool in the MAC viewer plots unreadable hex numbers. \n",
        "\n",
        "### plotms\n",
        "-    In plotms, PDF and PS exports have been reported not to work with some older sub-versions of RH7 (e.g., RH 7.6). While the problem has not been completely characterized, upgrading to a newer RH version (e.g., RH 7.9) has shown to solve this issue.\n",
        "\n",
        "-    In RedHat 7 we found that in some circumstances the vertical tab of the viewer appears on the right hand side instead of the left hand side. This eclipses the scrollbar and makes it difficult to use. To fix, add the following to the top of \\~/.config/Trolltech.conf\n",
        "\n",
        "    ```\n",
        "    [[Qt]]{.error}\n",
        "  \n",
        "    style=GTK+\n",
        "    ```\n",
        "\n",
        "-    When plotting pointing axes in **plotms** on RHEL6, the tick-values of minutes and seconds on the axes are not multiples of 5\n",
        "\n",
        "-    For concatenated data sets, **plotms** can create an output error if certain data columns were present in some of the concat input MSs, but missing in others (making concat inset zero values). A practical workaround is to either handle the MSs separately, or delete those columns using the tb.removecols tool (but in case of the latter one has to take care that the columns are not crucial).\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "CHoyzdy8JYp6"
      },
      "source": [
        "### uvmodelfit\n",
        "-    When running **uvmodelfit**, the output componentlist does not contain the uncertainty in flux that the task calculates (and displays at the end of the fitting process).\n",
        "\n",
        "### imstat\n",
        "-    The use of the *\"centerbox*\" parameter when specifying a region in **imstat** has a known issue that under very specific circumstances, less pixels are taken into account for the statistics than what is expected. This only occurs when all of the following are true: (1) values are specified in pixels; (2) the width of the box is an even number of pixels (e.g, 4pix, 16pix, or 100pix); and (3) the box is located away from the image center in Right Ascension (progressively more pixels are dropped when moving away from the image center, but only in RA). The issue is a combination of machine rounding errors (when the boundary of the centerbox is exactly at the center of a pixel), and the fact that centerbox has to converts pixel coordinates to sky coordinates to allow all possible combinations of regions. Note that the \"*box*\" parameter is not affected by this, because it can be more strict in only using flat pixel coordinates.    As a simple work-around solution, we recommend to always give the width of the centerbox in \"odd\" number of pixels. Please note that because centerbox places the center of a box in the middle of a pixel and CASA only includes full pixels, the width of a centerbox always has an odd number of pixels anyway. For example, `centerbox=[[1000pix,4000pix],[4pix,4pix]]` for an 8000x8000 pixel image should give npts=25, but due to the above issue will result in `npts <25`. Instead, `centerbox=[[1000pix,4000pix],[5pix,5pix]]` will always give npts=25.\n",
        "\n",
        "### tb.statistics\n",
        "-    The table tool\\'s statistics function *tb.statistics* currently ignores the useflags parameter, so statistics are calculated for all values in the specified column, and flagged values cannot be avoided.\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pvS0_ko5JYp6"
      },
      "source": [
        "### simobserve / simanalyze\n",
        "-    When using **simobserve** to simulate a spectral cube, using the *inwidth* parameter with units of velocity (e.g., *kms/s*) is known to produce wrong results. Use inwidth with frequency units instead (e.g., *inwidth=‘1MHz’*).\n",
        "\n",
        "-    CASA simulations do not yet fully support all spectral types of components (i.e., ability to include spectral lines or spectral indices)\n",
        "\n",
        "-    When cleaning with a simulated MS, it should be considered best practice to declare the *phasecenter* parameter using the \\'J2000 xx:xx:xx.xxx +xxx.xx.xx.xxx\\' notation to account for possible rounding errors that can create an offset in the image.\n",
        "    \n",
        "-    corruption of simulated MS by an atmospheric phase screen is only available from the toolkit. **simobserve** and **sm**: Under some circumstances, running **sm.setnoise** and **sm.corrupt**, or **simobserve** with thermal noise, twice using the same project name, the noise can be applied a second time, doubling the noise level. Be sure to use different project names for creating different simulations with noise. See [casaguides.nrao.edu](https://casaguides.nrao.edu/index.php/Main_Page) for the latest simulation information\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "bSfGPjsaJYp7"
      },
      "source": [
        "### single dish\n",
        "-    Difficulty in allocating memory to import/processing of Band 9 (fast-mapped, double-circle) data. Use high-performance machines as workaround.\n",
        "\n",
        "-    Please avoid using spectral window and channel selection by frequency range. It may occasionally fail. So far, this has only been reported on Mac OS but it may happen on Linux, too.\n",
        "\n",
        "- **CASA 6.4.0: sdcal** crashes if *'en_US'* is not available in the OS locale. This is known to happen on Ubuntu 20.04 with the so-called \"minimal\" install option. The underline cause is that task sdcal expects the presence of *'en_US'* in the OS locales, but the Ubuntu OS is only shipped with *'en_US.utf8'* by default, not *'en_US'*. This issue was fixed in the CASA 6.4.3 release.\n",
        "\n",
        "### sdimaging\n",
        "-    Frequencies and frequency increments in the weight image generated by **sdimaging** could be slightly different from those in the science image. The difference in frequency resolution (CDELT3 in .fits) could be 0.1% at maximum, which is negligible in most cases. If the difference matters, please use **tsdimaging** instead although it takes more time to process than **sdimaging**.\n",
        "\n",
        "-    **sdimaging** task may fail when more than several MSes are chosen as inputs (infiles) to create single output image. It is because the file descriptor opened by the task exceeds the limit defined by OSes. You can relax the limit of the number of open file descriptors by the command, e.g., *ulimit -n 4096* . Note the typical number of file descriptors opened by the task is 35/MS.       \n",
        "\n",
        "### sdintimaging\n",
        "-    For task **sdintimaging**, *gridder='awproject'* is not yet available. It will be enabled in a subsequent release.\n",
        "\n",
        "### plotprofilemap\n",
        "-    The task intermittently seg faults on Mac OS.\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "5AIpo-cqFHcd"
      },
      "source": [
        "## Compatibility\n",
        "\n",
        "The CASA software is available for mutiple LINUX and Mac computer operating systems, as well as multiple versions of Python. The compatibility matrix below shows the different Operating Systems and Python versions on which current and future CASA versions are expected to work, and for which the CASA team accepts bug reports. \n",
        "\n",
        "**However, note that CASA is only validated against the operational configuration of NRAO instruments (currently RHEL7/Python 3.6).**\n",
        "\n",
        "Further differences exist between the monolithic CASA distribution (which includes all packages and a relocatable copy of Python) and modular CASA (in which the user supplies their own Python environment).\n",
        "\n",
        "Refer to the following matrix for current and future planned compatibility.\n",
        "\n",
        "**Full Monolithic Distribution**\n",
        "\n",
        "|               | Python 2.7 | Python 3.6 | Python 3.7 | Python 3.8 |\n",
        "| ------------- |:----------:|:----------:|:----------:|:----------:|\n",
        "| RHEL 6        | 5.8        | <=6.3      |            |            |\n",
        "| RHEL 7        | 5.8        | >=6.1      |            | >=6.4      |\n",
        "| RHEL 8        |            |            |            | >=6.4      |\n",
        "| Ubuntu 18.04  |            | >=6.2      |            | >=6.4      |\n",
        "| Ubuntu 20.04  |            | >=6.2      |            | >=6.4      |\n",
        "| Mac OS 10.14  | 5.8        | >=6.1      |            | <=6.3      |\n",
        "| Mac OS 10.15  | 5.8        | >=6.1      |            | >=6.3      |\n",
        "| Mac OS 11 x86 |            | >=6.3      |            | >=6.3      |\n",
        "| Mac OS 12 ARM*|            |            |            | >=6.4      |\n",
        "\n",
        "*Note: the CASA Viewer may not work on Mac OS 12. We recommend to use the [CARTA visualization software](carta.ipynb) instead.\n",
        "\n",
        "\n",
        "**Modular CASA**\n",
        "\n",
        "|               | Python 2.7 | Python 3.6    | Python 3.7 | Python 3.8 |\n",
        "| ------------- |:----------:|:-------------:|:----------:|:----------:|\n",
        "| RHEL 6        |            | <=6.3         | 6.2        | 6.2        |\n",
        "| RHEL 7        |            | >=6.0         | >=6.2      | >=6.2      |\n",
        "| RHEL 8        |            | >=6.0         | >=6.4      | >=6.4      |\n",
        "| Ubuntu 18.04  |            | >=6.0         | >=6.2      | >=6.2      |\n",
        "| Ubuntu 20.04  |            | >=6.0         | >=6.2      | >=6.2      |\n",
        "| Mac OS 10.14  |            | >=6.1         |            | <=6.3      |\n",
        "| Mac OS 10.15  |            | >=6.1         |            | >=6.3      |\n",
        "| Mac OS 11 x86 |            | >=6.3         |            | >=6.3      |\n",
        "| Mac OS 12 ARM |            |               |            | >=6.4      |\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "Notes \n",
        "\n",
        "Older versions of CASA may not be compatible with the latest Operating Systems (for example, an appropriate usage mode on RedHat8 for CASA versions older than 6.3 has not yet been defined/tested). A listing of previous CASA versions and their supported OSs can be found on the [CASA website](https://casa.nrao.edu/casa_obtaining.shtml).\n",
        "\n",
        "The AppImage software is used to package the GUIs that are part of CASA. Users need to have the FUSE software installed, so these applications and be mounted and CASA can be run in its entirety.\n",
        "\n",
        "casaplotms became available for all Linux/Python 3.x combinations beginning in **6.1**\n",
        "\n",
        "casaviewer became initially available in **6.2** and fully supported in **6.3**\n",
        "</div>\n",
        "\n",
        "***\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Tqd0_w8VHEhG"
      },
      "source": [
        "## Installation \n",
        "\n",
        "A full installation of CASA including custom python environment is available as a Linux (.tar) or Mac (.dmg) file from our [Downloads](http://casa.nrao.edu/casa_obtaining.shtml) page (<http://casa.nrao.edu/casa_obtaining.shtml>)\n",
        "\n",
        "The CASA 6.x series is also available as modular packages, giving users the flexibility to build CASA tools and tasks in their own Python environment. This includes the casatools, casatasks, and casampi modules, allowing for core data processing capabilities in parallel.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "5rJ_gGXUr9cW"
      },
      "source": [
        "### Prerequisite OS Libraries\n",
        "\n",
        "CASA requires certain libraries be installed in the users operating system. Some may already be present by default.  In case they are not, the following list should be checked before using CASA or if errors are encountered at runtime.  Commands and package names are for Red Hat Linux, but equivalents can be found for other Linux distributions.\n",
        "\n",
        "A system administrator may be required to install OS libraries.\n",
        "\n",
        "-    ```$: sudo yum install ImageMagick*```\n",
        "-    ```$: sudo yum install xorg-x11-server-Xvfb```\n",
        "-    ```$: sudo yum install compat-libgfortran-48```\n",
        "-    ```$: sudo yum install libnsl```\n",
        "\n",
        "For modular CASA, one must supply their own Python environment. There are many, including ipython and Jupyter, here is a basic example:\n",
        "\n",
        "-    ```$: sudo yum install python36-devel``` or ```python38-devel```\n",
        "\n",
        "When using the casampi package from modular CASA, additional MPI libraries are needed:\n",
        "\n",
        "-    ```$: sudo yum install openmpi-devel```\n",
        "-    ```$: sudo yum install mpich-devel```\n",
        "-    User installs mpi4py with: \n",
        "\n",
        "    -    ```$: env MPICC=/usr/lib64/openmpi/bin/mpicc python -m pip install mpi4py --no-cache-dir```\n",
        "    -    Ensure mpirun is found: ```which mpirun```\n",
        "    -    If not, try full path: ```export PATH=/usr/lib64/openmpi/bin/mpirun\\$PATH```\n",
        "\n",
        "Alternative method for *NRAO systems only*\n",
        "\n",
        "-    contact the helpdesk to install casa-toolset-3 (which contains the previous libraries)\n",
        "-    the run ```export PATH=/opt/casa/03/bin:\\$PATH```\n",
        "\n",
        "\n",
        "<div class=\"alert alert-info\"> \n",
        "Note\n",
        "\n",
        "**Using the modular CASA Viewer with Mac OS** requires a special setup step.  [Download](https://casa.nrao.edu/download/devel/patch/pgplot.tar.gz) and expand the pgplot installation files on your machine. Then set the following environment variables from a terminal:\n",
        "\n",
        "```\n",
        "export PGPLOT_DIR=<download location>/pgplot\n",
        "export PGPLOT_FONT=<download location>/pgplot/grfont\n",
        "```\n",
        "\n",
        "</div>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gSIlhESeHf6A"
      },
      "source": [
        "### Monolithic Distribution\n",
        "\n",
        "**On Linux:** \n",
        "\n",
        "1.  Download the .tar file and place it in a work directory (e.g. \\~/casa)\n",
        "2.  From a Linux terminal window: \n",
        "    \n",
        "    ```\n",
        "    $: tar -xvf casa-xyz.tar.xz\n",
        "    $: ./casa-xyz/bin/casa\n",
        "    ```\n",
        "\n",
        "The one caveat is that CASA on Linux currently will not run if the Security-Enhanced Linux option of the linux operating system is set to enforcing. For the non-root install to work, SElinux must be set to disabled or permissive (in */etc/selinux/config*) or you must run (as root): ```$: setsebool -P allow_execheap=1```. Otherwise, you will encounter errors like:\n",
        "\n",
        "*error while loading shared libraries: /opt/casa/casa-20.0.5653-001/lib/liblapack.so.3.1.1: cannot restore segment prot after reloc: Permission denied*\n",
        "\n",
        "<div class=\"alert alert-warning\">\n",
        "**WARNING:** By default, python 3.6 (and earlier versions of python 3) include the current working directory in the python path at startup. Any script in that directory with the same name as a standard python module or a CASA module will be detected and used by python instead of the code that is delivered with CASA. Protections have been included for files called \"new.py\" and \"pickle.py\", but other scripts may cause problems with the CASA startup. For example, do not include a file named runpy.py in the working directory. \n",
        "</div>\n",
        "\n",
        "\n",
        "**On Macintosh:**\n",
        "\n",
        "1.  Download the .dmg disk image file\n",
        "2.  Double click on the disk image file (if your browser does not automatically open it).\n",
        "3.  Drag the CASA application to the *Applications* folder of your hard disk.\n",
        "4.  Eject the CASA disk image.\n",
        "5.  Double click the CASA application to run it for the first time. If the OS does not allow you to install apps from non-Apple sources, please Change the settings in \\\"System Preferences-\\> Security & Privacy -\\> General\\\" and \\\"Allow applications downloaded from: Mac App store and identified developers\\\".\n",
        "6.  Optional: Create symbolic links to the CASA version and its executables (Administrator privileges are required), which will allow you to run `casa`, `casaviewer`, `casaplotms`, etc. from any terminal command line. To do so, run \n",
        "    ```\n",
        "    !create-symlinks \n",
        "    ```\n",
        " \n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KmtgVmBXHitv"
      },
      "source": [
        "### Modular Packages\n",
        "\n",
        "Pip wheels for casatools and casatasks are available as Python 3 modules. This allows simple installation and import into standard Python environments. The casatools wheel is necessarily a binary wheel so there may be some compatibility issues for some time as we work toward making wheels available for important Python configurations.\n",
        "\n",
        "Make sure you have set up your machine with the *necessary prerequisite libraries* first.  Then a la carte installation of desired modules (from a Linux terminal window) as follows:\n",
        "\n",
        "```\n",
        "$: python3 -m venv myvenv\n",
        "$: source myvenv/bin/activate\n",
        "(myvenv) $: pip install --upgrade pip wheel\n",
        "```\n",
        "\n",
        "Now pick whichever subset of the available CASA packages you are interested in.  Package dependencies are handled automatically by pip, with the exception of **casadata** which must be explicitly installed and updated by the user (see [External Data](external-data.ipynb#Updating-the-Data-Tables)). The following packages are available:\n",
        "\n",
        "```\n",
        "(myvenv) $: pip install casatools==6.4.4.31\n",
        "(myvenv) $: pip install casatasks==6.4.4.31\n",
        "(myvenv) $: pip install casaplotms==1.5.5\n",
        "(myvenv) $: pip install casaviewer==1.5.2\n",
        "(myvenv) $: pip install almatasks==1.5.2\n",
        "(myvenv) $: pip install casampi==0.4.3\n",
        "(myvenv) $: pip install casashell==6.4.4.31\n",
        "(myvenv) $: pip install casadata==2022.3.28\n",
        "(myvenv) $: pip install casaplotserver==1.2.1\n",
        "```\n",
        "Users are advised to use a Python virtual environment (venv) and specific module version numbers as shown above. Giving an invalid number (like 999) to the pip install command is an effective way to list all available version numbers.\n",
        "\n",
        "**List all available versions of a module** (a hack):\n",
        "\n",
        "```\n",
        "(myvenv) $: pip install casatasks==999\n",
        "ERROR: Could not find a version that satisfies the requirement casatasks==999 (from versions: 6.0.0.27, 6.2.0.124, 6.2.1.7, 6.3.0.48)\n",
        "```\n",
        "\n",
        "**Start Python in your venv and sanity check**:\n",
        "\n",
        "```\n",
        "(myvenv) $ python\n",
        "\n",
        "Python 3.6.9 (default, Nov 7 2019, 10:44:02) \n",
        "[[GCC 8.3.0] on linux]\n",
        "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n",
        ">>> import casatasks\n",
        ">>> help(casatasks)\n",
        "```\n",
        "\n",
        "To exit the python venv, type ```deactivate``` from the terminal.  However, the rest of this documentation **assumes the venv is active** (to reactivate, type ```source myvenv/bin/activate```)\n",
        "\n",
        "The use of python3 venv is a simple built-in method of containerizing the pip install such that multiple versions of CASA 6.x can be kept on a single machine in different environments. In addition, CASA is built and tested using standard (python 3.6) libraries which can be replicated with a fresh venv, keeping the libraries needed for CASA isolated from other libraries which may already be installed on your machine.\n",
        "\n",
        "With the pip installation, CASA may be used in a standard Pythonic manner. Examples can be found in [this Jupyter Notebook](https://colab.research.google.com/github/casangi/examples/blob/master/casa6/CASA6_demo.ipynb).\n",
        "\n",
        "<div class=\"alert alert-warning\">\n",
        "**WARNING:** The pip-wheel version is intended for manual data processing, and is not yet officially endorsed by ALMA or VLA. Currently, pipelines are included in -and tested only for- all-inclusive monolithic CASA distributions.  \n",
        "</div>\n",
        "\n",
        "**Parallel Processing Setup**\n",
        "\n",
        "The casampi package provides the task-level [MPI](https://en.wikipedia.org/wiki/Message_Passing_Interface) parallelization infrastructure of CASA.  The casatasks module detects when casampi is available and enables the parallel processing capabilities of CASA. Advanced users may also access the casampi package directly to build new or custom parallelization schemes.\n",
        "\n",
        "*Make sure you have installed the prerequisite OS libraries for parallel processing.* To test for correct modular MPI installation, run the following commands (from Linux terminal):\n",
        "\n",
        "```\n",
        "(myvenv) $ echo \"from casampi.MPIEnvironment import MPIEnvironment; print('working?', MPIEnvironment.is_mpi_enabled)\" > test.py\n",
        "(myvenv) $ mpirun -q -n 2 python test.py\n",
        "```\n",
        "\n",
        "observe two instances of \\\"working? True\\\"\n",
        "\n",
        "\n"
      ]
    }
  ]
}