FILE: 00README.making_xrt_cal_files.txt AUTH: M.Weber DATE: 2010.03.11 SUBJ: This is a *QUICK* guide on how to create a new XRT calibration file. It does not describe all of the details and options. =========================================================================== Table of Contents: 0) General comments. 1) Create a new "config" file. 2) Add "config" file to repository control, IF it is an important update. 3) Create the "channel" file. 4) Move the "channel" file and commit it for public distribution. 5) Closing comments. =========================================================================== 0) General comments. The process for preparing a new XRT calibration for the public is handled with programs under this part of the SSWIDL tree: ssw/hinode/xrt/calibration/ *** The "calibration" directory is NOT publicly distributed in SSWIDL. You will NOT see it under your SSWIDL installation. ==> To do the work described here, you must check out a copy of the SSWIDL tree from the Subversion repository. (This example assumes you are logged in locally to the SAO-HEAD computer network.) .......................................... EXAMPLE: Unix> svn checkout file:///data/solarb/XRT/software/svnrepos/xrt/trunk/ssw Unix> cd ssw/hinode/xrt/calibration/ .......................................... 1) Create a new "config" file. A "config" file is actually an IDL program that specifies almost(*) all of the instrument calibration parameters. It includes parameters such as filter layer thicknesses. (*) --> The "config" file specifically does NOT include the contamination calibrations--- those parameters are time-dependent and maintained separately by the J-side. (The contamination is later added into the instrument calibration when the end-user creates the effective areas with .) The config files are stored here for version control in the repository: ssw/hinode/xrt/calibration/configs/ *** Do NOT change existing "config" files that are under version control! ==> Always make a new file with a new version number. You may make any new files you want for your own use, but do not modify or overwrite existing config files. Do not add config files to the repository control (with "svn add") unless you are planning to make a new calibration for distribution. *** Even when a config file is "svn added" to the repository control, it does not yet get publicly distributed, nor is it seen by . That happens in a later step. ==> Therefore, you can make a calibration file just for testing by the XRT Team. .......................................... EXAMPLE: Unix> cd ssw/hinode/xrt/calibration/configs/ Unix> cp xrt_config_v0013.pro xrt_config_v0014.pro Unix> vi xrt_config_v0014.pro [... edit parameters inside file ... save file ... exit editor ...] .......................................... 2) Add "config" file to repository control, IF it is an important update. If you just want to try different calibrations, then you should not add the file to the repository. If you *DO* want to create a new instrument calibration for distribution, then you SHOULD add the "config" file to repository control. .......................................... EXAMPLE: Unix> cd ssw/hinode/xrt/calibration/configs/ Unix> svn add xrt_config_v0014.pro .......................................... 3) Create the "channel" file. A "channel" file is a derivative of the "config" file, and it carries the same version number, automatically. What is the difference between these files? The "config" file treats all of the instrument components and parameters separately. The "channel" file treats combinations of components as channels or passbands. For example, the "Al-poly" channel includes the net transmission function for the "Al-poly" passband, through all of the pieces. (Note that contamination is not included at this point.) .......................................... EXAMPLE: Unix> cd ssw/hinode/xrt/calibration/ Unix> sswidl IDL> make_xrt_channel, 'configs/xrt_config_v0014.pro', $ IDL> xrt_channel=chn_struct, caldir='./' Unix> ls xrt_channels_v0014.geny xrt_channels_v0014.geny .......................................... *** Note that the version number from the filename is now ALSO a piece of data inside the calibration variable. ==> You should not rename the version number in a "channel" file filename, because it will then be inconsistent with the information inside the file. That ".geny" file is the "channel" file, and it is the main output of . One file contains all of the defined channels for that calibration configuration. If you used the optional keyword XRT_CHANNEL, then the named variable will also have the channel output. This option is provided so you can immediately review the output without having to read the "channel" file. IDL> help, chn_struct, /st *** The "channel" file is what takes as the calibration input file. ==> You can now create effective areas, even though we have not yet moved this "channel" file to public distribution. .......................................... EXAMPLE: Unix> cd ssw/hinode/xrt/calibration/ Unix> sswidl IDL> wresp = make_xrt_wave_resp(contam_thick=0.1, $ IDL> chn_filename='./xrt_channels_v0014') IDL> help, wresp, /st .......................................... 4) Move the "channel" file and commit it for public distribution. When you are satisfied that a calibration channel file is ready for public distribution, you need to move the file to the correct location and add it to the repository control. *** This is a significant step! Once this happens, the file will automatically go into public distribution. If it has the highest version number in the filename, it will become the DEFAULT calibration for . *** The "svn add" must come AFTER the file is in the proper location, because svn remembers WHERE you added the file. .......................................... EXAMPLE: Unix> cd ssw/hinode/xrt/calibration/ Unix> ls xrt_channels_v0014.geny xrt_channels_v0014.geny Unix> mv xrt_channels_v0014.geny ../idl/response/channels/ Unix> svn add ../idl/response/channels/xrt_channels_v0014.geny Unix> cd .. Unix> svn status Unix> svn commit -m "Added calibration file xrt_channels_v0014.geny." .......................................... It is always a good idea to run "svn status" before "svn commit", in order to review the changes you will be making to the repository. Why did I "cd .."? The "svn commit" command only commits changes below your present working directory. If you run "svn commit" from the "calibration/" directory, it will not commit the channel file over in the "responses/channels/" directory. 5) Closing comments. Every night, there is a cronjob that checks out the XRT tree from the repository, removes non-public directories (eg, "calibration/"), and moves it to a location where the SolarSoft cronjobs can find it to copy it for daily distribution. Therefore, it takes 1 to 2 days for a change to propagate to everyone's SSWIDL installation (if they are running daily updates). END