spectral_galerkin_heat.core.parameters

Core parameters and SimulationContext definition.

Classes

`NumParams`	Numerical parameters for the simulation: time stepping and grid resolution.
`MaterialParams`	Material properties for the simulation.
`GeomParams`	Rectangular domain `[0, Lx] × [0, Ly] × [0, Lz]` with a uniform spectral grid.
`LaserParams`	Laser source parameters.
`FineMeshParams`	Refined, laser-following sub-box of the domain, for the latent-heat and
`SimulationContext`	Complete simulation configuration: numerics, material, domain, laser, and I/O.

Module Contents

class spectral_galerkin_heat.core.parameters.NumParams

Numerical parameters for the simulation: time stepping and grid resolution.

Variables:

dt (float) – Time step size in seconds.
nx (int) – Number of spectral modes in the x direction.
ny (int) – Number of spectral modes in the y direction.
nz (int) – Number of spectral modes in the z direction.
t_end (float, optional) – Total simulation duration in seconds, by default 0.0. The solver runs from t=0 to t=t_end with time step dt.
update_interval (float, optional) – Wall-clock or simulation-time interval between logging/output updates in seconds, by default 1e-3.
save_all (bool, optional) – If True, save the full temperature field at every time step; default False.
dtype (type, optional) – Floating-point precision for the solver arrays (numpy.float32 or numpy.float64), by default numpy.float32. Set via the simulation.dtype config key.
max_picard_iter (int, optional) – Cap on the spectral solver’s fixed-point (Picard) iterations per step. None (default) lets the solver use its built-in default. Set via the simulation.max_picard_iter config key.
picard_tol (float, optional) – Relative convergence tolerance for the Picard loop. None (default) uses the solver default. Set via simulation.picard_tol.
picard_omega (float, optional) – Under-relaxation (mixing) factor for the Picard loop. None (default) uses the solver default. Set via simulation.picard_omega.

class spectral_galerkin_heat.core.parameters.MaterialParams

Material properties for the simulation.

These properties define the thermal and thermodynamic behavior of the workpiece. All temperatures must be in Kelvin; all energies in joules per unit mass.

Variables:

name (str, optional) – Material identifier (e.g., “316L”, “Aluminum”). Used for logging and output, by default “Material”.
rho (float, optional) – Density in kg/m³. Determines heat capacity and latent heat effects. Typical range: 2700 (Al) to 8960 (Cu) kg/m³, by default 1.0.
k (float, optional) – Thermal conductivity in W/(m·K). Controls heat diffusion rate and cooling speed. Critical for predicting melt pool shape and solidification. Typical range: 15–429 W/(m·K), by default 1.0.
Cp (float, optional) – Specific heat capacity in J/(kg·K). Energy required to raise material temperature by 1 K. Typical range: 385–4180 J/(kg·K), by default 1.0.
L_f (float, optional) – Latent heat of fusion in J/kg. Energy released/absorbed during solid↔liquid phase transition (around melting point). Set to 0.0 for isothermal models, by default 0.0.
T_solidus (float, optional) – Solidus temperature in Kelvin. Below this, material is fully solid. Must be < T_liquidus. For single-phase analysis, set both to the melting point, by default 0.0.
T_liquidus (float, optional) – Liquidus temperature in Kelvin. Above this, material is fully liquid. by default 0.0.
Pa (float, optional) – Ambient (atmospheric) pressure in Pa. Used for evaporation calculations. Standard: 101325 Pa, by default 0.
R_v (float, optional) – Specific gas constant of the vapor in J/(kg·K). For Ar or vapor phase. by default 0.
T_boil (float, optional) – Boiling temperature in Kelvin. Above this, material evaporates. For 316L steel: ~3090 K, by default 0.
DeltaH_LV (float, optional) – Latent heat of vaporization in J/kg. Energy released during liquid→vapor transition. Typically 1–10 MJ/kg depending on material, by default 0.
T0 (float, optional) – Initial/ambient temperature in Kelvin. All temperatures computed relative to T0 as reference. Typical: 293 K (room temperature), by default 0.
h_conv_top (float, optional) – Convective heat transfer coefficient in W/(m²·K) at the top surface (z = Lz, the laser-facing face – same face as the laser flux and evaporation). 0.0 disables it. Typical: 50-5000 W/(m²·K), by default 0.0.
h_conv_bottom (float, optional) – Convective heat transfer coefficient in W/(m²·K) at the bottom surface (z = 0). 0.0 disables it. Typical: 50-5000 W/(m²·K), by default 0.0.
model (MaterialModel, optional) – Temperature-dependent property model (k(T), rho(T), c(T) solid/liquid branch expressions). None for a constant-property material, in which case the solver uses the scalar rho/k/Cp directly. When present, the scalar rho/k/Cp fields hold the user-supplied reference constants (each property’s in-block reference: key) used by the ETD1 propagators; the property-correction path reinstates the fluctuations about them.

property diff: float

Thermal diffusivity in m²/s.

Computed as k / (rho * Cp), this dimensionless group governs the rate of heat diffusion. Higher values → faster heat propagation. Controls the characteristic time scale for thermal evolution independent of domain size.

Returns:: Thermal diffusivity in m²/s.
Return type:: float

class spectral_galerkin_heat.core.parameters.GeomParams

Rectangular domain [0, Lx] × [0, Ly] × [0, Lz] with a uniform spectral grid.

The geometry is stored as grouped (x, y, z) triples (Vec3) rather than loose scalars, so e.g. the spacing is geom.d.x / geom.d (the whole triple) instead of geom.dx.

Variables:

size (Vec3) – Domain extent (Lx, Ly, Lz) in metres.
n (Vec3) – Mesh counts (nx, ny, nz).
d (Vec3) – Grid spacing (dx, dy, dz) = size / n (computed in __post_init__).

class spectral_galerkin_heat.core.parameters.LaserParams

Laser source parameters.

Variables:

radius (float) – Beam radius (meters). Typically 30–100 μm for additive manufacturing.
absorptivity (float) – Absorptivity coefficient (0–1, dimensionless). Fraction of incident power absorbed by material; rest is reflected.
power (float, optional) – Nominal/maximum laser power (watts), by default 0.0. Actual power may vary via LaserPath.get_state.
profile (str, optional) – Beam-profile name ("gaussian" / "flat_top" / "super_gaussian") resolved to a spectral_galerkin_heat.core.laser.LaserProfile, by default "gaussian". Set via the laser.profile config key.
r_y (r_x,) – Beam radii along x and y (metres). Default to radius (circular beam); set both for an elliptical beam. Set via laser.r_x / laser.r_y.
super_gaussian_order (float, optional) – Super-Gaussian order n used when profile == "super_gaussian" (2 = Gaussian, large = flat-top), by default 2.0. Set via laser.super_gaussian_order.
cell_integrated (bool, optional) – When True, the Gaussian flux is integrated analytically over each grid cell (exact power deposition even for a beam narrower than the grid) instead of being point-sampled at the cell centre. Gaussian only. Default False. Set via laser.cell_integrated.

property ref_area: float

Reference area r_x · r_y (r_b² for a circular beam).

Used by LaserProfile.peak_intensity() to enforce ∬ q dA = A·P.

Return type:: float

class spectral_galerkin_heat.core.parameters.FineMeshParams

Refined, laser-following sub-box of the domain, for the latent-heat and nonlinear terms.

The solver reconstructs temperature on a refined box that tracks the laser, to resolve the sharp mushy-zone gradients the coarse spectral grid cannot.

Variables:

refinement (int) – Per-axis cell-refinement factor of the fine mesh relative to the global spectral grid (fine spacing = geom.d / refinement), by default 4.
box_size (Vec3) – Extent of the refined, laser-following sub-box in metres (Lx_box, Ly_box, Lz_box): the x/y extents span the laser footprint, the z extent is the near-surface depth. By default Vec3(0.9e-3, 0.9e-3, 0.04e-3).

class spectral_galerkin_heat.core.parameters.SimulationContext

Complete simulation configuration: numerics, material, domain, laser, and I/O.

Variables:

num (NumParams) – Numerical parameters (time step, grid resolution, duration).
mat (MaterialParams) – Material thermal and thermodynamic properties.
geom (GeomParams) – Domain geometry and grid definition.
laser (LaserParams) – Laser beam parameters (radius, absorptivity, nominal power).
laser_path (LaserPath) – Laser trajectory and power evolution over time.
io (dict) – I/O configuration (output intervals, visualization planes, etc.).
backend (str, optional) – Compute backend (‘cpu’, ‘gpu’, or ‘cpu_linear’), by default ‘cpu’.
fine (FineMeshParams, optional) – Moving fine-mesh parameters: the refined, laser-following sub-box (refinement, box extents). Defaults to FineMeshParams defaults.

classmethod from_dict(cfg, config_dir=None)

Parses a nested dictionary and instantiates a full SimulationContext.

Parameters:

cfg (dict) – Parsed dictionary typically loaded from a YAML configuration file. Should contain keys like ‘simulation’, ‘domain’, ‘material’, ‘laser’, and ‘io’.
config_dir (str, optional) – Path to the directory containing the configuration file. Used to resolve relative paths for external assets like G-code files, by default None.

Returns:

A populated simulation context ready to build and initialize a solver.

Return type:

SimulationContext