MatSciKit-COSMOTIM 0.2.2__py3-none-any.whl

MatSciKit_COSMOTIM/__init__.py

@@ -0,0 +1,19 @@
+"""
+MatSciKit — Materials Science Toolkit.
+
+A Python package for materials science research data processing,
+with a focus on thermal transport analysis.
+
+Subpackages
+-----------
+io : Instrument-specific data readers
+structure : Crystallography and XRD analysis
+heat_capacity : Heat capacity analysis (Pipeline 1)
+thermal_conductivity : Thermal conductivity analysis (Pipeline 2)
+fitting : Curve fitting utilities
+visualization : Publication-quality figure export
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"

MatSciKit_COSMOTIM/constants.py

@@ -0,0 +1,25 @@
+"""
+Physical constants in SI units.
+
+Values are sourced from :mod:`scipy.constants` (CODATA 2018).
+Aliases are provided for backward compatibility.
+"""
+
+from __future__ import annotations
+
+from scipy import constants as _c
+
+# Boltzmann constant (J/K)
+kb: float = _c.Boltzmann
+
+# Planck constant (J·s)
+h: float = _c.Planck
+
+# Reduced Planck constant ħ (J·s)
+hbar: float = _c.hbar
+
+# Avogadro constant (mol⁻¹)
+NA: float = _c.Avogadro
+
+# Atomic mass unit (kg)
+AMU_TO_KG: float = _c.atomic_mass

MatSciKit_COSMOTIM/fitting/__init__.py

@@ -0,0 +1,13 @@
+"""
+Curve fitting utilities.
+
+Modules
+-------
+linear : Weighted linear regression with error propagation
+"""
+
+from __future__ import annotations
+
+from . import linear
+
+__all__ = ["linear"]

MatSciKit_COSMOTIM/fitting/linear.py

@@ -0,0 +1,67 @@
+"""
+Weighted linear regression with error propagation.
+
+Translated from linear_fit_with_errors.m
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def fit_with_errors(x: np.ndarray, y: np.ndarray, y_err: np.ndarray) -> tuple[float, float, float]:
+    """
+    Weighted linear fit to data with measurement errors.
+
+    Performs a weighted least-squares linear fit y = slope * (x - x0) + intercept,
+    where weights are 1/y_err^2.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        Independent variable values.
+    y : np.ndarray
+        Dependent variable values.
+    y_err : np.ndarray
+        Standard errors on y values.
+
+    Returns
+    -------
+    slope : float
+        Fitted slope.
+    se_slope : float
+        Standard error of the slope.
+    intercept : float
+        Fitted intercept (at x = mean(x)).
+
+    Notes
+    -----
+    Translated from MATLAB ``linear_fit_with_errors.m``. The fit is performed
+    with x shifted by its mean (x0 = mean(x)) for numerical stability.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    y_err = np.asarray(y_err, dtype=float)
+
+    n = len(x)
+    weights = 1.0 / y_err**2
+
+    x0 = np.mean(x)
+    dx = x - x0
+
+    sum_w = np.sum(weights)
+    sum_wx = np.sum(weights * dx)
+    sum_wv = np.sum(weights * y)
+    sum_wxx = np.sum(weights * dx**2)
+    sum_wvx = np.sum(weights * y * dx)
+
+    delta = sum_w * sum_wxx - sum_wx**2
+    slope = (sum_wvx * sum_w - sum_wx * sum_wv) / delta
+    intercept = (sum_wxx * sum_wv - sum_wx * sum_wvx) / delta
+
+    # Standard error of slope
+    residuals = y - slope * dx - intercept
+    sum_wrr = np.sum(weights * residuals**2)
+    se_slope = np.sqrt(sum_wrr * sum_w / delta / (n - 2))
+
+    return slope, se_slope, intercept

MatSciKit_COSMOTIM/heat_capacity/__init__.py

@@ -0,0 +1,15 @@
+"""
+Heat capacity analysis (Pipeline 1).
+
+Modules
+-------
+low_t_fitting : Debye temperature and sound velocity from low-T Cp fit
+dulong_petit : Dulong-Petit limit calculation
+debye : Debye temperature converters (velocity, modulus)
+"""
+
+from __future__ import annotations
+
+from . import debye, dulong_petit, low_t_fitting
+
+__all__ = ["debye", "dulong_petit", "low_t_fitting"]

MatSciKit_COSMOTIM/heat_capacity/debye.py

@@ -0,0 +1,61 @@
+"""
+Debye temperature converters.
+
+Convert between Debye temperature, sound velocity, and elastic modulus.
+
+Translated from modulus2debyeT.m and velocity2debyeT.m
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from MatSciKit_COSMOTIM.constants import hbar, kb
+
+
+def from_velocity(v_s: float, n_density: float) -> float:
+    """
+    Calculate Debye temperature from sound velocity.
+
+    Parameters
+    ----------
+    v_s : float
+        Sound velocity (m/s).
+    n_density : float
+        Number density N/V (atoms/m³).
+
+    Returns
+    -------
+    theta_D : float
+        Debye temperature (K).
+
+    Notes
+    -----
+    Formula: θ_D = v_s · (ħ/kb) · (6π²·N_density)^(1/3)
+    """
+    return v_s * (hbar / kb) * (6 * np.pi**2 * n_density) ** (1.0 / 3)
+
+
+def from_modulus(modulus_gpa: float, density: float, n_density: float) -> float:
+    """
+    Calculate Debye temperature from bulk modulus.
+
+    First computes the sound velocity as v = sqrt(B/ρ), then converts
+    to Debye temperature.
+
+    Parameters
+    ----------
+    modulus_gpa : float
+        Bulk modulus (GPa).
+    density : float
+        Mass density (kg/m³).
+    n_density : float
+        Number density N/V (atoms/m³).
+
+    Returns
+    -------
+    theta_D : float
+        Debye temperature (K).
+    """
+    v_s = np.sqrt(modulus_gpa * 1e9 / density)
+    return from_velocity(v_s, n_density)

MatSciKit_COSMOTIM/heat_capacity/dulong_petit.py

@@ -0,0 +1,38 @@
+"""
+Dulong-Petit limit calculation.
+
+The classical upper limit of heat capacity per unit mass.
+"""
+
+from __future__ import annotations
+
+from MatSciKit_COSMOTIM.constants import kb
+
+
+def calculate(n_density: float, density: float) -> float:
+    """
+    Calculate the Dulong-Petit heat capacity limit.
+
+    The Dulong-Petit law states that the molar heat capacity of a solid
+    approaches 3R per mole of atoms at high temperatures.
+
+    Parameters
+    ----------
+    n_density : float
+        Number density N/V (atoms/m³).
+    density : float
+        Mass density (kg/m³).
+
+    Returns
+    -------
+    limit : float
+        Dulong-Petit limit in J/(g·K).
+
+    Notes
+    -----
+    Formula: C_DP = 3 · N_density · kb / Density × 1e-3
+
+    The factor 1e-3 converts from J/(kg·K) to J/(g·K) to match
+    typical specific heat capacity units in materials science.
+    """
+    return 3 * n_density * kb / density * 1e-3

MatSciKit_COSMOTIM/heat_capacity/low_t_fitting.py

@@ -0,0 +1,154 @@
+"""
+Low-temperature heat capacity fitting for Debye temperature and sound velocity.
+
+Fits Cp/T vs T² in the low-temperature regime to extract the Debye temperature
+(θ_D) and average sound velocity (v_s).
+
+Translated from LowT_Cp_fitting.m
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import curve_fit
+
+from MatSciKit_COSMOTIM.constants import hbar, kb
+
+
+def _linear(x: np.ndarray, a: float, b: float) -> np.ndarray:
+    """Linear model: y = a*x + b."""
+    return a * x + b
+
+
+def fit(
+    T: np.ndarray,
+    Cp: np.ndarray,
+    Cp_err: np.ndarray,
+    n_density: float,
+    density: float,
+    t_range: tuple[float, float] | None = None,
+    n_range: tuple[int, int] | None = None,
+) -> tuple[float, float, float, float]:
+    """
+    Extract Debye temperature and sound velocity from low-T Cp data.
+
+    Performs a weighted linear fit of Cp/T vs T² in the low-temperature
+    regime. The slope relates to the Debye temperature through:
+
+        Cp/T = β·T² + γ
+
+    where β = (12π⁴/5) · N_density · kb / (Density · θ_D³)
+
+    The fitting region can be specified in two ways:
+
+    - **Temperature range:** ``t_range=(T_min, T_max)`` selects all points
+      within that range.
+    - **Index range:** ``n_range=(n_start, n_end)`` uses data points at
+      indices n_start through n_end (1-based, inclusive) after sorting by T.
+      This matches the MATLAB convention ``data(n_start:n_end, :)``.
+
+    If both are given, ``t_range`` takes priority. If neither is given,
+    all data is used.
+
+    Parameters
+    ----------
+    T : np.ndarray
+        Temperature values (K).
+    Cp : np.ndarray
+        Heat capacity values (J/(g·K)).
+    Cp_err : np.ndarray
+        Heat capacity errors (J/(g·K)).
+    n_density : float
+        Number density N/V (atoms/m³).
+    density : float
+        Mass density (kg/m³).
+    t_range : tuple of (float, float), optional
+        Temperature range (T_min, T_max) in Kelvin for the fitting region.
+    n_range : tuple of (int, int), optional
+        Index range (n_start, n_end) using 1-based inclusive indexing,
+        applied after sorting by temperature. Matches MATLAB convention
+        ``data(n_start:n_end, :)``. For example, ``n_range=(13, 41)``
+        selects the 13th through 41st data points.
+
+    Returns
+    -------
+    theta_D : float
+        Debye temperature (K).
+    v_s : float
+        Average sound velocity (m/s).
+    theta_D_error : float
+        Uncertainty in Debye temperature (K).
+    v_s_error : float
+        Uncertainty in sound velocity (m/s).
+
+    Notes
+    -----
+    The fit is weighted by (Cp_err/Cp)^(-2), matching the MATLAB implementation
+    which uses relative errors as weights for the ``poly1`` fit.
+
+    Examples
+    --------
+    >>> # Method 1: Fit using temperature range
+    >>> theta_D, v_s, err_D, err_v = fit(T, Cp, Cp_err, n_density, density,
+    ...                                   t_range=(3.0, 10.0))
+    >>> # Method 2: Use data points 13 through 41 (1-based, like MATLAB)
+    >>> theta_D, v_s, err_D, err_v = fit(T, Cp, Cp_err, n_density, density,
+    ...                                   n_range=(13, 41))
+    """
+    T = np.asarray(T, dtype=float)
+    Cp = np.asarray(Cp, dtype=float)
+    Cp_err = np.asarray(Cp_err, dtype=float)
+
+    # Sort by temperature
+    sort_idx = np.argsort(T)
+    T = T[sort_idx]
+    Cp = Cp[sort_idx]
+    Cp_err = Cp_err[sort_idx]
+
+    # Select fitting region
+    if t_range is not None:
+        # Method 1: Temperature range
+        t_min, t_max = t_range
+        mask = (t_min <= T) & (t_max >= T)
+        T = T[mask]
+        Cp = Cp[mask]
+        Cp_err = Cp_err[mask]
+    elif n_range is not None:
+        # Method 2: Index range (1-based inclusive, like MATLAB)
+        n_start, n_end = n_range
+        # Convert 1-based inclusive to 0-based Python slice
+        T = T[n_start - 1 : n_end]
+        Cp = Cp[n_start - 1 : n_end]
+        Cp_err = Cp_err[n_start - 1 : n_end]
+
+    if len(T) < 3:
+        raise ValueError(
+            f"Fewer than 3 data points in the selected range. "
+            f"Need at least 3 for a meaningful linear fit. Got {len(T)}."
+        )
+
+    # Prepare data: Cp/T vs T²
+    x = T**2
+    y = Cp / T
+
+    # Weights: inverse of relative error squared, matching MATLAB W = (Cp_err./Cp).^(-2)
+    sigma = Cp_err / Cp  # relative errors used as sigma for curve_fit
+
+    # Weighted linear fit
+    popt, pcov = curve_fit(_linear, x, y, sigma=sigma, absolute_sigma=False)
+    slope = popt[0]
+
+    # 95% confidence interval for slope error
+    slope_std = np.sqrt(pcov[0, 0])
+    slope_95 = slope_std * 1.96  # approximate 95% CI
+    r_error = slope_95 / abs(slope)
+
+    # Debye temperature: θ_D = (slope * Density * 1e3 / (12π⁴/5 * N_density * kb))^(-1/3)
+    theta_D = (1.0 / (12 * np.pi**4 / 5 * n_density * kb) * slope * density * 1e3) ** (-1.0 / 3)
+    theta_D_error = theta_D * r_error / 3
+
+    # Sound velocity: v_s = θ_D / (ħ/kb * (6·N_density·π²)^(1/3))
+    v_s = theta_D / (hbar / kb * (6 * n_density * np.pi**2) ** (1.0 / 3))
+    v_s_error = v_s * r_error / 3
+
+    return theta_D, v_s, theta_D_error, v_s_error

MatSciKit_COSMOTIM/io/__init__.py

@@ -0,0 +1,36 @@
+"""
+Instrument-specific data readers.
+
+Function-based readers (quick use):
+    ``ppms_hc.read()``, ``ppms_tto.read()``, ``dsc.read()``, ``lfa.read()``
+
+Class-based readers (metadata + caching):
+    ``PPMSHCReader``, ``PPMSTTOReader``, ``DSCReader``, ``LFAReader``,
+    ``auto_reader()``
+"""
+
+from __future__ import annotations
+
+from . import dsc, lfa, lfa_excel, ppms_hc, ppms_tto
+from .readers import (
+    BaseReader,
+    DSCReader,
+    LFAReader,
+    PPMSHCReader,
+    PPMSTTOReader,
+    auto_reader,
+)
+
+__all__ = [
+    "BaseReader",
+    "DSCReader",
+    "LFAReader",
+    "PPMSHCReader",
+    "PPMSTTOReader",
+    "auto_reader",
+    "dsc",
+    "lfa",
+    "lfa_excel",
+    "ppms_hc",
+    "ppms_tto",
+]

MatSciKit_COSMOTIM/io/dsc.py

@@ -0,0 +1,59 @@
+"""
+DSC (Differential Scanning Calorimetry) data reader.
+
+Reads heat capacity data from DSC CSV export files (e.g., Netzsch DSC 214).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+
+def read(filepath: str, skip_rows: int = 34) -> np.ndarray:
+    """
+    Read DSC heat capacity data from a CSV export file.
+
+    The file is expected to have header rows followed by data columns:
+    [Temperature (°C), Time (min), Cp (J/(g·K))].
+    Temperature is automatically converted from °C to K.
+
+    Parameters
+    ----------
+    filepath : str
+        Full path to the DSC CSV file.
+    skip_rows : int, optional
+        Number of header rows to skip. Default is 34 (Netzsch format).
+
+    Returns
+    -------
+    data : np.ndarray
+        Array with columns [Temperature (K), Cp (J/(g·K))].
+
+    Raises
+    ------
+    FileNotFoundError
+        If the specified file does not exist.
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"File not found: {filepath}")
+
+    # Read CSV data
+    # DSC files may contain non-UTF-8 characters (e.g., µ in µV)
+    # Read with latin-1 encoding, then parse with numpy
+    with open(filepath, encoding="latin-1") as f:
+        lines = f.readlines()[skip_rows:]
+
+    # Parse numeric data from remaining lines
+    raw = np.genfromtxt(lines, delimiter=",")
+
+    if raw.ndim == 1:
+        raw = raw.reshape(1, -1)
+
+    # Extract Temperature (°C) and Cp columns, convert T to Kelvin
+    temp_k = raw[:, 0] + 273.15
+    cp = raw[:, 2]  # Third column is Cp
+
+    return np.column_stack([temp_k, cp])

MatSciKit_COSMOTIM/io/lfa.py

@@ -0,0 +1,49 @@
+"""
+LFA (Laser Flash Analysis) data reader.
+
+Reads thermal diffusivity or conductivity data from LFA CSV files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+
+def read(filepath: str) -> np.ndarray:
+    """
+    Read LFA data from a CSV file.
+
+    Expected format: columns [Temperature (K), Value, Error].
+    Rows containing NaN values are automatically dropped.
+
+    Parameters
+    ----------
+    filepath : str
+        Full path to the LFA CSV file.
+
+    Returns
+    -------
+    data : np.ndarray
+        Array with columns [Temperature (K), Value, Error], NaN rows removed.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the specified file does not exist.
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"File not found: {filepath}")
+
+    data = np.genfromtxt(filepath, delimiter=",")
+
+    if data.ndim == 1:
+        data = data.reshape(1, -1)
+
+    # Drop rows with any NaN
+    mask = ~np.any(np.isnan(data), axis=1)
+    data = data[mask]
+
+    return data

MatSciKit_COSMOTIM/io/lfa_excel.py

@@ -0,0 +1,116 @@
+"""
+LFA Excel data reader.
+
+Reads laser flash analysis diffusivity data from Excel files
+(e.g., UT LFA instrument export format).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+
+def read(filepath: str, sheet_name: str | int = 0, skip_rows: int = 1) -> np.ndarray:
+    """Read LFA diffusivity data from an Excel file.
+
+    Expected format after skipping header:
+    columns [Temperature (°C), T_error, Diffusivity (mm²/s), Diff_error].
+
+    Temperature is converted from °C to K.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to the Excel file (.xlsx).
+    sheet_name : str or int, optional
+        Sheet name or index (default 0).
+    skip_rows : int, optional
+        Number of header rows to skip (default 1).
+
+    Returns
+    -------
+    data : np.ndarray
+        Array with columns [Temperature (K), Diffusivity (mm²/s), Diffusivity_error].
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    ImportError
+        If openpyxl is not installed.
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"File not found: {filepath}")
+
+    try:
+        import openpyxl
+    except ImportError as exc:
+        raise ImportError(
+            "openpyxl is required to read Excel files. Install with: pip install openpyxl"
+        ) from exc
+
+    wb = openpyxl.load_workbook(filepath, read_only=True, data_only=True)
+
+    ws = wb.worksheets[sheet_name] if isinstance(sheet_name, int) else wb[sheet_name]
+
+    rows = []
+    for i, row in enumerate(ws.iter_rows(values_only=True)):
+        if i < skip_rows:
+            continue
+        # Skip empty rows
+        if row[0] is None:
+            continue
+        try:
+            vals = [float(v) if v is not None else np.nan for v in row[:4]]
+            rows.append(vals)
+        except (ValueError, TypeError):
+            continue
+
+    wb.close()
+
+    if not rows:
+        raise ValueError(f"No numeric data found in sheet '{sheet_name}'")
+
+    raw = np.array(rows)
+
+    # Extract: Temperature (°C → K), Diffusivity, Diffusivity_error
+    temp_k = raw[:, 0] + 273.15
+    diffusivity = raw[:, 2]
+    diff_error = raw[:, 3]
+
+    result = np.column_stack([temp_k, diffusivity, diff_error])
+
+    # Drop NaN rows
+    mask = ~np.any(np.isnan(result), axis=1)
+    result = result[mask]
+
+    return result
+
+
+def list_sheets(filepath: str) -> list[str]:
+    """List available sheet names in an LFA Excel file.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to the Excel file.
+
+    Returns
+    -------
+    sheets : list of str
+        Sheet names.
+    """
+    try:
+        import openpyxl
+    except ImportError as exc:
+        raise ImportError(
+            "openpyxl is required to read Excel files. Install with: pip install openpyxl"
+        ) from exc
+
+    wb = openpyxl.load_workbook(filepath, read_only=True)
+    names = wb.sheetnames
+    wb.close()
+    return names