Solver Reference

Solver Reference

Every solver accepts a plain config dict and returns a results dict. Omitted keys fall back to the defaults listed here. All inputs use SI units unless the name says otherwise, so *_C keys are degrees Celsius and *_um micrometres.

Key names match the MATLAB reference toolbox one to one, which is why several naming styles coexist. Units are carried in the schema rather than in the key names.

This page is a snapshot. The package itself is the authority, and it can print the same information at any time:

laserttm describe depth_profile

from laserttm import describe_solver
describe_solver("depth_profile")["params"]["spotRadius"]

Keys shared by all solvers

Field	Default	Meaning
makePlots	True	draw diagnostic figures
saveFigures	False	write figures into the output folder, which also forces makePlots
outputDir	outputs under the working directory	where the text report and figures are written
caseTag	""	prefix for output filenames, for keeping a sweep's runs apart
showProgress	auto	show the progress window. Leave it unset to let the package decide, which keeps batch and server runs headless. False also silences the per-pulse console lines
verbose	True	print the banner, progress and summary. False keeps the solver silent
writeReport	True	write the text report. False writes nothing and returns outputFile as None
reportHistory	True	append the per-sample XY table to the report. False keeps the summary only, which matters on long history runs where the table is tens of megabytes
ablationThreshold	material preset	single-shot ablation threshold fluence in J/m^2 for the validity check. Tungsten's preset is 4400, the other presets carry none

The multi-pulse solvers also accept nPulses, which fires a chosen number of pulses and overrides the count derived from simDuration; simDuration then only sets where the last coast ends and defaults to nPulses / f_rep.

Returned keys shared by all solvers are solver, solverId, contractVersion, material, outputFile, outputDir, inputConfig, resolvedConfig, materialProps, warnings, diagnostics, Tmelt_C, meltDetected, meltPulse, pulseEnergy_J, peakFluence_J_m2, absorbedFluence_J_m2 and caseTag, plus nPulses and wallTime_s where meaningful. See Results and Outputs.

Material keys

Presets cover tungsten, copper, aluminum, and gold. Any single property can be overridden without leaving the preset, which is the usual way to study one parameter:

Field	Unit	Meaning
material		W, Cu, Al, Au, or custom
gamma, Cl, G, kl	see Model Background	override one preset property
ke0, alpha_opt, delta_opt		electron conductivity and optical absorption, depth-resolved solvers only
T_melt_C	degC	override the melting point used by the melt checks
kTable		auto, measured, or constant, choosing the conductivity model
gamma_manual, Cl_manual, G_manual, kl_manual, ke0_manual, alpha_opt_manual		properties used when material is custom

Gold carries only the lattice-family properties, so the depth-resolved solvers reject it rather than guess an electron conductivity split. laserttm materials prints the full table.

---

surface_point_solver

results = surface_point_solver(cfg)

0D surface-point TTM, and the fastest entry point for pulse-accumulation studies and parameter sweeps. It solves the coupled electron-lattice equations at the surface during each pulse, then runs 1D Crank-Nicolson diffusion into depth for the inter-pulse gap.

Reach for it when the surface temperature history matters and depth resolution does not. Reach for something else when you need temperature versus depth, the inversion resolved in space, or a radial or scanned geometry.

Field	Default	Unit	Meaning
Pavg	1	W	average laser power
spotRadius	80e-6	m	1/e^2 Gaussian spot radius
f_rep	1e6	Hz	repetition rate
tau_FWHM	500e-15	s	pulse duration, FWHM
pulseProfile	gaussian		gaussian, square, or exp. The exponential form is one sided, zero before the pulse and exp(-t/tau)/tau after it
simDuration	100e-6	s	simulated time. Without nPulses the pulse count is round(simDuration * f_rep)
nPulses	unset		number of pulses to fire, overriding the count from simDuration
absorbance	0.55		absorbed fraction of incident fluence
Leff	100e-9	m	effective deposition depth for the 0D energy balance
T0_C	25	degC	initial temperature
depthProfile	exponential		depth distribution of deposited energy, exponential or box
dzTarget	500e-9	m	diffusion grid spacing
Ndiff	100		Crank-Nicolson steps per inter-pulse period, a minimum. The solver raises it to hold the coast Fourier number at or below 0.5 and reports the count used as NdiffUsed

A bare call runs 100 pulses.

Key returned keys beyond the shared contract: full surface histories time_s, Te_K, Tl_K, Te_C, Tl_C, per-pulse arrays TeqVals_C, TresidVals_C, TePeakPerPulse_C and TlPeakPerPulse_C, the scalars peakTe_C, peakTl_C, peakPulse, finalResid_C, NdiffUsed, and energy bookkeeping in absorbedAreal_J_m2, depthEnergy_J_m2, energyMismatch_pct. During each inter-pulse coast the electrons are equilibrated with the lattice, so Te_C equals Tl_C there by construction.

---

depth_profile_solver

results = depth_profile_solver(cfg)

The main 1D depth-resolved multi-pulse solver. It solves the coupled electron-lattice equations along depth with a stiff BDF integrator during each pulse, then maps the end state onto a coarser, deeper grid and diffuses it with Crank-Nicolson for the inter-pulse gap. This is the solver that resolves the surface temperature inversion.

Field	Default	Unit	Meaning
Pavg	40	W	average laser power
spotRadius	100e-6	m	1/e^2 spot radius
f_rep	18e6	Hz	repetition rate
tau_FWHM	100e-15	s	pulse duration, FWHM
pulseProfile	gaussian		temporal pulse shape
simDuration	100e-6	s	simulated time. Without nPulses the pulse count is round(simDuration * f_rep)
nPulses	unset		number of pulses to fire, overriding the count from simDuration
absorbance	0.55		absorbed fraction of incident fluence
T0_C	25	degC	initial temperature
Lz	1000e-9	m	depth of the fine two-temperature grid
Nz	200		fine grid nodes. Keep dz at or below a third of the optical penetration depth
snapshotDelays	0 to 200 ps set	s	delays after the first pulse centre for depth snapshots. Each requested instant is returned exactly, so a dense list stays distinct
profileSnapshotPulses	unset		1-based pulses after which a residual depth profile is kept. Unset means at most 12 logarithmically spaced pulses ending at the last
enableRadialProfile	False		derive a radial surface view from the depth solution. On by default before 0.4.0
lateralDiffusionWarnRatio	0.1		lateral diffusion length over spot radius above which the radial view raises lateral_diffusion
Nr_radial	20		radial nodes of that derived view
rMax_factor	3		radial extent of that view, in spot radii. It does not affect the depth solution
dzTarget_diff	500e-9	m	coarse diffusion grid spacing
Ndiff	100		Crank-Nicolson steps per inter-pulse period, a minimum. The solver raises it to hold the coast Fourier number at or below 0.5 and reports the count used as NdiffUsed
relTol, absTol	1e-6, 0.1		stiff integrator tolerances, absTol in kelvin

A bare call runs 1,800 pulses.

Key returned keys: per-pulse arrays TePeakPerPulse_C, TlPeakPerPulse_C, TeqVals_C, TresidVals_C, baseTempPerPulse_C, inversion metrics invMaxPerPulse_K, tMaxInvPerPulse_s, tInvOnsetPerPulse_s, invDurationPerPulse_s, Te_atMaxInvPerPulse_C, Tl_atMaxInvPerPulse_C, the surface traces time_s, Te_C, Tl_C, the first-pulse depth snapshots zGrid_m, snapshotDelays_s, TeSnapshots_C, TlSnapshots_C, the residual depth profiles zGridDiff_m, profileSnapshotPulses, profileSnapshotTimes_s, profileSnapshots_C, NdiffUsed, and the resolved input set f_rep, Pavg, tau_FWHM, spotRadius, absorbance, F_peak, gamma, Cl, G, ke0, kl, alpha_opt, Trep, simDuration. The per-pulse inversion maximum is refined between samples by the parabola through the three samples around it, fitted in time relative to the middle sample; the absolute-time form inherited from MATLAB lost everything to cancellation late in a train and was replaced in 0.4.0.

With enableRadialProfile on, it also returns the radial view: radialGrid_um, radialFluenceRatio, radialSurfaceProfiles_C, crossSection_C, crossSections_C (the radius-by-depth map after each snapshot pulse), lateralDiffusionLength_m and lateralDiffusionRatio. These are computed whether or not figures are drawn.

---

radial_profile_solver

results = radial_profile_solver(cfg)

Radial surface-temperature solver under a Gaussian beam, with two modes:

• scale, the default and the faster of the two. One 0D solve at beam centre, scaled radially by the Gaussian fluence profile, then carried outward by a single survival factor. Valid while the spot radius is much larger than the lateral diffusion length.
• independent. A separate 0D solve at every radial node, roughly Nr times slower, capturing the nonlinear electron heat capacity response at each local fluence.

Field	Default	Unit	Meaning
Pavg	40	W	average laser power
spotRadius	100e-6	m	1/e^2 spot radius
f_rep	18e6	Hz	repetition rate
tau_FWHM	100e-15	s	pulse duration, FWHM
pulseProfile	gaussian		temporal pulse shape
simDuration	1e-3	s	simulated time
absorbance	0.55		absorbed fraction of incident fluence
Leff	100e-9	m	effective deposition depth
T0_C	25	degC	initial temperature
Nr	80		radial nodes from the beam axis outward
rMax_factor	5		radial extent, in spot radii
radialSolveMode	scale		scale or independent
earlyStopMeltRadius_um	0	um	stop once the melt radius reaches this value. 0 disables the check
earlyStopT_melt_C	the material's melting point	degC	melt temperature for that check
earlyStopCheckInterval	100		pulses between checks
storeHistory	True		keep the per-pulse time histories. See the note below
depthProfile, dzTarget, Ndiff	as the 0D solver		inter-pulse diffusion settings. Ndiff is a minimum here, raised as needed to keep the Fourier number at or below 0.5

A bare call runs 18,000 pulses, so this is a solver worth validating before launching.

Key returned keys: rGrid_um, finalRadialProfile_C, spotRadius_um, peakTeq_C, finalResid_C, and mode.

Long runs. Set storeHistory to False to drop the per-pulse time histories, which are needed only for the timeline figures. This bounds memory on accumulation studies past 100,000 pulses and leaves every physical result unchanged.

---

single_pulse_visualizer

results = single_pulse_visualizer(cfg)

One pulse of the 1D depth-resolved model, with spatial snapshots at chosen delays. Useful for inspecting early-time behaviour and for teaching figures. It accepts the same material and laser keys as the depth solver, with different defaults.

Field	Default	Unit	Meaning
Pavg	1	W	average laser power
spotRadius	80e-6	m	1/e^2 spot radius
f_rep	1e6	Hz	sets the pulse energy Pavg / f_rep only. This solver always runs exactly one pulse
tau_FWHM	100e-15	s	pulse duration, FWHM
Lz	1000e-9	m	simulation depth
Nz	200		spatial nodes
snapshotDelays	0 to 200 ps set	s	delays for the Te(z) and Tl(z) snapshots
relTol, absTol	1e-6, 0.1		stiff integrator tolerances

Key returned keys: peakTe_C, peakTl_C, finalTe_C, finalTl_C, invDetected, maxInv_C.

---

inversion_quantifier

results = inversion_quantifier(cfg)

A post-processing layer over the depth solver that quantifies the electron-lattice inversion across pulses: magnitude, onset time, duration, and how each trends against the accumulating base temperature. It accepts the same keys as depth_profile_solver, plus one:

Field	Default	Meaning
depthResults	none	a results dict from a previous depth run. When supplied, the depth solve is skipped

Key returned keys: summary statistics nInvPulses, meanInv_K, maxInv_K, minInv_K, stdInv_K, invSlope_KperPulse, corrBaseTempInv, meanInvFraction, per-pulse arrays invMaxPerPulse_K, TePeak_C, TlPeak_C, Tbase_C, Teq_C, Tresid_C, tMaxInv_s, tOnset_s, invDuration_s, Te_atMaxInv_C, Tl_atMaxInv_C, and the nested depthResults from the underlying run.

---

scanning_beam_solver

results = scanning_beam_solver(cfg)

Moving-beam surface model. It combines scanning kinematics with per-pulse heating and inter-pulse surface diffusion to build the 2D temperature footprint of a scanned line. For MATLAB parity it also accepts two optional positional arguments, scanning_beam_solver(cfg, output_dir, save_plots), though the config dict is the preferred form and carries the same settings.

Field	Default	Unit	Meaning
Pavg	40	W	average laser power
spotRadius	100e-6	m	1/e^2 spot radius
f_rep	18e6	Hz	repetition rate
tau_FWHM	100e-15	s	pulse duration, FWHM
v_scan	1	m/s	scan speed
scanLength	2e-3	m	scanned line length. Pulse count is scanLength * f_rep / v_scan
absorbance	0.55		absorbed fraction of incident fluence
Leff	100e-9	m	effective deposition depth
T0_C	25	degC	initial temperature
Nx, Ny	120, 60		surface grid resolution along and across the scan
xPad	3		padding beyond each end of the scan, in spot radii
yExtent	5		half-width across the scan, in spot radii
depthProfile, dzTarget, Ndiff	as the 0D solver		depth and diffusion controls. Ndiff is the exact count here, since the scanning coast is pinned by its fixtures
NadiPerGap	10		alternating-direction implicit steps per inter-pulse gap
mapSnapshotPulses	unset		1-based pulses after which the surface map is kept

A bare call runs 36,000 pulses and takes several minutes.

Key returned keys: Tpeak_map for the peak temperature reached at each surface point, Tsurf for the final surface field, peakT_history, all three in kelvin with Celsius twins Tpeak_map_C, Tsurf_C and peakT_history_C, the grids xGrid and yGrid (maps are indexed [y, x]), the beam position at every pulse in beamX_m, the kept maps mapSnapshotPulses, mapSnapshotTimes_s and TsurfSnapshots_C, pulseSpacing, dTeq_single, peakT_C and its cross-solver twin peakTl_C, and matPath for a MATLAB-compatible .mat snapshot written alongside the report.