output_dimension is now property of UQTestFunBareABC

Introduce the `output_dimension` property for UQ test functions
and update related tests and documentations.

Furthermore, the high-level function `list_functions()`
is updated to display additional information related to
output dimension and parameterization in grid format.

This commit should resolve Issue #345.

Author: damar-wicaksono

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `output_dimension` is now property of `UQTestFunBareABC` and inherited to
+  all concrete classes of UQ test functions.
 - Printing a test function instance now shows whether the function is 
   parameterized or not.
 - The information related to the parameterization of a function is now
@@ -23,6 +25,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- `list_functions()` is now printed in grid format and include information
+  regarding the output dimension and the parameterization. Furthermore,
+  filtering can be done based on the input dimension, output dimension,
+  tag, and parameterization.
 - The class `UnivDist` has been renamed to `Marginal`. The name more clearly
   refers to one-dimensional marginal distributions (of a univariate random
   variable), which form a `ProbInput`.

README.md

@@ -33,17 +33,23 @@ To list the available functions:
 ```python-repl
 >>> import uqtestfuns as uqtf
 >>> uqtf.list_functions()
- No.            Constructor            Dimension                Application                Description
------  -----------------------------  -----------  --------------------------------------  ----------------------------------------------------------------------------
-  1              Ackley()                  M             optimization, metamodeling        Optimization test function from Ackley (1987)
-  2           Alemazkoor2D()               2                    metamodeling               Two-dimensional high-degree polynomial from Alemazkoor & Meidani (2018)
-  3             Borehole()                 8             metamodeling, sensitivity         Borehole function from Harper and Gupta (1983)
-  4           Bratley1992a()               M              integration, sensitivity         Integration test function #1 from Bratley et al. (1992)
-  5           Bratley1992b()               M              integration, sensitivity         Integration test function #2 from Bratley et al. (1992)
-  6           Bratley1992c()               M              integration, sensitivity         Integration test function #3 from Bratley et al. (1992)
-  7           Bratley1992d()               M              integration, sensitivity         Integration test function #4 from Bratley et al. (1992)
-  8         CantileverBeam2D()             2                    reliability                Cantilever beam reliability problem from Rajashekhar and Ellington (1993)
-  9         CircularPipeCrack()            2                    reliability                Circular pipe under bending moment from Verma et al. (2015)
++-------+-------------------------------+-----------+------------+----------+---------------+--------------------------------+
+|  No.  |          Constructor          |  # Input  |  # Output  |  Param.  |  Application  | Description                    |
++=======+===============================+===========+============+==========+===============+================================+
+|   1   |           Ackley()            |     M     |     1      |   True   | optimization, | Optimization test function     |
+|       |                               |           |            |          | metamodeling  | from Ackley (1987)             |
++-------+-------------------------------+-----------+------------+----------+---------------+--------------------------------+
+|   2   |        Alemazkoor20D()        |    20     |     1      |  False   | metamodeling  | High-dimensional low-degree    |
+|       |                               |           |            |          |               | polynomial from Alemazkoor &   |
+|       |                               |           |            |          |               | Meidani (2018)                 |
++-------+-------------------------------+-----------+------------+----------+---------------+--------------------------------+
+|   3   |        Alemazkoor2D()         |     2     |     1      |  False   | metamodeling  | Low-dimensional high-degree    |
+|       |                               |           |            |          |               | polynomial from Alemazkoor &   |
+|       |                               |           |            |          |               | Meidani (2018)                 |
++-------+-------------------------------+-----------+------------+----------+---------------+--------------------------------+
+|   4   |          Borehole()           |     8     |     1      |  False   | metamodeling, | Borehole function from Harper  |
+|       |                               |           |            |          |  sensitivity  | and Gupta (1983)               |
++-------+-------------------------------+-----------+------------+----------+---------------+--------------------------------+
 ...
 ```
 
@@ -53,33 +59,35 @@ and sensitivity analysis purposes; to create an instance of this test function:
 ```python-repl
 >>> my_testfun = uqtf.Borehole()
 >>> print(my_testfun)
-Name              : Borehole
-Spatial dimension : 8
-Description       : Borehole function from Harper and Gupta (1983)
+Function ID      : Borehole
+Input Dimension  : 8
+Output Dimension : 1
+Parameterized    : False
+Description      : Borehole function from Harper and Gupta (1983)
 ```
 
 The probabilistic input specification of this test function is built-in:
 
 ```python-repl
 >>> print(my_testfun.prob_input)
-Name         : Borehole-Harper-1983
-Spatial Dim. : 8
-Description  : Probabilistic input model of the Borehole model from Harper and Gupta (1983).
-Marginals    :
+Name            : Borehole-Harper-1983
+Input Dimension : 8
+Description     : Probabilistic input model of the Borehole model from
+                  Harper and Gupta (1983).
+Marginals       :
 
-  No.   Name    Distribution        Parameters                          Description                  
-                                                                                                     
+ No.    Name    Distribution        Parameters                          Description
 -----  ------  --------------  ---------------------  -----------------------------------------------
-    1    rw        normal      [0.1       0.0161812]            radius of the borehole [m]
-    2    r       lognormal        [7.71   1.0056]                 radius of influence [m]
-    3    Tu       uniform        [ 63070. 115600.]      transmissivity of upper aquifer [m^2/year]
-    4    Hu       uniform          [ 990. 1100.]         potentiometric head of upper aquifer [m]
-    5    Tl       uniform          [ 63.1 116. ]        transmissivity of lower aquifer [m^2/year]
-    6    Hl       uniform           [700. 820.]          potentiometric head of lower aquifer [m]    
-    7    L        uniform          [1120. 1680.]                length of the borehole [m]                                       
-    8    Kw       uniform         [ 9985. 12045.]     hydraulic conductivity of the borehole [m/year]
-
-    Copulas      : None
+  1      rw        normal      [0.1       0.0161812]            radius of the borehole [m]
+  2      r       lognormal        [7.71   1.0056]                 radius of influence [m]
+  3      Tu       uniform        [ 63070. 115600.]      transmissivity of upper aquifer [m^2/year]
+  4      Hu       uniform          [ 990. 1100.]         potentiometric head of upper aquifer [m]
+  5      Tl       uniform          [ 63.1 116. ]        transmissivity of lower aquifer [m^2/year]
+  6      Hl       uniform           [700. 820.]          potentiometric head of lower aquifer [m]
+  7      L        uniform          [1120. 1680.]                length of the borehole [m]
+  8      Kw       uniform         [ 9985. 12045.]     hydraulic conductivity of the borehole [m/year]
+
+Copulas         : None
 ```
 
 A sample of input values can be generated from the input model:

docs/fundamentals/integration.md

@@ -35,5 +35,5 @@ using the ``tag`` parameter:
 
 import uqtestfuns as uqtf
 
-uqtf.list_functions(tag="integration")
+uqtf.list_functions(tag="integration", tablefmt="html")
 ```

docs/fundamentals/metamodeling.md

@@ -58,5 +58,5 @@ using the ``tag`` parameter:
 
 import uqtestfuns as uqtf
 
-uqtf.list_functions(tag="metamodeling")
+uqtf.list_functions(tag="metamodeling", tablefmt="html")
 ```

docs/fundamentals/optimization.md

@@ -31,5 +31,5 @@ using the ``tag`` parameter:
 
 import uqtestfuns as uqtf
 
-uqtf.list_functions(tag="optimization")
+uqtf.list_functions(tag="optimization", tablefmt="html")
 ```

docs/fundamentals/reliability.md

@@ -39,7 +39,7 @@ using the ``tag`` parameter:
 
 import uqtestfuns as uqtf
 
-uqtf.list_functions(tag="reliability")
+uqtf.list_functions(tag="reliability", tablefmt="html")
 ```
 
 ## About reliability analysis

docs/fundamentals/sensitivity.md

@@ -45,5 +45,5 @@ using the ``tag`` parameter:
 
 import uqtestfuns as uqtf
 
-uqtf.list_functions(tag="sensitivity")
+uqtf.list_functions(tag="sensitivity", tablefmt="html")
 ```

src/uqtestfuns/core/uqtestfun_abc.py

@@ -64,6 +64,7 @@ def __init__(
         self.prob_input = prob_input
         self._parameters = parameters
         self._function_id = function_id
+        self._output_dimension: Optional[int] = None
 
     @property
     def prob_input(self) -> ProbInput:
@@ -105,6 +106,21 @@ def input_dimension(self) -> int:
         """The input dimension of the UQ test function."""
         return self.prob_input.input_dimension
 
+    @property
+    def output_dimension(self) -> int:
+        if self._output_dimension is None:
+            xx = self.prob_input.get_sample()
+            yy = self(xx)
+            if yy.ndim == 1:
+                self._output_dimension = 1
+            elif yy.ndim == 2:
+                self._output_dimension = yy.shape[1]
+            else:
+                self._output_dimension = yy.shape[1:]
+            return self._output_dimension
+
+        return self._output_dimension
+
     def transform_sample(
         self,
         xx: np.ndarray,
@@ -151,9 +167,10 @@ def transform_sample(
 
     def __str__(self):
         out = (
-            f"Function ID     : {self.function_id}\n"
-            f"Input Dimension : {self.input_dimension}\n"
-            f"Parameterized   : {bool(self.parameters)}"
+            f"Function ID      : {self.function_id}\n"
+            f"Input Dimension  : {self.input_dimension}\n"
+            f"Output Dimension : {self.output_dimension}\n"
+            f"Parameterized    : {bool(self.parameters)}"
         )
 
         return out
@@ -380,10 +397,11 @@ def description(cls) -> Optional[str]:
 
     def __str__(self):
         out = (
-            f"Function ID     : {self.function_id}\n"
-            f"Input Dimension : {self.input_dimension}\n"
-            f"Parameterized   : {bool(self.parameters)}\n"
-            f"Description     : {self.description}"
+            f"Function ID      : {self.function_id}\n"
+            f"Input Dimension  : {self.input_dimension}\n"
+            f"Output Dimension : {self.output_dimension}\n"
+            f"Parameterized    : {bool(self.parameters)}\n"
+            f"Description      : {self.description}"
         )
 
         return out