---
title: 'PhysLib: Formal Physics & Geometric Software'
url: https://www.emergentmind.com/topics/physlib
type: topic
---

# PhysLib: Formal Physics & Geometric Software

Searching arXiv for papers referring to “PhysLib” to ground the article in published sources.
PhysLib is a name used for distinct research software artifacts in contemporary scientific computing, most prominently for formal-physics libraries in the Lean ecosystem and, separately, for polygonal metric-geometry visualization software. In the Lean context, PhysLib denotes a community-run physics library that supplies reusable formal infrastructure on top of Lean and Mathlib; one line of work describes it as the largest physics library in Lean and notes that it was formerly called PhysLean and merged with Lean-QuantumInfo [2603.08139], while another presents it as a foundational Lean4 repository containing unit systems and topic-specific theorems for college-level formal physics reasoning [2510.26094]. In a different computational-geometry context, PhysLib refers to educational and research software for visualizing Funk, reverse Funk, Thompson, and Hilbert geometries inside convex polygonal domains [2503.01988]. The term therefore does not designate a single monolithic package across all of arXiv, but rather a small family of domain-specific software systems whose common feature is the provision of reusable technical infrastructure for research and pedagogy.

## 1. Lean-based PhysLib as formal physics infrastructure

In the formal-methods literature, PhysLib is presented as a shared library for mechanized physics reasoning in Lean. The 2026 paper on formalizing two-Higgs-doublet-model stability states that PhysLib is the largest physics library in Lean, that it was formerly called PhysLean, and that it merged with Lean-QuantumInfo; it is described as open-source and community-run, with a philosophy of formalizing physics in the way physicists reason in papers rather than axiomatizing all of physics from first principles [2603.08139]. In that work, PhysLib supplies the formalization environment for Higgs-doublet objects, the 2HDM potential, stability statements, and the proof and counterexample that expose an error in the literature [2603.08139].

A closely related but not identical description appears in Lean4PHYS, where PhysLib is introduced as a community-driven repository containing fundamental unit systems and theorems essential for formal physics reasoning in Lean4 [2510.26094]. There, PhysLib is framed as the domain-specific layer missing from Mathlib: mathematics libraries provide algebraic and analytic foundations, but formal physics additionally requires unit systems, dimension handling, physics quantities, and reusable theorems stated in physically meaningful types [2510.26094].

Taken together, these accounts indicate that “PhysLib” in Lean refers less to a frozen software release than to an evolving formalization substrate. This suggests a continuity of purpose across versions and naming conventions: reusable domain infrastructure for mechanically verified physics arguments.

## 2. Architectural organization in Lean4

Lean4PHYS gives the most explicit architectural account of PhysLib. It describes the repository as built bottom-up and organized into three layers: a **Foundation unit system**, a **Topic-specific unit system**, and **Topic-specific theorems** [2510.26094]. This stratification is intended to preserve a stable base while allowing topic-level growth and regular extension of theorem collections [2510.26094].

The foundational layer extends Mathlib4 and the Lean4 UnitSystem kernel from Terence Tao’s `teorth_analysis` project, implementing the seven SI base units: time, length, mass, electric current, temperature, amount of substance, and luminous intensity [2510.26094]. The same paper states that PhysLib also defines basic Normed Space, algebraic computation, and derivatives for the physics unit system, proves interchangeability between physics quantities and mathematical quantities, and introduces a physics dimension cast together with proofs that such casts preserve mathematical correctness or propriety [2510.26094].

At the topic level, PhysLib organizes content into six major areas: mechanics, waves and acoustics, thermodynamics, electromagnetism, optics, and modern physics [2510.26094]. The implementation strategy is to create separate namespaces and Lean files for each topic, add topic-specific unit types and constants inside those namespaces, implement basic physics rules as definitions, and then implement theorems and proofs relevant to that topic [2510.26094]. The paper notes that the mechanics section is currently the most developed and serves as the example foundation for the rest of the library [2510.26094].

This layered organization is significant because it mirrors the dependency structure of actual physics formalization: unit-safe quantitative expressions at the base, topic-local semantics in the middle, and theorem reuse at the top.

## 3. Formal language, units, and proof ergonomics

A central technical contribution of Lean-based PhysLib is the embedding of unit-aware physical quantities directly into theorem statements. Lean4PHYS illustrates this with statements whose variables carry types such as `Length`, `Time`, `Speed`, `Acceleration`, `Charge`, `Force`, and `Mass`, and with expressions involving unit constructors like `second`, `meter`, `coulomb`, and `newton` [2510.26094]. The paper identifies reusable lemmas and interfaces including `Scalar.val_inj`, unit constructors and simplification lemmas such as `SI.nano`, `milli`, `coulomb`, `meter`, `newton`, support for `.cast`, and rules for extracting `.val` and simplifying unit-bearing expressions [2510.26094].

The practical effect is that once unit-aware expressions are reduced to their scalar content, standard Lean tactics such as `simp` and `norm_num` become effective on the remaining arithmetic structure [2510.26094]. In the electromagnetism example, a proof of a Coulomb-force expression is closed by simplification over `Scalar.val_inj`, explicit unit constructors, and numerical normalization [2510.26094]. The same pattern appears in more advanced statements involving force balance, friction, calculus, and logarithms [2510.26094].

This is not merely notation. A plausible implication is that PhysLib functions simultaneously as a type discipline for dimensional consistency and as a tactic-enabling normalization layer that translates physically typed statements into proof obligations manageable by existing mathematical automation.

## 4. Research use in high-energy physics formalization

The 2026 2HDM formalization paper demonstrates PhysLib in a research-level setting beyond textbook examples. Using Lean, Mathlib, and PhysLib, the paper formalizes the structure of the two Higgs doublet model potential, including Higgs doublets \(\Phi_1,\Phi_2 \in \mathbb{C}^2\), the associated Gram matrix, the Pauli-basis-derived Gram vector \(K_\mu\), and the reparameterized potential
\[
V = \sum_{\mu=0}^3 \xi_\mu K_\mu + \sum_{\mu,\nu=0}^3 \eta_{\mu\nu} K_\mu K_\nu
\]
together with the stability question of whether \(V\) is bounded from below [2603.08139].

The paper identifies a specific flaw in a widely cited 2006 theorem on 2HDM potential stability: the claimed equivalence between the full stability condition and “Condition C” fails because Condition C is necessary but not sufficient [2603.08139]. It then gives a corrected reduction, formalized in Lean, stating that stability is equivalent to the existence of \(c \ge 0\) such that for all \(\vec k\) with \(\|\vec k\|^2 \le 1\),
\[
0 \le J_4(\vec k)
\quad\text{and}\quad
\bigl(J_2(\vec k)<0 \Rightarrow J_2(\vec k)^2 \le 4\,c\,J_4(\vec k)\bigr)
\]
[2603.08139].

The same work provides an explicit counterexample with
\[
m_{11}^2 = m_{22}^2 = 0,\qquad m_{12}^2 = i,
\]
\[
\lambda_1=\lambda_2=\lambda_3=\lambda_4=\lambda_5=2,\qquad \lambda_6=\lambda_7=-2,
\]
for which the potential simplifies to
\[
V = 2\,\mathrm{Im}(\Phi_1^\dagger \Phi_2) + \|\Phi_1-\Phi_2\|^4,
\]
satisfies Condition C, yet is not stable [2603.08139].

This use case establishes PhysLib as more than a pedagogical unit library. It supports formal verification of nontrivial research mathematics in physics and can expose logically invalid theorem reductions in the published literature. The paper explicitly states that this is, to the best of the author’s knowledge, the first non-trivial error in a physics paper found through formalization [2603.08139].

## 5. PhysLib within Lean4PHYS and benchmark-driven development

Lean4PHYS integrates PhysLib into a broader benchmarking framework for college-level formal physics reasoning. The paper presents LeanPhysBench as a benchmark of 200 hand-crafted and peer-reviewed statements derived from university textbooks and physics competition problems, and states that these benchmark statements are formalized using PhysLib [2510.26094]. The benchmark contains 104 college-level statements and 96 competition-level statements, the latter divided into 62 easy and 34 hard problems [2510.26094].

PhysLib is described as the foundation on which this benchmark is built: if a benchmark problem requires a physics law not already present, it is added to PhysLib, after which the new theorem is written using that library support and checked by Lean’s verifier and expert review [2510.26094]. Prompt templates in the appendix explicitly instruct models to “learn the new library besides mathlib” and “refer to the new unit system,” with PhysLib injected into the proof-generation context [2510.26094].

The paper reports baseline theorem-proving performance for several models and states that PhysLib yields an average improvement of **11.75%** in model performance [2510.26094]. It further reports that DeepSeek-Prover-V2-7B achieves **16%** and Claude-Sonnet-4 achieves **35%** on the benchmark [2510.26094]. The experimental protocol evaluates models with and without PhysLib using Pass@16, and the paper attributes improvements to better in-context understanding of the unit system and improved theorem selection [2510.26094].

These results position PhysLib as a knowledge substrate for machine-assisted theorem proving in physics. A plausible implication is that the library serves two roles simultaneously: formal repository for human-authored theorems and retrieval-like contextual scaffold for LLM-based proof synthesis.

## 6. Polygonal-geometry PhysLib: a distinct software system

Separate from Lean, the name PhysLib is used in computational geometry for software devoted to polygonal metric spaces. The paper “Software for the Thompson and Funk Polygonal Geometry” presents PhysLib as educational and research software for polygonal metric geometry, focused on convex polygons and on the Funk, reverse Funk, Thompson, and Hilbert metrics [2503.01988]. The implementation is described as predominantly in JavaScript, with code made available through GitHub and a web app [2503.01988].

The software addresses an intuition gap in polygonal metric geometry: these metrics are defined using intersections with the polygon boundary, balls are non-Euclidean polygons whose shape depends on the domain, and Hilbert movement requires nontrivial projective or affine transformations to preserve a useful visualization [2503.01988]. PhysLib therefore allows users to choose a convex polygonal domain, place and move points inside it, display metric balls, compare the metrics geometrically, and travel through Hilbert geometry while maintaining visualization stability [2503.01988].

The underlying supported geometries are explicitly defined as follows [2503.01988]:

| Geometry | Definition |
|---|---|
| Funk metric | \(F_\Omega(p,q)=\ln \frac{\|p-q'\|}{\|q-q'\|}\) |
| reverse Funk metric | \(rF_\Omega(p,q)=F_\Omega(q,p)\) |
| Hilbert metric | \(H_\Omega(p,q)=\frac12(F_\Omega(p,q)+rF_\Omega(p,q))\) |
| Thompson metric | \(T_\Omega(p,q)=\max(F_\Omega(p,q),rF_\Omega(p,q))\) |

The paper emphasizes the geometry of balls. The open forward Funk ball is the image of \(\Omega\) under Euclidean homothety about the center with dilation factor \(1-e^{-r}\), and the open reverse Funk ball has dilation factor \(e^r-1\) [2503.01988]. Thompson balls are intersections of the forward and reverse Funk balls; because both are convex polygons, the Thompson ball can be computed by polygon intersection, which the paper states can be done linearly in the complexity of the polygons, and the Thompson ball has at most \(2m\) sides when the domain has \(m\) sides [2503.01988]. The paper also records the inclusion
\[
B_H(p,r/2) \subset B_T(p,r) \subset B_H(p,r)
\]
as a comparison between Thompson and Hilbert geometries [2503.01988].

For Hilbert traversal, the software uses a projective map after centroid normalization:
\[
\phi_v(p)=\frac{p}{1+\langle p,v\rangle},
\]
citing work of Izmestiev [2503.01988]. Because repeated projective updates can make polygons very skinny, PhysLib augments this with a stabilization pipeline based on an approximate John ellipsoid, Mahalanobis distance scaling, and Cholesky decomposition; the paper remarks that the affine maps used in this normalization preserve the Hilbert metric [2503.01988].

This PhysLib is therefore unrelated in implementation and purpose to the Lean library, despite the shared name. One concerns interactive visualization of polygonal metric spaces in \(R^2\); the other concerns formal theorem proving and physics libraries in proof assistants.

## 7. Scope, limitations, and terminological ambiguity

The most important conceptual caution is that “PhysLib” is polysemous in the arXiv record. The Lean-based PhysLib is a community-run formalization library tied to Mathlib, Lean, and physics theorem development [2603.08139; 2510.26094]. The polygonal-geometry PhysLib is JavaScript-based interactive software for convex polygonal metrics [2503.01988]. These systems are independent in subject matter, language, and intended audience.

Within the Lean ecosystem itself, PhysLib is still evolving. Lean4PHYS states that it is a current version rather than a complete physics library, that topic coverage is broad but uneven, and that mechanics is the most developed area [2510.26094]. The same paper emphasizes continued maintenance and community growth [2510.26094]. The 2HDM paper similarly treats PhysLib as reusable infrastructure that can support future extensions such as discrete group actions on the 2HDM potential, added singlet scalars, and broader formalization across particle physics [2603.08139].

The polygonal-geometry PhysLib is explicitly limited to convex polygonal domains in \(R^2\); the paper does not describe support for non-convex domains or higher-dimensional polygonal geometries, and it notes visualization deformation issues under repeated Hilbert movement as the reason for ellipsoid-based stabilization [2503.01988].

Across both contexts, PhysLib denotes software infrastructure rather than a single canonical theory package. In formal physics, it is increasingly associated with reusable Lean libraries that bridge mathematics and physics through units, dimensions, and theorem collections. In computational geometry, it designates an interactive environment for exploring polygonal metric geometries. The common thread is infrastructural: each PhysLib turns a technically intricate domain into a manipulable, sharable, and extensible software substrate for research and education.

Source: https://www.emergentmind.com/topics/physlib