Polynomial¶
The polynomial parent class; one of the main building blocks in Effective Quadratures.
- class equadratures.poly.Poly(parameters, basis, method=None, sampling_args=None, solver_args={}, variable=None, override_cardinality=False)[source]¶
Definition of a polynomial object.
- Parameters
parameters (list) – A list of parameters, where each element of the list is an instance of the Parameter class.
basis (Basis) – An instance of the Basis class corresponding to the multi-index set used.
method (str, optional) – The method used for computing the coefficients. Should be one of:
compressed-sensing
,least-squares
,minimum-norm
,numerical-integration
,least-squares-with-gradients
,least-absolute-residual
,huber
,elastic-net
,relevance-vector-machine
orcustom-solver
. SeeSolver
for further details.sampling_args (dict, optional) –
A dict containing optional arguments centered around the specific sampling strategy:
mesh (str): Avaliable options are:
monte-carlo
,sparse-grid
,tensor-grid
,induced
, oruser-defined
. Note that when thesparse-grid
option is invoked, the sparse pseudospectral approximation method [1] is the adopted. One can think of this as being the correct way to use sparse grids in the context of polynomial chaos [2] techniques.subsampling-algorithm (str): The
subsampling-algorithm
input refers to the optimisation technique for subsampling. In the aforementioned four sampling strategies, we generate a logarithm factor of samples above the required amount and prune down the samples using an optimisation technique (see [1]). Existing optimisation strategies include:qr
,lu
,svd
,newton
. These refer to QR with column pivoting [2], LU with row pivoting [3], singular value decomposition with subset selection [2] and a convex relaxation via Newton’s method for determinant maximization [4]. Note that if thetensor-grid
option is selected, then subsampling will depend on whether the Basis argument is a total order index set, hyperbolic basis or a tensor order index set.sampling-ratio (float): Denotes the extent of undersampling or oversampling required. For values equal to unity (default), the number of rows and columns of the associated Vandermonde-type matrix are equal.
sample-points (numpy.ndarray): A numpy ndarray with shape (number_of_observations, dimensions) that corresponds to a set of sample points over the parameter space.
sample-outputs (numpy.ndarray): A numpy ndarray with shape (number_of_observations, 1) that corresponds to model evaluations at the sample points. Note that if
sample-points
is provided as an input, then the code expectssample-outputs
too.sample-gradients (numpy.ndarray): A numpy ndarray with shape (number_of_observations, dimensions) that corresponds to a set of sample gradient values over the parameter space.
solver_args (dict, optional) – Optional arguments centered around the specific solver used for computing the coefficients. See
Solver
.override_cardinality (bool, optional) – Option to override the soft cardinality limit of 50E3. By default the limit is enforced in order to avoid excessively long run times when the polynomial coefficients are computed.
Examples
>>> # Subsampling from a tensor grid >>> param = eq.Parameter(distribution='uniform', lower=-1., upper=1., order=3) >>> basis = eq.Basis('total order') >>> poly = eq.Poly(parameters=[param, param], basis=basis, method='least-squares' , sampling_args={'mesh':'tensor-grid', 'subsampling-algorithm':'svd', 'sampling-ratio':1.0})
>>> # User-defined data with compressive sensing >>> X = np.loadtxt('inputs.txt') >>> y = np.loadtxt('outputs.txt') >>> param = eq.Parameter(distribution='uniform', lower=-1., upper=1., order=3) >>> basis = eq.Basis('total order') >>> poly = eq.Poly([param, param], basis, method='compressive-sensing', sampling_args={'sample-points':X_red,'sample-outputs':Y_red})
>>> # Using a sparse grid >>> param = eq.Parameter(distribution='uniform', lower=-1., upper=1., order=3) >>> basis = eq.Basis('sparse-grid', level=7, growth_rule='exponential') >>> poly = eq.Poly(parameters=[param, param], basis=basis, method='numerical-integration')
References
Constantine, P. G., Eldred, M. S., Phipps, E. T., (2012) Sparse Pseudospectral Approximation Method. Computer Methods in Applied Mechanics and Engineering. 1-12. Paper
Xiu, D., Karniadakis, G. E., (2002) The Wiener-Askey Polynomial Chaos for Stochastic Differential Equations. SIAM Journal on Scientific Computing, 24(2), Paper
Seshadri, P., Iaccarino, G., Ghisu, T., (2018) Quadrature Strategies for Constructing Polynomial Approximations. Uncertainty Modeling for Engineering Applications. Springer, Cham, 2019. 1-25. Preprint
Seshadri, P., Narayan, A., Sankaran M., (2017) Effectively Subsampled Quadratures for Least Squares Polynomial Approximations. SIAM/ASA Journal on Uncertainty Quantification, 5(1). Paper
Rogers, S., Girolami, M., (2016) Variability in predictions. In: A First Course in Machine Learning, Second Edition (2nd. ed.). Chapman & Hall/CRC. Book
- get_coefficients()[source]¶
Returns the coefficients of the polynomial approximation.
- Returns
The coefficients with size (number_of_coefficients, 1).
- Return type
- get_mean_and_variance()[source]¶
Computes the mean and variance of the model.
- Returns
Tuple containing two floats; the approximated mean and variance from the polynomial fit.
- Return type
- get_model_evaluations()[source]¶
Returns the output model evaluations used to fit the polynomial.
- Returns
Array containing the output model evaluations.
- Return type
- get_multi_index()[source]¶
Returns the multi-index set of the basis.
- Returns
Array of the coefficients with size (cardinality_of_basis, dimensions).
- Return type
- get_points()[source]¶
Returns the samples based on the sampling strategy.
- Returns
The sampled quadrature points with shape (number_of_samples, dimension).
- Return type
- get_points_and_weights()[source]¶
Returns the samples and weights based on the sampling strategy.
- Returns
Tuple containing two ndarrays; the sampled quadrature points with shape (number_of_samples, dimension), and the corresponding quadrature weights with shape (number_of_samples, 1).
- Return type
- get_poly(stack_of_points, custom_multi_index=None)[source]¶
Evaluates the value of each polynomial basis function at a set of points.
- Parameters
stack_of_points (numpy.ndarray) – An ndarray with shape (number of observations, dimensions) at which the polynomial must be evaluated.
custom_multi_index (numpy.ndarray, optional) – Array containing a custom multi-index set, in the format given by
get_elements()
.
- Returns
Array of shape (cardinality, number_of_observations) corresponding to the polynomial basis function evaluations at the stack_of_points.
- Return type
- get_poly_grad(stack_of_points, dim_index=None)[source]¶
Evaluates the gradient for each of the polynomial basis functions at a set of points, with respect to each input variable.
- Parameters
stack_of_points (numpy.ndarray) – An ndarray with shape (number_of_observations, dimensions) at which the gradient must be evaluated.
dim_index (int, optional) – Index of the dimension to evaluate the gradient for.
- Returns
A list with d elements, where d corresponds to the dimension of the problem. Each element is a numpy.ndarray of shape (cardinality, number_of_observations) corresponding to the gradient polynomial evaluations at the stack_of_points.
- Return type
- get_poly_hess(stack_of_points)[source]¶
Evaluates the Hessian for each of the polynomial basis functions at a set of points, with respect to each input variable.
- Parameters
stack_of_points (numpy.ndarray) – An ndarray with shape (number_of_observations, dimensions) at which the Hessian must be evaluated.
- Returns
A list with d^2 elements, where d corresponds to the dimension of the model. Each element is a numpy.ndarray of shape (cardinality, number_of_observations) corresponding to the hessian polynomial evaluations at the stack_of_points.
- Return type
- get_polyfit(stack_of_points, uq=False)[source]¶
Evaluates the /polynomial approximation of a function (or model data) at prescribed points.
- Parameters
stack_of_points (numpy.ndarray) – An ndarray with shape (number_of_observations, dimensions) at which the polynomial fit must be evaluated at.
uq (bool, optional) – If
True
, the estimated uncertainty (standard deviation) of the polynomial approximation is also returned (see [5]).
- Returns
Array with shape (1, number_of_observations) corresponding to the polynomial approximation of the model.
- Return type
- get_polyfit_function()[source]¶
Returns a callable polynomial approximation of a function (or model data).
- Returns
A callable function.
- Return type
- get_polyfit_grad(stack_of_points, dim_index=None)[source]¶
Evaluates the gradient of the polynomial approximation of a function (or model data) at prescribed points.
- Parameters
stack_of_points (numpy.ndarray) – An ndarray with shape (number_of_observations, dimensions) at which the polynomial fit approximation’s gradient must be evaluated at.
dim_index (int, optional) – Index of dimension to evaluate gradient for.
- Returns
Array of shape (dimensions, number_of_observations) corresponding to the polynomial gradient approximation of the model.
- Return type
- get_polyfit_grad_function()[source]¶
Returns a callable for the gradients of the polynomial approximation of a function (or model data).
- Returns
A callable function.
- Return type
- get_polyfit_hess(stack_of_points)[source]¶
Evaluates the hessian of the polynomial approximation of a function (or model data) at prescribed points.
- Parameters
stack_of_points (numpy.ndarray) – An ndarray with shape (number_of_observations, dimensions) at which the polynomial fit approximation’s Hessian must be evaluated at.
- Returns
Array of shape (dimensions, dimensions, number_of_observations) corresponding to the polynomial Hessian approximation of the model.
- Return type
- get_polyfit_hess_function()[source]¶
Returns a callable for the hessian of the polynomial approximation of a function (or model data).
- Returns
A callable function.
- Return type
- get_polyscore(X_test=None, y_test=None, metric='adjusted_r2')[source]¶
Evaluates the accuracy of the polynomial approximation using the selected accuracy metric.
Training accuracy is evaluated on the data used for fitting the polynomial. Testing accuracy is evaluated on new data if it is provided by the
X_test
andy_test
arguments (both must be provided together).- Parameters
X_test (numpy.ndarray, optional) – An ndarray with shape (number_of_observations, dimensions), containing new data
X_test
data (optional).y_test (numpy.ndarray, optional) – An ndarray with shape (number_of_observations, 1) containing new
y_test
data (optional).metric (str, optional) – An optional string containing the scoring metric to use. Avaliable options are:
adjusted_r2
,r2
,mae
,rmse
, ornormalised_mae
(default:adjusted_r2
).
- Returns
float – If
X_test
andy_test
areNone
. The training score of the model, output as a float.tuple – If
X_test
andy_test
are given. Tuple containing the train and test scores of the model.
- get_skewness_and_kurtosis()[source]¶
Computes the skewness and kurtosis of the model.
- Returns
Tuple containing two floats; the approximated skewness and kurtosis from the polynomial fit.
- Return type
- get_summary(filename=None, tosay=False)[source]¶
A simple utility that writes a file summarising what the polynomial approximation has determined.
- get_total_sobol_indices()[source]¶
Computes the total Sobol’ indices.
- Returns
Array of length d (number of input parameters) of total Sobol’ indices.
- Return type
- get_weights()[source]¶
Computes quadrature weights.
- Returns
Array of the corresponding quadrature weights with shape (number_of_samples, 1).
- Return type
- plot_model_vs_data(ax=None, sample_data=None, metric='adjusted_r2', show=True)[source]¶
Plots the polynomial approximation against the true data. See
plot_model_vs_data()
for full description.
- plot_parameters(ax=None, cols=2, show=True)[source]¶
Plots the probability density functions for all Parameters within a Polynomial. See
plot_parameters()
for full description.
- plot_polyfit_1D(ax=None, uncertainty=True, output_variances=None, number_of_points=200, show=True)[source]¶
Plots a 1D only polynomial fit to the data. See
plot_polyfit_1D()
for full description.
- plot_sobol(ax=None, order=1, show=True, labels=None, kwargs={})[source]¶
Plots a polynomial’s Sobol’ indices of a given order. See
plot_sobol()
for full description.
- plot_sobol_heatmap(parameters=None, show=True, ax=None)[source]¶
Generates a heatmap showing the first and second order Sobol indices. See
plot_sobol_heatmap()
for full description.
- plot_total_sobol(ax=None, show=True, labels=None, kwargs={})[source]¶
Plots a polynomial’s total-order Sobol’ indices. See
plot_total_sobol()
for full description.
- set_model(model=None, model_grads=None)[source]¶
Computes the coefficients of the polynomial via the method selected.
If model evaluations and/or gradients have not yet been provided to Poly via
sample-outputs
and/orsample-gradients
, they can be given here via themodel
andmodel_grads
arguments.- Parameters
model (Callable,numpy.ndarray) – The function that needs to be approximated. In the absence of a callable function, the input can be a ndarray model evaluations at the quadrature points.
model_grads (Callable,numpy.ndarray) – The gradient of the function that needs to be approximated. In the absence of a callable gradient function, the input can be a ndarray of gradient evaluations at the quadrature points.
Examples
- Defining a simple univariate example
>>> x = np.linspace(-2,2,20).reshape(-1,1) >>> f = lambda x: x**2 - 1 >>> param = eq.Parameter(lower=-2,upper=2,order=2) >>> basis = eq.Basis('univariate')
- Least-squares regression of existing data
>>> y = f(x) >>> poly = eq.Poly(param,basis,method='least-squares',sampling_args={'mesh': 'user-defined','sample-points':x,'sample-outputs':y}) >>> poly.set_model() >>> eq.datasets.score(f(xtest),poly.get_polyfit(xtest),metric='rmse') 5.438959822042073e-16
- Numerical integration with model provided as a callable function
>>> poly = eq.Poly(param,basis,method='numerical-integration') >>> poly.set_model(f) >>> eq.datasets.score(f(xtest),poly.get_polyfit(xtest),metric='rmse') 5.363652779335998e-15
- Numerical integration, manually providing model evaluations at quadrature points
>>> poly = eq.Poly(param,basis,method='numerical-integration') >>> x = poly.get_points() >>> y = f(x) >>> poly.set_model(y) >>> eq.datasets.score(f(xtest),poly.get_polyfit(xtest),metric='rmse') 5.363652779335998e-15
- Raises
ValueError – model values should be a column vector.
- equadratures.poly.evaluate_model(points, function)[source]¶
Evaluates the model function at given values.
- Parameters
points (numpy.ndarray) – An ndarray with shape (number_of_observations, dimensions) at which the gradient must be evaluated.
function (Callable) – A callable argument for the function.
- Returns
Array of function evaluations.
- Return type
- equadratures.poly.evaluate_model_gradients(points, fungrad, format='matrix')[source]¶
Evaluates the model gradient at given values.
- Parameters
points (numpy.ndarray) – An ndarray with shape (number_of_observations, dimensions) at which the gradient must be evaluated.
fungrad (Callable) – A callable argument for the function’s gradients.
format (str, optional) – The format in which the output is to be provided:
matrix
will output a numpy.ndarray of shape (number_of_observations, dimensions) with gradient values, whilevector
will stack all the vectors in this matrix to yield a numpy.ndarray with shape (number_of_observations x dimensions, 1).
- Returns
Array of gradient evaluations.
- Return type
- equadratures.poly.vector_to_2D_grid(coefficients, index_set)[source]¶
Handy function that converts a vector of coefficients into a matrix based on index set values.
- Parameters
coefficients (numpy.ndarray) – An ndarray with shape (N, 1) where N corresponds to the number of coefficient values.
index_set (numpy.ndarray) – The multi-index set of the basis.
- Returns
Tuple (x,y,z,max_order), containing the x,y values of the meshgrid, the coefficient values, and the highest order.
- Return type