Metadata-Version: 2.4
Name: qts2d
Version: 0.1.0
Summary: Quantum-Based Image Encoding of Time Series
Project-URL: Homepage, https://github.com/sokolmarek/qts2d
Project-URL: Repository, https://github.com/sokolmarek/qts2d
Author-email: Marek Sokol <marek.sokol@cvut.cz>
License: Copyright (c) 2025, Marek Sokol and qts2d contributors
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of pyts nor the names of its contributors may be used to
          endorse or promote products derived from this software without specific
          prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE.txt
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: numpy>=2.2.5
Requires-Dist: pyts>=0.13.0
Requires-Dist: qiskit-aer==0.17.0
Requires-Dist: qiskit-machine-learning==0.8.2
Requires-Dist: qiskit==1.4.2
Requires-Dist: scikit-learn>=1.6.1
Description-Content-Type: text/markdown

<p align="center">
  <img width="200" height="200" src="https://i.postimg.cc/9Q6GyVZ2/qts2d-logo.png">
</p>

# QTS2D: Quantum-Based Image Encoding of Time Series

[![PyPI version](https://badge.fury.io/py/qts2d.svg)](https://badge.fury.io/py/qts2d)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/qts2d)](https://pypi.python.org/pypi/qts2d)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/qts2d.svg)](https://img.shields.io/pypi/pyversions/qts2d.svg)
[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

**QTS2D** is a Python library for encoding time series data into image representations using quantum computing principles. These image-based representations can then be used as input for various machine learning models, particularly Convolutional Neural Networks (CNNs), for tasks like time series classification or forecasting.

## Description

The library provides several quantum-inspired transformers that convert 1D time series into 2D matrices (images). These methods are analogous to classical time series imaging techniques but leverage quantum computations or quantum-inspired mathematical formulations.

Currently implemented transformers:

*   **QGAF**: Quantum Gramian Angular Field
*   **QRP**: Quantum Recurrence Plot
*   **QSG**: Quantum Spectrogram
*   **QMTF**: Quantum Markov Transition Field

## Installation

You can install library using pip:

```bash
pip install qts2d
```

or using pip+git for the latest version of the code:

```bash
pip install git+
```

The library requires Python >= 3.10 and the following main dependencies:

*   numpy (>=2.2.5)
*   scikit-learn (>=1.6.1)
*   qiskit (==1.4.2)
*   qiskit-aer (==0.17.0)
*   qiskit-machine-learning (==0.8.2)
*   pyts (>=0.13.0)

## Quick Example

Each transformer follows the scikit-learn `Estimator` and `TransformerMixin` interface.

```python
import numpy as np
from qts2d.encoding import QGAF

# Example time series data (n_samples, n_timestamps)
X = np.random.rand(1, 1000)

# Using Quantum Gramian Angular Field (QGAF)
qgaf = QGAF(image_size=32, method='summation', computation_method='hadamard', scaling='minmax')
X_qgaf = qgaf.fit_transform(X)
print(f"QGAF output shape: {X_qgaf.shape}")
```

For more detailed examples, please refer to the `examples/` directory for each specific transformer. To run the examples Matplotlib is required.

## Contributing
We welcome everyone to contribute to ```qts2d```! The library is still evolving and far from perfect, so your help is especially valuable. Please feel free to submit a pull request or open an issue. Detailed contribution guidelines will be shared soon along with the documentation. Stay tuned!

## Citation
Coming soon!

## License

This project is licensed under the BSD 3-Clause License - see the [LICENSE.txt](LICENSE.txt) file for details.

## References

* [1] Xu, Z., Wang, Y., Feng, X., Wang, Y., Li, Y., & Lin, H.
    Quantum-enhanced forecasting: Leveraging quantum gramian angular field 
    and CNNs for stock return predictions. Finance Research Letters (2024)

* [2] Z. Wang and T. Oates, "Encoding Time Series as Images for Visual
    Inspection and Classification Using Tiled Convolutional Neural
    Networks." AAAI Workshop (2015).

* [3] J.-P Eckmann, S. Oliffson Kamphorst and D Ruelle, "Recurrence
    Plots of Dynamical Systems". Europhysics Letters (1987).