Citations

[logan-nc]

This branch adds more specific citations.
I let Claude read the foundational papers and put specific citations where possible.
It didn't find too many, which is good - didn't go crazy making things up.
I also standardized the citation style, which cleans up the various Chance references we already had there.

[jhalpern30]

Looks good. Note I also added full deprecation of is_closed_toroidal since this PR referenced some equations specific to that and it was removed from the WallGeometry struct so I think it only partially implemented anyway

[claude]

Code Review - PR #155: Citations

This PR standardizes citation format and adds specific equation references throughout the codebase. The changes improve traceability between theory and implementation.

Positive Aspects

1. Citation standardization: The new format [Chance Phys. Plasmas 1997 2161] is clear and consistent across all modules.

2. Specific equation references: Adding equation numbers (e.g., eq. 78, eq. A5-A7) will be useful for developers cross-referencing the papers.

3. Expanded physical interpretation: The additions in ResponseMatrices.jl:102-106 and FieldReconstruction.jl:201-210 clarify the physics behind the equations.

4. Code cleanup: Removing the unused is_closed_toroidal branching logic in Kernel2D.jl:209-216 simplifies the code since only the closed toroidal case is currently supported.

Issues Found

1. Type annotation removal in Vacuum.jl:343 (Minor)

-    xzpts = zeros(Float64, inputs.mtheta, 4)
+    xzpts = zeros(inputs.mtheta, 4)

The explicit Float64 type annotation was removed. While Julia's type inference will likely produce the same result, the explicit annotation documents the intended type and could prevent subtle issues if inputs.mtheta changes type in the future. Consider keeping the explicit type.

2. Incomplete citation in VacuumFromEquilibrium.jl:38-41 (Minor documentation)

The reference section was reformatted but the actual content "Matches GPEC's ahg_write..." appears disconnected from the [Chance Phys. Plasmas 1997 2161] citation. The docstring should clarify which aspect relates to Chance 1997.

3. Potential behavior change with is_closed_toroidal removal (Needs verification)

In Vacuum.jl:310, the condition changed from:

(n == 0 && !wall.nowall && wall.is_closed_toroidal)

to:

(n == 0 && !wall.nowall)

This removes the wall.is_closed_toroidal check. While the PR body states that simplification is appropriate, this changes when the n=0 regularization is applied. Verify that:

• The wall.is_closed_toroidal field always equals true in the current codebase
• Or confirm that the regularization should apply regardless of topology

4. Inconsistent citation detail (Minor)

Some citations include specific sections (e.g., Section VI in EulerLagrange.jl:141) while others only include equation numbers. Consider whether section references should be standardized or removed for consistency.

Recommendations

1. Keep the explicit Float64 type annotation in Vacuum.jl:343
2. Clarify the reference in VacuumFromEquilibrium.jl:38-41
3. Document the is_closed_toroidal removal in the commit message or add a comment explaining why the check was removed
4. Consider standardizing whether to include section numbers in citations

Test Coverage

The PR should pass existing tests since it's primarily documentation changes. However, the is_closed_toroidal removal in Kernel2D.jl and Vacuum.jl involves logic changes that should be verified against the vacuum response tests.

---

Overall, this PR improves code documentation and will be useful for developers working with the theoretical foundations. The citation format is clear and the equation references are valuable additions.