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) <https://sites.google.com/view/sparse-grids-kit>`_.

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:

.. code-block:: bash

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

Then import and start working with sparse grids:

.. code-block:: python

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

.. code-block:: bash

   # 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
-------------

.. code-block:: python

   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.


.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules
   installation
   usage
   contributing
   changelog

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`