From 562f80724337e60618d58526e1a7bf815ccf61db Mon Sep 17 00:00:00 2001 From: Jiri Pittner Date: Thu, 19 Nov 2026 14:48:19 +0100 Subject: [PATCH] NRVec: colexicographic ordering and rank/unrank --- CLAUDE.md | 11 +++- doc/building.tex | 21 ++++++-- doc/vec.tex | 55 ++++++++++++++++++- la_traits.h | 4 ++ vec.h | 137 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 220 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 94f7ea8..611fcf5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 -O0 -DDEBUG -DFORTRAN_ -DNONCLAPACK X.cc /.libs/libla.a -lcblas -lblas -llapack` + Quick test program: `g++ -std=gnu++11 -I -O0 -DDEBUG -DFORTRAN_ -DNONCLAPACK X.cc /.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` (from NRVec) and `NRVec_from1_colex` (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; diff --git a/doc/building.tex b/doc/building.tex index be42018..feeeeba 100644 --- a/doc/building.tex +++ b/doc/building.tex @@ -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=} & 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} diff --git a/doc/vec.tex b/doc/vec.tex index f8fd42c..40d11b0 100644 --- a/doc/vec.tex +++ b/doc/vec.tex @@ -305,8 +305,8 @@ for unsigned integer types; auxiliary.} \code{NRVec_from1} is derived publicly from \code{NRVec} 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 &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 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} (derived from \code{NRVec}) and \code{NRVec_from1_colex} (derived from \code{NRVec_from1}) +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::bigger/smaller} of the elements, \code{sort()} of a \code{NRVec >} 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 NRVec_colex(const T (&a)[SIZE]); explicit NRVec_colex(const std::list l)}{As +for \code{NRVec}; the same for \code{NRVec_from1_colex}.} +\lafunc{explicit NRVec_colex(const NRVec &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::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\&}, 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 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} diff --git a/la_traits.h b/la_traits.h index 8f77d4f..0bbe37a 100644 --- a/la_traits.h +++ b/la_traits.h @@ -82,6 +82,8 @@ namespace LA { //forward declarations template class NRVec; template class NRVec_from1; +template class NRVec_colex; +template class NRVec_from1_colex; template class NRMat; template class NRMat_from1; template 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) diff --git a/vec.h b/vec.h index b61a091..3d9cfb3 100644 --- a/vec.h +++ b/vec.h @@ -21,6 +21,7 @@ #define _LA_VEC_H_ #include "la_traits.h" +#include "miscfunc.h" #include "vecmat3.h" #include @@ -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::iamax() + 1;}; + using NRVec::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::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 +inline bool colex_bigger(const T *a, int na, const T *b, int nb) +{ +while(na>0 && nb>0) + { + --na; --nb; + if(LA_traits::bigger(a[na],b[nb])) return true; + if(LA_traits::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 +inline unsigned long long colex_rank(const T *s, const int m, const T origin) +{ +static_assert(std::numeric_limits::is_integer,"colex rank is defined only for integer types"); +unsigned long long r=0; +for(int i=0; i +inline bool colex_next(T *s, const int m, const T n, const T origin) +{ +static_assert(std::numeric_limits::is_integer,"colex next is defined only for integer types"); +for(int i=0; i +inline void colex_first(T *s, const int m, const T origin) +{ +static_assert(std::numeric_limits::is_integer,"colex setfirst is defined only for integer types"); +for(int i=0; i +inline void colex_unrank(T *s, const int m, unsigned long long r, const T origin) +{ +static_assert(std::numeric_limits::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 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 is explicit, a colex vector passed as \c NRVec 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 +class NRVec_colex : public NRVec { +public: + NRVec_colex(): NRVec() {}; + template NRVec_colex(const T (&a)[SIZE]) : NRVec(a) {}; + explicit NRVec_colex(const int n): NRVec(n) {}; + explicit NRVec_colex(const NRVec &rhs): NRVec(rhs) {}; + NRVec_colex(const T &a, const int n): NRVec(a, n) {}; + NRVec_colex(const T *a, const int n): NRVec(a, n) {}; + explicit NRVec_colex(const std::list l) : NRVec(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 &rhs) const = delete; + const bool operator<(const NRVec &rhs) const = delete; + const bool operator>=(const NRVec &rhs) const = delete; + const bool operator<=(const NRVec &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 with the colex order: as \c NRVec_colex, but the positions (also from) + * and the elements of the subsets (1..n) are counted from 1 + ******************************************************************************/ +template +class NRVec_from1_colex : public NRVec_from1 { +public: + NRVec_from1_colex(): NRVec_from1() {}; + template NRVec_from1_colex(const T (&a)[SIZE]) : NRVec_from1(a) {}; + explicit NRVec_from1_colex(const int n): NRVec_from1(n) {}; + explicit NRVec_from1_colex(const NRVec &rhs): NRVec_from1(rhs) {}; + NRVec_from1_colex(const T &a, const int n): NRVec_from1(a, n) {}; + NRVec_from1_colex(const T *a, const int n): NRVec_from1(a, n) {}; + explicit NRVec_from1_colex(const std::list l) : NRVec_from1(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 &rhs) const = delete; + const bool operator<(const NRVec &rhs) const = delete; + const bool operator>=(const NRVec &rhs) const = delete; + const bool operator<=(const NRVec &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);}; };