Skip to content

feat(PhyslibAlpha): rational values of the 3j symbols of a Regge square - #2100

Open
dl-eigenart wants to merge 1 commit into
leanprover-community:masterfrom
dl-eigenart:rational-3j-a
Open

dl-eigenart wants to merge 1 commit into
leanprover-community:masterfrom
dl-eigenart:rational-3j-a

Conversation

@dl-eigenart

Copy link
Copy Markdown
Contributor

This PR adds PhyslibAlpha/QuantumMechanics/AngularMomentum/Wigner3jRational.lean. The file provides rational computational aids for the existing real definitions from Wigner3j.lean and links them to those definitions via cast lemmas.

This allows specific values of the square and the signed square of a Wigner-3j symbol to be checked using decide +kernel, without native_decide and without additional axioms.

The file contains rational versions of the existing building blocks:
invFactQ
negOnePowQ
sixTermQ
sixSumQ

For a Regge square R, four additional definitions are added:

threeJRRadQ: the rational quantity under the root

threeJRSumQ: the rational sum

threeJRSqQ: the square of the 3j symbol

threeJRSgnSqQ: the product of the 3j symbol and its magnitude

For each definition, there is a cast_… lemma that demonstrates, after casting to ℝ, that it matches the corresponding real expression. The lemma threeJR_eq_rat also represents the real 3j symbol as a sign × root of a rational number × rational number.

Why use rational computational aids?

The existing definition of threeJR contains a real root and a finsum. It is therefore not immediately suitable for the intended evaluation of specific table values in the kernel.

The 3j symbol itself is generally irrational. Its square, however, is rational. The product of the symbol and its absolute value is also rational and, in addition, preserves the sign: For a real number x, the number x·|x| determines both |x| and the sign of x.

The rational sum is restricted to the domain in which all factorials have nonnegative arguments. This allows it to be evaluated as a finite, computable sum. The Cast lemmas ensure that this calculation continues to correspond to the existing real definitions.

Examples:
Two examples use decide +kernel to check the following rational product values:

3j symbol checked value of threeJRSgnSqQ
$\begin{pmatrix} \tfrac12 & \tfrac12 & 0 \ \tfrac12 & -\tfrac12 & 0 \end{pmatrix}$ $1/2$
$\begin{pmatrix} 2 & 2 & 2 \ 0 & 0 & 0 \end{pmatrix}$ $-2/35$

These examples serve as proof that the kernel check works. A more comprehensive collection of tabulated values is not part of this PR.

Relationship to Existing Definitions:
The real-number definitions in Wigner3j.lean remain authoritative. The new ℚ versions are computational aids; the corresponding proofs relate their results to the real-number formulation.
There are no corresponding rational versions yet on the underlying master branch. This PR therefore supplements the computational framework without replacing the existing definitions.
The formulation uses the existing Regge square: a 3×3 array of combinations of the angular momentum and magnetic quantum numbers, whose row and column sums each yield J = j_1 + j_2 + j_3.

Deliberately not included in this PR:
• No rational representation of the 3j symbol itself, since it is generally irrational.
• No 6j symbols. These will follow in a separate PR on the rational-6j branch, which builds on this PR.
• No complete verification of a value table. The two examples initially test the calculation process.

Verification:
Built on master at commit be0a9ee; The following tests were successful:

Build of the new module
lint-style.sh
alphaPythonLinters.sh
module_doc_lint
alphaFileImports and
Batteries-#lint for PhyslibAlpha.
lint_all and auxillary_script_test were not run.

References in the File:
The file refers to the following sources;
• Varshalovich, Moskalev, Khersonskii, Quantum Theory of Angular Momentum (1988):
◦ Section 8.1.3, p. 237, Eq. 8.1(14)– (18)
◦ Section 8.2, p. 237, Eq. 8.2(1)
◦ Section 8.2.1, p. 238, Eq. 8.2(3)
• DLMF, Section 34.2, Eqs. 34.2.4–34.2.5

The order of the rows here differs from that in Varshalovich 8.1(15): There, the second row is (j+m) ((R_{21}=a+\alpha)) and the third is (j-m) ((R_{31}=a-\alpha)). In physlib, it is the other way around: the second line is (j-m), and the third line is (j+m). This is documented both in the module documentation for Wigner3j.lean and in reggeJ within SixJSymmetry.lean.

This convention already originates from the merged Wigner3j.lean; so the PR does not introduce it anew but rather adopts it. Both examples follow this physlib convention.

To perform the conversion, swap the last two rows. This corresponds to (m \mapsto -m) and yields the factor ((-1)^J). The corresponding lemma in physlib is called threeJR_swap_rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added medium PhyslibAlpha Pull requests which are for modifications to PhyslibAlpha. labels Nov 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Thank you for this pull-request (PR). If this is your first PR, welcome to the community!

While you wait for a review, note that you can review PRs too; reviewing is not restricted to maintainers. Our review guidelines explain what to look for.

Over time, contributions such as reviews, maintenance and documentation are recorded on contributions.physlib.io.

Three main points:

  • Comment -awaiting-author on its own line to remove that label from your PR.
  • Comment blocked-by-PR or -blocked-by-PR on its own line to add or remove that label, respectively.
  • The first review might take several days to arrive. If in doubt message on the Zulip.

For the author: Please read

Below is what will happen next. Please read carefully if you are not familiar with the process. You may open other PRs while this one is being reviewed, and can stack PRs on top of each other, so don't let these steps slow you down.

  1. Some automated checks will be run on your PR. You can see the results of these checks at the buttom of your PR page. If any of these checks fail, you will need to fix the issues before your PR can be merged. You can learn more about these here, including how to run them locally, which is sometimes quicker than relying on the GitHub Actions. If you have never had a PR merged before, you may have to wait for a reviewer to manually start these checks (this is for security).

  2. A reviewer will look at your PR and may ask you to make changes. This may happen a couple of days after you submit your PR, so you may need to be patient. But it should not be longer than that - if it is please bring it to the attention of the community on the Zulip. The level of review will depend on where your PR is submitted. If it is submitted to ./Physlib or ./QuantumInfo, the review will be more thorough than if it is submitted to ./PhyslibAlpha. You can find out more about what the review process is looking for in our review guidelines. If a reviewer adds an awaiting-author label to your PR, address the review comments, then please remove that label by adding a comment with -awaiting-author. This helps us keep track of reviews.

  3. The reviewer will either approve your PR, or request more changes (in which case we return to step 2). Once your PR is approved, it will be merged by a maintainer, this should happen shortly after approval, though you may get more comments at this stage.

Tip: The easiest way to get a fast review is to submit a PR that is small and self-contained, and has clear documentation explaining why things are the way they are in your changes.

If you have any problems or questions, please reach out to the community on the Zulip.

For reviewers: Summary of your PR

Found differences:
@@ PhyslibAlpha.QuantumMechanics.AngularMomentum.Wigner3jRational @@
+ module added PhyslibAlpha.QuantumMechanics.AngularMomentum.Wigner3jRational (+183 -0)
  namespaces PhyslibAlpha.Sl2
+ added def invFactQ
+ added def negOnePowQ
+ added def sixSumQ
+ added def sixTermQ
+ added def threeJRRadQ
+ added def threeJRSgnSqQ
+ added def threeJRSqQ
+ added def threeJRSumQ
+ added lemma cast_invFactQ
+ added lemma cast_negOnePowQ
+ added lemma cast_sixSumQ
+ added lemma cast_sixTermQ
+ added lemma cast_threeJRRadQ
+ added lemma cast_threeJRSgnSqQ
+ added lemma cast_threeJRSqQ
+ added lemma cast_threeJRSumQ
+ added lemma threeJRRadQ_nonneg
+ added lemma threeJR_eq_rat
@@ PhyslibAlpha @@
! module modified PhyslibAlpha (+1 -0)
20 differences

The declarations are found by reading the diff as text, without regard for namespaces, so a declaration whose keyword and name are on different lines is missed, and two declarations of the same name in different namespaces are listed as one. A change to a proof, or to the body of a definition, does not appear. See scripts/alpha/github/pr_summary.lean.

Summary of commit a94d9ba, remade whenever a commit is pushed.

@jstoobysmith

Copy link
Copy Markdown
Member

Just to let you know that we have changed the policy regarding PR descriptions. The new policy is that they should be human written and concise. The reason for this is that we found that the AI written doc-strings were essentially been read by no-one, and were not particularly useful. It is good to think as PR descriptions as forming part of the code, and as much care and attention should be given to them as to the Lean code itself.

Would you mind changing your future PR descriptions accordingly?

@dl-eigenart

Copy link
Copy Markdown
Contributor Author

@jstoobysmith okay, I´ll keep it in mind.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

medium PhyslibAlpha Pull requests which are for modifications to PhyslibAlpha.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants