VHC configuration ================= ``vhc`` execution is driven by a configuration file, whose name is defined in :data:`~libvhc.config.DEF_CONFNAME`. Since the VHC development and the configuration updates are decoupled we store and track the configurations in a separate svn repository. Get it ------ To get the repository execute:: svn checkout svn://luna.mpe.mpg.de/vhc_config or:: svn checkout svn://luna.mpe.mpg.de/vhc_config/trunk vhc_config Edit and commit it ------------------ We want to be able to keep track of all the changes to the configuration files and to be able to replicate any of the results from ``vhc``. We have added at the top of the configuration file the following section .. code-block:: ini [svn] # DO NOT EDIT # these options are automatically set when doing an svn commit. They are # used to track the changes when running vhc. vhc should query these options # without interpolation date = $Date: 2015-03-23 14:25:45 +0100 (Mon, 23 Mar 2015) $ revision = $Revision: 3 $ author = $Author: montefra $ The ``date``, ``revision`` and ``author`` entries are updated automatically by svn when committing. These options will be gathered by ``vhc`` and saved in the ``log_{N}.txt`` and the html recap files. Thus, **any** set of edits belonging together and that are used for any kind of observation **must** be committed together to the repository **before** the start of observations and the repository must be updated. The description and motivation of the changes should be added to the ``Changelog`` file. To force svn to update the above options, we have added a pre-commit hook that refuses the commit if ``vhc_settings.cfg`` has not been modified. If ``vhc_settings.cfg`` has been modified, changes can be committed using the standard command:: svn commit Otherwise, you can run the script ``touch_commit.sh``:: Usage: touch_commit.sh [-hnt] Change the property 'touchsettings' of file 'vhc_settings.cfg' to a random string and commit. If the file 'svn-commit.tmp' is available in the current or parent directory and '-t' option is not given, it will be used to provide the commit message and, if successfull, it will be removed. -h print this help -n don't do the commit -t don't use the 'svn-commit.tmp' file for the svn commit message If ``svn-commit.tmp`` file is found, its content is printed to screen before the prompt for the svn password, so it is possible to abort the commit if the message is wrong. Directory structure ------------------- :: ├── Changelog ├── fplane # everything related to the focal plane │   └── fplane.txt # the focal plane file: position and ids of the IFUs ├── README.md # information about the repository ├── reference_files # VHC reference files │   ├── arcs.txt # line list files and tolerance in the pixel position │   ├── bias.txt # expected bias mean and standard deviation │   ├── distfiles.txt # list of distortion file names │   ├── distfiles # reference distortion files │   │   ├── mastertrace_045L.dat │   │   ├── [...] │   │   └── mastertrace_046R.dat │   ├── linefiles # reference line list files │   │   ├── lines_045L.dat │   │   ├── [...] │   │   └── lines_046R.dat │   ├── n_fibers.txt # number of expected fibers │   └── overscan.txt # expected overscan mean and standard deviation ├── scripts # auxiliary scripts │   └── replace_idca.py ├── touch_commit.sh # touch vhc_settings.cfg and commit └── vhc_settings.cfg # configuration file .. _useit: Use it ------ The most important file is ``vhc_settings.cfg``, and ``VHC`` requires it in order to be able to run. There are three ways to point ``VHC`` to the file. The ways are listed according to their priority: - command line option ``-c/--config``; - environment variable ``VHC_CONFIG``, e.g.:: export VHC_CONFIG=/path/to/vhc_settings.cfg vhc - a location on the file system. The first found is used: - ``./vhc_config/vhc_settings.cfg`` - ``$HOME/.config/vhc_config/vhc_settings.cfg`` - ``/etc/vhc_config/vhc_settings.cfg`` A note on the ``vhc_config`` directory ++++++++++++++++++++++++++++++++++++++ In the configuration file there are references to other files in the ``vhc_config`` repository. To prevent the user having to modify the ``vhc_settings.cfg`` file in order to set the correct path for these files, the options:: config_dir = ${vhc_config_dir} have been added in the ``general`` section. The values ``vhc_config_dir`` is inserted in the configuration object defaults by ``vhc``. So if the configuration directory is set as suggested in the :ref:`previous section `, ``config_dir`` contains the correct path to the configuration directory. Configuration file ------------------ In the configuration file we allow `cross-section interpolation `_ of the variables. This means that it is possible to build the value of an option using the value of another option, even if it is in another section of the file. Example +++++++ .. code-block:: ini [general] directory = /path/to/directory [section] file = ${general:directory}/file.txt subdir = a/subdir otherfile = ${subdir}/file.dat resolves into:: file = /path/to/directory/file.txt otherfile = a/subdir/file.dat Note: this kind of interpolation is built into the Python 3 configuration parser. In order to make it available to ``vhc`` also when running python 2 we make use of a custom configuration parser class implemented in :mod:`pyhetdex.tools.configuration`