hydroBayesCal 0.1.0__py3-none-any.whl

hydroBayesCal/__init__.py

@@ -0,0 +1 @@
+"""hydroBayesCal: surrogate-assisted Bayesian calibration for hydrodynamic models."""

hydroBayesCal/delft3d/__init__.py

@@ -0,0 +1,5 @@
+# Delft3D-FLOW bindings for hydroBayesCal (planned -- not yet implemented).
+#
+# This sub-package is a placeholder that defines the intended interface for
+# coupling HydroBayesCal to Delft3D-FLOW (Deltares). See
+# ``control_delft3d.Delft3DModel`` and the ``usage-delft3d`` documentation page.

hydroBayesCal/delft3d/control_delft3d.py

@@ -0,0 +1,106 @@
+"""
+Delft3D-FLOW binding for HydroBayesCal -- **planned, not yet implemented**.
+
+This module is a placeholder that mirrors the TELEMAC
+(:mod:`hydroBayesCal.telemac.control_telemac`) and OpenFOAM
+(:mod:`hydroBayesCal.openfoam.control_openfoam`) bindings. It defines the
+intended public interface for coupling HydroBayesCal to the structured-grid
+**Delft3D-FLOW** engine (Deltares) so that the coupling can be implemented
+incrementally without changing the surrogate / Bayesian-active-learning layer.
+
+The :class:`Delft3DModel` class subclasses
+:class:`hydroBayesCal.hysim.HydroSimulations`; the Python attribute names are
+shared across solvers, while the *string and file conventions* below are
+Delft3D-specific and must be preserved when the binding is filled in:
+
+* ``<case>.mdf`` -- master definition FLOW file (the control file); the engine
+  is launched through ``config_d_hydro.xml`` and the ``d_hydro`` executable.
+* Bed roughness via Chézy / Manning / White-Colebrook (``.rgh`` file or
+  ``Roughness`` keywords in the ``.mdf``); eddy viscosity/diffusivity
+  ``Vicouv`` / ``Dicouv``.
+* ``trim-<case>.dat`` / ``trim-<case>.def`` -- NEFIS map (field) output.
+* ``trih-<case>.dat`` / ``trih-<case>.def`` -- NEFIS history (monitoring-point)
+  output.
+
+See the :doc:`usage-delft3d <usage-delft3d>` page for the planned workflow.
+"""
+
+from hydroBayesCal.hysim import HydroSimulations
+
+#: Marker so callers / tests can detect that the binding is not ready yet.
+DELFT3D_BINDING_IMPLEMENTED = False
+
+_NOT_IMPLEMENTED_MSG = (
+    "The Delft3D-FLOW binding is planned but not yet implemented. "
+    "Use the TELEMAC (hydroBayesCal.telemac.control_telemac.TelemacModel) or "
+    "OpenFOAM (hydroBayesCal.openfoam.control_openfoam.OpenFOAMModel) bindings, "
+    "or contribute the Delft3D-FLOW implementation in "
+    "hydroBayesCal.delft3d.control_delft3d."
+)
+
+
+class Delft3DModel(HydroSimulations):
+    """
+    Placeholder Delft3D-FLOW model wrapper (planned).
+
+    Defines the intended constructor signature and interface but raises
+    :class:`NotImplementedError`. Instantiating it documents the Delft3D-specific
+    configuration the binding will need; it does not run a simulation.
+
+    Parameters
+    ----------
+    control_file : str
+        Master definition FLOW file, default ``"control.mdf"`` (Delft3D-FLOW
+        convention ``<case>.mdf``).
+    d_hydro_config : str
+        Runtime configuration passed to the ``d_hydro`` launcher, default
+        ``"config_d_hydro.xml"``.
+    flow_executable : str
+        Name of the Delft3D-FLOW launcher on ``PATH``, default ``"d_hydro"``.
+    roughness_formulation : str
+        Bed-roughness law used for the calibration parameters
+        (``"Chezy"``, ``"Manning"`` or ``"WhiteColebrook"``).
+    map_file_base, history_file_base : str
+        Base names of the NEFIS map (``trim-<case>``) and history
+        (``trih-<case>``) output files.
+    **kwargs
+        Common :class:`~hydroBayesCal.hysim.HydroSimulations` parameters
+        (``model_dir``, ``res_dir``, ``calibration_pts_file_path``,
+        ``calibration_parameters``, ``param_values``, ``calibration_quantities``,
+        ``init_runs``, ``max_runs`` ...).
+
+    Raises
+    ------
+    NotImplementedError
+        Always -- the binding is not implemented yet.
+    """
+
+    def __init__(
+        self,
+        control_file="control.mdf",
+        d_hydro_config="config_d_hydro.xml",
+        flow_executable="d_hydro",
+        roughness_formulation="Manning",
+        map_file_base="trim",
+        history_file_base="trih",
+        *args,
+        **kwargs,
+    ):
+        # Keep the Delft3D-specific configuration on the instance so the intended
+        # interface is documented, then make the not-yet-implemented state
+        # explicit instead of silently constructing a non-functional model.
+        self.control_file = control_file
+        self.d_hydro_config = d_hydro_config
+        self.flow_executable = flow_executable
+        self.roughness_formulation = roughness_formulation
+        self.map_file_base = map_file_base
+        self.history_file_base = history_file_base
+        raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+    def run_multiple_simulations(self, *args, **kwargs):
+        """Run the Delft3D-FLOW experimental-design simulations (planned)."""
+        raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+    def output_processing(self, *args, **kwargs):
+        """Extract calibration quantities from NEFIS map/history output (planned)."""
+        raise NotImplementedError(_NOT_IMPLEMENTED_MSG)

hydroBayesCal/doepy/DOE_functions.py

@@ -0,0 +1,522 @@
+"""
+Core DOE functions
+"""
+from pyDOE import *
+from hydroBayesCal.doepy.pyDOE_corrected import *
+#from diversipy import *
+import pandas as _pd
+import numpy as _np
+
+
+def construct_df(x, r):
+    """Construct a DataFrame from a numpy array generated by PyDOE function and individual lists
+
+    :param x: data
+    :param r:
+    :return: pandas.DataFrame
+    """
+    df = _pd.DataFrame(data=x, dtype='float32')
+    for i in df.index:
+        for j in range(len(list(df.iloc[i]))):
+            df.iloc[i][j] = r[j][int(df.iloc[i][j])]
+    return df
+
+
+def construct_df_from_matrix(x, factor_array):
+    """
+    Construct a DataFrame from a matrix with floating point numbers between -1 and +1. Both inputs x
+     and factor_array are assumed to be numpy arrays. Numbers in x (which is output of a design-of-experiment
+     build) are projected onto the factor array ranges. factor_array is assumed to have only min and max ranges.
+     The array x is assumed to have numbers ranging from -1 to 1.
+
+    :param _np.array x: output of a design-of-experiment build
+    :param _np.array factor_array: only min and max ranges
+    :return: pandas.DataFrame
+    """
+
+    row_num = x.shape[0]  # Number of rows in the matrix x
+    col_num = x.shape[1]  # Number of columns in the matrix x
+
+    empty = _np.zeros((row_num, col_num))
+
+    def simple_substitution(idx, factor_list):
+        if idx == -1:
+            return factor_list[0]
+        elif idx == 0:
+            return factor_list[1]
+        elif idx == 1:
+            return factor_list[2]
+        else:
+            alpha = _np.abs(factor_list[2] - factor_list[0]) / 2
+            if idx < 0:
+                beta = _np.abs(idx) - 1
+                return factor_list[0] - (beta * alpha)
+            else:
+                beta = idx - 1
+                return factor_list[2] + (beta * alpha)
+
+    for i in range(row_num):
+        for j in range(col_num):
+            empty[i, j] = simple_substitution(x[i, j], factor_array[j])
+
+    return _pd.DataFrame(data=empty)
+
+
+def construct_df_from_random_matrix(x, factor_array):
+    """
+    This function constructs a DataFrame out of matrix x and factor_array, both of which are assumed to be numpy arrays.
+    It projects the numbers in the x (which is output of a design-of-experiment build) to the factor array ranges.
+    Here factor_array is assumed to have only min and max ranges.
+    Matrix x is assumed to have numbers ranging from 0 to 1 only.
+
+    :param _np.array x: output of a design-of-experiment build
+    :param _np.array factor_array: only min and max ranges
+    :return: pandas.DataFrame
+    """
+
+    row_num = x.shape[0]  # Number of rows in the matrix x
+    col_num = x.shape[1]  # Number of columns in the matrix x
+
+    empty = _np.zeros((row_num, col_num))
+
+    def simple_substitution(idx, factor_list):
+        alpha = _np.abs(factor_list[1] - factor_list[0])
+        beta = idx
+        return factor_list[0] + (beta * alpha)
+
+    for i in range(row_num):
+        for j in range(col_num):
+            empty[i, j] = simple_substitution(x[i, j], factor_array[j])
+
+    return _pd.DataFrame(data=empty)
+
+
+def build_full_fact(factor_level_ranges):
+    """
+    Builds a full factorial design dataframe from a dictionary of factor/level ranges
+
+    :param dict factor_level_ranges: Something like {'Pressure':[50,60,70],'Temperature':[290, 320, 350],'Flow rate':[0.9,1.0]}
+    """
+
+    factor_lvl_count = []
+    factor_lists = []
+
+    for key in factor_level_ranges:
+        factor_lvl_count.append(len(factor_level_ranges[key]))
+        factor_lists.append(factor_level_ranges[key])
+
+    x = fullfact_corrected(factor_lvl_count)
+    df = construct_df(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+
+    return df
+
+
+def build_frac_fact(factor_level_ranges, gen_string):
+    """
+    Builds a 2-level fractional factorial DataFrame from a dictionary and a generator string
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+
+    This function requires a little more knowledge of how the confounding will be allowed.
+    This means that some factor effects get muddled with other interaction effects, so it’s harder to distinguish between them).
+
+    Let’s assume that we just can’t afford (for whatever reason) the number of runs in a full-factorial design. We can systematically decide on a fraction of the full-factorial by allowing some of the factor main effects to be confounded with other factor interaction effects.
+    This is done by defining an alias structure that defines, symbolically, these interactions. These alias structures are written like “C = AB” or “I = ABC”, or “AB = CD”, etc.
+    These define how one column is related to the others.
+
+    EXAMPLE
+    ------------
+    For example, the alias “C = AB” or “I = ABC” indicate that there are three factors (A, B, and C) and that the main effect of factor C is confounded with the interaction effect of the product AB, and by extension, A is confounded with BC and B is confounded with AC.
+    A full- factorial design with these three factors results in a design matrix with 8 runs, but we will assume that we can only afford 4 of those runs.
+    To create this fractional design, we need a matrix with three columns, one for A, B, and C, only now where the levels in the C column is created by the product of the A and B columns.
+    """
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    if factor_count != len(gen_string.split(' ')):
+        print(
+            "Length of the generator string for the fractional factorial build does not match the length of the process variables dictionary")
+        return None
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = fracfact(gen_string)
+
+    def index_change(x):
+        if x == -1:
+            return 0
+        else:
+            return x
+
+    vfunc = _np.vectorize(index_change)
+    x = vfunc(x)
+
+    df = construct_df(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+
+    return df
+
+
+def build_plackett_burman(factor_level_ranges):
+    """
+    Builds a Plackett-Burman dataframe from a dictionary of factor/level ranges.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+
+    Plackett–Burman designs are experimental designs presented in 1946 by Robin L. Plackett and J. P. Burman while working in the British Ministry of Supply.(Their goal was to find experimental designs for investigating the dependence of some measured quantity on a number of independent variables (factors), each taking L levels, in such a way as to minimize the variance of the estimates of these dependencies using a limited number of experiments.
+
+    Interactions between the factors were considered negligible. The solution to this problem is to find an experimental design where each combination of levels for any pair of factors appears the same number of times, throughout all the experimental runs (refer to table).
+    A complete factorial design would satisfy this criterion, but the idea was to find smaller designs.
+
+    These designs are unique in that the number of trial conditions (rows) expands by multiples of four (e.g. 4, 8, 12, etc.).
+    The max number of columns allowed before a design increases the number of rows is always one less than the next higher multiple of four.
+    """
+
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = pbdesign(factor_count)
+
+    def index_change(x):
+        if x == -1:
+            return 0
+        else:
+            return x
+
+    vfunc = _np.vectorize(index_change)
+    x = vfunc(x)
+
+    df = construct_df(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+
+    return df
+
+
+def build_sukharev(factor_level_ranges, num_samples=None):
+    """
+    Builds a Sukharev-grid hypercube design dataframe from a dictionary of factor/level ranges.
+    Number of samples raised to the power of (1/dimension), where dimension is the number of variables, must be an integer.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+    num_samples: Number of samples to be generated
+
+    Special property of this grid is that points are not placed on the boundaries of the hypercube, but at centroids of the  subcells constituted by individual samples.
+    This design offers optimal results for the covering radius regarding distances based on the max-norm.
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    check = num_samples ** (1 / factor_count)
+    if (check - int(check)) > 1e-5:
+        num_samples = (int(check) + 1) ** factor_count
+        print("\nNumber of samples not adequate to fill a Sukharev grid. Increasing sample size to: ", num_samples)
+
+    x = sukharev_grid(num_points=num_samples, dimension=factor_count)
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_random_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df
+
+
+def build_box_behnken(factor_level_ranges, center=1):
+    """
+    Builds a Box-Behnken design dataframe from a dictionary of factor/level ranges.
+    Note 3 levels of factors are necessary. If not given, the function will automatically create 3 levels by linear mid-section method.
+    Example of the dictionary:
+    {'Pressure':[50,60,70],'Temperature':[290, 320, 350],'Flow rate':[0.9,1.0,1.1]}
+
+    In statistics, Box–Behnken designs are experimental designs for response surface methodology, devised by George E. P. Box and Donald Behnken in 1960, to achieve the following goals:
+        * Each factor, or independent variable, is placed at one of three equally spaced values, usually coded as −1, 0, +1. (At least three levels are needed for the following goal.)
+        * The design should be sufficient to fit a quadratic model, that is, one containing squared terms, products of two factors, linear terms and an intercept.
+        * The ratio of the number of experimental points to the number of coefficients in the quadratic model should be reasonable (in fact, their designs kept it in the range of 1.5 to 2.6).*estimation variance should more or less depend only on the distance from the centre (this is achieved exactly for the designs with 4 and 7 factors), and should not vary too much inside the smallest (hyper)cube containing the experimental points.
+    """
+
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) == 2:
+            factor_level_ranges[key].append((factor_level_ranges[key][0] + factor_level_ranges[key][1]) / 2)
+            factor_level_ranges[key].sort()
+            print(f"{key} had only two end points. Creating a mid-point by averaging them")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = bbdesign_corrected(factor_count, center=center)
+    x = x + 1  # Adjusting the index up by 1
+
+    df = construct_df(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+
+    return df
+
+
+def build_central_composite(factor_level_ranges, center=(2, 2), alpha='o', face='ccc'):
+    """
+    Builds a central-composite design dataframe from a dictionary of factor/level ranges.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+
+    In statistics, a central composite design is an experimental design, useful in response surface methodology, for building a second order (quadratic) model for the response variable without needing to use a complete three-level factorial experiment.
+    The design consists of three distinct sets of experimental runs:
+        * A factorial (perhaps fractional) design in the factors studied, each having two levels;
+        * A set of center points, experimental runs whose values of each factor are the medians of the values used in the factorial portion. This point is often replicated in order to improve the precision of the experiment;
+        * A set of axial points, experimental runs identical to the centre points except for one factor, which will take on values both below and above the median of the two factorial levels, and typically both outside their range. All factors are varied in this way.
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    # Creates the mid-points by averaging the low and high levels
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) == 2:
+            factor_level_ranges[key].append((factor_level_ranges[key][0] + factor_level_ranges[key][1]) / 2)
+            factor_level_ranges[key].sort()
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = ccdesign(factor_count, center=center, alpha=alpha, face=face)
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df
+
+
+def build_lhs(factor_level_ranges, num_samples=None, prob_distribution=None):
+    """
+    Builds a Latin Hypercube design dataframe from a dictionary of factor/level ranges.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+    num_samples: Number of samples to be generated
+    prob_distribution: Analytical probability distribution to be applied over the randomized sampling. 
+    Takes strings like: 'Normal', 'Poisson', 'Exponential', 'Beta', 'Gamma'
+
+    Latin hypercube sampling (LHS) is a form of stratified sampling that can be applied to multiple variables. The method commonly used to reduce the number or runs necessary for a Monte Carlo simulation to achieve a reasonably accurate random distribution. LHS can be incorporated into an existing Monte Carlo model fairly easily, and work with variables following any analytical probability distribution.
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    if not num_samples:  # i.e. num_samples = None
+        num_samples = factor_count
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = lhs(n=factor_count, samples=num_samples)
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_random_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df
+
+
+def build_space_filling_lhs(factor_level_ranges, num_samples=None):
+    """
+    Builds a space-filling Latin Hypercube design dataframe from a dictionary of factor/level ranges.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+    num_samples: Number of samples to be generated
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    if not num_samples:  # i.e. num_samples = None
+        num_samples = factor_count
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = transform_spread_out(
+        lhd_matrix(num_points=num_samples, dimension=factor_count))  # create latin hypercube design
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_random_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df
+
+
+def build_random_k_means(factor_level_ranges, num_samples=None):
+    """
+    Designs with random _k-means_ clusters from a dictionary of process variables.
+    Produce a centroidal Voronoi tesselation of the unit random hypercube and generate k-means clusters.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+    num_samples: Number of samples to be generated
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    if not num_samples:  # i.e. num_samples = None
+        num_samples = factor_count
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = random_k_means(num_points=num_samples, dimension=factor_count)  # create latin hypercube design
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_random_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df
+
+
+def build_maximin(factor_level_ranges, num_samples=None):
+    """
+    Builds a maximin reconstructed design dataframe from a dictionary of factor/level ranges.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+    num_samples: Number of samples to be generated
+
+    This algorithm carries out a user-specified number of iterations to maximize the minimal distance of a point in the set to
+        * other points in the set,
+        * existing (fixed) points,
+        * the boundary of the hypercube.
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    if not num_samples:  # i.e. num_samples = None
+        num_samples = factor_count
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = maximin_reconstruction(num_points=num_samples, dimension=factor_count)  # create latin hypercube design
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_random_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df
+
+
+def build_halton(factor_level_ranges, num_samples=None):
+    """
+    Builds a Halton matrix based design from a dictionary of process variables. Output is a
+    quasirandom dataframe from a dictionary of factor/level ranges using prime numbers as seed.
+    Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+    num_samples: Number of samples to be generated
+
+    Quasirandom sequence using the default initialization with first n prime numbers equal to the number of factors/variables.
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    if not num_samples:  # i.e. num_samples = None
+        num_samples = factor_count
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = halton(num_points=num_samples, dimension=factor_count)  # create Halton matrix design
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_random_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df
+
+
+def build_uniform_random(factor_level_ranges, num_samples=None):
+    """
+    Builds a design dataframe with samples drawn from uniform random distribution based on a dictionary
+    of factor/level ranges. Only min and max values of the range are required.
+    Example of the dictionary:
+    {'Pressure':[50,70],'Temperature':[290, 350],'Flow rate':[0.9,1.0]}
+    num_samples: Number of samples to be generated
+    """
+    for key in factor_level_ranges:
+        if len(factor_level_ranges[key]) != 2:
+            factor_level_ranges[key][1] = factor_level_ranges[key][-1]
+            factor_level_ranges[key] = factor_level_ranges[key][:2]
+            print(f"{key} had more than two levels. Assigning the end point to the high level.")
+
+    factor_count = len(factor_level_ranges)
+    factor_lists = []
+
+    if not num_samples:  # i.e. num_samples = None
+        num_samples = factor_count
+
+    for key in factor_level_ranges:
+        factor_lists.append(factor_level_ranges[key])
+
+    x = random_uniform(num_points=num_samples, dimension=factor_count)  # create Halton matrix design
+    factor_lists = _np.array(factor_lists)
+
+    df = construct_df_from_random_matrix(x, factor_lists)
+    df.columns = factor_level_ranges.keys()
+    return df