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/,
Goal: 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.
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.
Reasonable for a human to understand without use of specialized knowledge.
\int_0^{\infty} is not understandable to everyone, and neither is contentML
Just writing down symbols and expressions is not meaningful.
https://github.com/allofphysicsgraph/task-tracker/issues/117
Mathematica, MathCad, Sage
https://github.com/allofphysicsgraph/task-tracker/issues/106
COQ, Isabelle, Lean
Latex, Content MathML, Presentation ML, Mathematica,
https://github.com/allofphysicsgraph/task-tracker/issues/97
d3js, graphviz, networkx
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.
Rendered HTML pages should have a single scope. (As opposed to a single-page website.)
DigitalOcean, AWS, Oracle, Azure
https://github.com/allofphysicsgraph/task-tracker/issues/56
https://physicsderivationgraph.blogspot.com/2026/01/vps-price-comparison-september-2024.html
https://physicsderivationgraph.blogspot.com/2026/01/vps-price-comparison-january-2026.html
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
from pdg_other_routes import other_routes_bp web_app.register_blueprint(other_routes_bp)
and then pdg_other_routes.py contains
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")
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 url_for function in Jinja2 templates (and in the Python code) now expects the format:
other_routes.function_name
That would require figuring out which url_for functions point to routes in pdg_other_routes.py and which routes are in pdg_app.py
Therefore, having all routes in pdg_app.py is easiest.
Languages I'm comfortable with and are widely used - Python; HTML; Docker
Why web ui? Why not a GUI? Or command line?
Accessibility
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.