3 # calibcant - tools for thermally calibrating AFM cantilevers
5 # Copyright (C) 2007,2008, 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 Separate the more general bump_analyze() from the other bump_*()
28 functions in calibcant. Also provide a command line interface
29 for analyzing data acquired through other workflows.
31 The relevant physical quantities are :
32 Vzp_out Output z-piezo voltage (what we generate)
33 Vzp Applied z-piezo voltage (after external ZPGAIN)
34 Zp The z-piezo position
35 Zcant The cantilever vertical deflection
36 Vphoto The photodiode vertical deflection voltage (what we measure)
38 Which are related by the parameters :
40 zpSensitivity Zp / Vzp
41 photoSensitivity Vphoto / Zcant
43 photoSensitivity is measured by bumping the cantilever against the
44 surface, where Zp = Zcant (see calibrate.bump_aquire()). The measured
45 slope Vphoto/Vout is converted to photoSensitivity with bump_analyze().
49 import common # common module for the calibcant package
50 import config # config module for the calibcant package
54 from splittable_kwargs import splittableKwargsFunction, \
55 make_splittable_kwargs_function
57 #@splittableKwargsFunction((bump_plot, 'data'))
58 # Some of the child functions aren't yet defined, so postpone
59 # make-splittable until later in the module.
60 def bump_analyze(data, zpGain=config.zpGain,
61 zpSensitivity=config.zpSensitivity,
62 Vzp_out2V=config.Vzp_out2V,
63 Vphoto_in2V=config.Vphoto_in2V,
66 Return the slope of the bump ;).
68 data dictionary of data in DAC/ADC bits
69 Vzp_out2V function that converts output DAC bits to Volts
70 Vphoto_in2V function that converts input ADC bits to Volts
71 zpGain zpiezo applied voltage per output Volt
72 zpSensitivity nm zpiezo response per applied Volt
74 photoSensitivity (Vphoto/Zcant) in Volts/nm
75 Checks for strong correlation (r-value) and low randomness chance (p-value)
77 With the current implementation, the data is regressed in DAC/ADC bits
78 and THEN converted, so we're assuming that both conversions are LINEAR.
79 if they aren't, rewrite to convert before the regression.
81 bump_plot_kwargs, = bump_analyze._splitargs(bump_analyze, kwargs)
82 scale_Vzp_bits2V = Vzp_out2V(1) - Vzp_out2V(0)
83 scale_Vphoto_bits2V = Vphoto_in2V(1) - Vphoto_in2V(0)
84 Vphoto2Vzp_out_bit, intercept = \
85 linfit.linregress(x=data["Z piezo output"],
86 y=data["Deflection input"],
88 Vphoto2Vzp_out = Vphoto2Vzp_out_bit *scale_Vphoto_bits2V / scale_Vzp_bits2V
90 # 1 / (Vzp/Vzp_out * Zp/Vzp * Zcant/Zp )
91 Vzp_out2Zcant = 1.0/ (zpGain * zpSensitivity) # * 1
92 bump_plot(data, **bump_plot_kwargs)
93 return Vphoto2Vzp_out * Vzp_out2Zcant
95 @splittableKwargsFunction()
96 def bump_save(data, log_dir=None) :
97 "Save the dictionary data, using data_logger.data_log()"
99 log = data_logger.data_log(log_dir, noclobber_logsubdir=False,
101 log.write_dict_of_arrays(data)
103 def bump_load(datafile) :
104 "Load the dictionary data, using data_logger.date_load()"
105 dl = data_logger.data_load()
106 data = dl.read_dict_of_arrays(datafile)
109 @splittableKwargsFunction()
110 def bump_plot(data, plotVerbose=False) :
111 "Plot the bump (Vphoto vs Vzp) if plotVerbose or PYLAB_VERBOSE == True"
112 if plotVerbose or config.PYLAB_VERBOSE :
113 common._import_pylab()
114 common._pylab.figure(config.BASE_FIGNUM)
115 common._pylab.plot(data["Z piezo output"], data["Deflection input"],
117 common._pylab.title("bump surface")
118 common._pylab.legend(loc='upper left')
121 make_splittable_kwargs_function(bump_analyze, (bump_plot, 'data'))
123 @splittableKwargsFunction((bump_analyze, 'data'))
124 def bump_load_analyze_tweaked(tweak_file, **kwargs):
125 "Load the output file of tweak_calib_bump.sh, return an array of slopes"
126 bump_analyze_kwargs, = \
127 bump_load_analyze_tweaked._splitargs(bump_load_analyze_tweaked, kwargs)
128 photoSensitivity = []
129 for line in file(tweak_file, 'r') :
130 parsed = line.split()
131 path = parsed[0].split('\n')[0]
132 if config.TEXT_VERBOSE :
133 print "Reading data from %s with ranges %s" % (path, parsed[1:])
135 full_data = bump_load(path)
136 if len(parsed) == 1 :
137 data = full_data # use whole bump
139 # use the listed sections
142 for rng in parsed[1:] :
146 zp.extend(full_data['Z piezo output'][starti:stopi])
147 df.extend(full_data['Deflection input'][starti:stopi])
148 data = {'Z piezo output': numpy.array(zp),
149 'Deflection input': numpy.array(df)}
150 pSi = bump_analyze(data, **bump_analyze_kwargs)
151 photoSensitivity.append(pSi)
152 return numpy.array(photoSensitivity, dtype=numpy.float)
154 # commandline interface functions
157 def read_data(ifile):
158 "ifile can be a filename string or open (seekable) file object"
159 if ifile == None : ifile = sys.stdin
160 unlabeled_data=scipy.io.read_array(ifile)
162 data['Z piezo output'] = unlabeled_data[:,0]
163 data['Deflection input'] = unlabeled_data[:,1]
166 def remove_further_than(data, zp_crit) :
168 ndata['Z piezo output'] = []
169 ndata['Deflection input'] = []
170 for zp,df in zip(data['Z piezo output'],data['Deflection input']) :
172 ndata['Z piezo output'].append(zp)
173 ndata['Deflection input'].append(df)
176 if __name__ == '__main__' :
177 # command line interface
178 from optparse import OptionParser
180 usage_string = ('%prog <input-file>\n'
181 '2008, W. Trevor King.\n'
183 'There are two operation modes, one to analyze a single bump file,\n'
184 'and one to analyze tweak files.\n'
186 'Single file mode (the default) :\n'
187 'Scales raw DAC/ADC bit data and fits a straight line.\n'
188 'Returns photodiode sensitivity Vphotodiode/Zcantilever in V/nm.\n'
189 '<input-file> should be whitespace-delimited, 2 column ASCII\n'
190 'without a header line. e.g: "<zp_DAC>\\t<deflection_ADC>\\n"\n'
193 'Runs the same analysis as in single file mode for each bump in\n'
194 'a tweak file. Each line in the tweak file specifies a single bump.\n'
195 'The format of a line is a series of whitespace-separated fields--\n'
196 'a base file path followed by optional point index ranges, e.g.:\n'
197 '20080919/20080919132500_bump_surface 10:651 1413:2047\n'
198 'which only discards all points outside the index ranges [10,651)\n'
199 'and [1413,2047) (indexing starts at 0).\n'
201 parser = OptionParser(usage=usage_string, version='%prog '+common.VERSION)
202 parser.add_option('-C', '--cut-contact', dest='cut',
203 help='bilinear fit to cut out contact region (currently only available in single-file mode)',
204 action='store_true', default=False)
205 parser.add_option('-o', '--output-file', dest='ofilename',
206 help='write output to FILE (default stdout)',
207 type='string', metavar='FILE')
208 parser.add_option('-c', '--comma-out', dest='comma_out', action='store_true',
209 help='Output comma-seperated values (default %default)',
211 parser.add_option('-p', '--pylab', dest='pylab', action='store_true',
212 help='Produce pylab fit checks during execution',
214 parser.add_option('-t', '--tweak-mode', dest='tweakmode', action='store_true',
215 help='Run in tweak-file mode',
217 parser.add_option('-v', '--verbose', dest='verbose', action='store_true',
218 help='Print lots of debugging information',
221 options,args = parser.parse_args()
223 assert len(args) >= 1, "Need an input file"
227 if options.ofilename != None :
228 ofile = file(options.ofilename, 'w')
231 config.TEXT_VERBOSE = options.verbose
232 config.PYLAB_INTERACTIVE = False
233 config.PYLAB_VERBOSE = options.pylab
234 config.GNUPLOT_VERBOSE = False
236 if options.tweakmode == False :
237 data = read_data(ifilename)
239 ddict = {'approach':data} # although it may be any combination of approach and retract
241 params = z_piezo_utils.analyzeSurfPosData(ddict, retAllParams=True)
242 a,b,c,d = tuple(params) # model : f(x) = x<c ? a + b*x : (a+b*c) + d*(x-c)
243 print >> sys.stderr, "fit with", params, ". using zp < %d" % c
244 data = remove_further_than(data, c)
245 except z_piezo_utils.poorFit, s :
246 # data not very bilinear, so don't cut anything off.
247 print >> sys.stderr, "use everything"
249 photoSensitivity = bump_analyze(data)
251 print >> ofile, photoSensitivity
252 else : # tweak file mode
253 slopes = bump_load_analyze_tweaked(ifilename)
254 if options.comma_out :
258 common.write_array(ofile, slopes, sep)
260 if options.ofilename != None :