A first example

In this section, we start with a basic example to perform a standard component-by-component (CBC) method for an ordinary lattice rule, which we use to introduce the different command-line options. After, we extend that example in various ways to show how to achieve more elaborated tasks.

Consider the following basic example:

latnetbuilder \ 
 --set-type lattice \
 --construction ordinary \
 --size-parameter 2053 \
 --dimension 5 \
 --exploration-method full-CBC  \
 --figure-of-merit CU:P2 \
 --norm-type 2 \
 --weights product:0.7

The order in which the arguments are specified is not important. Some arguments consists of several tokens, separated by a colon.

The argument –set-type lattice indicates that we seek a rank-1 lattice rule.
The argument --construction ordinary indicates that we seek an ordinary (in contrast to polynomial) rank-1 lattice rule.
The argument --size-parameter 2053 indicates that we seek a lattice rule with modulus 2053.
The argument --dimension 5 specifies that we seek a lattice point set of dimension 5.
The argument --exploration-method full-CBC specifies that the CBC method should be used.
The argument --figure-of-merit CU:P2 consists of two colon-separated tokens. It tells LatNet Builder to use the specialized coordinate-uniform evaluation algorithm, whence the first CU token, for the \(\mathcal P_2\) discrepancy.
The argument –norm-type 2 indicates that the \(\ell_2\) norm is used to accumulate the merit of all projections. As we are using the \(\mathcal P_2\) discrepancy with the coordinate-uniform evaluation algorithm, this is the only possible norm.
The argument --weights product:0.7 assigns product weights to the figure of merit, with the same weight (0.7) for every coordinate.

To summarize, this command executes a CBC method for an ordinary lattice rule with 2053 points in 5 dimensions, using the weighted \(\mathcal P_2\) figure of merit with an \(\ell_2\) norm and product weights such that \(\gamma_j^2 = 0.7\) for all \(j\). The evaluation uses the coordinate-uniform algorithm.

Option names come in long and short forms. For example, the following has the same effect as the previous example:

latnetbuilder -t lattice -c ordinary -s 2053 -d 5 -e full-CBC -f CU:P2 -q 2 -w product:0.7

The long forms are favored in this tutorial to make the examples self-explanatory.

For the sake of conciseness, in the derived examples, we often only show the command-line parameters that need to be changed, or added; other parameters should be left as in the basic example.

Saving the results in a folder

It is possible to save the results of LatNet Builder in a folder. The –output-folder option indicates the path of the folder to use. This path can either be absolute or relative. If the folder does not exist, it will be created. If the folder already exists, some existing files may be lost. For instance, if you want the output folder to be located at /home/results, use –output-folder /home/results

This folder contains three files:

input.txt which contains the summary of the input parameters of LatNet Builder
output.txt which contains the result of the search in a human readable format
outputMachine.txt which contains an easily parsable formatting of the results

Exploring the search space with other methods

LatNet Builder supports a variety of exploration methods. The –exploration-method option controls which one is used to explore the search space.

To fasten computation, it is recommended to use the fast-CBC algorithm instead of full-CBC whenever possible. This is done by using the following option:

–exploration-method fast-CBC.

Using the fast-CBC method does not really change the exploration method but reduces the computation time. However, other methods, such as the random exploration method, are really different. For instance, to select the best point set among 100 random point sets, one can use the following option:

–exploration-method random:100.

All the available exploration methods and the usage restrictions can be found here.

Using different figures of merit

Figures of merit are constructed using the following ingredients:

a projection-dependent merit \(D_{\mathfrak u}\);
weights \(\gamma_{\mathfrak u}\); and
a norm-type \(\ell_q\).

By changing the value of the options corresponding to these three ingredients, one can explore the various figures of merit which are supported by LatNet Builder.

To use another projection-dependent merit than the \(\mathcal P_2\) discrepancy, one should change the value of the –figure-of-merit option. For instance, to use the \(\mathcal R_1\) criterion, with the coordinate-uniform evaluation algorithm, the following option should be used:

–figure-of-merit CU:R1

The different projection-dependent merits which are available and their usage restrictions are listed here.

Alternatively, one can change the type of weights. This can be done by changing the value of the –weights option. For instance:

–weights order-dependent:1

will tell LatNet Builder to use weights equal to 1 for all projections. Details on the possible value for the –weights option can be found here.

Finally, the \(\ell_2\) norm can be replaced by another norm. For instance to use the \(\mathcal P_2\) discrepancy will an \(\ell_3\) norm, use the following options:

–figure-of-merit P2 –norm-type 3.

Note that the CU token has disappeared: only a specific norm-type is compatible with the coordinate-uniform evaluation algorithm. Consequently, changing the norm-type will often lead to longer computations.

One can also use the \(\ell_\infty\) norm, for instance with the spectral projection-dependent merit:

–figure-of-merit spectral –norm-type inf.

Constructing polynomial lattice rules and digital nets

As explained here, the available figures of merit depend on the type of the point set we want to construct. Now that we know how to change the figure of merit, we can construct digital nets and polynomial lattice rules.

Let's start with digital nets. Say we want to construct a digital net with random generating matrices and that we want the digital net to have \(2^{10}\) points. We will look at the best net among a hundred nets.

Then the following options should be used:

–set-type net –construction explicit –size-parameter 2^10 –random:100.

We now need a figure of merit to evaluate the net. We can for instance use the maximum of the t-value of the subprojections of order lower than 3:

–figure-of-merit projdep:t-value –norm-type inf –weights order-dependent:0:1,1,1.

Again the possible figures of merit are listed here. It is really easy to use the Sobol' construction instead of random matrices. You just have to change –construction explicit to –construction sobol.

Polynomial lattice rules are a bit trickier because they can be constructed either with –set-type lattice –construction polynomial or –set-type net –construction polynomial. There is a huge performance gap between these two approaches depending on what you precisely want to do. Happily, detailed guidelines are available for you to pull through. But here we will just compare the two following examples:

latnetbuilder \ 
 --set-type lattice \
 --construction polynomial \
 --size-parameter 2^10 \
 --dimension 5 \
 --exploration-method fast-CBC  \
 --figure-of-merit CU:R \
 --norm-type 2 \
 --weights product:0.7

latnetbuilder \ 
 --set-type net \
 --construction polynomial \
 --size-parameter 2^10 \
 --dimension 5 \
 --exploration-method random-CBC:70  \
 --figure-of-merit CU:R \
 --norm-type 2 \
 --weights product:0.7

The only difference between these two examples it that the first performs a fast-CBC exploration with the \(\mathcal R\) criterion (note the CU token) whereas the second uses a random-CBC exploration with 70 samples per coordinate. For now, just retain the general idea that that the lattice approach (first example) should only be used with the fast-CBC construction. In all the other cases, the net approach (second example) is most efficient.

Applying filters and normalizations

The general idea behind filters and normalizations is explained here. Filters are optional and can be used to transform the computed values of a figure of merit, or to reject bad values. Multiple filters can be chained together by specifying multiple filter arguments separated by whitespace.

Normalization using a bound on \(\mathcal P_\alpha\) from [30] with \(\alpha=2\):
```
    --filters norm:P2-SL10
```
The first colon-separated token (norm) indicates that we want to apply a normalization. The second one is the type of normalization (here, a particular bound on \(\mathcal P_2\).
Rejecting candidate lattices that have a normalized merit value larger than unity:
```
    --filters norm:P2-SL10 low-pass:1.0
```
The first filter is explained above. The second filter consists of two colon-separated tokens: the first one (low-pass) indicates that we want to apply a low-pass filter on merit values; the second one specifies the threshold value of this low-pass filter.

For usage with embedded lattices, see Constructing embedded point sets. Additional details on how to use filters and normalizations can be found here.

Constructing embedded point sets

For multilevel point sets, a merit value is computed for each embedding level. Optionally, multilevel filters and normalizations are applied to the merit value of each level. Then the merits are combined using a sum or a maximum.

Let us start by giving an example with the Sobol' construction. We search for a multilevel digital net in dimension 7 with \(2^{15}\) points for the maximum embedding level. We will use the projection-dependent t-value-based star discrepancy bound merit, with an \(\ell_{\infty}\) norm and order-dependent weights equal to 0.9 on the 2-dimensional projections, 0.3 on the three-dimensional projections and 0.2 on the four-dimensional projections. To combine the merit values, we will use the maximum, which is more compatible with the star discrepancy (which is itself a maximum) than a sum. The search will be based on the full-CBC exploration method.

latnetbuilder \
--set-type net \
--construction sobol \
--size-parameter 2^15 \
--dimension 7 \
--exploration-method full-CBC  \
--figure-of-merit projdep:t-value:starDisc \
--norm-type inf \
--weights order-dependent:0:0,.9,.3,.2 \
--multilevel true \
--combiner max

Note the –multilevel true option: it tells LatNet Builder that we search for an embedded point set. The combiner is specified with the –combiner option. All the possible values for this option are listed here.

Now we give another example for embedded ordinary lattice rules with a multilevel normalization. We search for an embedded lattice rule in dimension 10, with \(2^{17}\) points. We use the \(\mathcal P_2\) discrepancy with an \(\ell_2\) norm, enabling the coordinate-uniform evaluation algorithm. The weights are order-dependent weights. The combiner is a sum. We use the fast-CBC algorithm to fasten the computations. We add the SL10 normalization (–filters norm:P2-SL10:select:10,17).
Note the select:10,17 token which tells LatNet Builder to put positive weights for the embedding levels 10 to 17, and a zero weight for the other embedding level.

latnetbuilder \
--set-type lattice \
--construction ordinary \
--size-parameter 2^17 \
--dimension 10 \
--exploration-method fast-CBC  \
--figure-of-merit CU:P2 \
--norm-type 2 \
--weights order-dependent:.1:0,.8,.3,.2 \
--multilevel true \
--combiner sum \
--filters norm:P2-SL10:select:10,17

Evaluating figures of merit for a specific point set

In this section we focus on the evaluation of a figure of merit for a specific point set. Evaluation is not a real exploration method as the search space is limited to only one point set. It is meant to compute the quality of only one point set.

First, we must be able to tell LatNet Builder which point set we want to evaluate. We will just give an example for ordinary lattice rules.

Say we want to evaluate the \(\mathcal R_1\) criterion with product weights equal to 0.9 and an \(\ell_2\) norm for the lattice rule with modulus 11551 and generating vector (1, 5396, 2285, 484, 5355, 20, 249, 4237, 4919, 3622). The following command-line will do the job:

latnetbuilder \
--set-type lattice \
--construction ordinary \
--size-parameter 11551 \
--dimension 10 \
--exploration-method evaluation:1-5396-2285-484-5355-20-249-4237-4919-3622  \
--figure-of-merit CU:R1 \
--norm-type 2 \
--weights product:.9

The way we specify the other point set types is explained here.

Constructing interlaced digital nets and polynomial lattice rules

In this section, we explain how to construct good interlaced polynomial lattice rules. Specific figures of merit must be used for interlaced polynomial lattice rules. One must also choose an interlacing factor, which equals the number of interlaced components used for each coordinate.

Say we want to construct an interlaced polynomial lattice rules in dimension 10 with \(2^{15}\) points and an interlacing factor \(d\) equal to 2. We will use the \(B_{d,(2)}\) interlaced discrepancy with the \(\ell_1\) norm to enable the coordinate-uniform evaluation algorithm and the fast-CBC method. The weights will be product weights equal to \(.9\).

latnetbuilder \
--set-type lattice \
--construction polynomial \
--size-parameter 2^15 \
--dimension 10 \
--exploration-method fast-CBC  \
--figure-of-merit CU:IB \
--norm-type 1 \
--weights product:.9 \
--interlacing-factor 2

the –figure-of-merit CU:IB option tells LatNet Builder that we want to use the \(B_{d,(2)}\) interlaced discrepancy;
the interlacing-factor 2 option tells LatNet Builder that \(d=2\).

LatNet Builder will actually search for the best underlying polynomial lattice rule, that is the polynomial lattice rules in dimension 20 which gives the best interlaced polynomial lattice rule in dimension 10.

You can fin additional details on constructing interlaced digital nets and polynomial lattice rules here.

Extending point sets

Suppose you have constructed embedded lattice rules up to \(2^8\) points in dimension 5 with:

latnetbuilder \
  --set-type lattice \
  --construction ordinary \
  --size-parameter 2^8 \
  --dimension 5 \
  --exploration-method fast-CBC \
  --figure-of-merit CU:P2 \
  --norm-type 2 \
  --weights product:0.1 \
  --multilevel true \
  --combiner sum \
  --filters norm:P2 low-pass:1.0

and have obtained the generating vector \(\boldsymbol a=(1,45,101,41,25)\). Then, you find out that you need to extend the number of points to \(2^9\). This can be done with:

latnetbuilder \
  --set-type lattice \
  --construction ordinary \
  --size-parameter 2^9 \
  --dimension 5 \
  --exploration-method extend:2^8:1-45-101-41-25 \
  --figure-of-merit CU:P2 \
  --norm-type 2 \
  --weights product:0.1

Note that only the merit value of the lattice with \(2^9\) points, and not that of the embedded lattices, is considered in this type of construction. The argument --size-parameter 2^9 specifies the extended number of points and the argument --exploration-method extend:2^8:1-45-101-41-25 indicates that we want to extend on a lattice with \(2^8\) points and generating vector \(\boldsymbol a=(1,45,101,41,25)\).

It is also possible to extend polynomial lattice rules in a similar manner. See here to learn how to specify a generating vector for a polynomial lattice rule.