Archive for the ‘Examples’ Category

An Introduction to Using Apex

March 9, 2008

Here’s a step-by-step intro to some first steps with Apex. I’ll be trying to add content to this document as I am able.


A Movie Example

March 9, 2008

Here’s a movie I made to show off some of the 3D graphics of Apex. The rotation sequence is produced from a script — the other bits are screengrabs from Apex with different atoms visible in the display.

Its all thrown together with iMovie with a voiceover I recorded late one night, so I sound a little sleepy.

Test Suite Timing Comparisons

January 18, 2007

Part of the release procedure for Apex is that I run the test suite on the compiled app. ‘The test suite’ is currently nine AppleScripts which run Apex through a lot of its paces — importing and exporting files, calculating a proxigram, saving an animation as a QuickTime movie, running the select particles in shell action from the isosurfaceOps plugin, and most recently I’ve added an rdf export.

I run the suite once on a PowerPC machine and once on an Intel-based machine. If the test succeeds, its a pretty good indication that the build is OK to go out the door. It doesn’t catch issues in the GUI, and it doesn’t run through all the functionality, but it gets a good deal. For example, the most recent problem I discovered was that one of the plugins was building for PowerPC only because of a glitch in the XCode config files.

Of course, one of the things that I monitor is how long each script takes, so I can verify that I haven’t screwed anything up too much in making changes for each release. And the other thing is that, having an automated test suite means its pretty easy to move the test to new machines. So I’ve done a little comparison of performance on a few different machines. From slowest to fastest:

G4 PowerBook , 1.25 GHz: 508 seconds
G4 PowerMac, Dual 1.25 GHz: 462 seconds
G5 PowerMac, Dual 2 GHz: 250 seconds
iMac, 1.83GHz Intel Core 2 Duo: 209 seconds
MacBook, 2 GHz Core Duo: 192 seconds
MacPro, Dual 2.66GHz Xeon: 133 seconds

These are all running 10.4.8. All in all, its about what you would expect, but I must say I’m very impressed by the MacBook.

An RDF example using the Apex RDF plugin

December 12, 2006

Apex a43 includes a new RDF generation plugin. Here’s an example of some data taken with the plugin. Thanks to Dieter Isheim of Northwestern University for a sample dataset. In this case, it is the Fe alloy with Ni, Cu and Al, and a number of other components. In the picture below, Cu atoms are in red, and visually they appear in clusters.

First, I use ‘Select Points’ mode to make a simple selection in the dataset. Thats the rectangular area shown where the atoms are drawn slightly darker. This selected range includes about 118,000 atoms, 2093 of which are Cu atoms. These 2093 atoms will be used as the reference points in the RDF calculation.

From Clipboard.gif

I choose the ‘RDF Export’ menu item and select the parameters I want — Cu atoms for reference, 1600 bins and cutoff radius of 40 Ångstroms. I specify the name for the output file, in this case ‘Cu44 3.rdf’. The calculation takes 40 seconds. In that time, Apex has gone through each of the 2093 Cu atoms, found all of the other atoms in the dataset in a 40 Ångstrom radius, and measured the distance to each reference atom and binned all the results, writing out a tab-delimited file. I go to my graphing application proFit , and choose ‘Import’. Here I can specify that the file contains its own column headers,and this is the window that gets created:


In short order, I’ve got a graph that looks like this:


A few things to note. The red line is the most interesting. What it means is that the density of Cu is a lot higher near your average Cu atom than further away: That’s the same thing as seeing the Cu atoms in clusters in the atom map, but in the RDF, you can see how big the clusters are. The plot drops down significantly between 5 and 10 Ångstroms, which is indicative of clusters of about 20 Ångstroms in size. This kind of data is fun to interpret, because it is an average over all the reference atoms, some of which are in the center of a cluster, some of which are near the edge of a cluster, and the clusters aren’t necessarily spherical or uniform in size.

Second thing to note is that the Ni and Al also have slightly higher concentrations near Cu than farther away, but that the Aluminum concentration drops off faster than the Ni — out at a radius of 20 Å, the Ni concentration is double that of the Al. So there is a much stronger correlation of the Al with the Cu than of Ni with Cu.

the Fe concentration stays pretty flat despite a higher density of the other components near Cu atoms. Does this mean that there is actually a higher atomic density in the sample near the Cu clusters? Well, no. There are any number of Atom Probe conditions which might cause this sort of data anomaly: one possibility is that the radius of the tip may change as a function of chemical composition of the tip — and thus the magnification changes, too, producing changes in the apparent density. This effect is quite common. The efficiency of detection may also change as a function of composition — the Atom Probe may only collect 50% of the atoms in any given sample — other are lost due to bad ion optics, or evaporation outside of the pulse window, or multiple atom evaporation, or other electrical noise. Another effect is that some of the reference atoms may be close to edges in the dataset itself, which means that those reference atoms are not surrounded by a 40 Å radius of atoms, which would result in a decrease of the total density with increasing radius.

A common ploy to correct all these effects is to make a plot of concentration, rather than density (Dieter says he prefers that, actually). It is easy to do that in this case, as the total number of atoms is already supplied in the dataset in column 2.

Some RDF datasets also show short range order: that is, down in the 2 -3 Ångstrom range, it is possible to see the effects of first-nearest neighbor positions vs, second or third nearest neighbor positions. This dataset doesn’t show any such interesting pattern.

Lastly, one feature of the RDF that we calculate is the gradually changing binsize. As noted here previously, data analysis in the Atom Probe is often a tradeoff of positional error vs. statistical sampling error. Because the number of atoms at a given radius increases with r squared, we expect to have less error in the measurement at higher radii. In our calculation, we show both lower sampling error and lower statistical sampling error as the radius increases, by decreasing the binsize with increasing radius. This is reflected in the data: At lower radii, the scatter in the data is higher, and there is slightly more distance between the datapoints.

Radial Distribution Function Plugin

December 10, 2006

With Apex a43, there is now a plugin module that calculates a radial distribution function, or RDF. The RDF is one way of analyzing the local environment of atoms in the dataset. The calculation looks at all the neighboring particles of a particular atom (the reference atom), and collects the distance between that reference atom and each neighbor, and the atomtype of that neighbor. This information is compressed onto a single graph, the y axis representing the density of neighboring atoms of each type, and the x axis representing the distance of separation.

Usually, the data collected relative to a single atom is neither representative of the whole sample, nor is the statistical error low enough to have confidence in the results. Typically, the RDFs of many reference atoms are combined into a single plot. The RDF calculation in Apex operates on the current selection, and only on the atoms of a given atomtype.

When RDF calculation is enabled, there is a menu item called ‘RDF Export’ under the Plugins menu. Selecting this menu item offers the following choices for the calculation parameters:


Only atoms of the specified atomtype will be used for the RDF, and only those which are in the current selection. The distribution will be generated as a histogram with the given number of bins, and the last bin will represent radial separation of the specified cutoff radius.

The RDF will be output as a text file with tab-delimited columns and return delimited radius values. This file can be imported into a graphing application such as proFit with little effort.

If you are using proFit, select ‘Open…’ from the profit ‘File’ menu. Select the display ‘All Files’ option to be able to select the generated .rdf file. When importing, you will be presented with this dialog:


Choose the ‘with title’ option from the format popup menu. This will direct profit to use the first line of the text file as the column headers in the generated dataset.

One of the quirks of RDF generation is that as the radius increases, the number of atoms N in a shell of thickness Δr increases with r2. As is common with the interpretation of atom probe data, there is always a trade off between statistical error and positional error. If the binsize were to remain constant in the RDF histogram, this would mean that the statistical error would decrease as a function of 1/r , because the statistical error is proportional to sqrt(N). But because of the constant binsize, the positional error would remain constant through the data. This is non-ideal because at small radii, the statistical sampling error is much higher than the positional error, and at high radii, the positional error is higher than the statistical error. Instead, Apex generates an RDF with a continuously decreasing binsize, so that both the statistical error and positional error decrease with increasing radii proportional to sqrt(1/r). That is, as the radius increases, the binsize gets smaller by a factor of 1/sqrt(r) and the number of atoms per bin gets larger by a factor of r. The choice of number of bins and radial cutoff combine to determine the tradeoff between positional error and statistical sampling error.

As of Apex version a43, the value of the calculated RDF is in units of atoms per cubic Angstrom times the number of reference atoms. This will be changed in the future to be simply atoms per cubic Angstrom, so that the data is invariant to the number of atoms selected. In Apex a44, the units will be Atoms per cubic nanometer.

In addition, the radius value is given as the arithmetic average of the inner radius and the outer radius of the given shell. This is less than ideal for small radii, because for small radii, the number of atoms near the outer radius is higher. In other words, for the shell from radius = 0 to radius = 1, the current RDF labels the bin as r = 0.5, although the mean radius should be close to 0.8. In Apex a44, will have a radius value appropriately weighted toward the higher radius.

The Intel Mac Pro

August 26, 2006

Now that’s a screaming machine. Here’s Apex on Intel:


The colors are a little off on intel — must be a byte switching issue — perhaps ‘ARGB’ became ‘BGRA’ ???

In any case, Calculations are approximately twice as fast compared with my dual G5 machine, and most things just work. I’ll be releasing soon.

– Olof

Filming a Movie

May 29, 2006

A simple script to show how animations are done:

tell application “Apex”
starting the movie
set destinationFile to “Macintosh HD:coercion movie”
start filming of window 1 of document 1 saving in destinationFile
saving movie frames
repeat 90 times
rotate window 1 of document 1 axially 0.1
rotate window 1 of document 1 vertically 1
save movie frame of window 1 of document 1
end repeat
stopping the movie
stop filming of window 1 of document 1
end tell

Basically, there are three phases of the script: starting the filming, saving frames, and stopping the filming.

In this script, the name of the movie is hard coded. That’s a problem if you’d like to run the script a number of times. If you’d like to generate a different name for the movie each time, try doing this:

set secs to (( current date ) – (date “Sunday, January 1, 2006 12:00:00 AM” ))as text
set destinationFile to “Macintosh HD:movie ” & secs

secs will be the number of seconds since the first of the year, so as long as you wait one second between script runs, you’ll have a different name for the movie file. Or perhaps you’d like to name the file with a traditional Mac OS put file dialog. In which case, do this:

set destinationFile to choose file name

You’ll have interesting results if you change the size of the window while the script is running. QuickTime movies have a fixed size, so the size that you start with is the size you’ll get no matter what.

Speeding up a Mass Ranges Script

March 10, 2006

You may have a script which defines a lot of mass ranges and the colors and sizes for each atom type. One of the things that makes this script a little slow is that Apex will redraw the screen live with each change to the graphics state, even though that really isn’t useful until the whole script is over.

To make this script go faster, use the ‘updating atomtypes’ property of an Apex document — while this setting is false, Apex will avoid recalculating all the mass ranges, which saves a bit of time if you start to get a lot of them.

Additionally, you can turn off redraws in the window using the ‘doing redraw’ property of a window — while this is false, the window contents won’t be redrawn.

Be sure to turn these two properties back on when you are done with a script action. Here’s an example script using these two properties:

to setAtomtypeProps(typeIndex, typeColor, typeSize, typeName)
tell application “Apex”
set the color of atomtype typeIndex of document 1 to typeColor
set the size of atomtype typeIndex of document 1 to typeSize
set the name of atomtype typeIndex of document 1 to typeName
end tell
end setAtomtypeProps
tell application “Apex”

set doing redraw of window 1 of document 1 to false
set updating atomtypes of document 1 to false

if ((count mass ranges of document 1) > 0) then
delete every mass range of document 1
end if
make new mass range with properties {name:”Al”, lower limit:13.38, upper limit:13.84, atomtype:4} in document 1
make new mass range with properties {name:”Fe”, lower limit:26.82, upper limit:27.34, atomtype:1} in document 1
make new mass range with properties {name:”Ni”, lower limit:28.88, upper limit:29.26, atomtype:2} in document 1
make new mass range with properties {name:”Ni”, lower limit:29.860001, upper limit:30.24, atomtype:2} in document 1
make new mass range with properties {name:”Ni”, lower limit:30.84, upper limit:31.26, atomtype:2} in document 1
make new mass range with properties {name:”Cu”, lower limit:31.379999, upper limit:32.32, atomtype:3} in document 1
make new mass range with properties {name:”Cu”, lower limit:32.400002, upper limit:33.139999, atomtype:3} in document 1
make new mass range with properties {name:”Cu”, lower limit:62.66, upper limit:64.5, atomtype:3} in document 1
make new mass range with properties {name:”Cu”, lower limit:64.660004, upper limit:66.5, atomtype:3} in document 1
set updating atomtypes of document 1 to true
end tell
setAtomtypeProps(1, {0, 0, 65535}, 0, “Fe”)
setAtomtypeProps(2, {0, 65535, 0}, 1, “Ni”)
setAtomtypeProps(3, {65535, 0, 0}, 1, “Cu”)
tell application “Apex”
set doing redraw of window 1 of document 1 to true
end tell