API reference

Core classes

Bezier random variable

bezierv.classes.bezierv.Bezierv(n, controls_x=None, controls_z=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).

update_bezierv(controls_x, controls_z)

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()

Compute and store binomial coefficients.

Parameters:

Name	Type	Description	Default
None			required

Returns:

Type	Description
None

deltas()

Compute the differences between consecutive control points.

Parameters:

Name	Type	Description	Default
None			required

Returns:

Type	Description
None

bernstein(t, i, combinations, n)

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 - like	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(t, controls_x=None)

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(t, controls_z=None)

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 - like	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(x, method='brentq')

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(t)

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 of floats	A tuple (p_x, p_z) where p_x is the evaluated x-coordinate and p_z is the evaluated z-coordinate.

eval_x(x)

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 of floats	A tuple (p_x, p_z) where p_x is the x-coordinate and p_z is the z-coordinate of the curve at x.

cdf_x(x)

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(alpha, method='brentq')

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(t)

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(x)

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(t)

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(closed_form=True)

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.

random(n_sims, *, rng=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(data=None, num_points=100, ax=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

Returns:

Type	Description
None

plot_pdf(data=None, num_points=100, ax=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

Returns:

Type	Description
None

Distribution fitting

bezierv.classes.distfit.DistFit(data, n=5, init_x=None, init_z=None, init_t=None, emp_cdf_data=None, method_init_x='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'

fit(method='projgrad', step_size_PG=0.001, max_iter_PG=1000, threshold_PG=0.001, step_size_PS=0.001, max_iter_PS=1000, solver_NL='ipopt', max_iter_NM=1000)

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
solver_NL	str	The solver to use for the nonlinear fitting method (default is 'ipopt').	'ipopt'

Returns:

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

get_controls_z()

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

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

Parameters:

Name	Type	Description	Default
data	array	The sorted data points.	required

Returns:

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

get_controls_x(method)

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
data	array	The sorted data points.	required

Returns:

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

Convolution

bezierv.classes.convolver.Convolver(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

convolve(n_sims=1000, *, rng=None, **kwargs)

Convolve the Bezier RVs via Monte Carlo 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	{}

---

Algorithms

Projected Gradient Descent

grad(n, m, t, bezierv, controls_z, emp_cdf_data)

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(controls_z)

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(n, m, data, bezierv, init_x, init_z, t, emp_cdf_data, step_size, max_iter, threshold)

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	float or 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
Bezierv	The updated Bezierv instance with fitted control points.
float	The mean squared error (MSE) of the fit.

Projected Subgradient

subgrad(n, m, bezierv, t, controls_z, emp_cdf_data)

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
(array, array)	A tuple containing the subgradient with respect to the x control points and the gradient with respect to the z control points.

project_x(data, controls_x)

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(controls_z)

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(m, bezierv, emp_cdf_data, z, t)

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(n, m, data, bezierv, init_x, init_z, init_t, emp_cdf_data, step_size, max_iter)

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	float	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
Bezierv	The updated Bezierv instance with fitted control points.
float	The mean squared error (MSE) of the fit.

Nonlinear Solver

fit(n, m, data, bezierv, init_x, init_z, init_t, emp_cdf_data, solver)

Fit a Bézier random variable to the empirical CDF data using a nonlinear optimization solver.

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 Bézier distribution.	required
bezierv	Bezierv	An instance of the Bezierv class representing the Bézier 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
init_t	array	Initial guess for the Bézier 'time' parameters corresponding to the data points.	required
emp_cdf_data	array	The empirical CDF data points used for fitting.	required
solver	str	The name of the solver to use for optimization.	required

Returns:

Name	Type	Description
	Bezierv	The fitted Bezierv object with updated control points.
	float	The mean squared error (MSE) of the fit.
Raises	Bezierv
Exception	If the solver fails to find an optimal solution.
Notes	Bezierv
	- The method uses the IPOPT solver for optimization.
	- The control points are constrained to lie within the range of the data.
	- The method ensures that the control points and the Bézier 'time' parameters are sorted.
	- Convexity constraints are applied to the control points and the Bézier 'time' parameters.
	- The first and last control points are fixed to the minimum and maximum of the data, respectively.
	- The first and last Bézier 'time' parameters are fixed to 0 and 1, respectively.

Nelder–Mead

objective_function(concatenated, n, m, data, bezierv, emp_cdf_data)

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(concatenated, n, m, data, bezierv, emp_cdf_data, penalty_weight=1000.0)

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(n, m, data, bezierv, init_x, init_z, emp_cdf_data, max_iter)

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

Returns:

Type	Description
Bezierv	The fitted Bezierv object with updated control points.
float	The mean squared error (MSE) of the fit.

Utilities

root_find(n, bezierv, controls_x, data_point)

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(n, m, data, bezierv, controls_x)

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.