API Reference

Top-level API

compute_melt_pool(data: pd.DataFrame, *, domain: SimulationDomain | None = None, chunk_size: int = 50, workers: int | None = None, output_dir: Path | str | None = None, return_field: bool = True) -> pd.DataFrame

Compute melt pool dimensions for every row in a DataFrame.

Parameters are processed in chunks; each chunk can be dispatched to a separate process for parallelism. Results are appended as new columns to a copy of data and returned.

Parameters:

Name	Type	Description	Default
data	DataFrame	Input DataFrame. Must contain the columns listed in REQUIRED_COLUMNS.	required
domain	SimulationDomain | None	Custom simulation domain. If None, the default 1200 x 1200 x 1000 um domain is used for every row.	None
chunk_size	int	Number of rows per chunk. Larger values reduce multiprocessing overhead at the cost of coarser progress. Defaults to 50.	50
workers	int | None	Worker processes to use. 1 or None runs serially; -1 uses all available cores.	None
output_dir	Path | str | None	If provided, each processed chunk is saved as a CSV file under this directory before results are concatenated.	None
return_field	bool	When True, a temperature_field column is added to the output DataFrame containing the TemperatureField for each row (None for rows that failed).	True

Returns:

Type	Description
DataFrame	A new DataFrame identical to data plus the output columns:
DataFrame	melt_length, melt_width, melt_depth (m),
DataFrame	melt_length_um, melt_width_um, melt_depth_um (um),
DataFrame	peak_temperature, min_temperature (K), and optionally
DataFrame	temperature_field when return_field=True.

Raises:

Type	Description
TypeError	If data is not a pandas DataFrame.
ValueError	If any required column is absent from data.
ValueError	If workers is not a positive integer, -1, or None.

Examples:

import pandas as pd
from eagar_tsai import compute_melt_pool

df = pd.DataFrame({
    "velocity_m_s": [0.5],
    "power_w": [200.0],
    "beam_diameter_m": [100e-6],
    "absorptivity": [0.35],
    "liquidus_temperature_k": [1700.0],
    "thermal_conductivity_w_mk": [30.0],
    "density_kg_m3": [7800.0],
    "specific_heat_j_kgk": [700.0],
})
result = compute_melt_pool(df, workers=1)

compute_single_point(beam: BeamParameters, material: MaterialProperties, domain: SimulationDomain | None = None) -> MeltPoolResult

Compute melt pool dimensions for a single set of process parameters.

The temperature field is evaluated on the x-y (z=0) and x-z (y=0) planes. Melt pool extents are extracted from the liquidus isotherm. If the melt pool touches a domain boundary the domain is expanded iteratively (up to _MAX_EXPANSION_ITERS times) and the computation is repeated on the enlarged grid.

Parameters:

Name	Type	Description	Default
beam	BeamParameters	Laser beam and process parameters.	required
material	MaterialProperties	Material thermal properties.	required
domain	SimulationDomain | None	Spatial domain; defaults to 1200 x 1200 x 1000 um, 1 um.	None

Returns:

Type	Description
MeltPoolResult	A MeltPoolResult containing melt pool dimensions, temperature
MeltPoolResult	extremes, and the full TemperatureField. All lengths are zero
MeltPoolResult	if the peak temperature does not exceed the liquidus temperature.

Raises:

Type	Description
RuntimeError	If domain expansion does not converge within _MAX_EXPANSION_ITERS iterations.

Data Classes

BeamParameters(beam_diameter: float, power: float, velocity: float, absorptivity: float) dataclass

Laser beam and process parameters.

Attributes:

Name	Type	Description
beam_diameter	float	Beam diameter (2*sigma) in metres.
power	float	Laser power in Watts.
velocity	float	Scan velocity in m/s.
absorptivity	float	Absorptivity (dimensionless, must be in (0, 1]).
sigma	float	Derived Gaussian width parameter sqrt(2) * (beam_diameter / 2).

__post_init__() -> None

Validate physical constraints and compute derived sigma.

MaterialProperties(liquidus_temperature: float, thermal_conductivity: float, density: float, specific_heat: float) dataclass

Material thermal properties evaluated at the liquidus temperature.

Attributes:

Name	Type	Description
liquidus_temperature	float	Liquidus temperature in Kelvin.
thermal_conductivity	float	Thermal conductivity in W/(m K).
density	float	Density in kg/m^3.
specific_heat	float	Specific heat capacity in J/(kg K).

thermal_diffusivity: float property

Thermal diffusivity alpha = k / (rho * cp) in m^2/s.

__post_init__() -> None

Validate physical constraints.

SimulationDomain(x_length_um: float = 1200.0, y_length_um: float = 1200.0, z_depth_um: float = 1000.0, spatial_resolution_um: float = 1.0) dataclass

Spatial domain for numerical temperature field evaluation.

All _um attributes are in micrometres; corresponding properties (without the suffix) return the equivalent value in metres.

Attributes:

Name	Type	Description
x_length_um	float	Domain length along x (scan direction) in um.
y_length_um	float	Domain half-width along y in um.
z_depth_um	float	Domain depth along z in um.
spatial_resolution_um	float	Grid spacing in um.

spatial_resolution: float property

Grid spacing in metres.

x_length: float property

Domain length along x in metres.

y_length: float property

Domain half-width along y in metres.

z_depth: float property

Domain depth along z in metres.

__post_init__() -> None

Validate that all domain dimensions and resolution are positive.

expanded(*, dx_um: float = 0.0, dy_um: float = 0.0, dz_um: float = 0.0) -> SimulationDomain

Return a new domain with expanded dimensions.

Parameters:

Name	Type	Description	Default
dx_um	float	Additional length along x in um.	0.0
dy_um	float	Additional half-width along y in um.	0.0
dz_um	float	Additional depth along z in um.	0.0

Returns:

Type	Description
SimulationDomain	A new SimulationDomain with the specified expansions added.

MeltPoolResult(length: float, width: float, depth: float, peak_temperature: float, min_temperature: float, temperature_field: TemperatureField) dataclass

Melt pool geometry, temperature extremes, and associated temperature field.

Attributes:

Name	Type	Description
length	float	Melt pool length along x in metres.
width	float	Melt pool full width along y in metres.
depth	float	Melt pool depth along z in metres.
peak_temperature	float	Maximum temperature in the domain in Kelvin.
min_temperature	float	Minimum temperature in the domain in Kelvin.
temperature_field	TemperatureField	Full 2-D temperature field for the x-y and x-z planes.

depth_um: float property

Melt pool depth in micrometres.

length_um: float property

Melt pool length in micrometres.

width_um: float property

Melt pool full width in micrometres.

plot(*, output: str | None = None, annotate: bool = True) -> matplotlib.figure.Figure

Render a two-panel temperature field figure (x-y surface and x-z depth cross-section).

Delegates to self.temperature_field.plot().

Parameters:

Name	Type	Description	Default
output	str | None	File path to save the figure. When None the figure is returned without saving.	None
annotate	bool	When True, overlay width and depth annotations.	True

Returns:

Type	Description
Figure	A matplotlib.figure.Figure.

Raises:

Type	Description
ImportError	If matplotlib is not installed.

TemperatureField(T_xy: np.ndarray, T_xz: np.ndarray, x_range_m: np.ndarray, y_range_m: np.ndarray, z_range_m: np.ndarray, liquidus_temperature_k: float, melt_width_m: float = 0.0, melt_depth_m: float = 0.0) dataclass

Full 2-D temperature field associated with a MeltPoolResult.

Attributes:

Name	Type	Description
T_xy	ndarray	Temperature on the x-y plane (z=0, surface). Shape (ny, nx), Kelvin.
T_xz	ndarray	Temperature on the x-z plane (y=0, centerline). Shape (nz, nx), Kelvin.
x_range_m	ndarray	1-D x-coordinate array in metres (scan direction).
y_range_m	ndarray	1-D y-coordinate array in metres (cross-scan, half-domain).
z_range_m	ndarray	1-D z-coordinate array in metres (negative values = depth below surface).
liquidus_temperature_k	float	Liquidus temperature in Kelvin, used for contour plots.
melt_width_m	float	Melt pool full width in metres, used for width annotation in plots.
melt_depth_m	float	Melt pool depth in metres, used for depth annotation in plots.

x_range_um: np.ndarray property

x-coordinate array in micrometres.

y_range_um: np.ndarray property

y-coordinate array in micrometres.

z_range_um: np.ndarray property

z-coordinate array in micrometres (negative values = depth below surface).

plot(*, output: str | None = None, annotate: bool = True) -> matplotlib.figure.Figure

Render a two-panel temperature field figure (x-y surface and x-z depth cross-section).

Parameters:

Name	Type	Description	Default
output	str | None	File path to save the figure. When None the figure is returned without saving.	None
annotate	bool	When True, overlay width and depth annotations derived from melt_width_m and melt_depth_m.	True

Returns:

Type	Description
Figure	A matplotlib.figure.Figure.

Raises:

Type	Description
ImportError	If matplotlib is not installed.

Plotting

plot_temperature_field(beam: BeamParameters, material: MaterialProperties, domain: SimulationDomain | None = None, *, output: str | Path | None = None, annotate: bool = True) -> matplotlib.figure.Figure

Compute and render the x-y surface and x-z depth temperature planes.

Internally calls compute_single_point and passes the temperature field to _render_temperature_panels. Use this function when you only need the figure. If you also want access to the raw temperature arrays or melt pool summary, call compute_single_point directly and then call result.plot() or result.temperature_field.plot().

Parameters:

Name	Type	Description	Default
beam	BeamParameters	Laser beam and process parameters.	required
material	MaterialProperties	Material thermal properties.	required
domain	SimulationDomain | None	Spatial domain. Defaults to SimulationDomain(1200, 1200, 1000, 1) um.	None
output	str | Path | None	File path to save the figure (e.g. "field.png"). Supports any format recognized by matplotlib.figure.Figure.savefig. When None the figure is returned without saving.	None
annotate	bool	When True (default), overlay width and depth annotations on the respective panels.	True

Returns:

Type	Description
Figure	A matplotlib.figure.Figure containing two panels: the x-y surface
Figure	heatmap (top) and the x-z depth cross-section (bottom).

Integrand

eagar_tsai_integrand(t: float, x: float, y: float, z: float, p: float) -> float

Evaluate the Eagar-Tsai integrand at a single point.

This function has the signature expected by scipy.integrate.quad when passed via the args keyword: quad(f, 0, inf, args=(x, y, z, p)).

Parameters:

Name	Type	Description	Default
t	float	Integration variable (dimensionless time), must be > 0.	required
x	float	Non-dimensional x-coordinate (scan direction).	required
y	float	Non-dimensional y-coordinate (cross-scan direction).	required
z	float	Non-dimensional z-coordinate (depth, via sqrt(alpha * sigma / v)).	required
p	float	Non-dimensional parameter alpha / (v * sigma).	required

Returns:

Type	Description
float	Integrand value at the given point.