diff --git a/docs/source/design/boundary.rst b/docs/source/design/boundary.rst index 2317b47..813e530 100644 --- a/docs/source/design/boundary.rst +++ b/docs/source/design/boundary.rst @@ -55,4 +55,60 @@ Python session from the GUI via :xref:`websocket` will be converted to :xref:`ju messages sent to the remote kernel. These messages will then run the process using the same interfaces provided by CASA and other packages as was used for local execution. +These two execution models will are sufficient as the basis for the usage settings described +in the casagui system document. A variant of these execution models may also be sufficent +for a website implementation. The GUI elements created with :xref:`bokeh` are compatible +with display within a website. The remote :xref:`jupyterkernel` execution is compatible +with processing initiated from a website. The details of the execution model between a +public website portal and the backend execution model lies outside of the CASA/casagui +context. +Implications +---------------- + +The varied usage and execution environments make it difficult to provide sufficient testing +for casagui. To ameliorate these difficulties, it is important to push as much functionality +down into the processing level as possible. Doing this maximizes the testing of functionality +as part of processing level testing. This testing is independent of GUI elements. + +The second implication arises from supporting remote execution. Because processing results +must be serialized and returned via :xref:`websocket` and displayed within a browser, the +processing interface must be defined in terms of basic Python types or types which can be +converted to basic Python types. An example of the latter is :xref:`numpy` arrays. The +interactive clean app uses :xref:`numpy` arrays to represent the images which are displayed +within :xref:`bokeh`. + +Example +---------------- + +This is drafted as the first version of interactive clean nears release. This initial release +will **not** include remote execution, but its design does attempt to conform to the constraints +which remote execution requires. + +The parameters and processing results are transferred from Python to a web browser for display. +As a result, they are serializable. + +Interactive clean uses a very limited portion of the public interface or perhaps this is better +termed an interface treated as public. This caveat is included because the processing interaction +is encapsulated within :xref:`gclean`. This allows for testing of the process that supports the +GUI. The public process API from CASA that interactive clean depend upon is :xref:`gclean` and +the :code:`shape`, :code:`maskhandler`, :code:`coordsys`, :code:`getregion`, :code:`fitsheader`, +:code:`getchunk`, :code:`putchunk` and :code:`statistics` functions of the :xref:`imagetool`. + +gclean +^^^^^^^^^^^^^^^^ + +:xref:`gclean` is a Python class which encapsulates the process layer of interactive clean. It +allows for automated testing of all of the process interface of interactive clean as part of +the standard (non-interactive) testing of the process layer. It implement the functionality +of :xref:`tclean` in a way that is usable by interactive clean. Scientifically the behavior of +:xref:`gclean` is equivalent to :xref:`tclean`, but modifying :xref:`tclean` is difficult because +it is used extensiviely in a production environment. + +A :xref:`gclean` object is constructed with the subset of :xref:`tclean` parameters which are +relevant to interactive use. It implements a Python generator which returns a series of +:xref:`returndict`. This dictionary is a regular python dictionary which accumulates information +as processing progresses. :xref:`gclean` deviates somewhat from the typical generator by +including an :code:`update` function which accepts a dictionary of parameters to change for +the next generation step. These parameters are the modifications the user has indicated from +the interactive clean GUI. diff --git a/docs/source/links/gclean.py b/docs/source/links/gclean.py new file mode 100644 index 0000000..57b23fe --- /dev/null +++ b/docs/source/links/gclean.py @@ -0,0 +1,6 @@ +from . import link + +link_name = "gclean" +user_text = "gclean" +url = "https://open-bitbucket.nrao.edu/projects/CASA/repos/casa6/browse/casatasks/src/private/imagerhelpers/_gclean.py" +link.xref_links.update({link_name: (user_text, url)}) diff --git a/docs/source/links/imagetool.py b/docs/source/links/imagetool.py new file mode 100644 index 0000000..7674826 --- /dev/null +++ b/docs/source/links/imagetool.py @@ -0,0 +1,6 @@ +from . import link + +link_name = "imagetool" +user_text = "CASA image tool" +url = "https://casadocs.readthedocs.io/en/stable/api/tt/casatools.image.html" +link.xref_links.update({link_name: (user_text, url)}) diff --git a/docs/source/links/numpy.py b/docs/source/links/numpy.py new file mode 100644 index 0000000..1725780 --- /dev/null +++ b/docs/source/links/numpy.py @@ -0,0 +1,6 @@ +from . import link + +link_name = "numpy" +user_text = "NumPy" +url = "https://numpy.org/" +link.xref_links.update({link_name: (user_text, url)}) diff --git a/docs/source/links/returndict.py b/docs/source/links/returndict.py new file mode 100644 index 0000000..881783d --- /dev/null +++ b/docs/source/links/returndict.py @@ -0,0 +1,6 @@ +from . import link + +link_name = "returndict" +user_text = "imaging return dictionary" +url = "https://casadocs.readthedocs.io/en/stable/notebooks/synthesis_imaging.html#Returned-Dictionary" +link.xref_links.update({link_name: (user_text, url)}) diff --git a/docs/source/links/tclean.py b/docs/source/links/tclean.py new file mode 100644 index 0000000..366e57a --- /dev/null +++ b/docs/source/links/tclean.py @@ -0,0 +1,6 @@ +from . import link + +link_name = "tclean" +user_text = "tclean" +url = "https://casadocs.readthedocs.io/en/stable/api/tt/casatasks.imaging.tclean.html" +link.xref_links.update({link_name: (user_text, url)})