Welcome to sgpykit’s documentation!

Warning

This documentation is autogenerated and may contain inaccuracies or incomplete information. A manual review and update of the documentation is planned for future releases.

sgpykit is a Python library for constructing, manipulating, evaluating and analysing sparse-grid surrogate models. It implements a Python version of Sparse Grids Matlab Kit (SGMK).

Key Features

  1. Sparse Grid Construction - Supports multiple sparse grid rules (e.g., Total Degree (TD), Hyperbolic Cross (HC), Smolyak (SM)). - Works with various knot types (e.g., Clenshaw-Curtis, Gauss-Patterson, Leja, Chebyshev, Legendre, Hermite, Laguerre). - Allows custom level-to-knot mappings (linear, doubling, tripling, etc.).

  2. Adaptive Sparse Grids - Implements dimension-adaptive refinement to dynamically refine grids where needed. - Optimizes computational efficiency by focusing on the most relevant regions of the domain.

  3. Function Evaluation & Interpolation - Efficiently evaluates functions on sparse grids. - Supports interpolation, quadrature, and derivative computations (gradients, Hessians). - Handles both scalar and vector-valued functions.

  4. Modal & Polynomial Representations - Converts sparse grid interpolants into orthogonal polynomial expansions (Legendre, Chebyshev, Hermite, etc.). - Enables generalized Polynomial Chaos Expansions (gPCE) for uncertainty quantification.

  5. Visualization & Analysis - Includes tools for plotting sparse grids in 2D and 3D. - Computes Sobol indices for sensitivity analysis. - Provides utilities for comparing and validating sparse grids.

Use Cases

  • Uncertainty Quantification (UQ) – Efficiently compute statistics of high-dimensional models.

  • Numerical Integration – Perform high-dimensional quadrature with fewer evaluations.

  • Interpolation & Surrogate Modeling – Approximate complex functions with sparse grids.

  • Sensitivity Analysis – Compute Sobol indices to identify influential parameters.

Quickstart

Install sgpykit:

pip install git+https://github.com/uncertaintyhub/sgpykit

Then import and start working with sparse grids:

import sgpykit as sg

# Create a sparse grid
S, _ = sg.create_sparse_grid(N=2, w=3, knots=sg.knots_CC, lev2knots=sg.lev2knots_doubling)

Installation

The library has no compiled extensions and relies only on standard scientific Python packages (NumPy, SciPy and Matplotlib).

# Create and activate a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate   # on Windows use `venv\Scripts\activate`

# Upgrade pip and install dependencies
pip install --upgrade pip
pip install numpy scipy matplotlib

# Install sgpykit
pip install git+https://github.com/uncertaintyhub/sgpykit

Usage Example

import numpy as np
import sgpykit as sg

# 1. Define the 1-D knot generator (Clenshaw-Curtis)
knots = lambda n: sg.knots_CC(n, -1, 1, 'nonprob')

# 2. Build a sparse grid of level w = 3 in N = 2 dimensions
N = 2  # number of variables
w = 3  # level (total degree)
S, _ = sg.create_sparse_grid(N=N, w=w, knots=knots,
                            lev2knots=sg.lev2knots_doubling)
Sr = sg.reduce_sparse_grid(S)

# 3. Evaluate a target function on the grid points
fs = lambda x: sum(x)  # or np.sum(x,axis=0)
y, *_ = sg.evaluate_on_sparse_grid(fs, S=None, Sr=Sr)

# 4. Interpolate the surrogate at new locations
Mnew = 5
Xnew = np.random.uniform(-1, 1, size=(N, Mnew))
y_pred = sg.interpolate_on_sparse_grid(S, Sr, function_on_grid, Xnew)

print('Interpolated values:', y_pred)

Development Status

This implementation is currently in Alpha and the API is not yet finalized. Expect potential changes in future releases.

Key Areas for Improvement: - Testing: More comprehensive test coverage is needed. - Performance: A performance analysis is planned to enhance efficiency. - Streamlining Code: Future releases will focus on reducing unnecessary overhead and improving Pythonic efficiency.

Contents:

Indices and tables