Apple Open Sources Grand Central Dispatch

Apple has released the source code for Snow Leopard's new Grand Central Dispatch under an Apache-style license. Grand Central Dispatch lets programmers easily take advantage of modern multi-core hardware. The Apache licensing means it can be safely used in projects wishing to keep the rest of their code proprietary. This is great news for folks writing code that needs lots of horsepower and needs to run on multiple platforms.

Links:
Grand Central Dispatch code at Mac OS Forge
MacResearch article discussing the release
Apple's Grand Central Dispatch Technology Briefing
Introducing Blocks and Grand Central Dispatch (Must be a registered Apple Developer to access this article)

Technical Note For Windows Programmers: Grand Central Dispatch uses a technology known as Blocks. Blocks require a language extension to C or C++ known as Lambdas. This language extension has been added to the publicly available GCC compiler and has been submitted for inclusion for the next version of the C programming language. But I don't think it's part of Microsoft's Visual Studio development environment. The proposed extension differs syntactically from Microsoft's Lambda extension. Bottom line, if you want to use Grand Central Dispatch on Windows, you'll want to use the GCC compiler.

Custom POOMA Particles And The Standard Model

POOMA provides the ability to define custom particles that you can use in your physics simulations. Now, a "particle" in POOMA can be anything, baseballs, planets, imaginary particles, whatever you want. In this post we're going to create definitions for the particles from the standard model of quantum physics. If you want to brush up on the standard model, you can find a good description of it at Wikipedia's Standard Model page. You can download the code being discussed in this post (just one header file) from The POOMA Add-On Project at SourceForge. A short POOMA program that uses these custom particles is here.

IMPORTANT NOTE: While all the main particles from the standard model are created, they are treated in a "classical" manner in the classes we create. That is, their positions, charges, velocities, and so on, are all precisely known.

Extending POOMA's Particle Template
You create a custom particle in POOMA by extending the Particle Template. The class you create can contain any data you'd like. You'll certainly want to store the information that applies to your custom particle type in this class. However, it also seems to be customary to include Vectors of information for all instances of your class where the information changes from particle to particle. For example, because the positions of the instances of your particles will all be different, it's customary to include a Vector in your particle class to store the positions of each particle.

This post will discuss the header file that defines the particles of the standard model. First we will look at the base class, CustomParticle, and then the derived classes.

The CustomParticle Base Class
The CustomParticle class is the base class for all the other classes we'll define. It has a protected constructor, so it can't be instantiated. You'll need to instantiate one of the derived classes.

A description of the members is provided below:

*) getMass() Returns the mass of the particle, measured in MeV.
*) getCharge() Returns the charge of the particle.
*) getSpin() Returns the spin of the particle.
*) getName() Returns the name of the particle. Example names are Electron, Photon, and Charm Quark.
*) getInteractsWithStrong() Returns true if the particle interacts with the strong force, or false if it doesn't.
*) getInteractsWithElectromagnetic() Returns true if the particle interacts with the electromagnetic force, or false if it doesn't.
*) getInteractsWithWeak() Returns true if the particle interacts with the weak force, or false if it doesn't.
*) getInteractsWithGravity() Returns true if the particle interacts with the gravity, or false if it doesn't.
*) getInteractsWithParticle() Pass this function a particle and it will return true if this particle interacts with it, or false if it doesn't.
*) getLifetime() Returns the lifetime of the particle in seconds. A value of -1 means the particle lasts forever.
*) isFermion() returns true if a particle is a fermion, false if it is not.
*) isBoson() returns true if a particle is a boson, false if it is not.
*) isQuark() returns true if a particle is a quark, false if it is not.
*) isLeption() returns true if a particle is a lepton, false if it is not.
*) DynamicArray< PointType_t, AttributeEngineTag_t > pos This is an array that will store all the positions of particles of a given type.
*) DynamicArray< PointType_t, AttributeEngineTag_t > vel; This is an array that will store all the velocities of particles of a given type.
*) globalCreateAndSetRandomPositionsAndVelocities() This function will create a given number of objects, all of the same particle type and set their positions and velocities to random values. Pass this function the number of particles to create, a seed for the random number generator, and true or false depending on if you want velocities to be randomized or zero.
*) getDistance() This is a static helper function that will return the distance between two vectors. Pass it the position of two particles and it will return their distance.

The Derived Particle Classes
There are derived particle classes for each of the three types of matter, Quarks, Leptons, and Bosons. These classes have protected constructors and cannot directly be instantiated. Instead, you'll create objects from classes that derive from these classes. A class inheritance diagram is provided below. Only the classes that inherit from Quark, Lepton, and Boson can be instantiated.


Inheritance Diagram. Click picture for larger image.

There is also an enumration called ColorCharge. This defines the color charge that quarks have. There is also a GluonColorCharge enumeration for gluons. The base class for all quarks, Quark, and the Gluon class have getColorCharge() and setColorCharge() methods for their ColorCharge.

The Fermion class serves as the base for the Quark and Lepton classes. Fermion has values for weak isospin, weak hypercharge, and generation. These values are set by the constructor of derived classes and can be obtained using the getWeakIsospin(), getWeakHyperCharge(), and getGeneration() methods.

Additionally, quarks have charm, strange, top, bottom, isospin, and baryon number values. These values are set by the derived quark classes and can be obtained with the methods getCharm(), getStrange(), getTop(), getBottom(), getIsospin(), and getBaryonNumber().

Similarly, leptons have leptonic electronic number, leptonic muonic number, and leptonic tauonic number values. These values are set by the derived lepton classes and can be obtained with the methods getLeptonicElectronicNumber(), getLeptonicMuonicNumber(), and getLeptonicTauonicNumber().

Using Custom Particles
Finally, we want to use our custom particles in an actual POOMA program. If you haven't done so already, you can download the test program from here and the custom particle file from here.

The test program creates a bunch of electrons with zero velocity and places them in an imaginary box. The electrons bounce around the box driven by their own repulsive force to each other. Every time step the positions of the electrons is printed to standard out.

Getting POOMA Data For Use In Cocoa

POOMA ALife Data Running In An iPhone.

In the previous post we covered how to build the physics engine known as FreePOOMA on a Macintosh and how to write a simple Cocoa application that starts and stops POOMA. In this post we'll look at how to grab the data POOMA has calculated and use it in a Cocoa application.

Using C++ Code in Cocoa Objective C Programs
The first thing we need to do is enable the use of C++ code in a Cocoa program. There are two ways to do this.

The first way is to change the file extension of any Objective C file that needs to also use C++ from ".m" to ".mm". We did this in the example from the previous post.

The second way is to right click the file in the Groups & Files window and select Get Info from the popup menu. Then click the General tab. Find the section named File Type. You see a drop down list box there. Use the list box to change the file type to sourcecode.cpp.objcpp.

You only need to do one of these methods, not both.

Directly Grabbing FreePOOMA Domains
POOMA stores data in Engines and Engines have a Domain that contains the actual data. So for a given object, you want to grab its Domain in order to gain access to its data. The example below shows how to do this for a POOMA Array.

Domain<1, MyDataType>& oDomain = MyPOOMAArray.totalDomain();

As you can see, Domains are templates. The first template parameter specifies the number of dimensions in the Domain. The second template parameter specifies the data type the Domain stores. Once you have a Domain, you can pull data from it using the bracket operator, [], as shown below.

MyDataType& oMyData = oDomain[0];

From here you can perform any operation supported by the data type being used.

Parsing POOMA Data From Strings Programatically
Many POOMA objects can send their data to a stream. You can use this functionality to send POOMA data to a string stream, and then parse the resulting string. An example is shown below.

stringstream oStream;

oStream << MyPOOMAArray;

string strData = oStream.str();

parseString(strData); // custom function to parse the string and pull the needed data from it.

In the docs directory of the FreePOOMA install you will find tutorials in HTML format. Tutorial 11 discusses sending the data contained in POOMA objects to streams.

Parsing POOMA Data From Strings Manually
Finally, when debugging your program in XCode you can print POOMA data to the gdb console by sending it to the cout stream. You can then open the gdb console, copy the data and manually edit it to fit whatever format you need. Other programs can then use this data without the need to actually run POOMA. A code sample of how to do this is shown below.

cout << MyPOOMAArray; // Put a break point here.

In this case we put a breakpoint on the line of code shown above. Just before the code executes we open the gdb console and clear the log using the "Clear Log" button located at the upper right corner of the gdb console window. Then we step over the line of code shown above. Finally, we open the gdb console again and copy the resulting printout. Paste this information into TextEdit or some other editor and change it into the format you need to read it in your program.

The images below illustrate these steps. These images were taken while running a slightly modified version of the ALife example program provided with the FreePOOMA install.


Image 1. POOMA data in the gdb console. Click image for larger picture.


Image 2. The edited version of the gdb console data. It's now a C array. Click image for larger picture.

The movie at the beginning of this post shows the POOMA ALife data being used by an application running in an iPhone. Because we manually added the data to the program, FreePOOMA does not need to run on the iPhone.

Building POOMA on a Macintosh

FreePOOMA is an open source project for physics. The FreePOOMA web site describes the project like this:

FreePOOMA is a C++ library supporting element-wise, data-parallel, and stencil-based physics computations using one or more processors. The library automatically handles all interprocessor communication, obviating the need for any explicit communication code. The library supports high-level syntax close to mathematical or algorithmic syntax (like Fortran 95), easing the conversion from algorithms to code.

You can find the FreePOOMA project here: FreePOOMA web site
And a useful manual for the project here: POOMA manual

But the instructions for building FreePOOMA on a Macintosh cover the old CodeWarrior development environment. So this post will show the steps needed to build FreePOOMA on a modern Macintosh computer and create XCode projects that use FreePOOMA.

Getting FreePOOMA Source Code
To get the FreePOOMA source go to the download page and download their zipped tarball, or just click this link. Unzip the file using Stuffit Expander or a similar tool. UNIX geeks can open a terminal and type tar xzvf pooma-2.4.1.tgz.

Configure FreePOOMA
Before FreePOOMA can be built, it must be configured. To do this, follow these steps:

*) Open a terminal window. You can do this by typing "terminal" in Spotlight and starting the terminal application.
*) Use the "cd" command to change to the FreePOOMA root directory. The location of this directory is based on the location where you unziped the tarball. An example command would be cd /Users/[UserName]/Desktop/freepooma-2.4.1.
*) Type ./configure --arch LINUXgcc and hit return.
*) Type export POOMASUITE=LINUXgcc and hit return.
*) Type make and hit return.

This will create a file named PoomaConfiguration.h in the lib/LINUXgcc under your FreePOOMA directory.

We've now successfully created the FreePOOMA library! Navigate to the lib/LINUXgcc directory and look for a file named libpooma-gcc.a. This is the FreePOOMA library.

Creating A FreePOOMA XCode Project
Now we want to test using the FreePOOMA library in XCode. To do this, follow these steps:

*) Start Xcode and create a new Cocoa application project. Name the project.
*) Open a Finder window and navigate to the folder containing the libpooma-gcc.a FreePOOMA library.
*) Drag and drop the library file into your project. Check the option copy the file into the project.
*) Select the project icon at the top of the Groups & Files window.
*) Right click and select Get Info from the popup menu.
*) Select the Build tab.
*) Navigate to the Search Paths section of the build options.
*) Add a path to the FreePOOMA headers. Where this is located depends on where you downloaded the source code. Here is an example path: /Users/[UserName]/Desktop/freepooma-2.4.1/src
*) Click the "Recursive" check box so that all subdirectories will be searched.
*) Add a path to PoomaConfiguration.h. Where this is located depends on where you downloaded the source code. Here is an example path: /Users/[UserName]/Desktop/freepooma-2.4.1/lib
*) Click the "Recursive" check box so that all subdirectories will be searched.
*) Save these changes and exit the project info window.
*) Rename the file main.m to main.mm.

The above steps perform all the setup you need for using FreePOOMA in an XCode Cocoa application. Now lets write a sample app. Open the main.mm file and edit it so that it looks like the picture below (click the picture for a larger image):



Click the "Build and Go" button and step through the app to make sure everything is working.