navigation / documentation overview / design documentation
Recommendation: Read the user documentation and FAQ first. This page assumes familiarity with the jargon used in the Physics Derivation Graph.
This page provides background context for design decisions and implementation choices associated with the Physics Derivation Graph (PDG). Contributions to the project are welcome; see CONTRIBUTING.md on how to get started. The Physics Derivation Graph is covered by the Creative Commons Attribution 4.0 International License, so if you don't like a choice that was made you are welcome to fork the Physics Derivation Graph project.
This page enumerates design principles and goals for the Physics Derivation Graph (PDG).
The list is unordered.
Therefore
Contents
Restating the goal from the front page of https://allofphysics.com/,
"Write down all known mathematical physics in a way that can be both read by humans and checked by a computer algebra system."
This page describes the current status and historical evolution of design decisions critical to the Physics Derivation Graph.
Decisions are not made independently; one choice informs others. Below is a visual overview of the relations among various decisions.
legend for shapes:
colors:
rule of connectivity for this graph:
Dirac notation, calculus, differential equations, algebra, trigonometry.
Geometry is but the developer hasn't figure out how to incorporate geometry.
See also Supported mathematical features and not in scope.
Reasonable for a human to understand without use of specialized knowledge.
\int_0^{\infty} is not understandable to everyone, and neither is contentML.
The mathematical steps, identity, or solution can be verified as correct using symbolic mathematical software. (See for examples.)
Just writing down symbols and expressions is not meaningful. Why this matters: Reliability of machine-verified logic, Reproducibility, and Accessibility (no leaps of logic).
A CAS is not sufficient as it may report \( 1 = x/x \) as true, even though \( x = 0 \) is false. That is why a proof assistant is necessary. (See which proof assistant?.)
Currently using SymPy.
https://github.com/allofphysicsgraph/task-tracker/issues/117 See comparison of CAS like Mathematica, MathCad, Sage, Maple, SymPy. Currently using Lean 4.
https://github.com/allofphysicsgraph/task-tracker/issues/106 See comparison of Rocq, Isabelle, Lean Currently using Latex.
See comparison of Latex, Content MathML, Presentation ML Currently using d3js and graphviz.
https://github.com/allofphysicsgraph/task-tracker/issues/97 d3js, graphviz, networkx Currently using Neo4j.
See comparison of txt, XML, CSV, SQL, property graph Currently using Neo4j.
https://github.com/allofphysicsgraph/task-tracker/issues/43 I had ui_v7 for JSON/SQL and ui_v8 for Neo4j. The ui_v7 had a working implementation of Google authentication. I had trouble getting Google authentication working in ui_v8, and I didn't want to have to refactor all the static content from ui_v7, so I decided to create a new repo, "allofphysics.com". Although getting Neo4j into ui_v7 was do-able, the "mash together to repos" ended up being a bad decision from a troubleshooting and cleanliness-of-design experience. I decided to name the repo "allofphysics.com" to make it clear which repo hosted the website on the Internet. Also, the alternative repo name "a mashup of v7 and v8" wasn't a good name, though it would have been more descriptive.
In retrospect, that was a bad naming convention because I later reverted to using ui_v7 for the website. Currently using page-per-decision.
Rendered HTML pages should have a single scope. (As opposed to a single-page website.) Currently using MathJax.
Currently using Hetzner.
DigitalOcean, AWS, Oracle, Azure https://github.com/allofphysicsgraph/task-tracker/issues/56 https://physicsderivationgraph.blogspot.com/2026/01/vps-price-comparison-september-2024.html Currently using single file (pdg_app.py).
Having all the routes in a single file (e.g., pdg_app.py) results in a huge file with thousands of lines. Happily, Flask provides a way to separate routes into separate files (e.g., pdg_other_routes.py) using blueprints. The file pdg_app.py contains
and then pdg_other_routes.py contains
So far, so good. The cost of this separation is that Flask namespaces the endpoints to ensure there are no name collisions between different files. The That would require figuring out which Therefore, having all routes in pdg_app.py is easiest. Currently using Python, HTML, Latex.
Languages I'm comfortable with and are widely used - Python; HTML; Docker Currently using web UI.
Why web ui? Why not a GUI? Or command line?
Accessibility Decision: a CAS is not sufficient verification
Decision: Which Computer Algebra System(s) to use?
Decision: Which proof assistant(s) to use?
Decision: How to represent expressions?
Decision: How to render graphs visually?
Decision: Which data structure?
Decision: Which Property Graph database?
Decision: Upgrade path from JSON/SQL to Neo4j
Decision: Naming of repo
Decision: Page scope
Decision: How to display Latex on webpages?
Decision: Which VPS provider service company to use?
https://physicsderivationgraph.blogspot.com/2026/01/vps-price-comparison-january-2026.html
Decision: Separate non-interactive workflow pages (e.g., user_documentation) into a separate Python file?
from pdg_other_routes import other_routes_bp
web_app.register_blueprint(other_routes_bp)
other_routes_bp = Blueprint("other_routes", __name__)
@other_routes_bp.route("/api_via_js")
def to_api_via_js() -> str:
return render_template("js_with_api/api_js.html")
url_for function in Jinja2 templates (and in the Python code) now expects the format:
other_routes.function_name
url_for functions point to routes in pdg_other_routes.py and which routes are in pdg_app.py
Decision: Which languages to use?
Decision: Interface
Decision: Data structure used in the Physics Derivation Graph
The Physics Derivation Graph is stored in a Neo4j Property Graph database.
The many alternatives data storage options (e.g., SQLite, Redis, Python Pickle, CSV, GraphML) offer trade-offs, a few of which have been explored.
There are multiple choices of how to represent a mathematical expression. The choices feature trade-offs between conciseness, ability to express the range of notations necessary for Physics, symantic meaning, and ability to use the expression in a computer algebra system (CAS). See the comparison of syntax. \(\rm\LaTeX\) was selected primarily because of the common use in Physics, display of complex math, conciseness, and expressiveness. The use of \(\rm\LaTeX\) means other tasks like parsing symbols and resolving ambiguity are harder.
(e.g., inference rules and expressions and symbols)
Many but not all symbols are supported. Here are some categories of supported symbols. (Symbols exist on the left side or right side of an expression and can also appear in a feed.)
Operators. These act on symbols (listed above) and are part of either the left side or right side of an expression. Operators can also appear in feeds.
Relations. These evaluate to True for an expression. Relations do not appear in a feed.
To check the above documentation against the code, see https://github.com/allofphysicsgraph/ui_v8_website_flask_neo4j/blob/gh-pages/webserver_for_pdg/library/list_of_valid.py
Although the Physics Derivation Graph is intended to be comprehensive across domains, there are aspect of Physics not within the current scope of the project:
These aspects could be included if the data structure and workflow were adapted to an expanded scope.