FronTier

A C library for fluid-dynamics simulations with front tracking capabilities.

Except for the  public release of the FronTier code, you need a username and password to access the content referenced in this page. Click here for instructions on how to request an account.

Browse the Code

You can browse the code on-line by clicking on the tab Browse Source, or using the hgweb page http://sitsec.ams.sunysb.edu/hg.

Download the Code

You can download the code with one of the following options:

1. Download using Mercurial (for reading and writing);
2. Download using Git (read-only repository);
3. Download using a weblink below without Mercurial or Git.

Downloading the code with Mercurial or Git requires signing in. To learn more about Mercurial (i.e., hg), view the book  Mercurial: The Definitive Guide. To learn more about Git, see  http://git-scm.com/documentation.

There are three key branches in the repository: the default branch, the devel branch, and the contactor branch . The default branch contains a stable version and can be considered as a release candidate. The devel and contactor branches are for active code development, where the contactor branch contains some features for cylindrical coordinates and will be merged with the devel branch in the near future. Students should develop code in the devel or contactor branch to use the most recent bug fixes and test out new features. A nightly build and test is run every day on both the devel and contactor branches.

NOTE: Students should not push changes onto the default branch. Students can push their changes into the devel branch, but this should be done only after careful testing of the changes.

NOTE: The general account "sitsec" has only read-only access. You must have a personal username and password in order to push to the repository.

Download the default Branch with Mercurial

From any machine that allows outgoing HTTP traffic, you can download the most recent version of the code using the command on your UNIX system with Mercurial installed:

hg clone http://sitsec.ams.sunysb.edu/hg FronTier

Use the username and password of this webpage. After downloading the code, it is a good idea to look at the README file.

Download the devel or contactor Branch with Mercurial on Vogon

To use the devel branch, run the following command after downloading the repository:

hg clone -r devel http://yourHGUsername@sitsec.ams.sunysb.edu/hg FronTier
cd FronTier
hg update -r devel

To use the contactor branch, run the following command after downloading the repository:

hg clone -r contactor http://yourHGUsername@sitsec.ams.sunysb.edu/hg FronTier
cd FronTier
hg update -r contactor

You should change yourHGUsername to your own username for the repository. Note that the last two statements may not be needed if you use a newer version of Mercurial (such as v1.0+). The argument FronTier is a local directory name, and you can change it to any other directory name you want, as long as that directory does not yet exist.

Download the devel or contactor Branch with Mercurial on New York Blue (Blue Gene)

Mercurial is not available in the system directory on New York Blue, but it is installed in Prof. Jiao's directory. To use it, edit your ~/.bash_profile to insert the line

PATH=$PATH:/gpfs/home2/xjiao/bin

after the line "# User specific environment and startup programs". Then run the command "source ~/.bash_profile" (without the quotes) in UNIX shell. You can now download the code using command

hg clone -r devel http://yourHGUsername@localhost:8080/hg FronTier

or

hg clone -r contactor http://yourHGUsername@localhost:8080/hg FronTier

After this, the "hg push" will also work. Note: If the port 8080 does not work, please email Prof. Jiao at jiao@….

Download the develor contactor Branch with Mercurial on Other UNIX Machines

If you use any other computer with Mercurial installed and that has HTTP access, you can download the code in the same way as on Vogon.

If you are using a machine that blocks outgoing HTTP traffic (such as Seawulf), then you need to use SSH reverse tunneling to access the repository. Here I use Seawulf as example. From your local computer, ssh to Seawulf using the command:

ssh -R 8080:sitsec.ams.sunysb.edu:80 yourSeawulfUsername@seawulf.stonybrook.edu

Obviously you should change yourSeawulfUsername to your username for Seawulf. This would reverse tunnel port 8080 on Seawulf to port 80 on sitsec.ams.sunysb.edu. (If ssh reports that port 8080 is already in use, try to change 8080 to some other unprivileged port number.) Then you can checkout the devel branch using the command

hg clone -r devel http://yourHGUsername@localhost:8080/hg FronTier
cd FronTier
hg update -r devel

After this, the "hg push" will also work.

Download the Code Using Git

You can download a read-only version of FronTier using Git, which obtains the file from a Git repository that pulls the Mercurial repository every hour. Just like Mercurial, the downloaded version contains all the revision history. However, you cannot push changes to the Git repository, since it is meant to be readonly.

To use Git, you need to first create a file ~/.netrc with the following content:

 machine sitsec.ams.sunysb.edu
 login yourusername
 password yourpassword

Obviously, you should replace yourusername by your own trac-system's username, and replaceyourusername by the corresponding password. The Git client uses this file to obtain the username and password when accessing the server. Since this file is clear-text, you should not use your UNIX's system's username and password for the Trac system. In addition, you should change the file to be readable only by yourself by running command

 chmod 600 ~/.netrc

After you have created ~/.netrc, you can then download the code by running command

git clone -b contactor http://sitsec.ams.sunysb.edu/git/FronTier.git

This will create a directory FronTier, which contains the source code and the revision history on the contactor branch. You need to run git clone only once. Afterwards, you can use git pull to update from the repository. Change contactor to devel to download the devel branch. If you omit -b contactor, then it will download the default branch (or the master branch in Git's terminology.)

Download without Mercurial

If you do not have or do not want to use Mercurial, you can still download the code in one of the following ways:

1. You can download the public release of FronTier at  http://frontier.ams.sunysb.edu/download/.
2. You can also download the current version without the .hg directory in the repository on the default branch (more stable), the devel branch (less stable), or the contactor branch. There will be a revision_id file in the directory to identify the downloaded version. (Smaller download file.)
3. You can also download the current version with the .hg directory in the repository on the default branch (more stable), the devel branch (less stable), or the contactor branch. This produces larger download files than option 2, but it is recommended if you wish to use hg to check the revision history after downloading.

Note that the latter two approaches take longer time, and are password protected (with the same username and password as the hg repository).

Documentations

1. Reference Manual.

Build the Code

To build the FronTier is platform dependent. On Blue Gene/L, Blue Gene/P, and Vogon, most users can build FronTier using one single command:

./build.sh

which builds with optimization and with packages which are most commonly used, or

./build.sh -d

which builds with debugging. You can run build.sh with the -h option like

./build.sh -h 

to see additional options.

Run the Code

To get started, go to the example and example3d directories to build and run simple test programs.

Update and Commit into the Devel Branch

To update your working FronTier directory, perform

    cd FronTier/
    hg pull -r devel
    hg update

• Note that hg pull only brings the updates into your local repository (.hg). You must run hg update to actually get the latest updates into your working directory.

After debugging and testing your changes, you can upload your changes to the devel branch of the central repository by issuing the commands

    cd FronTier/
    hg commit -u yourname
    hg push

After you issue hg commit -u yourname, an editor will pop up for you to type a message for the change. Note that "yourname" need not be your username for the hg repository. The name is saved in the log and is useful for others to see who made the change. A good practice is to use your full name. You can customize it by adding the following lines (for example) to your FronTier/.hg/hgrc file:

    [ui]
    username = Duo Wang
    editor = vi

Now you can simply perform hg commit instead of hg commit -u yourname.

• By default "hg commit" will commit all the changes you have made, you can specify the directory or files you want to commit by "hg commit dir" or " hg commit dir/file"
• If you want to abort the commit, just exit the editor without saving any information you have typed.
• Similar as "hg pull", "hg commit" only commit your changes into your local repository (.hg). You must run hg push to send you changesets into the central repository. You can view your changes here.
• You can commit many times before running hg push. This is useful when you made several small changes.

Merge Branches (Advanced)

The default branch (or the main trunk) is merged to the devel branch periodically (nightly) and automatically. In other words, the devel branch almost always contains the most recent changes in the default branch.

To merge the devel branch onto the default branch, it can be done in the following steps:

1. Backup your repository before proceeding with the merge. This is a good idea in case you make any mistake when resolving conflicts during merging. You can backup using tar or using hg clone.
2. Make sure your repository is up to date. Suppose your FronTier work directory is FronTier_workdir on Vogon, perform:

     cd FronTier_workdir/
     hg pull -r default ~linli/FronTier
     hg pull -r devel http://sitsec.ams.sunysb.edu/hg
   

   For the last command, you must enter your username and password for the hg repository.
3. Perform the merge.

     hg update -r default
     hg merge -r devel
   

   Now your working directory will contain a merged version of the default and devel branches. Note that during hg merge, Mercurial should be able resolve most of the differences. When there are conflicts, a GUI will be loaded automatically for you to manually resolve the conflicts.
4. Commit your changes.

     hg commit -m "Merged with devel branch."
   

   This will commit your merged results into your local repository. (The remote repository is unaffected.)

Most commonly used hg commands

1. clone from the web devel version:

   hg clone -r devel http://yourHGUsername@localhost:8080/hg FronTier
   cd FronTier
   hg update -r devel
   

2. clone from other places (for example ~linli/test1/FronTier):

   hg clone -r devel ~linli/test1/FronTier
   

3. view current banches:

   hg view  
   

This command should be used inside your FronTier directory

4. see which branch you are in:

   hg branch
   

If you are not on the right branch (in particular, devel), then run "hg update -r devel" to change to the correct branch.

5. see all heads:

   hg head
   

6. commit your personal change:

   hg commit
   

7. push to the web (caution, better to send your change to me instead of

push yourself, especially for new users).

hg push

8. pull from previous source:

   hg pull
   hg update
   

It is a good idea to use "hg pull -r devel" so that you don't need to worry about the other branches.

9.

hg help

will show all possible commands and

hg help cmd

will show all options for the hg command "cmd"

Some Tips of Using Mercurial

1. Always use the '-r devel' option when you clone (even when you clone a working copy that is already in the devel branch). Run "hg branch" to check that you are actually working on the devel branch instead of the default branch. If it is not in the devel branch, run the command "hg update -r devel".
2. Always try your best to make sure the modification you made doesn't introduce some bugs which will affect other people before you push to the repository.
3. When adding or removing a file, use "hg add" or "hg remove" so that we can track this change in the repository. If you rename a file, use "hg mv old new" or "hg rename old new". There are some other useful options of hg which you can see by issuing the command "hg help".
4. Update the devel branch everyday before you work to include other people's modification. That may fix the bug you have and you may also check other people's change at http://sitsec.ams.sunysb.edu/trac/timeline.
5. If you make a major change, you should get the permission of Prof. Li before you push it to the central repository.
6. Hg can now be used on both Vogon and Blue Gene, so try to use it. If you still want to move your modified version of the code between Blue Gene and Vogon by hand, include the .hg subdirectory so that you can use "hg diff" to keep track of changes. (The "make tar" facility has been updated to include the .hg subdirectory. Don't try to remove it.)

Logs of Nightly Build and Test

A nightly build is run on the devel branch on the following platforms:

1. Vogon. See the log file at http://sitsec.ams.sunysb.edu/nightlytest/testfrontier_vogon.log.
2.  Seawulf. See the log file at http://sitsec.ams.sunysb.edu/nightlytest/testfrontier_seawulf.log.
3.  NYBlue/L. See the log file at http://sitsec.ams.sunysb.edu/nightlytest/testfrontier_bgl.log.
4.  NYBlue/P. See the log file at http://sitsec.ams.sunysb.edu/nightlytest/testfrontier_bgp.log.
5.  NCSA Abe Linux Cluster. See the log file at http://sitsec.ams.sunysb.edu/nightlytest/testfrontier_abe.log.
6. A PC. See the log file at http://sitsec.ams.sunysb.edu/nightlytest/testfrontier_pc3.log.

Autotest:

Please refer to Autotest for Autotest outputs and information.