UQPyL 2.1.6__cp313-cp313-win_amd64.whl

UQPyL/__init__.py

@@ -0,0 +1,33 @@
+"""UQPyL package entry."""
+
+import importlib
+from types import ModuleType
+
+doe = importlib.import_module(__name__ + ".doe")
+
+problem = importlib.import_module(__name__ + ".problem")
+viz = importlib.import_module(__name__ + ".viz")
+
+def _import_submodule(name: str) -> ModuleType:
+    return importlib.import_module(f"{__name__}.{name}")
+
+
+surrogate = _import_submodule("surrogate")
+optimization = _import_submodule("optimization")
+analysis = _import_submodule("analysis")
+inference = _import_submodule("inference")
+calibration = _import_submodule("calibration")
+
+__version__ = "2.1.7"
+__author__ = "wmtSky"
+
+__all__=[
+    "problem",
+    "surrogate",
+    "optimization",
+    "analysis",
+    "doe",
+    "inference",
+    "calibration",
+    "viz"
+]

UQPyL/analysis/__init__.py

@@ -0,0 +1,21 @@
+from .methods.delta import DeltaTest
+from .methods.fast import FAST
+from .methods.morris import Morris
+from .methods.rbd_fast import RBDFAST
+from .methods.rsa import RSA
+from .methods.sobol import Sobol
+
+try:
+    from .methods.mars import MARS
+except Exception:
+    MARS = None
+
+__all__ = [
+    "DeltaTest",
+    "FAST",
+    "MARS",
+    "Morris",
+    "RBDFAST",
+    "RSA",
+    "Sobol",
+]

UQPyL/analysis/base.py

@@ -0,0 +1,231 @@
+import abc
+import time
+from typing import List, Union
+
+import numpy as np
+
+from ..core.params import Params
+from ..core.runtime_session import RunSession
+from ..problem import ProblemABC as Problem
+from .runtime import AnaState, SqliteStorage, Verbose
+
+AnaIndex = Union[str, int, List[int]]
+
+class AnalysisABC(metaclass=abc.ABCMeta):
+    """
+    Abstract base class for analysis methods.
+    Shared workflow and utilities for sensitivity analysis methods.
+    """
+
+    def __init__(self, verboseFlag: bool = False, logFlag: bool = False, saveFlag: bool = False):
+        """
+        Initialize the analysis base class.
+
+        Args:
+            verboseFlag: Whether to print compact runtime summaries.
+            logFlag: Whether to write a log file.
+            saveFlag: Whether to persist results to sqlite.
+        """
+
+        # Set flags for verbosity, logging, and saving
+        self.verboseFlag = verboseFlag
+        self.logFlag = logFlag
+        self.saveFlag = saveFlag
+        
+        # Initialize settings and results
+        self.setting = Params()
+        self.params = self.setting
+        self.result = AnaState(self)
+        self.state = self.result
+        self.storage = None
+        self.session: RunSession | None = None
+        self.runId = None
+        
+    def set(self, key, value):
+        """
+        Set an analysis parameter.
+
+        Args:
+            key: Parameter name.
+            value: Parameter value.
+        """
+        
+        self.setting.set(key, value)
+    
+    def get(self, *args):
+        """
+        Retrieve one or more analysis parameters.
+
+        Args:
+            *args: Parameter names.
+
+        Returns:
+            The requested parameter value or values.
+        """
+        
+        return self.setting.get(*args) 
+        
+    def setProblem(self, problem: Problem):
+        """
+        Set the problem instance for the analysis.
+
+        Args:
+            problem: Problem instance defining the input and output space.
+        """
+        
+        self.problem = problem
+
+    def setup(self, problem):
+        self.setProblem(problem)
+        self.result.reset()
+        self.state = self.result
+        self.runId = None
+        self.session = None
+        Verbose.setupContext(self, problem)
+        if self.saveFlag:
+            rootDir = getattr(problem, "workDir", None) or Verbose.workDir
+            self.storage = SqliteStorage(rootDir)
+            self.session = self.storage.create_run(self)
+            self.runId = self.session.run_id
+
+    def finalize(self):
+        result = self.state.buildResult()
+        if self.saveFlag and self.session is not None:
+            self.storage.saveResult(self.session, result)
+            self.storage.close(self.session)
+            self.session = None
+        Verbose.printConclusion(self, result)
+        if self.logFlag:
+            Verbose.saveLog(self)
+        return result
+
+    def analyze(self, problem, *args, **kwargs):
+        """
+        Run the analysis workflow and return the final `AnaResult`.
+
+        Expected public inputs follow the unified protocol:
+        `analyze(problem, X, Y=None, meta=None, target="objs", index="all")`.
+        Here `target` is the semantic label of `Y`, and when `Y` is not
+        provided it also selects which problem output block to evaluate.
+        """
+        meta = kwargs.get("meta")
+        if meta is not None:
+            self.checkMeta(meta)
+        self.setup(problem)
+        Verbose.printSettings(self)
+        start = time.perf_counter()
+        self._analyzeCore(problem, *args, **kwargs)
+        self.state.runtime = time.perf_counter() - start
+        return self.finalize()
+
+    def checkMeta(self, meta):
+        """
+        Validate sampling metadata produced by `sampleWithMeta()`.
+        """
+        return None
+
+    def check_Y(self, X, Y, target: str = 'objs', index: AnaIndex = 'all'):
+        """
+        Resolve and slice analysis outputs.
+
+        `target` labels the meaning of `Y`, typically `objs` or `cons`.
+        If `Y` is not provided, `target` also selects which problem output
+        block should be evaluated. If `index` is not `'all'`, only the
+        selected output columns are kept.
+        """
+        if Y is None:
+            Y = self.evaluate(X, target=target)
+
+        if index != 'all':
+            indices = self._normalize_index(index)
+            try:
+                Y = Y[:, indices]
+            except Exception:
+                raise ValueError("Please check the index you set!")
+        
+        return Y
+    
+    def recordResult(self, X, Y, res, target: str = 'objs', meta=None):
+        self.result.record(X, Y, res, target=target, meta=meta)
+        for metric in self.result.metrics:
+            for i, target in enumerate(metric.rowLabels):
+                self.record(target, metric.name, metric.colLabels, metric.values[i])
+
+    def record(self, target, indicator, labels, values):
+        """
+        Record the analysis results.
+
+        Args:
+            target: Output label such as `obj1` or `con1`.
+            indicator: Metric name.
+            labels: Input variable labels.
+            values: Metric values.
+        """
+                        
+        self.result.verbose.setdefault(target, {})
+        self.result.verbose[target].setdefault(indicator, {})
+        
+        for label, v in zip(labels, values):
+            self.result.verbose[target][indicator][label] = v
+
+        self.result.verbose[target][indicator]['array'] = np.array(values)
+        
+
+    def __check_X_Y__(self, X, Y):
+        """
+        Check input and output arrays.
+
+        Args:
+            X: Input matrix.
+            Y: Output matrix.
+
+        Returns:
+            The validated `X` and `Y`.
+        """
+        
+        if not isinstance(X, np.ndarray) and X is not None:
+            raise TypeError("X must be an instance of np.ndarray or None!")
+        
+        if not isinstance(Y, np.ndarray) and Y is not None:
+            raise TypeError("Y must be an instance of np.ndarray or None!")
+
+        if Y.ndim == 1:
+            Y = Y.reshape(-1, 1)
+                  
+        return X, Y
+    
+    def evaluate(self, X, target: str = 'objs'):
+        """
+        Evaluate the problem with the given input data.
+
+        Args:
+            X: Input matrix.
+            target: Semantic output label to evaluate, typically `objs` or `cons`.
+
+        Returns:
+            The requested output matrix.
+        """
+
+        if target not in ('objs', 'cons'):
+            raise ValueError("Target must be 'objs' or 'cons'!")
+
+        evalRes = self.problem.evaluate(X, target=target)
+        Y = evalRes.objs if target == 'objs' else evalRes.cons
+        if Y is None:
+            raise ValueError(f"Problem does not provide target '{target}'.")
+        return Y
+
+    def _normalize_index(self, index: AnaIndex):
+        """
+        Normalize output column selection into a list of integers.
+        """
+        if isinstance(index, int):
+            return [index]
+        if isinstance(index, (list, tuple, np.ndarray)):
+            return list(index)
+        raise ValueError("Index must be 'all', an integer, or a list of integers!")
+    
+    @abc.abstractmethod
+    def _analyzeCore(self, problem, *args, **kwargs):
+        pass
+

UQPyL/analysis/delta.py

@@ -0,0 +1,2 @@
+from ..optimization.soea import GA
+from .methods.delta import *

UQPyL/analysis/fast.py

@@ -0,0 +1,2 @@
+from .methods.fast import *
+

UQPyL/analysis/mars.py

@@ -0,0 +1,2 @@
+from .methods.mars import *
+

UQPyL/analysis/methods/__init__.py

@@ -0,0 +1,21 @@
+from .delta import DeltaTest
+from .fast import FAST
+from .morris import Morris
+from .rbd_fast import RBDFAST
+from .rsa import RSA
+from .sobol import Sobol
+
+try:
+    from .mars import MARS
+except Exception:
+    MARS = None
+
+__all__ = [
+    "DeltaTest",
+    "FAST",
+    "MARS",
+    "Morris",
+    "RBDFAST",
+    "RSA",
+    "Sobol",
+]

UQPyL/analysis/methods/delta.py

@@ -0,0 +1,249 @@
+# Delta test
+import numpy as np
+import sys
+from scipy.spatial import KDTree
+from typing import Optional
+
+from ..base import AnaIndex, AnalysisABC
+from ...problem import ProblemABC, Problem
+
+class DeltaTest(AnalysisABC):
+    """
+    Delta Test
+    Non-parametric sensitivity analysis based on nearest-neighbor prediction error.
+    
+    Examples:
+        >>> from UQPyL.doe import LHS
+        >>> delta_method = DeltaTest(nNeighbors=2)
+        >>> X = LHS('classic').sample(problem, 1000)
+        >>> res = delta_method.analyze(problem, X, target="objs")
+        >>> print(res)
+        
+    References:
+        [1] E. Eirola et al, Using the Delta Test for Variable Selection, 
+            Artificial Neural Networks, 2008.
+        [2] SALib, https://github.com/SALib/SALib
+    """
+    
+    name = "DeltaTest"
+    
+    def __init__(self, nNeighbors: int = 2,
+                 verboseFlag: bool = True, logFlag: bool = False, saveFlag: bool = False):
+        """
+        Initialize the Delta Test method.
+
+        Args:
+            nNeighbors: Number of nearest neighbors used by the delta estimate.
+            verboseFlag: Whether to print compact runtime summaries.
+            logFlag: Whether to write a log file.
+            saveFlag: Whether to persist results to sqlite.
+        """
+        super().__init__(verboseFlag, logFlag, saveFlag)
+        self.set("nNeighbors", nNeighbors)
+
+    def _analyzeCore(self, problem, X: np.ndarray, Y: Optional[np.ndarray] = None, meta: Optional[dict] = None,
+                     target: str = 'objs', index: AnaIndex = 'all') -> None:
+        """
+        Run the Delta Test on the provided samples.
+
+        Args:
+            problem: Analysis problem.
+            X: Input sample matrix.
+            Y: Optional output matrix corresponding to `X`.
+            meta: Optional sampling metadata for persistence only.
+            target: Semantic label of `Y`, typically `objs` or `cons`.
+            index: Output column selection.
+        """
+        
+        # Set the problem instance for analysis
+        self.setProblem(problem)
+        
+        # Evaluate the problem if Y is not provided
+        Y = self.check_Y(X, Y, target, index)
+        
+        X, Y = self.__check_X_Y__(X, Y)
+        nInput = problem.nInput
+        numY = Y.shape[1]
+        nNeighbors = self.get("nNeighbors")
+        
+        outputLabel = "obj" if target == "objs" else "con"
+        
+        S1 = np.zeros((numY, nInput))
+        S1_norm = np.zeros((numY, nInput))
+        row_label = [f"{outputLabel}{i+1}" for i in range(numY)]
+        col_label_1 = problem.xLabels
+        
+        for i in range(numY):
+            Y_i = Y[:, i:i+1]
+            base = self._cal_delta(X, Y_i, nNeighbors)
+            for j in range(nInput):
+                XSub = np.delete(X, [j], axis=1)
+                deltaWithoutVar = self._cal_delta(XSub, Y_i, nNeighbors)
+                S1[i, j] = deltaWithoutVar - base
+
+            total = np.sum(S1[i])
+            if np.isclose(total, 0.0):
+                S1_norm[i] = 0.0
+            else:
+                S1_norm[i] = S1[i] / total
+
+        res = [('S1', S1, row_label, col_label_1, 'decsDim1'), ('S1_norm', S1_norm, row_label, col_label_1, 'decsDim1')]
+        
+        self.recordResult(X, Y, res, target=target, meta=meta)
+
+        return None
+    
+    def findCombEA(self, problem, X: np.ndarray, Y: Optional[np.ndarray] = None, 
+                   FEs: int = 10000, 
+                   verboseFlag: bool = True, saveFlag: bool = True):
+        """
+        Find the best combination using Evolutionary Algorithm.
+
+        Args:
+            problem: Analysis problem.
+            X: Input sample matrix.
+            Y: Optional output matrix corresponding to `X`.
+            FEs: Maximum number of function evaluations.
+            verboseFlag: Whether the helper GA should print progress.
+            saveFlag: Whether the helper GA should persist results.
+
+        Returns:
+            The optimization result returned by the configured GA.
+        """
+        # Set the problem instance for analysis
+        self.setProblem(problem)
+        
+        # Retrieve the number of nearest neighbors for analysis
+        nNeighbors = self.get('nNeighbors')
+        
+        # Evaluate outputs if Y is not provided
+        if Y is None:
+            Y = self.evaluate(X, target="objs")
+        
+        X, Y = self.__check_X_Y__(X, Y)
+        
+        @ProblemABC.singleFunc
+        def objective(x_):
+            """
+            Minimize the delta value.
+
+            Args:
+                x_: Binary array indicating selected variables.
+
+            Returns:
+                The delta value for the selected variables.
+            """
+            x_ = x_.astype(int)
+            Indices = np.where(x_ == 1)[0]
+            XSub = X[:, Indices]
+            
+            if np.sum(x_) == 0:
+                return np.inf
+            else:
+                return self._cal_delta(XSub, Y, nNeighbors)
+        
+        # Create the optimization problem
+        nInput = problem.nInput
+        nObj = 1
+        ub = [1] * nInput
+        lb = [0] * nInput
+        varType = [1] * nInput
+        
+        problem = Problem(nInput=nInput, nObj=nObj, ub=ub, lb=lb, 
+                          varType=varType, objFunc=objective, optType='min')
+
+        publicModule = sys.modules.get("UQPyL.analysis.delta")
+        gaClass = getattr(publicModule, "GA", None) if publicModule is not None else None
+        if gaClass is None:
+            from ...optimization.soea import GA as gaClass
+
+        # Initialize the GA
+        ga = gaClass(maxFEs=FEs, verboseFlag=verboseFlag, saveFlag=saveFlag)
+        
+        # Run the GA
+        res = ga.run(problem)
+        
+        return res
+    
+    def findCombVio(self, problem, X: np.ndarray, Y: Optional[np.ndarray] = None):
+        """
+        Find the best combination using a brute-force approach.
+
+        Args:
+            problem: Analysis problem.
+            X: Input sample matrix.
+            Y: Optional output matrix corresponding to `X`.
+
+        Returns:
+            Labels of the selected variables.
+        """
+        
+        from itertools import product
+        
+        # Set the problem instance for analysis
+        self.setProblem(problem)
+        
+        nInput = problem.nInput
+        
+        # Retrieve the number of nearest neighbors for analysis
+        nNeighbors = self.get('nNeighbors')
+        
+        # Evaluate outputs if Y is not provided
+        if Y is None:
+            Y = self.evaluate(X, target="objs")
+        
+        X, Y = self.__check_X_Y__(X, Y)
+        
+        # Generate all possible combinations of input variables
+        combinations = list(product([0, 1], repeat=nInput))
+        
+        # Initialize an array to store objective values for each combination
+        objs = np.zeros((len(combinations), 1))
+        
+        # Evaluate each combination
+        for i in range(len(combinations)):
+            x_ = np.array(combinations[i])
+            Indices = np.where(x_ == 1)[0]
+            XSub = X[:, Indices]
+            
+            if np.sum(x_) == 0:
+                objs[i] = np.inf
+            else:
+                objs[i] = self._cal_delta(XSub, Y, nNeighbors)
+        
+        # Find the best combination based on the objective values
+        best_index = np.argmin(objs)
+        best_combination = combinations[best_index]
+        
+        # Return the labels of the most sensitive variables
+        return [problem.xLabels[i] for i in range(nInput) if best_combination[i] == 1]
+    
+    def _cal_delta(self, X: np.ndarray, Y: np.ndarray, nNeighbors: int):
+        """
+        Calculate the Delta value using KDTree for nearest neighbor search.
+
+        Args:
+            X: Input data array.
+            Y: Output data array.
+            nNeighbors: Number of nearest neighbors to consider.
+
+        Returns:
+            The calculated delta value.
+        """
+        N, _ = X.shape
+        
+        # Build a KDTree for fast nearest neighbor search
+        tree = KDTree(X)
+        
+        # Query the nearest neighbors for each point
+        _, neighbors_indices = tree.query(X, k=nNeighbors + 1)  # +1 to include the point itself
+        
+        # Exclude the point itself from the neighbors
+        neighbors_indices = neighbors_indices[:, 1:]
+        
+        Delta = 0
+        for i in range(N):
+            d = (Y[i] - Y[neighbors_indices[i]])**2
+            Delta += float(np.mean(d))
+        
+        return Delta / (nNeighbors * N)