Built-in functionalities

Factory functions and implementations for built-in samplers, benchmark functions, and optimizers. These can be instantiated by name using the factory functions or imported directly from their submodules.

See also

• Guide: Built-in Defaults for a quick reference with tables and examples
• Tutorials: Benchmark Functions | Built-in Optimizers | Built-in Samplers

f3dasm.create_sampler(sampler: str | DictConfig, **parameters) -> Block

Create a sampler block from one of the built-in samplers.

Parameters:

Name	Type	Description	Default
sampler	str | DictConfig	Name of the built-in sampler. Accepted values (issue #289): "random_sampler" (preferred) or "random" (deprecated): uniform random sampling. Accepted parameters: seed. "latin_sampler" (preferred) or "latin" (deprecated): Latin-Hypercube sampling. Accepted parameters: seed. "sobol_sampler" (preferred) or "sobol" (deprecated): Sobol low-discrepancy sequence sampling. Accepted parameters: seed. "grid_sampler" (preferred) or "grid" (deprecated): full cross-product grid. Accepted parameters: stepsize_continuous_parameters. Can also be a Hydra DictConfig that instantiates a sampler block directly.	required
**parameters		Additional keyword arguments passed when initializing the sampler. Only the keywords documented per-backend above are accepted; any other keyword raises a TypeError so typos and stale options do not silently get ignored.	required

Returns:

Type	Description
Block	Block object of the sampler

Raises:

Type	Description
KeyError	If the built-in sampler name is not recognized.
TypeError	If sampler is not a str or DictConfig, or if parameters contains a keyword the chosen backend does not accept.

Source code in src/f3dasm/_src/samplers.py

def create_sampler(sampler: str | DictConfig, **parameters) -> Block:
    """
    Create a sampler block from one of the built-in samplers.

    Parameters
    ----------
    sampler : str | DictConfig
        Name of the built-in sampler. Accepted values (issue #289):

        - ``"random_sampler"`` (preferred) or ``"random"`` (deprecated):
          uniform random sampling. Accepted ``parameters``: ``seed``.
        - ``"latin_sampler"`` (preferred) or ``"latin"`` (deprecated):
          Latin-Hypercube sampling. Accepted ``parameters``: ``seed``.
        - ``"sobol_sampler"`` (preferred) or ``"sobol"`` (deprecated):
          Sobol low-discrepancy sequence sampling. Accepted
          ``parameters``: ``seed``.
        - ``"grid_sampler"`` (preferred) or ``"grid"`` (deprecated): full
          cross-product grid. Accepted ``parameters``:
          ``stepsize_continuous_parameters``.

        Can also be a Hydra ``DictConfig`` that instantiates a sampler
        block directly.
    **parameters
        Additional keyword arguments passed when initializing the sampler.
        Only the keywords documented per-backend above are accepted; any
        other keyword raises a ``TypeError`` so typos and stale options
        do not silently get ignored.

    Returns
    -------
    Block
        Block object of the sampler

    Raises
    ------
    KeyError
        If the built-in sampler name is not recognized.
    TypeError
        If ``sampler`` is not a ``str`` or ``DictConfig``, or if
        ``parameters`` contains a keyword the chosen backend does not
        accept.
    """
    if isinstance(sampler, str):
        filtered_name = (
            sampler.lower().replace(" ", "").replace("-", "").replace("_", "")
        )

        if filtered_name in SAMPLER_MAPPING:
            # Old, short keys (issue #289): emit a DeprecationWarning so
            # users can move to the explicit `<name>_sampler` form.
            if not filtered_name.endswith("sampler"):
                _warn_deprecated_sampler_name(sampler)
            _validate_sampler_parameters(filtered_name, parameters)
            return SAMPLER_MAPPING[filtered_name](**parameters)

        else:
            raise KeyError(f"Unknown built-in sampler name: {sampler}")

    elif isinstance(sampler, DictConfig):
        return instantiate(sampler)

    else:
        raise TypeError(f"Unknown sampler type given: {type(sampler)}")

f3dasm.create_datagenerator(data_generator: str, output_names: str | Iterable[str], **parameters) -> DataGenerator

Create a DataGenerator block from one of the built-in data generators.

Parameters:

Name	Type	Description	Default
data_generator	str | DataGenerator	name of the built-in data generator. This can be a string with the name of the data generator, a Block object (this will just by-pass the function), or a function.	required
**parameters		Additional keyword arguments passed when initializing the data generator	required

Returns:

Type	Description
DataGenerator	DataGenerator object

Raises:

Type	Description
KeyError	If the built-in sampler data generator is not recognized.
TypeError	If the given type is not recognized.

Source code in src/f3dasm/_src/datageneration/datagenerator_factory.py

def create_datagenerator(
    data_generator: str, output_names: str | Iterable[str], **parameters
) -> DataGenerator:
    """
    Create a DataGenerator block from one of the built-in data generators.

    Parameters
    ----------
    data_generator : str | DataGenerator
        name of the built-in data generator. This can be a string with the name
        of the data generator, a Block object (this will just by-pass the
        function), or a function.
    **parameters
        Additional keyword arguments passed when initializing the data
        generator

    Returns
    -------
    DataGenerator
        DataGenerator object

    Raises
    ------
    KeyError
        If the built-in sampler data generator is not recognized.
    TypeError
        If the given type is not recognized.
    """
    # If the data generator is a string, check if it is a known data generator
    if isinstance(data_generator, str):
        filtered_name = (
            data_generator.lower()
            .replace(" ", "")
            .replace("-", "")
            .replace("_", "")
            .replace(".", "")
        )

        if filtered_name in BENCHMARK_FUNCTIONS:
            return datagenerator(output_names=output_names)(
                BENCHMARK_FUNCTIONS[filtered_name]
            )

        else:
            raise KeyError(f"Unknown data generator name: {data_generator}")

    # If the data generator is not a known type, raise an error
    else:
        raise TypeError(f"Unknown data generator type: {type(data_generator)}")

f3dasm.create_optimizer(optimizer: str | DictConfig, **hyperparameters) -> Block

Create an optimizer block from one of the built-in optimizers.

The returned block is always a single step of the optimizer's work, never a full loop:

• For ask/tell optimizers (e.g. "tpesampler") the block is the per-iteration update step and must be chained with a data generator and wrapped in a :class:LoopBlock::

  tpe = create_optimizer("tpesampler", output_name="y") step = (tpe >> f).loop(50) data = step.call(data)

• For scipy optimizers (e.g. "cg", "lbfgsb", "neldermead") the block is a one-shot optimizer that runs scipy's own inner loop on a single call; pass maxiter via hyperparameters, and do not wrap it in a :class:LoopBlock::

  step = create_optimizer( "cg", data_generator=f, output_name="y", input_name="x", maxiter=50, ) data = step.call(data)

Parameters:

Name	Type	Description	Default
optimizer	str | DictConfig	Name of the built-in optimizer, or a Hydra DictConfig that instantiates an optimizer block.	required
**hyperparameters		Forwarded to the underlying factory function.	required

Returns:

Type	Description
Block	Configured optimizer block.

Raises:

Type	Description
KeyError	If the built-in optimizer name is not recognized.
TypeError	If optimizer is not a str or DictConfig.

Source code in src/f3dasm/_src/optimization/optimizer_factory.py

def create_optimizer(optimizer: str | DictConfig, **hyperparameters) -> Block:
    """Create an optimizer block from one of the built-in optimizers.

    The returned block is always a single step of the optimizer's work,
    never a full loop:

    - For ask/tell optimizers (e.g. ``"tpesampler"``) the block is the
      per-iteration update step and must be chained with a data generator
      and wrapped in a :class:`LoopBlock`::

          tpe = create_optimizer("tpesampler", output_name="y")
          step = (tpe >> f).loop(50)
          data = step.call(data)

    - For scipy optimizers (e.g. ``"cg"``, ``"lbfgsb"``, ``"neldermead"``)
      the block is a one-shot optimizer that runs scipy's own inner loop
      on a single call; pass ``maxiter`` via ``hyperparameters``, and do
      *not* wrap it in a :class:`LoopBlock`::

          step = create_optimizer(
              "cg", data_generator=f, output_name="y",
              input_name="x", maxiter=50,
          )
          data = step.call(data)

    Parameters
    ----------
    optimizer : str | DictConfig
        Name of the built-in optimizer, or a Hydra ``DictConfig`` that
        instantiates an optimizer block.
    **hyperparameters
        Forwarded to the underlying factory function.

    Returns
    -------
    Block
        Configured optimizer block.

    Raises
    ------
    KeyError
        If the built-in optimizer name is not recognized.
    TypeError
        If ``optimizer`` is not a ``str`` or ``DictConfig``.
    """
    if isinstance(optimizer, str):
        filtered_name = (
            optimizer.lower()
            .replace(" ", "")
            .replace("-", "")
            .replace("_", "")
        )

        if filtered_name in OPTIMIZERS:
            return OPTIMIZERS[filtered_name](**hyperparameters)
        else:
            raise KeyError(f"Unknown optimizer name: {optimizer}")

    elif isinstance(optimizer, DictConfig):
        return instantiate(optimizer)

    else:
        raise TypeError(f"Unknown optimizer type: {type(optimizer)}")

Built-in samplers

f3dasm.design.grid(stepsize_continuous_parameters: Optional[dict[str, float] | float] = None, **kwargs) -> Block

Create a Grid sampler.

Parameters:

Name	Type	Description	Default
stepsize_continuous_parameters	dict[str, float] or float	Step size for continuous parameters. If a single float, the same step size is used for all continuous parameters. If a dict, maps parameter names to individual step sizes.	None
**kwargs	dict	Additional parameters for the sampler.	required

Returns:

Type	Description
Block	A Block instance of a grid sampler.

Source code in src/f3dasm/_src/samplers.py

def grid(
    stepsize_continuous_parameters: Optional[dict[str, float] | float] = None,
    **kwargs,
) -> Block:
    """
    Create a Grid sampler.

    Parameters
    ----------
    stepsize_continuous_parameters : dict[str, float] or float, optional
        Step size for continuous parameters. If a single float, the same
        step size is used for all continuous parameters. If a dict, maps
        parameter names to individual step sizes.
    **kwargs : dict
        Additional parameters for the sampler.

    Returns
    -------
    Block
        A Block instance of a grid sampler.
    """
    return Grid(
        stepsize_continuous_parameters=stepsize_continuous_parameters, **kwargs
    )

f3dasm.design.random(seed: Optional[int] = None, **kwargs) -> Block

Create a RandomUniform sampler.

Parameters:

Name	Type	Description	Default
seed	Optional[int]	The random seed, by default None	None
**kwargs	dict	Additional parameters for the sampler.	required

Returns:

Type	Description
Block	An Block instance of a random uniform sampler.

Source code in src/f3dasm/_src/samplers.py

def random(seed: Optional[int] = None, **kwargs) -> Block:
    """
    Create a RandomUniform sampler.

    Parameters
    ----------
    seed : Optional[int], optional
        The random seed, by default None
    **kwargs : dict
        Additional parameters for the sampler.

    Returns
    -------
    Block
        An Block instance of a random uniform sampler.
    """
    return RandomUniform(seed=seed, **kwargs)

f3dasm.design.latin(seed: Optional[int] = None, **kwargs) -> Block

Create a Latin Hypercube sampler.

Parameters:

Name	Type	Description	Default
seed	Optional[int]	The random seed, by default None	None
**kwargs	dict	Additional parameters for the sampler.	required

Returns:

Type	Description
Block	An Block instance of a latin hypercube sampler.

Source code in src/f3dasm/_src/samplers.py

def latin(seed: Optional[int] = None, **kwargs) -> Block:
    """
    Create a Latin Hypercube sampler.

    Parameters
    ----------
    seed : Optional[int], optional
        The random seed, by default None
    **kwargs : dict
        Additional parameters for the sampler.

    Returns
    -------
    Block
        An Block instance of a latin hypercube sampler.
    """
    return Latin(seed=seed, **kwargs)

f3dasm.design.sobol(seed: Optional[int] = None, **kwargs) -> Block

Create a Sobol sampler.

Parameters:

Name	Type	Description	Default
seed	Optional[int]	The random seed, by default None	None
**kwargs	dict	Additional parameters for the sampler.	required

Returns:

Type	Description
Block	A Block instance of a sobol sequence sampler.

Source code in src/f3dasm/_src/samplers.py

def sobol(seed: Optional[int] = None, **kwargs) -> Block:
    """
    Create a Sobol sampler.

    Parameters
    ----------
    seed : Optional[int], optional
        The random seed, by default None
    **kwargs : dict
        Additional parameters for the sampler.

    Returns
    -------
    Block
        A Block instance of a sobol sequence sampler.
    """
    return Sobol(seed=seed, **kwargs)

Built-in datagenerators

f3dasm.datageneration.functions.ackley(x: ndarray, a: float = 20.0, b: float = 0.2, c: float = 6.283185307179586)

Ackley function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required
a	float	Parameter a, by default 20	20.0
b	float	Parameter b, by default 0.2	0.2
c	float	Parameter c, by default 2 * np.pi	6.283185307179586

Returns:

Type	Description
float	The value of the Ackley function at x.

Notes

Recommended search domain: x_i in [-32.768, 32.768] for all i. Global minimum: f(x) = 0 at x = (0, ..., 0). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def ackley(
    x: np.ndarray, a: float = 20.0, b: float = 0.2, c: float = 2 * np.pi
):
    """Ackley function

    ![Ackley function surface](../img/functions/ackley.png){ width=30% }

    Parameters
    ----------
    x : np.ndarray
        Input array
    a : float, optional
        Parameter a, by default 20
    b : float, optional
        Parameter b, by default 0.2
    c : float, optional
        Parameter c, by default 2 * np.pi

    Returns
    -------
    float
        The value of the Ackley function at x.

    Notes
    -----
    Recommended search domain: x_i in [-32.768, 32.768] for all i.
    Global minimum: f(x*) = 0 at x* = (0, ..., 0).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = -a * np.exp(-b * np.sqrt(np.mean(x**2)))
    y = y - np.exp(np.mean(np.cos(c * x))) + a + np.exp(1)
    return y

f3dasm.datageneration.functions.beale(x: ndarray)

Beale function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Beale function at x.

Notes

Recommended search domain: x_i in [-4.5, 4.5] for i = 1, 2. Global minimum: f(x) = 0 at x = (3, 0.5). Two-dimensional.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def beale(x: np.ndarray):
    """Beale function

    ![Beale function surface](../img/functions/beale.png){ width=30% }

    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Beale function at x.

    Notes
    -----
    Recommended search domain: x_i in [-4.5, 4.5] for i = 1, 2.
    Global minimum: f(x*) = 0 at x* = (3, 0.5).
    Two-dimensional.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = (
        (1.5 - x[0] + x[0] * x[1]) ** 2
        + (2.25 - x[0] + x[0] * x[1] ** 2) ** 2
        + (2.625 - x[0] + x[0] * x[1] ** 3) ** 2
    )
    return y

f3dasm.datageneration.functions.booth(x: ndarray)

Booth function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Booth function at x.

Notes

Recommended search domain: x_i in [-10, 10] for i = 1, 2. Global minimum: f(x) = 0 at x = (1, 3). Two-dimensional.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def booth(x: np.ndarray):
    """Booth function

    ![Booth function surface](../img/functions/booth.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Booth function at x.

    Notes
    -----
    Recommended search domain: x_i in [-10, 10] for i = 1, 2.
    Global minimum: f(x*) = 0 at x* = (1, 3).
    Two-dimensional.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = (x[0] + 2 * x[1] - 7) ** 2 + (2 * x[0] + x[1] - 5) ** 2
    return y

f3dasm.datageneration.functions.branin(x: ndarray, a=1, b=0.12918450914398066, c=1.5915494309189535, r=6, s=10, t=0.039788735772973836)

Branin function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required
a	float	Parameter a, by default 1	1
b	float	Parameter b, by default 5.1 / (4 * np.pi**2)	0.12918450914398066
c	float	Parameter c, by default 5 / np.pi	1.5915494309189535
r	float	Parameter r, by default 6	6
s	float	Parameter s, by default 10	10
t	float	Parameter t, by default 1 / (8 * np.pi)	0.039788735772973836

Returns:

Type	Description
float	The value of the Branin function at x.

Notes

Recommended search domain: x_1 in [-5, 10], x_2 in [0, 15]. Global minima: f(x) = 0.397887 at x = (-pi, 12.275), (pi, 2.275), and (9.42478, 2.475). Two-dimensional.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def branin(
    x: np.ndarray,
    a=1,
    b=5.1 / (4 * np.pi**2),
    c=5 / np.pi,
    r=6,
    s=10,
    t=1 / (8 * np.pi),
):
    """Branin function

    ![Branin function surface](../img/functions/branin.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array
    a : float, optional
        Parameter a, by default 1
    b : float, optional
        Parameter b, by default 5.1 / (4 * np.pi**2)
    c : float, optional
        Parameter c, by default 5 / np.pi
    r : float, optional
        Parameter r, by default 6
    s : float, optional
        Parameter s, by default 10
    t : float, optional
        Parameter t, by default 1 / (8 * np.pi)

    Returns
    -------
    float
        The value of the Branin function at x.

    Notes
    -----
    Recommended search domain: x_1 in [-5, 10], x_2 in [0, 15].
    Global minima: f(x*) = 0.397887 at x* = (-pi, 12.275),
    (pi, 2.275), and (9.42478, 2.475).
    Two-dimensional.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = a * (x[1] - b * x[0] ** 2 + c * x[0] - r) ** 2
    y = y + s * (1 - t) * np.cos(x[0]) + s
    return y

f3dasm.datageneration.functions.crossintray(x: ndarray)

Cross-in-Tray function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Cross-in-Tray function at x.

Notes

Recommended search domain: x_i in [-10, 10] for i = 1, 2. Global minima: f(x) = -2.06261 at x = (+/- 1.34941, +/- 1.34941). Two-dimensional.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def crossintray(x: np.ndarray):
    """Cross-in-Tray function

    ![Cross-in-tray function surface](
        ../img/functions/crossintray.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Cross-in-Tray function at x.

    Notes
    -----
    Recommended search domain: x_i in [-10, 10] for i = 1, 2.
    Global minima: f(x*) = -2.06261 at x* = (+/- 1.34941, +/- 1.34941).
    Two-dimensional.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = (
        -0.0001
        * (
            np.abs(np.sin(x[0]) * np.sin(x[1]))
            * np.exp(np.abs(100 - np.sqrt(x[0] ** 2 + x[1] ** 2) / np.pi))
            + 1
        )
        ** 0.1
    )
    return y

f3dasm.datageneration.functions.dixonprice(x: ndarray)

Dixon Price function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Dixon Price function at x.

Notes

Recommended search domain: x_i in [-10, 10] for all i. Global minimum: f(x) = 0 at x_i = 2 ** (-(2 ** i - 2) / 2 ** i). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def dixonprice(x: np.ndarray):
    """Dixon Price function

    ![dixonprice function surface](
        ../img/functions/dixonprice.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Dixon Price function at x.

    Notes
    -----
    Recommended search domain: x_i in [-10, 10] for all i.
    Global minimum: f(x*) = 0 at x*_i = 2 ** (-(2 ** i - 2) / 2 ** i).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    d = x.shape[0]
    y = (x[0] - 1) ** 2 + np.sum(
        [(i + 1) * (2 * x[i] ** 2 - x[i - 1]) ** 2 for i in range(1, d)]
    )
    return y

f3dasm.datageneration.functions.easom(x: ndarray)

Easom function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Easom function at x.

Notes

Recommended search domain: x_i in [-100, 100] for i = 1, 2. Global minimum: f(x) = -1 at x = (pi, pi). Two-dimensional.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def easom(x: np.ndarray):
    """Easom function

    ![Easom function surface](../img/functions/easom.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Easom function at x.

    Notes
    -----
    Recommended search domain: x_i in [-100, 100] for i = 1, 2.
    Global minimum: f(x*) = -1 at x* = (pi, pi).
    Two-dimensional.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = (
        -np.cos(x[0])
        * np.cos(x[1])
        * np.exp(-((x[0] - np.pi) ** 2) - (x[1] - np.pi) ** 2)
    )
    return y

f3dasm.datageneration.functions.eggholder(x: ndarray)

Egg Holder function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Egg Holder function at x.

Notes

Recommended search domain: x_i in [-512, 512] for i = 1, 2. Global minimum: f(x) = -959.6407 at x = (512, 404.2319). Two-dimensional.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def eggholder(x: np.ndarray):
    """Egg Holder function

    ![Eggholder function surface](../img/functions/eggholder.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Egg Holder function at x.

    Notes
    -----
    Recommended search domain: x_i in [-512, 512] for i = 1, 2.
    Global minimum: f(x*) = -959.6407 at x* = (512, 404.2319).
    Two-dimensional.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = -(x[1] + 47) * np.sin(np.sqrt(np.abs(x[1] + 0.5 * x[0] + 47))) - x[
        0
    ] * np.sin(np.sqrt(np.abs(x[0] - (x[1] + 47))))
    return y

f3dasm.datageneration.functions.griewank(x: ndarray)

Griewank function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Griewank function at x.

Notes

Recommended search domain: x_i in [-600, 600] for all i. Global minimum: f(x) = 0 at x = (0, ..., 0). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def griewank(x: np.ndarray):
    """Griewank function

    ![griewank function surface](../img/functions/griewank.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Griewank function at x.

    Notes
    -----
    Recommended search domain: x_i in [-600, 600] for all i.
    Global minimum: f(x*) = 0 at x* = (0, ..., 0).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    d = x.shape[0]
    i = np.arange(1, d + 1)
    y = 1 + np.sum(x**2 / 4000) - np.prod(np.cos(x / np.sqrt(i)))
    return y

f3dasm.datageneration.functions.levy(x: ndarray)

Levy function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Levy function at x.

Notes

Recommended search domain: x_i in [-10, 10] for all i. Global minimum: f(x) = 0 at x = (1, ..., 1). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def levy(x: np.ndarray):
    """Levy function

    ![Levy function surface](../img/functions/levy.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Levy function at x.

    Notes
    -----
    Recommended search domain: x_i in [-10, 10] for all i.
    Global minimum: f(x*) = 0 at x* = (1, ..., 1).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    z = 1 + (x - 1) / 4
    y = (
        np.sin(np.pi * z[0]) ** 2
        + sum((z[:-1] - 1) ** 2 * (1 + 10 * np.sin(np.pi * z[:-1] + 1) ** 2))
        + (z[-1] - 1) ** 2 * (1 + np.sin(2 * np.pi * z[-1]) ** 2)
    )
    return y

f3dasm.datageneration.functions.rastrigin(x: ndarray)

Rastrigin function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Rastrigin function at x.

Notes

Recommended search domain: x_i in [-5.12, 5.12] for all i. Global minimum: f(x) = 0 at x = (0, ..., 0). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def rastrigin(x: np.ndarray):
    """Rastrigin function

    ![Rastrigin function surface](../img/functions/rastrigin.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Rastrigin function at x.

    Notes
    -----
    Recommended search domain: x_i in [-5.12, 5.12] for all i.
    Global minimum: f(x*) = 0 at x* = (0, ..., 0).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    d = x.shape[0]
    y = 10 * d + np.sum(x**2 - 10 * np.cos(2 * np.pi * x))
    return y

f3dasm.datageneration.functions.rosenbrock(x: ndarray)

Rosenbrock function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Rosenbrock function at x.

Notes

Recommended search domain: x_i in [-5, 10] for all i (some sources use [-2.048, 2.048]). Global minimum: f(x) = 0 at x = (1, ..., 1). Defined on any dimension d (most often used at d = 2).

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def rosenbrock(x: np.ndarray):
    """Rosenbrock function

    ![Rosenbrock function surface](
        ../img/functions/rosenbrock.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Rosenbrock function at x.

    Notes
    -----
    Recommended search domain: x_i in [-5, 10] for all i
    (some sources use [-2.048, 2.048]).
    Global minimum: f(x*) = 0 at x* = (1, ..., 1).
    Defined on any dimension d (most often used at d = 2).

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = np.sum(np.abs(100 * (x[1:] - x[:-1] ** 2) ** 2 + (1 - x[:-1]) ** 2))
    return y

f3dasm.datageneration.functions.rotatedhyperellipsoid(x: ndarray)

Rotated Hyper-Ellipsoid function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Rotated Hyper-Ellipsoid function at x.

Notes

Recommended search domain: x_i in [-65.536, 65.536] for all i. Global minimum: f(x) = 0 at x = (0, ..., 0). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def rotatedhyperellipsoid(x: np.ndarray):
    """Rotated Hyper-Ellipsoid function

    ![Rotated Hyper-Ellipsoid function surface](
        ../img/functions/rotatedhyperellipsoid.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Rotated Hyper-Ellipsoid function at x.

    Notes
    -----
    Recommended search domain: x_i in [-65.536, 65.536] for all i.
    Global minimum: f(x*) = 0 at x* = (0, ..., 0).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    d = x.shape[0]
    y = np.sum([np.sum(x[: i + 1] ** 2) for i in range(d)])
    return y

f3dasm.datageneration.functions.schwefel(x: ndarray)

Schwefel function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Schwefel function at x.

Notes

Recommended search domain: x_i in [-500, 500] for all i. Global minimum: f(x) = 0 at x = (420.9687, ..., 420.9687). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def schwefel(x: np.ndarray):
    """Schwefel function

    ![Schwefel function surface](../img/functions/schwefel.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Schwefel function at x.

    Notes
    -----
    Recommended search domain: x_i in [-500, 500] for all i.
    Global minimum: f(x*) = 0 at x* = (420.9687, ..., 420.9687).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    d = x.shape[0]
    y = 418.9829 * d - np.sum(x * np.sin(np.sqrt(np.abs(x))))
    return y

f3dasm.datageneration.functions.sphere(x: ndarray)

Sphere funct

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Sphere function at x.

Notes

Recommended search domain: x_i in [-5.12, 5.12] for all i. Global minimum: f(x) = 0 at x = (0, ..., 0). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def sphere(x: np.ndarray):
    """Sphere funct

    ![Sphere function surface](
        ../img/functions/sphere.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Sphere function at x.

    Notes
    -----
    Recommended search domain: x_i in [-5.12, 5.12] for all i.
    Global minimum: f(x*) = 0 at x* = (0, ..., 0).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = np.sum(x**2)
    return y

f3dasm.datageneration.functions.styblinskitang(x: ndarray)

Styblinski-Tang function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Styblinski-Tang function at x.

Notes

Recommended search domain: x_i in [-5, 5] for all i. Global minimum: f(x) = -39.16599 * d at x = (-2.903534, ..., -2.903534), where d is the dimensionality. Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def styblinskitang(x: np.ndarray):
    """Styblinski-Tang function

    ![styblinski-tang function surface](
        ../img/functions/styblinskitang.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Styblinski-Tang function at x.

    Notes
    -----
    Recommended search domain: x_i in [-5, 5] for all i.
    Global minimum: f(x*) = -39.16599 * d at
    x* = (-2.903534, ..., -2.903534), where d is the dimensionality.
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    y = 0.5 * np.sum(x**4 - 16 * x**2 + 5 * x)
    return y

f3dasm.datageneration.functions.threehump(x: ndarray)

Three-Hump function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Three-Hump function at x.

Notes

Recommended search domain: x_i in [-5, 5] for i = 1, 2. Global minimum: f(x) = 0 at x = (0, 0). Two-dimensional.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def threehump(x: np.ndarray):
    """Three-Hump function

    ![Threehump function surface](../img/functions/threehump.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Three-Hump function at x.

    Notes
    -----
    Recommended search domain: x_i in [-5, 5] for i = 1, 2.
    Global minimum: f(x*) = 0 at x* = (0, 0).
    Two-dimensional.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    x1, x2 = x
    y = 2 * x1**2 - 1.05 * x1**4 + x1**6 * (1 / 6) + x1 * x2 + x2**2
    return y

f3dasm.datageneration.functions.zakharov(x: ndarray)

Zakharov function

Parameters:

Name	Type	Description	Default
x	ndarray	Input array	required

Returns:

Type	Description
float	The value of the Zakharov function at x.

Notes

Recommended search domain: x_i in [-5, 10] for all i. Global minimum: f(x) = 0 at x = (0, ..., 0). Defined on any dimension d.

References

.. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. https://www.sfu.ca/~ssurjano/optimization.html

Source code in src/f3dasm/_src/datageneration/benchmarkfunctions.py

def zakharov(x: np.ndarray):
    """Zakharov function

    ![Zakharov function surface](../img/functions/zakharov.png){ width=30% }


    Parameters
    ----------
    x : np.ndarray
        Input array

    Returns
    -------
    float
        The value of the Zakharov function at x.

    Notes
    -----
    Recommended search domain: x_i in [-5, 10] for all i.
    Global minimum: f(x*) = 0 at x* = (0, ..., 0).
    Defined on any dimension d.

    References
    ----------
    .. [1] Surjanovic, S. & Bingham, D. (2013). Virtual Library
       of Simulation Experiments: Test Functions and Datasets.
       https://www.sfu.ca/~ssurjano/optimization.html
    """
    d = x.shape[0]
    y = (
        np.sum(x**2)
        + np.sum(0.5 * np.arange(1, d + 1) * x) ** 2
        + np.sum(0.5 * np.arange(1, d + 1) * x) ** 4
    )
    return y

Built-in optimizers

f3dasm.optimization.cg(data_generator: DataGenerator, output_name: str, input_name: str, bounds: Optional[scipy.optimize.Bounds] = None, grad_f: Optional[Callable] = None, **hyperparameters) -> ScipyOptimizer

Create a Conjugate Gradient block.

Parameters:

Name	Type	Description	Default
data_generator	DataGenerator	The data generator whose f attribute will be optimized.	required
output_name	str	Name of the output column to minimize.	required
input_name	str	Name of the input column controlled by CG.	required
bounds	Bounds	Bounds on variables (CG does not natively support bounds; kept for interface consistency).	None
grad_f	callable	Gradient function. If None, gradients are estimated numerically.	None
**hyperparameters		Options forwarded to the CG optimizer, such as maxiter, gtol, norm.	required

Returns:

Type	Description
ScipyOptimizer	Configured CG block.

See Also

scipy.optimize.minimize

Source code in src/f3dasm/_src/optimization/scipy_implementations.py

def cg(
    data_generator: DataGenerator,
    output_name: str,
    input_name: str,
    bounds: Optional[scipy.optimize.Bounds] = None,
    grad_f: Optional[Callable] = None,
    **hyperparameters,
) -> ScipyOptimizer:
    """Create a Conjugate Gradient block.

    Parameters
    ----------
    data_generator : DataGenerator
        The data generator whose ``f`` attribute will be optimized.
    output_name : str
        Name of the output column to minimize.
    input_name : str
        Name of the input column controlled by CG.
    bounds : scipy.optimize.Bounds, optional
        Bounds on variables (CG does not natively support bounds; kept for
        interface consistency).
    grad_f : callable, optional
        Gradient function. If ``None``, gradients are estimated numerically.
    **hyperparameters
        Options forwarded to the CG optimizer, such as ``maxiter``, ``gtol``,
        ``norm``.

    Returns
    -------
    ScipyOptimizer
        Configured CG block.

    See Also
    --------
    scipy.optimize.minimize
    """
    return ScipyOptimizer(
        method="CG",
        data_generator=data_generator,
        output_name=output_name,
        input_name=input_name,
        bounds=bounds,
        grad_f=grad_f,
        **hyperparameters,
    )

f3dasm.optimization.lbfgsb(data_generator: DataGenerator, output_name: str, input_name: str, bounds: Optional[scipy.optimize.Bounds] = None, grad_f: Optional[Callable] = None, **hyperparameters) -> ScipyOptimizer

Create an L-BFGS-B block.

Parameters:

Name	Type	Description	Default
data_generator	DataGenerator	The data generator whose f attribute will be optimized.	required
output_name	str	Name of the output column to minimize.	required
input_name	str	Name of the input column controlled by L-BFGS-B.	required
bounds	Bounds	Bounds on variables; L-BFGS-B supports box constraints natively.	None
grad_f	callable	Gradient function. If None, gradients are estimated numerically.	None
**hyperparameters		Options forwarded to the L-BFGS-B optimizer, such as maxiter, maxfun, ftol, gtol, maxcor.	required

Returns:

Type	Description
ScipyOptimizer	Configured L-BFGS-B block.

See Also

scipy.optimize.minimize

Source code in src/f3dasm/_src/optimization/scipy_implementations.py

def lbfgsb(
    data_generator: DataGenerator,
    output_name: str,
    input_name: str,
    bounds: Optional[scipy.optimize.Bounds] = None,
    grad_f: Optional[Callable] = None,
    **hyperparameters,
) -> ScipyOptimizer:
    """Create an L-BFGS-B block.

    Parameters
    ----------
    data_generator : DataGenerator
        The data generator whose ``f`` attribute will be optimized.
    output_name : str
        Name of the output column to minimize.
    input_name : str
        Name of the input column controlled by L-BFGS-B.
    bounds : scipy.optimize.Bounds, optional
        Bounds on variables; L-BFGS-B supports box constraints natively.
    grad_f : callable, optional
        Gradient function. If ``None``, gradients are estimated numerically.
    **hyperparameters
        Options forwarded to the L-BFGS-B optimizer, such as ``maxiter``,
        ``maxfun``, ``ftol``, ``gtol``, ``maxcor``.

    Returns
    -------
    ScipyOptimizer
        Configured L-BFGS-B block.

    See Also
    --------
    scipy.optimize.minimize
    """
    return ScipyOptimizer(
        method="L-BFGS-B",
        data_generator=data_generator,
        output_name=output_name,
        input_name=input_name,
        bounds=bounds,
        grad_f=grad_f,
        **hyperparameters,
    )

f3dasm.optimization.nelder_mead(data_generator: DataGenerator, output_name: str, input_name: str, bounds: Optional[scipy.optimize.Bounds] = None, grad_f: Optional[Callable] = None, **hyperparameters) -> ScipyOptimizer

Create a Nelder-Mead block.

Parameters:

Name	Type	Description	Default
data_generator	DataGenerator	The data generator whose f attribute will be optimized.	required
output_name	str	Name of the output column to minimize.	required
input_name	str	Name of the input column controlled by Nelder-Mead.	required
bounds	Bounds	Bounds on variables (standard Nelder-Mead does not support them).	None
grad_f	callable	Gradient function (unused by Nelder-Mead; kept for interface consistency).	None
**hyperparameters		Options forwarded to the Nelder-Mead optimizer, such as maxiter, maxfev, xatol, fatol.	required

Returns:

Type	Description
ScipyOptimizer	Configured Nelder-Mead block.

See Also

scipy.optimize.minimize

Source code in src/f3dasm/_src/optimization/scipy_implementations.py

def nelder_mead(
    data_generator: DataGenerator,
    output_name: str,
    input_name: str,
    bounds: Optional[scipy.optimize.Bounds] = None,
    grad_f: Optional[Callable] = None,
    **hyperparameters,
) -> ScipyOptimizer:
    """Create a Nelder-Mead block.

    Parameters
    ----------
    data_generator : DataGenerator
        The data generator whose ``f`` attribute will be optimized.
    output_name : str
        Name of the output column to minimize.
    input_name : str
        Name of the input column controlled by Nelder-Mead.
    bounds : scipy.optimize.Bounds, optional
        Bounds on variables (standard Nelder-Mead does not support them).
    grad_f : callable, optional
        Gradient function (unused by Nelder-Mead; kept for interface
        consistency).
    **hyperparameters
        Options forwarded to the Nelder-Mead optimizer, such as ``maxiter``,
        ``maxfev``, ``xatol``, ``fatol``.

    Returns
    -------
    ScipyOptimizer
        Configured Nelder-Mead block.

    See Also
    --------
    scipy.optimize.minimize
    """
    return ScipyOptimizer(
        method="Nelder-Mead",
        data_generator=data_generator,
        output_name=output_name,
        input_name=input_name,
        bounds=bounds,
        grad_f=grad_f,
        **hyperparameters,
    )

f3dasm.optimization.tpesampler(output_name: str) -> OptunaUpdateStep

Create an Optuna TPE-sampler update-step block.

Parameters:

Name	Type	Description	Default
output_name	str	Name of the output column to minimize.	required

Returns:

Type	Description
OptunaUpdateStep	Update-step block wrapping Optuna's TPE sampler.

Source code in src/f3dasm/_src/optimization/optuna_implementations.py

def tpesampler(output_name: str) -> OptunaUpdateStep:
    """Create an Optuna TPE-sampler update-step block.

    Parameters
    ----------
    output_name : str
        Name of the output column to minimize.

    Returns
    -------
    OptunaUpdateStep
        Update-step block wrapping Optuna's TPE sampler.
    """
    return OptunaUpdateStep(
        optuna_sampler=optuna.samplers.TPESampler(),
        output_name=output_name,
    )