PhysLib: Formal Physics & Geometric Software

• PhysLib is a collection of research software artifacts providing formal physics libraries in Lean and interactive tools for polygonal metric geometry.
• In the Lean ecosystem, PhysLib offers a layered architecture with unit systems and topic-specific theorems that support mechanized physics reasoning and error detection in research.
• In computational geometry, PhysLib enables real-time visualization of Funk, reverse Funk, Thompson, and Hilbert metrics on convex polygons, aiding both pedagogy and research.

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 (Tooby-Smith, 9 Mar 2026), while another presents it as a foundational Lean4 repository containing unit systems and topic-specific theorems for college-level formal physics reasoning (Li et al., 30 Oct 2025). 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 (Banerjee et al., 3 Mar 2025). 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 (Tooby-Smith, 9 Mar 2026). 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 (Tooby-Smith, 9 Mar 2026).

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 (Li et al., 30 Oct 2025). 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 (Li et al., 30 Oct 2025).

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 (Li et al., 30 Oct 2025). This stratification is intended to preserve a stable base while allowing topic-level growth and regular extension of theorem collections (Li et al., 30 Oct 2025).

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 (Li et al., 30 Oct 2025). 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 (Li et al., 30 Oct 2025).

At the topic level, PhysLib organizes content into six major areas: mechanics, waves and acoustics, thermodynamics, electromagnetism, optics, and modern physics (Li et al., 30 Oct 2025). 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 (Li et al., 30 Oct 2025). The paper notes that the mechanics section is currently the most developed and serves as the example foundation for the rest of the library (Li et al., 30 Oct 2025).

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 (Li et al., 30 Oct 2025). 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 (Li et al., 30 Oct 2025).

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 (Li et al., 30 Oct 2025). 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 (Li et al., 30 Oct 2025). The same pattern appears in more advanced statements involving force balance, friction, calculus, and logarithms (Li et al., 30 Oct 2025).

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 (Tooby-Smith, 9 Mar 2026).

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 (Tooby-Smith, 9 Mar 2026). 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)$$

(Tooby-Smith, 9 Mar 2026).

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

$K_\mu$0

satisfies Condition C, yet is not stable (Tooby-Smith, 9 Mar 2026).

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 (Tooby-Smith, 9 Mar 2026).

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 (Li et al., 30 Oct 2025). The benchmark contains 104 college-level statements and 96 competition-level statements, the latter divided into 62 easy and 34 hard problems (Li et al., 30 Oct 2025).

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 (Li et al., 30 Oct 2025). 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 (Li et al., 30 Oct 2025).

The paper reports baseline theorem-proving performance for several models and states that PhysLib yields an average improvement of 11.75% in model performance (Li et al., 30 Oct 2025). It further reports that DeepSeek-Prover-V2-7B achieves 16% and Claude-Sonnet-4 achieves 35% on the benchmark (Li et al., 30 Oct 2025). 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 (Li et al., 30 Oct 2025).

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 (Banerjee et al., 3 Mar 2025). The implementation is described as predominantly in JavaScript, with code made available through GitHub and a web app (Banerjee et al., 3 Mar 2025).

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 (Banerjee et al., 3 Mar 2025). 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 (Banerjee et al., 3 Mar 2025).

The underlying supported geometries are explicitly defined as follows (Banerjee et al., 3 Mar 2025):

Geometry	Definition
Funk metric	$K_\mu$1
reverse Funk metric	$K_\mu$2
Hilbert metric	$K_\mu$3
Thompson metric	$K_\mu$4

The paper emphasizes the geometry of balls. The open forward Funk ball is the image of $K_\mu$5 under Euclidean homothety about the center with dilation factor $K_\mu$6, and the open reverse Funk ball has dilation factor $K_\mu$7 (Banerjee et al., 3 Mar 2025). 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 $K_\mu$8 sides when the domain has $K_\mu$9 sides (Banerjee et al., 3 Mar 2025). The paper also records the inclusion

$$V = \sum_{\mu=0}^3 \xi_\mu K_\mu + \sum_{\mu,\nu=0}^3 \eta_{\mu\nu} K_\mu K_\nu$$0

as a comparison between Thompson and Hilbert geometries (Banerjee et al., 3 Mar 2025).

For Hilbert traversal, the software uses a projective map after centroid normalization: $$V = \sum_{\mu=0}^3 \xi_\mu K_\mu + \sum_{\mu,\nu=0}^3 \eta_{\mu\nu} K_\mu K_\nu$$1 citing work of Izmestiev (Banerjee et al., 3 Mar 2025). 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 (Banerjee et al., 3 Mar 2025).

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 $$V = \sum_{\mu=0}^3 \xi_\mu K_\mu + \sum_{\mu,\nu=0}^3 \eta_{\mu\nu} K_\mu K_\nu$$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 (Tooby-Smith, 9 Mar 2026, Li et al., 30 Oct 2025). The polygonal-geometry PhysLib is JavaScript-based interactive software for convex polygonal metrics (Banerjee et al., 3 Mar 2025). 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 (Li et al., 30 Oct 2025). The same paper emphasizes continued maintenance and community growth (Li et al., 30 Oct 2025). 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 (Tooby-Smith, 9 Mar 2026).

The polygonal-geometry PhysLib is explicitly limited to convex polygonal domains in $$V = \sum_{\mu=0}^3 \xi_\mu K_\mu + \sum_{\mu,\nu=0}^3 \eta_{\mu\nu} K_\mu K_\nu$$3; 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 (Banerjee et al., 3 Mar 2025).

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.