3 # calibcant - tools for thermally calibrating AFM cantilevers
5 # Copyright (C) 2007-2009 William Trevor King
7 # This program is free software; you can redistribute it and/or
8 # modify it under the terms of the GNU General Public License as
9 # published by the Free Software Foundation; either version 3 of the
10 # License, or (at your option) any later version.
12 # This program is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
15 # See the GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with this program; if not, write to the Free Software
19 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
22 # The author may be contacted at <wking@drexel.edu> on the Internet, or
23 # write to Trevor King, Drexel University, Physics Dept., 3141 Chestnut St.,
24 # Philadelphia PA 19104, USA.
27 Aquire, save, and load cantilever calibration bump data.
28 For measuring photodiode sensitivity.
30 W. Trevor King Dec. 2007 - Oct. 2008
32 The relevent physical quantities are :
33 Vzp_out Output z-piezo voltage (what we generate)
34 Vzp Applied z-piezo voltage (after external ZPGAIN)
35 Zp The z-piezo position
36 Zcant The cantilever vertical deflection
37 Vphoto The photodiode vertical deflection voltage (what we measure)
39 Which are related by the parameters :
41 zpSensitivity Zp / Vzp
42 photoSensitivity Vphoto / Zcant
44 Cantilever calibration assumes a pre-calibrated z-piezo (zpSensitivity) and
45 amplifier (zpGain). In our lab, the z-piezo is calibrated by imaging a
46 calibration sample, which has features with well defined sizes, and the gain
47 is set with a knob on the Nanoscope.
49 photoSensitivity is measured by bumping the cantilever against the surface,
50 where Zp = Zcant (see the bump_*() family of functions)
51 The measured slope Vphoto/Vout is converted to photoSensitivity via
52 Vphoto/Vzp_out * Vzp_out/Vzp * Vzp/Zp * Zp/Zcant = Vphoto/Zcant
53 (measured) (1/zpGain) (1/zpSensitivity) (1) (photoSensitivity)
55 We do all these measurements a few times to estimate statistical errors.
57 The functions are layed out in the families:
59 For each family, * can be any of :
60 aquire get real-world data
61 save store real-world data to disk
62 load get real-world data from disk
63 analyze interperate the real-world data.
64 plot show a nice graphic to convince people we're working :p
66 read a file with a list of paths to previously saved real world data
67 load each file using *_load(), analyze using *_analyze(), and
68 optionally plot using *_plot().
69 Intended for re-processing old data.
70 A family name without any _* extension (e.g. bump()),
71 runs *_aquire(), *_save(), *_analyze(), *_plot().
79 import piezo.z_piezo_utils as z_piezo_utils
81 from .bump_analyze import bump_analyze
84 LOG_DATA = True # quietly grab all real-world data and log to LOG_DIR
85 LOG_DIR = '$DEFAULT$/calibrate_cantilever'
87 TEXT_VERBOSE = True # for debugging
92 def bump_aquire(zpiezo, push_depth, npoints, freq) :
94 Ramps closer push_depth and returns to the original position.
96 zpiezo an opened zpiezo.zpiezo instance
97 push_depth distance to approach, in nm
98 npoints number points during the approach and during the retreat
99 freq rate at which data is aquired
100 log_dir directory to log data to (see data_logger.py).
101 None to turn off logging (see also the global LOG_DATA).
102 Returns the aquired ramp data dictionary, with data in DAC/ADC bits.
104 # generate the bump output
105 start_pos = zpiezo.curPos()
106 pos_dist = zpiezo.pos_nm2out(push_depth) - zpiezo.pos_nm2out(0)
107 close_pos = start_pos + pos_dist
108 appr = linspace(start_pos, close_pos, npoints)
109 retr = linspace(close_pos, start_pos, npoints)
110 out = concatenate((appr, retr))
111 # run the bump, and measure deflection
113 print "Bump %g nm" % push_depth
114 data = zpiezo.ramp(out, freq)
115 # default saving, so we have a log in-case the operator is lazy ;)
116 if LOG_DATA == True :
117 log = data_logger.data_log(LOG_DIR, noclobber_logsubdir=False,
118 log_name="bump_surface")
119 log.write_dict_of_arrays(data)
122 def bump_save(data, log_dir) :
123 "Save the dictionary data, using data_logger.data_log()"
125 log = data_logger.data_log(log_dir, noclobber_logsubdir=False,
127 log.write_dict_of_arrays(data)
129 def bump_load(datafile) :
130 "Load the dictionary data, using data_logger.date_load()"
131 dl = data_logger.data_load()
132 data = dl.read_dict_of_arrays(path)
135 def bump_plot(data, plotVerbose) :
136 "Plot the bump (Vphoto vs Vzp) if plotVerbose or PYLAB_VERBOSE == True"
137 if plotVerbose or PYLAB_VERBOSE :
139 _pylab.figure(BASE_FIGNUM)
140 _pylab.plot(data["Z piezo output"], data["Deflection input"],
142 _pylab.title("bump surface")
143 _pylab.legend(loc='upper left')
146 def bump(zpiezo, push_depth, npoints=1024, freq=100e3,
150 Wrapper around bump_aquire(), bump_save(), bump_analyze(), bump_plot()
152 data = bump_aquire(zpiezo, push_depth, npoints, freq)
153 bump_save(data, log_dir)
154 photoSensitivity = bump_analyze(data, zpiezo.gain, zpiezo.sensitivity,
155 zpiezo.pos_out2V, zpiezo.def_in2V)
156 bump_plot(data, plotVerbose)
157 return photoSensitivity
159 def bump_load_analyze_tweaked(tweak_file, zpGain=_usual_zpGain,
160 zpSensitivity=_usual_zpSensitivity,
161 Vzp_out2V=_usual_Vzp_out2V,
162 Vphoto_in2V=_usual_Vphoto_in2V,
164 "Load the output file of tweak_calib_bump.sh, return an array of slopes"
165 photoSensitivity = []
166 for line in file(tweak_file, 'r') :
167 parsed = line.split()
168 path = parsed[0].split('\n')[0]
170 full_data = bump_load(path)
171 if len(parsed) == 1 :
172 data = full_data # use whole bump
174 # use the listed sections
177 for rng in parsed[1:] :
181 zp.extend(full_data['Z piezo output'][starti:stopi])
182 df.extend(full_data['Deflection input'][starti:stopi])
183 data = {'Z piezo output': array(zp),
184 'Deflection input':array(df)}
185 pSi = bump_analyze(data, zpGain, zpSensitivity,
186 Vzp_out2V, Vphoto_in2V, plotVerbose)
187 photoSensitivity.append(pSi)
188 bump_plot(data, plotVervose)
189 return array(photoSensitivity, dtype=numpy.float)