Getting Started - openpixi/openpixi_pic GitHub Wiki

This manual offers information for the new comers to OpenPixi project. It consists out of the following sections

How do I run OpenPixi?
How do I contribute to OpenPixi?
How do I profile OpenPixi?
How do I trace the particle movement?

How do I run OpenPixi?

Most of the main classes for running OpenPixi are present in org.openpixi.pixi.ui package. If you would like to run the graphical user interface where you can see the particles movement, run MainControlApplet class. Alternatively, if you just want to run the OpenPixi in the command line, run MainBatch.

If you would like to run OpenPixi from command line (instead of from IDE), you can run it through maven command

mvn exec:java -Dexec.mainClass="MAIN_CLASS"

(substitute the MAIN_CLASS for the class you would like to run). For a specific example see the script run in scripts directory (openpixi/pixi/scripts).

How do I contribute to OpenPixi?

To contribute to OpenPixi,

fork the OpenPixi repository,
commit code to your personal fork,
send us a pull request.

How should I set up my own fork in SmartGit client?

Instructions for the SmartGit client.

Set up a local repository to point to your private fork

Create a fork (ONLY do the first step: "First: Fork a repo". Don't do the other steps!)
In SmartGit, select "clone existing repository".
The repository URL is your private fork, e.g. "[email protected]:github_user_name/openpixi.git".
Select a suitable local directory and open in new project; then wait for initial clone.
Open menu > remote > manage remotes.
Add a new remote with name "upstream" which points to the official openpixi repository "https://github.com/openpixi/openpixi.git".
Pull the changes by pressing the "Pull" button. Select remote repository "upstream". Pull.
Now use menu > Branch > Branch Manager.
Click on "upstream/master" in the list of grey entries at the bottom of the list.
Select "Switch to..", create local branch "upstream", and keep checkbox "track remote branch".
Switch to "master".

Now you have "master" that points to your private fork, and "upstream" that points to the official openpixi repository.

Modify your existing local repository to point to your private fork

If you have already checked out the openpixi repository before creating a fork, you can modify your existing checkout so that the new "master" branch points to your fork, and the "upstream" branch points to the official openpixi fork.

Create a fork (ONLY do the first step: "First: Fork a repo". Don't do the other steps!)
Open your existing repository in SmartGit. (The branch "master" is connected to the remote called "origin", which points to the official openpixi repository)
Open menu > remote > manage remotes: There is one remote called "origin" which points at "https://github.com/openpixi/openpixi.git".
Select "origin" and rename it to "upstream".
Add a new remote with name "origin" which points to your private fork, e.g. "[email protected]:github_user_name/openpixi.git".
Pull the changes by pressing the "Pull" button. Select remote repository "origin". Pull.
Now use menu > Branch > Branch Manager.
Click on "origin/master" in the list of grey entries at the bottom of the list.
Select "Switch to..", create local branch "myfork", and keep checkbox "track remote branch".
Select "master" and rename it to "upstream"
Switch to "upstream", then select "myfork" and rename it to "master".
Switch to "master".

Now you have "master" that points to your private fork, and "upstream" that points to the official openpixi repository.

Merge changes from upstream to your local repository

To keep up-to-date with upstream in the future, do the following:

Pull "upstream" (just fetch).
Merge from "upstream/master".

If you want to try out latest features of upstream without changing your private fork, simply switch to "upstream". Don't forget to switch back to "master" when you are done.

Check out other people's work

If you want to take a look at other people's private forks, just create a new remote for them, create a tracked branch, and switch to that branch.

How do I profile OpenPixi?

Since the fast performance of OpenPixi is of great interest to us, it is often desirable to measure the time of the simulation. For collecting the time measurements we use the aspectj framework. The great advantage of aspectj is that it enables us to collect the time measurements only when we really ask for them. To find out more about aspectj see our [aspectj page] (http://github.com/openpixi/openpixi/wiki/AspectJ-in-OpenPixi).

If you want to see some time measurements, you have to first compile the application with maven profile called "aspectj-profile". While this is straight forward when doing so on the command line (mvn compile -P aspectj-profile), it is much more complicated when trying to do so from your IDE (ie. eclipse). To compile the application with "aspectj-profile" from eclipse see our aspectj page.

Once you managed to compile the application with aspectj-profile profile you can get the time measurements from the class ProfileInfo. For instance, if you run the class MainBatch, the time measurements are automatically displayed at the end of the simulation.

How do I trace the particle movement?

If you are developing a piece of code which relies heavily on positions and movement of particles, you can use the built in support for tracing particle movement. With this support you can see how the particle moved in each time step. Additionally, you are also notified if the particle is getting too fast covering distances larger than one cell or even larger than the simulation area itself.

To enable the support for tracing particle movement you have to set the enabled boolean variable in the MovementDebug aspect to "true". This aspect is located in the org.openpixi.pixi.aspectj.debug package. If you are running OpenPixi in Eclipse you should do Project > Clean each time you change this variable. If your are using maven, compile the application with the profile "aspectj-debug". To see how to enable this profile see our aspectj page.