spectral_galerkin_heat.core.parameters ====================================== .. py:module:: spectral_galerkin_heat.core.parameters .. autoapi-nested-parse:: Core parameters and SimulationContext definition. Classes ------- .. autoapisummary:: spectral_galerkin_heat.core.parameters.NumParams spectral_galerkin_heat.core.parameters.MaterialParams spectral_galerkin_heat.core.parameters.GeomParams spectral_galerkin_heat.core.parameters.LaserParams spectral_galerkin_heat.core.parameters.FineMeshParams spectral_galerkin_heat.core.parameters.SimulationContext Module Contents --------------- .. py:class:: NumParams Numerical parameters for the simulation: time stepping and grid resolution. :ivar dt: Time step size in seconds. :vartype dt: float :ivar nx: Number of spectral modes in the x direction. :vartype nx: int :ivar ny: Number of spectral modes in the y direction. :vartype ny: int :ivar nz: Number of spectral modes in the z direction. :vartype nz: int :ivar t_end: Total simulation duration in seconds, by default 0.0. The solver runs from t=0 to t=t_end with time step dt. :vartype t_end: float, optional :ivar update_interval: Wall-clock or simulation-time interval between logging/output updates in seconds, by default 1e-3. :vartype update_interval: float, optional :ivar save_all: If True, save the full temperature field at every time step; default False. :vartype save_all: bool, optional :ivar dtype: Floating-point precision for the solver arrays (``numpy.float32`` or ``numpy.float64``), by default ``numpy.float32``. Set via the ``simulation.dtype`` config key. :vartype dtype: type, optional :ivar max_picard_iter: 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. :vartype max_picard_iter: int, optional :ivar picard_tol: Relative convergence tolerance for the Picard loop. ``None`` (default) uses the solver default. Set via ``simulation.picard_tol``. :vartype picard_tol: float, optional :ivar picard_omega: Under-relaxation (mixing) factor for the Picard loop. ``None`` (default) uses the solver default. Set via ``simulation.picard_omega``. :vartype picard_omega: float, optional .. py:class:: 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. :ivar name: Material identifier (e.g., "316L", "Aluminum"). Used for logging and output, by default "Material". :vartype name: str, optional :ivar rho: Density in kg/m³. Determines heat capacity and latent heat effects. Typical range: 2700 (Al) to 8960 (Cu) kg/m³, by default 1.0. :vartype rho: float, optional :ivar k: 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. :vartype k: float, optional :ivar Cp: 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. :vartype Cp: float, optional :ivar L_f: 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. :vartype L_f: float, optional :ivar T_solidus: 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. :vartype T_solidus: float, optional :ivar T_liquidus: Liquidus temperature in Kelvin. Above this, material is fully liquid. by default 0.0. :vartype T_liquidus: float, optional :ivar Pa: Ambient (atmospheric) pressure in Pa. Used for evaporation calculations. Standard: 101325 Pa, by default 0. :vartype Pa: float, optional :ivar R_v: Specific gas constant of the vapor in J/(kg·K). For Ar or vapor phase. by default 0. :vartype R_v: float, optional :ivar T_boil: Boiling temperature in Kelvin. Above this, material evaporates. For 316L steel: ~3090 K, by default 0. :vartype T_boil: float, optional :ivar DeltaH_LV: Latent heat of vaporization in J/kg. Energy released during liquid→vapor transition. Typically 1–10 MJ/kg depending on material, by default 0. :vartype DeltaH_LV: float, optional :ivar T0: Initial/ambient temperature in Kelvin. All temperatures computed relative to T0 as reference. Typical: 293 K (room temperature), by default 0. :vartype T0: float, optional :ivar h_conv_top: 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. :vartype h_conv_top: float, optional :ivar h_conv_bottom: 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. :vartype h_conv_bottom: float, optional :ivar model: 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. :vartype model: MaterialModel, optional .. py:property:: diff :type: 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. :rtype: float .. py:class:: GeomParams Rectangular domain ``[0, Lx] × [0, Ly] × [0, Lz]`` with a uniform spectral grid. The geometry is stored as grouped ``(x, y, z)`` triples (:class:`Vec3`) rather than loose scalars, so e.g. the spacing is ``geom.d.x`` / ``geom.d`` (the whole triple) instead of ``geom.dx``. :ivar size: Domain extent ``(Lx, Ly, Lz)`` in metres. :vartype size: Vec3 :ivar n: Mesh counts ``(nx, ny, nz)``. :vartype n: Vec3 :ivar d: Grid spacing ``(dx, dy, dz) = size / n`` (computed in ``__post_init__``). :vartype d: Vec3 .. py:class:: LaserParams Laser source parameters. :ivar radius: Beam radius (meters). Typically 30–100 μm for additive manufacturing. :vartype radius: float :ivar absorptivity: Absorptivity coefficient (0–1, dimensionless). Fraction of incident power absorbed by material; rest is reflected. :vartype absorptivity: float :ivar power: Nominal/maximum laser power (watts), by default 0.0. Actual power may vary via :class:`LaserPath.get_state`. :vartype power: float, optional :ivar profile: Beam-profile name (``"gaussian"`` / ``"flat_top"`` / ``"super_gaussian"``) resolved to a :class:`spectral_galerkin_heat.core.laser.LaserProfile`, by default ``"gaussian"``. Set via the ``laser.profile`` config key. :vartype profile: str, optional :ivar r_x, r_y: 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``. :vartype r_x, r_y: float, optional :ivar super_gaussian_order: Super-Gaussian order ``n`` used when ``profile == "super_gaussian"`` (``2`` = Gaussian, large = flat-top), by default 2.0. Set via ``laser.super_gaussian_order``. :vartype super_gaussian_order: float, optional :ivar cell_integrated: 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``. :vartype cell_integrated: bool, optional .. py:property:: ref_area :type: float Reference area ``r_x · r_y`` (``r_b²`` for a circular beam). Used by :meth:`LaserProfile.peak_intensity` to enforce ``∬ q dA = A·P``. .. py:class:: 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. :ivar refinement: Per-axis cell-refinement factor of the fine mesh relative to the global spectral grid (fine spacing ``= geom.d / refinement``), by default 4. :vartype refinement: int :ivar box_size: 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)``. :vartype box_size: Vec3 .. py:class:: SimulationContext Complete simulation configuration: numerics, material, domain, laser, and I/O. :ivar num: Numerical parameters (time step, grid resolution, duration). :vartype num: NumParams :ivar mat: Material thermal and thermodynamic properties. :vartype mat: MaterialParams :ivar geom: Domain geometry and grid definition. :vartype geom: GeomParams :ivar laser: Laser beam parameters (radius, absorptivity, nominal power). :vartype laser: LaserParams :ivar laser_path: Laser trajectory and power evolution over time. :vartype laser_path: LaserPath :ivar io: I/O configuration (output intervals, visualization planes, etc.). :vartype io: dict :ivar backend: Compute backend ('cpu', 'gpu', or 'cpu_linear'), by default 'cpu'. :vartype backend: str, optional :ivar fine: Moving fine-mesh parameters: the refined, laser-following sub-box (refinement, box extents). Defaults to :class:`FineMeshParams` defaults. :vartype fine: FineMeshParams, optional .. py:method:: from_dict(cfg, config_dir = None) :classmethod: Parses a nested dictionary and instantiates a full `SimulationContext`. :param cfg: Parsed dictionary typically loaded from a YAML configuration file. Should contain keys like 'simulation', 'domain', 'material', 'laser', and 'io'. :type cfg: dict :param config_dir: Path to the directory containing the configuration file. Used to resolve relative paths for external assets like G-code files, by default None. :type config_dir: str, optional :returns: A populated simulation context ready to build and initialize a solver. :rtype: SimulationContext