radia 1.3.13__tar.gz → 1.3.14__tar.gz

{radia-1.3.13/src/radia.egg-info → radia-1.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: radia
-Version: 1.3.13
+Version: 1.3.14
 Summary: Radia 3D Magnetostatics with NGSolve Integration and OpenMP Parallelization
 Home-page: https://github.com/ksugahar/Radia_NGSolve
 Author: Pascal Elleaume

{radia-1.3.13 → radia-1.3.14}/docs/API_EXTENSIONS.md

@@ -4,9 +4,18 @@ This document describes custom extensions to the original ESRF Radia API.
 
 **Original Documentation**: https://www.esrf.fr/home/Accelerators/instrumentation--equipment/Software/Radia/Documentation/ReferenceGuide.html
 
-**Date**: 2025-11-27
+**Date**: 2025-12-11
+**Version**: 1.3.13
 **Status**: Active development
 
+> **Note (v1.3.13):** The solver architecture was significantly updated in v1.3.13:
+> - **Recommended API**: Use `rad.Solve()` for all new code
+> - **Deprecated API**: `RlxPre()`, `RlxMan()`, `SetRelaxSubInterval()` are legacy
+> - **Solver Methods**: LU (Method 0) and BiCGSTAB (Method 1) replaced original Gauss-Seidel
+> - **H-matrix**: Under research, NOT available in v1.3.13
+>
+> See [SOLVER_METHODS.md](SOLVER_METHODS.md) for current solver documentation.
+
 ---
 
 ## Table of Contents
@@ -367,53 +376,24 @@ See detailed benchmark results in [`examples/solver_benchmarks/README.md`](../ex
 
 ## Performance Features
 
-### SolverHMatrixDisable/Enable
-
-**Purpose**: Control H-matrix (hierarchical matrix) acceleration for field computation.
-
-**Syntax**:
-```python
-rad.SolverHMatrixDisable()  # Disable H-matrix (use dense matrix)
-rad.SolverHMatrixEnable()   # Enable H-matrix (default)
-```
-
-**Parameters**: None
+### SolverHMatrixDisable/Enable (DEPRECATED)
 
-**Returns**: None
-
-**When to use**:
+> **NOT AVAILABLE in v1.3.13**
+>
+> H-matrix acceleration was evaluated and found to provide **NO benefit for typical Radia use cases**
+> (single compact objects). These APIs are not available in the current release.
+>
+> See [HMATRIX_EVALUATION.md](HMATRIX_EVALUATION.md) for evaluation results.
 
-**Disable H-matrix** (`SolverHMatrixDisable()`):
-- Small problems (N < 1000)
-- Benchmarking and testing
-- Debugging solver behavior
-- When H-matrix overhead exceeds benefit
+~~**Purpose**: Control H-matrix (hierarchical matrix) acceleration for field computation.~~
 
-**Enable H-matrix** (`SolverHMatrixEnable()`):
-- Large problems (N > 1000)
-- Production runs
-- When memory is limited
-- Long-range field computations
-
-**Usage Example**:
+~~**Syntax**:~~
 ```python
-import radia as rad
-
-# For benchmarking - use dense matrix
-rad.SolverHMatrixDisable()
-
-intrc = rad.RlxPre(obj, obj)
-rad.RlxMan(intrc, 4, 100, 1.0)
-
-# For production - re-enable H-matrix
-rad.SolverHMatrixEnable()
+# NOT AVAILABLE in v1.3.13
+# rad.SolverHMatrixDisable()
+# rad.SolverHMatrixEnable()
 ```
 
-**Notes**:
-- H-matrix is enabled by default
-- Setting persists for entire session until changed
-- Does not affect existing interaction matrices (only new ones)
-
 ---
 
 ### SolverTetraMethod
@@ -517,9 +497,16 @@ rad.SolverTetraMethod(1)
 - Added `ObjBckgCF()` for arbitrary background fields
 - Improved NGSolve integration
 
+### v1.3.13 (2025-12-11)
+- **Major solver refactoring**: Replaced Implicit SS (Gauss-Seidel) with BiCGSTAB
+- Added `rad.Solve()` as recommended API
+- Deprecated `RlxPre()`, `RlxMan()`, `SetRelaxSubInterval()` (still available for legacy)
+- H-matrix APIs removed (under research)
+- Added OpenBLAS and OpenMP optimizations
+
 ### v1.0.5 (2025-10-30)
-- Added `SolverHMatrixDisable/Enable()` controls
-- Performance improvements for H-matrix
+- Added `SolverHMatrixDisable/Enable()` controls (REMOVED in v1.3.13)
+- Performance improvements for H-matrix (REMOVED in v1.3.13)
 
 ---
 
@@ -773,6 +760,6 @@ See [`examples/ngsolve_integration/README.md`](../examples/ngsolve_integration/R
 
 ---
 
-**Last Updated**: 2025-11-27
+**Last Updated**: 2025-12-11
 **Maintained By**: Radia Development Team
 **License**: LGPL-2.1 (modifications), BSD-style (original RADIA from ESRF)

{radia-1.3.13 → radia-1.3.14}/docs/HMATRIX_SERIALIZATION.md

@@ -1,8 +1,21 @@
 # Full H-Matrix Serialization (v1.1.0)
 
+> **ARCHIVED DOCUMENT (2025-12-11)**
+>
+> **This document is archived.** H-matrix acceleration was evaluated and found to provide
+> **NO benefit for typical Radia use cases** (single compact objects).
+>
+> See [HMATRIX_EVALUATION.md](HMATRIX_EVALUATION.md) for the evaluation results.
+>
+> The H-matrix serialization feature described below is **NOT available** in v1.3.13+.
+
+---
+
 ## Overview
 
-Radia v1.1.0 introduces full H-matrix serialization to disk, providing **instant startup** for repeated simulations with the same geometry. This feature saves the complete H-matrix structure to disk and reloads it on subsequent runs, eliminating the need to rebuild the interaction matrix.
+~~Radia v1.1.0 introduces full H-matrix serialization to disk, providing **instant startup** for repeated simulations with the same geometry. This feature saves the complete H-matrix structure to disk and reloads it on subsequent runs, eliminating the need to rebuild the interaction matrix.~~
+
+**Status:** H-matrix serialization is NOT available in current releases.
 
 **Key Benefits:**
 - **~10x speedup** for solver initialization across program restarts

{radia-1.3.13 → radia-1.3.14}/docs/HMATRIX_USER_GUIDE.md

@@ -1,11 +1,24 @@
 # H-Matrix Acceleration User Guide
 
-**Version:** 1.0.10
+> **ARCHIVED DOCUMENT (2025-12-11)**
+>
+> **This document is archived.** H-matrix acceleration was evaluated and found to provide
+> **NO benefit for typical Radia use cases** (single compact objects).
+>
+> See [HMATRIX_EVALUATION.md](HMATRIX_EVALUATION.md) for the evaluation results.
+>
+> The H-matrix APIs described below are **NOT available** in v1.3.13+.
+
+---
+
+**Version:** 1.0.10 (Archived)
 **Date:** 2025-11-13
 
 ## Overview
 
-This guide explains how to use Radia's H-matrix acceleration feature for faster magnetostatic simulations. H-matrix provides up to **350x speedup** for large problems and iterative workflows.
+~~This guide explains how to use Radia's H-matrix acceleration feature for faster magnetostatic simulations. H-matrix provides up to **350x speedup** for large problems and iterative workflows.~~
+
+**Status:** H-matrix is NOT recommended and NOT available in current releases.
 
 ## Table of Contents
 

{radia-1.3.13 → radia-1.3.14}/docs/HYBRID_DOF_SOLVER_DESIGN.md

@@ -1,5 +1,16 @@
 # Hybrid Variable DOF Solver Design
 
+> **FUTURE DEVELOPMENT DOCUMENT (2025-12-11)**
+>
+> **This document describes a PROPOSED feature that is NOT YET IMPLEMENTED.**
+>
+> The current Radia implementation uses **3 DOF per element** for all element types
+> (rectangular blocks, tetrahedral MSC, and hexahedral MSC).
+>
+> The 6-DOF MSC hexahedra described below are **NOT currently available**.
+
+---
+
 ## Overview
 
 This document describes the design for extending `radTInteraction` and the LU/BiCGSTAB solvers to support **variable degrees of freedom (DOF)** per element, enabling **hybrid analysis** with:

{radia-1.3.13 → radia-1.3.14}/docs/ML_PARAMETER_TUNING.md

@@ -1,7 +1,18 @@
 # ML Parameter Tuning for H-Matrix
 
+> **ARCHIVED DOCUMENT (2025-12-11)**
+>
+> **This document is archived.** H-matrix acceleration was evaluated and found to provide
+> **NO benefit for typical Radia use cases** (single compact objects).
+>
+> See [HMATRIX_EVALUATION.md](HMATRIX_EVALUATION.md) for the evaluation results.
+>
+> The ML parameter tuning described below is **NOT applicable** in v1.3.13+.
+
+---
+
 **Date:** 2025-11-13
-**Status:** ✅ **ANALYSIS COMPLETE**
+**Status:** ARCHIVED
 
 ## Overview
 

radia-1.3.14/docs/README.md

@@ -0,0 +1,110 @@
+# Radia Documentation
+
+**Version:** 1.3.13
+**Date:** 2025-12-11
+
+This folder contains the official documentation for Radia.
+
+## Documentation Organization
+
+### Essential Documentation
+
+#### Getting Started
+- [SUPPORTED_ELEMENTS.md](SUPPORTED_ELEMENTS.md) - **Supported magnetic element types** (tet, hex, rectangular)
+- [SOLVER_METHODS.md](SOLVER_METHODS.md) - Solver methods (LU, BiCGSTAB)
+- [API_REFERENCE.md](API_REFERENCE.md) - Complete Python API reference
+
+#### NGSolve Integration
+- [NGSOLVE_USAGE_GUIDE.md](NGSOLVE_USAGE_GUIDE.md) - How to use Radia with NGSolve
+- [NGSOLVE_INTEGRATION.md](NGSOLVE_INTEGRATION.md) - Integration overview
+
+#### Mesh Import
+- [MESH_MSC_API_DESIGN.md](MESH_MSC_API_DESIGN.md) - Mesh import API design
+- [MMM_MSC_IMPLEMENTATION.md](MMM_MSC_IMPLEMENTATION.md) - MMM/MSC implementation details
+
+### Technical Documentation
+
+#### Implementation Details
+- [MATERIAL_API_IMPLEMENTATION.md](MATERIAL_API_IMPLEMENTATION.md) - Material property implementation
+- [CF_BACKGROUND_FIELD_IMPLEMENTATION.md](CF_BACKGROUND_FIELD_IMPLEMENTATION.md) - Background field implementation
+- [NGSOLVE_CF_BACKGROUND_FIELD_DESIGN.md](NGSOLVE_CF_BACKGROUND_FIELD_DESIGN.md) - NGSolve CoefficientFunction design
+- [API_EXTENSIONS.md](API_EXTENSIONS.md) - Extended features and new APIs
+
+#### H-Matrix Evaluation (Research)
+- [HMATRIX_EVALUATION.md](HMATRIX_EVALUATION.md) - **H-matrix evaluation results** (NOT recommended for typical use)
+
+**Note:** H-matrix acceleration was evaluated and found to provide no benefit for typical Radia use cases (single compact objects). The following docs are archived for reference:
+- [HMATRIX_USER_GUIDE.md](HMATRIX_USER_GUIDE.md) - (Archived) User guide
+- [HMATRIX_SERIALIZATION.md](HMATRIX_SERIALIZATION.md) - (Archived) Disk cache feature
+
+## Quick Start
+
+### 1. Supported Element Types
+
+Radia currently supports:
+
+| Element Type | API | Status |
+|--------------|-----|--------|
+| Axis-aligned rectangular | `rad.ObjRecMag()` + `rad.ObjDivMag()` | **Supported** |
+| Tetrahedron (4-face MSC) | `rad.ObjPolyhdr()` with `TETRA_FACES` | **Supported** |
+| Hexahedron (6-face MSC) | `rad.ObjPolyhdr()` with `HEX_FACES` | **Supported** |
+| General polyhedra (>6 faces) | - | **Not Supported** |
+
+See [SUPPORTED_ELEMENTS.md](SUPPORTED_ELEMENTS.md) for details.
+
+### 2. Solver Methods
+
+| Method | Name | Best For |
+|--------|------|----------|
+| LU Direct | `'lu'` or `0` | Small problems (N < 500) |
+| BiCGSTAB | `'bicgstab'` or `1` | General purpose (default) |
+
+See [SOLVER_METHODS.md](SOLVER_METHODS.md) for details.
+
+### 3. Basic Example
+
+```python
+import radia as rad
+rad.FldUnits('m')
+
+# Create soft iron cube
+cube = rad.ObjRecMag([0, 0, 0], [0.1, 0.1, 0.1], [0, 0, 0])
+rad.ObjDivMag(cube, [5, 5, 5])  # 125 elements
+
+# Apply material
+mat = rad.MatLin(999.0)  # mu_r = 1000
+rad.MatApl(cube, mat)
+
+# External field
+ext = rad.ObjBckg([0, 0, 1.0])  # 1 T
+grp = rad.ObjCnt([cube, ext])
+
+# Solve
+rad.Solve(grp, 0.0001, 1000)
+
+# Get field
+B = rad.Fld(grp, 'b', [0, 0, 0])
+print(f"B at center: {B}")
+```
+
+## Additional Resources
+
+### Examples
+Working code examples are in [../examples/](../examples/):
+- [simple_problems/](../examples/simple_problems/) - Basic examples
+- [solver_benchmarks/](../examples/solver_benchmarks/) - Performance benchmarks
+- [ngsolve_integration/](../examples/ngsolve_integration/) - NGSolve integration examples
+- [cube_uniform_field/](../examples/cube_uniform_field/) - Cube in uniform field benchmarks
+
+### Tests
+Automated tests are in [../tests/](../tests/).
+
+## See Also
+
+- [Main README](../README.md) - Project overview and installation
+- [CHANGELOG](../CHANGELOG.md) - Version history
+
+---
+
+**Last Updated:** 2025-12-11
+**Project:** Radia Magnetic Field Computation

radia-1.3.14/docs/SOLVER_METHODS.md

@@ -0,0 +1,207 @@
+# Radia Solver Methods
+
+**Version:** 1.3.13
+**Date:** 2025-12-11
+
+This document describes the available solver methods in Radia.
+
+## Available Methods
+
+| Method | Name | Complexity | Best For |
+|--------|------|------------|----------|
+| **LU Direct** | `'lu'` or `'direct'` or `0` | O(N^3) | Small problems (N < 500), guaranteed convergence |
+| **BiCGSTAB** (Default) | `'bicgstab'` or `'iterative'` or `1` | O(N^2 * k) | General purpose, large problems |
+
+**Note:** Both solvers support linear and nonlinear materials. They use pure Newton-Raphson iteration for nonlinear convergence.
+
+## Solver Architecture (v1.3.13)
+
+### Historical Background
+
+- **Original Radia**: Used Implicit SS (Successive Substitution / Gauss-Seidel) method
+  - Slow convergence for high-permeability nonlinear materials
+  - Could require hundreds of iterations
+
+- **Current Radia (v1.3.13+)**: Replaced with modern solvers
+  - **BiCGSTAB** iterative solver for better convergence
+  - **LU direct** solver for guaranteed convergence
+  - Both use pure Newton-Raphson iteration (no Gauss-Seidel M(H) correction)
+
+### Performance (v1.3.13)
+
+After OpenBLAS and OpenMP optimization:
+
+| N_elem | LU Time | BiCGSTAB Time | Notes |
+|--------|---------|---------------|-------|
+| 104 | 0.13s | 0.13s | Linear material |
+| 200 | 0.44s | 0.43s | Linear material |
+| 390 | 1.72s | 1.71s | Linear material |
+
+**Comparison with ELF_MAGIC (nonlinear material):**
+- BiCGSTAB: **0.4x-0.6x** ratio (Radia is faster)
+- LU: 7-11x ratio (more iterations in Radia due to stricter tolerance)
+
+## Usage
+
+### Basic Usage
+
+```python
+import radia as rad
+
+# Create geometry
+cube = rad.ObjRecMag([0, 0, 0], [40, 40, 40], [0, 0, 0])
+rad.ObjDivMag(cube, [5, 5, 5])
+mat = rad.MatLin(999.0)  # mu_r = 1000
+rad.MatApl(cube, mat)
+
+# Apply external field
+ext_field = rad.ObjBckg([0, 0, 1.0])  # 1 T in SI
+grp = rad.ObjCnt([cube, ext_field])
+
+# Solve using default method (BiCGSTAB)
+res = rad.Solve(grp, 0.0001, 1000)
+
+# Or specify method by name
+res = rad.Solve(grp, 0.0001, 1000, 'bicgstab')    # BiCGSTAB (default)
+res = rad.Solve(grp, 0.0001, 1000, 'lu')          # LU decomposition
+```
+
+### Method Selection Guide
+
+```
+Problem size?
+  |-- N < 500    --> Either method (LU is more robust)
+  |-- N >= 500   --> 'bicgstab' (faster)
+
+Material type?
+  |-- Linear (MatLin)      --> Any solver works
+  |-- Nonlinear (MatSatIso, etc.) --> Any solver works
+```
+
+## LU Direct Solver (Method 0)
+
+Direct solver using LU decomposition with LAPACK `dgesv`.
+
+**Pros:**
+- Exact solution per nonlinear iteration
+- Always converges (no divergence risk)
+- Stable for all materials
+
+**Cons:**
+- O(N^3) time complexity
+- O(N^2) memory usage
+
+**Best for:** Small problems (N < 500), validation/debugging
+
+```python
+res = rad.Solve(grp, 0.0001, 100, 'lu')     # By name
+res = rad.Solve(grp, 0.0001, 100, 0)        # By number
+```
+
+## BiCGSTAB Solver (Method 1, Default)
+
+BiCGSTAB (Biconjugate Gradient Stabilized) iterative solver with Jacobi preconditioning.
+
+**Pros:**
+- O(N^2 * k) time complexity (k = iterations)
+- Fast for medium to large problems
+- Good convergence with preconditioning
+
+**Cons:**
+- May not converge for ill-conditioned problems
+
+**Best for:** General magnetostatic problems, tetrahedral/hexahedral meshes
+
+```python
+res = rad.Solve(grp, 0.0001, 1000)              # Default (BiCGSTAB)
+res = rad.Solve(grp, 0.0001, 1000, 'bicgstab')  # By name
+res = rad.Solve(grp, 0.0001, 1000, 1)           # By number
+```
+
+## Convergence Tolerance
+
+The `PrecOnMagnetiz` parameter controls convergence:
+
+```python
+rad.Solve(grp, tol, max_iter, method)
+#              ^^^
+#              Relative tolerance: ||dM||/||M||
+```
+
+**Comparison with ELF_MAGIC:**
+- ELF default: `0.01` (1%)
+- Radia benchmark: `0.0001` (0.01%)
+
+**Recommendation:** Use `0.01` for typical applications, `0.0001` for high precision.
+
+## H-Matrix Acceleration
+
+**Status:** Under research (not available in v1.3.13)
+
+H-matrix (HACApK) acceleration was evaluated but found to provide **no benefit for typical Radia use cases** (single compact objects). This is because:
+
+1. All elements are spatially close together
+2. No blocks satisfy the admissibility criterion
+3. All blocks remain dense (no compression benefit)
+
+See [HMATRIX_EVALUATION.md](HMATRIX_EVALUATION.md) for details.
+
+**Future:** H-matrix may be beneficial for:
+- Multiple well-separated magnetic objects
+- Large-scale problems with distributed geometry
+
+## Technical Details
+
+### System Equation
+
+The MMM (Magnetic Moment Method) system equation:
+
+```
+(1/chi - N) * M = H_ext
+```
+
+Where:
+- `chi`: Magnetic susceptibility tensor
+- `N`: Interaction matrix (demagnetization coefficients)
+- `M`: Magnetization vector
+- `H_ext`: External field
+
+### Nonlinear Iteration
+
+For nonlinear materials, outer Newton-Raphson iteration:
+
+1. Compute `chi(H)` from current field estimate
+2. Solve linear system with current `chi`
+3. Update magnetization: `M_new = solution`
+4. Check convergence: `||M_new - M_old|| / ||M_new|| < tol`
+5. Repeat until converged
+
+### BLAS/LAPACK Optimization (v1.3.13)
+
+- `cblas_ddot`, `cblas_dnrm2`, `cblas_daxpy`: Vector operations
+- `cblas_dgemv`: Matrix-vector product
+- `dgesv_`: LU decomposition with partial pivoting
+
+### OpenMP Parallelization (v1.3.13)
+
+- Interaction matrix O(N^2) construction is parallelized
+- Speedup: Up to 240x for large problems
+
+## Migration Notes
+
+### From v1.3.6 or earlier
+
+| Old Method | New Method | Notes |
+|------------|------------|-------|
+| `8` (Newton) | Removed | Use `0` (LU) or `1` (BiCGSTAB) |
+| `9` (LU) | `0` or `'lu'` | Same functionality |
+| `10` (BiCGSTAB) | `1` or `'bicgstab'` | Same functionality |
+
+### From v1.3.12 (Implicit SS removal)
+
+Method 2 (Implicit SS / Gauss-Seidel) was removed due to slow convergence for nonlinear materials. Use BiCGSTAB (Method 1) instead.
+
+---
+
+**Last Updated:** 2025-12-11
+**Project:** Radia Magnetic Field Computation