# Generator Domain References

Mathematical foundations and verification sources for each matrix generator domain.

## 1. Diffusion (5-Point Stencil Laplacian)

**PDE:** `-div(κ · grad(u)) = f` on unit square, Dirichlet zero BC

**Discretization:**
Standard 5-point finite difference stencil on uniform grid with spacing `h = 1/(gs+1)`.
Off-diagonal entries: `-κ_edge / h²` where `κ_edge` is the edge-averaged diffusivity.
Diagonal entries: sum of absolute off-diagonals (negative sum of off-diagonal entries), ensuring row-sum zero for the pure Laplacian.

**Edge averaging:** Currently uses arithmetic mean `0.5·(κ_src + κ_dst)`.
For discontinuous coefficients (material jumps), the harmonic mean `2·κ_src·κ_dst / (κ_src + κ_dst)` is mathematically correct — it preserves flux continuity at interfaces and maintains M-matrix properties.
The arithmetic mean overestimates interface conductivity by orders of magnitude when jump ratios reach 10-1000×.

**Known deviation:** `variable_diffusion.py` and `enhanced_diffusion.py` omit the `1/h²` factor in off-diagonal values. This is absorbed by the `scale_and_shift` normalization (which divides by max absolute row sum), so it has no functional impact on the normalized matrix.

**Sources:**
- Chen, L. "Finite Difference Methods for Poisson Equation." UC Irvine. https://www.math.uci.edu/~chenlong/226/FDM.pdf
- Li, Z. et al. "Simple Second-Order Finite Differences for Elliptic PDEs with Discontinuous Coefficients." arXiv:1806.10593
- Zhang, Q. et al. "Analysis of the Harmonic Average Method for Interface Problems." arXiv:2502.09413 (2025) — proves second-order convergence of harmonic averaging for discontinuous coefficients
- Langtangen, H.P. "Finite Difference Computing with PDEs." Springer Open. Chapter on diffusion equations.
- Wikipedia: Five-point stencil. https://en.wikipedia.org/wiki/Five-point_stencil

---

## 2. Advection-Diffusion (Central Differences)

**PDE:** `-div(κ · grad(u)) + v · grad(u) = f`

**Discretization:**
The advection term `v · grad(u)` uses central differences:
- `du/dx ≈ (u_{i,j+1} - u_{i,j-1}) / (2h)` — coefficient `±vx/(2h)` on left/right neighbors
- `du/dy ≈ (u_{i+1,j} - u_{i-1,j}) / (2h)` — coefficient `±vy/(2h)` on up/down neighbors

Central differences contribute zero to the diagonal (antisymmetric stencil).
The advection makes the matrix non-symmetric, which is intended.

**Peclet number constraint:** Central differences are stable for cell Peclet number `Pe_h = |v|·h/κ < 2`.
With typical parameters (κ ∈ [0.1, 10], strength ∈ [0.1, 3.0], h ≈ 0.03 for gs=32), Pe_h ≈ 0.3-0.9 — well within stability bounds.

**Known deviation:** `diffusion.py` lines 29-30 swap and negate x/y advection signs (`advection_vx_signs = adv_y`, `advection_vy_signs = -adv_x`). Since velocity directions are random and symmetric around zero, this produces the same statistical distribution of matrices. No functional impact for training data generation.

**Sources:**
- Wikipedia: Central differencing scheme. https://en.wikipedia.org/wiki/Central_differencing_scheme
- Wikipedia: Numerical solution of the convection-diffusion equation. https://en.wikipedia.org/wiki/Numerical_solution_of_the_convection%E2%80%93diffusion_equation
- Langtangen, H.P. "Finite Difference Computing with PDEs." Chapter on advection-dominated equations.

---

## 3. 2D Linear Elasticity

**PDE (plane stress):**
```
-(λ+2μ)·d²ux/dx² - μ·d²ux/dy² - (λ+μ)·d²uy/dxdy = fx
-μ·d²uy/dx² - (λ+2μ)·d²uy/dy² - (λ+μ)·d²ux/dxdy = fy
```

**Plane stress Lamé parameters:**
- `λ_eff = E·ν / (1 - ν²)`
- `μ = E / (2·(1+ν))`

**Correct stencil:**

For ux-ux block (d²ux/dx² strong, d²ux/dy² weak):
- Left/right (x-direction): coefficient `-(λ+2μ)/h²` = strong
- Up/down (y-direction): coefficient `-μ/h²` = weak
- Diagonal: `2·((λ+2μ) + μ) / h²`

For uy-uy block (d²uy/dy² strong, d²uy/dx² weak):
- Up/down (y-direction): coefficient `-(λ+2μ)/h²` = strong
- Left/right (x-direction): coefficient `-μ/h²` = weak
- Diagonal: `2·((λ+2μ) + μ) / h²` (same as ux)

For coupling (mixed derivative d²/dxdy):
- Requires **4 corner neighbors** (i±1, j±1), NOT axis-aligned neighbors
- Coefficient `-(λ+μ)/(4h²)` with alternating signs: `+` at (i-1,j-1) and (i+1,j+1), `-` at (i-1,j+1) and (i+1,j-1)

**KNOWN BUGS in current implementation (elasticity.py):**
1. Strong/weak directions are swapped for both ux-ux and uy-uy blocks
2. Diagonal uses `4·c1/h²` instead of `2·(1+c2)·c1/h²`
3. Coupling connects to axis-aligned neighbors instead of corner neighbors
4. Coupling uses uniform sign instead of alternating ±1

**Sources:**
- Wikipedia: Linear elasticity. https://en.wikipedia.org/wiki/Linear_elasticity
- Wikipedia: Plane stress. https://en.wikipedia.org/wiki/Plane_stress
- Medusa library docs: Solid Mechanics. https://e6.ijs.si/medusa/wiki/index.php/Solid_Mechanics
- Shin, W. et al. "Finite Difference Schemes for the Cauchy-Navier Equations of Elasticity with Variable Coefficients." J Sci Comput 2014. https://link.springer.com/article/10.1007/s10915-014-9847-8
- Idesman, A. et al. "Compact high-order stencils for 2D elasticity." CMAME 2020. https://www.sciencedirect.com/science/article/abs/pii/S0045782519305870

---

## 4. Stokes Equations (MAC Staggered Grid)

**PDE:**
```
-μ · Δu + ∇p = f
div(u) = 0
```

**MAC scheme:**
On a staggered grid, velocity components live on cell faces, pressure at cell centers:
- u-velocity on vertical faces: `(gs+1) × gs` DOFs, stride `gs`
- v-velocity on horizontal faces: `gs × (gs+1)` DOFs, stride `gs+1`
- pressure at cell centers: `gs × gs` DOFs

**Velocity Laplacian:** Standard 5-point stencil on each velocity grid. Coefficient `4μ/h²` on diagonal, `-μ/h²` on neighbors. Boundary conditions (homogeneous Dirichlet) are implicit (missing neighbors not added).

**Divergence operator B:** For pressure cell (i,j):
```
div = (u_east - u_west)/h + (v_north - v_south)/h
```
where u_east/u_west are adjacent u-faces and v_north/v_south adjacent v-faces.

**Saddle point structure:** `[μA, B^T; B, -εI]` where A is the velocity Laplacian.

**KNOWN BUGS in current implementation (stokes.py):**
1. Divergence operator index wrapping: `u_east` for last pressure column wraps into next u-grid row; `v_north` for last pressure row accesses pressure DOF block
2. Pressure stabilization `0.01/h²` grows with grid refinement — non-standard. MAC grid satisfies inf-sup condition natively, so no stabilization needed. If used, should scale as `O(h²)` or be mesh-independent.

**Sources:**
- Chen, L. "Finite Difference Method for Stokes Equations: MAC Scheme." UC Irvine. https://www.math.uci.edu/~chenlong/226/MACStokes.pdf
- Chen, L. "Programming of MAC Scheme for Stokes Equations." https://www.math.uci.edu/~chenlong/226/MACcode.pdf
- Strang, G. "The Saddle Point Stokes Problem." MIT 18.086. https://math.mit.edu/classes/18.086/2006/am65.pdf
- iFEM Project: MAC Scheme for Stokes Equations. https://lyc102.github.io/ifem/projects/StokesMAC/
- Becker, T. "2D Stokes Equations on a Staggered Grid." UT Austin. https://www-udc.ig.utexas.edu/external/becker/teaching/557/problem_sets/problem_set_fd_stokes_staggered.pdf

---

## 5. Graph Laplacian (Barabási-Albert Model)

**Definition:** `L = D - A` where D is the degree matrix and A the adjacency matrix.

**Properties:**
- L is symmetric positive semi-definite
- Smallest eigenvalue is 0 (with eigenvector 1)
- For connected graphs, 0 has multiplicity 1
- `L_ii = deg(i)`, `L_ij = -w_ij` for edges

The BA model generates scale-free graphs via preferential attachment. It always produces connected graphs, guaranteeing a single zero eigenvalue. Parameter `m` (edges per new node, randomized 2-5) controls sparsity.

After `scale_and_shift` with `diag_shift=0.1`, the matrix becomes `L_scaled + 0.1·I` which is strictly positive definite.

**Sources:**
- Wikipedia: Laplacian matrix. https://en.wikipedia.org/wiki/Laplacian_matrix
- Wikipedia: Barabási-Albert model. https://en.wikipedia.org/wiki/Barab%C3%A1si%E2%80%93Albert_model
- Li, H. "Properties and Applications of Graph Laplacian." UChicago REU 2022. http://math.uchicago.edu/~may/REU2022/REUPapers/Li,Hanchen.pdf
- Gallier, J. "Spectral Theory of Unsigned and Signed Graphs." UPenn. https://www.cis.upenn.edu/~cis5150/cis515-14-graphlap.pdf
- MIT OCW 18.409: Properties of the Laplacian. https://ocw.mit.edu/courses/18-409-topics-in-theoretical-computer-science-an-algorithmists-toolkit-fall-2009/

---

## 6. Stochastic Block Model (SBM)

**Definition:** Nodes are partitioned into k blocks. Edge probability between nodes i,j depends only on their block membership:
- `P(edge | same block) = p_in`
- `P(edge | different blocks) = p_out`

With `p_in >> p_out`, the graph has clear community structure. The resulting graph Laplacian has eigenvalues clustered around the intra- and inter-community connectivity levels.

**Parameters:** `p_in ∈ [0.1, 0.4]`, `p_out ∈ [0.001, 0.05]`, `num_clusters ∈ [2, 5]`.

**Sources:**
- Wikipedia: Stochastic block model. https://en.wikipedia.org/wiki/Stochastic_block_model
- Holland, P.W. et al. "Stochastic blockmodels: First steps." Social Networks 5.2 (1983): 109-137.
- Abbe, E. "Community detection and stochastic block models." Found. and Trends in Comm. and Inf. Theory (2017).

---

## 7. Spectral Stress Testing

**Purpose:** Takes a base diffusion matrix and modifies its spectrum to create higher condition number matrices (harder preconditioner targets).

**Mechanism:**
1. Generate base diffusion matrix (already normalized by `scale_and_shift`)
2. Divide all off-diagonal entries by `target_κ^0.3` where `target_κ ∈ [100, 10000]`
3. Re-normalize with `scale_and_shift(diag_shift=0.05)`

Dividing off-diagonals by a constant > 1 increases diagonal dominance (by Gershgorin theorem, eigenvalues cluster tighter around diagonal values). The exponent 0.3 is a heuristic — does not target an exact condition number but produces matrices with varied, elevated condition numbers.

**Properties preserved:** Symmetry (uniform scaling of all off-diagonals), positive definiteness (increased diagonal dominance + positive shift).

**Sources:**
- Wikipedia: Gershgorin circle theorem. https://en.wikipedia.org/wiki/Gershgorin_circle_theorem
- Guillot, D. et al. "Functions preserving positive definiteness for sparse matrices." Trans. AMS 2015. https://arxiv.org/abs/1210.3894

---

## 8. Common Pipeline Components

### scale_and_shift
Normalizes the matrix by dividing by max absolute row sum (`gamma`), then adds a diagonal shift (default 0.1). This ensures:
- All eigenvalues in a bounded range (roughly [0, 1+shift])
- Strict diagonal dominance (diagonal is at least `shift` larger than needed)
- Consistent scaling across different grid sizes and domains

### make_context_pairs
Generates random (x, Ax) pairs for context-based learning. The network sees these input-output examples to infer matrix structure, analogous to in-context learning in PFN (Prior-Fitted Networks).

**PFN reference:**
- Mueller, S. et al. "Transformers Can Do Bayesian Inference." ICLR 2022. — introduces the PFN framework of training on synthetic priors.

### GridStencil
Precomputed 5-point stencil structure shared across grid-based generators. Stores row/column indices, edge masks (x vs y direction), and advection sign arrays. Avoids redundant recomputation across generators using the same grid.
