Workshop Collaboration

Update: February 2013: The workshop report is now available:

Multiphysics Simulations: Challenges and Opportunities, D. E. Keyes, L. C. McInnes, C. Woodward, W. Gropp, E. Myra, M. Pernice, J. Bell, J. Brown, A. Clo, J. Connors, E. Constantinescu, D. Estep, K. Evans, C. Farhat, A. Hakim, G. Hammond, G. Hansen, J. Hill, T. Isaac, X. Jiao, K. Jordan, D. Kaushik, E. Kaxiras, A. Koniges, K. Lee, A. Lott, Q. Lu, J. Magerlein, R. Maxwell, M. McCourt, M. Mehl, R. Pawlowski, A. P. Randles, D. Reynolds, B. Riviere, U. Ruede, T. Scheibe, J. Shadid, B. Sheehan, M. Shephard, A. Siegel, B. Smith, X. Tang, C. Wilson, and B. Wohlmuth, International Journal of High Performance Computing Applications, 27(1): 4-83, 2013. Special issue. DOI 10.1177/1094342012468181.

Instructions below for Google Docs and a Mercurial were used when writing this workshop report.

Google Doc: ICiS Multiphysics Workshop Report 2011

This document is accessible only to workshop participants. Contact Lois or Carol for details.

Instructions for Mecurial are below. This repository is accessible only to workshop participants.

1. Install Mercurial

Windows: Install tortoisehg from http://mercurial.selenic.com/downloads/ [This bundles in kdiff3 - a merge tool, and provides a graphical repository browser]

Mac OSX: Install Mercurial from http://mercurial.selenic.com/downloads/. [Select appropriate 10.5 vs 10.6 vs 10.7 binary]

Also install kdiff3 from http://kdiff3.sourceforge.net/ [Mac OSX binary]. And then add '/Applications/kdiff3.app/Contents/MacOS' to PATH in ~/.bashrc.

export PATH=${PATH}:/Applications/kdiff3.app/Contents/MacOS

Next install hgk - the graphical viewer as:

cd /usr/local/bin

sudo curl -O http://selenic.com/repo/hg-stable/raw-file/de9eb6b1da4f/contrib/hgk

sudo chmod a+x hgk

Linux:

- Ubuntu users can do:

sudo apt-get install mercurial tk kdiff3

- Fedora users can do:

sudo yum install mercurial mercurial-hgk emacs-mercurial-el kdiff3

Other OSes: Instructions for additional OSes including alternate windows installers are listed at http://mercurial.selenic.com/downloads/

2. Configure Mercurial

Edit the following file:

on Windows: %USERPROFILE%\Mercurial.ini

on Linux/Mac: ~/.hgrc

Add the following four lines to the file (replacing username below with your name and email address)

[ui]

username=Satish Balay <balay@mcs.anl.gov>

[hostfingerprints]

hg.icis.anl.gov = 8a:64:8f:03:81:e8:77:e4:81:f0:1b:49:9c:f4:eb:d7:34:7b:2c:e5

[Linux/Mac] to get 'hg view' working - add the following two lines :

[extensions]

hgext.hgk =

[Mac] to use kdiff3 with 'hg merge' - add the following four lines:

[extdiff]

cmd.kdiff3 =

[merge-tools]

kdiff3.args = $base $local $other -o $output

3. A Sample ~/.hgrc File

The following are the contents of my ~/.hgrc file [on Mac OSX 10.6]

[ui]

verbose=true

username=Satish Balay <balay@mcs.anl.gov>

editor=emacs -nw

[hostfingerprints]

hg.icis.anl.gov = 8a:64:8f:03:81:e8:77:e4:81:f0:1b:49:9c:f4:eb:d7:34:7b:2c:e5

[extensions]

hgext.hgk =

[extdiff]

cmd.kdiff3 =

[merge-tools]

kdiff3.args = $base $local $other -o $output

4. Test Mercurial and kdiff3 (optional; this step can be omitted)

Try invoking the following commands:

hg clone http://petsc.cs.iit.edu/petsc/tutorials/summer11

cd summer11

hg pull http://petsc.cs.iit.edu/petsc/tutorials/summer11-bigchange

hg merge

hg commit

hg view

hg log

hg help

Notes:

- The merge command above should invoke kdiff3 to help with the manual merge. [But normal workflow might not have merge conflicts - in which case mercurial will do automerge - and not invoke kdiff3]

- On windows with tortoisehg - use 'thg' instead of 'hg view'

5. Obtain the Mercurial Repository for the ICIS Multiphysics 2011 Workshop Report

1. Obtain Mercurial password from Mike McCourt <mjm458@cornell.edu>. Either hit me during a session, or email me a userid you'd like and I'll send you a password back.

2. Make sure you've added [hostfingerprints] section to mercurial config file as mentioned above. [otherwise the clone below can fail]

3. Obtain a clone of the report repository with:

hg clone https://hg.icis.anl.gov/multiphysics11/report icis-multiphysics11-report

[prompt for userid and password]

hg clone https://userid:passwd@hg.icis.anl.gov/multiphysics11/report icis-multiphysics11-report

Note: the URL for the remote clone is stored in .hg/hgrc file in the local clone created. So subsequent push/pull operations use this URL as default. The difference between the above 2 usage modes [ without and with userid:password specified in the URL] is: in the first mode - the userid,password has to be typed in at the prompt with each clone,push,pull operation - but no such retyping is needed for the second usage.

6. Obtain the Multiphysics Examples Repository

Please follow instructions from step #5 above, with the following URL.

hg clone https://hg.icis.anl.gov/multiphysics11/examples icis-multiphysics11-examples

hg clone https://userid:passwd@hg.icis.anl.gov/multiphysics11/examples icis-multiphysics11-examples

Note: The same userid,password should be used for both 'report' & 'examples' repositories.

7. Using Mercurial: Basic Workflow

1. [Assuming you already have a local clone of a remote repository - and no local changes yet,] Get the latest changes from the remote repository - before starting local changes

hg pull -u

2. Make changes to working files in the local clone.

3. Check the changes [wrt the previous repository state] with:

hg status

hg diff

4. Commit the changes to the local repository with:

hg commit

5. Now push these commited changes to the remote repository. This might involve obtaining commited changes from the remote repository and merging with local changes.

hg pull

hg merge

hg commit

hg push

Notes:

- If there are no new changes in the remote repository to pull - then the merge operation [and a subsequent commit operation] is not needed.

- 'hg pull -u' is equivalent to 'hg pull [from remote repo metadata to local repo metadata]; hg update [from local repo metadata to local repo working files]'

8. Using Mercurial: Alternative Workflow

The following workflow is equivalent to SVN usage of 'svn update; edit; svn update; svn commit'. It is listed for illustration purposes.

1. Get the latest changes from the remote repository - before starting local changes

hg pull -u

2. Make changes to working files in the local clone.

3. Check the changes with:

hg status

hg diff

4. Obtain changes from the remote repository - and perhaps merge them with local changes [similar to 'svn update'].

hg pull -u

5. Now do the following in quick succession [similar to 'svn commit'].

hg pull -u; hg commit; hg push

Note: since mercurial does not have a concept of locking the remote repository similar to 'svn commit' - the above illustartion shows pull,update,commit,push in quick succession as the equivalent [assuming no-one else pushed in the meantime]. Or If the first pull-update takes extra time - [4] - doing pull-update again [5] until it is a no-op - will satisfy the 'quick succession' criteria.

9. Difference between Mercurial and SVN

Mercurial is a distributed version control tool, where the revision history/metadata exists in each clone. In contrast, for SVN the metadata is in the central repository, and the clones just have working files. i.e.,

SVN: metadata <central repo>

workingfiles

Mercurial: remote-metadata <remote repo>

local-metadata <local clone>

working files <local clone>

So, transmitting changes in either direction is a 2-step process in Mercurial [as opposed to a single locked step in SVN].

hg pull; hg update

hg commit; hg push

10. Additional Mercurial Resources

http://mercurial.selenic.com/wiki/UnderstandingMercurial

http://mercurial.selenic.com/learn/

http://ivy.fr/mercurial/ref/v1.0/Mercurial-QuickStart-v1.0-300dpi.png

http://ivy.fr/mercurial/ref/v1.0/Mercurial-Usage-v1.0-300dpi.png