Chroma Tutorial 1: Lattice Practices, Zeuthen 9-11 March 2011

First example: the XML input file

To use chroma to generate hadron spectroscopy you need a XML input file which specifies what calculation you want to do and how you want to do it. The input file, hadspec.ini.xml, is a basic, simple, example. You can download the file by right clicking the mouse on the link and choosing the option "Save link target as".

XML is easily viewed with a browser of the Mozilla family (using "open file" in the "File menu") - firefox/iceape/iceweasel/icecat: you can contract or expand the XML by clicking on the "+"'s or "-"'s, respectively, next to the tags (XML tags are explained below).

Chroma is designed so that the input files are modular and follow the structure of a lattice calculation. We will do the following:

Compute the meson and baryon spectrum for degenerate quarks using point sources and sinks and the Wilson fermion action. The conjugate gradient algorithm (CG) will be used for the inversions to generate the propagator.

The steps necessary for this calculation are:

Create a source for the propagator.
- Specify a point source and its location (the origin, (0 0 0 0)).
Generate the propagator.
- Specify the fermion action (Wilson), boundary conditions (anti-periodic in time), quark mass (kappa = 0.11), inversion algorithm (CG), residual.
Perform the sink smearing of the propagator.
- Specify point smearing.
Perform the contractions of the propagator to obtain the correlators.
- Specify the correlators to be calculated and the momenta.

Step 3 is in fact unnecessary as point smearing leaves the propagator unchanged. However, chroma expects this step whether the smearing is trivial or more complicated. Note that since we are using degenerate quarks we only need to generate one propagator.

A configuration is required for this calculation. Initially, we will use a small test configuration of lattice size 4x4x4x8 with a gauge field close to free field. This configuration can be generated by chroma on the fly. How we specify this in the input file is described below. How to read in a previously generated configuration will be dealt with in section Modifying the input file.

Now let us look at the input file, hadspec.ini.xml. We will see that it contains the steps of the calculation above. The file begins with the line,

<?xml version="1.0"?>

which just specifies that this is a file written in XML and states the XML version number. This line is not displayed if you view the file with a browser. What follows is the input information wrapped up in "tags". A tag is comprised of a name within a set of <> . The first tag we see is

<chroma>

Tags always come in pairs, a beginning tag, like the one shown above and an end tag, which is the same but with a / in front of the name. If you look at the end of the input file you will see the end tag.

</chroma>

Between the tags can be text, numbers etc or more tags, i.e. tags can be nested. However, any content must be enclosed within tags. The tags you can use and in what ordering are defined within chroma.

The next line illustrates the use of the annotation tag which allows you to add comments to your input file:

<annotation>Hadron spectrum input file.</annotation>

Next we have the "Param" tag, after which the inline measurements are defined.

<Param>

The inline measurements are the modules or tasks you need for the calculation. Each measurement is enclosed by an <elem>, </elem> pair. An inline measurement has

a key, which is always capitalized (specified within the <Name></Name> tags),
a set of parameters (within <Param> </Param>),
named objects associated with it, as the input, output or both (within <NamedObject> </NamedObject>).

Named objects are a way of referring to objects that are created by inline measurements while chroma is running and that are stored in memory.

The inline measurements in the input file, in order, are

MAKE_SOURCE
PROPAGATOR
SINK_SMEAR
HADRON_SPECTRUM

Let us look at the first inline measurement:

    <elem>
      <Name>MAKE_SOURCE</Name>
      <Frequency>1</Frequency>
      <Param>
        <version>6</version>
        <Source>
          <version>2</version>
          <SourceType>POINT_SOURCE</SourceType>
          <j_decay>3</j_decay>
          <t_srce>0 0 0 0</t_srce>
        </Source>
      </Param>
      <NamedObject>
        <gauge_id>default_gauge_field</gauge_id>
        <source_id>pt_source</source_id>
      </NamedObject>
    </elem>

What do these tags mean?

<Frequency>

this tag is only relevant if the inline measurements are being used in conjunction with the hmc or pure gauge configuration generation code. The <Frequency> tag then specifies how often to perform the measurement. Here the frequency is set to 1 and the measurement is always performed.

<Param>

the parameters specific to the MAKE_SOURCE inline measurement are given within this tag.

<version>

this tracks the version of the input parameter XML. The input required for the measurement might be changed but for most older measurements this does not happen.

<Source>

these are the parameters for the creation of the source. There is a version number associated with this input XML.

<SourceType>: specifies what type of source is to be created.
<j_decay>: defines what index (of an array length 4, from 0 to 3) corresponds to time.
<t_srce>: defines the source location. If we were using a smeared source this would be the coordinates of the center of the source.

<NamedObject>

This tag is used to specify the objects that the measurement needs as input and/or produces as output. The objects are given ids so they can be used, once created, throughout the program. To make a source we need the gauge configuration even if it is a point source since the input XML must follow the most general structure. This is loaded automatically at the start of the program. The configuration information is specified at the end of the XML file (see below). The object id for this configuration is fixed to default_gauge_field. The propagator source object produced by this inline measurement is given the id pt_source.

Continuing through the rest of the input file, the three inline measurements which follow have a similar structure to MAKE_SOURCE and most tags are designed to be self explanatory.

    <elem>
      <Name>PROPAGATOR</Name>
      <Frequency>1</Frequency>
      <Param>
        <version>10</version>
        <quarkSpinType>FULL</quarkSpinType>
        <obsvP>false</obsvP>
        <FermionAction>
         <FermAct>WILSON</FermAct>
         <Kappa>0.11</Kappa>
         <AnisoParam>
           <anisoP>false</anisoP>
           <t_dir>3</t_dir>
           <xi_0>1.0</xi_0>
           <nu>1.0</nu>
         </AnisoParam>
         <FermionBC>
           <FermBC>SIMPLE_FERMBC</FermBC>
           <boundary>1 1 1 -1</boundary>
         </FermionBC>
        </FermionAction>
        <InvertParam>
          <invType>CG_INVERTER</invType>
          <RsdCG>1.0e-8</RsdCG>
          <MaxCG>1000</MaxCG>
        </InvertParam>
      </Param>
      <NamedObject>
        <gauge_id>default_gauge_field</gauge_id>
        <source_id>pt_source</source_id>
        <prop_id>pt_src_prop</prop_id>
      </NamedObject>
    </elem>

<quarkSpinType>: This specifies whether we compute all 4 spin components of the propagagor (for which we use FULL) or whether we use a non-relativistic projection onto the upper 2 components (use UPPER) or the lower 2 components (use LOWER)
<obsvP>: This tag is only interesting for 5 dimensional propagators (for example domain wall fermions). It allows for extra observables to be calculated. For 4 D propagators it should be set to false.
<FermionAction>: Here we specify that we want the Wilson action and that the kappa value is 0.11.
<AnisoParam>: If you are using an anisotropic lattice then you use this tag to specify the time direction, t_dir, (which has a different lattice spacing compared to the spatial direction), the bare gauge anisotropy, xi_0, and the fermion anisotropy nu. Since we have an isotropic lattice the anisotropy, anisoP, is set to false and xi_0=nu=1.0. In our case <AnisoParam> is redundant and in fact we could delete the XML between (and including) <AnisoParam> </AnisoParam>.
<FermionBC>: Here the fermion boundary conditions (BC) are specified. We are only interested in the simple cases (SIMPLE_FERMBC) which are defined within an array using the <boundary> tag. (1 1 1 -1) corresponds to anti-periodic BCs (in time), (1 1 1 1) to periodic and (1 1 1 0) to Dirichlet BCs.
<InvertParam>: This tag contains the information on the inverter. <invType> gives the type of inverter, here, conjugate gradient is used. <RsdCG> specifies the residual for the inversion, while <MaxCG> is the maximum number of iterations you want the inverter to use before deciding to stop (i.e. failing to obtain convergence).
<NamedObject>: There are three named objects. The first two are inputs, the gauge field and the propagator source, and the last is for the propagator generated by the inversion.

    <elem>
      <Name>SINK_SMEAR</Name>
      <Frequency>1</Frequency>
      <Param>
        <version>5</version>
        <Sink>
          <version>2</version>
          <SinkType>POINT_SINK</SinkType>
          <j_decay>3</j_decay>
        </Sink>
      </Param>
      <NamedObject>
        <gauge_id>default_gauge_field</gauge_id>
        <prop_id>pt_src_prop</prop_id>
        <smeared_prop_id>pt_src_pt_sink_prop</smeared_prop_id>
      </NamedObject>
    </elem>

The tags for SINK_SMEAR are very similar to MAKE_SOURCE. Remember that this inline measurement is required by chroma before passing the propagator to HADRON_SPECTRUM even if it is a trivial step.

    <elem>
      <Name>HADRON_SPECTRUM</Name>
      <Frequency>1</Frequency>
      <Param>
        <version>1</version>
        <MesonP>true</MesonP>
        <CurrentP>true</CurrentP>
        <BaryonP>true</BaryonP>
        <time_rev>false</time_rev>
        <mom2_max>3</mom2_max>
        <avg_equiv_mom>true</avg_equiv_mom>
       </Param>
      <NamedObject>
        <gauge_id>default_gauge_field</gauge_id>
        <sink_pairs>
          <elem>
            <first_id>pt_src_pt_sink_prop</first_id>
            <second_id>pt_src_pt_sink_prop</second_id>
          </elem>
        </sink_pairs>
      </NamedObject>
      <xml_file>hadspec.dat.xml</xml_file>
    </elem>

<MesonP>,<CurrentP>,<BaryonP>: With these tags you specify whether you want to compute the meson, current and baryon correlators. Even if you put true for <CurrentP> these correlators will only be calculated if you have point smearing for the sink.
<time_rev>: This is only interesting for baryon correlators. For meson correlators the backwardly propagating state is the same as the forwardly propagating one and so is automatically generated when you calculate the correlator (over the whole lattice). For baryons the backwardly propagating state has opposite parity. To increase statistics you can generate the backwardly propagating baryon (and average it with the forward propagating case) by setting <time_rev> to true.
<mom2_max>, <avg_equiv_mom>: The correlators will be calculated for all momenta that have |p|² less than or equal to the value in <mom2_max>. Correlators with equivalent momenta will be averaged if <avg_equiv_mom> is set to true.
<sink_pairs>: Here the propagator combinations are specified using a list of combinations each enclosed by <elem></elem> tags. In our example file only one combination is given. For each combination two propagators are expected, specified in the <first_id> and <second_id> (for HADRON_SPECTRUM the baryons are of the type q₁q₁q₂). In our case all the quarks have the same mass and so we give the same propagator id in both cases.
<xml_file>: With this (optional) tag you can have the correlator data written out to a separate XML file, instead of the normal default output file.

We are now almost at the end of the input file. There are just a few comments to make before we run chroma.

  </InlineMeasurements>
  <annotation>Lattice dimensions.</annotation>
  <nrow>4 4 4 8</nrow>
</Param>
<annotation>Configuration file information.</annotation>
<Cfg>
 <cfg_type>WEAK_FIELD</cfg_type>
 <cfg_file>dummy</cfg_file>
</Cfg>
</chroma>

The list of inline measurements is complete so the end tag </InlineMeasurements> is used. The dimensions of the lattice are now defined and then the end </Param> tag is needed. Finally, the configuration is specified. As mentioned above we are using a configuration which will be generated by chroma itself, which is close to a free field. We specify this using the key WEAK_FIELD in the <cfg_type> tag. As we don't need to read in a configuration any name can be put within the tags <cfg_file></cfg_file>.

[Up][Tutorial main page]