v3.0.0

JNumberTools

JNumberTools is an open-source Java library designed to provide powerful tools for solving complex problems in combinatorics and number theory. Whether you're a researcher, developer, or student, this library offers a comprehensive set of APIs to efficiently handle a wide range of mathematical tasks, from basic functions to advanced combinatorial computations.

Optimized for performance, JNumberTools allows you to tackle challenging combinatorics problems—such as permutations, combinations, conditional-cartesian-products, ranking, partitions, and more—without the need to develop custom algorithms. Seamlessly integrate these capabilities into your projects to streamline both academic and practical applications in fields like mathematics, cryptography, data analysis, and algorithm design.

Key Features:

1. Versatile and efficient APIs for various combinatorics and number-theory operations.
2. Ideal for educational, research, and real-world problem-solving in fields such as cryptography, computer science, and optimization.
3. Optimized for both small-scale and large-scale problems, delivering high performance.

latest version

The latest release of the library is v3.0.0.
It is available through The Maven Central Repository here.
Add the following section into your pom.xml file.

<dependency>
    <groupId>io.github.deepeshpatel</groupId>
    <artifactId>jnumbertools</artifactId>
    <version>3.0.0</version>
</dependency>

Currently Available Algorithms

1. Permutations: 10 different types of permutations

   1. Unique permutation in lex order
   2. Every m^th unique permutation in lex order
   3. Repetitive permutation in lex order
   4. Every m^th repetitive permutation in lex order
   5. k-permutation in lex order
   6. Every m^th k-permutation in lex order
   7. k-permutation in combination order
   8. Every m^th permutation in combination order
   9. Multiset permutation in lex order
   10. Every m^th multiset permutation in lex order

2. Combinations: 5 different types of combinations

   1. Uniques combination in lex order
   2. Every m^th unique combination in lex order
   3. Repetitive combination in lex order
   4. Every m^th repetitive combination in lex order
   5. Multiset combination in lex order
   6. Every m^th multiset combination in lex order: Coming soon

3. Set/subset generations: 4 different types available

   1. All subsets of a given set in lex order
   2. Every m^th of all subsets in lex order
   3. All subsets in a given size range in lex order
   4. Every m^th of subsets in a given size range in lex order

4. Cartesian Product: 4 different types of product

   1. Simple Cartesian product in lex order
   2. Every m^th cartesian product in lex order
   3. Complex Cartesian product in lex order
   4. Every m^th complex cartesian product in lex order

5. Ranking of permutations & combinations

   1. Ranking of unique permutation
   2. Ranking of k-permutation
   3. Ranking of repetitive permutation
   4. Ranking of unique combination
   5. Rank of repetitive combination : Coming soon
   6. Rank of multiset permutation : Coming soon
   7. Rank of multiset combination : Coming soon

6. Number system algorithms related to combinatorics

   1. Factorial Number System aka Factoradic
   2. Permutation Number System aka Permutadic
   3. Combinatorial Number System aka Combinadic

---

1. Permutations

1.1 Unique permutation

Used to generate all n! unique permutations of n elements in lex order

//generates all permutations of integers in range [0,3)
JNumberTools.permutations()
   .unique(3)
   .lexOrder().stream().toList();

//generates all permutations of "Red", "Green" and "Blue" in lex order
JNumberTools.permutations()
    .unique( "Red", "Green", "Blue")
    .lexOrder().stream().toList();

1.2 m-th Unique permutation

Generate every m^th permutation in lexicographical order of indices of input
values starting from given start index

This is important because say, if we need to generate next 100 trillionth permutation
of 100 items then it will take months to compute if we go sequentially and then increment
to the desired permutation because the total # of permutations is astronomical
(100!= 9.3326 x 10m¹⁵⁷)

int m = 2;
        int start = 5;

//generates 5th, 7th, 9th.. permutations of [0,5)
        JNumberTools.permutations()
        .unique(5)
        .lexOrderMth(m,start)
        .stream().toList();

//generates 5th, 7th, 9th.. permutations of elements in lex order
        JNumberTools.permutations()
        .unique("A","B","C","D","E")
        .lexOrderMth(m,start)
        .stream().toList();

1.3 Repetitive permutation

This is same as generating base-n numbers of max size r-digits with given n symbols, starting
from 0^th permutation in lex order. There are total n^r such permutations

//generates al permutations of 3 digits with repetition allowed from [0,5)
JNumberTools.permutations()
    .repetitive(3, 5)
    .lexOrder()
    .stream().toList();

//generates all permutations of 3 elements out of given elements with repetition allowed
JNumberTools.permutations()
    .repetitive(3,"A","B","C","D","E")
    .lexOrder()
    .stream().toList();

1.4 m-th Repetitive permutation

This is same as generating AP series of base-n numbers with given n-symbols and
a=start, d=m and max-digits = r. There are total n^r/m such permutations

//generates every 2nd repetitive permutations of 3 numbers in range [0,5)
//starting from 5th. That is, 5th, 7th, 9th, and so on 
int m = 2;
int start = 5;
JNumberTools.permutations()
        .repetitive(3, 5)
        .lexOrderMth(m,start)
        .stream().toList();

//generates every 2nd repetitive permutations of 3 elements out of given elements
//starting from 5th. That is, 5th, 7th, 9th, and so on 
        JNumberTools.permutations()
        .repetitive(3,"A","B","C","D","E")
        .lexOrderMth(m,start)
        .stream().toList();

1.5 k-permutation

Generates all unique permutations of size k where 0 ≤ k ≤ n and n is the number of
input elements in lex order. In number theory, this is also known as k-permutation.
There are total ⁿP_k such permutations possible

//generates all permutations of size '2' out of 5 numbers in range [0,5)
JNumberTools.permutations()
     .nPk(5,2)
     .lexOrder()
     .stream().toList();

//generates all permutations of '2' elements out of list of elements
     JNumberTools.permutations()
     .nPk(2,"A","B","C","D","E")
     .lexOrder()
     .stream().toList();

1.6 m-th k-permutation

Generates every m^th k-permutation in lex order without computing permutations
preceding it. This concept is important because the total number of permutations can grow
astronomically large. For instance, the number of permutations of 100 elements selected 50
at a time is 100P50 = 3.068518756 x 10⁹³, which is way beyond the practical limit
to be generated sequentially to reach the desired permutation.

To achieve this, a concept called Permutational Number System(Permutadic) and Deep-code(a generalization of Lehmer code)
is used. Details can be found in the research paper - Generating the nth Lexicographical
Element of a Mathematical k-Permutation using Permutational Number System

//generates every 3rd permutation starting from 0th of size 3 out of 10 
// numbers in range [0,10]. that is 0th, 3rd, 6th, 9th and so on
JNumberTools.permutations()
        .nPk(10,5)
        .lexOrderMth(3, 0)
        .stream().toList();

//generates every 3rd permutation starting from 0th of size 3 out of list of n elements
//that is 0th, 3rd, 6th, 9th and so on
        JNumberTools.permutations()
        .nPk(2,"A","B","C","D","E")
        .lexOrder()
        .stream().toList();

1.7 k-permutation in combination order

Generates all k-permutations in the lexicographical order of combination. For example, [C,A] comes before [B,C]
because combination-wise [C,A] = [A,C]. Note that the API does not sort the output to achieve this,
but it generates the permutation in said order, so it is very efficient.

//generates all k-permutations for ...

V1.0.2

Optimised and added UniquePermutationInSizeRangeTest

Initial Release

V1.0.0

Initial code push