Repository files navigation

Copyright (C) 2018-2024Vincent 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 thatenable representing and generating permutations and sequences, as well as performingcomputation on permutations and sequences. It includes implementations of a varietyof 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 versionand minimum supported Java version.

The jar files of the library are released via Maven Central, GitHub Packages,and GitHub Releases.

The JPT usesSemantic Versioning with versionnumbers of the form: MAJOR.MINOR.PATCH, where differences in MAJORcorrespond to incompatible API changes, differences in MINOR correspondto introduction of backwards compatible new functionality, and PATCHcorresponds to backwards compatible bug fixes.

The JavaPermutationTools library is built using Maven. The root of therepository contains a Mavenpom.xml. To build the library,executemvn package at the root of the repository, whichwill compile all classes, run all tests, run javadoc, and generatejar files of the library, the sources, and the javadocs. All buildoutputs will then be found in the directorytarget.

To include generation of a code coverage report during the build,executemvn package -Pcoverage at the root of the repository toenable a Maven profile that executes JaCoCo during the testphase. 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), executemvn package -Panalysis to enable a Mavenprofile that executes the various static analysis tools that we areusing. The SpotBugs html report will be found in thetarget directory,or you can use the SpotBugs GUI with:mvn spotbugs:gui -Panalysis. Therefactor-first report will be found in thetarget/site directory.

To run all of the above:mvn package -P "analysis,coverage".

There are several example programs available in a separaterepository:cicirello/jpt-examples. Theexamples repository contains example usage of several of the classes of thelibrary. Each of the examples contains detailed comments within the sourcecode explaining the example. Running the examples without reading the sourcecomments is not advised. Some of the example in the examples repository arebased on the experiments from published papers that have either used the librarydirectly, 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 yourmodule-info.java:

moduleyour.module.name.here {requiresorg.cicirello.jpt;}

This module includes theorg.cicirello.permutations andorg.cicirello.sequencespackages as well as their subpackages. See theAPI documentationfor details of all packages included in this module.

Beginning with version 3.0.0, randomization and other math utilities, and somegeneric utilities, have beenmoved to a pair of new librariesρμandorg.cicirello.core, which arenow 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 insteadneed the following:

moduleyour.module.name.here {requiresorg.cicirello.jpt;requiresorg.cicirello.rho_mu;requiresorg.cicirello.core;}

Add this to the dependencies section of your pom.xml, replacing the version numberwith 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 toeachGitHub Release. If youmanually download jar files, make sure you also get the relevant versions of thedependencies. The simplest way to do this is to import from Maven Central, whichwill obtain the relevant dependencies automatically.

The JPT library is licensed under theGNU General Public License 3.0.

If you would like to contribute in any way, suchas reporting bugs, suggesting new functionality, or code contributionssuch as bug fixes or implementations of new functionality, then startby reading thecontribution guidelines.This project has adoptedtheContributor Covenant Code of Conduct.