Getting Started

Getting Started

Requirements

• Python 3.10 or newer, on any operating system those releases support.
• NumPy, SciPy, Numba, and Matplotlib, installed automatically with the package.

Install

For using the solvers:

pip install laserttm

For working on the code, clone the repository and install it in editable form with the development extras:

git clone https://github.com/dfieser/ultrafast-laser-ttm-py.git
cd ultrafast-laser-ttm-py
pip install -e ".[dev]"

Pin an exact version in production work, for example pip install laserttm==0.1.14, so a later release cannot change results underneath a study.

First run

Run the simplest baseline example from a clone:

python examples/run_surface_point.py

The script builds a config for tungsten at 10 W average power, 5 MHz repetition rate, 500 fs pulses, and a 100 um spot, then calls surface_point_solver. You will see per-pulse progress lines like:

Pulse 1/50: Te_peak=2650.7 K, Teq=567.5 K, Tresid=308.6 K  (504 fine + 50 diff steps)
...
Pulse 50/50: Te_peak=2696.5 K, Teq=696.3 K, Tresid=430.2 K  (503 fine + 50 diff steps)
Simulation wall time: 0.07 s

followed by a summary block with peak temperatures and the path of the text report written under outputs/.

Each progress line reports three temperatures per pulse:

• Te_peak, the peak electron temperature during the pulse
• Teq, the equilibrated temperature after the electron and lattice baths couple
• Tresid, the residual surface temperature after inter-pulse diffusion, which becomes the starting temperature of the next pulse

The gap between Tresid and the initial temperature is the heat accumulation the package is built to study.

The first solver call in a fresh environment takes longer while Numba compiles the kernels. Compiled kernels are cached on disk, so later runs start immediately.

The recommended progression

1. examples/run_surface_point.py, the fastest 0D pulse-accumulation case.
2. examples/run_depth_profile.py, the main 1D depth-resolved solver. It resolves electron and lattice temperatures through depth and captures the surface temperature inversion described in Model Background.
3. examples/run_radial_profile.py, radial temperature distribution under a Gaussian spot.
4. examples/run_scanning_beam.py, a moving-beam scan. This case simulates 36,000 pulses and takes several minutes.

Editing parameters

Each example builds a plain dict and passes it to a solver:

from laserttm import surface_point_solver

cfg = {
    "material": "W",
    "Pavg": 10,
    "spotRadius": 100e-6,
    "f_rep": 5e6,
    "tau_FWHM": 500e-15,
}
cfg["nPulses"] = 50
results = surface_point_solver(cfg)

Rules of thumb:

• All inputs use SI units, so metres, seconds, watts, and hertz. A 100 micron spot is spotRadius = 100e-6, not 100. Initial temperature T0_C is in degrees Celsius.
• Any key you omit falls back to the default listed in Solver Reference.
• Set nPulses for a chosen number of pulses. Without it the count is round(simDuration * f_rep), and a fractional last period is coasted but never fired.
• Set makePlots: False for scripted runs, and saveFigures: True to write figures to the output folder.
• Config keys are case sensitive. A misspelled key is rejected with a suggestion rather than ignored.

Checking a config before running it

Long runs are worth validating first. This takes milliseconds and never starts a solve:

from laserttm import validate_config

report = validate_config("radial_profile", cfg)
print(report["ok"], report["estimate"])
for problem in report["errors"]:
    print(problem["message"], problem["suggestion"])

It catches a key with the wrong case, a key belonging to a different solver, a value that looks like microns rather than metres, and a config far more expensive than intended. The command line equivalent is laserttm validate cfg.json or laserttm run cfg.json --dry-run.

Verifying your install

From a clone, run the test suite:

python -m pytest                        # fast suite, about a minute
python -m pytest -m "slow or not slow"  # including the 36,000-pulse baseline

The suite compares every solver against MATLAB golden fixtures. See Validation.

Next steps

• Field-by-field solver documentation in Solver Reference
• The physics and the two-stage numerical strategy in Model Background
• Interpreting the returned dicts and text reports in Results and Outputs
• Batch runs, scripting, and AI assistants in Command Line and MCP