radia 1.3.9__tar.gz → 1.3.10__tar.gz

{radia-1.3.9/src/radia.egg-info → radia-1.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: radia
-Version: 1.3.9
+Version: 1.3.10
 Summary: Radia 3D Magnetostatics with NGSolve Integration and OpenMP Parallelization
 Home-page: https://github.com/ksugahar/Radia_NGSolve
 Author: Pascal Elleaume
@@ -96,7 +96,7 @@ pip install radia-ngsolve
 # - build/Release/radia_ngsolve.pyd
 ```
 
-See [README_BUILD.md](README_BUILD.md) for detailed build instructions.
+See [BUILD.md](BUILD.md) for detailed build instructions.
 
 ### Basic Usage
 
@@ -119,6 +119,21 @@ print(f"Field: {field} T")
 
 The `radia_ngsolve` module provides a C++ CoefficientFunction interface for using Radia magnetic fields in NGSolve FEM analysis.
 
+**Requirements:**
+- NGSolve must be installed separately: `pip install ngsolve`
+- **IMPORTANT**: NGSolve must be imported **before** `radia_ngsolve`
+- Current build is linked against **NGSolve 6.2.2406** (Windows Python 3.12)
+
+**Installation:**
+
+```bash
+# 1. Install NGSolve first
+pip install ngsolve
+
+# 2. Install Radia (includes radia_ngsolve.pyd)
+pip install radia
+```
+
 **Function Specification:**
 
 ```python
@@ -144,12 +159,12 @@ radia_ngsolve.RadiaField(radia_obj, field_type='b')
 **Example:**
 
 ```python
-# IMPORTANT: Import ngsolve first
+# IMPORTANT: Import ngsolve FIRST (required to load NGSolve DLLs)
 import ngsolve
-from ngsolve import Mesh, H1, GridFunction
+from ngsolve import Mesh, H1, GridFunction, HDiv
 
 import radia as rad
-import radia_ngsolve
+from radia import radia_ngsolve  # or: import radia_ngsolve
 
 # Create Radia magnet
 magnet = rad.ObjRecMag([0,0,0], [20,20,20], [0,0,1.2])  # mm units
@@ -167,24 +182,27 @@ gf = GridFunction(fes)
 gf.Set(B_field)  # Automatically converts mesh coordinates m → mm
 ```
 
-See [examples/Radia_to_NGSolve_CoefficientFunction/](examples/Radia_to_NGSolve_CoefficientFunction/) for complete examples.
+See [examples/ngsolve_integration/](examples/ngsolve_integration/) for complete examples.
 
 ## Documentation
 
-### Core
-- [README_BUILD.md](README_BUILD.md) - Build instructions
-- [docs/OPENMP_PERFORMANCE_REPORT.md](docs/OPENMP_PERFORMANCE_REPORT.md) - OpenMP benchmarks
-- [docs/DIRECTORY_STRUCTURE.md](docs/DIRECTORY_STRUCTURE.md) - Project structure
+### Build & Setup
+- [BUILD.md](BUILD.md) - Build instructions (Windows, macOS, Linux)
+
+### User Guides
+- [docs/API_REFERENCE.md](docs/API_REFERENCE.md) - Complete Python API reference
+- [docs/SOLVER_METHODS.md](docs/SOLVER_METHODS.md) - Solver methods (LU, BiCGSTAB, H-matrix)
+- [docs/HMATRIX_USER_GUIDE.md](docs/HMATRIX_USER_GUIDE.md) - H-matrix acceleration guide
 
 ### NGSolve Integration
-- [RAD_NGSOLVE_BUILD_SUCCESS.md](RAD_NGSOLVE_BUILD_SUCCESS.md) - Complete radia_ngsolve documentation
-- [examples/Radia_to_NGSolve_CoefficientFunction/README.md](examples/Radia_to_NGSolve_CoefficientFunction/README.md) - NGSolve examples overview
-- [examples/Radia_to_NGSolve_CoefficientFunction/EXAMPLES_GUIDE.md](examples/Radia_to_NGSolve_CoefficientFunction/EXAMPLES_GUIDE.md) - Detailed usage guide
-- [tests/test_radia_ngsolve.py](tests/test_radia_ngsolve.py) - Integration tests
+- [docs/NGSOLVE_USAGE_GUIDE.md](docs/NGSOLVE_USAGE_GUIDE.md) - How to use Radia with NGSolve
+- [docs/NGSOLVE_INTEGRATION.md](docs/NGSOLVE_INTEGRATION.md) - Integration overview
 
-### Development
-- [docs/TAB_CONVERSION_REPORT.md](docs/TAB_CONVERSION_REPORT.md) - Code style conversion
-- [docs/CLAUDE.md](docs/CLAUDE.md) - Development notes
+### Examples
+- [examples/ngsolve_integration/](examples/ngsolve_integration/) - NGSolve integration examples
+- [examples/magpylib_integration/](examples/magpylib_integration/) - magpylib background field examples
+- [examples/simple_problems/](examples/simple_problems/) - Basic magnet configurations
+- [tests/README.md](tests/README.md) - Test suite documentation
 
 ## Performance
 
@@ -197,7 +215,7 @@ OpenMP parallelization results (8-core system):
 | 4       | 3.57      | 3.27x   |
 | 8       | 4.33      | 2.70x   |
 
-See [docs/OPENMP_PERFORMANCE_REPORT.md](docs/OPENMP_PERFORMANCE_REPORT.md) for details.
+See [docs/SOLVER_METHODS.md](docs/SOLVER_METHODS.md) for solver performance details.
 
 ## Examples
 
@@ -205,12 +223,12 @@ Practical examples are available in the `examples/` directory:
 
 
 ### NGSolve Integration
-- `examples/Radia_to_NGSolve_CoefficientFunction/` - **Radia → NGSolve: Use Radia fields in FEM**
+- `examples/ngsolve_integration/` - **Radia → NGSolve: Use Radia fields in FEM**
   - `demo_field_types.py` - All field types demonstration
   - `visualize_field.py` - Field visualization and comparison
   - `export_radia_geometry.py` - Export geometry to VTK
 
-- `examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/` - **NGSolve → Radia: Background fields**
+- `examples/background_fields/` - **NGSolve → Radia: Background fields**
   - `test_sphere_in_quadrupole.py` - Magnetizable sphere in quadrupole field
   - Uses Python callbacks to define arbitrary background fields
 
@@ -434,7 +452,7 @@ See:
 
 This tool perfectly complements Radia_NGSolve by providing high-quality mesh generation:
 
-- **Nastran Format Export** - Compatible with Radia's `nastran_reader.py` module
+- **Nastran Format Export** - Compatible with Radia's `nastran_mesh_import.py` module
 - **Multiple Format Support** - Gmsh, MEG, VTK, and Nastran exports
 - **2D/3D Meshing** - Supports complex 3D geometries
 - **Second-Order Elements** - High-accuracy mesh generation
@@ -442,10 +460,10 @@ This tool perfectly complements Radia_NGSolve by providing high-quality mesh gen
 **Workflow Example:**
 1. Create complex geometry in Coreform Cubit
 2. Export to Nastran format using `Coreform_Cubit_Mesh_Export`
-3. Import into Radia using `nastran_reader.py`
+3. Import into Radia using `nastran_mesh_import.py`
 4. Couple with NGSolve for FEM analysis
 
-See [examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/](examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/) for Nastran mesh usage examples.
+See [examples/background_fields/](examples/background_fields/) for Nastran mesh usage examples.
 
 ## Links
 
@@ -455,5 +473,5 @@ See [examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/](examples/NG
 
 ---
 
-**Version**: 1.3.4 (OpenMP + NGSolve Edition)
-**Last Updated**: 2025-11-30
+**Version**: 1.3.9 (OpenMP + NGSolve Edition)
+**Last Updated**: 2025-12-05

{radia-1.3.9 → radia-1.3.10}/README.md

@@ -54,7 +54,7 @@ pip install radia-ngsolve
 # - build/Release/radia_ngsolve.pyd
 ```
 
-See [README_BUILD.md](README_BUILD.md) for detailed build instructions.
+See [BUILD.md](BUILD.md) for detailed build instructions.
 
 ### Basic Usage
 
@@ -77,6 +77,21 @@ print(f"Field: {field} T")
 
 The `radia_ngsolve` module provides a C++ CoefficientFunction interface for using Radia magnetic fields in NGSolve FEM analysis.
 
+**Requirements:**
+- NGSolve must be installed separately: `pip install ngsolve`
+- **IMPORTANT**: NGSolve must be imported **before** `radia_ngsolve`
+- Current build is linked against **NGSolve 6.2.2406** (Windows Python 3.12)
+
+**Installation:**
+
+```bash
+# 1. Install NGSolve first
+pip install ngsolve
+
+# 2. Install Radia (includes radia_ngsolve.pyd)
+pip install radia
+```
+
 **Function Specification:**
 
 ```python
@@ -102,12 +117,12 @@ radia_ngsolve.RadiaField(radia_obj, field_type='b')
 **Example:**
 
 ```python
-# IMPORTANT: Import ngsolve first
+# IMPORTANT: Import ngsolve FIRST (required to load NGSolve DLLs)
 import ngsolve
-from ngsolve import Mesh, H1, GridFunction
+from ngsolve import Mesh, H1, GridFunction, HDiv
 
 import radia as rad
-import radia_ngsolve
+from radia import radia_ngsolve  # or: import radia_ngsolve
 
 # Create Radia magnet
 magnet = rad.ObjRecMag([0,0,0], [20,20,20], [0,0,1.2])  # mm units
@@ -125,24 +140,27 @@ gf = GridFunction(fes)
 gf.Set(B_field)  # Automatically converts mesh coordinates m → mm
 ```
 
-See [examples/Radia_to_NGSolve_CoefficientFunction/](examples/Radia_to_NGSolve_CoefficientFunction/) for complete examples.
+See [examples/ngsolve_integration/](examples/ngsolve_integration/) for complete examples.
 
 ## Documentation
 
-### Core
-- [README_BUILD.md](README_BUILD.md) - Build instructions
-- [docs/OPENMP_PERFORMANCE_REPORT.md](docs/OPENMP_PERFORMANCE_REPORT.md) - OpenMP benchmarks
-- [docs/DIRECTORY_STRUCTURE.md](docs/DIRECTORY_STRUCTURE.md) - Project structure
+### Build & Setup
+- [BUILD.md](BUILD.md) - Build instructions (Windows, macOS, Linux)
+
+### User Guides
+- [docs/API_REFERENCE.md](docs/API_REFERENCE.md) - Complete Python API reference
+- [docs/SOLVER_METHODS.md](docs/SOLVER_METHODS.md) - Solver methods (LU, BiCGSTAB, H-matrix)
+- [docs/HMATRIX_USER_GUIDE.md](docs/HMATRIX_USER_GUIDE.md) - H-matrix acceleration guide
 
 ### NGSolve Integration
-- [RAD_NGSOLVE_BUILD_SUCCESS.md](RAD_NGSOLVE_BUILD_SUCCESS.md) - Complete radia_ngsolve documentation
-- [examples/Radia_to_NGSolve_CoefficientFunction/README.md](examples/Radia_to_NGSolve_CoefficientFunction/README.md) - NGSolve examples overview
-- [examples/Radia_to_NGSolve_CoefficientFunction/EXAMPLES_GUIDE.md](examples/Radia_to_NGSolve_CoefficientFunction/EXAMPLES_GUIDE.md) - Detailed usage guide
-- [tests/test_radia_ngsolve.py](tests/test_radia_ngsolve.py) - Integration tests
+- [docs/NGSOLVE_USAGE_GUIDE.md](docs/NGSOLVE_USAGE_GUIDE.md) - How to use Radia with NGSolve
+- [docs/NGSOLVE_INTEGRATION.md](docs/NGSOLVE_INTEGRATION.md) - Integration overview
 
-### Development
-- [docs/TAB_CONVERSION_REPORT.md](docs/TAB_CONVERSION_REPORT.md) - Code style conversion
-- [docs/CLAUDE.md](docs/CLAUDE.md) - Development notes
+### Examples
+- [examples/ngsolve_integration/](examples/ngsolve_integration/) - NGSolve integration examples
+- [examples/magpylib_integration/](examples/magpylib_integration/) - magpylib background field examples
+- [examples/simple_problems/](examples/simple_problems/) - Basic magnet configurations
+- [tests/README.md](tests/README.md) - Test suite documentation
 
 ## Performance
 
@@ -155,7 +173,7 @@ OpenMP parallelization results (8-core system):
 | 4       | 3.57      | 3.27x   |
 | 8       | 4.33      | 2.70x   |
 
-See [docs/OPENMP_PERFORMANCE_REPORT.md](docs/OPENMP_PERFORMANCE_REPORT.md) for details.
+See [docs/SOLVER_METHODS.md](docs/SOLVER_METHODS.md) for solver performance details.
 
 ## Examples
 
@@ -163,12 +181,12 @@ Practical examples are available in the `examples/` directory:
 
 
 ### NGSolve Integration
-- `examples/Radia_to_NGSolve_CoefficientFunction/` - **Radia → NGSolve: Use Radia fields in FEM**
+- `examples/ngsolve_integration/` - **Radia → NGSolve: Use Radia fields in FEM**
   - `demo_field_types.py` - All field types demonstration
   - `visualize_field.py` - Field visualization and comparison
   - `export_radia_geometry.py` - Export geometry to VTK
 
-- `examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/` - **NGSolve → Radia: Background fields**
+- `examples/background_fields/` - **NGSolve → Radia: Background fields**
   - `test_sphere_in_quadrupole.py` - Magnetizable sphere in quadrupole field
   - Uses Python callbacks to define arbitrary background fields
 
@@ -392,7 +410,7 @@ See:
 
 This tool perfectly complements Radia_NGSolve by providing high-quality mesh generation:
 
-- **Nastran Format Export** - Compatible with Radia's `nastran_reader.py` module
+- **Nastran Format Export** - Compatible with Radia's `nastran_mesh_import.py` module
 - **Multiple Format Support** - Gmsh, MEG, VTK, and Nastran exports
 - **2D/3D Meshing** - Supports complex 3D geometries
 - **Second-Order Elements** - High-accuracy mesh generation
@@ -400,10 +418,10 @@ This tool perfectly complements Radia_NGSolve by providing high-quality mesh gen
 **Workflow Example:**
 1. Create complex geometry in Coreform Cubit
 2. Export to Nastran format using `Coreform_Cubit_Mesh_Export`
-3. Import into Radia using `nastran_reader.py`
+3. Import into Radia using `nastran_mesh_import.py`
 4. Couple with NGSolve for FEM analysis
 
-See [examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/](examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/) for Nastran mesh usage examples.
+See [examples/background_fields/](examples/background_fields/) for Nastran mesh usage examples.
 
 ## Links
 
@@ -413,5 +431,5 @@ See [examples/NGSolve_CoefficientFunction_to_Radia_BackgroundField/](examples/NG
 
 ---
 
-**Version**: 1.3.4 (OpenMP + NGSolve Edition)
-**Last Updated**: 2025-11-30
+**Version**: 1.3.9 (OpenMP + NGSolve Edition)
+**Last Updated**: 2025-12-05

{radia-1.3.9 → radia-1.3.10}/docs/API_EXTENSIONS.md

@@ -201,7 +201,7 @@ rad.RlxMan(intrc, 5, 100, 1.0)
 - Must be called **after** `rad.RlxPre()` and **before** solver methods
 - Can be called multiple times to define different groups
 - Overlapping intervals: behavior is undefined (avoid)
-- See [benchmark results](../examples/solver_time_evaluation/README.md) for scaling analysis
+- See [benchmark results](../examples/solver_benchmarks/README.md) for scaling analysis
 
 ---
 
@@ -345,7 +345,7 @@ print(f"Gauss-Seidel: {t_solver*1000:.2f} ms")
 
 **Performance Comparison**:
 
-See detailed benchmark results in [`examples/solver_time_evaluation/README.md`](../examples/solver_time_evaluation/README.md).
+See detailed benchmark results in [`examples/solver_benchmarks/README.md`](../examples/solver_benchmarks/README.md).
 
 **Summary**:
 - **Small N (< 64)**: LU and GS comparable
@@ -361,7 +361,7 @@ See detailed benchmark results in [`examples/solver_time_evaluation/README.md`](
 
 **Related Documentation**:
 - Original ESRF Methods 0-4: https://www.esrf.fr/home/Accelerators/instrumentation--equipment/Software/Radia/Documentation/ReferenceGuide.html
-- Benchmark analysis: [`examples/solver_time_evaluation/README.md`](../examples/solver_time_evaluation/README.md)
+- Benchmark analysis: [`examples/solver_benchmarks/README.md`](../examples/solver_benchmarks/README.md)
 
 ---
 
@@ -722,7 +722,7 @@ B_direct = radia_ngsolve.RadiaField(magnet, 'b')
 
 #### Performance Comparison
 
-See [`examples/Radia_to_NGSolve_CoefficientFunction_A/README.md`](../examples/Radia_to_NGSolve_CoefficientFunction_A/README.md) for detailed benchmarks.
+See [`examples/ngsolve_integration/README.md`](../examples/ngsolve_integration/README.md) for detailed benchmarks.
 
 **Typical speedup with H-matrix** (N > 500):
 - Field evaluation: 2-10× faster
@@ -761,7 +761,7 @@ See [`examples/Radia_to_NGSolve_CoefficientFunction_A/README.md`](../examples/Ra
    https://www.esrf.fr/home/Accelerators/instrumentation--equipment/Software/Radia/Documentation/ReferenceGuide.html
 
 2. **Benchmark Results**
-   [`examples/solver_time_evaluation/README.md`](../examples/solver_time_evaluation/README.md)
+   [`examples/solver_benchmarks/README.md`](../examples/solver_benchmarks/README.md)
 
 3. **NGSolve Integration Guide**
    [`docs/NGSOLVE_USAGE_GUIDE.md`](NGSOLVE_USAGE_GUIDE.md)

{radia-1.3.9 → radia-1.3.10}/docs/API_REFERENCE.md

@@ -1021,7 +1021,7 @@ rad.Solve(mag_obj, 0.0001, 10000)
    - [API_EXTENSIONS.md](API_EXTENSIONS.md) - Detailed documentation of custom extensions
 
 3. **Examples**
-   - [`examples/solver_time_evaluation/README.md`](../examples/solver_time_evaluation/README.md) - Solver benchmarks
+   - [`examples/solver_benchmarks/README.md`](../examples/solver_benchmarks/README.md) - Solver benchmarks
    - [`examples/simple_problems/`](../examples/simple_problems/) - Basic examples
    - [`examples/complex_coil_geometry/`](../examples/complex_coil_geometry/) - Complex geometries
 

radia-1.3.10/docs/HMATRIX_EVALUATION.md

@@ -0,0 +1,139 @@
+# H-Matrix Acceleration Evaluation for Radia
+
+**Date**: 2025-12-05
+**Status**: Evaluation Complete - NOT Recommended for Radia
+
+## Executive Summary
+
+H-matrix (Hierarchical Matrix) acceleration was evaluated for Radia's MMM (Magnetic Moment Method) solver. **Conclusion: H-matrix provides NO benefit for Radia's typical use cases** and is NOT recommended for integration.
+
+## Benchmark Results
+
+### Single Compact Object (Cube in Uniform Field)
+
+| N_div | Elements | DOF | LU Time | BiCGSTAB Time | H-matrix BiCGSTAB |
+|-------|----------|-----|---------|---------------|-------------------|
+| 10 | 1,000 | 3,000 | 2.01s | 0.54s | 0.53s (**1.02x**) |
+| 15 | 3,375 | 10,125 | 24.28s | 7.56s | 7.27s (**1.04x**) |
+| 20 | 8,000 | 24,000 | 278.68s | 47.05s | 47.33s (**0.99x**) |
+
+**Key Finding**: H-matrix shows **NO speedup** (0.97x-1.04x ratio) for compact objects.
+
+## Why H-Matrix Does NOT Help Radia
+
+### 1. Admissibility Criterion Failure
+
+H-matrix partitions the interaction matrix into:
+- **Far-field blocks**: Low-rank approximation (ACA)
+- **Near-field blocks**: Dense (full) storage
+
+The admissibility criterion is:
+```
+dist(cluster_i, cluster_j) >= eta * min(diam(cluster_i), diam(cluster_j))
+```
+
+For a **single compact object** (typical Radia use case):
+- All elements are spatially close together
+- `dist` is always small relative to `diam`
+- **NO blocks satisfy the admissibility criterion**
+- **ALL blocks remain dense** -> No compression benefit
+
+### 2. Radia's Typical Use Cases
+
+Radia is designed for:
+- Single magnet assemblies (undulators, wigglers)
+- Compact electromagnet designs
+- Objects where elements are tightly packed
+
+These geometries have **high element density** with **no spatial separation**, making H-matrix ineffective.
+
+### 3. When H-Matrix WOULD Help
+
+H-matrix is beneficial for:
+- **Multiple separated objects** (e.g., array of magnets with large gaps)
+- **Particle simulations** with distributed sources
+- **BEM** for 3D geometries with large surface-to-volume ratio
+
+These are **NOT typical Radia use cases**.
+
+## HACApK Integration Assessment
+
+### HACApK Library Overview
+- **Source**: ppOpen-HPC project (MIT License)
+- **Purpose**: H-matrix with ACA+ for large-scale problems
+- **Design**: MPI-parallel, targeting supercomputers
+
+### Integration Challenges
+
+1. **MPI Dependency**
+   - HACApK requires MPI (`#include <mpi.h>`)
+   - Solution: MPI stub header created (`mpi_stub.h`)
+   - Status: Solved
+
+2. **Callback Interface**
+   - HACApK requires `cHACApK_calc_entry_ij.h` for matrix element computation
+   - Must provide Radia-specific implementation
+   - Complexity: Medium
+
+3. **Code Adaptation**
+   - ~5000+ lines of C/Fortran code
+   - Designed for distributed memory systems
+   - Would require significant adaptation for single-process use
+
+4. **Build System Integration**
+   - CMake changes needed
+   - Cross-platform testing required
+
+### Effort vs. Benefit Analysis
+
+| Aspect | Effort | Benefit |
+|--------|--------|---------|
+| MPI stub | Low | - |
+| Callback implementation | Medium | - |
+| Code adaptation | High | - |
+| Build integration | Medium | - |
+| Testing/debugging | High | - |
+| **Total Effort** | **HIGH** | **ZERO** (for typical use cases) |
+
+## Recommendation
+
+**DO NOT integrate HACApK** for the following reasons:
+
+1. **No benefit for typical use cases**: H-matrix provides zero speedup for compact objects
+2. **High integration effort**: ~2-4 weeks of development time
+3. **Code complexity**: Adds 5000+ lines of code to maintain
+4. **Limited applicability**: Only helps for separated objects (rare in Radia)
+
+### Alternative Optimizations
+
+For Radia performance improvement, consider:
+
+1. **OpenMP parallelization** (already implemented)
+   - Matrix-vector product parallelization
+   - LU decomposition parallelization
+
+2. **BLAS/LAPACK optimization**
+   - OpenBLAS with optimized kernels
+   - Intel MKL for Intel CPUs
+
+3. **Preconditioner improvements**
+   - Better Jacobi/block-Jacobi preconditioners
+   - ILU preconditioner for BiCGSTAB
+
+4. **Memory layout optimization**
+   - Cache-friendly data structures
+   - SIMD vectorization
+
+## Files Created During Evaluation
+
+- `src/ext/HACApK_LH-Cimplm/mpi_stub.h` - MPI stub for single-process
+
+## References
+
+1. HACApK: https://github.com/RIKENGITHUB/ppOpen-HPC
+2. Original paper: Ida, A., et al. "HACApK: An H-matrix library for Krylov methods"
+3. Radia benchmarks: `examples/cube_uniform_field/nonlinear/`
+
+---
+
+**Conclusion**: H-matrix acceleration is NOT suitable for Radia. Focus on other optimization strategies.