HackLatt 2008 MILC Code Basics
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.
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
Please start from the directory with the executable code:
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
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
- on lines beginning with "PLAQ", values of the plaquette operator,
- on lines beginning with "ACTION" and "FACTION", the several
contributions to the full action and fermion action
- on lines beginning with "DG", the several contributions to the
change in the action since the last measurement
- on lines beginning with "PBP", the chiral condensate for both
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,
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
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
and change it to
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
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
Exercise: Obtaining and unpacking the MILC code
If time permits, you may practice downloading and unpacking the code.
The distribution is available from the
It is best to practice the download in a fresh directory. For example
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
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
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
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.