Add 3D Ising model with FSS analysis and complete documentation

[hyangminj]

Summary

This PR extends the Ising model simulation suite with a complete 3D implementation, including finite-size scaling (FSS) analysis, visualization tools, comprehensive testing, and full documentation.

New Features

3D Ising Model Simulation

• ising3d.c: Three-dimensional Ising model with N×N×N cubic lattice
• 6-neighbor connectivity (up, down, left, right, front, back)
• Periodic boundary conditions in all three dimensions
• Monte Carlo simulation with Metropolis algorithm

3D Finite-Size Scaling Analysis

• ising3d_fss.c: FSS analysis for critical temperature determination
• System sizes: L = 4, 6, 8, 10, 12, 16
• Temperature range: 5.5 → 3.5 (focused near Tc ≈ 4.51)
• Binder cumulant calculation for precise Tc identification

Visualization and Analysis

• plot_binder_3d.py: Python script for generating 3D FSS plots
• Binder cumulant crossing plot (binder_crossing_3d.png)
• Complete thermodynamic analysis (fss_complete_analysis_3d.png)
• Shows critical exponents: β ≈ 0.326, γ ≈ 1.237, ν ≈ 0.630

Comprehensive Testing

• Extended test_suite.c with 3D physics tests
• High-T and low-T behavior validation
• Near-critical behavior testing
• Binder cumulant calculation accuracy tests
• All test suites pass ✓

Complete Documentation

• Updated CLAUDE.md with 3D implementation details
• Updated README.md with comprehensive 3D documentation
• Added dimensionality comparison table (1D vs 2D vs 3D)
• Physical insights and universality class explanation
• Both English and Korean documentation

Key Physics

Property	1D	2D	3D
Critical Temperature	Tc = 0	Tc ≈ 2.269	Tc ≈ 4.51
Phase Transition	None at T > 0	Second-order	Second-order
Critical Exponents	N/A	β=1/8, γ=7/4, ν=1	β≈0.326, γ≈1.237, ν≈0.630
Neighbors per Spin	2	4	6
Memory Scaling	O(N)	O(N²)	O(N³)
Universality Class	N/A	2D Ising	3D Ising

Usage

# Compile 3D programs
gcc -o ising3d ising3d.c -lm
gcc -o ising3d_fss ising3d_fss.c -lm

# Run basic 3D simulation
./ising3d 20

# Run 3D FSS analysis and generate plots
./ising3d_fss > fss_data_3d.txt
python3 plot_binder_3d.py

# Run comprehensive test suite
gcc -o test_suite test_suite.c -lm
./test_suite

Test Results

All test suites pass successfully:

• ✓ PCG random number generator tests
• ✓ 1D Ising model physics tests
• ✓ 2D Ising model physics tests
• ✓ 3D Ising model physics tests (new)
• ✓ 2D Binder cumulant tests
• ✓ 3D Binder cumulant tests (new)

Files Changed

New Files:

• ising3d.c - 3D Ising model implementation
• ising3d_fss.c - 3D FSS analysis with Binder cumulant
• plot_binder_3d.py - 3D visualization script
• binder_crossing_3d.png - 3D Binder cumulant crossing plot
• fss_complete_analysis_3d.png - 3D complete FSS analysis plot

Modified Files:

• CLAUDE.md - Added 3D documentation and dimensionality comparison
• README.md - Added comprehensive 3D usage and physics documentation
• test_suite.c - Added 3D physics and Binder cumulant tests

Performance Notes

• 3D simulations have O(N³) memory and computation complexity
• Recommended system sizes: N = 10-30 for production runs
• Use N < 20 for testing
• FSS analysis takes several hours for all system sizes

Physical Significance

The 3D Ising model is particularly important because:

• It belongs to the same universality class as real ferromagnetic materials
• It describes liquid-gas phase transitions
• Critical exponents differ from 2D, demonstrating dimensional effects
• FSS analysis precisely determines Tc ≈ 4.51

🤖 Generated with Claude Code

[claude]

Pull Request Review: 3D Ising Model Implementation

I've reviewed PR #5 which adds a complete 3D Ising model implementation with FSS analysis. Overall, this is a solid contribution that extends the codebase consistently. Here's my detailed feedback:

---

✅ Strengths

1. Excellent code consistency - The 3D implementation follows the same patterns as the existing 1D/2D code
2. Comprehensive testing - Added thorough 3D physics tests covering high-T, low-T, and near-critical behavior
3. Great documentation - Both README.md and CLAUDE.md are well-updated with detailed explanations
4. Correct physics implementation - Periodic boundary conditions, 6-neighbor connectivity, and Binder cumulant calculations all look correct
5. Good visualization - The Python plotting script is well-structured and produces informative plots

---

⚠️ Issues Found

Critical Issues:

1. Binary executable committed to repository (ising3d_fss:112)

   • ❌ The file ising3d_fss is a compiled Mach-O ARM64 executable (macOS binary)
   • This should never be committed to version control
   • Action required: Remove this file and add ising3d, ising3d_fss to .gitignore

   git rm ising3d_fss
   echo "ising3d" >> .gitignore
   echo "ising3d_fss" >> .gitignore

2. Memory leak in ising3d.c (ising3d.c:157-165)

   • The program re-initializes and frees the lattice on every temperature iteration
   • This is inefficient and creates unnecessary allocations
   • Recommendation: Initialize once at the start, free once at the end, and just reset spins between temperatures
   • Current approach is similar to ising2d.c, so this is a design choice but worth reconsidering for 3D due to O(N³) overhead

3. Mixed variable declaration style in ising3d.c (ising3d.c:159)

   • Line 159: for (int j = 0; j < N; j++) uses C99-style loop variable declaration
   • Earlier in the file: variables declared at function start (C89 style)
   • Action required: Be consistent - either use C99 style throughout or C89 style throughout
   • Given the Makefile uses -std=c99, C99 style is preferred

Moderate Issues:

4. Makefile not updated

   • The Makefile doesn't include targets for ising3d and ising3d_fss
   • Action required: Add these targets to the Makefile

   PROGRAMS = ising1d ising2d ising3d ising3d_fss ising2d_fss
   
   ising3d: ising3d.c pcg_random.h
       $(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
   
   ising3d_fss: ising3d_fss.c pcg_random.h
       $(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)

5. Potential division by zero protection (ising3d_fss.c:169)

   • Good: Uses m2_sum > 1e-10 check before division
   • Minor: The threshold 1e-10 might be too small for float precision issues
   • Suggestion: Consider 1e-8 or document why 1e-10 was chosen

6. Code duplication in test_suite.c

   • The 2D and 3D Binder cumulant calculation functions share ~90% of their code
   • Suggestion: Consider refactoring to reduce duplication (lower priority, not critical)

---

🔍 Code Quality Observations

Good Practices:

• ✅ Proper error handling (argc check in ising3d.c:117-120)
• ✅ Clear comments explaining physics (e.g., line 103: "Count each pair only once")
• ✅ Consistent naming conventions with existing code
• ✅ Python script includes error handling for missing files (plot_binder_3d.py:23-26)

Minor Style Issues:

• ising3d.c uses pointer-based neighbor structure (like 2D FSS), while ising2d.c uses integer indices
  • This is fine but worth noting the inconsistency
• Variable naming in ising3d.c uses descriptive names, which is good

---

🔬 Physics & Numerical Correctness

✅ All physics looks correct:

• Metropolis algorithm implementation is standard and correct
• Energy calculation counts each pair once (right, up, front) - correct for periodic boundaries
• Magnetization calculation uses absolute value - correct for ferromagnetic systems
• Binder cumulant formula: U = 1 - <M⁴>/(3<M²>²) - correct
• Critical temperature T_c ≈ 4.51 for 3D - matches literature values
• Critical exponents cited in documentation are accurate

---

🔒 Security Considerations

✅ No security issues found:

• No user input vulnerabilities
• Memory allocation/deallocation appears correct (except efficiency concern above)
• No hardcoded credentials or sensitive data
• This is defensive research code - appropriate use case

---

📊 Performance Considerations

1. Memory complexity correctly documented - O(N³) is clearly stated
2. Computational cost - 200k thermalization + 200k measurement steps is reasonable
3. Recommendation: For very large systems, consider:
   • Adding progress indicators for long runs
   • Checkpointing capability for multi-hour runs
   • Parallelization (OpenMP) for production use

---

✅ Test Coverage

Excellent test coverage added:

• ✅ 3D physics tests (high-T, low-T, critical-T)
• ✅ 3D Binder cumulant tests
• ✅ Tests use reasonable tolerances for Monte Carlo statistical fluctuations

One suggestion:

• Consider adding a test that verifies the 3D periodic boundary conditions explicitly

---

📝 Documentation Quality

Outstanding documentation:

• ✅ README.md comprehensively updated with 3D usage, physics, and interpretation
• ✅ Both English and Korean documentation maintained
• ✅ Dimensionality comparison table is very helpful
• ✅ CLAUDE.md properly updated with implementation details

Minor suggestion:

• Add a note about typical runtime expectations for different system sizes

---

🎯 Recommendations Summary

Must fix before merge:

1. ❌ Remove compiled binary ising3d_fss from repository
2. ❌ Update .gitignore to exclude binaries
3. ❌ Update Makefile to include 3D targets
4. ❌ Fix mixed variable declaration style in ising3d.c:159

Should fix:
5. Consider the memory allocation strategy (initialize once vs. per-temperature)

Nice to have:
6. Add progress indicators for long-running simulations
7. Refactor test suite to reduce code duplication

---

✨ Conclusion

This is a high-quality contribution that meaningfully extends the project. The physics is correct, the code is well-tested, and the documentation is excellent. The main issues are repository hygiene (compiled binary) and build system (Makefile) which are easy to fix.

Recommendation: Approve with requested changes - fix the critical issues above, then merge.

Great work! The 3D implementation significantly enhances the educational and research value of this codebase. The Binder cumulant crossing analysis is particularly well-implemented.

---

Reviewed with: Code inspection, physics verification, compilation check, and comparison with existing 1D/2D implementations.

[claude]

Code Review: 3D Ising Model Implementation

Thank you for this comprehensive PR adding 3D Ising model support! This is a well-structured extension that follows the existing patterns. Below is my detailed review.

Strengths

1. Excellent Code Consistency: The 3D implementation follows the same architectural patterns as 1D and 2D versions, making the codebase cohesive and maintainable.

2. Comprehensive Documentation: Both README.md and CLAUDE.md are thoroughly updated with clear usage instructions, physics background, and dimensionality comparisons.

3. Good Test Coverage: Extended test suite includes 3D physics validation and Binder cumulant tests.

4. Performance Optimization in ising3d.c: Smart refactoring to allocate lattice once and reuse across temperatures - this is much more efficient than the FSS version.

5. Well-Designed Visualization: The Python plotting script provides comprehensive analysis with professional-quality figures.

Issues Found

Critical: Memory Allocation Error Check Missing

Location: ising3d.c:18-24, ising3d_fss.c:18-24

Both files allocate memory without checking for allocation failures. This could cause segmentation faults on systems with limited memory, especially problematic for 3D lattices which use O(N³) memory. Add NULL checks after each malloc with proper error messages.

Bug: Mixed Loop Variable Declaration Style

Location: ising3d_fss.c:134

Uses C99-style loop variable declaration while other loops use pre-declared variables. This is inconsistent with the rest of the codebase. Declare s at the top with other variables for consistency.

Performance: Unnecessary Lattice Reallocation in FSS

Location: ising3d_fss.c:139-174

The FSS version calls initialize() and cleanup() for every temperature point, causing repeated allocation/deallocation. For 101 temperature points × 6 system sizes = 606 allocate/free cycles. With N=16, that's approximately 16³ × 606 = 2.5M allocation operations.

Follow the pattern in ising3d.c: Rename initialize() to allocate_lattice() and create separate reset_spins(). Allocate once per system size, reset spins per temperature.

Test Suite Concerns

Location: test_suite.c:407-424

The 3D tests have weaker assertions compared to 1D/2D. Line 417 only checks M_low > M_high, not absolute value. A broken implementation could pass if both values are near zero. Add a minimum threshold: assert(mag_low_T > 0.5 && mag_low_T > mag_high_T).

Tests use only 10,000-30,000 steps for 3D, which may not be enough for proper equilibration.

Minor: Binder Cumulant Test Too Permissive

Location: test_suite.c:540-542

This test only validates the range [0, 1] but doesn't test if it's actually near the universal value. Tighten to assert(U_crit >= 0.3 && U_crit <= 0.9) to catch obvious bugs.

Best Practices & Style

Good Practices Observed:

• Consistent naming conventions
• Clear function separation of concerns
• Proper periodic boundary conditions implementation
• Good use of comments explaining physics
• Professional visualization code

Suggestions:

• Consider defining constants for simulation parameters (THERMALIZATION_STEPS, MEASUREMENT_STEPS)
• Add error handling for empty data files in plot_binder_3d.py
• Validate command-line argument N > 0 in ising3d.c to prevent undefined behavior

Summary

This is a high-quality implementation that extends the codebase appropriately. The physics is correct, the code follows established patterns, and the documentation is excellent.

Priority Fixes:

1. HIGH: Add memory allocation error checking
2. MEDIUM: Fix inconsistent loop variable declaration style
3. MEDIUM: Optimize FSS memory allocation (follow ising3d.c pattern)
4. LOW: Strengthen test assertions with minimum thresholds

Recommendation: Approve with minor changes. The issues found are relatively minor and don't affect correctness for normal usage, but should be addressed for robustness.

---

Generated by Claude Code analysis of ising3d.c, ising3d_fss.c, test_suite.c, plot_binder_3d.py, Makefile, README.md