H5config
========

H5config is a Python package for conviniently saving and loading
configuration classes from disk.  After populating base configuration
classes with parameters, h5config automatically generates HDF5 and
YAML backends for saving and loading that class.  Yes, all this
information could go into a single database, but if you like the
flexibility of having a bunch of individual files that you can peek
into one at a time, this module is for you.

I wrote the module to support my experiment-control infrastructure,
and one of the key goals was to easily embed control parameters in the
saved data::

  experiment.h5
  |-- raw/
  |   |-- thermocouple: [32757, 32731, 32796, 32789, 32809, ...]
  |   `-- deflection: [29808, 29793, 29782, 29817, 29775, ...]
  |-- timeseries-config/
  |   |-- frequency: 0.1
  |   |-- run-time: 100
  |   |-- thermocouple-channel/
  |   |   |-- conversion-coefficients: [-10.0, 0.000305180437934]
  |   |   `-- conversion-origin: [0.0]
  |   |-- deflection-channel/
  |   |   |-- conversion-coefficients: [-10.0, 0.000305180437934]
  |   |   `-- conversion-origin: [0.0]
  |   `-- thermocouple-calibration: [25.08355e3, 7.860106e4]
  `-- environment-config/
      |-- temperature: 20
      `-- timestamp: 1311851980.750180

Storing all of the calibration and conversion factors can get
complicated quickly.  h5config will keep you organized, and allow you
to focus on defining the config options without getting bogged down in
the bookkeeping.

As a side effect, h5config also provides some tools to support system-
and user-wide configuration files.  For example, the pypiezo_ package
uses h5config to automatically detect and load the following config
file::

  $ cat ~/.pypiezorc.yaml
  log-level: debug
  matplotlib: no


Installation
============

Packages
--------

Gentoo
~~~~~~

I've packaged h5config for Gentoo.  You need layman_ and my `wtk
overlay`_.  Install with::

    # emerge -av app-portage/layman
    # layman --add wtk
    # emerge -av dev-python/h5config


Dependencies
------------

If you're installing by hand or packaging h5config for another
distribution, you'll need the following dependencies:

===========  =================  =====================
Package      Debian_            Gentoo_
===========  =================  =====================
H5Py_        python-h5py        dev-python/h5py
Nose_        python-nose        dev-python/nose
PyYAML_      python-pyyaml      dev-python/pyyaml
===========  =================  =====================


Installing by hand
------------------

H5config is available as a Git_ repository::

    $ git clone http://physics.drexel.edu/~wking/code/git/h5config.git

See the homepage_ for details.  To install the checkout, run the
standard::

    $ python setup.py install


Usage
=====

See the module docstrings for simple examples.


Testing
=======

Run internal unit tests with::

    $ nosetests --with-doctest --doctest-tests h5config


Licence
=======

This project is distributed under the `GNU General Public License
Version 3`_ or greater.


Author
======

W. Trevor King
wking@drexel.edu
Copyright 2011


.. _pypiezo: 
     http://physics.drexel.edu/~wking/unfolding-disasters/posts/pypiezo/
.. _layman: http://layman.sourceforge.net/
.. _wtk overlay:
     http://physics.drexel.edu/~wking/unfolding-disasters/posts/Gentoo_overlay
.. _Debian: http://www.debian.org/
.. _Gentoo: http://www.gentoo.org/
.. _H5Py: http://code.google.com/p/h5py/
.. _Nose: http://somethingaboutorange.com/mrl/projects/nose/
.. _PyYAML: http://pyyaml.org/wiki/PyYAML
.. _Git: http://git-scm.com/
.. _homepage:
     http://physics.drexel.edu/~wking/unfolding-disasters/posts/h5config/
.. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.txt