Accelerated solver and convergence

ChargeToleranceSpec

Charge tolerance parameters relevant to multiple simulation analysis types.

The accelerated solver is the default for every simulation (HeatChargeSimulation.use_accelerated_solver=True). Setting use_accelerated_solver=False selects the legacy solver, and is only permitted for charge simulations; heat and conduction always run on the accelerated solver.

The two solvers measure convergence differently, so tolerance values are not transferable between them. On the accelerated solver the ChargeToleranceSpec field defaults are tight and sufficient for the majority of problems. Start there and only adjust if a run does not converge.

Per-solver tolerance guidance:

Setting	Accelerated (default)	Legacy
rel_tol	tight, at the defaults (~1e-9 to 1e-10)	loose (~1e-5)
abs_tol	ignored on this path	large (~1e7 to 1e8)

Note

abs_tol only affects the legacy solver. On the accelerated (default) solver, rel_tol is the effective convergence knob.

Convergence parameters

Convergence on the accelerated solver is governed by a few fields on ChargeToleranceSpec and SteadyChargeDCAnalysis. On this solver rel_tol is the effective tolerance (abs_tol is ignored); the remaining fields control how the solver steps toward the DC solution.

Parameters you can adjust:

• rel_tol (ChargeToleranceSpec, default 1e-10): relative convergence tolerance and the effective convergence criterion on the accelerated solver. The tight default is sufficient for most problems. Loosening it is not a way to fix non-convergence (see Troubleshooting below): it only stops the solve at a higher residual, i.e. a less accurate solution.

• max_iters (ChargeToleranceSpec, default 120): maximum number of nonlinear (Newton) iterations per bias step. If the convergence history shows the residual still decreasing when a bias reaches this cap, raise it.

• convergence_dv (SteadyChargeDCAnalysis, default 1.0 V): the bias step. The solver starts at zero bias and ramps to the requested voltage in convergence_dv increments, re-solving at each step. Lowering it takes smaller, more robust steps toward the target bias, at the cost of more steps and longer runtime.

• ramp_up_iters (ChargeToleranceSpec, default 1): number of iterations over which quantities such as doping are ramped up to their full values during start-up. Increasing it introduces doping more gradually, which can stabilize start-up on heavily doped devices.

Advanced controls (leave at their defaults):

These rarely need changing. Non-default values emit a warning and can cause long runtimes or non-convergence:

• cfl_number (default 1e9)

• cfl_min (default None)

• preconditioner_iterations (default 50)

Troubleshooting convergence (accelerated solver)

The defaults converge for most problems. If a charge run on the accelerated solver does not converge, work through these in order:

1. Look at the convergence history first. Inspect sim_data.device_characteristics.dc_convergence – its converged, n_iters and residual_history fields (see SteadyConvergenceData):

   conv = sim_data.device_characteristics.dc_convergence
   conv.converged, conv.n_iters, conv.residual_history
   

   This tells you whether the residual was still decreasing (the solver simply needs more iterations) or had stagnated above the tolerance (it will not converge further without other changes).

2. Residual still decreasing – give it more iterations. Raise max_iters first. If the residual is still dropping when n_iters reaches the cap, also raise max_pseudo_steps. A non-default max_pseudo_steps emits a warning about long runtimes and convergence; that warning is conservative and is expected in this case.

3. A high-bias point fails or oscillates. Lower convergence_dv so the solver approaches the target voltage in smaller bias steps.

4. Start-up is unstable on a heavily doped device. Increase ramp_up_iters so doping is introduced more gradually.

5. Only then, trade accuracy for runtime. If the residual has stagnated above the tolerance and a less accurate solution is acceptable, loosen rel_tol to stop at that residual – but never down to legacy-style values such as 1e-5. Loosening rel_tol is not a convergence fix; it only stops the solve at a higher residual.

Migrating from the legacy solver

Because the two solvers measure convergence differently, tolerance values are not transferable: a configuration tuned for the legacy solver won’t necessarily work for the accelerated solver. In most cases td.ChargeToleranceSpec() (the defaults) is enough.

• Tighten rel_tol back toward the defaults (~1e-9 to 1e-10). The loose rel_tol (~1e-5) used on the legacy solver is satisfied almost immediately on the accelerated solver and returns an unconverged result.

• Drop the inflated abs_tol. It is ignored on the accelerated solver, so leaving it at the field default is fine.

The cfl_number, cfl_min, max_pseudo_steps and preconditioner_iterations controls apply only to the accelerated solver and have no legacy counterpart, so there is nothing to migrate there; leave them at their defaults.

Accelerated-only features

A few features are supported only on the accelerated solver, and requesting use_accelerated_solver=False while they are configured raises an error that names the offending feature:

• MasettiMobility

• SSAC at_voltages bias-point selection