Documentation
Getting Started
A guide for getting started with Physlib, aimed at people with no Lean experience or who are new to the project.
Getting Started
Code Quality
Useful Resources
Installing
Lean Installation
Ready to get started with Lean? Click the button below to see the official installation instructions.
Physlib Installation Steps
- Clone the repository: github.com/leanprover-community/physlib
- Run the following commands in the top-level Physlib directory:
lake update
lake exe cache get
lake buildNote: lake build may take around 20 minutes.
Troubleshooting
Sometimes things go wrong due to no fault of your own — Physlib or one of its dependencies may have been updated to a new version of Lean. In these cases you can try:
rm -rf .lake
lake update
lake exe cache get
lake buildOr as a single command:
rm -rf .lake; lake update; lake exe cache get; lake buildWriting Results
Things to bear in mind:
- —It helps if results sit next to results about the same physics.
- —Informal results and semi-formal results are easier to write if you're new to Lean.
- —If you make substantial changes to a file, feel free to add yourself to the author list, in alphabetic order by last name.
Definitions
Definitions are used to introduce new concepts or objects in a precise and formal way. In Physlib we give all definitions doc-strings.
/-- For a harmonic oscillator, the Schrodinger Operator corresponding to it
is defined as the function from `ℝ → ℂ` to `ℝ → ℂ` taking
`ψ ↦ - ℏ^2 / (2 * m) * ψ'' + 1/2 * m * ω^2 * x^2 * ψ`. -/
noncomputable def schrodingerOperator (ψ : ℝ → ℂ) : ℝ → ℂ :=
fun x => - Q.ℏ ^ 2 / (2 * Q.m) * (deriv (deriv ψ) x) + 1/2 * Q.m * Q.ω^2 * x^2 * ψ xstructure, inductive and abbrev also introduce new concepts in a similar way to def.
Lemmas
In Physlib we use lemmas for every theorem which is not a main one. For every lemma you must provide a proof.
lemma schrodingerOperator_parity (ψ : ℝ → ℂ) :
Q.schrodingerOperator (parity ψ) = parity (Q.schrodingerOperator ψ) := by
funext x
have (ψ : ℝ → ℂ) : (fun x => (deriv fun x => ψ (-x)) x) = fun x => - deriv ψ (-x) := by
funext x
rw [← deriv_comp_neg]
simp [schrodingerOperator, parity, this]Theorems
Theorems are significant results, but are otherwise exactly the same as lemmas.
theorem wicks_theorem_normal_order : (φs : List 𝓕.FieldOp) →
𝓣(𝓝(ofFieldOpList φs)) =
∑ (φsΛ : {φsΛ : WickContraction φs.length // ¬ HaveEqTime φsΛ}), φsΛ.1.wickTerm := by
...Informal Definitions
Informal definitions are definitions written in English rather than in Lean. They are given a tag (you can get a tag using lake exe make_tag), and a list of dependencies. The definition itself is written in the doc-string. They cannot be used in further results.
/-- The hubble constant defined in terms of the scale factor
as `(dₜ a) / a`.
The notation `H` is used for the `hubbleConstant`. -/
informal_definition hubbleConstant where
deps := []
tag := "6Z2NB"Informal Lemmas
Informal lemmas are lemmas written in English rather than in Lean. They are given a tag and a list of dependencies. The lemma and proof itself are written in the doc-string. They cannot be used in further results.
/-- The time evolution of the hubble parameter is equal to `dₜ H = - H^2 (1 + q)`. -/
informal_lemma time_evolution_hubbleConstant where
deps := [hubbleConstant]
tag := "6Z3BS"Semi-Formal Results
Semi-formal results are like informal definitions and lemmas except the type of the definition or statement of the lemma is made formal. They are half-way between informal and formal statements. They cannot be used in further results and are also given a tag.
/-- The force on the classical harmonic oscillator is `- k x`. -/
semiformal_result "6YB2U" force_is_linear (x : ℝ → ℝ) :
force S x = - S.k • xTODO Items
Todo items are used to indicate things which are to be done. They consist of a tag and a string statement of what is to be done.
TODO "6VZHC" "Create a new folder for the damped harmonic oscillator, initially as a place-holder."Making a New File
New files should be made when there is a natural separation of results in an existing file, or when a new result is being added that does not fit in any existing file.
New File Checklist
Create a new file: Place the file in the relevant directory.
File naming convention: Use a descriptive name with only alphabetic characters. Each new word should start with a capital letter, e.g. MyNewFile.lean.
Add a copyright statement: At the very top of the file, include:
/-
Copyright (c) 2025 your-name. All rights reserved.
Released under Apache 2.0 license as described in the file LICENSE.
Authors: your-name
-/Include necessary imports: Add any required imports next, for example:
import Mathlib.Analysis.SpecialFunctions.Integrals
import Mathlib.Analysis.SpecialFunctions.PolarCoord
import PhysLean.Meta.TODO.Basic
import PhysLean.Meta.Informal.SemiFormal
import PhysLean.Meta.Informal.BasicAdd a file description: Provide a brief description of the file's content.
Update the main import file: Add your new file to ./PhysLean.lean (or the main entry file) in alphabetical order as an import.
Linting
Linting is the process of checking your code for potential errors, stylistic issues, and adherence to coding standards. It helps ensure that your code is clean, consistent, and free from common mistakes.
On making a pull-request to Physlib, GitHub workflows will lint your code automatically. You can also check locally:
Linting Locally
lake exe lint_all
./scripts/lint-style.shEnsuring these commands produce no errors helps maintain the quality of Physlib.
Making a Pull Request
Small pull-requests are better than large ones — even if it's just a single result.
Using Forks
- Fork the Physlib repository to your GitHub account.
- Clone your forked repository to your local machine.
- Make your changes on your local version.
- Push your changes to your forked repository.
- Open a pull request from your forked version to the main Physlib repository.
Using Branches
- Ask Joseph Tooby-Smith to add you as an outside collaborator on the project.
- Clone the main GitHub repository.
- Make your own branch (e.g.
feat(your-name):updating spacetime). - Open a pull request from your branch to the main branch.