pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/dic/cpp/dicsubset.hpp

@@ -0,0 +1,122 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+#ifndef DICSUBSET_H
+#define DICSUBSET_H
+
+// STD library Header files
+#include <vector>
+
+// Program Header files
+#include "./dicinterpolator.hpp"
+
+namespace subset {
+
+    struct Grid {
+        int num;
+        int step;
+        int size;
+        int num_ss_x;
+        int num_ss_y;
+        int num_in_mask;
+        std::vector<int> coords;
+        std::vector<int> mask;
+        std::vector<std::vector<int>> neigh;
+    };
+
+    /**
+     * @brief holds a subset with pixel data and dimensions.
+     * 
+     * This struct holds the pixel values, coordinates, and dimensions of a square subset.
+     */
+    struct Pixels {
+        std::vector<double> vals;
+        std::vector<double> x;
+        std::vector<double> y;
+        int size;
+        int num_px;
+
+        // Constructor to initialize the vectors with ss_size
+        Pixels(int ss_size) 
+            : vals(ss_size * ss_size, 0.0),
+            x(ss_size * ss_size, 0.0),
+            y(ss_size * ss_size, 0.0),
+            size(ss_size),
+            num_px(ss_size * ss_size)
+        {}
+    };
+
+    /**
+     * @brief Extracts a square subset of pixels from an image and stores the data in a Subset object.
+     * 
+     * This function copies a square region of pixel data from the specified starting coordinates 
+     * (`ss_x`, `ss_y`) in the input image into the `ss_def` structure. The size of the square 
+     * subset is determined by `ss_def->size`. Both the pixel values and their corresponding 
+     * coordinates are stored in `ss_def`.
+     * 
+     * @param ss_x        X-coordinate (column) of the top-left corner of the subset in the image.
+     * @param ss_y        Y-coordinate (row) of the top-left corner of the subset in the image.
+     * @param img_def   Pointer to the source image (`util::Image`) from which to extract pixel data.
+     * @param ss_def      Pointer to the destination subset (`subset::Pixels`) where extracted pixel 
+     *                    values and coordinates are stored.
+     */            
+    void get_px_from_img(subset::Pixels &ss_ref,
+                    const int ss_x, const int ss_y,
+                    const int px_hori,
+                    const int px_vert,
+                    const double *img_def);
+
+
+    /**
+     * @brief Extracts a square subset of pixels from an image and stores the data in a Subset object.
+     * 
+     * This function copies a square region of pixel data from the specified starting coordinates 
+     * (`ss_x`, `ss_y`) in the input image into the `ss_def` structure. The size of the square 
+     * subset is determined by `ss_def->size`. Both the pixel values and their corresponding 
+     * coordinates are stored in `ss_def`.
+     * 
+     * @param ss_ref      Pointer to the destination subset (`subset::Pixels`) where extracted pixel info will be stored
+     * @param ss_x        X-coordinate (column) of the top-left corner of the subset in the image.
+     * @param ss_y        Y-coordinate (row) of the top-left corner of the subset in the image.
+     * @param interp_ref  interpolator for the reference image from which to extract pixel data.
+     */
+    void get_subpx_from_img(subset::Pixels &ss_def, 
+                          const double subpx_x, const double subpx_y, 
+                          const Interpolator &interp_def);
+
+    /**
+     *
+     */
+    void get_subpx_from_shape_params(subset::Pixels &ss_def, 
+                                     const double subpx_x, const double subpx_y,
+                                     const std::vector<double>& p,
+                                     const Interpolator &interp_def);
+
+    /**
+     * @brief Generates a list of subsets based on the provided image ROI and parameters.
+     * 
+     * This function creates a list of subsets (defined by their coordinates) from a binary mask 
+     * (`img_roi`) that indicates the region of interest in the image. The subsets are generated 
+     * with specified size and step values.
+     * 
+     * @param img_roi    Pointer to a binary mask indicating the region of interest in the image.
+     * @param px_hori Number of horizontal pixels in the image.
+     * @param px_vert   Number of vertical pixels in the image.
+     * @param ss_size      Size of each subset (in pixels).
+     * @param ss_step      Step size for generating subsets.
+     * @return            A subset::Grid object containing the generated subsets and their neighbours.
+     */
+    subset::Grid create_grid(const bool *img_roi, const int ss_step, const int ss_size, 
+                           const int px_hori, const int px_vert, const bool partial=false);
+
+    
+    inline bool px_in_img_dims(const int px_x, const int px_y, const int px_hori, 
+                        const int px_vert);
+
+    inline bool px_in_roi(const int px_x, const int px_y, const int px_hori, 
+                        const int px_vert, const bool *img_roi);
+}
+#endif // DICSMOOTH_H

pyvale/dic/cpp/dicutil.cpp

@@ -0,0 +1,108 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+
+// STD library Header files
+#include <cstdlib>
+#include <iostream>
+#include <fstream>
+#include <sstream>
+#include <vector>
+#include <cmath>
+#include <omp.h>
+
+// common_cpp Header files
+#include "../../common_cpp/util.hpp"
+
+// DIC Header files
+#include "./dicutil.hpp"
+#include "./dicsubset.hpp"
+
+
+namespace util {
+
+
+    std::vector<int> niter_arr;
+    std::vector<double> u_arr;
+    std::vector<double> v_arr;
+    std::vector<double> p_arr;
+    std::vector<double> ftol_arr;
+    std::vector<double> xtol_arr;
+    std::vector<double> cost_arr;
+    std::vector<uint8_t> conv_arr;
+    bool at_end;
+
+
+
+    void extract_image(double *img_def_stack, 
+                       int image_number,
+                       int px_hori,
+                       int px_vert){
+
+        int count = 0;
+        for (int px_y = 0; px_y < px_vert; px_y++){
+            for (int px_x = 0; px_x < px_hori; px_x++){
+                int idx = image_number * px_hori * px_vert + px_y * px_hori + px_x;
+                std::cout << img_def_stack[idx] << " ";
+                //img_def->vals[count] = img_def_stack[idx];
+                count++;
+            }
+            std::cout << std::endl;
+        }
+        exit(0);
+    }
+
+    int next_pow2(int n) {
+        if (n <= 0){
+            std::cerr << __FILE__ << " " << __LINE__ << std::endl;
+            std::cerr << "Expected a positive integer to calculate next power of 2 " << std::endl;
+            std::cerr << "n = " << n << std::endl;
+            exit(EXIT_FAILURE);
+        }
+
+        // If already a power of 2, return as-is
+        if ((n & (n - 1)) == 0) return n;
+
+        n--;
+        n |= n >> 1;
+        n |= n >> 2;
+        n |= n >> 4;
+        n |= n >> 8;
+        n |= n >> 16;
+        n++;
+
+        // Handle possible overflow
+        if (n < 0) return std::numeric_limits<int>::max();
+
+        return n;
+    }
+
+
+    void gen_size_and_step_vector(std::vector<int> &ss_sizes, std::vector<int> &ss_steps, 
+                                  const int ss_size, const int ss_step, const int max_disp) {
+
+        ss_sizes.clear();
+        ss_steps.clear();
+
+        int power = next_pow2(max_disp);
+
+        // Generate sizes down to just above ss_size
+        while (power > ss_size) {
+            ss_sizes.push_back(power);
+            ss_steps.push_back(power / 2);
+            power /= 2;
+        }
+
+        // Finally, add the original ss_size and ss_step
+        ss_sizes.push_back(ss_size);
+        ss_steps.push_back(ss_step);
+
+        // debugging
+        //for (size_t i = 0; i < ss_sizes.size(); ++i) {
+        //    std::cout << "ss_size = " << ss_sizes[i] << ", step = " << ss_steps[i] << std::endl;
+        //}
+    }
+}

pyvale/dic/cpp/dicutil.hpp

@@ -0,0 +1,96 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+
+#ifndef DICUTIL_H
+#define DICUTIL_H
+
+// STD library Header files
+#include <vector>
+#include <string>
+
+// common_cpp header files
+
+// program Header files
+
+
+namespace util {
+
+
+    // Custom hash from above
+    struct PairHash {
+        std::size_t operator()(const std::pair<int, int>& p) const {
+            return std::hash<int>()(p.first) ^ (std::hash<int>()(p.second) << 1);
+        }
+    };
+
+
+
+    struct Config {
+        int ss_step;
+        int ss_size;
+        int max_iter;
+        int px_hori;
+        int px_vert;
+        int num_def_img;
+        int num_params;
+        double precision;
+        double threshold;
+        double bf_threshold;
+        int max_disp;
+        std::pair<int, int> rg_seed;
+        std::string corr_crit;
+        std::string shape_func;
+        std::string interp_routine;
+        std::string scan_method;
+        std::vector<std::string> filenames;
+        bool fft_mad;
+        double fft_mad_scale;
+        unsigned int debug_level;
+    };
+
+
+
+
+    /**
+     * @brief Represents an image with pixel data and dimensions.
+     * 
+     * This struct holds the pixel values of an image along with its
+     * dimensions. The pixel data is stored in row-major order.
+     */
+    struct Image {
+        double *vals;
+        int px_hori;
+        int px_vert;
+        int num;
+    };
+
+
+    /**
+     * @brief Extracts a single image from a stacked image array and stores it in an `Image` object.
+     * 
+     * Takes a specific 2D image (identified by `image_number`) from a 3D image stack 
+     * (`img_def_stack`) and stores its pixel values into the `vals` field of the provided 
+     * `util::Image` structure.
+     * 
+     * @param img_def        Pointer to a `util::Image` object that will be populated with the extracted image data.
+     * @param img_def_stack  Pointer to a flat array representing a stack of images stored sequentially 
+     *                         (row-major order).
+     * @param image_number     Index of the image to extract from the stack (0-based).
+     */
+    void extract_image(double *img_def_stack, 
+                       int image_number,
+                       int px_hori,
+                       int px_vert);
+
+    int next_pow2(int n);
+
+    void gen_size_and_step_vector(std::vector<int> &ss_sizes, std::vector<int> &ss_steps, 
+                                  const int ss_size, const int ss_step, const int max_disp);
+
+}
+
+#endif //DICUTIL

pyvale/dic/cuda/malloc.cu

@@ -0,0 +1,99 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+
+// cpp header files
+#include <cuda.h>
+#include <cstring>
+#include <curand.h>
+#include <iostream>
+#include <cuda_runtime.h>
+
+// STD library Header files
+#include "../cpp/defines.hpp"
+
+namespace cuglobal {
+
+
+    //gpu variables
+	int tpb;
+	int bpg;
+
+
+    void device_info(int n_ss){
+            
+        TITLE("CUDA DEVICE PROPERTIES");
+        
+        
+        // Get number of available GPU devices
+        int devicesCount;
+        cudaGetDeviceCount(&devicesCount);
+        INFO_OUT("Number of available GPU devices:", devicesCount);	
+    
+        std::string devicename_str;
+        struct cudaDeviceProp properties;
+        
+        for (int i = 0; i < devicesCount; i++){
+            cudaGetDeviceProperties(&properties, i);
+            devicename_str = "Name of device " + std::to_string(i) + ":";	
+            INFO_OUT(devicename_str, properties.name);
+        }
+        
+        // check if device has been selected in config file	
+        int device = 0;	
+        if ((devicesCount != 1)) {
+            std::cout << "More than one GPU has been found. No Specific GPU has been selected. \n";
+            std::cout << "GPU has been automatically assigned to device 0. \n";
+        }
+
+        cudaSetDevice(device);
+        cudaGetDeviceProperties(&properties, device);
+        
+        // print GPU information to stdout
+        INFO_OUT("Device name:", properties.name);
+        INFO_OUT("Memory Clock Rate (KHz):", properties.memoryClockRate);
+        INFO_OUT("Memory Bus Width (bits):", properties.memoryBusWidth);
+        INFO_OUT("Peak Memory Bandwidth (GB/s):", 2.0*properties.memoryClockRate*(properties.memoryBusWidth/8)/1.0e6);
+        INFO_OUT("Total Device Global Memory (Mb):", properties.totalGlobalMem/1024/1024)
+        INFO_OUT("Total Device Constant Memory (Kb):", properties.totalConstMem/1024)
+        INFO_OUT("Device major.minor:", properties.major << "." << properties.minor)
+        INFO_OUT("Device registers per block:", properties.regsPerBlock);
+        INFO_OUT("multiprocessors:", properties.multiProcessorCount);
+        INFO_OUT("max threads per processor:", properties.maxThreadsPerMultiProcessor);
+        INFO_OUT("max threads per block:", properties.maxThreadsPerBlock);	
+        
+        tpb =  256;
+        bpg = (n_ss + tpb - 1) / tpb;
+
+        INFO_OUT("Simulation Threads Per Block:", tpb);
+        INFO_OUT("Simulation Blocks Per grid:", bpg);
+        
+    }
+
+    // void clear_memory(){
+    //     CUDA_CALL(cudaFree(dSx1d));
+    //     std::cout << "Deallocated GPU memory."
+    // }
+
+
+    // void allocate_memory(){
+
+    //     //Device spin variables
+    //     CUDA_CALL(cudaMalloc((void**)&dSx1d, sizeof(double)*params::Nspins));
+    //     CUDA_CALL(cudaMemset(cuheun::Sdashnx, 0.0, sizeof(double) * params::Nspins));
+
+    // }
+
+    // void copy_to_gpu(){
+	// 	CUDA_CALL(cudaMemset(cuheun::Sdashnx, 0.0, sizeof(double) * params::Nspins));
+
+    // }
+
+    // void copy_to_cpu
+	// 	CUDA_CALL(cudaMemset(cuheun::Sdashnx, 0.0, sizeof(double) * params::Nspins));
+    // }
+
+}

pyvale/dic/cuda/malloc.hpp

@@ -0,0 +1,17 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+
+// cpp header files
+
+
+// STD library Header files
+#include "../cpp/defines.hpp"
+
+namespace cuglobal {
+
+    void device_info(int n_ss);
+}

pyvale/dic/dic2d.py

@@ -0,0 +1,190 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+
+
+from logging import debug
+import numpy as np
+from pathlib import Path
+
+# pyvale
+import pyvale.dic.dic2dcpp as dic2dcpp
+import pyvale.dic.dicchecks as dicchecks
+import pyvale.common_py.util as common_py_util
+import pyvale.common_cpp.common_cpp as common_cpp
+
+def calculate_2d(reference: np.ndarray | str | Path,
+                 deformed: np.ndarray | str | Path | list[Path],
+                 roi_mask: np.ndarray,
+                 seed: list[int] | list[np.int32] | np.ndarray,
+                 subset_size: int = 21,
+                 subset_step: int = 10,
+                 correlation_criteria: str="ZNSSD",
+                 shape_function: str="AFFINE",
+                 interpolation_routine: str="BICUBIC",
+                 max_iterations: int=40,
+                 precision: float=0.001,
+                 threshold: float=0.9,
+                 bf_threshold: float=0.6,
+                 num_threads: int | None = None,
+                 max_displacement: int=128,
+                 method: str="MULTIWINDOW_RG",
+                 fft_mad: bool=False,
+                 fft_mad_scale: float=3.0,
+                 output_at_end: bool=False,
+                 output_basepath: Path | str = "./",
+                 output_binary: bool=False,
+                 output_prefix: str="dic_results_",
+                 output_delimiter: str=",",
+                 output_below_threshold: bool=False,
+                 output_shape_params: bool=False,
+                 debug_level: int=1) -> None:
+
+    """
+    Perform 2D Digital Image Correlation (DIC) between a reference image and one or more deformed images.
+
+    This function wraps a C++ DIC engine by preparing configuration parameters,
+    performing input validation, and dispatching image data and settings. It supports
+    pixel-level displacement and strain measurement over a defined region of interest (ROI).
+
+    Parameters
+    ----------
+    reference : np.ndarray, str or pathlib.Path
+        The reference image (2D array) or path to the image file.
+    deformed : np.ndarray, str , pathlib.Path or list[pathlib.Path]
+        The deformed image(s) (3D array for multiple images) or path/pattern to image files.
+    roi_mask : np.ndarray
+        A binary mask indicating the Region of Interest (ROI) for analysis (same size as image).
+    seed : list[int], list[np.int32] or np.ndarray
+        Coordinates `[x, y]` of the seed point for Reliability-Guided (RG) scanning, default is empty.
+    subset_size : int, optional
+        Size of the square subset window in pixels (default: 21).
+    subset_step : int, optional
+        Step size between subset centers in pixels (default: 10).
+    correlation_criteria : str, optional
+        Metric for matching subsets: "ZNSSD", "NSSD" or "SSD" (default: "ZNSSD").
+    shape_function : str, optional
+        Deformation model: e.g., "AFFINE", "RIGID" (default: "AFFINE").
+    interpolation_routine : str, optional
+        Interpolation method used on image intensity. "BICUBIC" is currently the
+        only supported option.
+    max_iterations : int, optional
+        Maximum number of iterations allowed for subset optimization (default: 40).
+    precision : float, optional
+        Precision threshold for iterative optimization convergence (default: 0.001).
+    threshold : float, optional
+        Minimum correlation/cost coefficient value to be considered a matching subset (default: 0.9).
+    num_threads : int, optional
+        Number of threads to use for parallel computation (default: None, uses all available).
+    bf_threshold : float, optional
+        Correlation threshold used in rigid bruteforce check for a subset to be considered a
+        good match(default: 0.6).
+    max_displacement : int, optional
+        Estimate for the Maximum displacement in any direction (in pixels) (default: 128).
+    method : str, optional
+        Subset scanning method: "RG" for Reliability-Guided (best overall approach), 
+        "IMAGE_SCAN" for a standard scan across the image with no seeding 
+        (best performance with for subpixel displacements with high quality images), 
+        "FFT" for a multi-window FFT based approach (Good for large displacements)
+    fft_mad : bool, optional
+        The option to smooth FFT windowing data by identifying and replacing outliers using 
+        a robust statistical method. For each subset, the function collects values from its 
+        neighboring subsets (within a 5x5 window, i.e., radius = 2), computes the median and 
+        Median Absolute Deviation (MAD), and determines whether the value at the current 
+        subset is an outlier. If it is, the value is replaced with the median of 
+        its neighbors. (default: False)
+    fft_mad_scale : bool, optional
+        An outlier is defined as a value whose deviation from the local median exceeds 
+        `fft_mad_scale` times the MAD. This value choses the scaling factor that determines 
+        the threshold for detecting outliers relative to the MAD.
+    output_at_end : bool, optional
+        If True, results will only be written at the end of processing (default: False).
+    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: "dic_results_"). 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: ",").
+    output_below_threshold : bool, optional
+        If True, subset results with cost values that did not exceed the cost threshold
+        will still be present in output (default: False).
+    output_shape_params : bool, optional
+        If True, all shape parameters will be saved in the output files (default: False).
+    debug_level:
+
+    Returns
+    -------
+    None
+        All outputs are written to files; no values are returned.
+
+    Raises
+    ------
+    ValueError
+        If input checks fail (e.g., invalid image sizes, unsupported parameters).
+    FileNotFoundError
+        If provided file paths do not exist.
+    """
+
+    if (debug_level>0):
+        dicchecks.print_title("Initial Checks")
+
+    # do checks on vars in python land
+    image_stack, roi_c, filenames = dicchecks.check_and_get_images(reference,deformed,roi_mask, debug_level)
+    dicchecks.check_correlation_criteria(correlation_criteria)
+    dicchecks.check_interpolation(interpolation_routine)
+    dicchecks.check_method(method)
+    dicchecks.check_thresholds(threshold, bf_threshold, precision)
+    common_py_util.check_output_directory(str(output_basepath), output_prefix, debug_level)
+    dicchecks.check_subsets(subset_size, subset_step)
+    updated_seed = dicchecks.check_and_update_rg_seed(seed, roi_mask, method, image_stack.shape[2], image_stack.shape[1], subset_size, subset_step)
+    num_params = dicchecks.check_shape_function(shape_function)
+
+
+    # Assign values to config struct for c++ land
+    config = dic2dcpp.Config()
+    config.ss_step = subset_step
+    config.ss_size = subset_size
+    config.max_iter = max_iterations
+    config.precision = precision
+    config.threshold = threshold
+    config.bf_threshold = bf_threshold
+    config.max_disp = max_displacement
+    config.corr_crit = correlation_criteria
+    config.shape_func = shape_function
+    config.interp_routine = interpolation_routine
+    config.scan_method = method
+    config.px_hori = image_stack.shape[2]
+    config.px_vert = image_stack.shape[1]
+    config.num_def_img = image_stack.shape[0]-1 # subtract ref image
+    config.num_params = num_params
+    config.rg_seed = updated_seed
+    config.filenames = filenames
+    config.fft_mad = fft_mad
+    config.fft_mad_scale = fft_mad_scale
+    config.debug_level = debug_level
+
+    # assigning c++ struct vals for save config
+    saveconf = common_cpp.SaveConfig()
+    saveconf.basepath = str(output_basepath)
+    saveconf.binary = output_binary
+    saveconf.prefix = output_prefix
+    saveconf.delimiter = output_delimiter
+    saveconf.at_end = output_at_end
+    saveconf.output_below_threshold = output_below_threshold
+    saveconf.shape_params = output_shape_params
+
+
+    #set the number of OMP threads
+    if num_threads is not None:
+        common_cpp.set_num_threads(num_threads)
+
+    # calling the c++ dic engine
+    with dic2dcpp.ostream_redirect(stdout=True, stderr=True):
+        dic2dcpp.dic_engine(image_stack, roi_c, config, saveconf)

pyvale/dic/dic2dconv.py

@@ -0,0 +1,6 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+