Implement PFM-5 Pointing/Focusing Correction Model

Modification Request #1 Cycle 4, 2007

1. Introduction

This MR details the work to be done to incorporate a new pointing and focusing model in the antenna manager. The changes described here will be released for tests on or before August 1st, 2007.

The current implementation of the pointing focus model version 4, is spread between the antenna coordinator and antenna manager, antenna characterization manager and active surface manager. The antenna manager implements the static geometric and gravitational models for pointing and focus tracking. The antenna coordinator coordinates with the scan-coordinator, reads the pfm database, and writes the antenna FITS files. The antenna characterization manager implements the (dynamic) thermal correction models for pointing and focusing, and passes the corrections to the antenna manager at regular intervals. As scans are run, the antenna manager uses the corrections to command the servos and then records the position data during the scan as well as all data associated with the pointing/focusing. A number of ancillary data items are recorded in the antenna FITS file by the antenna coordinator to document what corrections went into the model for a given scan. They are: the coefficients of the geometric/gravitational model; a time-tagged list of the net thermal corrections; the user specified offsets (LPC's); receiver feed offsets; and the average value of the lookup table corrections.

This MR details the changes to incrementally move to a new pointing and focusing model in preparation for the completion of track repairs on the GBT. Although it is understood that active surface and the focus model affects pointing, the current thrust is to update the track-related model. Hence the active surface and focus models are not detailed here. No modifications to the active surface or antenna characterization managers are outlined in this MR, however, since both either consume data calculated by the antenna manager or import antenna manager code libraries, there will be a very small effect on both systems. More background on specific details of the new/old models is given in the references below:

The new model is known as 'model 5'. The technical description of model 5 is given in PTCS PN-53.
The thermal correction model is discussed in PTCS project note 25.
A description of the processing currently performed (i.e. model 4) in the antenna manager is available here.
A description of the processing performed in model 5 by the antenna manager is detailed here.

A number of items have changed in Model 5, which I will attempt to summarize below:

two additional terms (b02, d02) have been added to the geometric/gravitational model for the azimuth axis
the three model-4 residual lookup tables have been removed
three new lookup tables have been added for track corrections (lambda1,lambda2 and lambda3) as a function of azimuth.
a hysteresis (direction-based) correction has been added (both az and el)
a rate-based hysteresis correction term has been added (both az and el)
where terms are dependent upon az/el, the mount az/el is used
where values are combined in a manner which includes a rescaling by 1/cos(minor), the value used for the cos function will be the minor coordinate value after the sum.
- e.g:
  - az=az+delta_xel/cos(el+delta_el)
- not
  - az = az + delta_xel/cos(el)

3. Requirements

The main goal is to update the antenna manager/antenna characterization manager to incorporate the new pointing model described in PTCS PN-53 and summarized above.

3.1 Parameter Set Changes

The antenna has a number of configurable items, referred to as 'Parameters'. These items are further divided into read-write (control-parameters), and read-only (feedback-parameters). The parameter-set constitutes a major portion of the external interface to the antenna device.

In order to implement the new model, the following parameter-related changes must be made:

Control Parameters renamed:
- az_xel_residual_table renamed to lambda1_table
- el_el_residual_table renamed to lambda2_table
- el_az_residual_table renamed to lambda3_table
Control Parameter Changes:
- The fields az_b02, az_d02, az_h00, az_h01, az_r00, el_h00, el_h01, and el_r00 shall be added to the control-parameter pointing_model
Feedback Parameter Changes:
- The fields b02 and d02 shall be added to the azimuth portion of the control-parameter traditionalCoeff.
- The fields h00, h01 and r00 shall be added to both the azimuth and elevation portions of the control-parameter traditionalCoeff

The fields b02 and d02 are being added for experimental purposes, and will be normally set to zero.

Note that these control-parameters exist only in the antenna manager, and not in the antenna coordinator, so most interfaces will be unaffected by this MR. However, there will be an impact on the cleo-antenna interface, due to the addition of fields to the traditionalCoeff and pointing_model parameters. Astrid will remain unaffected by control/feedback parameter changes.

3.2 Antenna FITS File Changes

The value of the FITSVER keyword shall be incremented from 2.10 to 2.11 to indicate the changes in this document.
The new keywords PNTAZB02 and PNTAZD02 will be added, to record the values of the new traditional model terms.
The new keywords PNTAZH00, PNTAZH01, PNTELH00, and PNTELH01 will be added to record the values of the hysteresis correction coefficients.
The new keywords PNTAZR00, PNTELR00 will be added to record the values of the rate-based hysteresis correction coefficients.
The new keywords PNTLAMB1,PNTLAMB2, PNTLAMB3, will be added to record the average value of the lambda1,lambda2 and lambda3 corrections respectively for the scan.

The new keywords have the following description:

Name	Description
PNTAZB02	The coefficient of the sin(2*elevation) term
PNTAZD02	The coefficient of the cos(2*elevation) term
PNTAZH00	The coefficient that describes the magnitude of the azimuth hysteresis correction.
PNTAZH01	The coefficient to the velocity which constitutes the argument to the hyperbolic tangent function, and thus establishes the width of a smooth transition between the two states.
PNTAZR00	The coefficient to the rate-base hysteresis correction.
PNTELH00	The coefficient that describes the magnitude of the elevation hysteresis correction.
PNTELH01	The coefficient to the velocity which constitutes the argument to the hyperbolic tangent function, and thus establishes the width of a smooth transition between the two states.
PNTELR00	The coefficient to the rate-base hysteresis correction.

3.3 Specific Modifications to the Current Implementation

This section is only a quick summary of the changes, as the details are described in GBT Pointing Focus Model 5.

3.3.1 Addition of Hysteresis Correction

This correction shall introduce an offset based on the direction of commanded movement. The magnitude of correction shall be adjustable. The correction shall be combined as an azimuth (i.e. not cross-elevation) term.

3.3.2 Addition of a Rate-based Hysteresis Correction

A correction which is proportional to axis rate shall be added. A single coefficient shall control the amplitude of the correction.

3.3.2 Re-factoring of the Traditional Model

The traditional and local pointing correction models will be merged into a single pointing correction module. Where pointing terms are dependent upon azimuth or elevation, the mount az/el shall be used.

3.4 PFM Database Changes

The pointing and focus database already contains a mechanism for storing look-up tables for specific purposes. This will be expanded to include storage for tables which are of type "lambda1", "lambda2" and "lamda3". However there are a few other minor changes required:

Add the fields az_h00, az_h01, az_r00, az_b02, az_d02, el_h00, el_h01, and el_r00 to the pointing_gravity_model table
Add "lambda1", "lambda2", "lambda3" as legal enumerations for table type in the field "set_id" of table "residual".
Verify operation of new schema with other systems, such as the AntennaCharacterization manager.

The revised PFM schema is shown below:

The revised PFM database schema.

4. Design

The antenna module which performs the pointing corrections is called the PointingProcessor. This module will be refractored to merge the LocalCorrectionModel and TraditionalModel classes as shown in figures 1 (before) and figure 2 (after refactoring). The goal here is to combine the two models as a single calculation, instead of artificially keeping them separate. Note the changes in table names and addition of new terms.


Figure 1: Class diagram of current Model-4.	Figure 2: Class diagram of Model-5, after refactoring.

5. Test Programs

As part of this MR, a test program will be produced to verify results on a canonical data set. This program directly links with the antenna manager code, providing a convenient testbed for numerical verification of results. This program will be used by PTCS staff to compare the model 5 implementation with test data produced by Kim and ToddHunter. This section documents the use of this program.

I've moved the documentation for the pointing test utility to its own manual page here. --JJB The program has the following options: (See manual page for more up-to-date information. The remainder of this section may be inaccurate.)

--input filename : specifies the input datafile to be used
--output filename : specifies the output datafile to be produced
--mount : means the input data is refracted topocentric az/el and that the output data will be in mount coordinates
--topocentric : opposite of above, input data is in mount and output data will be in refracted topocentric az/el
--model modelname : specifies the pointing model configuration name to be used
--lpc daz dxel del : specifies the az, cross elevation and elevation LPC terms in degrees; defaults to zeros if unspecified
--dyn daz dxel del : specifies the az, cross elevation and elevation thermal correction terms in degrees; defaults to zero if unspecified

The input data file should consist of refracted az/el position pairs, followed by az/el velocities (i.e. four fields azpos, elpos, azvel, elvel per line, separated by whitespace). Comments are allowed by placing a '#' in column 1 of each comment line. The output data file will contain a comment block documenting the coefficients, LPC's and thermal corrections, followed by the transformed az/el position data and velocity data in the same format as the input data file.

Note: Position units are in degrees and velocity units are degrees/second.

Example input and output files are provided.

6. Deployment Checklist

What has to get done to integrate this completely into the system.

Communication with Computing group needed? No
What documentation needs to be updated?
- Antenna FITS documentation
- On-line pointing model display scripts
Training Needed? Is this being released to staff astronomers or everyone right now? General release
Notification Needed? Cleo will need to be updated to reflect parameter changes/additions.

7. Test Plan

7.1 Internal Testing

Unit tests will be constructed to numerically test the changes. Additionally, a utility will be available, which allows the computation of canonical data sets using the exact code from the antenna system. ToddHunter will send data sets to both JoeBrandt and Kim. Each will run the model-5 and compare results.

7.2 Sponsor Testing

This section is for the sponsor. What do you need to do in order to ensure that the MR is complete and correct? These tests are the prerequisite for sign off for the "accepted/delivered by sponsor" item in the "signatures" section.

There will be significant testing to characterize the new track, and to derive new pointing model coefficients. The testing listed here are just some of the many tests which will be run to verify the new implementation.

7.2.1 Parameters checks

Check each of the new parameters manually using devexplorer for legal ranges. Verify messages appear when out-of-range values are entered.
Enter an out-of-range value into a test PFM database configuration. Verify the error messages appear when the configuration is selected, and reset when a legal value is entered.

7.2.2 FITS checks

Manually verify the FITSVER is 2.11.
Verify each of the new keywords listed in section 3.2 are present.
Verify each of the new keyword values match the values in the parameters (for those keywords which have corresponding parameters).
Verify the values in the PNTLAMB1,PNTLAMB2, PNTLAMB3 make sense by loading a constant offset into the tables and running a scan.
Verify that the updated FITS documentation for the antenna contains each of the new keywords, a description of the semantics and measurement units.

7.2.3 Model checks

The pointing modules are compiled into libraries and linked into the antenna manager, and into the test program described in section 5. This allows bench-testing of the pointing module. A portion of the verification of the new model implementation will be performed through the use the test program (documented in section 5) against a canonical test data set. The data shall be specified as a text file, with two values per line representing an azimuth and elevation value. The test program is able to compute both topocentric to mount and mount to topocentric. All az/el values shall be in degrees. (Refraction shall be disabled for the tests.)

7.3 Integration/Regression Tests

Verify that when a model-5 PFM configuration is selected that the AntennaCharacterization is unaffected by the change and continues to produces pointing corrections, without errors. (Confirming the AntennaCharacterization manager SQL queries are still consistent with the updated PFM schema.)
Conduct a series of pointing scans and verify:
- the produced LPC values from gfm converge upon a single value
- the pointing is not degraded.

Signatures

APPROVED: I acknowledge that my request is fully contained in this MR, and if the SDD delivers exactly what I specified, I will be happy.

ACCEPTED: I acknowledge that I have validated the completed code according to the acceptance tests, and I am happy with the results.

Written	- JoeBrandt - 22 Jun 2007
Checked	- RonGrider - 25 Jun 2007
Approved by Sponsor	- ToddHunter - 23 Jul 2007
Approved by CCC	- RonMaddalena - 7 Aug 2007
Accepted/Delivered by Sponsor	- ToddHunter - 19 Sep 2007

Symbols:

Use %X% if MR is not complete (will display )
Use %Y% if MR is complete (will display )

CCC Discussion Area

-- JoeBrandt - 29 May 2007

Attachment:	Action:	Size:	Date:	Who:	Comment:
PTCS_Model5.pdf	action	103276	23 Aug 2007 - 14:05	JoeBrandt
PTCS_Model4.pdf	action	97155	21 Jun 2007 - 20:56	JoeBrandt
ClassDiagModel4.png	action	10294	22 Jun 2007 - 17:57	JoeBrandt
ClassDiagModel5.png	action	10657	16 Jul 2007 - 14:48	JoeBrandt
AntennaPFMSchema.png	action	55163	09 Jul 2007 - 17:51	JoeBrandt
example_input.txt	action	210	23 Jul 2007 - 16:29	JoeBrandt
example_output.txt	action	446	23 Jul 2007 - 16:30	JoeBrandt
antenna_pfm.sql.gz	action	60266	15 Aug 2007 - 13:43	JoeBrandt	Dump of PFM4 database for posterity

Topic ModificationRequest1C407 . { Edit | Attach | Ref-By | Printable | Diffs | r1.31 | > | r1.30 | > | r1.29 | More }

Revision r1.31 - 18 Sep 2007 - 22:41 GMT - ToddHunter Parents: PlanOfRecordC42007	Content copyright © 1999-2007 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.


NRAO Home > Green Bank \| Wiki Topic: GB > Software > PlanOfRecordC42007 > ModificationRequest1C407

Changes \| Index \| Contents \| Search \| Statistics \| Go