1 # calibcant - tools for thermally calibrating AFM cantilevers
3 # Copyright (C) 2008-2011 W. Trevor King <wking@drexel.edu>
5 # This file is part of calibcant.
7 # calibcant is free software: you can redistribute it and/or
8 # modify it under the terms of the GNU Lesser General Public
9 # License as published by the Free Software Foundation, either
10 # version 3 of the License, or (at your option) any later version.
12 # calibcant is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU Lesser General Public License for more details.
17 # You should have received a copy of the GNU Lesser General Public
18 # License along with calibcant. If not, see
19 # <http://www.gnu.org/licenses/>.
21 """Acquire, save, and load cantilever calibration bump data.
23 For measuring photodiode sensitivity.
25 The relevent physical quantities are:
26 Vzp_out Output z-piezo voltage (what we generate)
27 Vzp Applied z-piezo voltage (after external ZPGAIN)
28 Zp The z-piezo position
29 Zcant The cantilever vertical deflection
30 Vphoto The photodiode vertical deflection voltage (what we measure)
32 Which are related by the parameters:
34 zp_sensitivity Zp / Vzp
35 photo_sensitivity Vphoto / Zcant
37 Cantilever calibration assumes a pre-calibrated z-piezo
38 (zp_sensitivity) and amplifier (zp_gain). In our lab, the z-piezo is
39 calibrated by imaging a calibration sample, which has features with
40 well defined sizes, and the gain is set with a knob on our modified
43 Photo-sensitivity is measured by bumping the cantilever against the
44 surface, where `Zp = Zcant` (see the `bump_*()` family of functions).
45 The measured slope Vphoto/Vout is converted to photo-sensitivity via
47 Vphoto/Vzp_out * Vzp_out/Vzp * Vzp/Zp * Zp/Zcant = Vphoto/Zcant
48 (measured) (1/zp_gain) (1/zp_sensitivity) (1) (photo_sensitivity)
50 We do all these measurements a few times to estimate statistical
53 The functions are layed out in the families:
55 For each family, * can be any of:
56 acquire get real-world data
57 save store real-world data to disk
58 load get real-world data from disk
59 analyze interperate the real-world data.
60 plot show a nice graphic to convince people we're working :p
62 A family name without any _* extension (e.g. `bump()`), runs `*_acquire()`,
63 `*_save()`, `*_analyze()`.
65 If `package_config['matplotlib']` is `True`, `*_analyze()` will call
66 `*_plot()` internally.
69 import numpy as _numpy
71 from pypiezo.base import convert_meters_to_bits as _convert_meters_to_bits
72 from pypiezo.base import convert_bits_to_meters as _convert_bits_to_meters
74 from . import LOG as _LOG
75 from .bump_analyze import bump_analyze as _bump_analyze
76 from .bump_analyze import bump_save as _bump_save
79 def bump_acquire(afm, bump_config):
80 """Ramps `push_depth` closer and returns to the original position.
83 afm a pyafm.AFM instance
84 bump_config a .config._BumpConfig instance
86 Returns the acquired ramp data dictionary, with data in DAC/ADC bits.
88 afm.move_just_onto_surface(
89 depth=bump_config['initial-position'], far=bump_config['far-steps'],
90 setpoint=bump_config['setpoint'],
91 min_slope_ratio=bump_config['min-slope-ratio'])
92 #afm.piezo.jump('z', 32000)
94 _LOG.info('bump the surface to a depth of %g m with a setpoint of %g V'
95 % (bump_config['push-depth'], bump_config['setpoint']))
97 axis = afm.piezo.axis_by_name(afm.axis_name)
99 start_pos = afm.piezo.last_output[afm.axis_name]
100 start_pos_m = _convert_bits_to_meters(axis.config, start_pos)
101 close_pos_m = start_pos_m + bump_config['push-depth']
102 close_pos = _convert_meters_to_bits(axis.config, close_pos_m)
104 dtype = afm.piezo.channel_dtype(afm.axis_name, direction='output')
105 appr = _numpy.linspace(
106 start_pos, close_pos, bump_config['samples']).astype(dtype)
107 # switch numpy.append to numpy.concatenate with version 2.0+
108 out = _numpy.append(appr, appr[::-1])
109 out = out.reshape((len(out), 1))
111 # (samples) / (meters) * (meters/second) = (samples/second)
112 freq = (bump_config['samples'] / bump_config['push-depth']
113 * bump_config['push-speed'])
115 data = afm.piezo.ramp(out, freq, output_names=[afm.axis_name],
116 input_names=['deflection'])
118 out = out.reshape((len(out),))
119 data = data.reshape((data.size,))
120 return {afm.axis_name: out, 'deflection': data}
122 def bump(afm, bump_config, filename, group='/'):
123 """Wrapper around bump_acquire(), bump_analyze(), bump_save().
127 >>> from h5config.storage.hdf5 import pprint_HDF5
128 >>> from pycomedi.device import Device
129 >>> from pycomedi.subdevice import StreamingSubdevice
130 >>> from pycomedi.channel import AnalogChannel, DigitalChannel
131 >>> from pycomedi.constant import AREF, IO_DIRECTION, SUBDEVICE_TYPE, UNIT
132 >>> from pypiezo.afm import AFMPiezo
133 >>> from pypiezo.base import PiezoAxis, InputChannel
134 >>> from pypiezo.config import ChannelConfig, AxisConfig
135 >>> from stepper import Stepper
136 >>> from pyafm.afm import AFM
137 >>> from .config import BumpConfig
139 >>> fd,filename = tempfile.mkstemp(suffix='.h5', prefix='calibcant-')
142 >>> d = Device('/dev/comedi0')
145 Setup an `AFMPiezo` instance.
147 >>> s_in = d.find_subdevice_by_type(SUBDEVICE_TYPE.ai,
148 ... factory=StreamingSubdevice)
149 >>> s_out = d.find_subdevice_by_type(SUBDEVICE_TYPE.ao,
150 ... factory=StreamingSubdevice)
152 >>> axis_channel = s_out.channel(
153 ... 0, factory=AnalogChannel, aref=AREF.ground)
154 >>> input_channel = s_in.channel(0, factory=AnalogChannel, aref=AREF.diff)
155 >>> for chan in [axis_channel, input_channel]:
156 ... chan.range = chan.find_range(unit=UNIT.volt, min=-10, max=10)
158 We set the minimum voltage for the `z` axis to -9 (a volt above
159 the minimum possible voltage) to help with testing
160 `.get_surface_position`. Without this minimum voltage, small
161 calibration errors could lead to a railed -10 V input for the
162 first few surface approaching steps, which could lead to an
163 `EdgeKink` error instead of a `FlatFit` error.
165 >>> axis_config = AxisConfig()
166 >>> axis_config.update(
167 ... {'gain':20, 'sensitivity':8e-9, 'minimum':-9})
168 >>> axis_channel_config = ChannelConfig()
169 >>> axis_channel_config['name'] = 'z'
170 >>> axis_config['channel'] = axis_channel_config
171 >>> input_channel_config = ChannelConfig()
172 >>> input_channel_config['name'] = 'deflection'
174 >>> a = PiezoAxis(config=axis_config, axis_channel=axis_channel)
177 >>> c = InputChannel(config=input_channel_config, channel=input_channel)
180 >>> piezo = AFMPiezo(axes=[a], inputs=[c])
182 Setup a `stepper` instance.
184 >>> s_d = d.find_subdevice_by_type(SUBDEVICE_TYPE.dio)
185 >>> d_channels = [s_d.channel(i, factory=DigitalChannel)
186 ... for i in (0, 1, 2, 3)]
187 >>> for chan in d_channels:
188 ... chan.dio_config(IO_DIRECTION.output)
190 >>> def write(value):
191 ... s_d.dio_bitfield(bits=value, write_mask=2**4-1)
193 >>> stepper = Stepper(write=write)
195 Setup an `AFM` instance.
197 >>> afm = AFM(piezo, stepper)
201 >>> bump_config = BumpConfig()
202 >>> bump(afm, bump_config, filename, group='/bump')
203 TODO: replace skipped example data with real-world values
204 >>> pprint_HDF5(filename) # doctest: +ELLIPSIS, +REPORT_UDIFF
209 <HDF5 dataset "far-steps": shape (), type "<i4">
211 <HDF5 dataset "initial-position": shape (), type "<f8">
213 <HDF5 dataset "model": shape (), type "|S9">
215 <HDF5 dataset "push-depth": shape (), type "<f8">
217 <HDF5 dataset "push-speed": shape (), type "<f8">
219 <HDF5 dataset "samples": shape (), type "<i4">
221 <HDF5 dataset "setpoint": shape (), type "<f8">
223 /bump/config/deflection
224 /bump/config/deflection/channel
225 <HDF5 dataset "channel": shape (), type "<i4">
227 <HDF5 dataset "conversion-coefficients": shape (2,), type "<f8">
228 [ -1.00000000e+01 3.05180438e-04]
229 <HDF5 dataset "conversion-origin": shape (), type "<f8">
231 <HDF5 dataset "device": shape (), type "|S12">
233 <HDF5 dataset "inverse-conversion-coefficients": shape (2,), type "<f8">
235 <HDF5 dataset "inverse-conversion-origin": shape (), type "<f8">
237 <HDF5 dataset "maxdata": shape (), type "<i8">
239 <HDF5 dataset "name": shape (), type "|S10">
241 <HDF5 dataset "range": shape (), type "<i4">
243 <HDF5 dataset "subdevice": shape (), type "<i4">
247 /bump/config/z/axis/channel
248 <HDF5 dataset "channel": shape (), type "<i4">
250 <HDF5 dataset "conversion-coefficients": shape (2,), type "<f8">
251 [ -1.00000000e+01 3.05180438e-04]
252 <HDF5 dataset "conversion-origin": shape (), type "<f8">
254 <HDF5 dataset "device": shape (), type "|S12">
256 <HDF5 dataset "inverse-conversion-coefficients": shape (2,), type "<f8">
258 <HDF5 dataset "inverse-conversion-origin": shape (), type "<f8">
260 <HDF5 dataset "maxdata": shape (), type "<i8">
262 <HDF5 dataset "name": shape (), type "|S1">
264 <HDF5 dataset "range": shape (), type "<i4">
266 <HDF5 dataset "subdevice": shape (), type "<i4">
268 <HDF5 dataset "gain": shape (), type "<i4">
270 <HDF5 dataset "maximum": shape (), type "<f8">
272 <HDF5 dataset "minimum": shape (), type "<i4">
274 <HDF5 dataset "monitor": shape (), type "|S1">
276 <HDF5 dataset "sensitivity": shape (), type "<f8">
278 <HDF5 dataset "processed": shape (), type "<f8">
281 <HDF5 dataset "deflection": shape (2048,), type "<u2">
283 <HDF5 dataset "z": shape (2048,), type "<u2">
286 Close the Comedi device.
290 Cleanup our temporary config file.
292 >>> os.remove(filename)
294 deflection_channel = afm.piezo.input_channel_by_name('deflection')
295 axis = afm.piezo.axis_by_name(afm.axis_name)
297 data = bump_acquire(afm, bump_config)
298 photo_sensitivity = _bump_analyze(
299 data, bump_config, z_axis_config=axis.config,
300 deflection_channel_config=deflection_channel.config)
302 filename, group, data, bump_config,
303 z_axis_config=axis.config,
304 deflection_channel_config=deflection_channel.config,
305 processed_bump=photo_sensitivity)
306 return photo_sensitivity