Metadata-Version: 2.4
Name: qoro-maestro-tci
Version: 0.1.3
Summary: Tensor Cross Interpolation engine for high-dimensional integration and function approximation
Author-email: "Qoro Quantum Ltd." <team@qoroquantum.de>
License: Proprietary
Project-URL: Homepage, https://qoroquantum.de
Keywords: tensor,TCI,integration,approximation,tensor-train,cross-interpolation,Monte Carlo,high-dimensional,Qoro
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: cryptlex.lexactivator
Provides-Extra: examples
Requires-Dist: ceviche>=0.1.3; extra == "examples"
Requires-Dist: matplotlib>=3.5.0; extra == "examples"
Requires-Dist: scipy>=1.7.0; extra == "examples"
Requires-Dist: quantlib-python>=1.18; extra == "examples"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# qoro-maestro-tci

**High-performance active Tensor Cross-Interpolation (TCI) engine for surrogate modeling, high-dimensional integration, and multi-output function approximation.**

`qoro-maestro-tci` provides active, sub-exponential black-box function approximation and integration using Tensor Trains (TT) and Tree Tensor Networks (TTN). For complex multi-variable responses, it typically requires **1,000–10,000× fewer evaluations** than dense grid sweeps or Monte Carlo sampling.

---

## Key Features

* **Active Sub-Exponential Sampling**: Learns high-dimensional responses by adaptively querying maximum-uncertainty pivot points.
* **Flexible Topologies**: Supports 1D Tensor Trains (`"tci1"`, `"tci2"`) and hierarchical Tree Tensor Networks (`"tree_tci"`).
* **Quantics TCI (QTCI)**: High-resolution bit discretization (`quantics=True`) for multiscale, non-smooth, or highly oscillatory integrands.
* **Multi-Output / Vector-Valued Fitting**: Simultaneously interpolates multi-dimensional target arrays (e.g. photodetector port intensities, multi-asset option payoffs) via `tensor_shape`.
* **Noise-Robust Denoising**: Built-in statistical sample averaging and outlier rejection (`Cleaner`) for noisy physical or quantum hardware measurements.
* **Analytic Differentiability & Microsecond Evaluation**: Constructed surrogates evaluate in microseconds and provide exact analytical sensitivity gradients for downstream control loops.

---

## Installation

```bash
pip install qoro-maestro-tci
```

---

## License Key Configuration

`qoro-maestro-tci` requires a license key issued by [Qoro Quantum](https://qoroquantum.net). You can configure your key using either of the following methods:

**Method 1: Environment Variable**
```bash
export MAESTRO_LICENSE_KEY="your-license-key-here"
```

**Method 2: License File**
Place your key inside `~/.maestro/license.key`:
```bash
mkdir -p ~/.maestro
echo "your-license-key-here" > ~/.maestro/license.key
```

---

## Quick Start

### 1. High-Dimensional Definite Integration

```python
import maestro_tci as tci
import numpy as np


# Define integrand: accepts (batch, d) -> returns (batch,)
def integrand(x):
    return 2**5 / (1 + 2 * x.sum(axis=1))


result = tci.integrate(
    f=integrand,
    dimensions=5,
    domain=(0.0, 1.0),
    nodes_per_dim=15,
    tolerance=1e-8,
)

print(f"Integral Value: {result.value:.12f}")
print(f"Function Evaluations: {result.n_evals}")
print(f"Converged: {result.converged}")
```

### 2. Building a Fast Differentiable Surrogate

```python
import maestro_tci as tci
import numpy as np


def expensive_physics_sim(x):
    return np.sin(np.pi * x[:, 0]) * np.exp(-0.5 * (x[:, 1] ** 2 + x[:, 2] ** 2))


surrogate = tci.approximate(
    f=expensive_physics_sim,
    dimensions=3,
    domain=[(-3.0, 3.0)] * 3,
    tolerance=1e-6,
)

# Evaluate instantly at continuous coordinates (no simulator calls)
val = surrogate(1.0, 0.5, -0.2)

# Batch evaluation
test_points = np.random.uniform(-3, 3, (1000, 3))
batch_vals = surrogate.evaluate_batch(test_points)

# Instant definite integration via weight contraction
integral_value = surrogate.integrate()
```

### 3. Tree-TCI & Vector-Valued Photonic / Hardware Characterization

```python
import maestro_tci as tci
from maestro_tci import Cleaner

# Wrap noisy physical hardware measurements with outlier rejection
cleaner = Cleaner(strategy="outlier_rejection", n_samples=10, sigma=2.0)

# Build a Tree Tensor Network surrogate for an 8-channel, 4-output port device
surrogate = tci.approximate(
    f=measure_photodetectors,  # returns (batch, 4) port intensities
    dimensions=8,  # 8 control channels
    domain=[(0.0, 150.0)] * 8,  # drive power in mW
    algorithm="tree_tci",  # Tree Tensor Network (TTN) topology
    tensor_shape=(4,),  # 4-mode vector output
    tolerance=1e-3,
    cleaner=cleaner,
)

# Predict full 4-port intensity vector instantly
predicted_ports = surrogate(120.0, 45.0, 80.0, 110.0, 35.0, 90.0, 15.0, 60.0)
```

### 4. Quantics TCI (QTCI) for Fine Discretization

```python
# Discretize continuous domain into 2^20 (1,048,576) grid points per dimension
result = tci.integrate(
    f=multiscale_function,
    dimensions=3,
    domain=(0.0, 1.0),
    quantics=True,
    bits_per_dim=20,  # 2^20 resolution
    tolerance=1e-6,
)
```

---

## API Reference

### `tci.integrate(f, dimensions, domain=(0, 1), ...)`
Computes a definite integral using TCI active sampling.

### `tci.approximate(f, dimensions, domain=(0, 1), ...)`
Constructs a continuous `Surrogate` object.

### Key Parameters

| Parameter | Default | Description |
| :--- | :--- | :--- |
| `f` | *(required)* | Target function accepting `(batch, d)` NumPy array. |
| `dimensions` | *(required)* | Number of input variables ($d$). |
| `domain` | `(0.0, 1.0)` | Bounds: single `(lo, hi)` tuple or list of per-dimension tuples. |
| `nodes_per_dim` | `15` | Quadrature nodes per dimension (standard TCI). |
| `quadrature` | `"gauss_legendre"` | Rule: `"gauss_legendre"`, `"gauss_hermite"`, `"clenshaw_curtis"`. |
| `algorithm` | `"auto"` | Algorithm: `"auto"`, `"tci1"` (1-site), `"tci2"` (2-site SVD), `"tree_tci"` (Tree Tensor Network). |
| `tensor_shape` | `None` | Output target shape for multi-output / vector functions (e.g. `(4,)`). |
| `quantics` | `False` | Enable Quantics TCI (binary bit discretization). |
| `bits_per_dim` | `20` | Bit depth per dimension when `quantics=True` ($2^L$ grid nodes). |
| `cleaner` | `None` | Optional `Cleaner` wrapper for denoising hardware measurements. |
| `tolerance` | `1e-6` | Convergence tolerance on sweep-to-sweep error. |
| `max_rank` | `50` | Maximum tensor rank allowed. |
| `max_sweeps` | `30` | Maximum TCI sweeps. |
| `verbose` | `False` | Print per-sweep rank and error diagnostics. |

---

## About & Support

**qoro-maestro-tci** is developed by [Qoro Quantum](https://qoroquantum.net).

* **Website**: [qoroquantum.net](https://qoroquantum.net)
* **Support & Licensing**: [team@qoroquantum.de](mailto:team@qoroquantum.de)
