Adds functions to generate matrices

include/tensorwrapper/generate/add_noise.hpp

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 NWChemEx-Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <cstdint>
+#include <random>
+#include <tensorwrapper/tensor/tensor.hpp>
+
+namespace tensorwrapper::generate {
+
+/** @brief Adds clamped normal noise to each element of @p matrix.
+ *
+ *  Draws `delta ~ Normal(0, t)` and clamps to `[-t, t]` before adding to each
+ *  element. When @p t is zero the input is copied unchanged.
+ *
+ *  @param[in] matrix The tensor to perturb.
+ *  @param[in] t Non-negative noise scale (standard deviation and clamp bound).
+ *  @param[in,out] gen Random number generator used for the normal draws.
+ *
+ *  @return A new tensor with the same shape as @p matrix.
+ *
+ *  @throw std::invalid_argument if @p t is negative.
+ */
+Tensor add_noise(const Tensor& matrix, double t, std::mt19937& gen);
+
+Tensor add_noise(const Tensor& matrix, double t, std::uint64_t seed = 42);
+
+} // namespace tensorwrapper::generate

include/tensorwrapper/generate/generate.hpp

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026 NWChemEx-Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <tensorwrapper/generate/add_noise.hpp>
+#include <tensorwrapper/generate/generate_eigen_system.hpp>
+#include <tensorwrapper/generate/generate_eigenvalues.hpp>
+#include <tensorwrapper/generate/generate_utils.hpp>
+#include <tensorwrapper/generate/identity_matrix.hpp>
+#include <tensorwrapper/generate/random_orthogonal_matrix.hpp>
+
+namespace tensorwrapper::generate {}

include/tensorwrapper/generate/generate_eigen_system.hpp

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2026 NWChemEx-Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <cstddef>
+#include <tensorwrapper/generate/generate_utils.hpp>
+#include <tensorwrapper/tensor/tensor.hpp>
+
+namespace tensorwrapper::generate {
+
+struct EigenSystem {
+    std::size_t n = 0;
+    Tensor eigenvalues;
+    Tensor eigenvectors;
+    Tensor matrix;
+};
+
+EigenSystem generate_eigen_system(const SymmetricMatrixSpec& spec);
+
+} // namespace tensorwrapper::generate

include/tensorwrapper/generate/generate_eigenvalues.hpp

@@ -0,0 +1,131 @@
+/*
+ * Copyright 2026 NWChemEx-Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <algorithm>
+#include <cmath>
+#include <tensorwrapper/generate/generate_utils.hpp>
+#include <tensorwrapper/utilities/make_tensor.hpp>
+#include <vector>
+
+namespace tensorwrapper::generate {
+namespace {
+inline auto linear_spacing(std::size_t n, double lambda_min,
+                           double lambda_max) {
+    const auto dx = (lambda_max - lambda_min) / (n - 1);
+    std::vector<double> values(n);
+    for(std::size_t i = 0; i < n; ++i) {
+        values[i] = lambda_min + static_cast<double>(i) * dx;
+    }
+    return values;
+}
+
+inline auto logarithmic_spacing(std::size_t n, double lambda_min,
+                                double lambda_max) {
+    const double log_min = std::log(lambda_min);
+    const double log_max = std::log(lambda_max);
+    const double dlog    = (log_max - log_min) / (n - 1);
+    std::vector<double> values(n);
+    for(std::size_t i = 0; i < n; ++i) {
+        values[i] = std::exp(log_min + static_cast<double>(i) * dlog);
+    }
+    return values;
+}
+
+inline auto clustered_spacing(std::size_t n, std::size_t n_clusters,
+                              double lambda_min, double lambda_max,
+                              double cluster_width, std::mt19937& gen) {
+    std::uniform_real_distribution<double> jitter(-cluster_width,
+                                                  cluster_width);
+    std::vector<double> values(n);
+    std::vector<double> cluster_centers(n_clusters);
+    if(n_clusters == 1) {
+        cluster_centers[0] = lambda_min;
+    } else {
+        const double dx = (lambda_max - lambda_min) / (n_clusters - 1);
+        for(std::size_t c = 0; c < n_clusters; ++c) {
+            cluster_centers[c] = lambda_min + static_cast<double>(c) * dx;
+        }
+    }
+
+    for(std::size_t i = 0; i < n; ++i) {
+        const auto cluster_id = i % n_clusters;
+        values[i]             = cluster_centers[cluster_id] + jitter(gen);
+    }
+    return values;
+}
+
+inline auto degenerate_spacing(std::size_t n, std::size_t n_clusters,
+                               double lambda_min, double lambda_max) {
+    std::vector<double> values(n);
+    if(n_clusters <= 1) {
+        std::fill(values.begin(), values.end(), lambda_min);
+    } else {
+        const auto n_plateaus = std::min(n_clusters, n);
+        const auto nm1        = std::max<std::size_t>(1, n_plateaus - 1);
+        const double dx = (lambda_max - lambda_min) / static_cast<double>(nm1);
+        for(std::size_t i = 0; i < n; ++i) {
+            const auto plateau = i % n_plateaus;
+            values[i]          = lambda_min + static_cast<double>(plateau) * dx;
+        }
+    }
+    return values;
+}
+} // namespace
+
+inline Tensor generate_eigenvalues(const SymmetricMatrixSpec& spec,
+                                   std::mt19937& gen) {
+    require_valid_n(spec.n);
+    const auto n = spec.n;
+
+    const double lambda_min = spec.min_eigenvalue;
+    const double lambda_max = spec.min_eigenvalue * spec.condition_number;
+
+    std::vector<double> values;
+
+    if(n == 1) return utilities::make_tensor({n}, values);
+
+    switch(spec.spacing) {
+        case EigenvalueSpacing::Linear: {
+            values = linear_spacing(n, lambda_min, lambda_max);
+            break;
+        }
+        case EigenvalueSpacing::Logarithmic: {
+            values = logarithmic_spacing(n, lambda_min, lambda_max);
+            break;
+        }
+        case EigenvalueSpacing::Clustered: {
+            const auto n_clusters = std::max<std::size_t>(1, spec.n_clusters);
+            const auto n_clusters_clamped = std::min(n_clusters, n);
+            values = clustered_spacing(n, n_clusters_clamped, lambda_min,
+                                       lambda_max, spec.cluster_width, gen);
+            break;
+        }
+        case EigenvalueSpacing::Degenerate: {
+            values =
+              degenerate_spacing(n, spec.n_clusters, lambda_min, lambda_max);
+            break;
+        }
+        default: {
+            throw std::invalid_argument("Invalid eigenvalue spacing");
+        }
+    }
+
+    std::sort(values.begin(), values.end());
+    return utilities::make_tensor({n}, values);
+}
+
+} // namespace tensorwrapper::generate

include/tensorwrapper/generate/generate_utils.hpp

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2026 NWChemEx-Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <cstdint>
+#include <random>
+#include <stdexcept>
+
+namespace tensorwrapper::generate {
+
+constexpr std::size_t kMaxMatrixDim = 10;
+
+enum class EigenvalueSpacing {
+    // delta = (lambda_max - lambda_min) / (n - 1).
+    Linear,
+    // delta = log(lambda_max / lambda_min) / (n - 1).
+    Logarithmic,
+    // clusters of width cluster_width are separated by
+    // (lambda_max - lambda_min) / (n_clusters - 1).
+    Clustered,
+    // same as clustered, but all eigenvalues in a cluster are the same.
+    Degenerate
+};
+
+struct SymmetricMatrixSpec {
+    std::size_t n             = 2;
+    double condition_number   = 10.0;
+    double min_eigenvalue     = 1.0;
+    EigenvalueSpacing spacing = EigenvalueSpacing::Linear;
+    std::size_t n_clusters    = 1;
+    double cluster_width      = 1e-6;
+    std::uint64_t seed        = 42;
+};
+
+inline std::mt19937 make_rng(std::uint64_t seed) {
+    if(seed == 0) {
+        std::random_device rd;
+        return std::mt19937(rd());
+    }
+    return std::mt19937(static_cast<std::mt19937::result_type>(seed));
+}
+
+inline void require_valid_n(std::size_t n) {
+    if(n < 1 || n > kMaxMatrixDim) {
+        throw std::invalid_argument("n must be in [1, kMaxMatrixDim]");
+    }
+}
+
+} // namespace tensorwrapper::generate

include/tensorwrapper/generate/identity_matrix.hpp

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2026 NWChemEx-Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <cstddef>
+#include <tensorwrapper/generate/generate_utils.hpp>
+#include <tensorwrapper/utilities/diagonal_matrix.hpp>
+#include <tensorwrapper/utilities/make_tensor.hpp>
+#include <vector>
+
+namespace tensorwrapper::generate {
+
+inline Tensor identity_matrix(std::size_t n) {
+    require_valid_n(n);
+    std::vector<double> values(n, 1.0);
+    auto values_tensor = utilities::make_tensor({n}, values);
+    return utilities::diagonal_matrix(values_tensor);
+}
+
+} // namespace tensorwrapper::generate

include/tensorwrapper/generate/random_orthogonal_matrix.hpp

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026 NWChemEx-Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include <random>
+#include <tensorwrapper/tensor/tensor.hpp>
+
+namespace tensorwrapper::generate {
+
+Tensor random_orthogonal_matrix(std::size_t n, std::mt19937& gen);
+
+} // namespace tensorwrapper::generate

include/tensorwrapper/tensorwrapper.hpp

@@ -19,6 +19,7 @@
 #include <tensorwrapper/detail_/detail_.hpp>
 #include <tensorwrapper/diis/diis.hpp>
 #include <tensorwrapper/dsl/dsl.hpp>
+#include <tensorwrapper/generate/generate.hpp>
 #include <tensorwrapper/layout/layout.hpp>
 #include <tensorwrapper/operations/operations.hpp>
 #include <tensorwrapper/shape/shape.hpp>