[Up][Tutorial main page]

Modifying the input file

Having run through the first basic example, it is now time to modify the input XML to enable you to perform a more realistic calculation.

The best place to look for the input XML you need is in the tests directory of the chroma source code.

The tests directory contains many input files (and the corresponding output files) that are used to test chroma. The files which are most interesting for this tutorial are contained within the directory,

The only problem with looking at the test input files is that often they are not in exactly the form you want. For example, the PROPAGATOR inline measurement may be for an anisotropic lattice when you are using an isotropic one. Some of the XML for an inline measurement may be redundant which can be confusing at the start. Also the values that are used may not be what you want (boundary conditions, residual for the inverter and so on), so you must be careful.

In the following, you can work through modifying the input file to do different things. The idea is that you find out how to make the changes by looking at the examples in the tests directory. However, hints are given, in particular, for the cases where it is not easy to find a suitable example.

"Solution" files for each modification are provided, these can be downloaded here: hadspec_xml.tar.gz. For simplicity all the solution input files only implement one modification in each case. What modification is necessary is then easy to see using the diff command. For example,

will show the changes necessary to use the clover action, the first modification suggested. However, the idea is that you only look at these files after you have had a go yourself. Also, in your own XML it is not necessary go back to hadspec.ini.xml for each new modification.

Note that you can comment out XML using <!-- and -->.

<!-- This line is commented out  -->

Use the clover action

To change the PROPAGATOR inline measurement to use the clover fermion action instead of the Wilson action is straightforward, however, most examples in the tests directory are for an anistropic lattice. The input files for all the different actions available to use with this measurement are in the directory

The input file we want to look at is

The prec_ in the file name refers to "preconditioned". This means that even-odd preconditioning is used for the inversion, which makes the inversion faster (this was also the case for our first example, hadspec.ini.xml, you do not need to specify anything). The unpreconditioned case is discussed later. Search for the tag <FermAct>. The key you need to use for the clover action is clear. Note that you also need an additional set of tags to define the clover coefficient. Since we are using an isotropic lattice you don't need the tags labelled by clovCoeffR and clovCoeffT.

Example solution input file: hadspec_v_action.ini.xml

Use the BiCGStab inverter

BiCGStab is faster than conjugate gradient, however, it is not guaranteed to converge. Look into

Searching for the tag <InvertParam> within this file will show you what modifications are necessary.

Example solution input file: hadspec_v_inverter.ini.xml

Erase objects

To save memory you can erase named objects that are longer needed before going on to create new ones. For example, in hadspec.ini.xml, the source object, with the id pt_source, can be erased after the propagator is calculated. Similarly, the propagator object pt_src_prop could be erased after the propagator is smeared at the sink.

There are many examples of objects being erased in the sub-directories of

For example, look into

Example solution input file: hadspec_v_erase.ini.xml

Write out the propagator

If a propagator is expensive to generate and if it will be needed in later calculations then it makes sense to write it out to a file. You will find the appropriate inline measurement in the input file in the directory:

Note that the examples given mostly use the key MULTIFILE. If you were running the code in parallel this would cause every node to dump out it's own file. In most cases, SINGLEFILE is preferable.

While the propagator is stored in binary, there are XML headers which contain information about the action, inverter and source used, along with other things. If your propagator file is called prop.dat you can view the header by using the more command.

However, a better way to view the contents is using the QIO program lime_contents. This program can be found in the installation directory for chroma. Use the command

You will obtain output similar to the log shown here, which gives information on all the records, xml or binary, written to the file. The propagator has been written out in SCIDAC format (there are IO inline measurements for writing out in other formats, for example NERSC format, see chroma_source_dir/tests/chroma/io/nersc_write_obj). SCIDAC format uses Lattice-QCD Interchange Message Encapsulation format (LIME). More information about these formats can be found in the QDP manual.

Example solution input file: hadspec_v_write_out_prop.ini.xml

Read in the propagator

Once you have written out the propagator you can re-run the calculation reading in the propagator instead of generating it. Look in the directory

to see how it's done.

Example solution input file: hadspec_v_read_in_prop.ini.xml

Read in a configuration

There are two ways to read in a configuration,

• as the default configuration, by specifying the configuration type and file name between the <Cfg> tags. In this case the object id for the configuration is defined as default_gauge_field,
• or by using an inline measurement similar to the one used to read in the propagator (look at the same files). In this case, you can specify your own object id.

To get a configuration to read in, either write out the default gauge field or use one we prepared earlier weak_field_4448.cfg.

Any configuration or propagator written out using the inline measurement QIO_WRITE_NAMED_OBJECT will be in SCIDAC format (this is the key to use for the tag <cfg_type>). If you are reading in an object using QIO_READ_NAMED_OBJECT chroma assumes it is in this format (and you don't need to specify the format explicitly).

To see what formats are available for reading in the configuration as the default_gauge_field mistype the key for <cfg_type> in the input file (this was set to WEAK_FIELD in hadspec.ini.xml). When you run chroma, the program will give a list of possible keys before exiting.

Example solution input file : hadspec_v_config.ini.xml and hadspec_v_read_in_config.ini.xml

Use gauge invariant Gaussian smearing

Point sources for propagators are rarely used in spectroscopy calculations as they have a significant overlap with radially excited states: normally you are primarily interested in the ground state. There are many different smearing functions in use. Here, we will use gauge invariant Gaussian smearing. This is an iterative smearing where the higher the number of iterations used the broader, the wavefunction.

It is also fairly common practice to use "smeared" gauge links when generating the smeared source, for example using 3D APE or stout gauge link smearing. The link smearing is, again, iterative and involves a weighted sum of each link with staples which start and end at the same points as the original link.

In the input XML for the MAKE_SOURCE inline measurement you can specify the link smearing for the gauge field that will then be used to generate the smeared source.

Look into the file

to see an example of the input XML. Note that,

• SHELL_SOURCE is the key for the tag <SourceType> for the smeared source.
• <quark_smear_lastP> is a tag which is only relevant if you want to apply a derivative to your source. This parameter then determines whether you smear first and then take the derivative or visa versa. You can delete this tag altogether or leave it set to false.
• <Displacement> is the tag to use for applying a derivative. Again in our case it is redundant and so you could delete it, or leave it as it is (set to no displacement)
• The parameters for the Gaussian smearing and the APE smearing are fine but you need to change <link_smear_num>, the number of iterations for APE smearing to be greater than 0.

For smearing at the sink, look at the example in the file

If you are, for example, calculating correlators with many different smearings, then time is wasted re-calculating the smeared gauge fields each time you generate a smeared source or apply smearing at the sink. Instead you can generate the smeared gauge field at the start and specifiy the smeared gauge field object in the <gauge_id> tag of the NamedObject list for the <MAKE_SOURCE> inline measurement (or similarly for smearing at the sink). Look into the file

to find the input XML for the inline measurement that performs the APE smearing. However, you should be careful only to use the smeared gauge field for making the source or smearing the propagator. A common mistake is to also put it as input to the PROPAGATOR inline measurement. Only the unsmeared gauge field should be used for this.

Example solution input files: hadspec_v_smear1.ini.xml, hadspec_v_smear2.ini.xml, hadspec_v_smear3.ini.xml

Use the unpreconditioned action

The preconditioning speeds up the inversion and so one would normally always choose to use it (there are other inline measurements, for example, that calculate the eigenvalues of the Dirac matrix for which you should not use preconditioning). However, it is interesting to see what effect the preconditioning has on the inversion. You only need to change the key for the tag <FermAct> in the PROPAGATOR inline measurement. To find the correct key mistype WILSON and you will see the key for the unpreconditioned case in the list of possiblities chroma displays.

Example solution input file: hadspec_v_unprecon.ini.xml.

Generate spectroscopy for non-degenerate quarks

In this case you need to generate two propagators (with different Kappa values). The same source can be used for both if you wish. In the HADRON_SPECTRUM inline measurement the ids specified within the <first_id> and <second_id> tags will be different.

Once you have the input file, generate the correlators and strip the output data file using strip_hadspec. Have a look at the new file names.

Example solution input file: hadspec_v_nondegen.ini.xml.

Input file needed for section Mini spectrum calculation

Now combine these examples to create a XML input file for use in the next section. The input file should:

• generate the degenerate spectrum using the clover fermion action,
• use the BiCGStab inverter,
• generate correlators that are smeared at both the source and the sink (SS), and correlators smeared at the source and point at the sink (SP). By having different sets of sink pairs various combinations of correlators can be contracted using one HADRON_SPECTRUM inline measurement. See file

  chroma_source_dir/tests/chroma/hadron/hadspec/hadspec.ini.xml

  for an example of this.

[Up][Tutorial main page]