FAQ

FAQ

Setup

What do I need to install? pip install laserttm on Python 3.10 or newer. NumPy, SciPy, Numba, and Matplotlib come with it. The MCP server needs the optional extra, pip install "laserttm[mcp]".

The first run is slow, then later runs are fast. That is Numba compiling the kernels on first use. The compiled result is cached on disk, so the cost is paid once per environment.

Does it work on Linux and macOS? Yes. Nothing is platform specific, and paths are constructed portably.

How do I pin a version for a study? pip install laserttm==0.1.14, choosing whichever version you validated against. Releases are published automatically, so an unpinned install can move under you between runs.

Running simulations

How do I set the number of pulses? Set nPulses. Without it the count is round(simDuration * f_rep) and a fractional last period is coasted but never fired, which validate_config points out. With nPulses set, simDuration only decides where the last coast ends. The scanning solver derives its count from scanLength * f_rep / v_scan.

Which solver should I start with? surface_point_solver for accumulation trends and sweeps, since it is the fastest. depth_profile_solver when depth resolution or the temperature inversion matters. radial_profile_solver for melt-radius and footprint questions. scanning_beam_solver for a moving beam. laserttm list prints the same guidance with a minimal config for each.

How do I run without figure windows? Set makePlots to False. Add saveFigures: True if you still want figure files written. The command line and the MCP server already default to no figures.

A run is too slow. What should I relax? For the depth solvers, reduce simDuration, Nz, or Ndiff. For the radial solver, keep radialSolveMode at scale and use a moderate Nr, since independent costs roughly Nr times more. For the scanning solver, shorten scanLength, lower f_rep, or raise v_scan. Run laserttm run cfg.json --dry-run first to see the pulse count and a rough runtime before committing to it.

A long run is using too much memory, or its report is huge. The surface-point, depth and radial solvers accept storeHistory: False, which drops the per-pulse time histories kept only for the timeline figures. Physical results are unchanged. To keep the history in the results but out of the text report, set reportHistory: False; the XY table is tens of megabytes for a few thousand pulses and takes longer to write than the solve. writeReport: False writes no report at all.

What do the warnings mean? above_melting says the peak lattice temperature passed the melting point and above_ablation says the peak fluence passed the material's single-shot ablation threshold. The model has no phase change or ablation, so a run past either limit describes deposited energy rather than the material. Every solver also returns meltDetected and meltPulse. coast_steps_raised is informational: Ndiff was raised to keep the inter-pulse diffusion converged, and the count used is in NdiffUsed.

Why does the surface temperature 10 ns after a pulse depend on the repetition rate? It no longer does. Before 0.4.0 the coast used a fixed 100 steps per period, so at 1 MHz each step was 10 ns and the first samples after a pulse were under-resolved. Ndiff is now a floor, raised to hold the Fourier number at 0.5; the end-of-period residual was never affected.

Why was my config rejected when the value looks fine? All inputs are SI. A 100 micron spot is spotRadius = 100e-6, not 100. Key names are case sensitive, so pavg is not Pavg. Both cases are reported with the correction named, because both used to pass silently and produce a plausible but wrong run.

Physics and interpretation

Why do the electron and lattice temperatures converge after a few picoseconds? Electron-phonon coupling drives the two baths to a common temperature with a time constant on the order of Ce/G, a few hundred femtoseconds for tungsten at room temperature. After that, ordinary heat conduction takes over, which is exactly where the solver switches to its diffusion stage.

Why does the 0D solver not show the temperature inversion? The inversion is created by electron heat transport into the bulk, which needs spatial resolution. Use depth_profile_solver or single_pulse_visualizer. See Model Background.

The predicted temperature exceeds the melting point. Is that meaningful? Read it as "this parameter set melts the surface", not as a melt simulation. The model carries no latent heat and no melt-pool physics. The radial solver's earlyStopMeltRadius_um exists for exactly this use.

What is the difference between Leff and delta_opt? Leff is a lumped effective deposition thickness used by the 0D energy balance, and it defaults to 100 nm. delta_opt is the optical penetration depth used by the depth-resolved solvers, 17 nm for tungsten, and its reciprocal is alpha_opt. They are different quantities. Each solver accepts only the one that applies to it, so passing the wrong one is reported rather than silently ignored.

How do I model a metal with no preset? Set material to custom and supply the manual property keys. To change a single property of an existing preset instead, pass that property directly, for example {"material": "W", "delta_opt": 23e-9}. See Model Background for the shape of the data you need.

What absorbance should I use? absorbance is the fraction of incident fluence absorbed at the surface. The default 0.55 fits tungsten near 1030 nm at normal incidence. It depends on wavelength, angle, temperature, and surface condition, so treat it as an input you own rather than a constant.

Why does supplying my own conductivity change the tungsten results more than expected? Tungsten normally uses a measured temperature-dependent conductivity curve, running from 174.9 W/mK at 293 K down to 95.0 at 2500 K. Supplying a conductivity replaces that curve with your constant value, because the curve would otherwise ignore what you asked for. Set kTable to measured or constant to control that explicitly.

Outputs

Where do results go? Under outputs/ in the working directory, overridable with outputDir. Generated results stay out of version control. See Results and Outputs.

How do I keep a sweep's output files apart? Set caseTag, which prefixes the filenames.

How do I verify my install? From a clone, run python -m pytest. It compares every solver against the MATLAB golden fixtures. See Validation.

Contributing and citing

I found a bug or want to add something. See CONTRIBUTING.md in the repository. Small focused changes that preserve solver behaviour are the easiest to review. Solver numerics are pinned to the MATLAB fixtures, so a change that moves results needs a physical justification.

How do I cite this? See Citing. Cite the journal article, and the Zenodo software DOI when you need to pin an exact code version.