phyloexact (JaCK & Jill)

Author: Matthew D. Schwartz. Code written by Claude (Anthropic) under his supervision. Copyright (c) 2026 Anthropic, PBC. This is not an officially supported Anthropic product; it is maintained by Matthew D. Schwartz.

Register-honest, hardware-adaptive, self-certifying Bayesian evidence for phylogenetic substitution models: the register ladder R0 (decidability) / R1 (exact rationals) / R2 (rigorous enclosures) / R3 (estimates with measured calibration and a replicate spread), machine-checkable certificates with an independent verifier, the exact quintet rung and the large-scale Hill rung.

• GUIDE.md -- installation, the quickstart, every front door, how to read and verify a certificate, how to run the validation battery.
• SPEC.md -- the contract: registers, the certificate schema, the verifier's laws, the threat model (honest use), what is not built.
• MODELS.md -- the model x register matrix and each lane's mathematics.
• GATES.md -- the validation gates, generated from phyloexact/validate.py.
• AMBIGUITIES.md -- the conservative readings adopted where the specification leaves a choice open (how to interpret the outputs there).
• ROADMAP.md -- known limitations and future work.

Install: the package runs from its SOURCE TREE (the pinned bundle pins/, these pages and the examples live beside the package directory). Either pip install -e . from this directory (editable; Python >= 3.10; numpy, scipy, mpmath, sympy; optional python-flint for the R2 register, numba for the spectral-kit CPU engine and the GM kernel, torch + CUDA for the large-m R1 GPU backend) or put this directory on PYTHONPATH with those packages installed; then python -m phyloexact.validate runs the battery from any writable working directory. A non-editable build (pip install ., a wheel, python -m build) is NOT supported and is refused by name by the in-tree build backend -- see GUIDE.md, 'How to run the battery'.

License: MIT for the code, CC BY 4.0 for the written pages -- see LICENSE.

Maintenance, reporting and security

Maintenance. This repository is maintained by Matthew D. Schwartz, not by Anthropic. It is not an officially supported Anthropic product, and Anthropic does not provide support, updates or fixes for it.

Reporting issues. Please report bugs and security problems through this repository's GitHub issues.

Security considerations. Treat input files from others as code. These are research tools meant to be run locally on inputs you trust. Many of them evaluate the contents of their input files (JSON, YAML, .m, .ms, .jl, pickle and similar), so a file received from someone else can run arbitrary commands on your machine. Only run files you wrote yourself or got from a source you trust, or run them in a sandbox or container. The integrity checks and certificates in this repository guard against accidents. They are not a security boundary.

Prior work and acknowledgments

JaCK & Jill computes familiar objects to unfamiliar precision; the objects are other people's. The substitution models are those of Jukes and Cantor (1969), Kimura (1980, 1981), Felsenstein (1981), Hasegawa, Kishino and Yano (1985), Tavaré (1986), Yang (1994, discrete Γ), Barry and Hartigan (1987, general Markov), Tuffley and Steel (1998, covarion), Lartillot and Philippe (2004, CAT) and Rannala and Yang (2003, multispecies coalescent); likelihoods are Felsenstein's (1973, 1981) pruning algorithm. The exact registers live in the Hadamard/Fourier coordinates of Hendy and Penny (1989, 1993), Evans and Speed (1993) and Székely, Steel and Erdős (1993), whose algebraic structure was laid out by Cavender and Felsenstein (1987), Lake (1987), Allman and Rhodes (2003, 2008), Sturmfels and Sullivant (2005) and Pachter and Sturmfels (2005); Chang (1996) and Allman and Rhodes settle the identifiability the GM lane relies on. The estimators we grade against and learn from are thermodynamic integration (Lartillot and Philippe 2006), stepping-stone and generalized stepping-stone sampling (Xie, Lewis, Fan, Kuo and Chen 2011; Fan, Wu, Chen, Kuo and Lewis 2011) and nested sampling (Skilling 2006; Maturana Russel et al. 2019); Oaks et al. (2019) and Fourment et al. (2020) review them. Model adequacy by posterior prediction follows Bollback (2002) and Goldman (1993), whose unconstrained likelihood is also the Hill ceiling. The programs whose conventions the Hill rung documents, and whose authors we thank, are IQ-TREE and IQ-TREE 2 (Nguyen et al. 2015; Minh et al. 2020), RAxML and RAxML-NG (Stamatakis 2014; Kozlov et al. 2019), PAUP* 4 (Swofford), MrBayes 3.2 (Ronquist et al. 2012), BEAST 1.10 and BEAST 2.5 (Suchard et al. 2018; Bouckaert et al. 2019), physher (Fourment and Holmes 2014), RevBayes (Höhna et al. 2016), PhyloBayes (Lartillot, Lepage and Blanquart 2009), PAML 4 (Yang 2007), ASTER/wASTRAL (Zhang and Mirarab 2022), wQFM (Mahbub et al. 2021), and MODELTEST, ModelFinder and PartitionFinder 2 (Posada and Crandall 1998; Kalyaanamoorthy et al. 2017; Lanfear et al. 2017). The numerics rest on Arb and FLINT (Johansson 2017; Hart 2010) through python-flint (Johansson, Benjamin and contributors), on mpmath, NumPy, SciPy and SymPy, on scrambled Sobol' sequences (Sobol' 1967; Joe and Kuo 2008) via scipy.stats.qmc (Roy, Owen, Balandat and Haberland 2023), on the importance-sampling mixtures of Veach and Guibas (1995), Hesterberg (1995) and Owen and Zhou (2000), on the sequential Monte Carlo samplers of Del Moral, Doucet and Jasra (2006) with annealing after Neal (2001), on the partition-backtrack and individualization–refinement methods of Leon (1991) and McKay and Piperno (2014), and on Higham's (2002) rounding-error analysis. Amino-acid recodings are those of Dayhoff, Schwartz and Orcutt (1978), Susko and Roger (2007) and Kosiol, Goldman and Buttimore (2004). Data: NCBI RefSeq (O'Leary et al. 2016), Rfam 14 (Kalvari et al. 2021), the primate lysozyme alignment of Messier and Stewart (1997) as distributed with PAML, and UCE loci from Zhao, Thom, Faircloth et al. (2026). Full references with DOIs: GUIDE.md, "References". We are grateful to all of these authors and maintainers; errors in how we use their work are ours.

Experimental features

The package has a WARRANTED CORE and an EXPERIMENTAL set. Experimental means: served and tested by the battery, results labelled with their register, but the interfaces may change, and certificate verification across package versions is promised only for the core. The experimental set:

• the PAIL doors: px.pail_evidence, px.pail_row, px.pail_aggregate;
• prior= with a non-default prior, and px.PlugIn user models;
• the hill genome-scan command-line tools and APIs (python -m phyloexact.hill.scan, .weights, .verify_cert, px.hill.sup_ceiling_partitioned);
• px.quintet.adjudicate's tuning options (cap, total_budget, nstarts);
• px.check_adequacy's estimate (R3) route and px.prior_predictive;
• dataset= handed to verify_certificate as a path, a mapping or a superset (a Dataset object is core).

Everything else -- the exact and enclosure registers, the R3 estimates under the default prior, the topology sum, compare / compare_models / grade_model, R0 decidability, the verifier on a certificate with or without its Dataset -- is the warranted core. Known limitations and future work: ROADMAP.md at the package root.