tda4j
Persistent homology and topological data analysis on the JVM and in JavaScript: from Scala, Java, MATLAB, JavaScript, TypeScript and the command line.
tda4j computes persistent homology of point clouds (Vietoris-Rips, Čech, alpha, witness, Dowker, DTM and sparse Rips
complexes), images (cubical complexes), simplicial sets and nerves of groups, monoids and categories. Every barcode
comes with a representative cycle or cocycle for each bar, over any prime field. It is built for ease of use, for
access from MATLAB and other JVM languages, and as a platform for research: the machinery behind the convenient entry
points is public and meant to be extended. It descends from the libraries of the Computational Topology workgroup at
Stanford University (JavaPlex, JPlex, PLEX).
Using it
Installation lists requirements and dependency lines
for every build tool. In short, from sbt (Java 21, Scala 3.9):
libraryDependencies += "org.appliedtopology" %% "tda4j" % "VERSION"
import scala.language.experimental.modularity
import org.appliedtopology.tda4j.*
val points = Array.tabulate(30)(i => Array(math.cos(i * 0.21), math.sin(i * 0.21)))
val diagram = Persistence(points) // degrees 0 to 2, coefficients in the field with 17 elements
diagram.dim(1).longest // the most persistent loop, with a representative cycle
From Java, with tda4j-VERSION-assembly.jar on the class path:
import org.appliedtopology.tda4j.matlab.*;
double[][] points = { {0, 0}, {1, 0}, {1, 1}, {0, 1} };
PersistenceResult result = TDA4j.computeFromPoints(points, new String[] {"maxDimension", "1"});
double[][] bars = result.toArray(); // one row per bar: dimension, birth, death
From MATLAB, javaaddpath('tda4j-VERSION-assembly.jar') and the same calls
(MATLAB and Java). From the command line,
java -jar tda4j-VERSION-assembly.jar --max-dimension 1 points.csv. The jar is on the
releases page.
From JavaScript or TypeScript (browsers, and Node.js 20.16 or newer):
npm install @appliedtopology/tda4j
import { persistence } from "@appliedtopology/tda4j";
const result = persistence([[0, 0], [1, 0], [1, 1], [0, 1]], { maxDimension: 1 });
result.bars; // [{ dim: 0, birth: 0, death: Infinity }, ...]
In a Scala.js project the same sbt line picks the Scala.js artifact. tda4j-demo-VERSION.jar is a self-contained Scala REPL with the
library imported: java -jar tda4j-demo-VERSION.jar.
Documentation
tda4j.appliedtopology.org has the user guide (with the
quickstart), tutorials, the API reference and the
developer's guide. For persistent homology itself, we recommend the book
Topological Data Analysis with Applications
or Gunnar Carlsson's survey Topology and Data.
Presentations
Contributing
CONTRIBUTING.md covers setting up, the commands, the workflow from issue to pull request, and the
design principles. Questions, limitations and planned work are tracked as
issues; CHANGELOG.md lists what changed in each
release. The people behind tda4j are in CONTRIBUTORS.md.
To cite tda4j, use GitHub's "Cite this repository" (CITATION.cff). Security reports:
SECURITY.md. tda4j is released under the MIT License.
