Repository: damar-wicaksono/uqtestfuns (language: python)

Issue:
Add the highly-curved three-dimensional function from Dette and Pepelyshev (2010)
The three-dimensional function from Dette and Pepelyshev (2010)[^dette] is a test function used in the context of metamodeling (specifically, design of computer experiments to construct metamodels). The function reads as follows:

$$
\mathcal{M}(\boldsymbol{x}) = 4 \left( x_1 - 2 + 8 x_2 - 8 x_2^2 \right) + \left( 3 - 4 x_2 \right)^2 + 16 \left( x_3 + 1\right)^{0.5} \left( 2 x_3 - 1\right)^2
$$

where $\boldsymbol{x} = \\{ x_1, x_2, x_3 \\}$ is the vector of input variables modeled as an independent uniform random variable in $[0, 1]^3$. The function is highly curved.

[^dette]: H. Dette and A. Pepelyshev, "Generalized latin hypercube design for computer experiments," Technometrics, vol. 52, no. 4, pp. 421-429, 2010. doi: [10.1198/TECH.2010.09157](https://doi.org/10.1198/TECH.2010.09157). See Eq. (5), Section 3.1.



Discussion / hints:

Fix patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5bab18d..e413c11 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- The tree-dimensional exponential function from Dette and Pepelyshev (2010)
+- The three-dimensional highly-curved function from Dette and Pepelyshev (2010)
+  for metamodeling exercises.
+- The three-dimensional exponential function from Dette and Pepelyshev (2010)
   for metamodeling exercises.
 - The one-dimensional sine function from Higdon (2002) featuring behaviors
   that are different in two scales; for metamodeling (multi-resolution)
diff --git a/docs/_toc.yml b/docs/_toc.yml
index eed03d3..c0a405f 100644
--- a/docs/_toc.yml
+++ b/docs/_toc.yml
@@ -70,6 +70,8 @@ parts:
             title: Damped Oscillator
           - file: test-functions/damped-oscillator-reliability
             title: Damped Oscillator Reliability
+          - file: test-functions/dette-curved
+            title: Dette & Pepelyshev (2010) Curved
           - file: test-functions/dette-exp
             title: Dette & Pepelyshev (2010) Exponential
           - file: test-functions/flood
diff --git a/docs/fundamentals/metamodeling.md b/docs/fundamentals/metamodeling.md
index ad3b50b..0fe2b06 100644
--- a/docs/fundamentals/metamodeling.md
+++ b/docs/fundamentals/metamodeling.md
@@ -18,49 +18,50 @@ kernelspec:
 The table below listed the available test functions typically used
 in the comparison of metamodeling approaches.
 
-|                                   Name                                   | Input Dimension |      Constructor       |
-|:------------------------------------------------------------------------:|:---------------:|:----------------------:|
-|                  {ref}`Ackley <test-functions:ackley>`                   |        M        |       `Ackley()`       |
-|   {ref}`Alemazkoor & Meidani (2018) 2D <test-functions:alemazkoor-2d>`   |        2        |    `Alemazkoor2D()`    |
-|  {ref}`Alemazkoor & Meidani (2018) 20D <test-functions:alemazkoor-20d>`  |       20        |   `Alemazkoor20D()`    |
-|                {ref}`Borehole <test-functions:borehole>`                 |        8        |      `Borehole()`      |
-|        {ref}`Cheng and Sandu (2010) 2D <test-functions:cheng2d>`         |        2        |       `Cheng2D`        |
-|           {ref}`Coffee Cup Model <test-functions:coffee-cup>`            |        2        |     `CoffeeCup()`      |
-|      {ref}`Currin et al. (1988) Sine <test-functions:currin-sine>`       |        1        |     `CurrinSine()`     |
-|           {ref}`Damped Cosine <test-functions:damped-cosine>`            |        1        |    `DampedCosine()`    |
-|       {ref}`Damped Oscillator <test-functions:damped-oscillator>`        |        7        |  `DampedOscillator()`  |
-| {ref}`Dette & Pepelyshev (2010) Exponential <test-functions:dette-exp>`  |        3        |      `DetteExp()`      |
-|                   {ref}`Flood <test-functions:flood>`                    |        8        |       `Flood()`        |
-|        {ref}`Forrester et al. (2008) <test-functions:forrester>`         |        1        |   `Forrester2008()`    |
-|              {ref}`(1st) Franke <test-functions:franke-1>`               |        2        |      `Franke1()`       |
-|              {ref}`(2nd) Franke <test-functions:franke-2>`               |        2        |      `Franke2()`       |
-|              {ref}`(3rd) Franke <test-functions:franke-3>`               |        2        |      `Franke3()`       |
-|              {ref}`(4th) Franke <test-functions:franke-4>`               |        2        |      `Franke4()`       |
-|              {ref}`(5th) Franke <test-functions:franke-5>`               |        2        |      `Franke5()`       |
-|              {ref}`(6th) Franke <test-functions:franke-6>`               |        2        |      `Franke6()`       |
-|            {ref}`Friedman (6D) <test-functions:friedman-6d>`             |        6        |     `Friedman6D()`     |
-|           {ref}`Friedman (10D) <test-functions:friedman-10d>`            |       10        |    `Friedman10D()`     |
-|       {ref}`Genz (Corner Peak) <test-functions:genz-corner-peak>`        |        M        |   `GenzCornerPeak()`   |
-|      {ref}`Gramacy (2007) 1D Sine <test-functions:gramacy-1d-sine>`      |        1        |   `Gramacy1DSine()`    |
-|          {ref}`Higdon (2002) Sine <test-functions:higdon-sine>`          |        1        |     `HigdonSine()`     |
-|    {ref}`Holsclaw et al. (2013) Sine <test-functions:holsclaw-sine>`     |        1        |    `HolsclawSine()`    |
-|  {ref}`Lim et al. (2002) Non-Polynomial <test-functions:lim-non-poly>`   |        2        |     `LimNonPoly()`     |
-|      {ref}`Lim et al. (2002) Polynomial <test-functions:lim-poly>`       |        2        |      `LimPoly()`       |
-|               {ref}`McLain S1 <test-functions:mclain-s1>`                |        2        |      `McLainS1()`      |
-|               {ref}`McLain S2 <test-functions:mclain-s2>`                |        2        |      `McLainS2()`      |
-|               {ref}`McLain S3 <test-functions:mclain-s3>`                |        2        |      `McLainS3()`      |
-|               {ref}`McLain S4 <test-functions:mclain-s4>`                |        2        |      `McLainS4()`      |
-|               {ref}`McLain S5 <test-functions:mclain-s5>`                |        2        |      `McLainS5()`      |
-|       {ref}`Oakley & O'Hagan (2002) 1D <test-functions:oakley-1d>`       |        1        |      `Oakley1D()`      |
-|             {ref}`OTL Circuit <test-functions:otl-circuit>`              |     6 / 20      |     `OTLCircuit()`     |
-|             {ref}`Piston Simulation <test-functions:piston>`             |     7 / 20      |       `Piston()`       |
-|               {ref}`Robot Arm <test-functions:robot-arm>`                |        8        |      `RobotArm()`      |
-|           {ref}`Solar Cell Model <test-functions:solar-cell>`            |        5        |     `SolarCell()`      |
-|                  {ref}`Sulfur <test-functions:sulfur>`                   |        9        |       `Sulfur()`       |
-|     {ref}`Undamped Oscillator <test-functions:undamped-oscillator>`      |        6        | `UndampedOscillator()` |
-|       {ref}`Webster et al. (1996) 2D <test-functions:webster-2d>`        |        2        |     `Webster2D()`      |
-|          {ref}`Welch et al. (1992) <test-functions:welch1992>`           |       20        |     `Welch1992()`      |
-|             {ref}`Wing Weight <test-functions:wing-weight>`              |       10        |     `WingWeight()`     |
+|                                  Name                                   | Input Dimension |      Constructor       |
+|:-----------------------------------------------------------------------:|:---------------:|:----------------------:|
+|                  {ref}`Ackley <test-functions:ackley>`                  |        M        |       `Ackley()`       |
+|  {ref}`Alemazkoor & Meidani (2018) 2D <test-functions:alemazkoor-2d>`   |        2        |    `Alemazkoor2D()`    |
+| {ref}`Alemazkoor & Meidani (2018) 20D <test-functions:alemazkoor-20d>`  |       20        |   `Alemazkoor20D()`    |
+|                {ref}`Borehole <test-functions:borehole>`                |        8        |      `Borehole()`      |
+|        {ref}`Cheng and Sandu (2010) 2D <test-functions:cheng2d>`        |        2        |       `Cheng2D`        |
+|           {ref}`Coffee Cup Model <test-functions:coffee-cup>`           |        2        |     `CoffeeCup()`      |
+|      {ref}`Currin et al. (1988) Sine <test-functions:currin-sine>`      |        1        |     `CurrinSine()`     |
+|           {ref}`Damped Cosine <test-functions:damped-cosine>`           |        1        |    `DampedCosine()`    |
+|       {ref}`Damped Oscillator <test-functions:damped-oscillator>`       |        7        |  `DampedOscillator()`  |
+|  {ref}`Dette & Pepelyshev (2010) Curved <test-functions:dette-curved>`  |        3        |    `DetteCurved()`     |
+| {ref}`Dette & Pepelyshev (2010) Exponential <test-functions:dette-exp>` |        3        |      `DetteExp()`      |
+|                   {ref}`Flood <test-functions:flood>`                   |        8        |       `Flood()`        |
+|        {ref}`Forrester et al. (2008) <test-functions:forrester>`        |        1        |   `Forrester2008()`    |
+|              {ref}`(1st) Franke <test-functions:franke-1>`              |        2        |      `Franke1()`       |
+|              {ref}`(2nd) Franke <test-functions:franke-2>`              |        2        |      `Franke2()`       |
+|              {ref}`(3rd) Franke <test-functions:franke-3>`              |        2        |      `Franke3()`       |
+|              {ref}`(4th) Franke <test-functions:franke-4>`              |        2        |      `Franke4()`       |
+|              {ref}`(5th) Franke <test-functions:franke-5>`              |        2        |      `Franke5()`       |
+|              {ref}`(6th) Franke <test-functions:franke-6>`              |        2        |      `Franke6()`       |
+|            {ref}`Friedman (6D) <test-functions:friedman-6d>`            |        6        |     `Friedman6D()`     |
+|           {ref}`Friedman (10D) <test-functions:friedman-10d>`           |       10        |    `Friedman10D()`     |
+|       {ref}`Genz (Corner Peak) <test-functions:genz-corner-peak>`       |        M        |   `GenzCornerPeak()`   |
+|     {ref}`Gramacy (2007) 1D Sine <test-functions:gramacy-1d-sine>`      |        1        |   `Gramacy1DSine()`    |
+|         {ref}`Higdon (2002) Sine <test-functions:higdon-sine>`          |        1        |     `HigdonSine()`     |
+|    {ref}`Holsclaw et al. (2013) Sine <test-functions:holsclaw-sine>`    |        1        |    `HolsclawSine()`    |
+|  {ref}`Lim et al. (2002) Non-Polynomial <test-functions:lim-non-poly>`  |        2        |     `LimNonPoly()`     |
+|      {ref}`Lim et al. (2002) Polynomial <test-functions:lim-poly>`      |        2        |      `LimPoly()`       |
+|               {ref}`McLain S1 <test-functions:mclain-s1>`               |        2        |      `McLainS1()`      |
+|               {ref}`McLain S2 <test-functions:mclain-s2>`               |        2        |      `McLainS2()`      |
+|               {ref}`McLain S3 <test-functions:mclain-s3>`               |        2        |      `McLainS3()`      |
+|               {ref}`McLain S4 <test-functions:mclain-s4>`               |        2        |      `McLainS4()`      |
+|               {ref}`McLain S5 <test-functions:mclain-s5>`               |        2        |      `McLainS5()`      |
+|      {ref}`Oakley & O'Hagan (2002) 1D <test-functions:oakley-1d>`       |        1        |      `Oakley1D()`      |
+|             {ref}`OTL Circuit <test-functions:otl-circuit>`             |     6 / 20      |     `OTLCircuit()`     |
+|            {ref}`Piston Simulation <test-functions:piston>`             |     7 / 20      |       `Piston()`       |
+|               {ref}`Robot Arm <test-functions:robot-arm>`               |        8        |      `RobotArm()`      |
+|           {ref}`Solar Cell Model <test-functions:solar-cell>`           |        5        |     `SolarCell()`      |
+|                  {ref}`Sulfur <test-functions:sulfur>`                  |        9        |       `Sulfur()`       |
+|     {ref}`Undamped Oscillator <test-functions:undamped-oscillator>`     |        6        | `UndampedOscillator()` |
+|       {ref}`Webster et al. (1996) 2D <test-functions:webster-2d>`       |        2        |     `Webster2D()`      |
+|          {ref}`Welch et al. (1992) <test-functions:welch1992>`          |       20        |     `Welch1992()`      |
+|             {ref}`Wing Weight <test-functions:wing-weight>`             |       10        |     `WingWeight()`     |
 
 In a Python terminal, you can list all the available functions relevant
 for metamodeling applications using ``list_functions()``


Test patch:
diff --git a/docs/test-functions/available.md b/docs/test-functions/available.md
index 737e35b..6530e6b 100644
--- a/docs/test-functions/available.md
+++ b/docs/test-functions/available.md
@@ -38,6 +38,7 @@ regardless of their typical applications.
 |                 {ref}`Damped Cosine <test-functions:damped-cosine>`                 |        1        |        `DampedCosine()`         |
 |             {ref}`Damped Oscillator <test-functions:damped-oscillator>`             |        7        |      `DampedOscillator()`       |
 | {ref}`Damped Oscillator Reliability <test-functions:damped-oscillator-reliability>` |        8        | `DampedOscillatorReliability()` |
+|        {ref}`Dette & Pepelyshev (2010) Curved <test-functions:dette-curved>`        |        3        |         `DetteCurved()`         |
 |       {ref}`Dette & Pepelyshev (2010) Exponential <test-functions:dette-exp>`       |        3        |          `DetteExp()`           |
 |                         {ref}`Flood <test-functions:flood>`                         |        8        |            `Flood()`            |
 |              {ref}`Forrester et al. (2008) <test-functions:forrester>`              |        1        |        `Forrester2008()`        |
diff --git a/docs/test-functions/dette-curved.md b/docs/test-functions/dette-curved.md
new file mode 100644
index 0000000..07f83ec
--- /dev/null
+++ b/docs/test-functions/dette-curved.md
@@ -0,0 +1,96 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+(test-functions:dette-curved)=
+# Highly-Curved Function from Dette and Pepelyshev (2010)
+
+```{code-cell} ipython3
+import numpy as np
+import matplotlib.pyplot as plt
+import uqtestfuns as uqtf
+```
+
+The function is a three-dimensional, scalar-valued function.
+The function contains no cross-term but curved along each dimension.
+
+The function appeared in {cite}`Dette2010` as a test function for comparing
+different experimental designs in the construction of metamodels.
+
+## Test function instance
+
+To create a default instance of the test function:
+
+```{code-cell} ipython3
+my_testfun = uqtf.DetteCurved()
+```
+
+Check if it has been correctly instantiated:
+
+```{code-cell} ipython3
+print(my_testfun)
+```
+
+## Description
+
+The test function is defined as[^location]:
+
+$$
+\mathcal{M}(\boldsymbol{x}) = 4 \left( x_1 - 2 + 8 x_2 - 8 x_2^2 \right) + \left( 3 - 4 x_2 \right)^2 + 16 \left( x_3 + 1\right)^{0.5} \left( 2 x_3 - 1\right)^2,
+$$
+
+where $\boldsymbol{x} = \left( x_1, x_2, x_3 \right)$ is the three-dimensional
+vector of input variables further defined below.
+
+## Probabilistic input
+
+The probabilistic input model for the test function is shown below.
+
+```{code-cell} ipython3
+:tags: [hide-input]
+
+print(my_testfun.prob_input)
+```
+
+## Reference results
+
+This section provides several reference results of typical UQ analyses
+involving the test function.
+
+### Sample histogram
+
+Shown below is the histogram of the output based on $100'000$ random points:
+
+```{code-cell} ipython3
+:tags: [hide-input]
+
+my_testfun.prob_input.reset_rng(42)
+xx_test = my_testfun.prob_input.get_sample(100000)
+yy_test = my_testfun(xx_test)
+
+plt.hist(yy_test, bins="auto", color="#8da0cb");
+plt.grid();
+plt.ylabel("Counts [-]");
+plt.xlabel("$\mathcal{M}(X)$");
+plt.gcf().tight_layout(pad=3.0)
+plt.gcf().set_dpi(150);
+```
+
+## References
+
+```{bibliography}
+:style: unsrtalpha
+:filter: docname in docnames
+```
+
+[^location]: see Eq. (5), Section 3.1, p. 424, in {cite}`Dette2010`.
diff --git a/src/uqtestfuns/test_functions/__init__.py b/src/uqtestfuns/test_functions/__init__.py
index b756f6d..ee39ed0 100644
--- a/src/uqtestfuns/test_functions/__init__.py
+++ b/src/uqtestfuns/test_functions/__init__.py
@@ -14,7 +14,7 @@
 from .currin_sine import CurrinSine
 from .damped_cosine import DampedCosine
 from .damped_oscillator import DampedOscillator, DampedOscillatorReliability
-from .dette import DetteExp
+from .dette import DetteCurved, DetteExp
 from .flood import Flood
 from .forrester import Forrester2008
 from .four_branch import FourBranch
@@ -76,6 +76,7 @@
     "DampedCosine",
     "DampedOscillator",
     "DampedOscillatorReliability",
+    "DetteCurved",
     "DetteExp",
     "Flood",
     "Forrester2008",
diff --git a/src/uqtestfuns/test_functions/dette.py b/src/uqtestfuns/test_functions/dette.py
index fcf6db4..699738e 100644
--- a/src/uqtestfuns/test_functions/dette.py
+++ b/src/uqtestfuns/test_functions/dette.py
@@ -18,7 +18,7 @@
 from uqtestfuns.core.custom_typing import ProbInputSpecs
 from uqtestfuns.core.uqtestfun_abc import UQTestFunFixDimABC
 
-__all__ = ["DetteExp"]
+__all__ = ["DetteCurved", "DetteExp"]
 
 
 def evaluate_exp(xx: np.ndarray) -> np.ndarray:
@@ -41,6 +41,28 @@ def evaluate_exp(xx: np.ndarray) -> np.ndarray:
     return 100 * yy
 
 
+def evaluate_curved(xx: np.ndarray) -> np.ndarray:
+    """Evaluate the highly-curved function from Dette and Pepelyshev (2010).
+
+    Parameters
+    ----------
+    xx : np.ndarray
+        M-Dimensional input values given by an N-by-3 array where
+        N is the number of input values.
+
+    Returns
+    -------
+    np.ndarray
+        The output of the test function evaluated on the input values.
+        The output is a 1-dimensional array of length N.
+    """
+    term_1 = 4 * (xx[:, 0] - 2 + 8 * xx[:, 1] - 8 * xx[:, 1] ** 2)
+    term_2 = (3 - 4 * xx[:, 1]) ** 2
+    term_3 = (16 * (xx[:, 2] + 1) ** 0.5) * (2 * xx[:, 2] - 1) ** 2
+
+    return term_1 + term_2 + term_3
+
+
 class DetteExp(UQTestFunFixDimABC):
     """A concrete implementation of the exponential function."""
 
@@ -51,7 +73,7 @@ class DetteExp(UQTestFunFixDimABC):
             "function_id": "DetteExp",
             "description": (
                 "Input specification for the exponential test function "
-                "from Dette and Pepelyshev et al. (2010)"
+                "from Dette and Pepelyshev (2010)"
             ),
             "marginals": [
                 {
@@ -68,3 +90,32 @@ class DetteExp(UQTestFunFixDimABC):
     _available_parameters = None
 
     evaluate = staticmethod(evaluate_exp)  # type: ignore
+
+
+class DetteCurved(UQTestFunFixDimABC):
+    """A concrete implementation of the highly-curved function."""
+
+    _tags = ["metamodeling"]
+    _description = "Curved function from Dette and Pepelyshev (2010)"
+    _available_inputs: ProbInputSpecs = {
+        "Dette2010": {
+            "function_id": "DetteCurved",
+            "description": (
+                "Input specification for the highly-curved test function "
+                "from Dette and Pepelyshev (2010)"
+            ),
+            "marginals": [
+                {
+                    "name": f"x_{i + 1}",
+                    "distribution": "uniform",
+                    "parameters": [0, 1],
+                    "description": None,
+                }
+                for i in range(3)
+            ],
+            "copulas": None,
+        },
+    }
+    _available_parameters = None
+
+    evaluate = staticmethod(evaluate_curved)  # type: ignore