[Tutorial main page]

Creating quenched configurations with the purgaug executable

To generate quenched (i.e. pure gauge) configurations the chroma software package provides the program purgaug. This program uses an input file to specify what you want to calculate. The input file must be written in XML.

An example input file, su3_4448_beta_5.8.ini.xml, is provided which will be used to create 10 configurations of a 4*4*4*8 lattice, for the Wilson gauge action with &beta=6/(g*g)=5.8.

The information the program needs to know in order to do this is the following

• The starting configuration: this can be one generated by the program itself if you need to thermalise. For example if you want a hot or cold start. Or the configuration can be in a external file, for example if you have already thermalised and you want to carry on generating configurations.
• The seed for the random number generator: you always want to keep a record of this so that the results can be reproduced if necessary.
• The number of updates or sweeps to perform: one also needs to specify how often you want to dump out the configuration.
• The gauge action information: in addition to the type of gauge action and the &beta value, one also needs to specify the boundary conditions and the lattice size.
• The Monte Carlo algorithm: the purgaug program uses heat bath and overrelaxation. One needs to specify the number of overrelaxation and heatbath sweeps in each update.
• Inline measurements: it is possible to specify measurements that you want performed on the configurations as they are generated - for example the gauge loops required to calculate the static quark potential. However, in this example we will not specify any as we are only interested in the plaquette, which is automatically generated anyway. Separate programs, for example, chroma can read in the configurations generated and perform measurements so one normally only specifies measurements that you want to perform on every update of the configurations (instead of the ones you dump to a file).

Download the example input file. We will now go through its contents step-by-step (highlighted below in green).

The file starts with the declaration that this is an XML file

This is followed by the root tag

The closing root tag is at the end of the file.

The first significant information provided is the starting configuration:

 <Cfg>
    <cfg_type>WEAK_FIELD</cfg_type>
    <cfg_file>dummy</cfg_file>
  </Cfg>

In this example we wish to thermalise the configurations and so we use a pre-defined configuration generated by the program itself. This is why a "dummy" name is given to the tag for the configuration file name as no external file will be read in. Possible choices for the pre-defined configurations are:

• UNIT: this corresponds to a free field (cold start).
• WEAK_FIELD: this is close to a free field but with small fluctuations.
• DISORDERED: this uses a random gauge field (hot start).

For thermalisation it is not important which gauge field is used at the start.

Next in the file is the tag <MCControl> which contains the seeds for the random generator and the number of updates etc:

  <MCControl>
    <RNG>
      <Seed>
        <elem>11</elem>
        <elem>20</elem>
        <elem>240</elem>
        <elem>30</elem>
      </Seed>
    </RNG>

    <StartUpdateNum>0</StartUpdateNum>
    <NWarmUpUpdates>300</NWarmUpUpdates>
    <NProductionUpdates>200</NProductionUpdates>
    <NUpdatesThisRun>200</NUpdatesThisRun>
    <SaveInterval>20</SaveInterval>
    <SavePrefix>su3_4448_beta_5.8</SavePrefix>
    <SaveVolfmt>SINGLEFILE</SaveVolfmt>
  </MCControl>

These parameters are:

<RNG>

this specifies the seed for the random number generator using 4 integers.

<StartUpdateNum>

this counter specifies the current update number (see later).

<NWarmUpUpdates>

is the number of thermalization sweeps performed by purgaug. No inline meauserment is performed during this stage, with the exception of the Wilson plaquette.

<NProductionUpdates>

this is the total number of updates to perform after the thermalization.

<NUpdatesThisRun>

is the number of updates left to perform (see later).

<SaveInterval>

is the frequency of saving the configurations.

<SavePrefix>

is the filename prefix for the configurations.

<SaveVolfmt>

specify if each configuration should be saved in a single or multiple file.

Note that both <NProductionUpdates> and <NUpdatesThisRun> must be a multiple of<SaveInterval>.

The inline measurements tags follow, which in this case are empty:

  <InlineMeasurements>
  </InlineMeasurements>

The last part of the file specifies the parameters for the gauge action, the lattice and the update algorithm:

  <HBItr>
    <GaugeAction>
       <Name>WILSON_GAUGEACT</Name>
       <beta>5.8</beta>
       <AnisoParam>
            <anisoP>false</anisoP>
            <t_dir>3</t_dir>
            <xi_0>1</xi_0>
            <nu>1</nu>
       </AnisoParam>
       <GaugeState>
         <Name>SIMPLE_GAUGE_STATE</Name>
         <GaugeBC>
           <Name>PERIODIC_GAUGEBC</Name>
         </GaugeBC>
       </GaugeState>
    </GaugeAction>
    <HBParams>
      <nOver>4</nOver>
      <NmaxHB>1</NmaxHB>
    </HBParams>
    <nrow>4 4 4 8</nrow>
  </HBItr>

Most of the parameters are self explanatory:

<GaugeAction>

the wilson gauge action is specified here, with &beta = 5.8.

<AnisoParam>

anisotropy is set to false. Later in the course we will see how one can define a lattice theory with different lattice spacings in the temporal and spatial directions - an anisotropic lattice. However, at the moment we ignore this.

<GaugeState>

periodic boundary conditions are used.

<nOver>

is the number of overrelaxation steps per sweep.

<NmaxHB>

is the number of Cabibbo-Marinari (heat bath) updates per sweep.

<nrow>

is the lattice size. The last number (8 here) is usually the lattice extention in the temporal direction.

Now you can run the program with:

where < Dir > is the path to the course directory.

The -i flag on the command line is used to specify the input file and the -o flag is used to specify the output file. If no input file is specified (you would also need to omit the -i) then the program looks for a file with the name DATA. If no output file (and no -o) is specified the program dumps the output to a file called XMLDAT.

Here the output file is su3_4448_beta_5.8.out.xml.

The program writes some information to the screen (standard output), you should see something like this: log_run_purgaug.dat

The program also produces the following files:

...

...

The configurations are saved in the files starting with the name su3_4448_beta_5.8.lime. The files ending in .ini.xml can be used to restart the simulation in case anything goes wrong (for example if you are running on a supercomputer/cluster and your job runs out of time).

Suppose that for some reason the simulation crashes after the third configuration, you can easily restart the program with:

To understand better how this is achieved let us look at the file su3_4448_beta_5.8.ini.xml3. You will notice that the starting configuration is now su3_4448_beta_5.8.lime3 :

 <Cfg>
    <cfg_type>SZINQIO</cfg_type>
    <cfg_file>su3_4448_beta_5.8.lime3</cfg_file>
  </Cfg>

The <cfg_type> tag now specifies the file format which is SZINQIO and the tag <cfg_file> specifies the file name of the external file to be read in.

The MonteCarlo parameters in the section <MCControl> are also different:

    <StartUpdateNum>60</StartUpdateNum>
    <NWarmUpUpdates>0</NWarmUpUpdates>
    <NProductionUpdates>200</NProductionUpdates>
    <NUpdatesThisRun>140</NUpdatesThisRun>
    <SaveInterval>20</SaveInterval>

There is no need for thermalization, we are already at the 60th update (specified by <StartUpdateNum>), so the next configurations will be labelled as lime4, lime5...., and that we are left with 140 updates of the target of a total of 200.

Extracting the plaquette values:

Normally the thermalisation of the configurations is monitored using the plaquette. If you examine the output file su3_4448_beta_5.8.out.xml you will see it contains the input XML, information on the program (the version of chroma and qdp used, the layout of the lattice - this will be interesting if you are running in parallel on several compute nodes) and then follows values for different plaquettes measured for every update. For example for the third update:

  <Plaquette>
	<update_no>3</update_no>
	<w_plaq>0.738203755900031</w_plaq>
	<s_plaq>0.739175838786953</s_plaq>
	<t_plaq>0.737231673013108</t_plaq>
	<plane_01_plaq>0.746715279761702</plane_01_plaq>
	<plane_02_plaq>0.742085787390048</plane_02_plaq>
	<plane_12_plaq>0.72872644920911</plane_12_plaq>
	<plane_03_plaq>0.736957671353593</plane_03_plaq>
	<plane_13_plaq>0.738277118381423</plane_13_plaq>
	<plane_23_plaq>0.736460229304309</plane_23_plaq>
	<link>0.0174075132860404</link>
  </Plaquette>

The average over all spatial plaquettes is <s_plaq>, the temporal one is <t_plaq> and the total average is <w_plaq>. The planar plaquettes are the individual plaquettes in the different directions. Note that by default the time direction is the 3 direction.

To extract this information from the output XML file which is very long, you may first grep only the lines which contain <w_plaq> and then interpret the output as a regular expression, to be filtered using programs like awk, sed or perl.

For example to extract all the <s_plaq> values you can use the command:

which redirects the output to the text file splaq.txt. Note that the plaquette values measured during the thermalization will be included in the output.

An alternative is to write an xsl style sheet like the one here:strip_plaq.xsl which will extract the w_plaq plaquette values and print them to the screen with the update number if you use the command:

If you want to redirect the output to a file, w_plaq.txt use the command:

Finally you may want to know what other gauge actions/boundary conditions etc are possible. Note that all the capitalised names in the input file su3_4448_beta_5.8.ini.xml are factory keys. If you mistype one of them (and nothing else before it) then the program will exit but before it does so it will dump out a list of correct keys.

Try mistyping the following, in turn

• WEAK_FIELD: this will give you a list of all configuration types that can be generated within the program itself and all the file formats it accepts for external files.
• WILSON_GAUGEACT: this will give you a list of all the pure gauge actions that the program supports.
• PERIODIC_GAUGEBC: this will give you a list of all the boundary conditions that can be imposed.

Note, however, that in order to find out exactly what the gauge actions correspond to you will need to look in the source code. You can do this by looking in the source code itself located in the directory < Dir >/chroma

To learn what parameters need to be specified for these different choices of the factory keys look at the example input files in the test directory:

< Dir >/chroma/tests/purgaug or the other test sub-directories.

[Tutorial main page]