Merge branch 'master' of https://github.com/fortran-lang/stdlib into add-pkg-config-ci

Author: srinjoy933

.github/workflows/ci_big_endian.yml

@@ -0,0 +1,68 @@
+name: CI - Big-Endian
+
+on:
+  # Always run on pushes to the main branch
+  push:
+    branches: [master, main]
+  # For PRs, ONLY run if the hash files or this workflow change
+  pull_request:
+    paths:
+      - '.github/workflows/ci_big_endian.yml'
+      - 'src/hash/**'
+      - 'test/hash_functions/**'
+  # Allow manual triggers from the GitHub Actions tab
+  workflow_dispatch:
+
+env:
+  CTEST_TIME_TIMEOUT: "5"  # some failures hang forever
+
+jobs:
+  test-big-endian:
+    runs-on: ubuntu-24.04
+    name: Test on s390x (big-endian)
+    strategy:
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build and test on s390x
+        uses: uraimo/run-on-arch-action@v3
+        with:
+          arch: s390x
+          distro: ubuntu24.04
+
+          # Cache Docker image layer in GitHub Package Registry
+          githubToken: ${{ github.token }}
+
+          # Install dependencies (cached in Docker image layer)
+          install: |
+            apt-get update -q -y
+            apt-get install -q -y gfortran gcc g++ cmake python3-pip ninja-build git
+            pip3 install --break-system-packages fypp
+
+          # Build and run big-endian tests
+          run: |
+            echo "=== Architecture Info ==="
+            uname -m
+            echo "Byte order: $(python3 -c 'import sys; print(sys.byteorder)')"
+
+            echo "=== Compiler Version ==="
+            gfortran --version
+
+            echo "=== CMake Configure ==="
+            cmake -G Ninja \
+              -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_MAXIMUM_RANK:String=4 \
+              -DFIND_BLAS:STRING=FALSE \
+              -S . -B build
+
+            echo "=== Build (Targeted) ==="
+            cmake --build build --target test_hash_functions --parallel
+
+            echo "=== Run Big-Endian Tests ==="
+            ctest --test-dir build \
+              -R hash_functions \
+              --output-on-failure \
+              --no-tests=error

.github/workflows/fpm-deployment.yml

@@ -46,6 +46,10 @@ jobs:
           python config/fypp_deployment.py --with_xdp --with_qp
           fpm test --profile release --flag '-DWITH_XDP -DWITH_QP'
 
+      - run: | # Tests without xdp and qp
+          python config/fypp_deployment.py
+          fpm test --profile release
+
       # Update and deploy the f90 files generated by github-ci to the `stdlib-fpm` branch.
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@4.1.5

doc/specs/stdlib_hash_procedures.md

@@ -394,6 +394,16 @@ generating seeds for `universal_mult_hash`.
 All assume a two's complement sign bit, and no out of
 range checks.
 
+**Endianness note:** Both `pengy_hash` and `spooky_hash` will produce
+different hash values on big-endian processors (e.g., s390x, SPARC,
+PowerPC) compared to little-endian processors (e.g., x86, ARM, RISC-V)
+for the same input bytes. The hash quality is equally good on both
+architectures, but the outputs are not cross-architecture portable.
+Do not use these hashes for cross-architecture verification (e.g.,
+hashing a file on an x86 system and verifying the hash on an IBM
+mainframe). The 32-bit hashes `nmhash32`, `nmhash32x`, and
+`water_hash` produce identical results on all architectures.
+
 The `stdlib_hash_32bit_fnv` and `stdlib_hash_64bit_fnv`
 submodules each provide implementations of the FNV-1 and FNV-1A
 algorithms in the form of two separate overloaded functions: `FNV_1`
@@ -1366,6 +1376,9 @@ performance on long keys. It passes all the SMHasher tests, and has
 no known bad seeds.
 It is a *pure* function for integer arrays, and an *elemental*
 function for character strings.
+Note that `pengy_hash` will produce different hash values on
+big-endian and little-endian processors for the same input. The hash
+quality is equally good on both architectures.
 
 ##### Example
 

doc/specs/stdlib_linalg.md

@@ -1111,6 +1111,100 @@ call [stdlib_linalg(module):constrained_lstsq_space(interface)]`(a,  c,  lwork [
 `c`: Shall be a rank-2 `real` or `complex` array of the same kind as `a` defining the linear equality constraints. It is an `intent(in)` argument.
 `lwork`: Shall be an `integer` scalar returning the optimal size required for the workspace array to solve the constrained least-squares problem.
 
+## `weighted_lstsq` - Computes the weighted least squares solution to a linear matrix equation {#weighted-lstsq}
+
+### Status
+
+Experimental
+
+### Description
+
+This function computes the weighted least-squares solution to a linear matrix equation \( A \cdot x = b \) where each observation has a different weight.
+
+The solver minimizes the weighted 2-norm \( \| D(Ax - b) \|_2^2 \) where \( D = \mathrm{diag}(\sqrt{w}) \) is a diagonal matrix formed from the square roots of the weight vector. This is equivalent to transforming the problem to ordinary least-squares through row scaling. The solver is based on LAPACK's `*GELSD` backends.
+
+### Syntax
+
+`x = ` [[stdlib_linalg(module):weighted_lstsq(interface)]] `(w, a, b [, cond, overwrite_a, rank, err])`
+
+### Arguments
+
+`w`: Shall be a rank-1 `real` array containing the weight vector. For complex `a` and `b`, `w` shall use the same real kind as the components of `a`. All weights must be positive. It is an `intent(in)` argument.
+
+`a`: Shall be a rank-2 `real` or `complex` array containing the coefficient matrix. It is an `intent(inout)` argument.
+
+`b`: Shall be a rank-1 array of the same kind as `a`, containing the right-hand-side vector. It is an `intent(in)` argument.
+
+`cond` (optional): Shall be a scalar `real` value cut-off threshold for rank evaluation: singular values with `s_i <= cond*maxval(s)` are treated as zero, and the rank counts values with `s_i > cond*maxval(s), i=1:rank`. Shall be a scalar, `intent(in)` argument.
+
+`overwrite_a` (optional): Shall be an input `logical` flag. If `.true.`, input matrix `a` will be used as temporary storage and overwritten. This avoids internal data allocation. This is an `intent(in)` argument.
+
+`rank` (optional): Shall be an `integer` scalar value, that contains the rank of input matrix `a`. This is an `intent(out)` argument.
+
+`err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument.
+
+### Return value
+
+Returns an array value of the same kind as `a`, containing the weighted least-squares solution.
+
+Raises `LINALG_VALUE_ERROR` if any weight is non-positive or if the matrix and weight/right-hand-side have incompatible sizes.
+Raises `LINALG_ERROR` if the underlying Singular Value Decomposition process did not converge.
+Exceptions trigger an `error stop`.
+
+### Example
+
+```fortran
+{!example/linalg/example_weighted_lstsq.f90!}
+```
+
+## `solve_weighted_lstsq` - Compute the weighted least squares solution to a linear matrix equation (subroutine interface). {#solve-weighted-lstsq}
+
+### Status
+
+Experimental
+
+### Description
+
+This subroutine computes the weighted least-squares solution to a linear matrix equation \( A \cdot x = b \) where each observation has a different weight.
+
+The solver minimizes the weighted 2-norm \( \| D(Ax - b) \|_2^2 \) where \( D = \mathrm{diag}(\sqrt{w}) \) is a diagonal matrix formed from the square roots of the weight vector. This is equivalent to transforming the problem to ordinary least-squares through row scaling. The solver is based on LAPACK's `*GELSD` backends.
+
+### Syntax
+
+`call ` [[stdlib_linalg(module):solve_weighted_lstsq(interface)]] `(w, a, b, x [, cond, overwrite_a, rank, err])`
+
+### Arguments
+
+`w`: Shall be a rank-1 `real` array containing the weight vector. For complex `a` and `b`, `w` shall use the same real kind as the components of `a`. All weights must be positive. It is an `intent(in)` argument.
+
+`a`: Shall be a rank-2 `real` or `complex` array containing the coefficient matrix. It is an `intent(inout)` argument.
+
+`b`: Shall be a rank-1 array of the same kind as `a`, containing the right-hand-side vector. It is an `intent(in)` argument.
+
+`x`: Shall be a rank-1 array of the same kind as `a`, and size of at least `n`, containing the solution to the weighted least squares system. It is an `intent(inout)` argument.
+
+`cond` (optional): Shall be a scalar `real` value cut-off threshold for rank evaluation: singular values with `s_i <= cond*maxval(s)` are treated as zero, and the rank counts values with `s_i > cond*maxval(s), i=1:rank`. Shall be a scalar, `intent(in)` argument.
+
+`overwrite_a` (optional): Shall be an input `logical` flag. If `.true.`, input matrix `a` will be used as temporary storage and overwritten. This avoids internal data allocation. This is an `intent(in)` argument.
+
+`rank` (optional): Shall be an `integer` scalar value, that contains the rank of input matrix `a`. This is an `intent(out)` argument.
+
+`err` (optional): Shall be a `type(linalg_state_type)` value. This is an `intent(out)` argument.
+
+### Return value
+
+Returns an array value of the same kind as `a`, containing the weighted least-squares solution.
+
+Raises `LINALG_VALUE_ERROR` if any weight is non-positive or if the matrix and weight/right-hand-side have incompatible sizes.
+Raises `LINALG_ERROR` if the underlying Singular Value Decomposition process did not converge.
+Exceptions trigger an `error stop`.
+
+### Example
+
+```fortran
+{!example/linalg/example_weighted_lstsq.f90!}
+```
+
 ## `det` - Computes the determinant of a square matrix
 
 ### Status

doc/specs/stdlib_stats.md

@@ -283,6 +283,110 @@ If `mask` is specified, the result is the _k_-th  (central) moment of all elemen
 {!example/stats/example_moment.f90!}
 ```
 
+## `pca` - Principal Component Analysis
+
+### Status
+
+Experimental
+
+### Description
+
+Performs Principal Component Analysis (PCA) on a 2D array of observations and features.
+The input matrix `x` has shape `(m, n)`, where `m` is the number of observations and `n` is the number of features.
+The subroutine computes the principal components (loadings), the singular values, and optionally the feature means.
+
+Two methods are supported:
+- `"svd"`: (Default) Computes PCA via Singular Value Decomposition of the centered data. This is generally more numerically stable.
+- `"eig"` or `"cov"`: Computes PCA via Eigendecomposition of the covariance matrix.
+
+### Syntax
+
+`call ` [[stdlib_stats(module):pca(interface)]] `(x, components, singular_values [, x_mean, method, overwrite_x, err])`
+
+### Class
+
+Generic subroutine
+
+### Arguments
+
+`x`: Shall be a rank-2 real array with shape `(m, n)`. It is an `intent(inout)` argument. If `overwrite_x` is `.true.`, `x` may be modified during computation.
+
+`components`: Shall be a rank-2 real array with shape `(n_components, n)`. It stores the principal components as rows. It is an `intent(out)` argument.
+
+`singular_values`: Shall be a rank-1 real array with shape `(n_components)`. It stores the singular values in descending order. It is an `intent(out)` argument.
+
+`x_mean` (optional): Shall be a rank-1 real array with shape `(n)`. It stores the mean of each feature (column). It is an `intent(out)` argument.
+
+`method` (optional): Shall be a character string. Either `"svd"` or `"eig"`/`"cov"`. It is an `intent(in)` argument.
+
+`overwrite_x` (optional): Shall be a scalar of type `logical`. If `.true.`, the input matrix `x` can be used as a workspace and modified. It is an `intent(in)` argument.
+
+`err` (optional): Shall be of type `linalg_state_type`. It is an `intent(out)` argument.
+
+### Example
+
+```fortran
+{!example/stats/example_pca.f90!}
+```
+
+## `pca_transform` - Projects data into principal component space
+
+### Status
+
+Experimental
+
+### Description
+
+Projects the input data `x` into the reduced dimensional space defined by the provided principal components.
+The transformation is defined as `x_transformed = (x - x_mean) * components^T`.
+
+### Syntax
+
+`call ` [[stdlib_stats(module):pca_transform(interface)]] `(x, components, x_transformed [, x_mean])`
+
+### Class
+
+Generic subroutine
+
+### Arguments
+
+`x`: Shall be a rank-2 real array with shape `(m, n)`. It is an `intent(in)` argument.
+
+`components`: Shall be a rank-2 real array with shape `(nc, n)`. It stores the principal components as rows. It is an `intent(in)` argument.
+
+`x_transformed`: Shall be a rank-2 real array with shape `(m, nc)`. It stores the projected data. It is an `intent(out)` argument.
+
+`x_mean` (optional): Shall be a rank-1 real array with shape `(n)`. It stores the feature means to subtract. It is an `intent(in)` argument.
+
+## `pca_inverse_transform` - Reconstructs original data from principal component space
+
+### Status
+
+Experimental
+
+### Description
+
+Reconstructs the original data representation from the principal component space.
+The reconstruction is defined as `x_reconstructed = x_reduced * components + x_mean`.
+
+### Syntax
+
+`call ` [[stdlib_stats(module):pca_inverse_transform(interface)]] `(x_reduced, components, x_reconstructed [, x_mean])`
+
+### Class
+
+Generic subroutine
+
+### Arguments
+
+`x_reduced`: Shall be a rank-2 real array with shape `(m, nc)`. It is an `intent(in)` argument.
+
+`components`: Shall be a rank-2 real array with shape `(nc, n)`. It stores the principal components as rows. It is an `intent(in)` argument.
+
+`x_reconstructed`: Shall be a rank-2 real array with shape `(m, n)`. It stores the reconstructed data. It is an `intent(out)` argument.
+
+`x_mean` (optional): Shall be a rank-1 real array with shape `(n)`. It stores the feature means to add back. It is an `intent(in)` argument.
+
 ## `var` - variance of array elements
 
 ### Status

doc/specs/stdlib_str2num.md

@@ -75,8 +75,8 @@ The accuracy of the conversion is implementation dependent; it is recommended th
 
 `sp`  : exact match
 
-`dp`  : precision up-to epsilon(0.0_dp)
+`dp`  : precision up-to 10*epsilon(0.0_dp)
 
-`qp` : precision around 200*epsilon(0.0_qp)
+`qp` : precision around 100*epsilon(0.0_qp)
 
 Where precision refers to the relative difference between `to_num` and `read`. On the other hand, `to_num` provides speed-ups ranging from 4x to >10x compared to the intrinsic `read`.

example/linalg/CMakeLists.txt

@@ -37,6 +37,7 @@ ADD_EXAMPLE(lstsq1)
 ADD_EXAMPLE(lstsq2)
 ADD_EXAMPLE(constrained_lstsq1)
 ADD_EXAMPLE(constrained_lstsq2)
+ADD_EXAMPLE(weighted_lstsq)
 ADD_EXAMPLE(norm)
 ADD_EXAMPLE(mnorm)
 ADD_EXAMPLE(get_norm)

example/linalg/example_weighted_lstsq.f90

@@ -0,0 +1,32 @@
+! Weighted least-squares solver: function and subroutine interfaces
+program example_weighted_lstsq
+  use stdlib_linalg_constants, only: dp
+  use stdlib_linalg, only: weighted_lstsq, solve_weighted_lstsq
+  implicit none
+
+  real(dp) :: A(4,2), b(4), w(4), x_sub(2)
+  real(dp), allocatable :: x(:)
+
+  ! Design matrix: intercept + slope
+  A(:,1) = 1.0_dp
+  A(:,2) = [1.0_dp, 2.0_dp, 3.0_dp, 4.0_dp]
+
+  ! Observations (one outlier at position 3)
+  b = [2.1_dp, 4.0_dp, 10.0_dp, 7.9_dp]
+
+  ! Weights: downweight the outlier
+  w = [1.0_dp, 1.0_dp, 0.1_dp, 1.0_dp]
+
+  ! Solve weighted least-squares (function interface)
+  x = weighted_lstsq(w, A, b)
+
+  print '("Function interface:  intercept = ",f8.4,", slope = ",f8.4)', x(1), x(2)
+  ! Function interface:  intercept =   0.1500, slope =   1.9911
+
+  ! Solve weighted least-squares (subroutine interface)
+  call solve_weighted_lstsq(w, A, b, x_sub)
+
+  print '("Subroutine interface: intercept = ",f8.4,", slope = ",f8.4)', x_sub(1), x_sub(2)
+  ! Subroutine interface: intercept =   0.1500, slope =   1.9911
+
+end program example_weighted_lstsq