spectral_galerkin_heat.core.properties
======================================

.. py:module:: spectral_galerkin_heat.core.properties

.. autoapi-nested-parse::

   Temperature-dependent material properties (expression branches + f_l blend).

   Each property ``k(T)``, ``rho(T)``, ``c(T)`` is described by a solid-branch and a
   liquid-branch expression of ``T`` blended pointwise by the liquid fraction ``f_l(T)``
   between the solidus and liquidus temperatures::

       p(T) = (1 - f_l) * p_solid(T) + f_l * p_liquid(T)

   This matches the reference 316L form used by the finite-element reference solver.
   The blended property is non-polynomial with slope kinks at ``T_S``/``T_L``; this
   never enters the spectral scheme, because the weak-form property correction
   samples ``k`` and ``a`` but never differentiates them in ``T``.

   A plain scalar is also accepted (both branches collapse to the constant), so
   existing constant-property configs keep working unchanged.



Classes
-------

.. autoapisummary::

   spectral_galerkin_heat.core.properties.TempProperty
   spectral_galerkin_heat.core.properties.MaterialModel


Functions
---------

.. autoapisummary::

   spectral_galerkin_heat.core.properties.liquid_fraction


Module Contents
---------------

.. py:function:: liquid_fraction(T, T_solidus, T_liquidus)

   Liquid fraction ``f_l(T)`` clamped to ``[0, 1]``.

   ``0`` below the solidus, ``1`` above the liquidus, linear in between. When
   ``T_liquidus <= T_solidus`` (no mushy band configured) the ramp degenerates
   to a step at ``T_solidus``.


.. py:class:: TempProperty

   A single temperature-dependent property with solid/liquid branch expressions.

   :ivar solid, liquid: Math expression of ``T`` for each phase (see
                        :class:`spectral_galerkin_heat.core.property_expr.PropertyExpr`).
   :vartype solid, liquid: PropertyExpr
   :ivar T_solidus, T_liquidus: Mushy-band limits used to blend parameters via :func:`liquid_fraction`.
   :vartype T_solidus, T_liquidus: float
   :ivar is_constant: True when both branches are the same single constant, which lets the
                      solver take the constant-coefficient fast path.

   :vartype is_constant: bool


   .. py:method:: from_config(spec, T_solidus, T_liquidus)
      :classmethod:


      Build a :class:`TempProperty` from a config value.

      Accepts:

      - a plain number, or a ``{value, unit}`` mapping → constant property;
      - a ``{solid: "<expr of T>", liquid: "<expr of T>"}`` mapping → branch
        expressions (a missing branch falls back to the other).

      A branch mapping may also carry ``reference:`` (the constant k̄/ρ̄/C̄p,
      read by the material parser) and ``unit:``. Both are ignored here.



.. py:class:: MaterialModel

   Aggregate of the temperature-dependent thermophysical properties.

   Bundles ``k(T)``, ``rho(T)``, ``c(T)`` and the derived volumetric sensible
   heat capacity ``a(T) = rho(T) * c(T)``. Used by the property-correction path
   of the spectral solver; ``None`` on a material with only scalar properties.


   .. py:method:: a(T)

      Volumetric sensible heat capacity ``a(T) = rho(T) * c(T)``.



   .. py:method:: k_prime_a_prime(T, k_bar, a_bar)

      Fluctuations ``(k(T) - k_bar, a(T) - a_bar)`` in a single fused pass.




   .. py:method:: latent_heat_source(T, T_prev, T_S, T_L, L_f, dt, out)

      Latent-heat sink ``Q = -rho(T) L_f (f_l(T)-f_l(T_prev))/dt`` into *out*.




   .. py:property:: is_constant
      :type: bool


      True when every property is a single constant (null-correction path).


   .. py:method:: recommended_references(T_lo, T_hi, n_samples = 512)

      Recommended reference scalars over the working band ``[T_lo, T_hi]``.

      The user supplies each T-dependent property's reference constant
      explicitly, as a ``reference:`` key inside its config block. This helper
      only computes a recommendation for each: the midpoint of the property's
      own extrema sampled across the range, ``½(min p + max p)``. Centering every
      reference in the middle of its working range reduces the peak fluctuations
      and helps convergence.

      Returns the recommended ``(k, rho, Cp)`` references.



   .. py:method:: from_config(mat_cfg, T_solidus, T_liquidus)
      :classmethod:


      Build a :class:`MaterialModel` from the ``material`` config section.

      Returns ``None`` when none of ``k``, ``rho``, ``Cp`` is given as
      solid/liquid branch expressions, i.e. the material is fully constant.
      The solver then keeps its existing constant-coefficient path.