Copyright (C) 2018-2024 Vincent A. Cicirello.
Website: https://jpt.cicirello.org/
API documentation: https://jpt.cicirello.org/api
| Publications About the Library |  |
|---|---|
| Packages and Releases |   |
| Build Status |    |
| JaCoCo Test Coverage |   |
| Security |   |
| DOI |  |
| Other Information |   |
| Support |    |
If you use this library in your research, please cite the following paper:
Cicirello, Vincent A (2018). JavaPermutationTools: A Java Library of Permutation Distance Metrics. Journal of Open Source Software, 3(31), 950. https://doi.org/10.21105/joss.00950 .
The JavaPermutationTools (JPT) library provides Java classes and interfaces, etc that enable representing and generating permutations and sequences, as well as performing computation on permutations and sequences. It includes implementations of a variety of permutation distance metrics as well as distance metrics on sequences (i.e., Strings, arrays, and other ordered data types).
We currently support Java 17+. See the following table for mapping between library version and minimum supported Java version.
| version | Java requirements |
|---|---|
| 4.w.x to 6.y.z | Java 17+ |
| 3.x.y | Java 11+ |
| 1.w.x to 2.y.z | Java 8+ |
The jar files of the library are released via Maven Central, GitHub Packages, and GitHub Releases.
The JPT uses Semantic Versioning with version numbers of the form: MAJOR.MINOR.PATCH, where differences in MAJOR correspond to incompatible API changes, differences in MINOR correspond to introduction of backwards compatible new functionality, and PATCH corresponds to backwards compatible bug fixes.
The JavaPermutationTools library is built using Maven. The root of the
repository contains a Maven pom.xml. To build the library,
execute mvn package at the root of the repository, which
will compile all classes, run all tests, run javadoc, and generate
jar files of the library, the sources, and the javadocs. All build
outputs will then be found in the directory target.
To include generation of a code coverage report during the build,
execute mvn package -Pcoverage at the root of the repository to
enable a Maven profile that executes JaCoCo during the test
phase. The JaCoCo report will also be found in the target directory.
To run all static analysis tools (i.e., SpotBugs, Find Security Bugs,
refactor-first), execute mvn package -Panalysis to enable a Maven
profile that executes the various static analysis tools that we are
using. The SpotBugs html report will be found in the target directory,
or you can use the SpotBugs GUI with: mvn spotbugs:gui -Panalysis. The
refactor-first report will be found in the target/site directory.
To run all of the above: mvn package -P "analysis,coverage".
There are several example programs available in a separate repository: cicirello/jpt-examples. The examples repository contains example usage of several of the classes of the library. Each of the examples contains detailed comments within the source code explaining the example. Running the examples without reading the source comments is not advised. Some of the example in the examples repository are based on the experiments from published papers that have either used the library directly, or which led to some of the code in the library.
This library provides a Java module, org.cicirello.jpt. To use in your project,
add the following to your module-info.java:
module your.module.name.here {
requires org.cicirello.jpt;
}This module includes the org.cicirello.permutations and org.cicirello.sequences
packages as well as their subpackages. See the API documentation
for details of all packages included in this module.
Beginning with version 3.0.0, randomization and other math utilities, and some generic utilities, have been moved to a pair of new libraries ρμ and org.cicirello.core, which are now dependencies of JavaPermutationTools. Your dependency manager (see next section) will handle downloading these for you.
If you are directly utilizing the functionality of the dependencies, then you may instead need the following:
module your.module.name.here {
requires org.cicirello.jpt;
requires org.cicirello.rho_mu;
requires org.cicirello.core;
}Add this to the dependencies section of your pom.xml, replacing the version number with the version you want to use.
<dependency>
<groupId>org.cicirello</groupId>
<artifactId>jpt</artifactId>
<version>5.0.0</version>
</dependency>If you'd prefer to import from Github Packages, rather than Maven Central, then: (1) add the dependency as indicated in previous section above, and (2) add the following to the repositories section of your pom.xml:
<repository>
<id>github</id>
<name>GitHub cicirello Apache Maven Packages</name>
<url>https://maven.pkg.github.com/cicirello/JavaPermutationTools</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>If you don't use a dependency manager that supports importing from Maven Central, or if you simply prefer to download manually, prebuilt jars are also attached to each GitHub Release. If you manually download jar files, make sure you also get the relevant versions of the dependencies. The simplest way to do this is to import from Maven Central, which will obtain the relevant dependencies automatically.
The JPT library is licensed under the GNU General Public License 3.0.
If you would like to contribute in any way, such as reporting bugs, suggesting new functionality, or code contributions such as bug fixes or implementations of new functionality, then start by reading the contribution guidelines. This project has adopted the Contributor Covenant Code of Conduct.