intro to gclean

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.

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)})

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)})

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)})

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)})

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)})