How to create a new tool in CASA

See also

• XML Schema for the tools description (casa.xsd)

These are my notes on how to create a new tool for CASA, in particular in this case a new tool to implement WVR phase correction.

Writing the tool XML file

The best way is to look at existing files, identify parts of those existing files with functionality similar to what is required and then copy those making the necessary changes. The structure of the files is relatively straightforward to understand.

If the XML new file is placed in one of the tool directories (in this case I will use code/xmlcasa/implement/synthesis) it is then automatically picked up by SCons, used in the binding generation process and compiled into the python library.

Header file <toolname>_private.h

These appear declarations of private members not generated in the binding which then get inserted nested within the class declaration. The #include is actually within in a class declaration, which is very unconventional

<toolname>_cmpt.h/cc files

These are generated by CCMTools but usually must be manually edited/added to. Therefore, CCMTools should be used to generate the initial version, and then this should be added to the main source tree.

Inclusion of the cmpt.h file

By default, the generated file will contain a line like:

#include <wvrphase_cmpt.h>

To include the tool header file. This however leads to problems because of auto-generated files of the same name floating about. This line needs to be changed to:

#include <xmlcasa/synthesis/wvrphase_cmpt.h>

which fully qualifies the header file to use.

Trivial example

This is a trivial example which adds a tool that doesn’t really do anything but can take parameters etc. All of the files below need to be placed in the casa/code/xmlcasa/implement/synthesis directory and the tool will be built and accessible from Python. For example, in this example on can do:

import casac;
wvrphasehome =  casac.homefinder.find_home_by_name('wvrphaseHome');
wvrphase = wvrphasehome.create(); wvrphase.xcorrect('test', 3);

which produces the trivial output “Got test,3”

This is the xml file:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" ?>
<casaxml xmlns="http://casa.nrao.edu/schema/psetTypes.html"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://casa.nrao.edu/schema/casa.xsd
file:///opt/casa/code/xmlcasa/xml/casa.xsd">

<!--
2009 Bojan Nikolic b.nikolic@mrao.cam.ac.uk
This file is part of CASA and is distributed under GPL V2 
-->

<tool name="wvrphase" module="wvrphase">
<shortdescription>WVR-based correction of phase errors</shortdescription>

<description>
Longer description goes here
</description>


<method type="constructor" name="wvrphase">
   <shortdescription>Construct a wvrphase tool</shortdescription>
   <returns type="calibrater"/>
   <description>
   </description>
   <example>
   \begin{verbatim}
   \end{verbatim}
   </example>
</method>

<method type="function" name="xcorrect">
  <shortdescription>Rough prototype for the phase correction functionality -- do not use</shortdescription>
  <input>
     <param type="string" direction="in" name="filename">
     <description>MeasurementSet file name.  No default</description>
     </param>
     <param type="int" direction="in" name="solival">
     <description>Solution interval for the coefficient retrieval (seconds)</description>
     <value>60</value>
     </param>
  </input>
  <returns type="bool"/>
  <description>
  </description>
  <example>
  \begin{verbatim}

  \end{verbatim}
  </example>
</method>


</tool>
</casaxml>

This is the <toolname>_cmpt.h file:

/***
 * Framework independent header file for wvrphase...
 *
 * Implement the wvrphase component here.
 * 
 * // TODO: WRITE YOUR DESCRIPTION HERE! 
 *
 * @author
 * @version 
 ***/

#ifndef _wvrphase_cmpt__H__
#define _wvrphase_cmpt__H__

#include <vector>
#include <impl/casac/casac.h>

// put includes here

namespace casac {

/**
 * wvrphase component class 
 *
 * // TODO: WRITE YOUR DESCRIPTION HERE! 
 *
 * @author
 * @version 
 **/
class wvrphase
{
  private:

	

  public:

    wvrphase();
    virtual ~wvrphase();

    bool xcorrect(const std::string& filename, const int solival = 60);

};

} // casac namespace
#endif

This is the <toolname>_cmpt.cc file:

/***
 * Framework independent implementation file for wvrphase...
 *
 * Implement the wvrphase component here.
 * 
 * // TODO: WRITE YOUR DESCRIPTION HERE! 
 *
 * @author
 * @version 
 ***/

#include <iostream>
#include <xmlcasa/synthesis/wvrphase_cmpt.h>

using namespace std;

namespace casac {

wvrphase::wvrphase()
{

}

wvrphase::~wvrphase()
{

}

bool
wvrphase::xcorrect(const std::string& filename, const int solival)
{
  std::cout<<"Got "<<filename
	   <<"," 
	   <<solival
	   <<std::endl;
}

} // casac namespace