NRVec: colexicographic ordering and rank/unrank

This commit is contained in:
jiri committed 2026-11-19 14:48:19 +01:00
1 parent 0b3343f878
commit 562f807243
5 files changed
+220 -8

No files matched your search

+10 -1
View File
@@ -15,7 +15,16 @@ decisions and plans agreed with the author, so that they survive a fresh clone.
## Build and test
- Build the library with `make -j 8` (after header changes most files rebuild; run it in the background).
- Flags used: `-std=gnu++11 -O3 -DDEBUG -DFORTRAN_ -DNONCLAPACK`, libs `-lcblas -lblas -llapack`.
Quick test program: `g++ -std=gnu++11 -I<repo> -O0 -DDEBUG -DFORTRAN_ -DNONCLAPACK X.cc <repo>/.libs/libla.a -lcblas -lblas -llapack`
Quick test program: `g++ -std=gnu++11 -I<repo> -O0 -DDEBUG -DFORTRAN_ -DNONCLAPACK X.cc <repo>/.libs/libla_debug.a -lcblas -lblas -llapack`
- Library names (2026-11-19): the production build (configure default) is `libla`, `--enable-debug` gives `libla_debug` (DEBUG); both can be
installed together (two configure+make runs: in-tree with `make clean` in between, or two out-of-tree build directories).
Programs compiled with -DDEBUG link -lla_debug, others -lla (headers are common, their inline code follows the program's
DEBUG). `LA::version` ends with "(debug build)" or "(production build)" (get_git_version gets $(DEBUGOPT)).
- Colex order (2026-11-19): `NRVec_colex<T>` (from NRVec) and `NRVec_from1_colex<T>` (from NRVec_from1) redefine the four
comparison operators (shared raw function colex_bigger; mixed-order comparisons are deleted, conversion from NRVec is
explicit); for integer T: rank/next/setfirst/unrank with optional (from, length) range, elements and positions from 0 or
from 1 like the class; next/setfirst/unrank call copyonwrite (like NRPerm::identity and next).
`NRVec_from1::sort` range is counted from 1. Test: bugtests/core/colex.cc.
(add `-fsanitize=address` for memory checks).
- Regression test of the optimizers: `make check` builds `testoptimize`; `./testoptimize` must report
"137 passed, 0 failed" (exit code = number of failures). New optimizer tests go to testoptimize.cc;
+16 -5
View File
@@ -47,7 +47,7 @@ accordingly:
\textbf{Option} & \textbf{Effect} \\
\midrule
\endhead
\code{--disable-debug} & do not define \code{DEBUG}; by default range checks and other consistency checks are compiled in (section~\ref{sec:concepts:errors}) \\
\code{--enable-debug} & define \code{DEBUG}: range checks and other consistency checks are compiled in (section~\ref{sec:concepts:errors}). The library is then called \code{libla\_debug}, without \code{DEBUG} (the default, production build) \code{libla} \\
\code{--enable-optimize=<flags>} & compiler optimization flags, default \code{-O3 -finline-limit=1000}; \code{--disable-optimize} for none \\
\code{--enable-profile} & compile with \code{-pg} \\
\code{--enable-matptr} & define \code{MATPTR}: \code{NRMat} stores an array of row pointers (\code{T**}), see chapter~\ref{ch:mat}; incompatible with CUDA \\
@@ -85,18 +85,29 @@ The headers \header{fortran.h}, \header{noncblas.h}, \header{cuda_la.h}, \header
\section{Compiling and linking user programs}
Include \header{la.h} (or the individual headers) and link with \code{-lla}, followed by the
libraries found by \code{configure}, e.g.
Include \header{la.h} (or the individual headers) and link with \code{-lla\_debug} (program compiled with
\code{-DDEBUG}) or \code{-lla} (without it), followed by the libraries found by \code{configure}, e.g.
\begin{lstlisting}[language=bash]
g++ -O3 -DDEBUG -DFORTRAN_ -DNONCLAPACK -I$PREFIX/include prog.cc \
-L$PREFIX/lib -lla_debug -llapack -lcblas -lblas
g++ -O3 -DFORTRAN_ -DNONCLAPACK -I$PREFIX/include prog.cc \
-L$PREFIX/lib -lla -llapack -lcblas -lblas
\end{lstlisting}
Both libraries can be installed together; the headers are common, and their inline code follows the \code{DEBUG} setting
of the user program, which should therefore match the library. They are built by two runs of \code{configure} and
\code{make install}, either in the source directory with \code{make clean} in between, or in two separate build
directories:
\begin{lstlisting}[language=bash]
mkdir build_prod build_debug
(cd build_prod; ../configure; make; make install)
(cd build_debug; ../configure --enable-debug; make; make install)
\end{lstlisting}
The variables \code{AM_CXXFLAGS} and \code{AM_LDFLAGS} in the generated \header{Makefile} show the exact
options used for the library itself.
The string \code{LA::version} (declared in \header{LA_version.h}) contains the git version, the commit date
and the time and place of compilation of the library; it is generated by the script \header{get_git_version}
at every \code{make}.
and the time and place of compilation of the library, followed by \code{(debug build)} or \code{(production build)};
it is generated by the script \header{get_git_version} at every \code{make}.
\section{Test programs}
+53 -2
View File
@@ -305,8 +305,8 @@ for unsigned integer types; auxiliary.}
\code{NRVec_from1<T>} is derived publicly from \code{NRVec<T>} and differs only in indexing: \code{operator[]} takes
$1\le i\le n$ (same DEBUG checks as \code{NRVec}), and \code{iamax()} returns a 1-based index. It is used e.g.\ for permutations
(Chapter~\ref{ch:permutation}). Everything else is inherited unchanged and \emph{remains zero-based} (e.g.\ \code{subvector},
\code{find}, \code{sort(direction,from,to,...)}, the raw pointer).
(Chapter~\ref{ch:permutation}). The range of \code{sort} is counted from 1 as well. Everything else is inherited unchanged
and \emph{remains zero-based} (e.g.\ \code{subvector}, \code{find}, the raw pointer).
\begin{lareference}
\lafunc{NRVec_from1(); explicit NRVec_from1(const int n); NRVec_from1(const T &a, const int n); NRVec_from1(const T *a, const int n)}{As
@@ -315,12 +315,63 @@ for \code{NRVec}.}
\lafunc{NRVec_from1(const NRVec<T> &rhs)}{Implicit conversion from the base class (shares data).}
\lafunc{const T& operator[](const int i) const; T& operator[](const int i)}{Element $i$, 1-based.}
\lafunc{int iamax() const}{1-based index of the element of largest absolute value.}
\lafunc{int sort(int direction = 0, int from = 1, int to = -1, int *perm = NULL, bool stable=false)}{As \code{NRVec::sort}, with
the range \code{from}\dots\code{to} counted from 1 (\code{-1}: last); \code{perm} points to the entry belonging to the first
element of the vector. The variant with \code{NRPerm} is inherited.}
\end{lareference}
\lawarning{\code{NRVec_from1} does not redeclare \code{operator=(const T&)}; the implicitly declared copy assignment hides it, so
\code{f = 0.;} does not compile for \code{NRVec_from1<double> f}. Use the \code{(value, size)} constructor or assign through a base
class reference.}
\section{Colex order: NRVec\_colex and NRVec\_from1\_colex}\label{sec:vec:colex}
\code{NRVec_colex<T>} (derived from \code{NRVec<T>}) and \code{NRVec_from1_colex<T>} (derived from \code{NRVec_from1<T>})
differ from their base classes in the order defined by the comparison operators: the \emph{colex} (colexicographic) order
compares two sequences from their last elements backwards, and a proper suffix is smaller; it is the lexicographic order of
the reversed sequences. For ascending sequences of integers (subsets) it is the order of the combinatorial number system,
equal to the numeric order of the corresponding bit masks, e.g.\ $\{3\}<\{1,3\}<\{2,3\}$. Since sorting uses
\code{LA_traits<T>::bigger/smaller} of the elements, \code{sort()} of a \code{NRVec<NRVec_colex<int> >} sorts in the colex
order, and the orders can be nested. The choice is static (no virtual functions, nothing stored in the object).
\begin{lareference}
\lafunc{NRVec_colex(); explicit NRVec_colex(const int n); NRVec_colex(const T &a, const int n); NRVec_colex(const T *a, const int n); template<int SIZE> NRVec_colex(const T (&a)[SIZE]); explicit NRVec_colex(const std::list<T> l)}{As
for \code{NRVec}; the same for \code{NRVec_from1_colex}.}
\lafunc{explicit NRVec_colex(const NRVec<T> &rhs)}{Conversion from a plain vector (shares data). It is explicit, so that
vectors with different orders are not mixed by accident.}
\lafunc{const bool operator>(const NRVec_colex &rhs) const; ... operator<, operator>=, operator<=}{Colex order using
\code{LA_traits<T>::bigger/smaller} of the elements, for any \code{T}. The comparison with a vector of another class
(\code{NRVec}, \code{NRVec_from1}, the other colex class) is deleted and does not compile. \code{operator==} and
\code{operator!=} are inherited.}
\end{lareference}
For integer \code{T} (other types do not compile) a range of the vector can hold an ascending subset of $n$ integers: of
$0,\dots,n-1$ in \code{NRVec_colex}, of $1,\dots,n$ in \code{NRVec_from1_colex}. The range is given by \code{from}
(counted like the index of the class, default the first element) and \code{length} (default $-1$: up to the end of the
vector; 0 is the empty subset).
\begin{lareference}
\lafunc{unsigned long long rank(const int from, const int length= -1) const}{Rank of the subset in the colex order of all
subsets of the same size, counted from 0: $\sum_{i=1}^{m}\binom{s_i}{i}$ for the elements $s_1<\dots<s_m$ counted from 0.
It does not depend on $n$.}
\lafunc{void setfirst(const int from, const int length= -1)}{Set the first subset (the $m$ smallest integers); calls copyonwrite.}
\lafunc{bool next(const T n, const int from, const int length= -1)}{Replace the subset of $n$ integers by the next one in
the colex order; returns \code{false} and leaves it unchanged after the last one (and for the empty subset); calls copyonwrite.}
\lafunc{void unrank(const unsigned long long r, const int from, const int length= -1)}{Set the subset of the given rank; calls copyonwrite.}
\end{lareference}
\lawarning{The operators are not virtual: a colex vector passed as \code{const NRVec<T>\&}, or standing on the right-hand side of
a plain vector, is compared lexicographically.}
The underlying functions on raw storage, \code{colex_bigger}, \code{colex_rank}, \code{colex_next}, \code{colex_first} and
\code{colex_unrank} (\header{vec.h}), take a pointer, the length and the origin of the integers (0 or 1).
\begin{lstlisting}
NRVec_from1_colex<int> s(3);
s.setfirst(); //1 2 3
do { /* s.rank() runs over 0..9 */ } while(s.next(5)); //all 3-element subsets of 1..5
\end{lstlisting}
\section{Examples}\label{sec:vec:examples}
\begin{lstlisting}
+4
View File
@@ -82,6 +82,8 @@ namespace LA {
//forward declarations
template<typename C> class NRVec;
template<typename C> class NRVec_from1;
template<typename C> class NRVec_colex;
template<typename C> class NRVec_from1_colex;
template<typename C> class NRMat;
template<typename C> class NRMat_from1;
template<typename C> class NRSMat;
@@ -413,6 +415,8 @@ generate_traits_nonscalar(NRMat)
generate_traits_nonscalar(NRMat_from1)
generate_traits_nonscalar(NRVec)
generate_traits_nonscalar(NRVec_from1)
generate_traits_nonscalar(NRVec_colex)
generate_traits_nonscalar(NRVec_from1_colex)
generate_traits_nonscalar(SparseMat)
generate_traits_nonscalar(SparseSMat) //product leading to non-symmetric result not implemented
generate_traits_nonscalar(CSRMat)
+137
View File
@@ -21,6 +21,7 @@
#define _LA_VEC_H_
#include "la_traits.h"
#include "miscfunc.h"
#include "vecmat3.h"
#include <list>
@@ -591,6 +592,142 @@ public:
inline const T& operator[] (const int i) const;
inline T& operator[] (const int i);
inline int iamax() const {return NRVec<T>::iamax() + 1;};
using NRVec<T>::sort;
//! sort with the range from..to counted from 1 (to = -1: last)
int sort(int direction = 0, int from = 1, int to = -1, int *perm = NULL, bool stable=false) {return NRVec<T>::sort(direction, from-1, to<0?-1:to-1, perm, stable);};
};
/***************************************************************************//**
* colex (colexicographic) order: sequences are compared from their last elements backwards
* and a proper suffix is smaller, i.e. it is the lexicographic order of the reversed sequences;
* for ascending subsets of integers it is the order of the combinatorial number system
* the following functions work on raw storage and are shared by the classes below
******************************************************************************/
template<typename T>
inline bool colex_bigger(const T *a, int na, const T *b, int nb)
{
while(na>0 && nb>0)
{
--na; --nb;
if(LA_traits<T>::bigger(a[na],b[nb])) return true;
if(LA_traits<T>::smaller(a[na],b[nb])) return false;
}
return na>nb;
}
//ascending subsets s[0..m-1] of the n integers origin..origin+n-1 (integer T only): rank in the colex order counted from 0
template<typename T>
inline unsigned long long colex_rank(const T *s, const int m, const T origin)
{
static_assert(std::numeric_limits<T>::is_integer,"colex rank is defined only for integer types");
unsigned long long r=0;
for(int i=0; i<m; ++i) r+=binom(s[i]-origin,i+1);
return r;
}
//next subset in the colex order, false after the last one (also for the empty subset)
template<typename T>
inline bool colex_next(T *s, const int m, const T n, const T origin)
{
static_assert(std::numeric_limits<T>::is_integer,"colex next is defined only for integer types");
for(int i=0; i<m; ++i) if(s[i] < (i==m-1? origin+n-1 : s[i+1]-1)) {++s[i]; for(int j=0; j<i; ++j) s[j]=origin+j; return true;}
return false;
}
//first subset in the colex order
template<typename T>
inline void colex_first(T *s, const int m, const T origin)
{
static_assert(std::numeric_limits<T>::is_integer,"colex setfirst is defined only for integer types");
for(int i=0; i<m; ++i) s[i]=origin+i;
}
//subset from its rank
template<typename T>
inline void colex_unrank(T *s, const int m, unsigned long long r, const T origin)
{
static_assert(std::numeric_limits<T>::is_integer,"colex unrank is defined only for integer types");
for(int i=m-1; i>=0; --i)
{
int c=i; //binom(i,i+1)=0
while(binom(c+1,i+1)<=r) ++c;
s[i]=origin+c;
r-=binom(c,i+1);
}
}
//length of the range starting at the zero-based position from in a vector of n elements (negative length: up to the end)
inline int colex_range(const int n, const int from, const int length)
{
int l= length<0? n-from : length;
#ifdef DEBUG
if(from<0 || l<0 || from+l>n) laerror("illegal range in a colex vector");
#endif
return l;
}
/***************************************************************************//**
* \c NRVec<T> with the comparison operators in the colex order instead of the lexicographic one
* (so that e.g. sort() of a vector of such vectors sorts in the colex order);
* the conversion from \c NRVec<T> is explicit, a colex vector passed as \c NRVec<T> is compared lexicographically
* for integer T it represents also an ascending subset of 0..n-1 in the elements from..from+length-1
* (default the whole vector) with rank(), next(), setfirst() and unrank() in the colex order
******************************************************************************/
template<typename T>
class NRVec_colex : public NRVec<T> {
public:
NRVec_colex(): NRVec<T>() {};
template<int SIZE> NRVec_colex(const T (&a)[SIZE]) : NRVec<T>(a) {};
explicit NRVec_colex(const int n): NRVec<T>(n) {};
explicit NRVec_colex(const NRVec<T> &rhs): NRVec<T>(rhs) {};
NRVec_colex(const T &a, const int n): NRVec<T>(a, n) {};
NRVec_colex(const T *a, const int n): NRVec<T>(a, n) {};
explicit NRVec_colex(const std::list<T> l) : NRVec<T>(l) {};
const bool operator>(const NRVec_colex &rhs) const {SAME_LOC(*this, rhs); NOT_GPU(*this); return colex_bigger(this->v,this->nn,rhs.v,rhs.nn);};
const bool operator<(const NRVec_colex &rhs) const {SAME_LOC(*this, rhs); NOT_GPU(*this); return colex_bigger(rhs.v,rhs.nn,this->v,this->nn);};
const bool operator>=(const NRVec_colex &rhs) const {return !(*this < rhs);};
const bool operator<=(const NRVec_colex &rhs) const {return !(*this > rhs);};
//comparison with a vector of another order is not defined (it would otherwise compare the pointers through operator T*)
const bool operator>(const NRVec<T> &rhs) const = delete;
const bool operator<(const NRVec<T> &rhs) const = delete;
const bool operator>=(const NRVec<T> &rhs) const = delete;
const bool operator<=(const NRVec<T> &rhs) const = delete;
unsigned long long rank(const int from=0, const int length= -1) const {return colex_rank(this->v+from,colex_range(this->nn,from,length),(T)0);};
bool next(const T n, const int from=0, const int length= -1) {this->copyonwrite(); return colex_next(this->v+from,colex_range(this->nn,from,length),n,(T)0);};
void setfirst(const int from=0, const int length= -1) {this->copyonwrite(); colex_first(this->v+from,colex_range(this->nn,from,length),(T)0);};
void unrank(const unsigned long long r, const int from=0, const int length= -1) {this->copyonwrite(); colex_unrank(this->v+from,colex_range(this->nn,from,length),r,(T)0);};
};
/***************************************************************************//**
* \c NRVec_from1<T> with the colex order: as \c NRVec_colex<T>, but the positions (also from)
* and the elements of the subsets (1..n) are counted from 1
******************************************************************************/
template<typename T>
class NRVec_from1_colex : public NRVec_from1<T> {
public:
NRVec_from1_colex(): NRVec_from1<T>() {};
template<int SIZE> NRVec_from1_colex(const T (&a)[SIZE]) : NRVec_from1<T>(a) {};
explicit NRVec_from1_colex(const int n): NRVec_from1<T>(n) {};
explicit NRVec_from1_colex(const NRVec<T> &rhs): NRVec_from1<T>(rhs) {};
NRVec_from1_colex(const T &a, const int n): NRVec_from1<T>(a, n) {};
NRVec_from1_colex(const T *a, const int n): NRVec_from1<T>(a, n) {};
explicit NRVec_from1_colex(const std::list<T> l) : NRVec_from1<T>(l) {};
const bool operator>(const NRVec_from1_colex &rhs) const {SAME_LOC(*this, rhs); NOT_GPU(*this); return colex_bigger(this->v,this->nn,rhs.v,rhs.nn);};
const bool operator<(const NRVec_from1_colex &rhs) const {SAME_LOC(*this, rhs); NOT_GPU(*this); return colex_bigger(rhs.v,rhs.nn,this->v,this->nn);};
const bool operator>=(const NRVec_from1_colex &rhs) const {return !(*this < rhs);};
const bool operator<=(const NRVec_from1_colex &rhs) const {return !(*this > rhs);};
//comparison with a vector of another order is not defined (it would otherwise compare the pointers through operator T*)
const bool operator>(const NRVec<T> &rhs) const = delete;
const bool operator<(const NRVec<T> &rhs) const = delete;
const bool operator>=(const NRVec<T> &rhs) const = delete;
const bool operator<=(const NRVec<T> &rhs) const = delete;
unsigned long long rank(const int from=1, const int length= -1) const {return colex_rank(this->v+from-1,colex_range(this->nn,from-1,length),(T)1);};
bool next(const T n, const int from=1, const int length= -1) {this->copyonwrite(); return colex_next(this->v+from-1,colex_range(this->nn,from-1,length),n,(T)1);};
void setfirst(const int from=1, const int length= -1) {this->copyonwrite(); colex_first(this->v+from-1,colex_range(this->nn,from-1,length),(T)1);};
void unrank(const unsigned long long r, const int from=1, const int length= -1) {this->copyonwrite(); colex_unrank(this->v+from-1,colex_range(this->nn,from-1,length),r,(T)1);};
};