HackLatt 2008 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 couple molecular dynamics steps of the Asqtad dynamical fermion code using the RHMC algorithm with the Omelyan integrator. The evolution starts from a preexisting gauge configuration.

Please start from the directory with the executable code: 


   cd /opt/localhomes/lab/milc/v7.6.2.beta

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


   ./su3_omelyan_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

The 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. 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. (It is automatically generated by multiprecision code in 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 =#

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: 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 NESC lab machines are not equipped for this, so go on to the next exercise.

Exercise: Other targets

 This package also contains a development-grade dynamical-fermion implementation of the UKQCD/HPQCD HISQ algorithm. Please note, the code is not recommended for production use.

Build the target su3_rhmc_hisq and run it with the sample input file in.sample.su3_rhmc_hisq.1. If you are successful, you should reproduce the output in the file out.sample.su3_rhmc_hisq.1.

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 /opt/localhomes/lab/milc-test
   cd    /opt/localhomes/lab/milc-test

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


    mkdir v7.6.2.beta
    cd v7.6.2
    tar -xzvf ../milc_qcd-7.6.2.beta.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.