Enhance clarity in API, index, and theory documentation

docs/api.md

@@ -1,10 +1,22 @@
 # API Reference
 
-All public routines are exported via the `smolpack` Python module.
+`smolpack` provides a Python interface to the SMOLPACK C library (Petras, 2001; 2003)
+for sparse-grid Smolyak cubature. The numerical core is implemented in C and compiled
+via `f2py`, providing near-native performance with a NumPy-based Python interface.
+See the [Theory](theory.md) and [Quickstart](quickstart.md) for mathematical background
+and usage examples.
 
 ---
 
-## Overview
+## Main Features
+
+- Sparse-grid cubature over $[0,1]^d$ for any dimension $1 \le d < 40$
+- Two solver variants: delayed and standard Clenshaw-Curtis Smolyak rules
+- Simple integrand signature — any callable `f(dim, x) -> float` works
+- Built-in function-evaluation counter via `get_count()`
+- `print_stats` flag for runtime diagnostics
+
+## Solvers
 
 | Function | Underlying 1-D rule | Integrates |
 |---|---|---|
@@ -133,7 +145,22 @@ print(f"Evaluations: {n}")
 
 ---
 
-## References
+## Example Workflows
+
+`smolpack` supports any callable integrand. You can:
+
+- Integrate smooth analytic functions in low to moderate dimensions
+- Compare accuracy between `int_smolyak` and `cc_int_smolyak` at the same level
+- Monitor the number of function evaluations with `get_count()` or `print_stats=True`
+- Use lambda functions for quick interactive experiments
+
+See the [Quickstart](quickstart.md) for full code examples, including:
+
+- Exponential sum and product integrands
+- High-dimensional integration (10-D)
+- Genz oscillatory test functions
+- Convergence study with increasing `qq`
+- Solver comparison
 
-See [References](references.md) for full citations of the Petras and Smolyak
-papers underlying the algorithms.
+All examples demonstrate both `int_smolyak` and `cc_int_smolyak`, along with
+the `get_count()` and `print_stats` diagnostics.

docs/index.md

@@ -1,66 +1,93 @@
 # smolpack
 
-**Sparse-grid Smolyak cubature over $[0,1]^d$ for Python.**
+**Multidimensional Quadrature Using Sparse Grids for Python**
 
 ---
 
-## What is smolpack?
+## Overview
 
 `smolpack` is a Python library for efficient numerical integration (cubature)
 over the unit hypercube $[0,1]^d$ using
 [Smolyak's algorithm](https://en.wikipedia.org/wiki/Sparse_grid) with
-Clenshaw-Curtis quadrature rules. The numerical core is written in C and
-compiled via `f2py`, giving near-native performance while providing a clean,
-NumPy-based Python API.
+Clenshaw-Curtis quadrature rules. The package allows you to **easily** and
+**efficiently** integrate high-dimensional functions without the exponential
+cost of classical tensor-product rules.
 
-**Numerical integration** (quadrature in 1-D, cubature in higher dimensions) is
-a fundamental problem in computational science. Standard tensor-product rules
-scale exponentially with dimension — a 1-D rule with $n$ nodes becomes $n^d$
-nodes in $d$ dimensions, quickly making the computation intractable. Smolyak's
-algorithm circumvents this *curse of dimensionality* by constructing **sparse
-grids** that achieve comparable polynomial exactness with dramatically fewer
-nodes.
-
-`smolpack` approximates integrals of the form:
+Numerical integration in multiple dimensions is a fundamental problem in
+computational science. Standard tensor-product rules scale exponentially with
+dimension — a 1-D rule with $n$ nodes becomes $n^d$ nodes in $d$ dimensions,
+quickly making the computation intractable. Smolyak's algorithm constructs
+**sparse grids** that achieve comparable polynomial exactness with dramatically
+fewer nodes. `smolpack` approximates integrals of the form:
 
 $$
 I[f] = \int_{[0,1]^d} f(\mathbf{x})\,d\mathbf{x},
 $$
 
 using the Smolyak combination technique with Clenshaw-Curtis basic rules.
 
-## Available solvers
-
-| Solver | Underlying 1-D rule | Characteristics |
-|---|---|---|
-| `int_smolyak` | Delayed Clenshaw-Curtis | Fewer function evaluations for a given accuracy level |
-| `cc_int_smolyak` | Standard Clenshaw-Curtis | Classical nested rule (1, 3, 5, 9, 17, 33, 65, … nodes) |
+## Requirements
 
-!!! tip "Choosing a solver"
-    For most applications, start with `int_smolyak` — the delayed variant
-    achieves the same polynomial exactness with fewer integrand evaluations.
-    Use `cc_int_smolyak` when compatibility with the classical Clenshaw-Curtis
-    node hierarchy is required.
+- [NumPy](http://www.numpy.org/)
 
-## Quick example
+## Example Usage
 
 ```python
 import numpy as np
 import smolpack
 
+
 # Integrate exp(x1 + x2 + x3) over [0,1]^3
 # Exact value: (e - 1)^3 ≈ 5.073214
+def exp_sum(dim, x):
+    return np.exp(np.sum(x))
 
 
-def my_func(dim, x):
-    return np.exp(np.sum(x))
+result = smolpack.int_smolyak(exp_sum, dim=3, qq=5)
+print(f"Result = {result:.6f}")
+
+# Convergence with increasing level
+exact = (np.e - 1.0) ** 3
+for qq in range(4, 9):
+    result = smolpack.int_smolyak(exp_sum, dim=3, qq=qq)
+    print(
+        f"qq={qq}  k={qq - 3}  result={result:.10f}  error={abs(result - exact):.2e}"
+    )
 
+# Compare both solvers
+r1 = smolpack.int_smolyak(exp_sum, dim=3, qq=7)
+r2 = smolpack.cc_int_smolyak(exp_sum, dim=3, qq=7)
+print(f"Delayed CC:  {r1:.10f}")
+print(f"Standard CC: {r2:.10f}")
 
-result = smolpack.int_smolyak(my_func, dim=3, qq=5)
-print(f"Integral ≈ {result:.6f}")
+# Query function-evaluation count
+n = smolpack.get_count()
+print(f"Evaluations: {n}")
 ```
 
-## License
+## Main Features
+
+1. **Sparse-grid cubature** over $[0,1]^d$ for dimensions $1 \le d < 40$.
+2. Two solver variants: delayed and standard Clenshaw-Curtis Smolyak rules.
+3. High-performance C core compiled via `f2py`, with a clean NumPy-based Python API.
+4. Simple integrand signature — any callable `f(dim, x) -> float` works.
+5. Built-in function-evaluation counter via `get_count()`.
+6. `print_stats` flag for runtime diagnostics.
+
+## See Also
+
+- [NumPy](http://www.numpy.org/): Array library used for the integrand interface
+- [SciPy](http://scipy.org): General scientific computing — complements `smolpack` for pre/post-processing
+- [SMOLPACK C library](https://people.math.sc.edu/Burkardt/c_src/smolpack/smolpack.html): The original C implementation by Knut Petras, distributed by John Burkardt
+
+## Acknowledgements
+
+The author thanks [Knut Petras](https://people.math.sc.edu/Burkardt/c_src/smolpack/smolpack.html)
+for the original SMOLPACK C library, which provides the numerical core of this
+package and is distributed via [John Burkardt's page](https://people.math.sc.edu/Burkardt/c_src/smolpack/smolpack.html).
+
+## References
 
-smolpack is distributed under the
-[LGPL-2.1](https://github.com/eggzec/smolpack/blob/main/LICENSE) license.
+- Smolyak, S., "Quadrature and Interpolation Formulas for Tensor Products of Certain Classes of Functions," *Doklady Akademii Nauk SSSR*, 4, 240–243, 1963.
+- Petras, K., "Fast Calculation of Coefficients in the Smolyak Algorithm," *Numerical Algorithms*, 26(2), 93–109, 2001.
+- Petras, K., "Smolyak Cubature of Given Polynomial Degree with Few Nodes for Increasing Dimension," *Numerische Mathematik*, 93(4), 729–753, 2003.

docs/installation.md

@@ -1,7 +1,6 @@
 # Installation
 
-`smolpack` is distributed as a compiled wheel on PyPI and can also be installed
-from source via GitHub.
+`smolpack` can be installed from PyPI, GitHub, or built from source.
 
 ---
 
@@ -16,30 +15,31 @@ For source builds you additionally need:
 - `meson` and `meson-python` build system
 - `numpy` (for `f2py` compilation)
 
-## PyPI (recommended)
+## [PyPI](https://pypi.org/project/smolpack)
 
-### pip
+For using the PyPI package in your project, add the following to your
+configuration file:
 
-```bash
-pip install --upgrade smolpack
-```
+=== "pyproject.toml"
 
-### pyproject.toml dependency
+    ```toml
+    [project]
+    dependencies = [
+        "smolpack"
+    ]
+    ```
 
-```toml
-[project]
-dependencies = [
-    "smolpack"
-]
-```
+=== "requirements.txt"
 
-### requirements.txt
+    ```text
+    smolpack
+    ```
 
-```text
-smolpack
-```
+### pip
 
-## Package managers
+```bash
+pip install --upgrade smolpack
+```
 
 ### uv
 
@@ -75,7 +75,7 @@ pdm add smolpack
 hatch add smolpack
 ```
 
-## Installing from source (GitHub)
+## [git](https://github.com/eggzec/smolpack)
 
 Install the latest development version directly from the repository:
 
@@ -85,35 +85,32 @@ pip install --upgrade "git+https://github.com/eggzec/smolpack.git#egg=smolpack"
 
 ### Building locally
 
-Clone and build from source if you want to modify the C code or test
-local changes:
+Clone and build from source to modify the C code or test local changes:
 
 ```bash
 git clone https://github.com/eggzec/smolpack.git
 cd smolpack
 uv pip install .
 ```
 
-This invokes the `meson` build system to compile the C sources via
-`f2py` and install the resulting extension module in development mode.
+This invokes the `meson` build system to compile the C sources via `f2py`
+and install the resulting extension module.
 
 !!! warning "C compiler required"
-    Source builds require a working C compiler. On most Linux
-    distributions install `gcc`
+    Source builds require a working C compiler.
 
-```bash
-# Debian/Ubuntu
-sudo apt install gcc
+    ```bash
+    # Debian/Ubuntu
+    sudo apt install gcc
 
-# Fedora
-sudo dnf install gcc
+    # Fedora
+    sudo dnf install gcc
 
-# macOS (Homebrew — Clang is pre-installed via Xcode Command Line Tools)
-xcode-select --install
-```
-
-On Windows, install MSVC (Microsoft Visual C++) via Visual Studio Build Tools. This is required for source builds and matches the official Python and NumPy wheels. MinGW is not supported.
+    # macOS (Clang via Xcode Command Line Tools)
+    xcode-select --install
+    ```
 
+    On Windows, install MSVC via Visual Studio Build Tools. MinGW is not supported.
 
 ## Verifying the installation
 
@@ -129,8 +126,5 @@ print("smolpack is working! Integral:", result)
 
 ## Dependencies
 
-| Package | Purpose |
-|---|---|
-| `numpy` | Array handling, `f2py` integration |
-
-No other runtime dependencies are required.
+- Python >=3.10
+- [numpy](https://pypi.org/project/numpy)