Creating XML Input Files

Finding XML Parameters

There is a list of available entities but that only tells you what entities (monomials, solvers, gauges, ...) are available. There seems to be no central documentation for all the parameters that can be supplied in the input XML file.

One can go through the C++ source code to find the possible parameters. The parameters for a certain entity are usually read in the same file as the entity is defined. The entities are loaded into a factory, indexed by the const std::string name attribute. Using grep to find it in the codebase will yield the filename:

$ git grep REMEZ
lib/update/molecdyn/monomial/remez_rat_approx.cc:    const std::string name = "REMEZ";

Most of the these C++ source files contain a Params struct or a read function. The following snippet is what to look for:

Params::Params(XMLReader &xml, const std::string &path) {
    XMLReader paramtop(xml, path);

    read(paramtop, "numPower", numPower);
    read(paramtop, "denPower", denPower);
    read(paramtop, "lowerMin", lowerMin);
    read(paramtop, "upperMax", upperMax);
    read(paramtop, "degree", degree);

    if (paramtop.count("digitPrecision") != 0)
        read(paramtop, "digitPrecision", digitPrecision);
    else
        digitPrecision = 50;
}

From this the parameters can be extracted. The parameter digitPrecision is optional and has a default of 50. The resulting XML could be the following:

<ratApproxType>REMEZ</ratApproxType>
<lowerMin>1.0e-3</lowerMin>
<upperMax>33</upperMax>
<numPower>-1</numPower>
<denPower>4</denPower>
<degree>16</degree>

Another example are the parameters of the QPhiX clover multi-shift inverter. The file where the std::string name is defined can be found with grep as well:

$ git grep QPHIX_CLOVER_MULTI_SHIFT_INVERTER
lib/actions/ferm/invert/qphix/multi_syssolver_mdagm_cg_clover_qphix_w.cc:      const std::string name("QPHIX_CLOVER_MULTI_SHIFT_INVERTER");

The parameters are not defined in that class, though. Traversing the C++ inheritance, one finds the parameters in the file lib/actions/ferm/invert/qphix/multi_syssolver_qphix_clover_params.cc. In there, the parameters can be found:

MultiSysSolverQPhiXCloverParams::MultiSysSolverQPhiXCloverParams(
    // ...

    read(paramtop, "MaxIter", MaxIter);
    // ...

    if (paramtop.count("Verbose") > 0) {
        read(paramtop, "Verbose", VerboseP);
    } else {
        VerboseP = false;
    }
    // ...
}

In case a name is used that is not known, Chroma will output an error message and print all the possible entities that are available in the given context (monomials, solvers, ...). Parameters that are not needed are silently ignored, this can be irritating at times.