tcad-stabilizer 0.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,38 @@
1
+ """TCAD Stabilizer v0.6 — Newton stabilization hooks for drift-diffusion solvers.
2
+ 1D/2D/3D diodes, 2D MOSFET, and 3D MOSFET.
3
+ v0.6: sparse colored Jacobians + gated reuse in the 2D solvers (20-70x
4
+ faster, identical results), MOSFET adaptive mesh options, fast modes.
5
+ See SPEED.md and SWEEP.md."""
6
+ from .stabilizer import make_stabilizer, solve_with_fallback
7
+ from .hook_interface import VERSION as HOOK_VERSION
8
+ try:
9
+ from .dd_solver_2d import DDSolver2D as Diode2D
10
+ _has_2d = True
11
+ except ImportError:
12
+ _has_2d = False
13
+ try:
14
+ from .mosfet_2d import MOSFET2D
15
+ _has_mosfet = True
16
+ except ImportError:
17
+ _has_mosfet = False
18
+ try:
19
+ from .diode_3d import DDSolver3D
20
+ _has_3d = True
21
+ except ImportError:
22
+ _has_3d = False
23
+ try:
24
+ from .mosfet_3d import MOSFET3D
25
+ _has_mosfet3d = True
26
+ except ImportError:
27
+ _has_mosfet3d = False
28
+
29
+ __version__ = "0.6.0"
30
+ __all__ = ["make_stabilizer", "solve_with_fallback", "HOOK_VERSION"]
31
+ if _has_2d:
32
+ __all__.append("Diode2D")
33
+ if _has_mosfet:
34
+ __all__.append("MOSFET2D")
35
+ if _has_3d:
36
+ __all__.append("DDSolver3D")
37
+ if _has_mosfet3d:
38
+ __all__.append("MOSFET3D")
@@ -0,0 +1,58 @@
1
+ """
2
+ Classical damping baselines, implemented as Newton-hook functions.
3
+
4
+ Each hook has the product interface: hook(state) -> {"alpha": ...}.
5
+ `alpha` is a scalar or per-element array applied as x_new = x + alpha*delta.
6
+ These are the fallback policies the product must never perform worse than.
7
+ """
8
+
9
+ import numpy as np
10
+
11
+
12
+ def hook_none(state):
13
+ """Plain Newton (alpha = 1)."""
14
+ return {}
15
+
16
+
17
+ def hook_fixed(alpha):
18
+ """Constant damping."""
19
+ def h(state):
20
+ return {"alpha": float(alpha)}
21
+ h.__name__ = f"fixed({alpha})"
22
+ return h
23
+
24
+
25
+ def hook_armijo(c=1e-4, max_backtrack=12):
26
+ """
27
+ Backtracking line search on merit m = ||S*F||_2^2.
28
+ For the exact Newton direction the directional derivative is -2*m,
29
+ so the Armijo condition is m_new <= m * (1 - 2*c*alpha).
30
+ """
31
+ def h(state):
32
+ solver = state["solver"]
33
+ s = state["row_scale"]
34
+ F, d = state["residual"], state["delta"]
35
+ m = float(np.sum((s * F) ** 2))
36
+ alpha = 1.0
37
+ for _ in range(max_backtrack):
38
+ Fn = solver.residual(state["x"] + alpha * d)
39
+ mn = float(np.sum((s * Fn) ** 2))
40
+ if np.isfinite(mn) and mn <= m * (1.0 - 2.0 * c * alpha):
41
+ break
42
+ alpha *= 0.5
43
+ return {"alpha": alpha}
44
+ h.__name__ = "armijo"
45
+ return h
46
+
47
+
48
+ def hook_dvmax(dvmax=1.0):
49
+ """
50
+ Potential-update limiting (Atlas-style DVMAX): cap the largest
51
+ Newton update component at `dvmax` volts by scaling the whole step.
52
+ """
53
+ def h(state):
54
+ mx = float(np.max(np.abs(state["delta"])))
55
+ alpha = min(1.0, dvmax / mx) if mx > dvmax else 1.0
56
+ return {"alpha": alpha}
57
+ h.__name__ = f"dvmax({dvmax})"
58
+ return h
@@ -0,0 +1,280 @@
1
+ """
2
+ Phase 1 reference solver: 1D drift-diffusion (drift-diffusion).
3
+
4
+ Physics: Poisson + electron/hole continuity, steady state,
5
+ Scharfetter-Gummel discretization of carrier fluxes, Newton-Raphson.
6
+
7
+ Formulation: unknowns per node are [psi, phin, phip] (electrostatic
8
+ potential and electron/hole quasi-Fermi potentials, all O(1) volts).
9
+ Carrier densities via Boltzmann: n = ni*exp((psi-phin)/Vt),
10
+ p = ni*exp((phip-psi)/Vt). (Degenerate statistics NOT modelled --
11
+ noted limitation for Phase 1.)
12
+
13
+ Newton loop exposes a per-iteration hook, the product interface:
14
+ correction = hook(state) # state -> dict
15
+ alpha = correction.get("alpha", 1.0)
16
+ x_new = x + alpha * delta
17
+ `alpha` may be a scalar or an array broadcastable to the Newton step.
18
+ Default (hook=None): plain Newton, alpha = 1.
19
+
20
+ Phase 2 Track B seam: `solver.flux_mult` (None default) holds optional
21
+ per-edge Bernoulli multipliers applied inside residual(). None reproduces
22
+ Phase 1 exactly; the solver adapter sets it when a Track B correction
23
+ is issued.
24
+
25
+ Row equilibration: each residual row is scaled by 1/|F0| (F0 = initial
26
+ residual), Dirichlet rows by 1.0 (absolute volts). Convergence is
27
+ ||S*F||_inf < tol.
28
+ """
29
+
30
+ import numpy as np
31
+
32
+ # ---------------- physical constants (SI) ----------------
33
+ q = 1.602176634e-19 # C
34
+ kB = 1.380649e-23 # J/K
35
+ T = 300.0 # K
36
+ Vt = kB * T / q # thermal voltage ~ 0.02585 V
37
+ eps0 = 8.854187817e-12 # F/m
38
+ eps_si = 11.7 * eps0 # silicon permittivity
39
+ ni = 1.0e16 # intrinsic carrier conc, m^-3 (Si, 300K)
40
+ mun = 0.14 # electron mobility, m^2/V/s
41
+ mup = 0.05 # hole mobility, m^2/V/s
42
+ Dn = mun * Vt # Einstein
43
+ Dp = mup * Vt
44
+
45
+
46
+ def bernoulli(x):
47
+ """Bernoulli function B(x) = x/(exp(x)-1), numerically stable."""
48
+ x = np.asarray(x, dtype=float)
49
+ out = np.empty_like(x)
50
+ big_pos = x > 50.0
51
+ big_neg = x < -50.0
52
+ mid = ~(big_pos | big_neg)
53
+ xm = x[mid]
54
+ tiny = np.abs(xm) < 1e-10
55
+ vals = np.empty_like(xm)
56
+ vals[tiny] = 1.0 - xm[tiny] / 2.0 + xm[tiny] ** 2 / 12.0
57
+ vals[~tiny] = xm[~tiny] / np.expm1(xm[~tiny])
58
+ out[mid] = vals
59
+ out[big_pos] = 0.0
60
+ out[big_neg] = -x[big_neg]
61
+ return out
62
+
63
+
64
+ def densities(psi, phin, phip):
65
+ """Boltzmann carrier densities from quasi-Fermi potentials."""
66
+ n = ni * np.exp(np.clip((psi - phin) / Vt, -50.0, 50.0))
67
+ p = ni * np.exp(np.clip((phip - psi) / Vt, -50.0, 50.0))
68
+ return n, p
69
+
70
+
71
+ class DriftDiffusion1D:
72
+ def __init__(self, N=120, L=2e-6, Na=1e22, Nd=1e22,
73
+ xj=0.5, abrupt_cells=2, taun=1e-6, taup=1e-6,
74
+ Vleft=0.0, Vright=0.0):
75
+ """
76
+ N: mesh nodes; L: device length (m); Na/Nd: doping (m^-3);
77
+ xj: junction position as fraction of L; abrupt_cells: transition
78
+ width in mesh cells (smaller = sharper, more brutal for SG);
79
+ taun/taup: SRH lifetimes (s); Vleft/Vright: contact bias (V).
80
+ """
81
+ self.N, self.L = N, L
82
+ self.xc = np.linspace(0.0, L, N)
83
+ self.h = L / (N - 1)
84
+ self.taun, self.taup = taun, taup
85
+ self.Vleft, self.Vright = Vleft, Vright
86
+
87
+ # Net doping C = Nd - Na: -Na left of junction, +Nd right.
88
+ wt = abrupt_cells * self.h
89
+ x = self.xc
90
+ trans = np.clip((x - (xj * L - wt / 2.0)) / wt, 0.0, 1.0)
91
+ self.C = -Na + (Na + Nd) * trans
92
+
93
+ # Ohmic contact boundary values.
94
+ self.psi_b0 = Vleft + Vt * np.arcsinh(self.C[0] / (2.0 * ni))
95
+ self.psi_b1 = Vright + Vt * np.arcsinh(self.C[-1] / (2.0 * ni))
96
+
97
+ # Phase 2 Track B: per-edge Bernoulli multiplier, set from the hook's
98
+ # "flux_scale" correction. None (default) -> unmodified physics.
99
+ self.flux_mult = None
100
+ self._edge = None
101
+
102
+ # ---------------- residuals ----------------
103
+ def recombination(self, n, p):
104
+ n1 = p1 = ni
105
+ return (n * p - ni ** 2) / (self.taup * (n + n1) + self.taun * (p + p1))
106
+
107
+ def residual(self, x):
108
+ """Residual F(x). If self.flux_mult is set (Track B, from the hook's
109
+ "flux_scale"), the Scharfetter-Gummel Bernoulli values are scaled
110
+ per-edge during assembly."""
111
+ N, h = self.N, self.h
112
+ psi = x[0::3]
113
+ phin = x[1::3]
114
+ phip = x[2::3]
115
+ n, p = densities(psi, phin, phip)
116
+ F = np.zeros(3 * N)
117
+
118
+ # Poisson, interior nodes.
119
+ ii = np.arange(1, N - 1)
120
+ lap = (psi[ii + 1] - 2.0 * psi[ii] + psi[ii - 1]) / h ** 2
121
+ chg = (q / eps_si) * (p[ii] - n[ii] + self.C[ii])
122
+ F[3 * ii] = lap + chg
123
+ terms = np.zeros(3 * N)
124
+ terms[3 * ii] = np.abs(lap) + (q / eps_si) * (p[ii] + n[ii] + np.abs(self.C[ii]))
125
+
126
+ # Scharfetter-Gummel edge fluxes.
127
+ dpsi = (psi[1:] - psi[:-1]) / Vt
128
+ Bp, Bm = bernoulli(dpsi), bernoulli(-dpsi)
129
+ # Phase 2 Track B seam: per-edge Bernoulli multipliers from the hook.
130
+ # None (default) -> Phase 1 behavior, bit-identical.
131
+ _fm = self.flux_mult
132
+ if _fm is not None:
133
+ _fm = np.asarray(_fm, dtype=float)
134
+ if _fm.shape != Bp.shape:
135
+ raise ValueError(f"flux_mult shape {_fm.shape} != {Bp.shape}")
136
+ Bp = Bp * _fm
137
+ Bm = Bm * _fm
138
+ Jn = (q * Dn / h) * (n[1:] * Bp - n[:-1] * Bm)
139
+ Jp = (q * Dp / h) * (p[:-1] * Bp - p[1:] * Bm)
140
+ self._last_Jn, self._last_Jp = Jn, Jp
141
+ self._edge = {"dpsi_vt": dpsi, "bernoulli_p": Bp, "bernoulli_m": Bm}
142
+
143
+ # Continuity, interior nodes: div J + q*(R - G) = 0, G = 0.
144
+ R = self.recombination(n[ii], p[ii])
145
+ dJn = (Jn[ii] - Jn[ii - 1]) / h
146
+ dJp = (Jp[ii] - Jp[ii - 1]) / h
147
+ F[3 * ii + 1] = dJn + q * R
148
+ F[3 * ii + 2] = dJp + q * R
149
+ terms[3 * ii + 1] = np.abs(dJn) + q * np.abs(R)
150
+ terms[3 * ii + 2] = np.abs(dJp) + q * np.abs(R)
151
+
152
+ # Dirichlet (ohmic contacts).
153
+ F[0], F[1], F[2] = psi[0] - self.psi_b0, phin[0] - self.Vleft, phip[0] - self.Vleft
154
+ F[-3] = psi[-1] - self.psi_b1
155
+ F[-2] = phin[-1] - self.Vright
156
+ F[-1] = phip[-1] - self.Vright
157
+ terms[[0, 1, 2, -3, -2, -1]] = 1.0 # absolute volts
158
+
159
+ self._terms = terms
160
+ return F
161
+
162
+ def fd_jacobian(self, x, F0):
163
+ n = x.size
164
+ J = np.empty((n, n))
165
+ eps = 1e-8 * (1.0 + np.abs(x))
166
+ for j in range(n):
167
+ dx = np.zeros(n)
168
+ dx[j] = eps[j]
169
+ J[:, j] = (self.residual(x + dx) - F0) / eps[j]
170
+ return J
171
+
172
+ def initial_guess(self, Vleft=None, Vright=None):
173
+ Vl = self.Vleft if Vleft is None else Vleft
174
+ Vr = self.Vright if Vright is None else Vright
175
+ ramp = Vl + (Vr - Vl) * self.xc / self.L
176
+ psi = Vt * np.arcsinh(self.C / (2.0 * ni)) + ramp
177
+ x = np.zeros(3 * self.N)
178
+ x[0::3], x[1::3], x[2::3] = psi, ramp, ramp
179
+ return x
180
+
181
+ # ---------------- Newton solve with hook ----------------
182
+ def newton_solve(self, x0, hook=None, tol=1e-6, max_iter=60):
183
+ x = x0.copy()
184
+
185
+ # Per-row absolute floors (fixed for the device) for the relative
186
+ # residual. Rows whose own term magnitudes fall below the floor are
187
+ # treated as numerical noise, not as equations to enforce.
188
+ Cmax = max(1.0, float(np.max(np.abs(self.C))))
189
+ Ap = max((q / eps_si) * Cmax, Vt / self.h ** 2) # Poisson
190
+ An = q * mun * Vt * Cmax / self.h ** 2 # e- continuity
191
+ Ah = q * mup * Vt * Cmax / self.h ** 2 # h+ continuity
192
+ ii = np.arange(1, self.N - 1)
193
+ arow = np.ones(3 * self.N)
194
+ arow[3 * ii] = Ap
195
+ arow[3 * ii + 1] = An
196
+ arow[3 * ii + 2] = Ah
197
+
198
+ hist, alphas = [], []
199
+ converged, diverged = False, False
200
+ best = {"honest": float("inf"), "x": x.copy()}
201
+ for k in range(max_iter):
202
+ F = self.residual(x) # also refreshes self._terms
203
+ # Adaptive row scale: normalize each equation by its OWN term
204
+ # magnitudes, so the linear solve prioritizes genuinely violated
205
+ # equations. `honest` is the worst fractional imbalance.
206
+ s = 1.0 / np.maximum(self._terms, 1e-12 * arow)
207
+ honest = float(np.max(s * np.abs(F)))
208
+ hist.append(honest)
209
+ if honest < best["honest"]:
210
+ best = {"honest": honest, "x": x.copy()}
211
+ if not np.isfinite(honest) or honest > 1e6 * max(1.0, hist[0]):
212
+ diverged = True
213
+ break
214
+ J = self.fd_jacobian(x, F)
215
+ try:
216
+ delta = np.linalg.solve(s[:, None] * J, -s * F)
217
+ except np.linalg.LinAlgError:
218
+ delta, *_ = np.linalg.lstsq(s[:, None] * J, -s * F, rcond=None)
219
+ update = float(np.max(np.abs(delta)))
220
+
221
+ # Convergence: Newton update negligible (like production TCAD)
222
+ # AND no equation macroscopically violated (false-convergence guard).
223
+ if update < 1e-10 and honest < 0.5:
224
+ converged = True
225
+ break
226
+
227
+ # v1 hook state: pure data (solver-agnostic) + "solver" extension
228
+ # for advanced hooks that need residual/Jacobian evaluation.
229
+ fields = self._fields(x)
230
+ state = {
231
+ "version": "1",
232
+ "iteration": k,
233
+ "x": x.copy(), "delta": delta.copy(),
234
+ "residual": F.copy(), "residual_norm": honest,
235
+ "row_scale": s,
236
+ "mesh": {"x": self.xc.copy(), "h": self.h, "N": self.N},
237
+ "fields": {kk: vv.copy() for kk, vv in fields.items()
238
+ if kk in ("psi", "phin", "phip", "n", "p", "doping")},
239
+ "edge": {kk: vv.copy() for kk, vv in self._edge.items()},
240
+ "solver": self, # extension: not part of the v1 pure-data contract
241
+ }
242
+ corr = hook(state) if hook is not None else {}
243
+ # Track A: damping (solution-preserving).
244
+ alpha = corr.get("alpha", 1.0)
245
+ alphas.append(float(np.min(alpha)) if np.ndim(alpha) else float(alpha))
246
+ # Track B: flux modification (EXPERIMENTAL). Takes effect from the
247
+ # NEXT iteration's residual assembly (documented one-iteration lag).
248
+ if "flux_scale" in corr and corr["flux_scale"] is not None:
249
+ self.flux_mult = np.asarray(corr["flux_scale"], dtype=float)
250
+ x = x + alpha * delta
251
+
252
+ # Track B cleanup: don't leak a hook's flux_mult into later solves.
253
+ self.flux_mult = None
254
+
255
+ # Return the best state seen (for non-converged runs, the last state
256
+ # may have wandered; the best-honest state is the most physical).
257
+ rx = x if converged else best["x"]
258
+ return {
259
+ "converged": converged, "diverged": diverged,
260
+ "iterations": len(hist), "residual_history": hist,
261
+ "alphas": alphas, "x": rx,
262
+ "final_residual": hist[-1] if hist else float("inf"),
263
+ }
264
+
265
+ def _fields(self, x):
266
+ psi, phin, phip = x[0::3], x[1::3], x[2::3]
267
+ n, p = densities(psi, phin, phip)
268
+ return {"psi": psi, "phin": phin, "phip": phip,
269
+ "n": n, "p": p, "doping": self.C, "x": self.xc, "h": self.h}
270
+
271
+ def set_bias(self, Vleft, Vright):
272
+ """Update contact bias (for voltage ramping / continuation)."""
273
+ self.Vleft, self.Vright = Vleft, Vright
274
+ self.psi_b0 = Vleft + Vt * np.arcsinh(self.C[0] / (2.0 * ni))
275
+ self.psi_b1 = Vright + Vt * np.arcsinh(self.C[-1] / (2.0 * ni))
276
+
277
+ def terminal_current(self, x):
278
+ """Total current density (A/m^2) at the left contact edge."""
279
+ self.residual(x) # refresh edge fluxes
280
+ return float(self._last_Jn[0] + self._last_Jp[0])
@@ -0,0 +1,315 @@
1
+ """
2
+ Clean 2D drift-diffusion solver, verified against 1D.
3
+ Built incrementally with 1D cross-checks.
4
+ Uses SAME physical constants and functions as 1D (imported, not hardcoded).
5
+ """
6
+ import numpy as np
7
+ import sys
8
+ sys.path.insert(0, "/home/hatch/workspace/tcad/package")
9
+ from tcad_stabilizer.dd_solver import q, eps_si, Vt, ni, Dn, Dp, bernoulli, densities, mun, mup
10
+ from scipy.sparse import coo_matrix, diags
11
+ from scipy.sparse.linalg import splu, spsolve
12
+
13
+ class DDSolver2D:
14
+ def __init__(self, Nx=16, Ny=8, Lx=2e-6, Ly=1e-6,
15
+ Na=1e22, Nd=1e22, taun=1e-6, taup=1e-6,
16
+ abrupt_cells=2):
17
+ self.Nx, self.Ny, self.Lx, self.Ly = Nx, Ny, Lx, Ly
18
+ self.hx, self.hy = Lx/(Nx-1), Ly/(Ny-1)
19
+ self.N = Nx*Ny
20
+ self.taun, self.taup = taun, taup
21
+ # doping with smooth transition (matches 1D)
22
+ xc = np.linspace(0, Lx, Nx)
23
+ wt = abrupt_cells * self.hx
24
+ trans = np.clip((xc - (0.5*Lx - wt/2))/wt, 0, 1)
25
+ C1d = -Na + (Na+Nd)*trans
26
+ self.C = np.tile(C1d, Ny)
27
+ self.Vleft = self.Vright = 0.0
28
+ self._update_bc()
29
+
30
+ def _update_bc(self):
31
+ self.psi_b0 = Vt*np.arcsinh(self.C[0]/(2*ni))
32
+ self.psi_b1 = Vt*np.arcsinh(self.C[self.Nx-1]/(2*ni))
33
+
34
+ def set_bias(self, Vl, Vr):
35
+ self.Vleft, self.Vright = Vl, Vr
36
+ self._update_bc()
37
+ self.psi_b0 += Vl
38
+ self.psi_b1 += Vr
39
+
40
+ def initial_guess(self, Vleft=None, Vright=None):
41
+ # 1D-style: psi from equilibrium + ramp, phin/phip = ramp
42
+ # (much better than linear psi with zero quasi-Fermi levels)
43
+ Vl = self.Vleft if Vleft is None else Vleft
44
+ Vr = self.Vright if Vright is None else Vright
45
+ x = np.zeros(3*self.N)
46
+ psi = x[0::3]; phin = x[1::3]; phip = x[2::3]
47
+ for iy in range(self.Ny):
48
+ for ix in range(self.Nx):
49
+ n_ = iy*self.Nx + ix
50
+ f = ix/(self.Nx-1)
51
+ ramp = Vl + (Vr - Vl)*f
52
+ # equilibrium psi from doping + applied ramp
53
+ psi_eq = Vt*np.arcsinh(self.C[n_]/(2.0*ni))
54
+ psi[n_] = psi_eq + ramp
55
+ phin[n_] = ramp
56
+ phip[n_] = ramp
57
+ # Enforce Dirichlet at contacts exactly
58
+ for iy in range(self.Ny):
59
+ n0 = iy*self.Nx + 0
60
+ n1 = iy*self.Nx + (self.Nx-1)
61
+ psi[n0] = self.psi_b0; phin[n0] = Vl; phip[n0] = Vl
62
+ psi[n1] = self.psi_b1; phin[n1] = Vr; phip[n1] = Vr
63
+ return x
64
+
65
+ def residual(self, x):
66
+ Nx, Ny, hx, hy = self.Nx, self.Ny, self.hx, self.hy
67
+ psi, phin, phip = x[0::3], x[1::3], x[2::3]
68
+ n, p = densities(psi, phin, phip)
69
+ F = np.zeros(3*self.N)
70
+ terms = np.zeros(3*self.N)
71
+ idx = lambda ix, iy: iy*Nx + ix
72
+
73
+ # Precompute all edge fluxes in a single clean pass
74
+ # x-edges: index ex(ix,iy) = iy*(Nx-1)+ix, connects (ix,iy)-(ix+1,iy)
75
+ # y-edges: index ey(ix,iy) = (Ny*(Nx-1)) + iy*Nx+ix, connects (ix,iy)-(ix,iy+1)
76
+ nxe = Ny*(Nx-1)
77
+ Jn = np.zeros(nxe + Nx*(Ny-1))
78
+ Jp = np.zeros(nxe + Nx*(Ny-1))
79
+ e = 0
80
+ for iy in range(Ny):
81
+ for ix in range(Nx-1):
82
+ a, b = idx(ix,iy), idx(ix+1,iy)
83
+ dv = (psi[b]-psi[a])/Vt
84
+ Bp, Bm = bernoulli(dv), bernoulli(-dv)
85
+ Jn[e] = (q*Dn/hx)*(n[b]*Bp - n[a]*Bm)
86
+ Jp[e] = (q*Dp/hx)*(p[a]*Bp - p[b]*Bm)
87
+ e += 1
88
+ for iy in range(Ny-1):
89
+ for ix in range(Nx):
90
+ a, b = idx(ix,iy), idx(ix,iy+1)
91
+ dv = (psi[b]-psi[a])/Vt
92
+ Bp, Bm = bernoulli(dv), bernoulli(-dv)
93
+ Jn[e] = (q*Dn/hy)*(n[b]*Bp - n[a]*Bm)
94
+ Jp[e] = (q*Dp/hy)*(p[a]*Bp - p[b]*Bm)
95
+ e += 1
96
+
97
+ def jx(ix, iy): return iy*(Nx-1) + ix
98
+ def jy(ix, iy): return nxe + iy*Nx + ix
99
+
100
+ for iy in range(Ny):
101
+ for ix in range(Nx):
102
+ n_ = idx(ix, iy)
103
+ if ix == 0:
104
+ F[3*n_] = psi[n_]-self.psi_b0
105
+ F[3*n_+1] = phin[n_]-self.Vleft
106
+ F[3*n_+2] = phip[n_]-self.Vleft
107
+ terms[3*n_:3*n_+3] = 1.0
108
+ continue
109
+ if ix == Nx-1:
110
+ F[3*n_] = psi[n_]-self.psi_b1
111
+ F[3*n_+1] = phin[n_]-self.Vright
112
+ F[3*n_+2] = phip[n_]-self.Vright
113
+ terms[3*n_:3*n_+3] = 1.0
114
+ continue
115
+ # Poisson
116
+ lapx = (psi[idx(ix+1,iy)] - 2*psi[n_] + psi[idx(ix-1,iy)])/hx**2
117
+ if iy == 0:
118
+ lapy = 2*(psi[idx(ix,1)] - psi[n_])/hy**2
119
+ elif iy == Ny-1:
120
+ lapy = 2*(psi[idx(ix,Ny-2)] - psi[n_])/hy**2
121
+ else:
122
+ lapy = (psi[idx(ix,iy+1)] - 2*psi[n_] + psi[idx(ix,iy-1)])/hy**2
123
+ chg = (q/eps_si)*(p[n_]-n[n_]+self.C[n_])
124
+ F[3*n_] = lapx + lapy + chg
125
+ terms[3*n_] = abs(lapx)+abs(lapy) + (q/eps_si)*(p[n_]+n[n_]+abs(self.C[n_]))
126
+ # Continuity
127
+ dJn = (Jn[jx(ix,iy)]-Jn[jx(ix-1,iy)])/hx
128
+ dJp = (Jp[jx(ix,iy)]-Jp[jx(ix-1,iy)])/hx
129
+ if iy < Ny-1:
130
+ dJn += Jn[jy(ix,iy)]/hy
131
+ dJp += Jp[jy(ix,iy)]/hy
132
+ if iy > 0:
133
+ dJn -= Jn[jy(ix,iy-1)]/hy
134
+ dJp -= Jp[jy(ix,iy-1)]/hy
135
+ R = (n[n_]*p[n_]-ni**2)/(self.taup*(n[n_]+ni)+self.taun*(p[n_]+ni))
136
+ F[3*n_+1] = dJn + q*R
137
+ F[3*n_+2] = dJp + q*R
138
+ terms[3*n_+1] = abs(dJn) + q*abs(R) + 1e-30
139
+ terms[3*n_+2] = abs(dJp) + q*abs(R) + 1e-30
140
+
141
+ self._terms = terms
142
+ return F
143
+
144
+ def sparse_jacobian(self, x, F):
145
+ """Colored finite-difference Jacobian -> scipy CSR.
146
+
147
+ 5-point stencil => columns of nodes with (ix%3, iy%3) equal never
148
+ share a row: 9 colors x 3 vars = 27 residual evals per build,
149
+ independent of mesh size (dense FD needs 3*N evals: 462-1512+).
150
+ Same per-unknown eps as the old dense FD, so entries agree.
151
+ """
152
+ Nx, Ny = self.Nx, self.Ny
153
+ n3 = 3*self.N
154
+ rows, cols, data = [], [], []
155
+ eps0 = 1e-8
156
+ for cy in range(3):
157
+ for cx in range(3):
158
+ members = [iy*Nx + ix
159
+ for iy in range(cy, Ny, 3)
160
+ for ix in range(cx, Nx, 3)]
161
+ if not members:
162
+ continue
163
+ for w in range(3):
164
+ xp = x.copy()
165
+ for m in members:
166
+ xp[3*m+w] += eps0*(1.0 + abs(x[3*m+w]))
167
+ dF = self.residual(xp) - F
168
+ for m in members:
169
+ em = eps0*(1.0 + abs(x[3*m+w]))
170
+ col = 3*m + w
171
+ ix, iy = m % Nx, m // Nx
172
+ for (jx, jy) in ((ix, iy), (ix-1, iy), (ix+1, iy),
173
+ (ix, iy-1), (ix, iy+1)):
174
+ if 0 <= jx < Nx and 0 <= jy < Ny:
175
+ mm = jy*Nx + jx
176
+ for v in range(3):
177
+ rows.append(3*mm+v)
178
+ cols.append(col)
179
+ data.append(dF[3*mm+v]/em)
180
+ J = coo_matrix((data, (rows, cols)), shape=(n3, n3)).tocsr()
181
+ J.sum_duplicates()
182
+ return J
183
+
184
+ @classmethod
185
+ def fast(cls, **kw):
186
+ """Fast mode: coarse-but-valid mesh preset (12x6).
187
+
188
+ Same physics and solver; roughly 4x fewer unknowns than the
189
+ default 16x8 mesh, so solves are several times faster with a
190
+ slightly coarser (still converged, still physical) solution.
191
+ Use the default constructor when maximum accuracy is needed.
192
+ """
193
+ kw.setdefault("Nx", 12)
194
+ kw.setdefault("Ny", 6)
195
+ return cls(**kw)
196
+
197
+ def newton_solve(self, x0, hook=None, tol=1e-6, max_iter=60, jac_reuse=3):
198
+ # 1D-style Newton with physical row floors, update-based convergence,
199
+ # divergence detection, and best-state tracking.
200
+ # Linear algebra (v0.6): sparse colored FD Jacobian + splu, with
201
+ # quasi-Newton reuse -- the factorization is reused for up to
202
+ # jac_reuse iterations and rebuilt early if the residual stalls.
203
+ # The iteration matrix never changes the converged solution:
204
+ # the fixed point is F(x)=0 and the convergence test is unchanged.
205
+ x = x0.copy()
206
+ n = len(x)
207
+
208
+ # Per-row absolute floors (physical scales, like 1D)
209
+ Cmax = max(1.0, float(np.max(np.abs(self.C))))
210
+ Ap = max((q/eps_si)*Cmax, Vt/self.hx**2) # Poisson
211
+ An = q*mun*Vt*Cmax/self.hx**2 # e- continuity
212
+ Ah = q*mup*Vt*Cmax/self.hx**2 # h+ continuity
213
+ arow = np.ones(3*self.N)
214
+ for iy in range(self.Ny):
215
+ for ix in range(1, self.Nx-1):
216
+ n_ = iy*self.Nx + ix
217
+ arow[3*n_] = Ap
218
+ arow[3*n_+1] = An
219
+ arow[3*n_+2] = Ah
220
+
221
+ hist = []
222
+ converged, diverged = False, False
223
+ best = {"honest": float("inf"), "x": x.copy()}
224
+ lu = None; s_build = None; k_build = -10**9; jac_builds = 0
225
+ prev_honest = None; prev_step = None
226
+ for k in range(max_iter):
227
+ F = self.residual(x)
228
+ s = 1.0/np.maximum(self._terms, 1e-12*arow)
229
+ honest = float(np.max(s*np.abs(F)))
230
+ hist.append(honest)
231
+ if honest < best["honest"]:
232
+ best = {"honest": honest, "x": x.copy()}
233
+ if not np.isfinite(honest) or honest > 1e6*max(1.0, hist[0]):
234
+ diverged = True
235
+ break
236
+ # Sparse Jacobian: build (and factor) only when needed.
237
+ # Reuse is permitted only in the asymptotic regime (the
238
+ # previous applied step was small): reusing a stale Jacobian
239
+ # during the hard transient of a bias jump poisons the
240
+ # trajectory (found by test T4: Vg=2 jump fails with naive
241
+ # reuse, converges with fresh Jacobians).
242
+ need_build = (lu is None or (k - k_build) > jac_reuse
243
+ or prev_step is None or prev_step > 0.01
244
+ or (prev_honest is not None
245
+ and honest > 0.95*prev_honest))
246
+ delta = None
247
+ if need_build:
248
+ J = self.sparse_jacobian(x, F)
249
+ jac_builds += 1
250
+ k_build = k
251
+ try:
252
+ lu = splu((diags(s) @ J).tocsc())
253
+ s_build = s
254
+ except Exception:
255
+ lu = None
256
+ if lu is not None:
257
+ try:
258
+ delta = np.asarray(lu.solve(-(s_build*F))).ravel()
259
+ except Exception:
260
+ delta = None
261
+ if delta is not None and not np.all(np.isfinite(delta)):
262
+ delta = None
263
+ if delta is None:
264
+ # Fallback: fresh sparse direct solve, then dense lstsq
265
+ try:
266
+ delta = np.asarray(spsolve(
267
+ (diags(s) @ self.sparse_jacobian(x, F)).tocsc(),
268
+ -s*F)).ravel()
269
+ except Exception:
270
+ delta = None
271
+ if delta is None or not np.all(np.isfinite(delta)):
272
+ Jd = self.sparse_jacobian(x, F).toarray()
273
+ delta, *_ = np.linalg.lstsq(s[:,None]*Jd, -s*F, rcond=None)
274
+ prev_honest = honest
275
+ update = float(np.max(np.abs(delta)))
276
+
277
+ # Convergence: update negligible AND honest reasonable (1D-style)
278
+ if update < 1e-10 and honest < 0.5:
279
+ converged = True
280
+ break
281
+
282
+ state = {"version":"1","iteration":k,"x":x.copy(),"delta":delta.copy(),
283
+ "residual":F.copy(),"residual_norm":honest,"row_scale":s,
284
+ "mesh":{"Nx":self.Nx,"Ny":self.Ny,"hx":self.hx,"hy":self.hy},
285
+ "fields":{"psi":x[0::3].copy(),"phin":x[1::3].copy(),
286
+ "phip":x[2::3].copy(),"doping":self.C.copy()},
287
+ "edge":{},"solver":self}
288
+ corr = hook(state) if hook else {}
289
+ a = corr.get("alpha", 1.0)
290
+ a = float(np.min(a)) if np.ndim(a) else float(a)
291
+ x = x + a*delta
292
+ prev_step = a*update
293
+
294
+ rx = x if converged else best["x"]
295
+ return {"converged":converged,"diverged":diverged,
296
+ "iterations":len(hist),"residual_history":hist,"x":rx,
297
+ "final_residual":hist[-1] if hist else float("inf"),
298
+ "jac_builds":jac_builds}
299
+
300
+ def terminal_current(self, x):
301
+ """Total current (A/m) at left contact, integrated over y."""
302
+ # Recompute x-edge fluxes at ix=0
303
+ Nx, Ny, hx, hy = self.Nx, self.Ny, self.hx, self.hy
304
+ psi, phin, phip = x[0::3], x[1::3], x[2::3]
305
+ n, p = densities(psi, phin, phip)
306
+ idx = lambda ix, iy: iy*Nx + ix
307
+ Itot = 0.0
308
+ for iy in range(Ny):
309
+ a, b = idx(0,iy), idx(1,iy)
310
+ dv = (psi[b]-psi[a])/Vt
311
+ Bp, Bm = bernoulli(dv), bernoulli(-dv)
312
+ Jn = (q*Dn/hx)*(n[b]*Bp - n[a]*Bm)
313
+ Jp = (q*Dp/hx)*(p[a]*Bp - p[b]*Bm)
314
+ Itot += (Jn + Jp)*hy # integrate over y (A/m)
315
+ return float(Itot)