Dimension reduction with polynomials#

class equadratures.subspaces.Subspaces(method, full_space_poly=None, sample_points=None, sample_outputs=None, subspace_dimension=2, polynomial_degree=2, param_args=None, poly_args=None, dr_args=None)[source]#

This class defines a subspaces object. It can be used for polynomial-based subspace dimension reduction.

Parameters

method (str) –
The method to be used for subspace-based dimension reduction. Two options:
- active-subspace, which uses ideas in [1] and [2] to compute a dimension-reducing subspace with a global polynomial approximant. Gradients evaluations of the polynomial approximation are used to compute the averaged outer product of the gradient covariance matrix. The polynomial approximation in the original full-space can be provided via full_space_poly. Otherwise, it is fit internally to the data provided via sample_points and sample_outputs.
- variable-projection [3], where a Gauss-Newton optimisation problem is solved to compute both the polynomial coefficients and its subspace, with the data provided via sample_points and sample_outputs.
full_space_poly (Poly, optional) – An instance of Poly fitted to the full-space data, to use for the AS computation.
sample_points (numpy.ndarray, optional) – Array with shape (number_of_observations, dimensions) that corresponds to a set of sample points over the parameter space.
sample_outputs (numpy.ndarray, optional) – Array with shape (number_of_observations, 1) that corresponds to model evaluations at the sample points.
subspace_dimension (int, optional) – The dimension of the active subspace.
param_args (dict, optional) – Arguments passed to parameters of the AS polynomial. (see Parameter)
poly_args (dict , optional) – Arguments passed to constructing polynomial used for AS computation. (see Poly)
dr_args (dict, optional) – Arguments passed to customise the VP optimiser. See documentation for _get_variable_projection() in source.

Examples

Obtaining a 2D subspace via active subspaces on user data

>>> mysubspace = Subspaces(method='active-subspace', sample_points=X, sample_outputs=Y)
>>> eigs = mysubspace.get_eigenvalues()
>>> W = mysubspace.get_subspace()[:, :2]
>>> e = mysubspace.get_eigenvalues()

Obtaining a 2D subspace via active subspaces with a Poly object (remember to call set_model() on Poly first)

>>> mysubspace = Subspaces(method='active-subspace', full_space_poly=my_poly)
>>> eigs = mysubspace.get_eigenvalues()
>>> W = mysubspace.get_subspace()[:, :2]
>>> e = mysubspace.get_eigenvalues()

Obtaining a 2D subspace via variable projection on user data

>>> mysubspace = Subspaces(method='variable-projection', sample_points=X, sample_outputs=Y)
>>> W = mysubspace.get_subspace()[:, :2]

References

Constantine, P., (2015) Active Subspaces: Emerging Ideas for Dimension Reduction in Parameter Studies. SIAM Spotlights.
Seshadri, P., Shahpar, S., Constantine, P., Parks, G., Adams, M. (2018) Turbomachinery Active Subspace Performance Maps. Journal of Turbomachinery, 140(4), 041003. Paper.
Hokanson, J., Constantine, P., (2018) Data-driven Polynomial Ridge Approximation Using Variable Projection. SIAM Journal of Scientific Computing, 40(3), A1566-A1589. Paper.

get_eigenvalues()[source]#

Returns the eigenvalues of the dimension reducing subspace. Note: this option is currently only valid for method active-subspace.

Returns: Array of shape (dimensions,) corresponding to the eigenvalues of the above mentioned covariance matrix.
Return type: numpy.ndarray

get_linear_inequalities()[source]#

Returns the linear inequalities defining the zonotope vertices, i.e., Ax<=b.

Returns: Tuple (A,b), containing the numpy.ndarray’s A and b; where A is the matrix for setting the linear inequalities, and b is the right-hand-side vector for setting the linear inequalities.
Return type: tuple

get_samples_constraining_active_coordinates(inactive_samples, active_coordinates)[source]#

A hit and run type sampling strategy for generating samples at a given coordinate in the active subspace by varying its coordinates along the inactive subspace.

Parameters

inactive_samples (int) – The number of inactive samples required.
active_coordiantes (numpy.ndarray) – The active subspace coordinates.

Returns

Array containing the full-space coordinates.

Return type

numpy.ndarray

Note

This routine has been adapted from Paul Constantine’s hit_and_run() function; see reference below.

Constantine, P., Howard, R., Glaws, A., Grey, Z., Diaz, P., Fletcher, L., (2016) Python Active-Subspaces Utility Library. Journal of Open Source Software, 1(5), 79. Paper.

get_subspace()[source]#

Returns the dimension reducing subspace.

Returns: Array of shape (dimensions, dimensions) where the first subspace_dimension columns contain the dimension reducing subspace, while the remaining columns contain its orthogonal complement.
Return type: numpy.ndarray

get_subspace_polynomial()[source]#

Returns a polynomial defined over the dimension reducing subspace.

Returns: A Poly object that defines a polynomial over the subspace. The distribution of parameters is assumed to be uniform and the maximum and minimum bounds for each parameter are defined by the maximum and minimum values of the project samples.
Return type: Poly

get_zonotope_vertices(num_samples=10000, max_count=100000)[source]#

Returns the vertices of the zonotope – the projection of the high-dimensional space over the computed subspace.

Parameters

num_samples (int, optional) – Number of samples per iteration to check.
max_count (int, optional) – Maximum number of iteration.

Returns

Array of shape (number of vertices, subspace_dimension).

Return type

numpy.ndarray

Note

This routine has been adapted from Paul Constantine’s zonotope_vertices() function; see reference below.

Constantine, P., Howard, R., Glaws, A., Grey, Z., Diaz, P., Fletcher, L., (2016) Python Active-Subspaces Utility Library. Journal of Open Source Software, 1(5), 79. Paper.

plot_2D_contour_zonotope(mysubspace, minmax=[- 3.5, 3.5], grid_pts=180, show=True, ax=None)[source]#: Generates a 2D contour plot of the polynomial ridge approximation. See plot_2D_contour_zonotope() for full description.

plot_samples_from_second_subspace_over_first(mysubspace_2, axs=None, no_of_samples=500, minmax=[- 3.5, 3.5], grid_pts=180, show=True)[source]#: Generates a zonotope plot where samples from the second subspace are projected over the first. See plot_samples_from_second_subspace_over_first() for full description.

plot_sufficient_summary(ax=None, X_test=None, y_test=None, show=True, poly=True, uncertainty=False, legend=False, scatter_kwargs={}, plot_kwargs={})[source]#: Generates a sufficient summary plot for 1D or 2D polynomial ridge approximations. See plot_sufficient_summary() for full description.