Metadata-Version: 2.4
Name: landscape-tools
Version: 0.0.4
Summary: Internal tools for landscape characterization
Project-URL: Homepage, https://github.com/ColibrITD-SAS/landscape_tools
Project-URL: Documentation, https://landscape-tools.colibri-quantum.com
Project-URL: Issues, https://github.com/ColibrITD-SAS/landscape_tools/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: tqdm
Requires-Dist: gudhi
Requires-Dist: setuptools_scm
Dynamic: license-file

# Landscape Tools

## Installation

```bash
pip install landscape_tools
```

```python
from landscape_tools import landscape_visualization as lv
from landscape_tools import barren_plateaus as bp
```

## Landscape Characterization

This module provides utilities to analyze and visualize the optimization
landscape of variational quantum algorithms (VQAs).

It is designed to work **independently of QUICK / HDES internals** and can be
used with any backend, as long as a suitable cost function is provided.

The main purpose of this module is to:

- perform 1D and 2D loss landscape scans,
- analyze loss landscapes in PCA subspaces,
- study gradient magnitudes and barren plateau effects,
- visualize trajectories and parameter influence.

Most algorithms implemented here only depend on a
**generic cost function interface**, not on circuits, observables, or backends.

All landscape analysis functions expect a cost function of the form:

```python
f(theta: np.ndarray) -> float
```

In practice, you must wrap the original cost function so that it only
takes the parameter vector as input and returns a scalar value.

```python
def your_cost_function(params, circuit, hamiltonian):
    state = circuit.run(params)
    return expectation_value(state, hamiltonian)

wrapped_loss = lambda p: cost_function(
    p,
    circuit=my_circuit,
    hamiltonian=my_hamiltonian,
)
```
