Skip to content

gpmap-v2

A typed, Rust-accelerated container and simulator toolkit for genotype-phenotype maps. Clean-break rewrite of harmslab/gpmap, with a locked schema, vectorized hot paths, and a PyO3 core for the operations that used to be inner Python loops.

  • Quickstart

    Build a GenotypePhenotypeMap, inspect its packed binary representation, and round-trip through JSON or CSV.

    Read the quickstart

  • Installation

    Install from PyPI with uv or pip. Source builds need a Rust toolchain.

    Install gpmap-v2

  • Concepts

    The container model, the encoding table, and the schema contract that downstream consumers depend on.

    Learn the model

  • Reference

    Per-module API reference for the container, simulators, I/O, statistics, and exceptions.

    Browse the reference

What you get

  • Fast. String-encoded genotypes are replaced with packed uint8 matrices. The encoding step (genotypes_to_binary) runs rayon-parallel in Rust. Construction is 5x faster than v1 at L=16 (65k genotypes), and binary_packed is a free cached lookup afterward, with no repeated re-encoding on each access.
  • Typed. Full type hints, mypy-checked, strict mode.
  • Safe. Cartesian-product enumeration is size-guarded out of the box via SpaceTooLargeError. No more silent 10^26 allocations.
  • Stable surface. The container and encoding_table schema are locked in SCHEMA.md for downstream consumers.
  • Modern tooling. uv plus maturin plus pyproject.toml. Automated releases via python-semantic-release. OIDC-based PyPI publishing.

Live demo

A multi-page Streamlit tour is published at gpmap-v2.streamlit.app; the source lives under examples/streamlit/ in the repo.

Status

Phase 1 port complete. Phase 2 Rust kernel (gpmap._rust) covers the dominant hot paths: encoding, enumeration, hamming reference distances. The schema in SCHEMA.md is the load-bearing contract that epistasis-v2 and gpgraph-v2 consume.

Next steps

Pick the page that matches what you want to do: