Merge pull request #59 from jwood000/repcapped-compositions

feat: add capped repetition compositions and fix permuteIter()

Extend the compositions framework to support capped (maximum-part)
compositions with repetition across counting, generation, ranking,
unranking (nth), sampling, and iteration. This includes weak and
mapped-zero variants and integrates fully with existing combinatorial
APIs such as compositionsGeneral(), compositionsRank(),
compositionsSample(), and compositionsIter().

Counting is implemented using exact inclusion–exclusion in the GMP
path, with double-return wrappers computing the full sum in mpz_class
before converting to double to avoid precision loss and cancellation
errors.

Harden binomial coefficient helpers (nChooseK, nChooseKGmp) to return
0 for invalid inputs and avoid unsafe signed-to-unsigned conversion
into GMP routines, preventing incorrect results and pathological
computations.

Fix iterator dispatch for permutation-of-partition constrained cases
so permuteIter() produces correct results when problems reduce to
partition/composition counting.

Add extensive tests covering capped composition families, parallel
ranking paths, GMP-index workflows, and permutation-of-partition
iterator correctness.

These changes are additive and maintain backwards compatibility.

Author: jwood000

.github/workflows/test-coverage.yml

@@ -24,7 +24,9 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::covr
+          extra-packages: |
+            any::covr
+            any::xml2
           needs: coverage
 
       - name: Test coverage

DESCRIPTION

@@ -30,7 +30,15 @@ URL: https://jwood000.github.io/RcppAlgos/,
 BugReports: https://github.com/jwood000/RcppAlgos/issues
 LinkingTo: cpp11
 Imports: gmp, methods
-Suggests: testthat, partitions, microbenchmark, knitr, RcppBigIntAlgos, rmarkdown
+Suggests:
+    testthat,
+    partitions,
+    microbenchmark,
+    knitr,
+    RcppBigIntAlgos,
+    rmarkdown,
+    covr,
+    xml2
 Config/Needs/website: pkgdown
 License: GPL (>=2)
 SystemRequirements: gmp (>= 4.2.3)

NEWS.md

@@ -1,30 +1,39 @@
 # RcppAlgos 2.10.0
 
+This release introduces major enhancements to the compositions framework, including support for distinct and repetition-restricted compositions, parallel ranking, and performance improvements across several combinatorial algorithms.
+
+These enhancements integrate fully with the existing counting, ranking, sampling, and iterator infrastructure, and have been validated for correctness and consistency across supported combinatorial families.
+
 ## New Features:
 
-* Added parallel capabilities to all ranking functions via the new `nThreads` argument (e.g. `partitionsRank(..., nThreads = 4)`, `comboRank(..., nThreads = 4)`).
-* Implemented a next-lexicographical algorithm for generating distinct integer compositions, enabling efficient large-scale generation such as `compositionsGeneral(50, 8)`.
-* Added accompanying algorithms for the distinct integer composition case, exposed through: `compositionsSample`, `compositionsRank`, and `compositionsIter`.
-* Enhanced `permuteCount()` to count permutations of partitions when called with `constraintFun = "sum"` and `comparisonFun = "=="`, allowing optimized counting in cases that reduce to partition/composition counting.
+* Added parallel capabilities to all ranking functions via a new `nThreads` argument (e.g. `comboRank()`, `partitionsRank()`, `compositionsRank()`), enabling faster ranking of large combinatorial results.
+* Implemented a next-lexicographical algorithm for generating **distinct integer compositions**, enabling efficient generation of large problems such as `compositionsGeneral(50, 8)`.
+* Added full support for distinct compositions across the compositional framework, including:
 
-## Bug Fixes:
+  * `compositionsGeneral()`
+  * `compositionsSample()`
+  * `compositionsRank()`
+  * `compositionsIter()`
 
-* Improved input validation for constraint-based calls by requiring `comparisonFun` to be a character vector (now errors early with a clearer message).
-* Fixed edge-case handling in partition iteration logic where boundary-derived indices could become negative, preventing incorrect behavior in some partition/multiset scenarios.
+* Added support for **compositions with repetition subject to a maximum part constraint** ("capped compositions"), including weak and non-weak cases, with full support for counting, ranking, sampling, and iteration.
+* Enhanced `permuteCount()` to count permutations of partitions when called with `constraintFun = "sum"` and `comparisonFun = "=="`, enabling faster counting when problems reduce to partition/composition counting.
 
 ## Improvements:
 
-* Added a package load-time check that validates the loaded shared library matches the installed package version, producing a clear reinstall/restart error instead of potential crashes from stale binaries.
-* Improved handling of singleton `v` with singleton `freqs` so that numeric values are interpreted correctly in some constrained/ranking paths.
-* Added nonexported `permutePartsDesign()` to inspect the partition-design/counting setup used by `permuteCount()` when it reduces to a partition/composition counting problem.
+* Added validation at package load time to ensure the loaded shared library matches the installed package version, producing a clear error message instead of potential crashes caused by stale compiled code.
+* Improved handling of certain constrained and ranking cases involving singleton inputs.
+* Added internal tooling to support partition and composition counting workflows.
 
 ## Performance:
 
-* General performance improvements for ranking and composition-related algorithms, including multi-threaded ranking support.
+* Improved performance of ranking and generation algorithms, including support for parallel ranking.
+* Improved performance and scalability of composition-related algorithms, particularly for constrained and distinct composition problems.
 
-## Internal:
+## Bug Fixes:
 
-* Added developer tooling and expanded internal type/class infrastructure to support the new composition and counting paths.
+* Fixed an issue in `permuteIter()` affecting cases that reduce to permutations of partitions, which could previously produce incorrect iteration results.
+* Improved input validation for constraint-based calls, producing clearer error messages for invalid inputs.
+* Fixed edge-case issues affecting certain partition and composition iteration scenarios.
 
 # RcppAlgos 2.9.5
 

inst/NEWS.Rd

@@ -1,37 +1,36 @@
 \name{NEWS}
 \title{News for Package \pkg{RcppAlgos}}
 
-\section{Changes in RcppAlgos version 2.10.0 (Release date: 2026-02-21)}{
+\section{Changes in RcppAlgos version 2.10.0 (Release date: 2026-03-05)}{
     \itemize{
-        \item New Features:
-        \itemize{
-            \item Added parallel capabilities to all ranking functions via the new \code{nThreads} argument (e.g. \code{partitionsRank(..., nThreads = 4)}, \code{comboRank(..., nThreads = 4)}).
-            \item Implemented a next-lexicographical algorithm for generating distinct integer compositions, enabling efficient large-scale generation such as \code{compositionsGeneral(50, 8)}.
-            \item Added accompanying algorithms for the distinct integer composition case, exposed through: \code{compositionsSample}, \code{compositionsRank}, and \code{compositionsIter}.
-            \item Enhanced \code{permuteCount()} to count permutations of partitions when called with \code{constraintFun = "sum"} and \code{comparisonFun = "=="}, allowing optimized counting in cases that reduce to partition/composition counting.
-        }
 
-        \item Bug Fixes:
+        \item New Features:
         \itemize{
-            \item Improved input validation for constraint-based calls by requiring \code{comparisonFun} to be a character vector (now errors early with a clearer message).
-            \item Fixed edge-case handling in partition iteration logic where boundary-derived indices could become negative, preventing incorrect behavior in some partition/multiset scenarios.
+            \item Added parallel capabilities to all ranking functions via the new \code{nThreads} argument (e.g. \code{comboRank()}, \code{partitionsRank()}, \code{compositionsRank()}), enabling faster ranking of large combinatorial results.
+            \item Implemented a next-lexicographical algorithm for generating distinct integer compositions, enabling efficient generation of large problems such as \code{compositionsGeneral(50, 8)}.
+            \item Added full support for distinct compositions across the compositional framework, including \code{compositionsGeneral()}, \code{compositionsSample()}, \code{compositionsRank()}, and \code{compositionsIter()}.
+            \item Added support for compositions with repetition subject to a maximum part constraint ("capped compositions"), including weak and non-weak cases, with full support for counting, ranking, sampling, and iteration.
+            \item Enhanced \code{permuteCount()} to count permutations of partitions when called with \code{constraintFun = "sum"} and \code{comparisonFun = "=="}, enabling faster counting when problems reduce to partition/composition counting.
         }
 
         \item Improvements:
         \itemize{
-            \item Added a package load-time check that validates the loaded shared library matches the installed package version, producing a clear reinstall/restart error instead of potential crashes from stale binaries.
-            \item Improved handling of singleton \code{v} with singleton \code{freqs} so that numeric values are interpreted correctly in some constrained/ranking paths.
-            \item Added nonexported \code{permutePartsDesign()} to inspect the partition-design/counting setup used by \code{permuteCount()} when it reduces to a partition/composition counting problem.
+            \item Added validation at package load time to ensure the loaded shared library matches the installed package version, producing a clear error message instead of potential crashes caused by stale compiled code.
+            \item Improved handling of certain constrained and ranking cases involving singleton inputs.
+            \item Added internal tooling to support partition and composition counting workflows.
         }
 
         \item Performance:
         \itemize{
-            \item General performance improvements for ranking and composition-related algorithms, including multi-threaded ranking support.
+            \item Improved performance of ranking and generation algorithms, including support for parallel ranking.
+            \item Improved performance and scalability of composition-related algorithms, particularly for constrained and distinct composition problems.
         }
 
-        \item Internal:
+        \item Bug Fixes:
         \itemize{
-            \item Added developer tooling and expanded internal type/class infrastructure to support the new composition and counting paths.
+            \item Fixed an issue in \code{permuteIter()} affecting cases that reduce to permutations of partitions, which could previously produce incorrect iteration results.
+            \item Improved input validation for constraint-based calls, producing clearer error messages for invalid inputs.
+            \item Fixed edge-case issues affecting certain partition and composition iteration scenarios.
         }
     }
 }

inst/include/Partitions/BigPartsCountDistinct.h

@@ -30,7 +30,7 @@ void CountPartsDistinctRstrctdMZ(
     int n, int m, const std::vector<int> &allowed, int strtLen
 );
 
-void CountCompDistLenRstrctd(
+void CountCompsDistLenRstrctd(
     mpz_class &res, std::vector<std::vector<mpz_class>> &p2d,
     int n, int m, const std::vector<int> &allowed, int strtLen = 0
 );

inst/include/Partitions/BigPartsCountRep.h

@@ -24,6 +24,12 @@ void CountCompsRepLen(
     const std::vector<int> &allowed = std::vector<int>(), int strtLen = 0
 );
 
+void CountCompsRepLenCap(mpz_class &res, int n, int m,
+                         const std::vector<int> &allowed, int strtLen = 0);
+
+void CountCompsRepCapZNotWk(mpz_class &res, int n, int m,
+                            const std::vector<int> &allowed, int strtLen = 0);
+
 void CountCompsRepZNotWk(
     mpz_class &res, int n, int m,
     const std::vector<int> &allowed = std::vector<int>(), int strtLen = 0

inst/include/Partitions/CompositionsRep.h

@@ -3,10 +3,19 @@
 #include "RMatrix.h"
 #include <vector>
 
+template <int one_or_zero, typename T>
+int CompsGenRepCapped(T* mat, const std::vector<T> &v, std::vector<int> &z,
+                      std::size_t width, std::size_t nRows);
+
 template <int one_or_zero, typename T>
 int CompsGenRep(T* mat, const std::vector<T> &v, std::vector<int> &z,
                 std::size_t width, std::size_t nRows);
 
+template <int one_or_zero, typename T>
+int CompsGenRepCapped(RcppParallel::RMatrix<T> &mat, const std::vector<T> &v,
+                      std::vector<int> &z, std::size_t strt,
+                      std::size_t width, std::size_t nRows);
+
 template <int one_or_zero, typename T>
 int CompsGenRep(RcppParallel::RMatrix<T> &mat, const std::vector<T> &v,
                 std::vector<int> &z, std::size_t strt,

…e/Partitions/CompositionsDistinctUtils.h …t/include/Partitions/CompositionsUtils.hinst/include/Partitions/CompositionsDistinctUtils.h renamed to inst/include/Partitions/CompositionsUtils.h inst/include/Partitions/CompositionsDistinctUtils.h renamed to inst/include/Partitions/CompositionsUtils.h

@@ -9,6 +9,9 @@ bool IsComplementZeroBased(bool firstZero, bool isWeak, bool IsGen);
 int GetFirstPartitionDistinct(const std::vector<int> &v, std::vector<int> &z,
                               int target, int m, int lenV);
 
+template <int one_or_zero>
+void FillTailRep(std::vector<int> &z, int strt, int cap, int lastCol);
+
 int NextDistinctBlock(const std::vector<int> &v, std::vector<int> &idx,
                       std::vector<int> &tailSum, int target, int m);
 

inst/include/Partitions/NextComposition.h

@@ -5,6 +5,9 @@
 template <int one_or_zero>
 void NextCompositionRep(std::vector<int> &z, int lastCol);
 
+template <int one_or_zero>
+void NextCompositionRep(std::vector<int> &z, int lastCol, int cap);
+
 void NextCompositionDistinct(
     std::vector<int> &z, std::vector<int> &complement, std::vector<int> &idx,
     std::vector<int> &tailSum, int &i1, int &i2, int &myMax, int lastCol,

inst/include/Partitions/PartitionsClass.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "Partitions/CompositionsDistinctUtils.h"
+#include "Partitions/CompositionsUtils.h"
 #include "Partitions/NextComposition.h"
 #include "ClassUtils/ComboResClass.h"
 #include "Partitions/NextPartition.h"