NCOPY programmmer's documentation

Contributed by JPH, 940208.
Updates: JPH 941031 Clarify handling of APPLY/DEAPPLY masks before and after changes of October 1994.
JPH 941121 prefix underscores with slashes

Contents

• Contents
• Overview
• NCOCPY: Copy sectors
  • STH modifications
  • SCH modifications
  • NCOCPB: Make unique copy of a data structure
• Tests
  • Copying flags (9401..-940207)
  • Checklist overflow (de Bruijn, 940207)

Overview

NCOPY Phase 2 is still a relatively straigthforward program. The structure follows standard Newstar practice, with a main dispatching routine NCOPY, initialisation and user-parameter input routines NCOINI and NCODAT, and routines NCOxxx> that do the actual work. Some parameter input may be done by the latter. There are currently two main options:

• COPY: To selectively copy (parts of) sectors.
• OVERVIEW: To display an overview of all sectors, one sector per line.

NCOCPY: Copy sectors

. For a number of variables and data structures, NCOCPY has an input and an output copy, which are distinguished by the prefixes I and O: IPLN OPLN, etc. This is in anticipation of their I and O values being different, as some already may be, line ISCN and OSCN. Pairs that are currently identical are linked by EQUIVALENCEs, INIFR and ONIFR. "O" variables that are not equivalenced must be explicitly assigned. . The basic logic of NCOPCPY is straightforward. NSCSTG is repeatedly called to read sectors. Each sector's HA range is checked against the user's range and first and last scan numbers to be copied, SCNFST and SCNLST, are established. The condition that the output need no more polarisations than present in the input is also checked. . ISTH is then copied to OSTH and written tentatively, with as many changes as possible already made; its address is saved for a later rewrite. Next, the IFR table is copied and the file address of the scans block established. . The WSRT headers are copied in an internal subroutine at label 2020. This routine consists of calls to:

• NSCSCR: read SCH; read raw uncorrected scan visibilities into 4-polarisation c/s and weight arrays, using STH and SCH dimension parameters such as PLN and NIFR.

• NSCSDW: write scan from these arrays, again using dimension parameters.

. The model lists and visibilities are copied in an internal subroutine at label 2010.

. Finally, the newly made sector is linked into the index structure. The code is patterned after that of NSCREG.

STH modifications

NCOCPY is responsible for the following OSTH fields that differ from their ISTH peers:

• HAB, SCN: reflect the user's HA selection.
• PLN: the number of polarisations in the output.
• NIFR: number of output interferometers (currently identical to input).

• SCNL: scan length (depends on NIFR, PLN).

• REDNS, ALGNS, OTHNS: zero the Y components if only XX data present.

• pointers to other data structures.

SCH modifications

NCOCPY is responsible for the following OSCH fields that differ from their ISCH peers:

• MAX: maximum of C/S values REDNS, ALGNS, OTHNS.
• OTHNS: zero the Y components if only XX data present.

NCOCPB: Make unique copy of a data structure

Several input data structures may be linked by more than one pointer, and each link might give rise to a separate copy. For copying such structures, NCOCPB must be used. It maintains a checklist of input file addresses of blocks it has already copied, with the corresponding output file addresses. The calling program is responsible for allocating a buffer for this list and initialising it through a special call to NCOCPB. Details of this and other variant calls are to be found in NCOCPB's header. Since there can(?) be no duplications of data structures between groups, the checklist is reinitialised for every new input group. The blocks that may have multiple references are:

• FDW for all sectors in a mosaic: 1
• OHW for all sectors in the same field: 128 fields
• SHW for all sectors at the same frequency: 8 frequencies.
• MDH for all sectors in the same field: 128 fields

Tests

. The following tests were made to check NCOPY:

• Copy sectors from the same input SCN file with various selection parameters. Check outputs with OVERVIEW and compare samples of headers and data with NCOPY SHOW.
• Copy one 4-polarisation input sector to three output sectors, selecting XYX, XY and X polarisations. Make 4 XX and 3 YY maps from the input amd output sectors and compare the map statistics through . sdiff -s -w 80 log1> log2 grep '-'

Copying flags (9401..-940207)

Upon request of Ger de Bruijn, all input flags are also copied to the output. To this end, the calls to NSCSCR and NSCSCW have been changed to calls to NSCSCF and NSCSFW, respectively. These have an extra parameter in which the flag settings from the input are transferred to the output. The new entry points exist in the new version of NSCSCR and NSCSCW which are still being tested in JPH's shadow system. If desired, it is very simple to add code to suppress the copying of flags. Test: Use a 720-scan single-polarisation file. NFLAG, flag_optionDETERM, ops_determPBAS, pbas_limits=0,200. This results in 18in a 270-scan single-polarisation file. flag_optionINSPECT, ops_inspectIFR gives an overview per interferometer. Copy the file with NCOPY and test the copy with NFLAG, flag_optionINSPECT, ops_inspectCOUNT, select_flagALL, sub_cubeNO. This gives the same result.

Checklist overflow (de Bruijn, 940207)

Corrections:

• Do not use NCOCPB for STH addresses. Multiple references to STH can only occur due to a NSCAN REGROUP operation which is very rarely used. Multiple copies of an STH can not be prevented between COPY operations. The user is already responsible for avoiding those and now has the added responsibility of avoiding REGROUP duplications.
• Reinitialise checklist for each new input group.
• Souble checklist size to handle the largest predicted mosaic observation

Test: Copy a simple observation A to B, then B to C, and verify that overviews of B and C are identical.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.