Lattice Builder Manual
Software Package for Constructing Rank-1 Lattices
Sequences of Merit Values

Iterating through a sequence of lattice definitions and evaluating a figure of merit for each element, as in Weighted Figures of Merit, is a common task when searching for good lattice parameters.

Lattice Builder abstracts out this process by providing sequences of (computed) merit values.

See also
MeritSeq

CBC Construction

The example in tutorial/MeritSeqCBC.cc improves on the example from A Simple Example Using CBC Construction.

The base lattice and its merit value are managed by MeritSeq::CBC, so we can remove the declarations of baseLat and initialMerit, and introduce:

auto cbc = MeritSeq::cbc(storage, figure);

In the CBC loop, we instantiate the sequence of merit values with:

auto meritSeq = cbc.meritSeq(baseDim == 0 ? genSeq0 : genSeq);

Because the elements of meritSeq are of the abstract type MeritValue, we need to convert them to the Real type using an empty list of merit value filters declared as:

MeritFilterList<L> filters;

and applied with:

auto filteredSeq = filters.apply(meritSeq);

Such a filter list can also be used to combine the merit values of individual levels in the case of embedded lattices (see Filters and Combiners). Then, we replace the minimization loop with a call to std::min_element:

auto best = std::min_element(filteredSeq.begin(), filteredSeq.end());

and notify the CBC instance that we have found our best lattice for the current dimension:

cbc.select(best.base());

Here, best is an iterator on the filteredSeq sequence, and best.base() is an iterator on corresponding element of the underlying meritSeq sequence. The output of this example is:

CBC search for dimension: 1
  base lattice: lattice(19, [])
  base merit value: 0
  new projections: [{1}]
CBC search for dimension: 2
  base lattice: lattice(19, [1])
  base merit value: 0.7
  new projections: [{2}, {1,2}]
CBC search for dimension: 3
  base lattice: lattice(19, [1, 4])
  base merit value: 0.7
  new projections: [{3}, {1,3}, {2,3}, {1,2,3}]

CBC Construction Using Signals

To improve on the above example by using signals, we can reintroduce the Observer class from A Improved Example Using Signals. We also need to notify the Observer class when a new minimum value is updated, with a few changes:

class Observer {
public:
Observer() { reset(); }
// initializes the best observed merit value to infinity
void reset() { m_bestMerit = std::numeric_limits<Real>::infinity(); }
bool onProgress(Real merit) const
{ return merit <= m_bestMerit; }
void onAbort(const LatDef& lat) const
{ std::cout << "rejected " << lat << std::endl; }
void onMinUpdated(const Real& bestMerit)
{ m_bestMerit = bestMerit; }
private:
Real m_bestMerit;
};

So, instead of using std::min_element, we use Functor::MinElement and connect its Functor::MinElement::onMinUpdated() signal to Observer::onMinUpdated():

Functor::MinElement<Real> minElement;
minElement.onMinUpdated().connect(boost::bind(&Observer::onMinUpdated, &obs, _1));

Then replace the call to std::min_element() with:

obs.reset();
auto best = minElement(filteredSeq.begin(), filteredSeq.end());

Also note the call to Observer::reset() to initialize the best observed merit value before using minElement. The resulting code can be found in tutorial/MeritSeqCBCSignals.cc .

CBC Construction for Coordinate-Uniform Figures of Merit

Figures of merit in a coordinate-uniform form can be evaluated more efficiently than the general weighted figures of merit. Here, we consider the case of the weighted \(\mathcal P_\alpha\) discrepancy, by adapting the code from CBC Construction . First, we replace the WeightedFigureOfMerit instance with an instance of CoordUniformFigureOfMerit:

auto weights = unique<LatCommon::ProductWeights>();
weights->setDefaultWeight(0.7);
CoordUniformFigureOfMerit<Kernel::PAlpha> figure(std::move(weights), 2);
std::cout << "figure of merit: " << figure << std::endl;

The type of weights must be specified as a template argument because a different evaluation algorithm is used for different types of weights. Then, we replace the MeritSeq::CBC instance with a MeritSeq::CoordUniformCBC instance:

auto cbc = MeritSeq::cbc<MeritSeq::CoordUniformInnerProd>(storage, figure);

The MeritSeq::CoordUniformInnerProd template argument specifies that we want to use a standard inner product during the CBC algorithm. The complete example can be found in tutorial/MeritSeqCoordUniform.cc.

Fast CBC Construction

Here, we modify the example from CBC Construction for Coordinate-Uniform Figures of Merit in order to use the fast CBC method, which is implemented only with coordinate-uniform figures of merit. First, we need to replace MeritSeq::CoordUniformInnerProd with MeritSeq::CoordUniformInnerProdFast:

auto cbc = MeritSeq::cbc<MeritSeq::CoordUniformInnerProdFast>(storage, figure);

The fast CBC algorithm requires a special ordering of the generator values, so we also need to replace:

typedef GenSeq::CoprimeIntegers<decltype(figure)::suggestedCompression()> Coprime;

with:

typedef GenSeq::CyclicGroup<decltype(figure)::suggestedCompression()> Coprime;

Note that instantiating GenSeq::CyclicGroup requires the number of points to be an integer power of a prime base. Then, we modify the instantiation of meritSeq accordingly:

auto meritSeq = cbc.meritSeq(baseDim == 0 ? genSeq0 : genSeq);

The complete example can be found in tutorial/MeritSeqFastCBC.cc.

Non-CBC Construction Methods

In Lattice Builder, sequences of merit values for non-CBC construction methods are available only as a wrapper of the CBC construction applied independently to each lattice definition, by replacing the sequences of candidate lattice definitions by singletons that contain only the candidate lattice being currently examined. CBC construction can thus output only this one lattice, together with its merit value. This enables the efficient computation algorithms used in the coordinate-uniform case with standard CBC.

The example in tutorial/MeritSeqNonCBC.cc illustrates how to transform the CBC search from CBC Construction for Coordinate-Uniform Figures of Merit into a Korobov search. First, we create an instance of MeritSeq::LatSeqOverCBC and a sequence of Korobov lattice definitions:

auto latSeq = LatSeq::korobov(storage.sizeParam(), Coprime(storage.sizeParam().numPoints()), dimension);

Then, the whole CBC loop is replaced with the execution of the Korobov search:

auto meritSeq = latSeqOverCBC.meritSeq(latSeq);
auto filteredSeq = filters.apply(meritSeq);
auto best = std::min_element(filteredSeq.begin(), filteredSeq.end());
std::cout << "BEST LATTICE: " << *best.base().base() << " with merit value " << *best << std::endl;