pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/strain/cpp/strain.hpp

@@ -0,0 +1,177 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+#ifndef DICSTRAIN_H
+#define DICSTRAIN_H
+
+// STD library Header files
+#include <vector>
+#include <cmath>
+
+// pybind header files
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+
+// common_cpp Header files
+#include "../../common_cpp/util.hpp"
+#include <Eigen/Dense>
+
+// Program Header files
+
+
+namespace py = pybind11;
+
+
+namespace strain {
+
+    /**
+     * @brief Struct for the strain window. Contains subset coordinates (x,y) 
+     * and the corresponding displacement vectors (u,v).
+     * 
+     */
+    struct Window {
+        std::vector<int> x;
+        std::vector<int> y;
+        std::vector<double> u;
+        std::vector<double> v;
+
+        Window(int sw_size) 
+            : x(sw_size * sw_size, 0.0),
+              y(sw_size * sw_size, 0.0),
+              u(sw_size * sw_size, 0.0),
+              v(sw_size * sw_size, 0.0)
+        {}
+    };
+
+
+    struct Results {
+        std::vector<int> x;
+        std::vector<int> y;
+        std::vector<double> def_grad;
+        std::vector<double> strain;
+        std::vector<bool> valid_window;
+
+        Results(int nwindows) 
+            : x(nwindows, 0),
+              y(nwindows, 0),
+              def_grad(nwindows*4, std::nan("")),
+              strain(nwindows*4, std::nan("")),
+              valid_window(nwindows, false)
+        {}
+    };
+
+
+
+    void engine(const py::array_t<int> &ss_x_arr,
+                const py::array_t<int> &ss_y_arr,
+                const py::array_t<double> &u_arr,
+                const py::array_t<double> &v_arr,
+                const int nss_x, const int nss_y, 
+                const int nimg, const int sw_size, 
+                const int q, const std::string &form,
+                const std::vector<std::string> &filenames,
+                const common_util::SaveConfig &strain_save_conf);
+
+    /**
+     * @brief Fills the strain window with the subset coordinates 
+     * and displacement vectors based on the input parameters
+     * 
+     * @param ss_x subset x-coordinates
+     * @param ss_y subset y-coordinates
+     * @param u horizontal displacement
+     * @param v vertical displacement
+     * @param window strain window struct. 
+     * @param num_ss_x number of subsets along the x-axis
+     * @param num_ss_y number of subsets along the y-axis
+     * @param x0_idx index of the x-coordinate in the subset mask
+     * @param y0_idx index of the x-coordinate in the subset mask
+     * @param swr strain window radius (strain window / 2)
+     * @return true if the strain window is filled successfully
+     * @return false if the strain window is out of bounds
+     */
+    bool fill_window(int *ss_x, int *ss_y, double *u, double *v,
+                            int img, int sw, Window &window,
+                            int nss_x, int nss_y, int sw_size);
+
+
+
+    Eigen::Matrix2d compute_def_grad(const int q, const Eigen::VectorXd &uc, 
+                                     const Eigen::VectorXd& vc, const double x0, 
+                                     const double y0);
+
+
+    Eigen::Matrix2d compute_strain(const std::string& form, 
+                                   const Eigen::Matrix2d& deform_grad);
+
+
+    /**
+     */
+    void append_results(int sw, strain::Results &results,
+                        const bool save_at_end, const int x0, const int y0, 
+                        const Eigen::Matrix2d &deform_grad, 
+                        const Eigen::Matrix2d &eps, 
+                        const int nwindows, const int img);
+
+
+    /**
+     */
+    void save_to_disk(int img, const strain::Results &results, 
+                      const common_util::SaveConfig &strain_save_conf, 
+                      const int nwindows, const int nimg,
+                      const std::vector<std::string> filenames);
+
+
+
+    // strain formulations
+    /**
+     * @brief Calculates Green strain for a given deformation gradient F and identity matrix I.
+     * 
+     * @param F deformation gradient
+     * @param I Identity Matrix
+     * @return Eigen::Matrix2d Green Strain
+     */
+    inline Eigen::Matrix2d green(Eigen::Matrix2d F);
+
+    /**
+     * @brief Calculates Hencky strain for a given deformation gradient F and identity matrix I.
+     * 
+     * @param F deformation gradient
+     * @param I Identity Matrix
+     * @return Eigen::Matrix2d Hencky Strain
+     */
+    inline Eigen::Matrix2d hencky(Eigen::Matrix2d F);
+
+    /**
+     * @brief Calculates Almansi strain for a given deformation gradient F and identity matrix I.
+     * 
+     * @param F deformation gradient
+     * @param I Identity Matrix
+     * @return Eigen::Matrix2d Almansi Strain
+     */
+    inline Eigen::Matrix2d almansi(Eigen::Matrix2d F);
+
+    /**
+     * @brief Calculates Biot strain in the euler coordiate system for a given deformation gradient F and identity matrix I.
+     * 
+     * @param F deformation gradient
+     * @param I Identity Matrix
+     * @return Eigen::Matrix2d Almansi Strain
+     */
+    inline Eigen::Matrix2d biot_euler(Eigen::Matrix2d F);
+
+    /**
+     * @brief Calculates Biot strain in the lagrange coordiate system for a given deformation gradient F and identity matrix I.
+     * 
+     * @param F deformation gradient
+     * @param I Identity Matrix
+     * @return Eigen::Matrix2d Almansi Strain
+     */
+    inline Eigen::Matrix2d biot_lagrange(Eigen::Matrix2d F);
+
+}
+
+
+#endif // DICSTRAIN_H

pyvale/strain/strain.py

@@ -0,0 +1,117 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+from pathlib import Path
+
+# pyvale
+from pyvale.strain.strainresults import StrainResults
+from pyvale.strain.strainchecks import check_strain_files
+from pyvale.dic.dicdataimport import import_2d
+from pyvale.common_py.util import check_output_directory
+import pyvale.strain.strain_cpp as strain_cpp
+import pyvale.common_cpp.common_cpp as common_cpp
+
+def calculate_2d(data: str | Path,
+              window_size: int=5, 
+              window_element: int=9,
+              input_binary: bool=False,
+              input_delimiter: str=",",
+              output_basepath: Path | str="./",
+              output_binary: bool=False,
+              output_prefix: str="strain_",
+              output_delimiter: str=",",
+              output_at_end: bool=False,
+              strain_formulation: str="HENCKY"):
+    """
+    Compute strain fields from DIC displacement data using a finite element smoothing approach.
+
+    This function validates the input data and parameters, optionally loads DIC results from file,
+    and passes the data to a C++-accelerated backend for strain computation.
+
+    Parameters
+    ----------
+    data : pathlib.Path or str
+        A pathlib.Path or str to files from which the data should be imported.
+    input_delimiter: str
+        delimiter used for the input dic results files (default: ",").
+    input_binary bool:
+        whether input data is in human-readable or binary format (default:
+        False).
+    window_size : int, optional
+        The size of the local window over which to compute strain (must be odd), by default 5.
+    window_element : int, optional
+        The type of finite element shape function used in the strain window: 4 (bilinear) or 9 (biquadratic),
+        by default 4.
+    strain_formulation : str, optional
+        The strain definition to use: one of 'GREEN', 'ALMANSI', 'HENCKY', 'BIOT_EULER', 'BIOT_LAGRANGE'.
+        Defaults to 'HENCKY'.
+    output_basepath : str or pathlib.Path, optional
+        Directory path where output files will be written (default: "./").
+    output_binary : bool, optional
+        Whether to write output in binary format (default: False).
+    output_prefix : str, optional
+        Prefix for all output files (default: "strain_"). results will be
+        named with output_prefix + original filename. THe extension will be
+        changed to ".csv" or ".dic2d" depending on whether outputting as a binary.
+    output_delimiter : str, optional
+        Delimiter used in text output files (default: ",").
+
+    Raises
+    ------
+    ValueError
+        If any of the input parameters are invalid (e.g., unsupported strain formulation,
+        even window size, or invalid element type).
+    """
+
+    allowed_formulations = ["GREEN", "ALMANSI", "HENCKY", "BIOT_EULER", "BIOT_LAGRANGE"]
+    if strain_formulation not in allowed_formulations:
+        raise ValueError(f"Invalid strain formulation: '{strain_formulation}'. "
+                         f"Allowed values are: {', '.join(allowed_formulations)}.")
+
+    allowed_elements = [4, 9]
+    if window_element not in allowed_elements:
+        raise ValueError(f"Invalid strain window element type: Q{window_element}. "
+                         f"Allowed values are: {', '.join(map(str, allowed_elements))}.")
+
+    if window_size % 2 == 0:
+        raise ValueError(f"Invalid strain window size: '{window_size}'. Must be an odd number.")
+
+    filenames = check_strain_files(strain_files=data)
+
+    # Load data if a file path is given
+    results = import_2d(layout="matrix", data=str(data),
+                                  binary=input_binary, delimiter=input_delimiter)
+
+    # Extract dimensions from the validated object
+    nss_x = results.ss_x.shape[1]
+    nss_y = results.ss_y.shape[0]
+    nimg = results.u.shape[0]
+
+
+    check_output_directory(str(output_basepath), output_prefix)
+
+    # assigning c++ struct vals for save config
+    strain_save_conf = common_cpp.SaveConfig()
+    strain_save_conf.basepath = str(output_basepath)
+    strain_save_conf.binary = output_binary
+    strain_save_conf.prefix = output_prefix
+    strain_save_conf.delimiter = output_delimiter
+    strain_save_conf.at_end = output_at_end
+
+    print(filenames)
+
+    # Call to C++ backend
+    strain_cpp.strain_engine(results.ss_x, results.ss_y,
+                           results.u, results.v,
+                           nss_x, nss_y, nimg,
+                           window_size, window_element, 
+                           strain_formulation, filenames,
+                           strain_save_conf)
+
+
+
+
+

pyvale/strain/strainchecks.py

@@ -0,0 +1,47 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+import os
+import glob
+from pathlib import Path
+
+
+def check_strain_files(strain_files: str | Path) -> list[str]:
+    """
+    Check for strain/deformation files in the given path and return their filenames.
+
+    Parameters
+    ----------
+    strain_files : str or pathlib.Path
+        Path or glob pattern pointing to the strain/deformation files.
+
+    Returns
+    -------
+    list[str]
+        A sorted list of filenames (not full paths) matching the input path/pattern.
+
+    Raises
+    ------
+    FileNotFoundError
+        If no files matching the given path or pattern are found.
+
+    Examples
+    --------
+    >>> check_strain_files("data/strain_*.tif")
+    ['strain_001.tif', 'strain_002.tif', 'strain_003.tif']
+    """
+
+    filenames = []
+
+    # Find deformation image files
+    files = sorted(glob.glob(str(strain_files)))
+    if not files:
+        raise FileNotFoundError(f"No DIC data found: {strain_files}")
+
+    for file in files:
+        filenames.append(os.path.basename(file))
+
+    return filenames

pyvale/strain/strainimport.py

@@ -0,0 +1,303 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+
+import numpy as np
+import glob
+from pathlib import Path
+
+# pyvale
+from pyvale.strain.strainresults import StrainResults
+
+
+
+
+def import_2d(data: str | Path,
+                   binary: bool = False,
+                   layout: str = "matrix",
+                   delimiter: str = ",") -> StrainResults:
+    """
+    Import strain result data from human readable text or binary files.
+
+    Parameters
+    ----------
+
+    data : str or pathlib.Path
+        Path pattern to the data files (can include wildcards). Default is "./".
+
+    layout : str, optional
+        Format of the output data layout: "column" (flat array per frame) or "matrix" 
+        (reshaped grid per frame). Default is "column".
+
+    binary : bool, optional
+        If True, expects files in a specific binary format. If False, expects text data. 
+        Default is False.
+
+    delimiter : str, optional
+        Delimiter used in text data files. Ignored if binary=True. Default is a single space.
+
+    Returns
+    -------
+    StrainResults
+        A named container with the following fields:
+            - window_x, window_y (grid arrays if layout=="matrix"; otherwise, 1D integer arrays)
+            - def_grad, eps (deformation gradient and strain arrays with shape depending on layout)
+            - filenames (python list)
+
+    Raises
+    ------
+    ValueError:
+        If `layout` is not "column" or "matrix", or text data has insufficient columns,
+        or binary rows are malformed.
+        
+    FileNotFoundError:
+        If no matching data files are found.
+    """
+
+
+
+
+    print("")
+    print("Attempting Strain Data import...")
+    print("")
+    
+    # convert to str 
+    if isinstance(data, Path):
+        data = str(data)
+
+
+    files = sorted(glob.glob(data))
+    filenames = files
+    if not files:
+        raise FileNotFoundError(f"No results found in: {data}")
+
+    print(f"Found {len(files)} files containing Strain results:")
+    for file in files:
+        print(f"  - {file}")
+    print("")
+
+
+    # Read first file to define reference coordinates
+    read_data = read_binary if binary else read_text
+
+    window_x_ref, window_y_ref, *fields = read_data(files[0], delimiter=delimiter)
+    frames = [list(fields)]
+
+    for file in files[1:]:
+        window_x, window_y, *f = read_data(file, delimiter)
+        if not (np.array_equal(window_x_ref, window_x) and
+                np.array_equal(window_y_ref, window_y)):
+            raise ValueError("Mismatch in coordinates across frames.")
+        frames.append(f)
+
+    # Stack fields into arrays
+    arrays = [np.stack([frame[i] for frame in frames]) for i in range(8)]
+
+    # if reading into a matrix layout we need to convert to meshgrids
+    if layout == "matrix":
+
+        # create meshgrid
+        x_unique = np.unique(window_x_ref)
+        y_unique = np.unique(window_y_ref)
+        X, Y = np.meshgrid(x_unique, y_unique)
+
+        # convert results to a grid based on meshgrid dims
+        shape = (len(files), len(y_unique), len(x_unique))
+        arrays = [to_grid(a,shape,window_x_ref, window_y_ref, x_unique,y_unique) for a in arrays]
+
+
+        # combine strain results into single np.ndarray. current dimeensions of
+        # each array are (file,x,y). The results will become
+        # (file,x,y,matrix_x,def_matrix_y)
+        current_shape = arrays[0].shape # (file,x,y)
+        def_xx = np.zeros(current_shape)
+        def_xy = np.zeros(current_shape)
+        def_yx = np.zeros(current_shape)
+        def_yy = np.zeros(current_shape)
+        eps_xx = np.zeros(current_shape)
+        eps_xy = np.zeros(current_shape)
+        eps_yx = np.zeros(current_shape)
+        eps_yy = np.zeros(current_shape)
+
+
+        def_xx[:,:,:] = arrays[0]
+        def_xy[:,:,:] = arrays[1]
+        def_yx[:,:,:] = arrays[2]
+        def_yy[:,:,:] = arrays[3]
+        eps_xx[:,:,:] = arrays[4]
+        eps_xy[:,:,:] = arrays[5]
+        eps_yx[:,:,:] = arrays[6]
+        eps_yy[:,:,:] = arrays[7]
+
+
+        return StrainResults(X, Y,
+                             def_xx, def_xy, def_yx, def_yy,
+                             eps_xx, eps_xy, eps_yx, eps_yy,
+                             filenames)
+
+    else:
+        current_shape = arrays[0].shape
+        def_xx = np.zeros(current_shape)
+        def_xy = np.zeros(current_shape)
+        def_yx = np.zeros(current_shape)
+        def_yy = np.zeros(current_shape)
+        eps_xx = np.zeros(current_shape)
+        eps_xy = np.zeros(current_shape)
+        eps_yx = np.zeros(current_shape)
+        eps_yy = np.zeros(current_shape)
+        def_xx[:,:,:] = arrays[0]
+        def_xy[:,:,:] = arrays[1]
+        def_yx[:,:,:] = arrays[2]
+        def_yy[:,:,:] = arrays[3]
+        eps_xx[:,:,:] = arrays[4]
+        eps_xy[:,:,:] = arrays[5]
+        eps_yx[:,:,:] = arrays[6]
+        eps_yy[:,:,:] = arrays[7]
+        return StrainResults(window_x_ref, window_y_ref, 
+                             def_xx, def_xy, def_yx, def_yy,
+                             eps_xx, eps_xy, eps_yx, eps_yy,
+                             filenames)
+
+
+
+def read_binary(file: str, delimiter: str):
+    """
+    Read a binary Strain result file and extract DIC fields.
+
+    Assumes a fixed binary structure with each row containing:
+    - 2x int32 (subset coordinates)
+    - 8x float64 (deformation matrix, strain matrix)
+
+    Parameters
+    ----------
+    file : str
+        Path to the binary result file.
+
+    delimiter : str
+        Ignored for binary data (included for API consistency).
+
+    Returns
+    -------
+    tuple of np.ndarray
+        Arrays corresponding to:
+        (window_x, window_y, def_grad, eps)
+
+    Raises
+    ------
+    ValueError
+        If the binary file size does not align with expected row size.
+    """
+
+    row_size = (3 * 4 + 6 * 8)
+    with open(file, "rb") as f:
+        raw = f.read()
+    if len(raw) % row_size != 0:
+        raise ValueError("Binary file has incomplete rows.")
+
+    rows = len(raw) // row_size
+    arr = np.frombuffer(raw, dtype=np.uint8).reshape(rows, row_size)
+    
+    # lil function to make extracting a bit easier
+    def extract(col, dtype, start): 
+        return np.frombuffer(arr[:, start:start+col], dtype=dtype)
+
+    window_x = extract(4, np.int32, 0)
+    window_y = extract(4, np.int32, 4)
+    def_grad00 = extract(8, np.float64, 8)
+    def_grad01 = extract(8, np.float64, 16)
+    def_grad10 = extract(8, np.float64, 24)
+    def_grad11 = extract(8, np.float64, 32)
+    eps00 = extract(8, np.float64, 40)
+    eps01 = extract(8, np.float64, 48)
+    eps10 = extract(8, np.float64, 56)
+    eps11 = extract(8, np.float64, 72)
+
+    return window_x, window_y, def_grad00, def_grad01, def_grad10, def_grad11, eps00, eps01, eps10, eps11
+
+
+
+
+def read_text(file: str, delimiter: str):
+    """
+    Read a human-readable text DIC result file and extract DIC fields.
+
+    Expects at least 9 columns:
+    [ss_x, ss_y, u, v, m, cost, ftol, xtol, niter]
+
+    Parameters
+    ----------
+    file : str
+        Path to the text result file.
+
+    delimiter : str
+        Delimiter used in the text file (e.g., space, tab, comma).
+
+    Returns
+    -------
+    tuple of np.ndarray
+        Arrays corresponding to:
+        (ss_x, ss_y, u, v, m, cost, ftol, xtol, niter)
+
+    Raises
+    ------
+    ValueError
+        If the text file has fewer than 9 columns.
+    """
+
+    data = np.loadtxt(file, delimiter=delimiter, skiprows=1)
+    if data.shape[1] < 9:
+        raise ValueError("Text data must have at least 9 columns.")
+    return (
+        data[:, 0].astype(np.int32), # window_x
+        data[:, 1].astype(np.int32), # window_y
+        data[:, 2], data[:, 3], data[:, 4], data[:, 5], #def_grad
+        data[:, 6], data[:, 7], data[:, 8], data[:, 9]  #eps
+    )
+
+
+
+
+
+
+def to_grid(data, shape, ss_x_ref, ss_y_ref, x_unique, y_unique):
+    """
+    Reshape a 2D DIC field from flat (column) format into grid (matrix) format.
+
+    This is used when output layout is specified as "matrix".
+    Maps values using reference subset coordinates (ss_x_ref, ss_y_ref).
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Array of shape (n_frames, n_points) to be reshaped into (n_frames, height, width).
+
+    shape : tuple
+        Target shape of output array: (n_frames, height, width).
+
+    ss_x_ref : np.ndarray
+        X coordinates of subset centers.
+
+    ss_y_ref : np.ndarray
+        Y coordinates of subset centers.
+
+    x_unique : np.ndarray
+        Sorted unique X coordinates in the grid.
+
+    y_unique : np.ndarray
+        Sorted unique Y coordinates in the grid.
+
+    Returns
+    -------
+    np.ndarray
+        Reshaped array with shape `shape`, filled with NaNs where no data exists.
+    """
+
+    grid = np.full(shape, np.nan)
+    for i, (x, y) in enumerate(zip(ss_x_ref, ss_y_ref)):
+        x_idx = np.where(x_unique == x)[0][0]
+        y_idx = np.where(y_unique == y)[0][0]
+        grid[:, y_idx, x_idx] = data[:, i]
+    return grid

pyvale/strain/strainresults.py

@@ -0,0 +1,55 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+
+from dataclasses import dataclass
+import numpy as np
+
+@dataclass(slots=True)
+class StrainResults:
+    """
+    Data container for Strain analysis results.
+
+    This dataclass stores the strain window coordinates, 2D deformation gradient
+    and strain values.
+
+    Attributes
+    ----------
+    window_x : np.ndarray
+        The x-coordinates of the strain window centre. shape=(img_num,y,x)
+    window_y : np.ndarray
+        The y-coordinates of the strain window centre. shape=(img_num,y,x)
+    def_xx : np.ndarray
+        The xx component of the 2D deformation gradient. shape=(img_num,y,x)
+    def_xy : np.ndarray
+        The xy component of the 2D deformation gradient. shape=(img_num,y,x)
+    def_yx : np.ndarray
+        The yx component of the 2D deformation gradient. shape=(img_num,y,x)
+    def_yy : np.ndarray
+        The yy component of the 2D deformation gradient. shape=(img_num,y,x)
+    eps_xx : np.ndarray
+        The xx component of the 2D strain tensor. shape=(img_num,y,x)
+     eps_xy : np.ndarray
+        The xy component of the 2D strain tensor. shape=(img_num,y,x)
+     eps_yx : np.ndarray
+        The yx component of the 2D strain tensor. shape=(img_num,y,x)
+     eps_yy : np.ndarray
+        The yy component of the 2D strain tensor. shape=(img_num,y,x)
+    filenames : list[str]
+        name of Strain result files that have been found
+    """
+
+    window_x: np.ndarray
+    window_y: np.ndarray
+    def_xx: np.ndarray
+    def_xy: np.ndarray
+    def_yx: np.ndarray
+    def_yy: np.ndarray
+    eps_xx: np.ndarray
+    eps_xy: np.ndarray
+    eps_yx: np.ndarray
+    eps_yy: np.ndarray
+    filenames: list[str]