softDOE 0.1.0__tar.gz

softdoe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wei-Yang Yu and V. Roshan Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

softdoe-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: softDOE
+Version: 0.1.0
+Summary: Space-filling one-factor-at-a-time designs.
+Author: Wei-Yang Yu and V. Roshan Joseph
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pyDOE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+Dynamic: requires-python
+
+# softDOE
+
+`softDOE` is a Python package for constructing space-filling
+one-factor-at-a-time (SOFT) designs.
+
+## What is included
+
+`softDOE` currently includes:
+
+* `soft()`: generate SOFT designs.
+* `measure()`: compute screening measures.
+
+Generated designs are returned as NumPy arrays with entries in `(0, 1)`.
+
+## Installation
+
+Install `softDOE` from PyPI:
+
+```bash
+pip install softDOE
+```
+
+
+`softDOE` requires Python 3.9 or later. The package depends on NumPy, SciPy,
+and pyDOE, and uses a compiled C++ extension built with pybind11.
+
+## Quick example
+
+```python
+import numpy as np
+import softDOE
+
+# SOFT design
+design = softDOE.soft(p=10, l=4)
+
+# Friedman function
+def friedman(x):
+    x = np.asarray(x)
+    return (
+        10 * np.sin(np.pi * x[0] * x[1])
+        + 20 * (x[2] - 0.5) ** 2
+        + 10 * x[3]
+        + 5 * x[4]
+    )
+
+# Evaluate Friedman function at each design point.
+y = np.array([friedman(row) for row in design])
+
+# Sensitivity measures
+result = softDOE.measure(design, y)
+
+print(result["mustar"])
+print(result["t"])
+```
+
+## Generating SOFT designs
+
+Use `softDOE.soft()` to generate a SOFT design:
+
+```python
+design = softDOE.soft(p=5, l=4, structure="standard", m=500, seed=123)
+```
+
+Arguments:
+
+* `p`: number of factors.
+* `l`: number of base runs. This value must be even.
+* `structure`: either `"standard"` or `"strict"`. The default is
+  `"standard"`.
+* `m`: number of Monte Carlo samples used when evaluating the design
+  objective.
+* `seed`: optional seed for reproducible design generation.
+
+The returned design has shape:
+
+```python
+(l * (p + 1), p)
+```
+
+## Computing screening measures
+
+Use `softDOE.measure()` with a design matrix and response vector:
+
+```python
+result = softDOE.measure(design, y)
+```
+
+The response vector `y` must have one value for each row of the design. The
+function returns a dictionary with two entries:
+
+* `mustar`: $\mu^*$ measure of Campolongo et al. (2007).
+* `t`: total Sobol' index of Sobol' (1993).
+
+## Testing
+
+After installing the test dependencies, run the test suite with:
+
+```bash
+python -m pytest
+```
+
+## Citation
+
+If you use `softDOE`, please cite:
+
+```bibtex
+@article{yu2026space,
+  title={Space-Filling One-Factor-At-A-Time Designs},
+  author={Yu, Wei-Yang and Joseph, V Roshan},
+  journal={arXiv preprint arXiv:2606.02533},
+  year={2026}
+}
+```
+
+## References
+
+* Sobol', I. M. (1993), "On sensitivity estimation for nonlinear mathematical
+  models," Mathematical Modeling and Computational Experiments, 1, 407-414.
+* Campolongo, F., Cariboni, J., and Saltelli, A. (2007), "An effective
+  screening design for sensitivity analysis of large models," Environmental
+  Modelling and Software, 22, 1509-1518.
+
+## Authors
+
+Wei-Yang Yu and V. Roshan Joseph.
+
+## License
+
+`softDOE` is licensed under the MIT License.

softdoe-0.1.0/README.md

@@ -0,0 +1,129 @@
+# softDOE
+
+`softDOE` is a Python package for constructing space-filling
+one-factor-at-a-time (SOFT) designs.
+
+## What is included
+
+`softDOE` currently includes:
+
+* `soft()`: generate SOFT designs.
+* `measure()`: compute screening measures.
+
+Generated designs are returned as NumPy arrays with entries in `(0, 1)`.
+
+## Installation
+
+Install `softDOE` from PyPI:
+
+```bash
+pip install softDOE
+```
+
+
+`softDOE` requires Python 3.9 or later. The package depends on NumPy, SciPy,
+and pyDOE, and uses a compiled C++ extension built with pybind11.
+
+## Quick example
+
+```python
+import numpy as np
+import softDOE
+
+# SOFT design
+design = softDOE.soft(p=10, l=4)
+
+# Friedman function
+def friedman(x):
+    x = np.asarray(x)
+    return (
+        10 * np.sin(np.pi * x[0] * x[1])
+        + 20 * (x[2] - 0.5) ** 2
+        + 10 * x[3]
+        + 5 * x[4]
+    )
+
+# Evaluate Friedman function at each design point.
+y = np.array([friedman(row) for row in design])
+
+# Sensitivity measures
+result = softDOE.measure(design, y)
+
+print(result["mustar"])
+print(result["t"])
+```
+
+## Generating SOFT designs
+
+Use `softDOE.soft()` to generate a SOFT design:
+
+```python
+design = softDOE.soft(p=5, l=4, structure="standard", m=500, seed=123)
+```
+
+Arguments:
+
+* `p`: number of factors.
+* `l`: number of base runs. This value must be even.
+* `structure`: either `"standard"` or `"strict"`. The default is
+  `"standard"`.
+* `m`: number of Monte Carlo samples used when evaluating the design
+  objective.
+* `seed`: optional seed for reproducible design generation.
+
+The returned design has shape:
+
+```python
+(l * (p + 1), p)
+```
+
+## Computing screening measures
+
+Use `softDOE.measure()` with a design matrix and response vector:
+
+```python
+result = softDOE.measure(design, y)
+```
+
+The response vector `y` must have one value for each row of the design. The
+function returns a dictionary with two entries:
+
+* `mustar`: $\mu^*$ measure of Campolongo et al. (2007).
+* `t`: total Sobol' index of Sobol' (1993).
+
+## Testing
+
+After installing the test dependencies, run the test suite with:
+
+```bash
+python -m pytest
+```
+
+## Citation
+
+If you use `softDOE`, please cite:
+
+```bibtex
+@article{yu2026space,
+  title={Space-Filling One-Factor-At-A-Time Designs},
+  author={Yu, Wei-Yang and Joseph, V Roshan},
+  journal={arXiv preprint arXiv:2606.02533},
+  year={2026}
+}
+```
+
+## References
+
+* Sobol', I. M. (1993), "On sensitivity estimation for nonlinear mathematical
+  models," Mathematical Modeling and Computational Experiments, 1, 407-414.
+* Campolongo, F., Cariboni, J., and Saltelli, A. (2007), "An effective
+  screening design for sensitivity analysis of large models," Environmental
+  Modelling and Software, 22, 1509-1518.
+
+## Authors
+
+Wei-Yang Yu and V. Roshan Joseph.
+
+## License
+
+`softDOE` is licensed under the MIT License.

softdoe-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=64", "wheel", "pybind11>=2.10", "numpy"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "softDOE"
+version = "0.1.0"
+description = "Space-filling one-factor-at-a-time designs."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  {name = "Wei-Yang Yu and V. Roshan Joseph"}
+]
+dependencies = [
+  "numpy",
+  "scipy",
+  "pyDOE"
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

softdoe-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

softdoe-0.1.0/setup.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext
+
+
+class BuildExt(build_ext):
+    def build_extensions(self) -> None:
+        import pybind11
+
+        for ext in self.extensions:
+            ext.include_dirs.append(pybind11.get_include())
+            ext.extra_compile_args = ["-std=c++17"]
+        super().build_extensions()
+
+
+ext_modules = [
+    Extension(
+        "softDOE._core",
+        ["src/softDOE/_core.cpp"],
+        language="c++",
+    )
+]
+
+
+setup(
+    name="softDOE",
+    version="0.1.0",
+    description="Space-filling one-factor-at-a-time designs.",
+    author="Wei-Yang Yu and V. Roshan Joseph",
+    package_dir={"": "src"},
+    packages=["softDOE"],
+    python_requires=">=3.9",
+    install_requires=["numpy", "scipy", "pyDOE"],
+    extras_require={"test": ["pytest"]},
+    ext_modules=ext_modules,
+    cmdclass={"build_ext": BuildExt},
+)

softdoe-0.1.0/src/softDOE/__init__.py

@@ -0,0 +1,6 @@
+"""Space-filling one-factor-at-a-time designs."""
+
+from ._measure import measure
+from ._soft import soft
+
+__all__ = ["soft", "measure"]

softdoe-0.1.0/src/softDOE/_core.cpp

@@ -0,0 +1,239 @@
+#include <cmath>
+#include <stdexcept>
+
+#include <pybind11/numpy.h>
+#include <pybind11/pybind11.h>
+
+namespace py = pybind11;
+
+namespace {
+
+using Array = py::array_t<double, py::array::c_style | py::array::forcecast>;
+
+// Evaluate the MIM correlation kernel between row ia of A and row ib of B.
+double corr_idx(const double* A, py::ssize_t ia, const double* B, py::ssize_t ib,
+                py::ssize_t p, double alpha, double beta) {
+    const double invbeta = 1.0 / beta;
+
+    if (alpha == 1.0) {
+        double c = 1.0;
+        for (py::ssize_t k = 0; k < p; ++k) {
+            const double d = A[ia * p + k] - B[ib * p + k];
+            c *= 1.0 / (1.0 + (d * d) * invbeta);
+        }
+        return c;
+    }
+
+    const double negalpha = -alpha;
+    double logc = 0.0;
+    for (py::ssize_t k = 0; k < p; ++k) {
+        const double d = A[ia * p + k] - B[ib * p + k];
+        logc += negalpha * std::log1p((d * d) * invbeta);
+    }
+    return std::exp(logc);
+}
+
+// Validate that a Python/NumPy input is a two-dimensional matrix.
+void require_matrix(const py::buffer_info& info, const char* name) {
+    if (info.ndim != 2) {
+        throw std::invalid_argument(std::string(name) + " must be two-dimensional.");
+    }
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// Testing helpers
+// ---------------------------------------------------------------------------
+
+// Expose corr_idx to Python for parity tests against R's internal corr_idx_fast.
+// This is intentionally private (_corr_idx) and is not part of the public API.
+double corr_idx_binding(Array A, py::ssize_t ia, Array B, py::ssize_t ib,
+                        double alpha, double beta) {
+    const py::buffer_info a_info = A.request();
+    const py::buffer_info b_info = B.request();
+    require_matrix(a_info, "A");
+    require_matrix(b_info, "B");
+
+    if (a_info.shape[1] != b_info.shape[1]) {
+        throw std::invalid_argument("A and B must have the same number of columns.");
+    }
+    if (ia < 0 || ia >= a_info.shape[0]) {
+        throw std::out_of_range("ia is out of range for A.");
+    }
+    if (ib < 0 || ib >= b_info.shape[0]) {
+        throw std::out_of_range("ib is out of range for B.");
+    }
+
+    const auto* a = static_cast<const double*>(a_info.ptr);
+    const auto* b = static_cast<const double*>(b_info.ptr);
+    return corr_idx(a, ia, b, ib, a_info.shape[1], alpha, beta);
+}
+
+// Build the MIM correlation matrix for X, or append new_X to a precomputed
+// old_R block when incrementally growing a design.
+Array corr_matrix(Array X, py::object new_X_obj, py::object old_R_obj,
+                  double alpha, double beta) {
+    const py::buffer_info x_info = X.request();
+    require_matrix(x_info, "X");
+    const auto n = x_info.shape[0];
+    const auto p = x_info.shape[1];
+    const auto* x = static_cast<const double*>(x_info.ptr);
+
+    if (new_X_obj.is_none()) {
+        Array out({n, n});
+        auto out_info = out.mutable_unchecked<2>();
+        for (py::ssize_t i = 0; i < n; ++i) {
+            out_info(i, i) = 1.0;
+            for (py::ssize_t j = i + 1; j < n; ++j) {
+                const double c = corr_idx(x, i, x, j, p, alpha, beta);
+                out_info(i, j) = c;
+                out_info(j, i) = c;
+            }
+        }
+        return out;
+    }
+
+    if (old_R_obj.is_none()) {
+        throw std::invalid_argument("old_R must be provided when new_X is not None.");
+    }
+
+    Array new_X = py::cast<Array>(new_X_obj);
+    Array old_R = py::cast<Array>(old_R_obj);
+    const py::buffer_info x2_info = new_X.request();
+    const py::buffer_info r0_info = old_R.request();
+    require_matrix(x2_info, "new_X");
+    require_matrix(r0_info, "old_R");
+
+    const auto k = x2_info.shape[0];
+    if (x2_info.shape[1] != p) {
+        throw std::invalid_argument("new_X must have the same number of columns as X.");
+    }
+    if (r0_info.shape[0] != n || r0_info.shape[1] != n) {
+        throw std::invalid_argument("old_R must have shape (X rows, X rows).");
+    }
+
+    const auto* x2 = static_cast<const double*>(x2_info.ptr);
+    const auto* r0 = static_cast<const double*>(r0_info.ptr);
+    const auto new_n = n + k;
+    Array out({new_n, new_n});
+    auto out_info = out.mutable_unchecked<2>();
+
+    for (py::ssize_t i = 0; i < new_n; ++i) {
+        for (py::ssize_t j = 0; j < new_n; ++j) {
+            out_info(i, j) = 0.0;
+        }
+        out_info(i, i) = 1.0;
+    }
+
+    for (py::ssize_t i = 0; i < n; ++i) {
+        for (py::ssize_t j = 0; j < n; ++j) {
+            out_info(i, j) = r0[i * n + j];
+        }
+    }
+
+    for (py::ssize_t i = 0; i < k; ++i) {
+        const py::ssize_t ii = n + i;
+        for (py::ssize_t j = 0; j < n; ++j) {
+            const double c = corr_idx(x2, i, x, j, p, alpha, beta);
+            out_info(ii, j) = c;
+            out_info(j, ii) = c;
+        }
+    }
+
+    for (py::ssize_t i = 0; i < k; ++i) {
+        const py::ssize_t ii = n + i;
+        for (py::ssize_t j = i + 1; j < k; ++j) {
+            const py::ssize_t jj = n + j;
+            const double c = corr_idx(x2, i, x2, j, p, alpha, beta);
+            out_info(ii, jj) = c;
+            out_info(jj, ii) = c;
+        }
+    }
+
+    return out;
+}
+
+// Build correlations between QMC/evaluation points and design points X, or
+// append rows for new_X to a precomputed design-vs-QMC correlation block.
+Array q_matrix(Array qmc, Array X, py::object old_R_obj, py::object new_X_obj,
+               double alpha, double beta) {
+    const py::buffer_info q_info = qmc.request();
+    const py::buffer_info x_info = X.request();
+    require_matrix(q_info, "qmc");
+    require_matrix(x_info, "X");
+
+    const auto m = q_info.shape[0];
+    const auto p = q_info.shape[1];
+    const auto n = x_info.shape[0];
+    if (x_info.shape[1] != p) {
+        throw std::invalid_argument("qmc and X must have the same number of columns.");
+    }
+
+    const auto* q = static_cast<const double*>(q_info.ptr);
+    const auto* x = static_cast<const double*>(x_info.ptr);
+
+    if (new_X_obj.is_none()) {
+        Array out({n, m});
+        auto out_info = out.mutable_unchecked<2>();
+        for (py::ssize_t j = 0; j < m; ++j) {
+            for (py::ssize_t i = 0; i < n; ++i) {
+                out_info(i, j) = corr_idx(q, j, x, i, p, alpha, beta);
+            }
+        }
+        return out;
+    }
+
+    if (old_R_obj.is_none()) {
+        throw std::invalid_argument("old_R must be provided when new_X is not None.");
+    }
+
+    Array old_R = py::cast<Array>(old_R_obj);
+    Array new_X = py::cast<Array>(new_X_obj);
+    const py::buffer_info r0_info = old_R.request();
+    const py::buffer_info x2_info = new_X.request();
+    require_matrix(r0_info, "old_R");
+    require_matrix(x2_info, "new_X");
+
+    const auto k = x2_info.shape[0];
+    if (x2_info.shape[1] != p) {
+        throw std::invalid_argument("new_X must have the same number of columns as X.");
+    }
+    if (r0_info.shape[0] != n || r0_info.shape[1] != m) {
+        throw std::invalid_argument("old_R must have shape (X rows, qmc rows).");
+    }
+
+    const auto* r0 = static_cast<const double*>(r0_info.ptr);
+    const auto* x2 = static_cast<const double*>(x2_info.ptr);
+    Array out({n + k, m});
+    auto out_info = out.mutable_unchecked<2>();
+
+    for (py::ssize_t i = 0; i < n; ++i) {
+        for (py::ssize_t j = 0; j < m; ++j) {
+            out_info(i, j) = r0[i * m + j];
+        }
+    }
+
+    for (py::ssize_t j = 0; j < m; ++j) {
+        for (py::ssize_t i = 0; i < k; ++i) {
+            out_info(n + i, j) = corr_idx(q, j, x2, i, p, alpha, beta);
+        }
+    }
+
+    return out;
+}
+
+// Register the compiled backend functions exposed to the Python module.
+PYBIND11_MODULE(_core, m) {
+    m.doc() = "Compiled correlation kernels for softDOE.";
+    m.def("_corr_idx", &corr_idx_binding, py::arg("A"), py::arg("ia"),
+          py::arg("B"), py::arg("ib"), py::arg("alpha") = 1.0,
+          py::arg("beta") = 1.0,
+          "Evaluate the MIM kernel between row ia of matrix A and row ib of matrix B.");
+    m.def("corr_matrix", &corr_matrix, py::arg("X"), py::arg("new_X") = py::none(),
+          py::arg("old_R") = py::none(), py::arg("alpha") = 1.0,
+          py::arg("beta") = 1.0);
+    m.def("q_matrix", &q_matrix, py::arg("qmc"), py::arg("X"),
+          py::arg("old_R") = py::none(), py::arg("new_X") = py::none(),
+          py::arg("alpha") = 1.0, py::arg("beta") = 1.0);
+}

softdoe-0.1.0/src/softDOE/_measure.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+def measure(design, y):
+    """Compute screening measures for a SOFT/Sobol'-structured design.
+
+    Parameters
+    ----------
+    design : array_like, shape (l * (p + 1), p)
+        Design matrix with one base block followed by one-factor-at-a-time
+        blocks.
+    y : array_like, shape (l * (p + 1),)
+        Response vector.
+
+    Returns
+    -------
+    dict
+        ``{"mustar": array, "t": array}``, matching the R function output.
+    """
+    design = np.asarray(design, dtype=float)
+    y = np.asarray(y, dtype=float).reshape(-1)
+
+    if design.ndim != 2:
+        raise ValueError("design must be a two-dimensional array.")
+
+    n, p = design.shape
+    if p < 1:
+        raise ValueError("design must contain at least one factor.")
+    if n % (p + 1) != 0:
+        raise ValueError("design must have l * (p + 1) rows.")
+    if y.shape[0] != n:
+        raise ValueError("y must have the same length as design rows.")
+
+    l = n // (p + 1)
+    design_blocks = [design[i * l : (i + 1) * l, :] for i in range(p + 1)]
+    y_blocks = [y[i * l : (i + 1) * l] for i in range(p + 1)]
+
+    y_diff = [None] * p
+    delta = [None] * p
+
+    for i in range(p):
+        matrix_idx, factor_idx = _find_a(design_blocks, i + 1)
+        y_diff[factor_idx] = np.abs(y_blocks[i + 1] - y_blocks[matrix_idx])
+        delta[factor_idx] = np.abs(
+            design_blocks[i + 1][:, factor_idx]
+            - design_blocks[matrix_idx][:, factor_idx]
+        )
+
+    if any(v is None for v in y_diff) or any(v is None for v in delta):
+        raise ValueError("design does not have a valid one-factor-at-a-time block structure.")
+
+    with np.errstate(divide="raise", invalid="raise"):
+        try:
+            mustar = np.array(
+                [np.sum(diff / step) / l for diff, step in zip(y_diff, delta)],
+                dtype=float,
+            )
+        except FloatingPointError as exc:
+            raise ValueError("design contains zero OFAT step sizes.") from exc
+
+    var_y = np.var(y, ddof=1)
+    if var_y == 0:
+        t = np.full(p, np.nan)
+    else:
+        vtot = np.array([np.sum(diff**2) for diff in y_diff], dtype=float) / (2 * l)
+        t = vtot / var_y
+
+    return {"mustar": mustar, "t": t}
+
+
+def _find_a(blocks, idx):
+    b = blocks[idx]
+    p = b.shape[1]
+    for j in range(idx):
+        a = blocks[j]
+        col_same = np.array(
+            [np.allclose(a[:, k], b[:, k], rtol=0.0, atol=1e-12) for k in range(p)]
+        )
+        changed = np.flatnonzero(~col_same)
+        if changed.size == 1:
+            return j, int(changed[0])
+    raise ValueError("could not find the matching prior OFAT block.")