https://github.com/cicirello/jpt-examples
Example programs for the JavaPermutationTools (JPT) library
https://github.com/cicirello/jpt-examples
distance permutation-distance permutations sequences string-distance
Last synced: 12 months ago
JSON representation
Example programs for the JavaPermutationTools (JPT) library
- Host: GitHub
- URL: https://github.com/cicirello/jpt-examples
- Owner: cicirello
- License: gpl-3.0
- Created: 2021-01-26T19:10:36.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-06T11:26:01.000Z (12 months ago)
- Last Synced: 2025-05-06T12:48:25.983Z (12 months ago)
- Topics: distance, permutation-distance, permutations, sequences, string-distance
- Language: Java
- Homepage:
- Size: 292 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Example Programs for the JavaPermutationTools (JPT) Library
Copyright (C) 2018-2024 Vincent A. Cicirello. https://www.cicirello.org/
| __Packages and Releases__ | [](https://central.sonatype.com/artifact/org.cicirello/jpt-examples/) [](https://github.com/cicirello/jpt-examples/releases) |
| :--- | :--- |
| __Build Status__ | [](https://github.com/cicirello/jpt-examples/actions/workflows/build.yml) [](https://github.com/cicirello/jpt-examples/actions/workflows/codeql-analysis.yml) |
| __Security__ | [](https://snyk.io/vuln/maven%3Aorg.cicirello%3Ajpt-examples) [](https://snyk.io/test/github/cicirello/jpt-examples) |
| __Other Information__ | [](https://github.com/cicirello/jpt-examples/blob/main/LICENSE) [](https://google.github.io/styleguide/javaguide.html) |
| __Support__ | [](https://github.com/sponsors/cicirello) [](https://liberapay.com/cicirello) [](https://ko-fi.com/cicirello) |
This repository contains several example programs of the
usage of the [JavaPermutationTools (JPT)](https://jpt.cicirello.org)
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](https://github.com/cicirello/JavaPermutationTools) is
maintained on GitHub, and the prebuilt jars of the library can be imported
from [Maven Central](https://central.sonatype.com/artifact/org.cicirello/jpt/)
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.examples.jpt.AverageDistance
* org.cicirello.examples.jpt.TableOfDistances
* org.cicirello.examples.jpt.PermutationExamples
* org.cicirello.examples.jpt.SimpleDistanceExamples
* org.cicirello.examples.jpt.SequenceDistanceExamples
* org.cicirello.examples.jpt.PermutationHashCodes
* org.cicirello.examples.jpt.RandomIndexerTimes
__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.arxiv2019may.CompareKendallTauSequenceDistAlgsDoubles
* org.cicirello.replication.arxiv2019may.CompareKendallTauSequenceDistAlgsInts
* org.cicirello.replication.arxiv2019may.CompareKendallTauSequenceDistAlgsStrings
* org.cicirello.replication.arxiv2019may.CompareKendallTauSequenceDistAlgsStringArray
__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)](https://jpt.cicirello.org). 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](https://semver.org/) 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:
* [GitHub releases](https://github.com/cicirello/jpt-examples/releases)
* [Maven Central](https://central.sonatype.com/artifact/org.cicirello/jpt-examples/)
* [GitHub Packages](https://github.com/cicirello?tab=packages&repo_name=jpt-examples)
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](https://github.com/cicirello/JavaPermutationTools)
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:
* __JDK 17__: Beginning with v4.0.0, the minimum supported Java version for the
JavaPermutationTools library is Java 17, so you will need Java 17+ for the example programs.
* __Apache Maven__: In the root of the repository, there is a pom.xml for building the example programs. Using this pom.xml, Maven will take care of downloading the most recent version of the [JavaPermutationTools](https://jpt.cicirello.org/) library for which the examples have been tested, as well as JPT's dependencies. The examples should also work with more recent versions of the library.
* __Make__ (optional): The repository also contains a Makefile to simplify running the build, and running the example programs. If you are familiar with using the Maven build tool, then you can just run these directly, although the Makefile may be useful to see the specific commands needed, such as the main classes to execute for the example programs.
## Building the Example Programs with Maven
The source code of the example programs are
in the [src/main/java](src/main/java) directory. You can build the example
programs in one of the following ways:
* Execute `mvn package` at the root of the repository (`mvn compile` should also be sufficient, but only generates `class` files, while `mvn package` generates `jar` files).
* Execute `make` or `make build` at the root of the repository (which simply executes a `mvn package`).
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](https://www.gnu.org/licenses/gpl-3.0.en.html).