KITPC Lattice Workshop 2009 MILC Code Basics

Objectives

In this tutorial you will first learn how to use precompiled MILC code to run a small RHMC molecular dynamics simulation of QCD with three light quarks using the asqtad action. You will learn the purpose of some of the input parameters and how to modify them. Then you will learn how to build variants of the code. Finally, you will learn how to download and unpack the code.

The first exercises in this tutorial assume that you have a precompiled, installed version of the code. The later exercises show how to unpack and build it.

Contents

Exercise: Running su3_omelyan_rhmc

In this exercise you will run a few molecular dynamics steps of the asqtad dynamical fermion code using the RHMD and RHMC algorithms and experiment with setting the optimum step size. Before we do this, let's run the test example.

Please start from the directory with the executable code: 


   cd $MILCHOME/v7.6.3/ks_imp_rhmc

Run the test code and generate an output log file using the command 


   ./su3_rhmc < in.sample.su3_omelyan_rhmc.1 > out.test.su3_omelyan_rhmc.1

It takes a couple minutes to complete. When the job is finished, have a look at the output file. If you are successful, your output log file out.test.su3_omelyan_rhmc.1 should agree pretty much with the sample output file 


   out.sample.su3_omelyan_rhmc.1

A glance at the output

This example starts with a preexisting 64 lattice and runs a two-trajectory dynamical asqtad fermion molecular dynamics evolution with twelve integration steps of size 0.01. Have a look at the sample output file. The first couple hundred lines echo the various input parameters. The actual execution log begins with the line "Restored binary gauge configuration..." The remaining information reported in this log includes The integration algorithm is hybrid Monte Carlo. Look for the line containing "delta S". This line reports the change in the action over the trajectory. In this example both of those lines should begin with "ACCEPT", showing that the Metropolis decision was to accept the change for both trajectories.

A glance at the input parameters

 The files in.sample.su3_omelyan_rhmc.1 and rationals.sample.su3_omelyan_rhmc contain the input parameters for the calculation. The former is the primary input parameter file. The latter gives the rational function parameters. (The code for generating it is in the subdirectory remez-milc. We won't be practicing that here.) Please have a look at the primary input file, in.sample.su3_omelyan_rhmc.1. The lines consist mostly of tag, value pairs. The first word is the tag and the rest, the value. This input file has been annotated with comments (lines beginning with hash #) indicating the purpose of each value.

Exercise: Modifying the input parameters

 Make a copy of the input parameter file and edit the copy.

Find the line that specifies the number of steps per trajectory and change it from 12 to 6.

Find the line with the command forget, signifying that the resulting gauge configuration file is not written. To write the resulting configuration to a file, change this command to 


  save_serial lat.test

After you make these changes, try rerunning the job. See that it does what you requested.

Exercise: Building the MILC code

Now that you are an expert at running the code, we turn to building the code. Normally you would first need to unpack the distribution tar file, but we have done that for you already. In the same subdirectory ks_imp_rhmc, please find the file Makefile. In this exercise you are first to edit the Makefile to use a different integration algorithm. Find the line 


   KSRHMCINT = -DINT_ALG=INT_OMELYAN

and change it to 


   KSRHMCINT =-DINT_ALG=INT_3G1F

This integration algorithm does three gauge-force updates for one fermion-force update. This time, let's make the RHMD (rational hybrid molecular dynamics) algorithm, i.e. the one that omits the Metropolis accept/reject decision. So run the command 


   make su3_rhmd

You might want to rename the executable to su3_rhmd_3g1f so your remember the different algorithm.

When you have compiled the code, rerun it with the original input parameter file. Because both trajectories were accepted before, you should get the same result, except that the line showing the change in the action begins with CHECK instead of ACCEPT. Note, also, that at the top of the log file the name of the integration algorithm has changed.

Exercise: Starting a Markov chain

In this exercise we start from a very small unit gauge configuration and run ten molecular dynamics trajectories. The objective is to reach equilibrium efficiently. The input file in.test.su3_rhmd sets the integration step size to 0.2 and runs ten steps per trajectory for ten trajectories. This is a rather large step size, but it is chosen to allow a rapid approach to equilibrium. However, when we do so, we can't use the Metropolis accept/reject decision. To see why, try running the RHMC algorithm su3_rhmc with this input file. 


   ./su3_rhmc < in.test.su3_rhmd > out.test.su3_rhmc

Look at the delta S lines. They should show that the trajectories are all rejected, so we make zero progress.

Next use the RHMD algorithm 


   ./su3_rhmd < in.test.su3_rhmd > out.test.su3_rhmd

If you examine the lines reporting the plaquette value 


   grep PLAQ: out.test.su3_rhmd

you should see the value falling rapidly toward equilibrium.

Let the code run to completion so it writes a final lattice file lat.test.

Exercise: Optimizing the step size

The initial ten trajectories in the previous exercise should be enough to allow us to run the RHMC algorithm starting from the saved lattice. The next objective is to select an integration step size that gives a reasonable acceptance rate. The input file in.test2.su3_rhmc is designed to read the output lattice from the previous exercise and run ten more trajectories of unit length. In this case we want to monitor the acceptance rate. In actual practice, we would probably want to run fifty or so trajectories in each trial before adjusting the step size. Here we will play with only ten trajectories. 


   ./su3_rhmc < in.test2.su3_rhmc > out.test2.su3_rhmc

Experiment with the step size to see what it takes to bring the acceptance rate up to approximately 80%. As you adjust the step size, keep the total length of the trajectory approximately equal to one unit. That is, if you reduce the step size by a factor of two, you should double the number of steps per trajectory.

Exercise: MPP compilation

 The code you have been working with so far is single-processor code. To build multiprocessor parallel (MPP) code, you would uncomment the line MPP = true in the Makefile and then check that the correct compiler choice is given in the line CC = mpicc. The KITPC lab machines are not set up for this, so go on to the next exercise.

Exercise: Obtaining and unpacking the MILC code

 If time permits, you may practice downloading and unpacking the code. The distribution is available from the URL http://www.physics.utah.edu/~detar/milc/milc_qcd.html.

It is best to practice the download in a fresh directory. For example 


   mkdir $MILCHOME/milc-test
   cd    $MILCHOME/milc-test

Once you have downloaded the tarball milc_qcd-7.6.3.tar.gz, the first step is to unpack the component tar files with 


    mkdir v7.6.3
    cd v7.6.3
    tar -xzvf ../milc_qcd-7.6.3.tar.gz

The file README_UNPACK explains how to unpack the file. We give a quick explanation here, as well. If you want all the components of the code, you then run 


    make -f Make_unpack all

If you are interested only in the RHMC staggered fermion code, you could unpack selectively with 


    make -f Make_unpack ks_imp_rhmc

Exercise: Configuring the MILC code

Once you have unpacked the code suite, you may proceed to build a particular target executable. Do this by going to the application directory, say ks_imp_rhmc, and copying the top-level default Makefile there 


    cd ks_imp_rhmc
    cp ../Makefile .

We do not use Gnu configure, so you need to edit the following files: ks_imp_rhmc/Makefile, libraries/Make_vanilla, and possibly include/config.h. You have already seen how to edit ks_imp_rhmc/Makefile. The makefile libraries/Make_vanilla is used to build a single-processor linear algebra package required in any of the target compilations. For the Make_vanilla, you should simply verify that the compiler requested on the CC line there is compatible with the compiler on the CC line in ks_imp_rhmc/Makefile. The entries in include/config.h make it possible to adjust the compilation to the local system environment. Since operating systems are converging to common standards, usually nothing needs changing there.

Once you have finished with these preliminaries, you are ready to make your executable, just as you did in the earlier exercises.