PFM Database Utilities

The file AntennaRDB.py has a number of methods to create/copy/modify antenna pointing and focus model database entries. This page documents the summary of usage.

Queries:

This section is meant as an FYI into how one might traverse the antenna PFM database tables. It might be helpful to examine the Antenna PFM schema.

Retrieving a Pointing or Focus Model

The PFM schema is shown in figure 1. The data stored is pretty much in normal form, such that datasets are never duplicated. Where data is shared, the data items are referenced either by foreign keys, or by 'maps' which represent many-to-many relations.

Navigation of the PFM always starts at the table configuration. A named configuration is normally specified by the user. So the first query in English is:
    What is the most recent configuration.id for the name "Model5g"
The data returned is sorted by version and then by date, returning the most recent, highest revision level entry.

The next query is to pull out all the entries of the configuration_map which have an configuration_id which matches the configuration.id from the first query. This gives us the id's of unique rows in the tables: pointing_grav_model, focus_grav_model, site_data, refraction_model, and the residual set_id for the named configuration. (More on set_id's in the next section.)

To summarize:
  • A name is mapped to a configuration.id by the configuration table,
  • which is then used by the configuration_map to find the foreign keys into the tables holding
    • the pointing model,
    • focus model,
    • site data,
    • refraction model
    • and residual set id

Given each of these foreign keys, entries for these items can easily be retrieved.

Retrieving Track Residual Model Data

In the discussion above, I noted how the set_id for the residual table is determined. A set_id specifies the entries located in the residual table, which belong to a given configuration. This contains data for the lambda, lambda2 and lambda3 track correction lookup tables. To retrieve values for a given table (e.g. the lambda1 table), a query of rows matching both the set_id and the residual_type_id is used. The special value of zero for the set_id is used as a default to specify no offset.

Retrieving Receiver Beam Offsets

The PFM database also contains entries for beam offsets of each receiver feedhorn, or virtual feed. A single set of offsets is specified using the following information:
  • configuration.id
  • The name of the selected receiver
  • The name of the selected beam

Since names are specified, but the foreign keys are numeric, a couple of joins with the receiver and beam tables is used. Again to maintain data in normal form, a map is used to represent the many-to-many relationships between receiver_beam_offsets, optics_config, receiver and beam tables for a given configuration.

For cleo's convenience, the receivers table contains a string of all legal beams for a specific receiver.

Maintaining and Adding New Configurations

Adding a new configuration can be a bit daunting. I usually begin by using list_configs() to print the contents of the configuration table. Next I add a new entry in the configuration table, with the name, date and version. A common approach is to copy an existing configuration, and modify the new data. The method create_config() performs this function.

create_config(reference_config, config_name, pid, fid, set_id)

Where:
  • reference_config is the name of the existing configuration to copy from
  • config_name is the name of the new configuration
  • pid is the id of an entry in the pointing_grav_model table to use If set to none, the pid from reference_config is used
  • fid is the id of an entry in the focus_grav_model table to use. If set to none, the fid from reference_config is used
  • set_id is the set id to use for residual data. Use a set_id of zero to specify no offset. If set_id is none, the set_id from reference_config is used

This method will create the named entry referencing the pointing_grav_model.id and focus_grav_model.id specified. It will then copy the map entries to populate the receiver_beam_map and dynamic_model_map tables. The site_data.id and refraction_model.id are hard-coded since I have yet to see any variation in the default usage. (TBF)

Step-by-Step Procedure for Adding a New Configuration

OK, now that we have the big picture. Here are some notes on creating a new pointing and focus model, with new residual data. A key to interpreting the output of the matlab/tpoint reduction is given on this page.

Adding a New Pointing Model

The first step is to create a record in the pointing_grav_model table. The best method is to use the AntennaRDB create_new_pointing_entry() method, which creates a new record by copying the one used in a reference model.
    import AntennaRDB a = AntennaRDB("antenna_pfm")

    a.list_configs() - prints a list of models. new_pid = a.create_new_pointing_entry('Model 5s')

The pointing coefficients which are prefixed by a,b,c or d are all in units of arc-minutes. The PTCS group may provide the coefficients in different units, so conversion to arc-min may be required. Typically the coefficients are provided in arc-sec, so a division by 60.0 is required. The field mnt_az_offset and mnt_el_offset are constants associated with the servo encoder. The values should be copied from another row in the pointing_grav_model table. This is the purpose of this method.

The new field h_00 is in arc-minutes; and represents the maximum hysteresis correction amplitude. The field r_00 is degrees of correction per degrees/sec of rate.

Adding a New Focus Model

The second step is to create a record in the focus_grav_model table - if required. Updating a pointing coefficient does not require a new focus model. Similar to adding a pointing model entry, the easiest method is to use phpmyadmin, to add a new row to the focus_grav_model table. The units here are in millimeters and degrees of tilt. Typically new coefficients are provided only for the Y-axis, so other values (e.g: X,Z,...) are copied from prior focus models.

Adding Residual Tables

Using phpmyadmin, examine the residual table contents. Click on the set_id column (twice) to sort by set_id in desending order. Find the highest numbered set_id, and add one for the new set_id. You only need one set_id per configuration. (i.e. the lambda1,lambda2 and lambda3 tables all share the same set_id for a given configuration.)

Residual tables should be formatted in two columns: az, lambda_angle Commas are required! (This is a change from when this document was first authored.)

Thermal Terms

The thermal terms are a set of equations, coefficients, and aliases which are evaluated by the AntennaCharacterization system. The tie-in with PFM configurations is in the dyn_model_map, which contains both a configuration.id and dyn_model.id. The create_config() method described above adds new rows to the table for the new configuration. (No longer does it use back references to the reference model.)

Note: The thermal terms are in units of arc-seconds and millimeters.

Adding a new Receiver

Here's an example of how we add nominal values for the new RcvrArray1_2 (a prime focus rx)

  • log into DB (antenna_pfm_sim to test, then move on to antenna_pfm)
  • add this row to the receiver table: RcvrArray1_2 1 0 (1,C)
  • get the python class up and running:
    • source /home/sim/gbt.bash
    • source /home/sparrow/integration/sparrow.bash
    • python
    • >>> from AntennaRDB import *
    • >>> a = AntennaRDB("antenna_pfm_sim")
  • make sure your receiver shows up: a.list_rx_table()
  • list the models that we may want to add it to: a.list_configs()
  • for this receiver, add the two names of the central beam (1 and C) :
    • a.create_new_beam('Default_PrimeFocus', 'RcvrArray1_2', '1', 0, 0)
    • a.create_new_beam('Default_PrimeFocus', 'RcvrArray1_2', 'C', 0, 0)
  • view this query to make sure it shows up: http://leo.gb.nrao.edu/php/antenna_db/displaydb.php?dbase=antenna_pfm_sim

Doc Strings from the AntennaRDB.py:

  • constructor: AntennaRDB(whichdb) - Creates a connection to the specified database. Note: this uses the !'DatabaseHost' specified in the $YGOR_TELESCOPE/etc/system.conf file.
  • list_configs() - prints a list of configuration names
  • getConfigurationId(config_name) - Returns the id of the associated configuration name
  • getRxId(rx_name) - Returns the id of the associated receiver name, independent of configuration
  • getBeamId(beam_name) - Returns the id of the associated receiver name, independent of configuration
  • getBeamOffsetId(configname, rx_name, beam_name) - Returns the id of the beam_offset associated with a given config,rx,beam combination
  • getPointingModelByName(config_name) - Returns the pointing model coefficients based on the configuration name
  • getFocusModelByName(config_name) - Returns the focus model coefficients based on the configuration name
  • get_residual_set_id_by_name(config_name) - Returns the residual set id based on the configuration name
  • create_config(reference_model, new_model, pid, fid, res_set_id) - Creates a new configuration given an existing configuration name, new pointing model id, new focus model id, and residual_set ids. Note: None may be used to specify that the data should be duplicated from the reference_model.
  • copy_rx_beam_map(from_model, to_model) - Copies/duplicates the beam map entries for a new configuration, based on an existing configuration
  • create_new_beam(config_name, rx_name, beam_name, xel_offset, el_offset) - Creates or updates a new named beam to an existing receiver, for a given configuration. The receiver, optics config, and configuration must already exist.
  • copy_dyn_model_map(from_config, to_config) - Copies the dynamic model map entries for a new configuration.
  • create_new_pointing_grav_entry(reference_model) - Creates a new row in the pointing_grav_model table based on data from the reference_model.
  • create_new_focus_grav_entry(reference_model) - ditto except for focus table.
  • load_el_f_el() etc. are deprecated and not used.
  • load_residual_table(residual_type, to_model, csv_filename) - loads a residual table into the to_model. The residual type is a string one of 'lambda1', 'lambda2' or 'lambda3'

Some common operations as receivers are moved around and installed/removed:
  • set_rx_slot(rxname, slot) - updates the receiver table with a new slot reference (i,e. moves the receiver to a new slot)
  • rx_to_telescope(rxname) - Marks a receiver as being installed on the telescope
  • rx_to_lab(rxname) - Marks a receiver as being removed from the telescope
  • update_beam_offsets(modelname, rx_name, beam_name, new_el_offset, new_xel_offset) - updates the beam offsets for a single beam of a single receiver in one model.

-- JoeBrandt - 30 Jul 2007
Topic revision: r9 - 2018-10-17, JoeBrandt
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback