Numerical Algorithms & Routines

This page summarizes the high-level routines used in a typical time step.

1. Build solver state

• Construct a problem (StefanMonoProblem or StefanDiphProblem) from grid, geometry, thermal parameters, and options.
• Create an initial state and linear solver cache using build_solver.

1. Advance one step (step!)

• Recompute cut-cell geometry and capacities from the current interface representation.
• Assemble diffusion operators for active cells/phases.
• Solve the diffusion subproblem(s) using PenguinDiffusion.jl/PenguinSolverCore.jl.
• Compute interface normal speed from Stefan flux balance.
• Advect/update interface representation and refresh diagnostics.

1. Time integration (solve!)

• Iterate step! over the requested tspan.
• Optionally collect history for post-processing and convergence studies.

Validation helpers

• neumann_1d_similarity, manufactured_planar_1d, and frank_disk_exact provide exact/benchmark fields.
• temperature_error_norms, stefan_residual_metrics, and fit_order quantify accuracy and order.

GlobalHFRep coupled iteration

For GlobalHFRep, the solver runs a coupled nonlinear iteration over graph heights/positions:

1. Build/predict graph geometry (xf) and reconstruct predicted phi.
2. Solve moving diffusion on the predicted geometry.
3. Compute Stefan residual from swept-volume change and interfacial flux.
4. Update graph heights/positions with damping.
5. Reconstruct phi from updated xf.
6. Repeat until coupling_tol / coupling_reltol or coupling_max_iter.

Residual and iteration diagnostics are logged and available through stefan_coupling_history.

LevelSetRep nonlinear iteration

For LevelSetRep, explicit stepping is the default mode, and :ls_newton activates a nonlinear inner iteration on the Stefan residual:

1. Predict phi from previous speed.
2. Solve diffusion and evaluate interface flux residual.
3. Apply a diagonal speed correction iterate.
4. Accept converged iterate and update state.

Use coupling_mode(rep) to determine which coupling route is active.

FrontTracking least-squares coupling (:ft_lm)

For FrontTrackingRep in 2D closed-curve mode, coupling=:ft_lm runs a least-squares correction loop on top of the explicit predictor:

1. Build predictor front/phi from previous speed.
2. Solve moving diffusion on predictor geometry and evaluate Stefan residual.
3. Build a geometric-only Jacobian (finite differences of phase volumes with frozen predictor normals).
4. Solve an LM correction for front-normal displacements.
5. Accept/reject by objective decrease and iterate.
6. Commit final front once, then recompute Stefan speed from accepted thermal state.

Main option knobs:

• ft_lm_lambda0, ft_lm_lambda_factor, ft_lm_lambda_min, ft_lm_lambda_max
• ft_lm_step_clip, ft_lm_step_tol, ft_lm_fd_eps
• ft_lm_reg_curv, ft_lm_reg_mass
• ft_lm_accept_relax, ft_lm_max_reject
• ft_lm_weight_by_volume, ft_lm_jac_refresh
• plus global coupling controls coupling_max_iter, coupling_tol, coupling_reltol.

Per-step diagnostics in solver.state.logs:

• :ft_ls_predictor_resnorm, :ft_ls_final_resnorm
• :ft_ls_predictor_objective, :ft_ls_final_objective
• :ft_ls_status_last, :ft_ls_iters_last, :ft_ls_accepts_last, :ft_ls_rejects_last, :ft_ls_lambda_last

These diagnostics are defined for each outer time step [t_n, t_{n+1}].