API Reference¶

This page provides comprehensive documentation for all bezierv classes, functions, and algorithms.

Core Classes¶

Bezierv - Main Distribution Class¶

The primary class for representing and working with Bézier random variables.

bezierv.classes.bezierv.Bezierv ¶

Bezierv(n: int, controls_x: ArrayLike = None, controls_z: ArrayLike = None)

Initialize a Bezierv instance representing a Bezier random variable.

This constructor initializes the Bezier curve with a given number of control points n and optionally with provided control points for the x and z coordinates. If control points are not provided, they are initialized as zero arrays. It also sets up auxiliary arrays for differences (deltas) and binomial coefficients, and initializes moment attributes to NaN.

Parameters:

Name	Type	Description	Default
`n`	`int`	The number of control points of the Bezier random variable.	required
`controls_x`	`array - like`	The x-coordinates of the control points (length n+1). If None, a zero array is created.	`None`
`controls_z`	`array - like`	The z-coordinates of the control points (length n+1). If None, a zero array is created.	`None`

Attributes:

Name	Type	Description
`n`	`int`	The number of control points of the Bezier random variables.
`deltas_x`	`array`	Differences between consecutive x control points.
`deltas_z`	`array`	Differences between consecutive z control points.
`comb`	`array`	Array of binomial coefficients (n).
`comb_minus`	`array`	Array of binomial coefficients (n - 1).
`support`	`tuple`	The support of the Bezier random variable (initialized as (-inf, inf)).
`controls_x`	`array`	x-coordinates of the control points.
`controls_z`	`array`	z-coordinates of the control points.
`mean`	`float`	The mean of the curve (initialized as np.inf).
`var`	`float`	The variance of the curve (initialized as np.inf).
`skew`	`float`	The skewness of the curve (initialized as np.inf).
`kurt`	`float`	The kurtosis of the curve (initialized as np.inf).

Functions¶

update_bezierv ¶

update_bezierv(controls_x: array, controls_z: array)

Update the control points for the Bezier curve, bounds and recalculate deltas.

Parameters:

Name	Type	Description	Default
`controls_x`	`array - like`	The new x-coordinates of the control points.	required
`controls_z`	`array - like`	The new z-coordinates of the control points.	required

Returns:

Type	Description
`None`

combinations ¶

combinations()

Compute and store binomial coefficients.

deltas ¶

deltas()

Compute the differences between consecutive control points.

bernstein ¶

bernstein(t: float, i: int, combinations: array, n: int) -> float

Compute the Bernstein basis polynomial value.

Parameters:

Name	Type	Description	Default
`t`	`float`	The parameter value (in the interval [0, 1]).	required
`i`	`int`	The index of the Bernstein basis polynomial.	required
`combinations`	`array`	An array of binomial coefficients to use in the computation.	required
`n`	`int`	The degree for the Bernstein polynomial.	required

Returns:

Type	Description
`float`	The value of the Bernstein basis polynomial at t.

poly_x ¶

poly_x(t: float, controls_x: array = None) -> float

Evaluate the x-coordinate at a given t value.

Parameters:

Name	Type	Description	Default
`t`	`float`	The parameter value at which to evaluate (in [0, 1]).	required
`controls_x`	`array`	An array of control points for the x-coordinate. Defaults to self.controls_x.	`None`

Returns:

Type	Description
`float`	The evaluated x-coordinate at t.

poly_z ¶

poly_z(t: float, controls_z: array = None) -> float

Evaluate the z-coordinate at a given t value.

Parameters:

Name	Type	Description	Default
`t`	`float`	The parameter value at which to evaluate the curve (typically in [0, 1]).	required
`controls_z`	`array`	An array of control points for the z-coordinate. Defaults to self.controls_z.	`None`

Returns:

Type	Description
`float`	The evaluated z-coordinate at t.

root_find ¶

root_find(x: float, method: str = 'brentq') -> float

Find t such that the Bezier curve's x-coordinate equals a given value.

This method solves for the root of the equation poly_x(t) - x = 0 using a specified root-finding algorithm. The search is performed in the interval [0, 1].

Parameters:

Name	Type	Description	Default
`x`	`float`	The x-coordinate for which to find the corresponding parameter t.	required
`method`	`(brentq, bisect)`	The root-finding method to use. Default is 'brentq'.	`'brentq'`

Returns:

Type	Description
`float`	The parameter t in the interval [0, 1] such that poly_x(t) is approximately equal to x.

eval_t ¶

eval_t(t: float) -> tuple[float, float]

Evaluate the CDF of the Bezier random variable at a given parameter value t.

Parameters:

Name	Type	Description	Default
`t`	`float`	The parameter value at which to evaluate the curve (typically in [0, 1]).	required

Returns:

Type	Description
`tuple[float, float]`	A tuple containing the (x, z) coordinates of the point on the curve w.r.t. t.

eval_x ¶

eval_x(x: float) -> tuple[float, float]

Evaluate the CDF of the Bezier random variable at a given x-coordinate.

Parameters:

Name	Type	Description	Default
`x`	`float`	The x-coordinate at which to evaluate the Bezier curve.	required

Returns:

Type	Description
`tuple[float, float]`	A tuple containing the (x, z) coordinates of the point on the curve w.r.t. x.

cdf_x ¶

cdf_x(x: float) -> float

Compute the cumulative distribution function (CDF) at a given x-coordinate.

Parameters:

Name	Type	Description	Default
`x`	`float`	The x-coordinate at which to evaluate the CDF.	required

Returns:

Type	Description
`float`	The CDF value at the given x-coordinate.

quantile ¶

quantile(alpha: float, method: str = 'brentq') -> float

Compute the quantile function (inverse CDF) for a given probability level alpha.

Parameters:

Name	Type	Description	Default
`alpha`	`float`	The probability level for which to compute the quantile (in [0, 1]).	required

Returns:

Type	Description
`float`	The quantile value corresponding to the given alpha.

pdf_t ¶

pdf_t(t: float) -> float

Compute the probability density function (PDF) of the Bezier random variable with respect to t.

Parameters:

Name	Type	Description	Default
`t`	`float`	The value at which to compute the PDF (in [0, 1]).	required

Returns:

Type	Description
`float`	The computed PDF value at t.

pdf_x ¶

pdf_x(x: float) -> float

Compute the probability density function (PDF) of the Bezier random variable at a given x.

Parameters:

Name	Type	Description	Default
`x`	`float`	The x-coordinate at which to evaluate the PDF.	required

Returns:

Type	Description
`float`	The computed PDF value at x.

pdf_numerator_t ¶

pdf_numerator_t(t: float) -> float

Compute the numerator part of the PDF for the Bezier random variable with respect to t.

Parameters:

Name	Type	Description	Default
`t`	`float`	The value at which to compute the PDF numerator (in [0, 1]).	required

Returns:

Type	Description
`float`	The numerator of the PDF at t.

get_mean ¶

get_mean(closed_form: bool = True) -> float

Compute and return the mean of the distribution.

Parameters:

Name	Type	Description	Default
`closed_form`	`bool`	If True, use a closed-form solution for the mean. If False, compute it numerically (default is True).	`True`

Returns:

Type	Description
`float`	The mean value of the distribution.

get_variance ¶

get_variance() -> float

Compute and return the variance of the distribution.

Returns: float: The variance value of the distribution.

random ¶

random(n_sims: int, *, rng: Generator | int | None = None)

Generate random samples from the Bezier random variable.

This method generates n_sims random samples from the Bezier random variable by evaluating the inverse CDF at uniformly distributed random values in the interval [0, 1].

Parameters:

Name	Type	Description	Default
`n_sims`	`int`	The number of random samples to generate.	required
`rng`	`Generator \| int \| None`	Pseudorandom-number generator state. If None (default), a new `numpy.random.Generator` is created with fresh OS entropy. Any value accepted by :func:`numpy.random.default_rng` (e.g. a seed integer or :class:`~numpy.random.SeedSequence`) is also allowed.	`None`

Returns:

Type	Description
`array`	An array of shape (n_sims,) containing the generated random samples from the Bezier random variable.

plot_cdf ¶

plot_cdf(data: array = None, num_points: int = 100, ax: Axes = None)

Plot the cumulative distribution function (CDF) of the Bezier random variable alongside the empirical CDF (if data is provided).

Parameters:

Name	Type	Description	Default
`data`	`array - like`	The data points at which to evaluate and plot the CDF. If None, a linspace is used.	`None`
`num_points`	`int`	The number of points to use in the linspace when data is not provided (default is 100).	`100`
`ax`	`Axes`	The axes on which to plot the CDF. If None, the current axes are used.	`None`

plot_pdf ¶

plot_pdf(data: array = None, num_points: int = 100, ax: Axes = None)

Plot the probability density function (PDF) of the Bezier random variable.

Parameters:

Name	Type	Description	Default
`data`	`array - like`	The data points at which to evaluate and plot the PDF. If None, a linspace is used.	`None`
`num_points`	`int`	The number of points to use in the linspace when data is not provided (default is 100).	`100`
`ax`	`Axes`	The axes on which to plot the PDF. If None, the current axes are used.	`None`

Quick Example

from bezierv.classes.bezierv import Bezierv
import numpy as np

# Create a simple Bézier distribution
controls_x = [0, 1, 2, 3]
controls_z = [0, 0.3, 0.8, 1]

bezier_rv = Bezierv(3, controls_x, controls_z)

# Evaluate PDF and CDF
pdf_value = bezier_rv.pdf_x(1.5)
cdf_value = bezier_rv.cdf_x(1.5)

# Generate random samples
samples = bezier_rv.random(100, rng=42)

InteractiveBezierv - Interactive Editor¶

Interactive Bokeh-based editor for hands-on exploration of Bézier distributions.

bezierv.classes.bezierv.InteractiveBezierv ¶

InteractiveBezierv(controls_x, controls_z)

Manages an interactive Bezier distribution in a Bokeh plot.

Interactive Session

from bezierv.classes.bezierv import InteractiveBezierv
from bokeh.plotting import curdoc

# Start with uniform distribution
controls_x = [0, 1, 2, 3]
controls_z = [0, 0.33, 0.67, 1]

editor = InteractiveBezierv(controls_x, controls_z)
curdoc().add_root(editor.layout)

# Run with: bokeh serve --show script.py

Distribution Fitting¶

DistFit - Fit Distributions to Data¶

Fits Bézier distributions to empirical data using various optimization algorithms.

bezierv.classes.distfit.DistFit ¶

DistFit(data: List, n: int = 5, init_x: array = None, init_z: array = None, init_t: array = None, emp_cdf_data: array = None, method_init_x: str = 'quantile')

A class to fit a Bezier random variable to empirical data.

Attributes:

Name	Type	Description
`data`	`List`	The empirical data to fit the Bezier random variable to.
`n`	`int`	The number of control points minus one for the Bezier curve.
`init_x`	`array`	Initial control points for the x-coordinates of the Bezier curve.
`init_z`	`array`	Initial control points for the z-coordinates of the Bezier curve.
`init_t`	`array`	Initial parameter values.
`emp_cdf_data`	`array`	The empirical cumulative distribution function (CDF) data derived from the empirical data.
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.
`m`	`int`	The number of empirical data points.
`mse`	`float`	The mean squared error of the fit, initialized to infinity.

Initialize the DistFit class with empirical data and parameters for fitting a Bezier random variable.

Parameters:

Name	Type	Description	Default
`data`	`List`	The empirical data to fit the Bezier random variable to.	required
`n`	`int`	The number of control points minus one for the Bezier curve (default is 5).	`5`
`init_x`	`array`	Initial control points for the x-coordinates of the Bezier curve (default is None).	`None`
`init_z`	`array`	Initial control points for the z-coordinates of the Bezier curve (default is None).	`None`
`emp_cdf_data`	`array`	The empirical cumulative distribution function (CDF) data derived from the empirical data (default is None).	`None`
`method_init_x`	`str`	Method to initialize the x-coordinates of the control points (default is 'quantile').	`'quantile'`

Functions¶

fit ¶

fit(method: str = 'projgrad', step_size_PG: float = 0.001, max_iter_PG: int = 1000, threshold_PG: float = 0.001, step_size_PS: float = 0.001, max_iter_PS: int = 1000, solver_NL: str = 'ipopt', max_iter_NM: int = 1000) -> Bezierv

Fit the bezierv distribution to the data.

Parameters:

Name	Type	Description	Default
`method`	`str`	The fitting method to use. Options are 'projgrad', 'nonlinear', 'projsubgrad', or 'neldermead'. Default is 'projgrad'.	`'projgrad'`
`step_size_PG`	`float`	The step size for the projected gradient descent method (default is 0.001).	`0.001`
`max_iter_PG`	`int`	The maximum number of iterations for the projected gradient descent method (default is 1000).	`1000`
`threshold_PG`	`float`	The convergence threshold for the projected gradient descent method (default is 1e-3).	`0.001`
`step_size_PS`	`float`	The step size for the projected subgradient method (default is 0.001).	`0.001`
`max_iter_PS`	`int`	The maximum number of iterations for the projected subgradient method (default is 1000).	`1000`
`solver_NL`	`str`	The solver to use for the nonlinear fitting method (default is 'ipopt').	`'ipopt'`
`max_iter_NM`	`int`	The maximum number of iterations for the Nelder-Mead optimization method (default is 1000).	`1000`

Returns:

Type	Description
`Bezierv`	The fitted Bezierv instance with updated control points.

get_controls_z ¶

get_controls_z() -> array

Compute the control points for the z-coordinates of the Bezier curve.

get_controls_x ¶

get_controls_x(method: str) -> array

Compute the control points for the x-coordinates of the Bezier curve.

'quantile' method is used to determine the control points based on the data quantiles.

Parameters:

Name	Type	Description	Default
`method`	`str`	The method to use for initializing the x-coordinates of the control points.	required

Returns:

Type	Description
`array`	The control points for the x-coordinates of the Bezier curve.

Fitting Example

from bezierv.classes.distfit import DistFit
import numpy as np

# Generate sample data
data = np.random.gamma(2, 3, 500)

# Fit Bézier distribution
fitter = DistFit(data, n=5)
bezier_rv, mse = fitter.fit(method="projgrad")

print(f"Fit quality (MSE): {mse:.6f}")

# Visualize results
bezier_rv.plot_cdf(data)
bezier_rv.plot_pdf()

Convolution Operations¶

Convolver - Sum of Random Variables¶

Computes convolutions (sums) of independent Bézier random variables using Monte Carlo simulation or exact numerical integration.

bezierv.classes.convolver.Convolver ¶

Convolver(list_bezierv: list[Bezierv])

Initialize a ConvBezier instance for convolving Bezier curves.

This constructor sets up the convolution object by storing the provided Bezierv random variables, and creates a new Bezierv instance to hold the convolution result. It also initializes the number of data points to be used in the numerical convolution process.

Parameters:

Name	Type	Description	Default
`list_bezierv`	`list[Bezierv]`	A list of Bezierv instances representing the Bezier random variables to be convolved.	required

Functions¶

convolve ¶

convolve(n_sims: int = 1000, *, rng: Generator | int | None = None, **kwargs) -> Bezierv

Convolve the Bezier RVs via Monte Carlo or numerical integration and fit a Bezierv to the sum.

Parameters:

Name	Type	Description	Default
`n_sims`	`int`	Number of Monte Carlo samples.	`1000`
`rng`	`Generator \| int \| None`	Shared PRNG stream for all sampling.	`None`
`**kwargs`		Init options for DistFit(...): n, init_x, init_z, init_t, emp_cdf_data, method_init_x Fit options for DistFit.fit(...): method, step_size_PG, max_iter_PG, threshold_PG, step_size_PS, max_iter_PS, solver_NL, max_iter_NM	`{}`

convolve_exact ¶

convolve_exact(n_points: int = 1000, **kwargs) -> Bezierv

Perform exact convolution of two Bezier random variables using numerical integration.

This method generates a grid of points and computes the exact CDF at each point using the exact_cdf_two_bezierv method, then fits a Bezierv to the resulting CDF values.

Parameters:

Name	Type	Description	Default
`n_points`	`int`	Number of points to evaluate the exact CDF (default is 1000).	`1000`
`**kwargs`		Init options for DistFit(...): n, init_x, init_z, init_t, emp_cdf_data, method_init_x Fit options for DistFit.fit(...): method, step_size_PG, max_iter_PG, threshold_PG, step_size_PS, max_iter_PS, solver_NL, max_iter_NM	`{}`

Returns:

Type	Description
`Bezierv`	The fitted Bezierv representing the exact convolution.

Raises:

Type	Description
`ValueError`	If the number of Bezier RVs is not exactly 2.

exact_cdf_two_bezierv ¶

exact_cdf_two_bezierv(z: float) -> float

Compute the exact CDF of the convolution Z = X + Y at point z using numerical integration.

Parameters:

Name	Type	Description	Default
`z`	`float`	The point at which to evaluate the CDF.	required

Returns:

Type	Description
`float`	The CDF value F_Z(z) at point z.

Method Comparison

We recommend using monte carlo convolution.

Convolution Example

from bezierv.classes.convolver import Convolver
from bezierv.classes.distfit import DistFit
import numpy as np

# Create two distributions
data1 = np.random.gamma(2, 2, 1000)  # Task 1 duration
data2 = np.random.lognormal(1, 0.5, 1000)  # Task 2 duration

# Fit distributions
rv1, _ = DistFit(data1, n=5).fit()
rv2, _ = DistFit(data2, n=5).fit()

# Compute convolution
convolver = Convolver([rv1, rv2])

total_mc = convolver.convolve(n_sims=1000, rng=42)

print(f"Expected total time (MC): {total_mc.get_mean():.2f}")

Optimization Algorithms¶

These algorithms are used internally by DistFit to optimize the fitting process. You typically don't need to call these directly.

Projected Gradient Method¶

Fast and stable gradient-based optimization with projection onto the feasible region.

bezierv.algorithms.proj_grad ¶

Classes¶

Functions¶

grad ¶

grad(n: int, m: int, t: array, bezierv: Bezierv, controls_z: array, emp_cdf_data: array) -> array

Compute the gradient of the fitting objective with respect to the z control points.

Parameters:

Name	Type	Description	Default
`n`	`int`	The number of control points minus one.	required
`m`	`int`	The number of empirical CDF data points.	required
`t`	`array`	The parameter values corresponding to the data points. Expected to be an array of shape (m,).	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`controls_z`	`array`	The current z-coordinates of the control points.	required
`emp_cdf_data`	`array`	The empirical CDF data points used for fitting.	required

Returns:

Type	Description
`array`	An array representing the gradient with respect to each z control point.

project_z ¶

project_z(controls_z: array) -> array

Project the z control points onto the feasible set.

The projection is performed by first clipping the control points to the [0, 1] interval, sorting them in ascending order, and then enforcing the boundary conditions by setting the first control point to 0 and the last control point to 1.

Parameters:

Name	Type	Description	Default
`controls_z`	`array`	The current z-coordinates of the control points.	required

Returns:

Type	Description
`array`	The projected z control points that satisfy the constraints.

fit ¶

fit(n: int, m: int, data: array, bezierv: Bezierv, init_x: array, init_z: array, t: array, emp_cdf_data: array, step_size: float, max_iter: int, threshold: float) -> tuple

Fit the Bezier random variable to the empirical CDF data using projected gradient descent.

Starting from an initial guess for the z control points, this method iteratively updates the z control points by taking gradient descent steps and projecting the result back onto the feasible set. The process continues until convergence is achieved (i.e., the change in control points is less than a set threshold) or until the maximum number of iterations is reached. After convergence, the Bezierv curve is updated with the new control points and the fitting error is computed.

Parameters:

Name	Type	Description	Default
`n`	`int`	The number of control points minus one.	required
`m`	`int`	The number of empirical CDF data points.	required
`data`	`array`	The sorted data points used to fit the Bezier distribution.	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`init_x`	`array`	Initial guess for the x-coordinates of the control points.	required
`init_z`	`array`	Initial guess for the z-coordinates of the control points.	required
`t`	`array`	The parameter values corresponding to the data points. Expected to be an array of shape (m,).	required
`emp_cdf_data`	`array`	The empirical CDF data points used for fitting.	required
`step_size`	`float`	The step size for the gradient descent updates.	required
`max_iter`	`int`	The maximum number of iterations allowed for the fitting process.	required
`threshold`	`float`	The convergence threshold for the change in control points.	required

Returns:

Type	Description
`tuple[Bezierv, float]`	A tuple containing: - bezierv (Bezierv): The fitted `Bezierv` object with updated control points. - mse (float): The final mean squared error (MSE) of the fit.

When to Use

Default choice for most fitting problems. Provides good balance of speed and accuracy.

Projected Subgradient Method¶

Memory-efficient optimization suitable for large datasets.

bezierv.algorithms.proj_subgrad ¶

Classes¶

Functions¶

subgrad ¶

subgrad(n: int, m: int, bezierv: Bezierv, t: array, controls_z: array, emp_cdf_data: array) -> tuple

Compute the subgradient of the fitting objective with respect to the (x, z) control points.

Parameters:

Name	Type	Description	Default
`n`	`int`	The number of control points minus one.	required
`m`	`int`	The number of empirical CDF data points.	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`t`	`array`	The parameter values corresponding to the data points. Expected to be an array of shape (m,).	required
`controls_z`	`array`	The current z-coordinates of the control points.	required
`emp_cdf_data`	`array`	The empirical CDF data points used for fitting.	required

Returns:

Type	Description
`tuple[ndarray, ndarray]`	A tuple containing: - subgrad_x (np.ndarray): Subgradient w.r.t. the x-coordinates. - grad_z (np.ndarray): Gradient w.r.t. the z-coordinates.

project_x ¶

project_x(data: array, controls_x: array) -> array

Project the x control points onto the feasible set.

The projection is performed by first clipping the control points to the [X_(1), X_(m)] interval, sorting them in ascending order, and then enforcing the boundary conditions by setting the first control point to X_(1) and the last control point to X_(m).

Parameters:

Name	Type	Description	Default
`controls_x`	`array`	The current z-coordinates of the control points.	required

Returns:

Type	Description
`array`	The projected z control points that satisfy the constraints.

project_z ¶

project_z(controls_z: array) -> array

Project the z control points onto the feasible set.

The projection is performed by first clipping the control points to the [0, 1] interval, sorting them in ascending order, and then enforcing the boundary conditions by setting the first control point to 0 and the last control point to 1.

Parameters:

Name	Type	Description	Default
`controls_z`	`array`	The current z-coordinates of the control points.	required

Returns:

Type	Description
`array`	The projected z control points that satisfy the constraints.

objective_function ¶

objective_function(m: int, bezierv: Bezierv, emp_cdf_data: array, z: array, t: array) -> float

Compute the objective function value for the given z control points.

This method calculates the sum of squared errors between the Bezier random variable's CDF and the empirical CDF data.

Parameters:

Name	Type	Description	Default
`z`	`array`	The z-coordinates of the control points.	required
`t`	`array`	The parameter values corresponding to the data points.	required

Returns:

Type	Description
`float`	The value of the objective function (MSE).

fit ¶

fit(n: int, m: int, data: array, bezierv: Bezierv, init_x: array, init_z: array, init_t: array, emp_cdf_data: array, step_size: float, max_iter: int) -> tuple[Bezierv, float]

Fit the Bezier random variable to the empirical CDF data using projected gradient descent.

Starting from an initial guess for the z control points, this method iteratively updates the z control points by taking gradient descent steps and projecting the result back onto the feasible set. The process continues until convergence is achieved (i.e., the change in control points is less than a set threshold) or until the maximum number of iterations is reached. After convergence, the Bezierv curve is updated with the new control points and the fitting error is computed.

Parameters:

Name	Type	Description	Default
`n`	`int`	The number of control points minus one.	required
`m`	`int`	The number of empirical CDF data points.	required
`data`	`array`	The empirical data to fit the Bezier random variable to.	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`init_x`	`array`	Initial control points for the x-coordinates of the Bezier curve.	required
`init_z`	`array`	Initial control points for the z-coordinates of the Bezier curve.	required
`init_t`	`array`	Initial parameter values corresponding to the data points.	required
`emp_cdf_data`	`array`	The empirical cumulative distribution function (CDF) data derived from the empirical data.	required
`step_size`	`float`	The step size for the subgradient method updates.	required
`max_iter`	`int`	The maximum number of iterations to perform.	required

Returns:

Type	Description
`tuple[Bezierv, float]`	A tuple containing: - bezierv (Bezierv): The fitted `Bezierv` object with updated control points. - mse (float): The final mean squared error (MSE) of the fit.

Nonlinear Optimization¶

Robust scipy-based nonlinear solver for complex fitting problems.

bezierv.algorithms.non_linear ¶

Classes¶

Functions¶

fit ¶

fit(n: int, m: int, data: array, bezierv: Bezierv, init_x: array, init_z: array, init_t: array, emp_cdf_data: array, solver: str) -> Bezierv

Fits a Bézier random variable to empirical CDF data.

This method uses a nonlinear optimization solver to find the optimal Bézier curve control points that best represent the empirical cumulative distribution function (CDF) of the provided data.

Parameters:

Name	Type	Description	Default
`n`	`int`	The degree of the Bézier curve (number of control points - 1).	required
`m`	`int`	The number of empirical CDF data points.	required
`data`	`ndarray`	The sorted data points used to fit the Bézier distribution.	required
`bezierv`	`Bezierv`	An instance of the `Bezierv` class to be fitted.	required
`init_x`	`ndarray`	Initial guess for the x-coordinates of the control points.	required
`init_z`	`ndarray`	Initial guess for the z-coordinates of the control points.	required
`init_t`	`ndarray`	Initial guess for the Bézier 'time' parameters `t` in [0, 1].	required
`emp_cdf_data`	`ndarray`	The empirical CDF values corresponding to the `data` points.	required
`solver`	`str`	The name of the solver to use for optimization. Defaults to 'ipopt'.	required

Returns:

Type	Description
`tuple[Bezierv, float]`	A tuple containing: - bezierv (Bezierv): The fitted `Bezierv` object with updated control points. - mse (float): The final mean squared error (MSE) of the fit.

Raises:

Type	Description
`Exception`	If the optimization solver fails to find a solution.

Notes

The optimization is subject to several constraints to ensure a valid CDF representation: - The control points and 'time' parameters are kept sorted. - Convexity constraints are applied to the control points. - The first and last control points are fixed to the data's range. - The first and last 'time' parameters are fixed to 0 and 1.

When to Use

Use when accuracy is more important.

Nelder-Mead¶

Derivative-free optimization method that doesn't require gradients.

bezierv.algorithms.nelder_mead ¶

Classes¶

Functions¶

objective_function ¶

objective_function(concatenated: array, n: int, m: int, data: array, bezierv: Bezierv, emp_cdf_data: array) -> float

Compute the objective function value for the given control points.

This method calculates the sum of squared errors between the Bezier random variable's CDF and the empirical CDF data.

Parameters:

Name	Type	Description	Default
`concatenated`	`array`	A concatenated array containing the control points for z and x coordinates. The first n+1 elements are the z control points, and the remaining elements are the x control points.	required
`n`	`int`	The number of control points minus one for the Bezier curve.	required
`m`	`int`	The number of empirical CDF data points.	required
`data`	`array`	The sorted data points used to fit the Bezier distribution.	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`emp_cdf_data`	`array`	The empirical CDF data points used for fitting.	required

Returns:

Type	Description
`float`	The value of the objective function (MSE).

objective_function_lagrangian ¶

objective_function_lagrangian(concatenated: array, n: int, m: int, data: array, bezierv: Bezierv, emp_cdf_data: array, penalty_weight: float = 1000.0) -> float

Compute the objective function value for the given control points.

This method calculates the sum of squared errors between the Bezier random variable's CDF and the empirical CDF data.

Parameters:

Name	Type	Description	Default
`concatenated`	`array`	A concatenated array containing the control points for z and x coordinates. The first n+1 elements are the z control points, and the remaining elements are the x control points.	required
`n`	`int`	The number of control points minus one for the Bezier curve.	required
`m`	`int`	The number of empirical CDF data points.	required
`data`	`array`	The sorted data points used to fit the Bezier distribution.	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`emp_cdf_data`	`array`	The empirical CDF data points used for fitting.	required
`penalty_weight`	`float`	The weight for the penalty term in the objective function (default is 1e3).	`1000.0`

Returns:

Type	Description
`float`	The value of the objective function + penalty (MSE + penalty).

fit ¶

fit(n: int, m: int, data: array, bezierv: Bezierv, init_x: array, init_z: array, emp_cdf_data: array, max_iter: int) -> tuple[Bezierv, float]

Fit the Bezier random variable to the empirical CDF data using the Nelder-Mead optimization algorithm.

Parameters:

Name	Type	Description	Default
`n`	`int`	The number of control points minus one for the Bezier curve.	required
`m`	`int`	The number of empirical CDF data points.	required
`data`	`array`	The sorted data points used to fit the Bezier distribution.	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`init_x`	`array`	Initial guess for the x-coordinates of the control points.	required
`init_z`	`array`	Initial guess for the z-coordinates of the control points.	required
`emp_cdf_data`	`array`	The empirical CDF data points used for fitting.	required
`max_iter`	`int`	The maximum number of iterations for the optimization algorithm.	required

Returns:

Type	Description
`tuple[Bezierv, float]`	A tuple containing: - bezierv (Bezierv): The fitted `Bezierv` object with updated control points. - mse (float): The final mean squared error (MSE) of the fit.

Algorithm Utilities¶

Helper functions and utilities used by the optimization algorithms.

bezierv.algorithms.utils ¶

Classes¶

Functions¶

root_find ¶

root_find(n: int, bezierv: Bezierv, controls_x: array, data_point: float) -> float

Find the parameter value t such that the Bezier random variable's x-coordinate equals data_i.

This method defines a function representing the difference between the x-coordinate of the Bezier curve and the given data point. It then uses Brent's method to find a root of this function, i.e., a value t in [0, 1] that satisfies the equality.

Parameters:

Name	Type	Description	Default
`n`	`int`	The number of control points minus one for the Bezier curve.	required
`bezierv`	`Bezierv`	An instance of the Bezierv class representing the Bezier random variable.	required
`controls_x`	`array`	The control points for the x-coordinates of the Bezier curve.	required
`data_point`	`float`	The data point for which to find the corresponding value of t.	required

Returns:

Type	Description
`float`	The value of t in the interval [0, 1] such that the Bezier random variable's x-coordinate is approximately equal to data_point.

get_t ¶

get_t(n: int, m: int, data: array, bezierv: Bezierv, controls_x: array) -> array

Compute values of the parameter t for each data point using root-finding.

For each sorted data point, this method finds the corresponding value 't' such that the x-coordinate of the Bezier random variable matches the data point.

Parameters:

Name	Type	Description	Default
`controls_x`	`array`	The control points for the x-coordinates of the Bezier curve.	required
`data`	`array`	Array of data points for which to compute the corresponding values of t.	required

Returns:

Type	Description
`array`	An array of values of t corresponding to each data point.

API Reference¶

Core Classes¶

Bezierv - Main Distribution Class¶

bezierv.classes.bezierv.Bezierv ¶

Functions¶

update_bezierv ¶

combinations ¶

deltas ¶

bernstein ¶

poly_x ¶

poly_z ¶

root_find ¶

eval_t ¶

eval_x ¶

cdf_x ¶

quantile ¶

pdf_t ¶

pdf_x ¶

pdf_numerator_t ¶

get_mean ¶

get_variance ¶

random ¶

plot_cdf ¶

plot_pdf ¶

InteractiveBezierv - Interactive Editor¶

bezierv.classes.bezierv.InteractiveBezierv ¶

Distribution Fitting¶

DistFit - Fit Distributions to Data¶

bezierv.classes.distfit.DistFit ¶

Functions¶

fit ¶

get_controls_z ¶

get_controls_x ¶

Convolution Operations¶

Convolver - Sum of Random Variables¶

bezierv.classes.convolver.Convolver ¶

Functions¶

convolve ¶

convolve_exact ¶

exact_cdf_two_bezierv ¶

Optimization Algorithms¶

Projected Gradient Method¶

bezierv.algorithms.proj_grad ¶

Classes¶

Functions¶

grad ¶

project_z ¶

fit ¶

Projected Subgradient Method¶

bezierv.algorithms.proj_subgrad ¶

Classes¶

Functions¶

subgrad ¶

project_x ¶

project_z ¶

objective_function ¶

fit ¶

Nonlinear Optimization¶

bezierv.algorithms.non_linear ¶

Classes¶

Functions¶

fit ¶

Nelder-Mead¶

bezierv.algorithms.nelder_mead ¶

Classes¶

Functions¶

objective_function ¶

objective_function_lagrangian ¶

fit ¶

Algorithm Utilities¶

bezierv.algorithms.utils ¶

Classes¶

Functions¶

root_find ¶

get_t ¶

See Also¶