Time-Domain Magnetic Solver¶

The TimeDomainMagneticSolver controls how the Time-Domain Magnetic Model is solved at each time step. It governs two nested loops:

• the inner linear solve — a preconditioned conjugate-gradient (CG) iteration that solves the linear system at each step;
• the outer nonlinear (Newton) iteration — needed when materials are nonlinear (e.g. a \(B\)–\(H\) curve), controlled through the under-relaxation factor and the optional line search.

Background: Linear Solvers covers the inner solve and preconditioning, and Newton Form covers the outer iteration, under-relaxation, line search, and the reported residual.

The solver is not created directly; every TimeDomainMagneticModel owns one. Access it with get_solver():

solver = time_domain_magnetic_model.get_solver()

Linear solver controls¶

These settings apply to the inner CG iteration.

set_relative_tolerance¶

solver.set_relative_tolerance(relative_tolerance: float)

Relative convergence tolerance of the CG solver: the iteration stops once the residual norm has dropped by this factor relative to the initial residual. Default 1e-6.

set_absolute_tolerance¶

solver.set_absolute_tolerance(absolute_tolerance: float)

Absolute residual floor of the CG solver. Default 0.0.

Once the outer iteration has converged, the linear right-hand side \(\mathbf{b} - \mathbf{A}\mathbf{x}\) sits at machine epsilon. With no absolute floor the CG target falls below round-off, so the solver runs to its iteration limit and returns noise. Setting set_absolute_tolerance(1e-12) is recommended when the model is run without regularization (add_regularization=False).

set_iteration_number¶

solver.set_iteration_number(iteration_number: int)

Maximum number of CG iterations per linear solve. If the solver fails to reach the requested tolerance within this many iterations, a warning is emitted and the results may be inaccurate. Default 250.

Nonlinear iteration controls¶

These settings shape the outer Newton update applied after each linear solve.

set_under_relaxation_factor¶

solver.set_under_relaxation_factor(under_relaxation_factor: float)

Damping applied to the Newton update. A value in \((0, 1]\); values below 1 add damping and can stabilise strongly nonlinear cases at the cost of more iterations. Default 1.0 (no damping). When the line search is active, it overrides this fixed factor on the iterations it covers.

set_frozen¶

solver.set_frozen(is_frozen: bool)

Freeze the model state. When True, solve() returns immediately without assembling or updating — the magnetic field is held fixed. This is useful in co-simulations where the magnetic solution should stay constant while another physics (e.g. a moving magnet) advances. Default False.

set_verbose¶

solver.set_verbose(verbose: bool)

Enable detailed per-iteration output from the linear solver. Default False.

Line search¶

For nonlinear problems the solver can pick the under-relaxation factor automatically with a Newton line search. It is inactive by default — the solver then simply applies the fixed under-relaxation factor at every outer iteration.

Obtain the controller from the solver:

line_search = solver.get_line_search()
line_search.set_active(True)

set_strategy¶

line_search.set_strategy(strategy: LineSearchStrategy)

Choose the extrapolation fit:

• LineSearchStrategy.TwoPointLinear (default) — two probes, linear fit; finds the energy minimum along the Newton ray.
• LineSearchStrategy.ThreePointQuadratic — adds the free \(g(0)\) anchor recovered from the just-solved Newton system, capturing one more anharmonic order at the same probe cost.
• LineSearchStrategy.ResidualMinimization — fits \(\|\mathbf{b}(\alpha)\|^2\) directly. Prefer this when the energy-minimum and residual-minimum branches diverge, as for stiff power-law constitutive laws (e.g. HTS conductors).

set_max_alpha¶

line_search.set_max_alpha(max_alpha: float)

Upper clamp on the extrapolated step \(\alpha\). Default 2.0. Set to 1.0 to forbid over-relaxation — recommended for stiff power-law laws (HTS) where stepping past the Newton prediction destabilises the iteration.

set_iteration_window¶

line_search.set_iteration_window(min_iter: int, max_iter: int)

Restrict the line search to outer iterations in [min_iter, max_iter] (1-indexed, inclusive). Off-window iterations fall back to the fixed under-relaxation factor.

set_residual_skip_threshold¶

line_search.set_residual_skip_threshold(threshold: float)

Skip the line search whenever the residual norm \(\|\mathbf{b}\|\) is below this threshold. Default 0.0 (never skip).

Examples¶

Robust nonlinear magnetostatics¶

Activate the line search over the first few iterations — a typical setup for a nonlinear \(B\)–\(H\) core (cf. the COMPUMAG TEAM 13 benchmark):

line_search = time_domain_magnetic_model.get_solver().get_line_search()
line_search.set_active(True)
line_search.set_iteration_window(min_iter=0, max_iter=6)

Stiff power-law conductor (HTS)¶

Forbid over-relaxation and minimise the residual directly:

solver = magnetic_model.get_solver()
solver.set_under_relaxation_factor(1.0)

line_search = solver.get_line_search()
line_search.set_active(True)
line_search.set_strategy(LineSearchStrategy.ThreePointQuadratic)
line_search.set_residual_skip_threshold(1.0e-10)
line_search.set_max_alpha(1.0)

Holding the magnetic field fixed¶

magnetic_solver = magnetic_model.get_solver()
magnetic_solver.set_frozen(True)