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]
or
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
or
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>
^
|
v
workingfiles
Mercurial: remote-metadata <remote repo>
^
|
v
local-metadata <local clone>
^
|
v
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