Sigmoid

class pumas.desirability.sigmoid.Sigmoid(params: Dict[str, Any] | None = None)

compute_numeric(x: int | float) → float

Compute the sigmoid desirability for a numeric input.

Parameters:

x (Union[int, float]) – The numeric input value.

Returns:

The computed desirability value.

Return type:

float

Raises:

• InvalidInputTypeError – If the input is not an int or float.

• ParameterValueNotSet – If any required parameter is not set.

compute_ufloat(x: AffineScalarFunc) → AffineScalarFunc

Compute the sigmoid desirability for an uncertain float input.

Parameters:

x (UFloat) – The uncertain float input value.

Returns:

The computed desirability value with uncertainty.

Return type:

UFloat

Raises:

• InvalidInputTypeError – If the input is not a UFloat.

• ParameterValueNotSet – If any required parameter is not set.

name: ClassVar[str] = 'sigmoid'

Sigmoid desirability function implementation.

This class implements a sigmoid desirability function with adjustable parameters. It provides methods to compute the desirability for both numeric and uncertain float inputs.

Mathematical Definition: The sigmoid function is defined as:

\[F(x) = \frac{1}{1 + {base}^{-arg}} * (1 - {shift}) + {shift}\]

Where the arg term is calculated as:

\[{arg} = \frac{10 * k * (x - \frac{{low} + {high}}{2})}{{high} - {low}}\]

Implementation Details:

The sigmoid function uses two different implementations based on the input parameters:

1. Hard Sigmoid: When high equals low, a hard sigmoid function is used, which returns 1.0 if k * x > 0, and 0.0 otherwise.

2. Stable Sigmoid: For all other cases, a numerically stable sigmoid implementation is used. This implementation avoids overflow errors for large positive or negative inputs by using different formulas based on the sign of the intermediate calculation.

The choice between these implementations is made automatically based on the input parameters, ensuring accurate and stable results across a wide range of inputs.

Parameters:

params (Optional[Dict[str, Any]]) – Initial parameters for the sigmoid function. Defaults to None.

low

The lower bound of the sigmoid range.

Type:

float

high

The upper bound of the sigmoid range.

Type:

float

k

The slope parameter, range [-1.0, 1.0], default 0.5.

Type:

float

base

The base of the exponential function, range (1.0, 10.0], default 10.0.

Type:

float

shift

The vertical shift of the sigmoid, range [0.0, 1.0], default 0.0.

Type:

float

Raises:

• InvalidBoundaryError – If base is less than or equal to 1, or if high is less than low.

• InvalidParameterTypeError – If any parameter is of an invalid type.

• ParameterValueNotSet – If any required parameter is not set.

Usage Example:

>>> from pumas.desirability import desirability_catalogue

>>> desirability_class = desirability_catalogue.get("sigmoid")

>>> params = {'low': 0.0, 'high': 1.0, 'k': 0.1, 'base': 10.0, 'shift': 0.0}
>>> desirability = desirability_class(params=params)
>>> print(desirability.get_parameters_values())
{'low': 0.0, 'high': 1.0, 'k': 0.1, 'base': 10.0, 'shift': 0.0}

>>> result = desirability.compute_numeric(x=0.5)
>>> print(f"{result:.2f}")
0.50

>>> result = desirability(x=0.5) # Same as compute_numeric
>>> print(f"{result:.2f}")
0.50

>>> from uncertainties import ufloat
>>> result = desirability.compute_ufloat(x=ufloat(0.5, 0.1))
>>> print(result)
0.50+/-0.06

class pumas.desirability.sigmoid.hard_sigmoid(x: float | AffineScalarFunc, k: float)

Compute the hard sigmoid function.

Parameters:

• x (Union[float, UFloat]) – The input value.

• k (float) – The slope parameter.

Returns:

The result of the hard sigmoid function.

Return type:

Union[float, UFloat]

class pumas.desirability.sigmoid.stable_sigmoid(x: float | ~uncertainties.core.AffineScalarFunc, k: float, base: float, math_module: ~types.ModuleType = <module 'math' from '/home/docs/.asdf/installs/python/3.12.10/lib/python3.12/lib-dynload/math.cpython-312-x86_64-linux-gnu.so'>)

Compute the stable sigmoid function.

Parameters:

• x (Union[float, UFloat]) – The input value.

• k (float) – The slope parameter.

• base (float) – The base of the exponential function.

• math_module (ModuleType, optional) – The math module to use. Defaults to math.

Returns:

The result of the stable sigmoid function.

Return type:

Union[float, UFloat]

Parameter Analysis

(Source code, png, hires.png, pdf)