analyzing the PDG repo using Gemini

This post documents the first time I used an LLM to assess the Physics Derivation Graph

All of the files in the git repo (tl;dr: Gemini crashed)

I uploaded all of the Physics Derivation Graph software and asked Gemini 2.0

The git repo has 96 files; 14 .py and 58 .html

$ find . -type f | wc -l
      96

10503 lines of Python, 4337 lines of HTML, and 968kB

Uploading the files uses 230,346 tokens of an available window size of 1,048,576 tokens on 2025-01-09.

Here's the prompt I provided along with the files:

The following files are from a project that works but is incomplete. 
Review the code and provide suggestions of what the most important 
tasks are to work on next.

Result: Gemini crashed ("An internal error has occurred.") after 40 seconds of processing. Two more tries also didn't work.

Just the .py and .html files

Removed everything except for 13 py and 58 html files, down to 816kB.

Now the token count is 209,717

The following files are from a project that works but is incomplete. 
Review the code and provide suggestions of what the most important 
tasks are to work on next.

That prompt resulted in Gemini making 7 very reasonable suggestions. I opened two new issues on github as a result of Gemini's assessment.

In the same context I asked

Briefly describe the purpose and goals of the software project. 
Highlight its key features and benefits.

The result from Gemini offered relevant text that I have included in the README.md file. The text is literally better than what I could have written!

Next I asked for a visualization,

Create a visual diagram of the program's flow, showing the sequence 
of operations, decision points, and loops. Create a markdown file 
with ASCII art for use in a README.md file.

That produced some almost-correctly-formatted ASCII art. The caveats provided by Gemini were very reasonable

"This is a simplified representation. The actual program flow involves many more specific states and transitions, not shown for simplicity."

Lastly I asked Gemini

Document the public APIs and web interfaces exposed by the software, 
including input/output formats and usage examples. Provide the answer 
as a single HTML file.

Gemini's output was mostly HTML (some Markdown) and very useful.

use of LLMs could make the Physics Derivation Graph more feasible

Previously I've considered the Physics Derivation Graph to be an unlikely dream, in that a complete representation of Physics is infeasible, and even a breadth-first approach is infeasible. My expectation of infeasibility was based on the constraints that data entry would not just require a significant number of person-hours, but the data entry would need to be enacted by highly-qualified people with training tailored to the Physics Derivation Graph.

If the workflow can be segmented into small tasks, LLMs might provide relevant automation of complex tasks that require semantic context.

Overview of workflow

For example,

1. Given a corpus of papers on arxiv,
2. identify whether a paper has a derivation.
3. Given a paper with a derivation, can the steps be identified? (Associate specific inference rule)
4. Can the steps be verified (e.g., SymPy, Lean)?
5. For derivations with steps, what variables and constants are used in the paper?
6. Do these variables and constants appear in other derivations?

That's a combination of text search and semantic awareness of the text content. Not every step has to be "just a human" or "just an LLM" -- an augmented capability is a reasonable workflow.

Another enabling aspect is the Latex representation for arxiv papers. That makes parsing (by regex or LLM) easier.

The above process could also be applied to pages on Wikipedia. See https://github.com/allofphysicsgraph/proofofconcept/wiki/All-Branches-of-Physics

Analysis of a specific paper

I had previously explored extraction of content from a specific paper in https://physicsderivationgraph.blogspot.com/2021/08/steps-to-convert-published-scientific.html. The following is an exploration of how to extract a derivation using Gemini 2.0 LLM on 2025-01-07.

 For "Speed of sound from fundamental physical constants" the .tex files are available from https://arxiv.org/abs/2004.04818

$ tar xzvf arXiv-2004.04818v2.tar.gz 
x elemental.pdf
x fig3.pdf
x sound1.tex
x sound-speeds.pdf

The file sound1.tex is 37110 bytes (36kB), 302 lines, 37108 characters, and 5134 words.

Loading the .tex into Gemini 2.0's prompt uses 10,518 tokens (with the max for Gemini 2.0 being 1,048,574 tokens).

The following is a scientific article. Answer the 
question about the article below.

```latex
\documentclass[aps,prl,groupedaddress,fleqn,twocolumn,10pt]{revtex4}
\pdfoutput=1
\usepackage{graphicx}

...snipped...

may be requested from the authors.
\end{document} 
```

Question: Does this article contain a derivation?

Answer:

Gemini 2.0 (on 2025-01-07) says

Yes, the article contains a derivation. It presents two approaches to derive the speed of sound, starting from system elasticity and vibrational properties, respectively. Both approaches lead to the same result, which is then used to find the upper bound for the speed of sound.

I ask a follow-up question,

What is the latex equation that is the result for the 
derivation for the speed of sound in this paper?

Gemini's response:

The main result of the derivation for the upper 
bound of the speed of sound, as given in the paper, is:

```latex
\frac{v_u}{c}=\alpha\left(\frac{m_e}{2m_p}\right)^{\frac{1}{2}}
```

This is equation (1) in the paper (though it is labeled (v0)).

There is also an intermediate result for the speed 
of sound *v* before it is specialized to the upper bound *vu*:

```latex
v=\alpha\left(\frac{m_e}{2m}\right)^{\frac{1}{2}}c
```

This is equation (6), labeled (v00).

I follow with another prompt,

What latex equation is the start of the derivation in this article?

Provide the latex for the equation and 
the equation label from the article.

Gemini's response:

The starting equation for the first derivation approach, 
based on system elasticity, is:

```latex
v=\left({\frac{M}{\rho}}\right)^{\frac{1}{2}}
```

This equation does not have a label.

The second approach, based on vibrational properties starts with:

```latex
v=\frac{1}{\pi}\omega_{\rm D}a.
```
This is equation (7), labeled (v001).

Let's see if Gemini can extract symbol definitions:

Using only the article and the latex equation
```latex
v=\frac{1}{\pi}\omega_{\rm D}a.
```
what is the name or meaning of each variable used in the equation?

Gemini's response:

Okay, using only the provided equation and the article, here's the breakdown of each variable:

*   **v**: This represents the **longitudinal speed 
of sound**. The article states, "The longitudinal 
speed of sound, $v$, can be evaluated as the phase velocity..."

*   **ωD**: This is the **Debye frequency**. The article 
defines it as "$\omega_{\rm D}$ are Debye frequency..." 
in the context of the Debye approximation.

*   **a**: This is the **interatomic (inter-molecule) 
separation**. The article states, 
"Using $k_{\rm D}=\frac{\pi}{a}$, where $a$ is the 
interatomic (inter-molecule) separation, gives..."

The use of unicode isn't desirable. Let's see if we can force the use of Latex using the prompt

please restate the previous answer and use 
latex to express the symbols and equations.

Gemini's response:

Okay, here's the restatement of the previous answer, 
using LaTeX to express the symbols and equations:

Using only the provided equation and the article, 
here's the breakdown of each variable:

*   $v$: This represents the **longitudinal speed of 
sound**. The article states, "The longitudinal speed 
of sound, $v$, can be evaluated as the phase velocity..."

*   $\omega_{\rm D}$: This is the **Debye frequency**. 
The article defines it as "$\omega_{\rm D}$ are Debye 
frequency..." in the context of the Debye approximation.

*   $a$: This is the **interatomic (inter-molecule) 
separation**. The article states, 
"Using $k_{\rm D}=\frac{\pi}{a}$, where $a$ is the 
interatomic (inter-molecule) separation, gives..."

The equation itself is:

```latex
v=\frac{1}{\pi}\omega_{\rm D}a.
```

Now lets see if Gemini can identify the steps of the derivation.

The starting equation for the first derivation approach, 
based on system elasticity is
```latex
v=\left({\frac{M}{\rho}}\right)^{\frac{1}{2}}
```

The upper bound of the speed of sound, as given in the paper, is:
\frac{v_u}{c}=\alpha\left(\frac{m_e}{2m_p}\right)^{\frac{1}{2}}

What are the steps of the derivation to get from the starting
equation to the final result? 

Use Latex for equations and symbols in your answer. 
Explain how to get from one step to the next in the derivation.

Gemini's response

Okay, let's trace the steps of the derivation from 
the initial equation based on system elasticity to 
the final upper bound for the speed of sound.

**Starting Point:**

The derivation begins with the equation for the 
longitudinal speed of sound based on system elasticity:

```latex
v=\left({\frac{M}{\rho}}\right)^{\frac{1}{2}}
```
where:
*  $v$ is the speed of sound.
*  $M$ is the longitudinal modulus (related to bulk and shear modulus).
*  $\rho$ is the density.

**Step 1: Relating Modulus to Bonding Energy**

The article states that elastic constants are 
related to the density of electromagnetic energy. 
Specifically, the modulus *M* is related to the bonding 
energy *E* and the interatomic separation *a* with a 
proportionality coefficient $f$.
```latex
M = f\frac{E}{a^3}
```
where *f* is a proportionality coefficient in the range of about 1-6

**Step 2: Expressing Density in Terms of Atomic Mass**

The density, $\rho$, can be expressed in terms 
of the mass *m* of the atom or molecule and the 
interatomic separation $a$. Using the relationship 
between mass, density, and volume, we have the volume 
on the order of $a^3$, and hence:
```latex
m = \rho a^3
```
or
```latex
\rho = \frac{m}{a^3}
```

**Step 3: Substituting into the Speed of Sound Equation**

Substituting the expressions for *M* and $\rho$ 
in terms of E, m and a into the original equation for $v$ :

```latex
v=\left({\frac{M}{\rho}}\right)^{\frac{1}{2}}
```

gives

```latex
v = \left( \frac{f\frac{E}{a^3}}{\frac{m}{a^3}}\right)^{\frac{1}{2}} = \left(f \frac{E}{m}\right)^{\frac{1}{2}}
```
Since the factor  $f^{\frac{1}{2}}$ is about 1-2 
and can be dropped in an approximate evaluation of $v$

```latex
v = \left(\frac{E}{m}\right)^{\frac{1}{2}}
```

**Step 4: Introducing the Rydberg Energy**
The bonding energy in condensed phases is approximately 
equal to the Rydberg energy, $E_{\rm R}$
```latex
E_{\rm R}=\frac{m_ee^4}{32\pi^2\epsilon_0^2\hbar^2}
```
Thus we can replace *E* with $E_{\rm R}$ in the equation for *v*.
```latex
v = \left(\frac{E_{\rm R}}{m}\right)^{\frac{1}{2}}
```

**Step 5: Rewriting the Rydberg Energy**

The Rydberg energy can be rewritten in terms of the 
fine-structure constant $\alpha$ and the speed of light *c* as:
```latex
E_{\rm R} = \frac{1}{2}m_e \left(\alpha c\right)^2
```
where $\alpha=\frac{1}{4\pi\epsilon_0}\frac{e^2}{\hbar c}$ 
is the fine structure constant.

**Step 6: Substituting the Rewritten Rydberg Energy**

Substitute the rewritten Rydberg energy into the equation for *v*:
```latex
v = \left(\frac{\frac{1}{2}m_e \left(\alpha c\right)^2}{m}\right)^{\frac{1}{2}}
```
which simplifies to:
```latex
v=\alpha\left(\frac{m_e}{2m}\right)^{\frac{1}{2}}c
```

**Step 7: Defining the Upper Bound**

The upper bound of the speed of sound, $v_u$, is found 
by setting the mass $m$ to be the proton mass $m_p$, 
which is the lightest relevant atomic mass scale. This 
corresponds to the case of atomic hydrogen.
```latex
v_u = \alpha \left(\frac{m_e}{2m_p}\right)^{\frac{1}{2}}c
```
Dividing by c gives the final result:

```latex
\frac{v_u}{c}=\alpha\left(\frac{m_e}{2m_p}\right)^{\frac{1}{2}}
```
Thus, by relating the speed of sound to the density, 
modulus, and then to the bonding energy and finally, 
the Rydberg energy, the derivation arrives at the upper 
bound of the speed of sound expressed in terms of fundamental constants.

Next step: extract the variables used in the above derivation to see if they are present in the Physics Derivation Graph by using the PDG API.

What are all the symbols and their definitions used in
the derivation steps?

Do not include the associated equations -- just provide 
a list of latex symbols and the definitions as a list.

Use Latex for equations and symbols in your answer. 

Gemini's response (2025-01-07):

Okay, here's a list of all the symbols and their 
definitions used in the derivation steps, without 
including the associated equations:

*   $v$: longitudinal speed of sound
*   $M$: longitudinal modulus (related to bulk and shear modulus)
*   $\rho$: density
*   $f$: proportionality coefficient
*   $E$: bonding energy
*   $a$: interatomic separation
*  $m$: mass of an atom or molecule
*  $E_{\rm R}$: Rydberg energy
*   $m_e$: electron mass
*   $e$: electron charge
*   $\epsilon_0$: permittivity of free space
*   $\hbar$: reduced Planck constant
*  $\alpha$: fine-structure constant
*   $c$: speed of light in vacuum
*   $m_p$: proton mass
* $v_u$: upper bound for speed of sound

TODO: the PDG API needs to be able to handle tasks associated with a workflow that uses an LLM.

There are a few additional steps outlined in https://physicsderivationgraph.blogspot.com/2021/08/steps-to-convert-published-scientific.html, like identifying inference rules between equations. I explored that in this post: https://physicsderivationgraph.blogspot.com/2025/01/using-gemini-llm-to-create-derivation.html.

using Gemini LLM to create derivation steps using inference rules

Previous related post: LLM prompts for PDG.

tl;dr: I'm unsuccessful at getting Gemini 2.0 (on 2025-01-07) to relate Brewster's angle to the Law of Refraction. However, Gemini is able to provide the steps for simple (non-trivial) derivations.

Reformatting HTML table

The site https://aistudio.google.com/ provides Gemini 2.0 LLM for free. To experiment with using it I wanted to provide the inference rules. There are 94 inference rules listed on https://allofphysics.com/list_all_inference_rules in an 8 column table. After removing javascript, headers, and footers the HTML file has 3869 lines. That takes 32,164 tokens for the prompt

The following is an HTML table. The table has 8 columns currently. 
Please remove the last 3 columns from the table and provide the HTML 
result. No explanation is necessary -- just show the HTML table with 
the 3 columns ("Used in derivations", "number of uses", "assumptions") 
removed. The new HTML table should have 5 columns.

```html
<!DOCTYPE html>
<HTML lang='en'>
  <body>

<table border="1"  class="sortable" id="infrule_table">
  <tr>
    <th>inf rule name</th>
    <th>inputs</th>
...

Gemini provided the correct 5 column HTML file. Huzzah!

Brewster's angle and Law of Refraction

Next step is to see if Gemini can use the inference rules for a derivation.

Answer the question based on the context below. Keep 
the answer short and concise. Respond "Unsure about 
answer" if not sure about the answer.

Context: Latex is software for document preparation 
to generate PDF files. Mathematical equations can be 
expressed in Latex using markup syntax. 

Brewster's angle is the angle of incidence at which 
light is perfectly transmitted through a transparent 
dielectric surface with no reflection. It's also known 
as the polarizing angle.

Expressed in Latex, Brewster's angle is
```latex
\theta_{\rm Brewster} = \arctan{ \left( \frac{ n_1 }{ n_2 } \right) }
```

The law of refraction, also called Snell's Law, expressed in Latex, is
```latex
n_1 \sin( \theta_1 ) = n_2 \sin( \theta_2 )
```

Context: a derivation in mathematical Physics consists 
of a sequence of steps. Each step relates mathematical 
expressions to an inference rule. An expression is 
comprised of symbols and operators. An inference rule 
typically transforms input expressions into output expressions.

Inference rules:
```html
<!DOCTYPE html>
<HTML lang='en'>
  <body>

<table border="1"  class="sortable" id="infrule_table">
  <tr>
    <th>inf rule name</th>
    <th>inputs</th>
    <th>outputs</th>
    <th>feeds</th>
    <th>Latex</th>
  </tr>

  <tr>
    <td><a name="LHS of expr 1 equals LHS of expr 2">LHS of expr 1 equals LHS of expr 2</a></td>
    <td>2</td>
    <td>1</td>
    <td>0</td>
    <td>LHS of Eq.~ref{eq:#1} is equal to LHS of Eq.~ref{eq:#2}; yields Eq.~ref{eq:#3}.</td>
  </tr>

  <tr>
    <td><a name="RHS of expr 1 equals RHS of expr 2">RHS of expr 1 equals RHS of expr 2</a></td>
    <td>2</td>
    <td>1</td>
    <td>0</td>
    <td>RHS of Eq.~ref{eq:#1} is equal to RHS of Eq.~ref{eq:#2}; yields Eq.~ref{eq:#3}.</td>
  </tr>

...snipped...

  <tr>
    <td><a name="take curl of both sides">take curl of both sides</a></td>
    <td>1</td>
    <td>1</td>
    <td>0</td>
    <td>Apply curl to both sides of Eq.~ref{eq:#1}; yields Eq.~ref{eq:#2}.</td>
  </tr>

  <caption>
    <a name="table of inference rules">
      Physics Derivation Graph: 94 Inference Rules
    </a>
  </caption>
</table>

    </body>
</html>
```

Question: Using the inference rules above, 
what are the derivation steps that relate 
Brewster's angle to the Law of refraction?

Answer:
  

To which Gemini replied (on 2025-01-07),

"Unsure about answer"

That's reasonable, so I removed the inference rules and tried again

Answer the question based on the context below. Keep 
the answer short and concise. Respond "Unsure about 
answer" if not sure about the answer.

Context: Latex is software for document preparation 
to generate PDF files. Mathematical equations can be 
expressed in Latex using markup syntax. 

Brewster's angle is the angle of incidence at which 
light is perfectly transmitted through a transparent 
dielectric surface with no reflection. It's also known 
as the polarizing angle.

Expressed in Latex, Brewster's angle is
```latex
\theta_{\rm Brewster} = \arctan{ \left( \frac{ n_1 }{ n_2 } \right) }
```

The law of refraction, also called Snell's Law, expressed in Latex, is
```latex
n_1 \sin( \theta_1 ) = n_2 \sin( \theta_2 )
```

Context: a derivation in mathematical Physics consists 
of a sequence of steps. Each step relates mathematical 
expressions to an inference rule. An expression is 
comprised of symbols and operators. An inference rule 
typically transforms input expressions into output expressions.

Question: what are the derivation steps that relate 
Brewster's angle to the Law of refraction?

Answer:
  

Again Gemini replied  (on 2025-01-07),

"Unsure about answer"

I then relaxed the constraint about right answers only and encouraged step-by-step reasoning

Answer the question based on the context below. 
Keep the answer short and concise. Step through 
the reasoning step by step, explaining why each 
step is correct before proceeding to the next step 
in the derivation.

Context: Latex is software for document preparation 
to generate PDF files. Mathematical equations can be 
expressed in Latex using markup syntax.

Brewster's angle is the angle of incidence at which 
light is perfectly transmitted through a transparent 
dielectric surface with no reflection. It's also known 
as the polarizing angle.

Expressed in Latex, Brewster's angle is
```latex
\theta_{\rm Brewster} = \arctan{ \left( \frac{ n_1 }{ n_2 } \right) }
```

The law of refraction, also called Snell's Law, expressed in Latex, is
```latex
n_1 \sin( \theta_1 ) = n_2 \sin( \theta_2 )
```

Context: a derivation in mathematical Physics consists 
of a sequence of steps. Each step relates mathematical 
expressions to an inference rule. An expression is 
comprised of symbols and operators. An inference rule 
typically transforms input expressions into output expressions.

Question: What are the derivation steps that relate 
Brewster's angle to the Law of refraction?

Answer:

Gemini's response (on 2025-01-07):

It's not possible to directly derive Brewster's angle from Snell's Law, or vice versa, using standard mathematical manipulations. Brewster's angle is a specific condition related to polarization, while Snell's Law describes refraction in general. Therefore, no sequence of inference rules can relate them directly. They are independent physical principles governing light behavior under different conditions.

Simple derivation

Answer the question based on the context below. 
Keep the answer short and concise. Step through 
the reasoning step by step, explaining why each 
step is correct before proceeding to the next step 
in the derivation.

Context: Latex is software for document preparation 
to generate PDF files. Mathematical equations can be 
expressed in Latex using markup syntax.

Context: a derivation in mathematical Physics consists 
of a sequence of steps. Each step relates mathematical 
expressions to an inference rule. An expression is 
comprised of symbols and operators. An inference rule 
typically transforms input expressions into output expressions.

Here are four inference rules that are used in derivations:
```latex
"declare initial expression"
number of inputs: 0; feeds: 0; outputs: 1
Eq.~\ref{eq:#1} is an initial expression.

"add X to both sides"
number of inputs: 1; feeds: 1; outputs: 1
Add $#1$ to both sides of Eq.~\ref{eq:#2}; yields Eq.~\ref{eq:#3}.

"declare final expression"
number of inputs: 1; feeds: 0; outputs: 0
Eq.~\ref{eq:#1} is one of the final expressions.
```

Question: What are the derivation steps that relate 
```latex
a = b
``` 
to the expression
```latex
a + c = b + c
```

Answer:

Gemini 2.0 on 2025-01-07 responds with

1. **"declare initial expression"**: The initial expression is `a = b`.
2. **"add X to both sides"**: Adding `c` to both sides of `a = b` yields `a + c = b + c`.

That's "good enough" in my view to be useful -- associating the relevant inference rule with specific steps in a multi-step derivation!

Non-trivial derivation

Answer the question based on the context below. 
Keep the answer short and concise. Step through 
the reasoning step by step, explaining why each 
step is correct before proceeding to the next step 
in the derivation.

Context: Latex is software for document preparation 
to generate PDF files. Mathematical equations can be 
expressed in Latex using markup syntax.

Context: a derivation in mathematical Physics consists 
of a sequence of steps. Each step relates mathematical 
expressions to an inference rule. An expression is 
comprised of symbols and operators. An inference rule 
typically transforms input expressions into output expressions.

Here are four inference rules that are used in derivations:
```latex
"declare initial expression"
number of inputs: 0; feeds: 0; outputs: 1
Eq.~\ref{eq:#1} is an initial expression.

"add X to both sides"
number of inputs: 1; feeds: 1; outputs: 1
Add $#1$ to both sides of Eq.~\ref{eq:#2}; yields Eq.~\ref{eq:#3}.

"substitute LHS of expr 1 into expr 2	"
number of inputs: 2; feeds: 0; outputs: 1
Substitute LHS of Eq.~\ref{eq:#1} into Eq.~\ref{eq:#2}; yields Eq.~\ref{eq:#3}.	

"swap LHS with RHS"	
number of inputs: 1; feeds: 0; outputs: 0
Swap LHS of Eq.~\ref{eq:#1} with RHS; yields Eq.~\ref{eq:#2}.	

"subtract X from both sides"
number of inputs: 1; feeds: 1; outputs: 1
Subtract $#1$ from both sides of Eq.~\ref{eq:#2}; yields Eq.~\ref{eq:#3}.	

"declare final expression"
number of inputs: 1; feeds: 0; outputs: 0
Eq.~\ref{eq:#1} is one of the final expressions.
```

Question: Using the inference rules listed above, what are the derivation steps that relate 
```latex
n_1 \sin( \theta_{\rm Brewster} ) = n_2 \sin( \theta_{\rm refracted} )
``` 
and
```latex
\theta_{\rm Brewster} + \theta_{\rm refracted} = 90^{\circ}
```
to the expression
```latex
n_1 \sin( \theta_{\rm Brewster} ) = n_2 \sin( 90^{\circ} - \theta_{\rm Brewster} )
```

Answer:
  

Gemini 2.0 on 2025-01-07 responds with

1. **"declare initial expression"**: The first initial expression is `n_1 \sin( \theta_{\rm Brewster} ) = n_2 \sin( \theta_{\rm refracted} )`.
2. **"declare initial expression"**: The second initial expression is `\theta_{\rm Brewster} + \theta_{\rm refracted} = 90^{\circ}`.
3. **"subtract X from both sides"**: Subtract `\theta_{\rm Brewster}` from both sides of `\theta_{\rm Brewster} + \theta_{\rm refracted} = 90^{\circ}` to get `\theta_{\rm refracted} = 90^{\circ} - \theta_{\rm Brewster}`.
4. **"substitute LHS of expr 1 into expr 2	"**: Substitute `\theta_{\rm refracted}` from `\theta_{\rm refracted} = 90^{\circ} - \theta_{\rm Brewster}` into `n_1 \sin( \theta_{\rm Brewster} ) = n_2 \sin( \theta_{\rm refracted} )` to get `n_1 \sin( \theta_{\rm Brewster} ) = n_2 \sin( 90^{\circ} - \theta_{\rm Brewster} )`.
  

troubleshooting docker and podman on MacAirbook M2

I have an old MacBook Air running 

• macOS Catalina v10.15.7 with a 1.8GHz Intel Core i5 and 4GB of RAM
• `docker compose version` = 2.2.1
• `docker --version` = 20.10.11

I have a new MacBook Air running 

• macOS Sonoma v14.6.1 with an Apple M2 and 8GB of RAM

Podman on the new MacBook M2

Downloaded 

https://github.com/podman-desktop/podman-desktop/releases/download/v1.15.0/podman-desktop-1.15.0-universal.dmg

from https://podman-desktop.io/downloads

Confusingly, 1.15.0 provides Podman 4.9.0 (?)

As per https://stackoverflow.com/a/76488304 I tried

% podman machine stop; podman machine start

Waiting for VM to exit...
Machine "podman-machine-default" stopped successfully
Starting machine "podman-machine-default"
Waiting for VM ...
Mounting volume... /Users:/Users
chattr: Operation not supported while reading flags on /
mkdir: cannot create directory ‘/Users’: Read-only file system
chattr: Operation not supported while reading flags on /
Error: exit status 1

I then tried

% podman machine stop
Waiting for VM to exit...
Machine "podman-machine-default" stopped successfully

% podman machine rm
The following files will be deleted:
...
Are you sure you want to continue? [y/N] y

% podman machine init                                         
Extracting compressed file: podman-machine-default_fedora-coreos-41.20241215.2.0-qemu.aarch64.qcow2: done  
Image resized.
Machine init complete
To start your machine run:
	podman machine start
    
% podman machine start
Starting machine "podman-machine-default"
Waiting for VM ...
Mounting volume... /Users:/Users
chattr: Operation not supported while reading flags on /
mkdir: cannot create directory ‘/Users’: Read-only file system
chattr: Operation not supported while reading flags on /
Error: exit status 1

Running as root doesn't help

% sudo podman machine start
Error: cannot run command "podman machine start" as root

As per https://stackoverflow.com/a/71576242 I tried

% podman machine init --cpus=4 --disk-size=60 --memory=6096 -v $HOME:$HOME
Extracting compressed file: podman-machine-default_fedora-coreos-41.20241215.2.0-qemu.aarch64.qcow2: done  
Image resized.
Machine init complete
To start your machine run:
	podman machine start

% podman machine start
Starting machine "podman-machine-default"
Waiting for VM ...
Mounting volume... /Users/myinitials:/Users/myinitials
chattr: Operation not supported while reading flags on /
mkdir: cannot create directory ‘/Users’: Read-only file system
chattr: Operation not supported while reading flags on /
Error: exit status 1

As a consequence, while I can run the container,

% podman run -it --rm localhost/ui_v8_website_flask_neo4j_webserver /bin/bash 
WARNING: image platform (linux/amd64) does not match the expected platform (linux/arm64)
root@4d006ef73e19:/code# 

I am unable to mount the local directory

% podman run -it --rm -v `pwd`:/scratch localhost/ui_v8_website_flask_neo4j_webserver /bin/bash
WARNING: image platform (linux/amd64) does not match the expected platform (linux/arm64)
Error: statfs /Users/bhp/version_control/allofphysicsgraph/ui_v8_website_flask_neo4j: no such file or directory

Uninstall Podman

podman machine stop podman-machine-default
podman machine rm podman-machine-default
podman machine rm
sudo /opt/podman/bin/podman-mac-helper uninstall
sudo rm /etc/paths.d/podman-pkg
sudo rm -rfv /opt/podman
sudo rm -rf /Applications/Podman\ Desktop.app/
sudo rm /var/run/docker.sock
rm -fr ~/.local/share/containers/

Docker on the new MacBook M2

Downloaded https://desktop.docker.com/mac/main/arm64/Docker.dmg from https://docs.docker.com/desktop/setup/install/mac-install/

roles, use cases, and requirements

Tests are based on validating requirements. Requirements are derived from use cases that address the needs of people in specific roles.

Roles

• Viewer: sees content on web UI, reads PDF versions. Uses either the web UI or the API. 
• Editor: adds equations, inference rules, and derivations. Uses either the web UI or the API
• Developer: uses the API to build an alternative web UI or runs a service that leverages the PDG
• Contributor: edits documentation and source code, fixes bugs. Uses github issue tracker. 

Use cases per role

See also https://derivationmap.net/static/state_diagram_for_web_interface.png

• Viewer
• reads documentation about PDG
• sees the number of derivations
• on the navigation page
• sees the number of symbols
• on the navigation page
• sees the number of inference rules
• on the navigation page
• sees the number of expressions
• on the navigation page
• sees a list of derivations
• accessed from the navigation page
• sees a list of expressions
• accessed from the navigation page
• sees a list of inference rules
• accessed from the navigation page
• sees a list of symbols
• accessed from the navigation page
• see a list of derivations that use a specific symbol
• see a list of derivations that use a specific inference rule
• see a list of derivations that use a specific expression
• see the steps of a specific derivation
• accessed from the list of derivations
• Editor has same as Viewer, plus:
  (the following actions require being logged in)
• adds a new derivation
• accessed from the navigation page
• next page is create new step
• edits an existing derivation
• accessed from the list of derivations
• after edit is submitted, return to viewing that derivation
• deletes an derivation
• accessed from the list of derivations
• after delete is confirmed, return to list of derivations
• adds a new step
• return to derivation
• edits an existing step
• deletes a step
• return to derivation
• adds a new expression
• return to derivation step
• edits an existing expression
• change Latex
• change relation (e.g., = to >)
• change label
• deletes an expression
• adds a new inference rule
• edits an existing inference rule
• change number of arguments
• deletes an inference rule. (What happens to all the instances of use in various derivations?)
• adds a new symbol
• edits an existing symbol
• change the latex
• change the sympy
• deletes a symbol. (What happens to all the instances of use in various expressions?)
• delete all database content
• return to navigation page

For each of the use cases per role,

• test in web UI
• test in API

what should I work on? many options for tasks TODO

• separate the property graph backend from an API and have the web interface call the API
• find a lighter weight alternative to neo4j backend
• get a minimum viable product working using the existing property graph backend
• separate static documentation pages from the dynamic paths
• get docker working on my new Mac

That last one is the blocker for everything else, so get docker working on my new Mac is priority. The good news is that the code does run on my old MacBook Air.

Next I'll work on getting a minimum viable product working using the existing property graph backend

levels of software quality

This post defines discrete levels of software quality. There are many dimensions of what "software quality" means, so the discrete levels described here are an oversimplification. The attribute clusters below are typically observed together.

software quality level 1

"Worked for me at one point."

• Code does not compile
• No documentation
• Required dependencies not included
• Purpose of code is unclear
• Hard coded numerical values
• Code is wrong - severe design and implementation flaws
• No tests

software quality level 2

"Good enough."

• Code compiles successfully, but with warnings
• Has bugs
• Inefficient
• Purpose of code isn't documented
• Documentation limited to inline comments

software quality level 3

Best practices are enacted.

• Code compiles and runs without errors
• Documentation:
• Inline documentation follows a style guide, e.g. https://google.github.io/styleguide/
• README file contains
• purpose of project
• how to install
• requirements
• quick start guide
• description of features
• roadmap
• Additional documentation like Doxygen, Sphinx
• Containerized (e.g., Docker, Podman, Apptainer/Singularity)
• Code is formatted consistently
• 1 or more tests
• Type hints for Python

software quality level 4

Other developers point to this project as an example of what to aspire to.

• code is designed to be intuitive
• no dead code present
• complete test coverage
• documentation is written in an easy-to-read style and has no grammatical errors