Usage

MeqSilhouette can be run in a number of ways. They all require that a JSON parset file is passed as the sole argument.

On the local machine

If MeqSilhouette is installed on the local machine, it should already have the command meqsilhouette in PATH and can be run as follows:

$ meqsilhouette obs_settings.json

This command will run the driver script run_meqsilhouette.

To use an existing MS, MeqSilhouette uses another driver script called readms_runmeqs which can be run as follows:

$ python </path/to/readms_runmeqs.py> </path/to/input/json/parset/file> </path/to/existing/ms>

The existing MS will be copied to output/inputs directory and will be regularized if necessary i.e., missing baselines for all timestamps in the MS will be inserted, so that the MS used for corruptions contains a regular grid of visibility values.

Note

If using an existing MS, care must be taken to ensure that all timestamps from the beginning to the end are present in the MS. If there are missing timestamps, then tropospheric turbulence cannot be added, since this will cause the covariance matrix to be NOT positive definite and hence its Cholesky decomposition will fail.

Via Singularity

There are two ways to run MeqSilhouette via Singularity. In both cases, it is the responsibility of the user to ensure that the relevant paths in the JSON parset file are writable.

Interactive mode

Interactively using the shell option:

$ singularity shell meqsilhouette.sif # drops the user inside the container
> meqsilhouette obs_settings.json

Command-line mode

Invoke the run option:

$ singularity run meqsilhouette.sif obs_settings.json

Via Docker

There are two ways to run MeqSilhouette via Docker as well. The interactive route is a bit more involved while the command-line mode is more straightforward.

As before, it is the responsibility of the user to ensure that the relevant paths in the JSON parset file are writable.

Interactive mode

A docker volume is the best way to share data between the container and the host. First copy the relevant input files to a directory with write access. Assuming that this directory is ~/data, start the docker container as follows:

$ docker run -dit -P -v ~/data:/meqsdata meqsilhouette

where /meqsdata is an arbitrary mount point in the running container to which the host directory ~/data is to be bound. The above command will print the container ID which is a long string of characters (this can also be obtained by typing docker ps -a on the terminal). Once started, attach to the container using the first four characters xxxx of this ID:

$ docker attach xxxx

This will drop the user into the shell from which MeqSilhouette can be run as follows:

$ meqsilhouette /meqsdata/obs_settings.json

Since /meqsdata is where ~/data is mounted, any output files must be written to /meqsdata for them to persist after the container is stopped. If the output files are written elsewhere, the execution will still be successful, but the files will not persist in host storage. To avoid this, the data generated must be manually copied into /meqsdata.

Command-line mode

More easily, the following command on the terminal (with all the caveats about paths to input/output files mentioned above) executes MeqSilhouette:

$ docker run -v ~/data:/meqsdata meqsilhouette meqsilhouette /meqsdata/obs_settings.json

Note that the first meqsilhouette is the name of the image to be run and the second meqsilhouette is the command that must be run within the container, since no default entrypoint/command is defined.

IPython/Jupyter Notebook

Running MeqSilhouette from any Python interpreter is as easy as firing up the interpreter and typing the following:

> from meqsilhouette.driver import run_meqsilhouette
> run_meqsilhouette.run_meqsilhouette('/path/to/JSON/parset/file')

The above command will run the default driver script shipped with the source code. This is the same script run by the command meqsilhouette on the command-line in the above cases.

To run readms_runmeqs:

> from meqsilhouette.driver import readms_runmeqs
> readms_runmeqs.readms_runmeqs(</path/to/input/json/parset/file>, </path/to/existing/ms>)

For advanced users

MeqSilhouette provides two driver scripts by default. Advanced users can construct their own versions of the driver script by importing the framework module in their code directly. For instance, additional operations on the Measurement Set such as flagging or averaging can be performed by an enhanced driver script tailored to the needs of the user.