README

   1 Pyafm
   2 =====
   3
   4 Pyafm is a set of tools for controlling atomic force microscopes.  It
   5 provides control of AFM postition using both short-range (piezo) and
   6 long range (stepper) vertical positioning.  There are separate modules
   7 for controlling the piezo (pypiezo_) and stepper (stepper_), this
   8 module mostly contains methods that require the capabilities of both.
   9
  10 This module can optionally include temperature sensing via a pypid_
  11 backend.
  12
  13 Packages
  14 ========
  15
  16 Gentoo
  17 ------
  18
  19 I've packaged pyafm for Gentoo.  You need layman_ and my `wtk
  20 overlay`_.  Install with::
  21
  22   # emerge -av app-portage/layman
  23   # layman --add wtk
  24   # emerge -av sci-libs/pyafm
  25
  26 Although it is not strictly required (thanks to `duck typing`_) you'll
  27 probably also want my `stepper`_ package or an equivalent
  28 stepper implementation.
  29
  30
  31 Dependencies
  32 ============
  33
  34 Pyafm requires the following Python modules:
  35
  36 * Pycomedi_ (required directly, and via ``pypiezo``)
  37 * Pypiezo_
  38 * Stepper_ (or equivalent stepper implementation)
  39 * Pypid_ (optional temperature monitoring and control)
  40 * H5config_ (required directly, and via ``pypiezo``)
  41 * SciPy_
  42
  43 Getting the source
  44 ==================
  45
  46 Pyafm is available as a Git_ repository::
  47
  48   $ git clone git://tremily.us/pyafm.git
  49
  50 There are also periodic bundled releases.  For example, get version
  51 0.3 as a gzipped tarball with::
  52
  53   $ wget 'http://git.tremily.us/?p=pyafm.git;a=snapshot;h=v0.3;sf=tgz'
  54   $ tar -xzvf pyafm-0.3.tar.gz
  55
  56
  57 Installation
  58 ============
  59
  60 After downloading, change to the source directory and run::
  61
  62   $ python setup.py install
  63
  64 to install pyafm.  Run::
  65
  66   $ python setup.py install --help
  67
  68 to see a list of installation options you may want to configure.
  69
  70
  71 Usage
  72 =====
  73
  74 The docstrings include some pretty detailed tests to get you started.
  75 ``dir()`` and ``help()`` are your friends ;).  One neat feature that
  76 I've added recently (2012-03-16) is the ability to store and load
  77 complete AFM configurations via h5config_.  For example, when you
  78 first use pyafm, it may take you a bit to dig up all the necessary
  79 calibration constants, etc. and plug them into your config::
  80
  81   >>> import pycomedi.constant
  82   >>> import pypiezo.config
  83   >>> import pyafm.config
  84   >>> config = pyafm.config.AFMConfig()
  85   >>> config['name'] = '1B3D9'
  86   >>> config['main-axis'] = 'z'
  87   >>> config['piezo'] = pypiezo.config.PiezoConfig()
  88   >>> config['piezo']['name'] = '2253E'
  89   >>> config['piezo']['axes'] = [
  90   ...     pypiezo.config.AxisConfig(), pypiezo.config.AxisConfig()]
  91   >>> config['piezo']['axes'][0]['gain'] = 20
  92   >>> config['piezo']['axes'][0]['sensitivity'] = 8.8e-9
  93   >>> config['piezo']['axes'][0]['channel'] = pypiezo.config.OutputChannelConfig()
  94   >>> config['piezo']['axes'][0]['channel']['analog-reference] = pycomedi.constant.AREF.ground
  95   >>> config['piezo']['axes'][0]['channel']['analog-reference] = pycomedi.constant.AREF.ground
  96
  97 and on, and on ;).  Don't worry though, once you finish telling Python
  98 about your particular AFM configuration, you can get a working ``AFM``
  99 instance quite easily::
 100
 101   >>> devices = []
 102   >>> afm = AFM(config=config, devices=devices)
 103
 104 That takes care of opening all the channels and initializing all the
 105 pieces you configured above.  ``devices`` will end up full of any
 106 ``pycomedi.device.Device`` instances that you need.  Once you're happy
 107 with your setup, make sure the ``config`` object is up-to-date with::
 108
 109   >>> afm.setup_config()
 110
 111 Which copies any new object state into the ``.config`` attribute
 112 (e.g. bit-to-volt conversion polynomials).  Then save your
 113 configuration with::
 114
 115   >>> import pyafm.storage
 116   >>> pyafm.storage.save_afm(afm=afm, filename='whatever', group='/optional')
 117
 118 Which will create a HDF5 file at the specified path, and store the AFM
 119 configutaion under the specified group.  Both ``filename`` and
 120 ``group`` are optional.  If you leave them out, they will default to
 121 ``~/.config/pyafm-default.h5`` and ``/`` respectively.
 122
 123 The next time you need to do something with the AFM, just load your
 124 old config file.  If you used the default location, that's as easy
 125 as::
 126
 127   >>> import pyafm.storage
 128   >>> devices = []
 129   >>> afm = pyafm.storage.load_afm(devices=devices)
 130   >>> afm.load_from_config()
 131
 132 When you're done using them, it's good practice to close any devices
 133 in ``devices``::
 134
 135   >>> for device in devices:
 136   ...     device.close()
 137
 138 Using ``load_afm`` with the default path is a good way to keep your
 139 AFM configuration synchronized across several applications.  That way,
 140 there's only one place you need to update if you recalibrate your
 141 piezo or rebuild an amplifier.
 142
 143
 144 .. _layman: http://layman.sourceforge.net/
 145 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 146 .. _duck typing: http://en.wikipedia.org/wiki/Duck_typing
 147 .. _pycomedi: http://blog.tremily.us/posts/pycomedi/
 148 .. _pypiezo: http://blog.tremily.us/posts/pypiezo/
 149 .. _stepper: http://blog.tremily.us/posts/stepper/
 150 .. _pypid: http://blog.tremily.us/posts/pypid/
 151 .. _h5config: http://blog.tremily.us/posts/h5config/
 152 .. _SciPy: http://www.scipy.org/
 153 .. _Git: http://git-scm.com/