Documentation overview

[jack-h]

The diagrams/docs on this repo are good, but it seems to me that the whole calibration process is crying out for a step-by-step overview. I don't know if the following is true, but something like.

Calibration:

1. Idling gain collator waits to receive solutions
2. Calibration processing (uvh5 recording and gain extraction) is triggered on the GPU nodes via an appropriate observation YAML
3. GPU nodes send their computed solutions (in what format?) to REDIS key ??
4. On receiving solutions from the first GPU node, the gain collator waits ?? seconds to gather solutions from all GPU nodes
5. When all solutions are received (or the wait times out) the gain collator assembles a full band of gains and runs a calibrration algorithm to extract a delay and per-channel phase. RFI excision might be applied here
6. computed calibrations are loaded to redis key ?? in ?? format where they can be included in phase tracking calculations

Delay tracking:

1. Delay model receives RA/DEC on redis channel ??
2. [Every N seconds] Delay model generates per antenna delays for this RA/DEC based on antenna positions stored in ??
3. Delay model sends delays to redis on channel ?? in format ??
4. FPGA control service receives delay polynomials on channel ?? and converts these into linear delay/phase polynomials to be loaded to FPGA.
5. [Every N seconds] FPGA recalculates delays to load to FPGA and loads them

In general, every process that does stuff with redis keys must have it's API documented somewhere. I.e., what keys it interacts with, what the keys do, and what the formats of the data payloads passed on these keys are.

[jack-h]

A troubleshooting section wouldn't hurt, either :)

Something like:

• uvh5 files not geneted: check observing yaml / postprocessing daemon
• calibrations not updated in redis: check collator service logs

If the log locations are configured in this repo, may as well describe them here. If not, I'll put them in the higher level documentation (though I'll still need you to tell me where the logs are / how they're set)

[talonmyburgh]

Sure thing. The above section on calibration is outlined in this document to a large extent but as a verification document it is not part (yet) of the FrontPage hierarchy. I'll take parts of it and detail them somewhere either within the Readme of this repository or inside of the FrontPage. I don't want to make this Readme too extensive, is there a better place I should be documenting this? I take it we're not so in favour of Google Docs?

[jack-h]

I guess there's a lot of personal preference here, but mine would be to have a succinct overview in the top-level readme, but certainly nothing so elaborate as that doc. As to where/how to format that doc, I think either publish as a PDF memo (https://github.com/COSMIC-SETI/FrontPage/tree/master/Memos) and link from the repo (and move the google doc so it is owned by an appropriate person/org). Or, put the whole thing in a docs section as markdown source. For what it's worth, the latter is what I am doing for the high-level doc (though as I'm doing it I'm aware it might be something i live to regret) (https://github.com/COSMIC-SETI/FrontPage/blob/top-level-doc/Memos/cosmic.md)