Home

Awesome

Example Programs for the JavaPermutationTools (JPT) Library

Copyright (C) 2018-2024 Vincent A. Cicirello. https://www.cicirello.org/

Packages and ReleasesMaven Central GitHub release (latest by date)
Build Statusbuild CodeQL
SecuritySnyk security score Snyk Known Vulnerabilities
Other InformationGitHub style
SupportGitHub Sponsors Liberapay Ko-Fi

This repository contains several example programs of the usage of the JavaPermutationTools (JPT) library. 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). JPT's source code is maintained on GitHub, and the prebuilt jars of the library can be imported from Maven Central using maven or other build tools. The purpose of this repository is to demonstrate usage of the major functionality of the JPT library.

The Example Programs

The source for several example programs is contained in this repository. Read the comments in the source code of the example programs for a description of what they demonstrate, etc. Running the examples without reading the source code, and comments, is not advised, since the output of the example programs requires the context of the code samples to be meaningful.

Basic Functionality Examples: The following examples are of basic usage of various functionality of the library:

org.cicirello.replication.arxiv2019may: There are four programs in this package that replicate the data from the paper that defined the Kendall Tau Sequence Distance, along with descriptions of the two algorithms for computing it used in the JPT. Kendall Tau Sequence Distance is an extension of the well-known Kendall Tau Distance for permutations to be applicable to Strings and other sequences. The data generated by these programs is that of the paper: V.A. Cicirello, "Kendall Tau Sequence Distance: Extending Kendall Tau from Ranks to Sequences," arXiv preprint arXiv:1905.02752 [cs.DM]. May 2019. https://www.cicirello.org/publications/cicirello2019arXiv.html. These four programs are as follows:

org.cicirello.replication.bict2019.BICT2019: This program generates the data for the principal component analysis, as well as the fitness distance correlation data, from the paper: V. A. Cicirello, "Classification of Permutation Distance Metrics for Fitness Landscape Analysis," in Proceedings of the 11th International Conference on Bio-inspired Information and Communications Technologies. March 2019. https://www.cicirello.org/publications/cicirello2019bict.html.

org.cicirello.replication.flairs2013.Flairs2013: This program generates the correlation data that appears in Tables 1 and 2, as well as the data necessary to generate the graphs in Figures 1, 2, 3, 4, and 5 of the paper: V. A. Cicirello and R. Cernera, "Profiling the distance characteristics of mutation operators for permutation-based genetic algorithms," in Proceedings of the 26th FLAIRS Conference. AAAI Press, May 2013, pp. 46–51. https://www.cicirello.org/publications/cicirello2013flairs.html.

org.cicirello.replication.ieeetevc2016.FDC: This program generates the fitness distance correlations for the "Permutation in a Haystack" fitness landscapes found in Table II of the paper: V.A. Cicirello, "The Permutation in a Haystack Problem and the Calculus of Search Landscapes," IEEE Transactions on Evolutionary Computation, 20(3):434-446, June 2016. https://www.cicirello.org/publications/cicirello2016evc.html.

Versioning Scheme

The version numbers for the example programs mirror the versions of JavaPermutationTools (JPT). The version may or may not be incremented upon every new release of the JPT library. The version number of the examples corresponds to the version of the JPT library used in that release. The examples should run against newer versions of the JPT library provided the MAJOR portion of the version number is the same.

The JPT library 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.

Prebuilt Jars of the Examples

Since the purpose of the example programs is to demonstrate usage of the JPT library, you will most likely want to build the examples directly from the source (see the sections that follow). However, we also provide jars of the compiled examples, as well as of the source and javadocs, in a variety of ways:

If you use the example programs in precompiled form, you will also need a compatible version of the JPT library, and its dependencies. If you build the examples from the source, the build process will take care of downloading these for you. But if you choose to use the prebuilt jars, you can find the jars of the JPT library likewise in Maven Central, GitHub Releases, and GitHub Packages.

Requirements to Build and Run the Example Programs from the Source

To build and run the examples on your own machine, you will need the following:

Building the Example Programs with Maven

The source code of the example programs are in the src/main/java directory. You can build the example programs in one of the following ways:

This build process follows the usual Maven directory structure, so the .class files, .jar files, etc will be found in a target directory that is created by the build process.

To run various static analysis tools (e.g., SpotBugs, FindSecBugs, etc) during the build, run: mvn clean package -Panalysis.

Running the Example Programs with Maven

Once you have successfully executed the build above, you can run the examples of basic library functionality by executing make examples at the root of the repository. This will run each of the example programs in sequence. Be aware that the examples are intended to illustrate how to use the JPT library, so will be most meaningful if you read the source code, which includes comments explaining what they are doing. If you would rather run them one at a time, see the examples target in the Makefile for the main classes to execute.

There are additional examples (see list in earlier section above) that are based on the experiments of a few published papers that either used the library, or which led to the code of the library (i.e., originally used preliminary versions of some of the library code). There are targets in the makefile for each of these, so you can run those by executing the following: make arxiv2019, make bict2019, make flairs2013, and make tevc2016.

License

The example programs in this repository are licensed under the GNU General Public License 3.0.