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

1. Constantine, P., (2015) Active Subspaces: Emerging Ideas for Dimension Reduction in Parameter Studies. SIAM Spotlights.

2. Seshadri, P., Shahpar, S., Constantine, P., Parks, G., Adams, M. (2018) Turbomachinery Active Subspace Performance Maps. Journal of Turbomachinery, 140(4), 041003. Paper.

3. 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.