pyroll-phase-transformation-model 3.1.0__py3-none-any.whl

pyroll/phase_transformation_model/__init__.py

@@ -0,0 +1,43 @@
+VERSION = "3.1.0"
+
+from . import profile  # noqa: F401  (registers profile hooks)
+from . import microstructure  # noqa: F401  (registers result hooks)
+
+from .sigmoidal_functions import S, I
+from .phase_transformations import (
+    Martensite,
+    Bainite,
+    Ferrite,
+    Perlite,
+    DiffusionalPhaseTransformation,
+)
+from .transformation import (
+    PhaseTransformationSolver,
+    vickers_hardness_martensite,
+    vickers_hardness_bainite,
+    vickers_hardness_ferrite_perlite,
+    tensile_strength_from_hardness,
+    elongation_a50,
+    reduction_of_area,
+    impact_energy_ku,
+)
+from .microstructure import Config
+
+__all__ = [
+    "S",
+    "I",
+    "Martensite",
+    "Bainite",
+    "Ferrite",
+    "Perlite",
+    "DiffusionalPhaseTransformation",
+    "PhaseTransformationSolver",
+    "vickers_hardness_martensite",
+    "vickers_hardness_bainite",
+    "vickers_hardness_ferrite_perlite",
+    "tensile_strength_from_hardness",
+    "elongation_a50",
+    "reduction_of_area",
+    "impact_energy_ku",
+    "Config",
+]

pyroll/phase_transformation_model/microstructure.py

@@ -0,0 +1,275 @@
+"""Integration of the phase-transformation model into the PyRoll hook system.
+
+The standalone :class:`~.transformation.PhaseTransformationSolver` works on a
+thermal cycle ``T(t)``. Inside a PyRoll process that cycle is not given
+explicitly; it has to be reconstructed from the solved unit tree. As the bar
+flows through the sequence, every unit's out-profile carries the accumulated
+time :pyattr:`~pyroll.core.Profile.t` and its :pyattr:`temperature`. Cooling
+units (:class:`~pyroll.core.Transport`, :class:`~pyroll.core.CoolingPipe`,
+:class:`~pyroll.core.Spooler`) are :class:`~pyroll.core.DiskElementUnit`\\ s, so
+their disk elements provide the fine-grained ``(t, T)`` samples that resolve the
+cooling rates the kinetics depend on.
+
+This module walks that tree, assembles the thermal history up to and including
+any out-profile, and exposes the resulting microstructure as profile hooks:
+
+* :pyattr:`microstructure_composition` – bulk phase fractions (core hook).
+* :pyattr:`ring_microstructure_compositions` – per-ring phase fractions, using
+  the ``ring_temperatures`` of :mod:`pyroll.ring_model_thermal`.
+* :pyattr:`vickers_hardness` – overall Maynier hardness (core hook).
+* :pyattr:`mechanical_properties` – tensile strength, elongation, etc.
+* :pyattr:`thermal_history` / :pyattr:`ring_thermal_histories` – the
+  reconstructed ``T(t)`` cycles, mainly for inspection.
+
+All result hooks are **lazy**: they are computed (and cached) only when accessed,
+e.g. ``sequence[i].out_profile.microstructure_composition``. They are
+intentionally not registered as root hooks, because root hooks are re-evaluated
+on every convergence iteration of every unit, which would make the per-step
+solver prohibitively expensive. To have them appear in reports, add the desired
+hook to ``pyroll.core.root_hooks`` in your own configuration.
+"""
+
+import numpy as np
+import pandas as pd
+
+from pyroll.core import Unit, Hook, config
+
+from .transformation import PhaseTransformationSolver
+
+#: Phase columns produced by the solver, in report order.
+_PHASES = ("ferrite", "perlite", "bainite", "martensite", "austenite")
+
+#: Key under which the computed solver frame is cached on a profile instance.
+_FRAME_CACHE = "_ptm_frame"
+
+
+@config("PYROLL_PHASE_TRANSFORMATION_MODEL")
+class Config:
+    THERMAL_HISTORY_SAMPLES = 1000
+    """Number of uniform time samples the thermal history is resampled to
+    before it is handed to the kinetics solver. The solver assumes a uniform
+    time grid, while the reconstructed history is non-uniform; this is the grid
+    it is interpolated onto. Higher values are more accurate but slower."""
+
+
+@Unit.OutProfile.extension_class
+class PhaseTransformationOutProfile(Unit.OutProfile):
+    """Result hooks added to every unit out-profile."""
+
+    thermal_history = Hook[dict]()
+    """The reconstructed scalar thermal cycle up to this profile as a dict with
+    the keys ``t`` (time in s) and ``T`` (temperature in K), each a 1-D array."""
+
+    ring_thermal_histories = Hook[np.ndarray]()
+    """The reconstructed per-ring thermal cycles up to this profile as a 2-D
+    array of shape ``(n_samples, n_rings)`` aligned with
+    :pyattr:`~pyroll.ring_model.RingProfile.rings`. Available only if ring
+    temperatures are present (``pyroll-ring-model-thermal`` in use)."""
+
+    ring_microstructure_compositions = Hook[np.ndarray]()
+    """Per-ring phase composition: an object array of ``{phase: fraction}``
+    dicts, one per ring from core to surface. Available only if ring
+    temperatures are present."""
+
+    mechanical_properties = Hook[dict]()
+    """Estimated mechanical properties derived from the final microstructure
+    (``HV``, ``ym``, ``Rm``, ``A50``, ``Z``, ``KU``)."""
+
+
+# ---------------------------------------------------------------------------
+# Thermal-history reconstruction (plain helpers, return None when unavailable)
+# ---------------------------------------------------------------------------
+
+def _root_unit(unit: Unit) -> Unit:
+    """Climb to the outermost unit (typically the :class:`PassSequence`)."""
+    while unit.parent is not None:
+        unit = unit.parent
+    return unit
+
+
+def _leaf_out_profiles(unit: Unit):
+    """Yield the out-profiles of all leaf units in solution order.
+
+    Cooling units are subdivided into disk elements; those disks are the leaves
+    and provide the fine ``(t, T)`` resolution. Units without subunits (e.g.
+    roll passes) contribute their own out-profile.
+    """
+    subunits = unit.subunits
+    if subunits:
+        for sub in subunits:
+            yield from _leaf_out_profiles(sub)
+    elif unit.out_profile is not None:
+        yield unit.out_profile
+
+
+def _ring_temperatures(profile):
+    if profile.has_set_or_cached("ring_temperatures"):
+        value = profile.ring_temperatures
+        if value is not None:
+            return np.asarray(value, dtype=float)
+    return None
+
+
+def _collect_history(target):
+    """Collect ``(t, temperature, ring_temperatures)`` samples up to ``target``.
+
+    Returns a list of ``(t, T, ring_T_or_None)`` tuples ordered by time,
+    starting from the first in-profile of the sequence and ending at ``target``.
+    Profiles later than ``target`` (downstream, or not yet solved) are excluded
+    via the ``t`` filter.
+    """
+    root = _root_unit(target.unit)
+    t_target = target.t
+
+    samples = []
+
+    start = root.in_profile
+    if start is not None and start.has_value("t") and start.has_value("temperature"):
+        samples.append((float(start.t), float(start.temperature), _ring_temperatures(start)))
+
+    for profile in _leaf_out_profiles(root):
+        if profile.t <= t_target + 1e-9:
+            samples.append(
+                (float(profile.t), float(profile.temperature), _ring_temperatures(profile))
+            )
+
+    samples.sort(key=lambda s: s[0])
+    return samples
+
+
+def _scalar_history(target):
+    """Return ``(time, temperature)`` arrays of the bulk cycle, or ``None``."""
+    samples = _collect_history(target)
+    if len(samples) < 2:
+        return None
+    times = np.array([s[0] for s in samples], dtype=float)
+    temperatures = np.array([s[1] for s in samples], dtype=float)
+    return times, temperatures
+
+
+def _ring_history(target):
+    """Return ``(time, ring_temperatures_2d)`` of the per-ring cycles, or ``None``."""
+    samples = _collect_history(target)
+    if len(samples) < 2 or any(s[2] is None for s in samples):
+        return None
+    if len({len(s[2]) for s in samples}) != 1:
+        return None
+    times = np.array([s[0] for s in samples], dtype=float)
+    ring_temperatures = np.array([s[2] for s in samples], dtype=float)
+    return times, ring_temperatures
+
+
+# ---------------------------------------------------------------------------
+# Kinetics evaluation
+# ---------------------------------------------------------------------------
+
+def _solve_cycle(solver, profile, times, temperatures, n):
+    """Run the kinetics solver on a single ``T(t)`` cycle.
+
+    Resamples ``(times, temperatures)`` onto the uniform grid the solver
+    expects and short-circuits to a fully austenitic frame when the cycle never
+    cools below the ferrite-start temperature, sparing the per-step root solve
+    for the still-hot part of the line.
+    """
+    times = np.asarray(times, dtype=float)
+    temperatures = np.asarray(temperatures, dtype=float)
+    unique_times, order = np.unique(times, return_index=True)
+    grid = np.linspace(unique_times[0], unique_times[-1], n)
+    grid_temperatures = np.interp(grid, unique_times, temperatures[order])
+
+    if np.nanmin(grid_temperatures) >= profile.ae3_temperature:
+        frame = pd.DataFrame({"t": grid, "T": grid_temperatures})
+        for name in ("ferrite", "perlite", "bainite", "martensite"):
+            frame[name] = 0.0
+        frame["austenite"] = 1.0
+        return frame
+
+    return solver.get_transformed_fraction(grid, grid_temperatures)
+
+
+def _final_composition(frame: pd.DataFrame) -> dict:
+    final = frame.iloc[-1]
+    return {name: float(final[name]) for name in _PHASES}
+
+
+def _bulk_frame(profile):
+    """The solver frame for the bulk thermal history, cached on the profile."""
+    cached = profile.__dict__.get(_FRAME_CACHE)
+    if cached is not None:
+        return cached
+    history = _scalar_history(profile)
+    if history is None:
+        return None
+    solver = PhaseTransformationSolver(profile)
+    frame = _solve_cycle(solver, profile, history[0], history[1], Config.THERMAL_HISTORY_SAMPLES)
+    profile.__dict__[_FRAME_CACHE] = frame
+    return frame
+
+
+# ---------------------------------------------------------------------------
+# Hooks
+# ---------------------------------------------------------------------------
+
+@Unit.OutProfile.thermal_history
+def thermal_history(self):
+    history = _scalar_history(self)
+    if history is None:
+        return None
+    return {"t": history[0], "T": history[1]}
+
+
+@Unit.OutProfile.ring_thermal_histories
+def ring_thermal_histories(self):
+    history = _ring_history(self)
+    if history is None:
+        return None
+    return history[1]
+
+
+@Unit.OutProfile.microstructure_composition
+def microstructure_composition(self):
+    frame = _bulk_frame(self)
+    if frame is None:
+        return None
+    return _final_composition(frame)
+
+
+@Unit.OutProfile.ring_microstructure_compositions
+def ring_microstructure_compositions(self):
+    history = _ring_history(self)
+    if history is None:
+        return None
+    times, ring_temperatures = history
+
+    # The kinetics inputs (transformation temperatures, composition factors,
+    # grain size) are profile-level and identical for every ring; only the
+    # temperature path differs, so one solver instance is reused.
+    solver = PhaseTransformationSolver(self)
+    n = Config.THERMAL_HISTORY_SAMPLES
+
+    n_rings = ring_temperatures.shape[1]
+    result = np.empty(n_rings, dtype=object)
+    for i in range(n_rings):
+        frame = _solve_cycle(solver, self, times, ring_temperatures[:, i], n)
+        result[i] = _final_composition(frame)
+    return result
+
+
+@Unit.OutProfile.vickers_hardness
+def vickers_hardness(self):
+    frame = _bulk_frame(self)
+    if frame is None:
+        return None
+    hardness = PhaseTransformationSolver(self).estimate_hardness(frame)
+    if not np.isfinite(hardness):
+        return None
+    return float(hardness)
+
+
+@Unit.OutProfile.mechanical_properties
+def mechanical_properties(self):
+    frame = _bulk_frame(self)
+    if frame is None:
+        return None
+    properties = PhaseTransformationSolver(self).estimate_mechanical_properties(frame)
+    return {key: float(value) for key, value in properties.items()}

pyroll/phase_transformation_model/phase_transformations/__init__.py

@@ -0,0 +1,6 @@
+from .base import PhaseTransformation
+from .diffusional_phase_transformation import DiffusionalPhaseTransformation
+from .bainite import Bainite
+from .ferrite import Ferrite
+from .perlite import Perlite
+from .martensite import Martensite

pyroll/phase_transformation_model/phase_transformations/bainite.py

@@ -0,0 +1,29 @@
+from .diffusional_phase_transformation import DiffusionalPhaseTransformation
+
+
+class Bainite(DiffusionalPhaseTransformation):
+    """
+    Austenite to bainite phase transformation
+    """
+
+    name = "bainite"
+
+    @property
+    def grain_size_coefficient(self):
+        return 0.29
+
+    @property
+    def diffusion_coefficient(self):
+        return 2
+
+    @property
+    def transformation_start_temperature(self):
+        return self.profile.bainite_start_temperature
+
+    @property
+    def transformation_finish_temperature(self):
+        return self.profile.martensite_start_temperature
+
+    @property
+    def composition_factor(self):
+        return self.profile.bainite_kinetics

pyroll/phase_transformation_model/phase_transformations/base.py

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+
+import numpy as np
+import pyroll.core as pr
+
+
+class PhaseTransformation(ABC):
+    """
+    Abstract base class for an austenite-decomposition product.
+
+    A phase only has to know how to evaluate the fraction transformed along a
+    thermal history ``T(t)``.  Diffusional products (ferrite, pearlite,
+    bainite) additionally provide isothermal kinetics and live in
+    :class:`DiffusionalPhaseTransformation`; athermal products (martensite)
+    implement :meth:`get_transformed_fraction` directly.
+
+    Attributes
+    ----------
+    name : str
+        Identifier of the phase. It is also the column key used in the result
+        frames produced by the solver and the colour key used by the diagram
+        utilities, so it must be unique across all registered phases.
+    """
+
+    name: str
+
+    def __init__(self, profile: pr.Profile):
+        self.profile: pr.Profile = profile
+
+    @abstractmethod
+    def get_transformed_fraction(
+        self, time: np.ndarray, temperature: np.ndarray, n: int = 1000
+    ):
+        """
+        Calculate the transformed fraction for a given thermal cycle ``T(t)``.
+
+        Parameters
+        ----------
+        time : np.ndarray
+            Time in seconds.
+        temperature : np.ndarray
+            Temperatures at the instants of ``time`` in Kelvin.
+        n : int, optional
+            Number of points at which the transformed fraction is evaluated.
+
+        Returns
+        -------
+        time, temperature, fraction : tuple of np.ndarray
+            The (possibly resampled) thermal cycle and the transformed phase
+            fraction evaluated along it.
+        """
+        raise NotImplementedError

pyroll/phase_transformation_model/phase_transformations/diffusional_phase_transformation.py

@@ -0,0 +1,248 @@
+from abc import abstractmethod
+from typing import Union
+
+import numpy as np
+import pyroll.core as pr
+
+from .base import PhaseTransformation
+from ..sigmoidal_functions import S
+
+
+class DiffusionalPhaseTransformation(PhaseTransformation):
+    """
+    Base class for diffusional (nucleation-and-growth) phase transformations.
+
+    Implements the modified Kirkaldy-Venugopalan kinetics as parametrised by
+    Li et al. (1998).  The isothermal time to reach a transformed fraction
+    ``X`` at temperature ``T`` is
+
+    .. math::
+
+        \\tau(X, T) = S(X) \\cdot
+            \\frac{C}{2^{g\\,G}\\,\\Delta T^{n}\\,\\exp(-Q / R T)}
+
+    where :math:`C` is the composition factor, :math:`g` the grain-size
+    coefficient, :math:`G` the ASTM grain-size number, :math:`\\Delta T` the
+    undercooling below the transformation-start temperature, :math:`n` the
+    diffusion exponent, :math:`Q` the activation energy and :math:`S(X)` the
+    sigmoidal reaction-rate term.
+
+    Concrete subclasses (ferrite, pearlite, bainite) only declare the
+    composition factor, the grain-size and diffusion coefficients and the
+    start/finish temperatures.
+    """
+
+    @property
+    @abstractmethod
+    def composition_factor(self):
+        """Composition factor for calculating the transformation time."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def transformation_start_temperature(self):
+        """Start temperature for the phase transformation."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def transformation_finish_temperature(self):
+        """Finish temperature for the phase transformation."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def grain_size_coefficient(self):
+        """Empirical constant representing the influence of grain size."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def diffusion_coefficient(self):
+        """
+        Exponent of the undercooling set by the effective diffusion mechanism
+        (``2`` for volume and ``3`` for boundary diffusion).
+        """
+        raise NotImplementedError
+
+    @property
+    def activation_energy(self):
+        """Activation energy of the diffusional reaction in J/mol."""
+        return 27500 * 4.184
+
+    def get_transformation_factor(self, temperature: np.ndarray):
+        """
+        Calculate the transformation factor for a given temperature.
+
+        Parameters
+        ----------
+        temperature : np.ndarray
+            Temperature array in Kelvin.
+
+        Returns
+        -------
+        transformation_factor : np.ndarray
+            Transformation factor with the same shape as ``temperature``.
+        """
+        undercooling = self.transformation_start_temperature - temperature
+
+        return self.composition_factor / (
+            2 ** (self.grain_size_coefficient * self.profile.astm_grain_size_number)
+            * undercooling**self.diffusion_coefficient
+            * np.exp(
+                -self.activation_energy
+                / (pr.Config.UNIVERSAL_GAS_CONSTANT * temperature)
+            )
+        )
+
+    def get_transformation_time(
+        self, temperature: np.ndarray, transformed_fraction: np.ndarray
+    ):
+        """
+        Calculate the time necessary for the material to reach a given
+        transformed fraction at a temperature.
+
+        Parameters
+        ----------
+        temperature : np.ndarray
+            Temperature in Kelvin.
+        transformed_fraction : np.ndarray
+            Transformed fraction with the same shape as ``temperature``.
+
+        Returns
+        -------
+        transformation_time : np.ndarray
+            Transformation time with the same shape as ``temperature``.
+        """
+        return S(transformed_fraction) * self.get_transformation_factor(temperature)
+
+    def get_transformation_temperature(
+        self,
+        initial_temperature: float,
+        final_temperature: float,
+        cooling_rate: Union[float, np.ndarray],
+        transformed_fraction: Union[float, np.ndarray],
+        temperature_increment: Union[float, int] = 1,
+    ):
+        """
+        Calculate the temperature at which a transformed fraction is reached
+        during continuous cooling, using Scheil's additivity rule.
+
+        Parameters
+        ----------
+        initial_temperature : float
+            Initial temperature in Kelvin.
+        final_temperature : float
+            Final temperature in Kelvin.
+        cooling_rate : float or np.ndarray
+            Cooling rate(s). May be provided as an array.
+        transformed_fraction : float or np.ndarray
+            Transformed fraction. If iterable it must have the same shape as
+            ``cooling_rate``.
+        temperature_increment : int or float, optional
+            Increment for the temperature integration grid.
+
+        Returns
+        -------
+        transformation_temperature : float or np.ndarray
+            Transformation temperature with the same shape as ``cooling_rate``.
+        """
+        time_increment = temperature_increment / np.array(cooling_rate)
+        number_of_cooling_rates = (
+            np.size(time_increment) if np.ndim(time_increment) > 0 else 1
+        )
+
+        temperature_profile = np.arange(
+            initial_temperature, final_temperature, -temperature_increment
+        )
+
+        # Scheil additivity: accumulate dt / transformation_factor over the
+        # cooling path and compare against S(f). The transformation reaches the
+        # fraction f once the accumulated sum exceeds S(f).
+        nucleation_time = np.zeros(
+            (number_of_cooling_rates, len(temperature_profile)), dtype=float
+        )
+        below_transformation_start_temperature = (
+            temperature_profile < self.transformation_start_temperature
+        )
+        nucleation_time[:, below_transformation_start_temperature] = np.outer(
+            time_increment,
+            1
+            / self.get_transformation_factor(
+                temperature_profile[below_transformation_start_temperature]
+            ),
+        )
+        nucleation_time = nucleation_time.cumsum(axis=1)
+
+        transformation_temperature = np.full(
+            number_of_cooling_rates, np.nan, dtype=float
+        )
+        sigmoidal_of_transformed_fraction = S(transformed_fraction)
+        for i, accumulated_time in enumerate(nucleation_time):
+            (reached,) = np.where(
+                accumulated_time >= sigmoidal_of_transformed_fraction
+            )
+            if len(reached) > 0:
+                transformation_temperature[i] = temperature_profile[reached[0]]
+
+        return (
+            float(transformation_temperature[0])
+            if number_of_cooling_rates == 1
+            else transformation_temperature
+        )
+
+    def get_transformed_fraction(
+        self, time: np.ndarray, temperature: np.ndarray, n: int = 1000
+    ):
+        """
+        Calculate the transformed fraction for a given thermal cycle ``T(t)``.
+
+        The transformation is only active between the start and finish
+        temperatures of the phase. The accumulated nucleation time is built up
+        over the cooling path and inverted through ``S`` to obtain the
+        fraction (clamped to ``[0, 1]`` outside the bounds of ``S``).
+
+        Parameters
+        ----------
+        time : np.ndarray
+            Time in seconds.
+        temperature : np.ndarray
+            Temperatures at the instants of ``time`` in Kelvin.
+        n : int, optional
+            Number of points used to derive the integration time increment.
+
+        Returns
+        -------
+        time, temperature, fraction : tuple of np.ndarray
+            The thermal cycle and the transformed phase fraction along it.
+        """
+        time_increment = (max(time) - min(time)) / (n - 1)
+        nucleation_time = np.zeros(time.shape, dtype=float)
+        phase_fraction = np.zeros(temperature.shape, dtype=float)
+
+        temperatures_in_phase_range = (
+            temperature < self.transformation_start_temperature
+        ) & (temperature > self.transformation_finish_temperature)
+
+        if not np.any(temperatures_in_phase_range):
+            return time, temperature, phase_fraction
+
+        nucleation_time[temperatures_in_phase_range] = (
+            time_increment
+            / self.get_transformation_factor(temperature[temperatures_in_phase_range])
+        )
+        nucleation_time = nucleation_time.cumsum()
+        if temperature[0] < self.transformation_start_temperature:
+            # Account for the fraction already transformed at time[0].
+            nucleation_time += min(time) / self.get_transformation_factor(
+                temperature[0]
+            )
+
+        # Invert S only where the accumulated time lies within its range;
+        # clamp to the fully-untransformed / fully-transformed limits outside.
+        within_bounds = (nucleation_time >= S.ymin) & (nucleation_time <= S.ymax)
+        if np.any(within_bounds):
+            phase_fraction[within_bounds] = S.inverse(nucleation_time[within_bounds])
+        phase_fraction[nucleation_time > S.ymax] = 1
+
+        return time, temperature, phase_fraction

pyroll/phase_transformation_model/phase_transformations/ferrite.py

@@ -0,0 +1,29 @@
+from .diffusional_phase_transformation import DiffusionalPhaseTransformation
+
+
+class Ferrite(DiffusionalPhaseTransformation):
+    """
+    Austenite to ferrite phase transformation
+    """
+
+    name = "ferrite"
+
+    @property
+    def grain_size_coefficient(self):
+        return 0.41
+
+    @property
+    def diffusion_coefficient(self):
+        return 3
+
+    @property
+    def transformation_start_temperature(self):
+        return self.profile.ae3_temperature
+
+    @property
+    def transformation_finish_temperature(self):
+        return self.profile.bainite_start_temperature
+
+    @property
+    def composition_factor(self):
+        return self.profile.ferrite_kinetics