# QXMT: Quantum Experiment Management Tool
![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)
[![unit tests](https://github.com/kenya-sk/qxmt/actions/workflows/unit_tests.yaml/badge.svg)](https://github.com/kenya-sk/qxmt/actions/workflows/unit_tests.yaml)
[![Docs](https://img.shields.io/badge/docs-online-brightgreen)](https://qxmt.vercel.app/)
[![PyPI version](https://img.shields.io/pypi/v/qxmt.svg)](https://pypi.org/project/qxmt/)


QXMT is an open-source experiment management tool for quantum machine learning. The development focus is on low-cost experiment management and ensuring reproducibility. For low-cost management, the goal is to minimize the implementation code required for managing experiments, allowing developers and researchers to focus solely on new experimental implementations. To ensure reproducibility, QXMT manages experimental information as configuration file, enabling not only the original developer but also collaborators to reproduce the same experimental results without investing significant time.

QXMT provides several datasets, machine learning models, and visualization methods to facilitate experiment management. By combining these, users can not only avoid developing the entire workflow themselves but also ensure that many people can evaluate their experiments based on the same standards. These default features will be continuously expanded in future development.

### Limitation
QXMT is newly released, and the available features are still limited. The quantum libraries and devices that have been tested are listed below. For future development plans, please refer to the roadmap. Even in environments not listed below, you can manage experiments by implementing according to the interfaces provided by QXMT. For details on how to implement, please refer to the documentation.


| Quantum Library              | Simulator | Real Machine |
|---------------------|-----------|--------------|
|<p align="center">[pennylane](https://github.com/PennyLaneAI/pennylane)</p>|<p align="center">✅</p>|<p align="center">❌</p>|
|<p align="center">[Qulacs](https://github.com/qulacs/qulacs)</p>           |<p align="center">❌</p>|<p align="center">❌</p>|
|<p align="center">[Qiskit](https://github.com/Qiskit/qiskit)</p>           |<p align="center">❌</p>|<p align="center">❌</p>|
|<p align="center">[Cirq](https://github.com/quantumlib/Cirq)</p>           |<p align="center">❌</p>|<p align="center">❌</p>|


## Installation
<!--
QXMT is tested and supported on 64-bit systems with:
- Python 3.11
- macOS 14.6.1 or later
-->

You can install QXMT with Python's pip package manager:
```bash
pip install qxmt
```

When installing QXMT, you have the option to enable the LLM functionality. By default, it is not installed. By enabling the LLM feature, you can automatically generate experiment summaries based on code differences. If needed, please install it using the following command:
```bash
pip install qxmt[llm]
```

## Tool Overview
QXMT manages experiments in the following folder structure.
```bash
<your_project>
├── data
├── configs
│   ├── config_1.yaml
│   ├──   ⋮
│   └── config_n.yaml
└── experiments
    ├── <your_experiment_1>
    │   ├── experiment.json
    │   ├── run_1
    │   │   └── model.pkl
    │   ├── run_2
    │   ├──   ⋮
    │   └── run_n
    │   ⋮
    └── <your_experiment_n>

```

### Keywords
- **data**: Stores raw data used in experiments
- **configs**: Stores yaml files related to the configuration of the experiment to be each run
- **experiments**: Stores experimental results
    - A folder is automatically created for each name set at the start of the experiment.
    - Each experiment folder consists of experiment.json and a folder to manage each run.


## Getting Started
### 1. Start new experiment
```python
import qxmt

# initialize experiment setting
exp = qxmt.Experiment(
    name="operation_check",  # set your experiment name
    desc="operation check of experiment package",  # set your experiment description
    auto_gen_mode=False,  # if True, each experimental description is automatically generated by LLM
).init()

# run experiment. each experiment defined in config file or instance
# run from config
artifact, result = exp.run(config_source="configs/baseline.yaml")
# run from instance
artifact, result = exp.run(dataset=your_dataset, model=your_model)

# get instance of each experiment artifact
dataset = artifact.dataset
model = artifact.model

# output result
# result table convert to pandas dataframe
exp.runs_to_dataframe()

# visualization (Below are some of the features. See documentation for details.)
model.plot_train_test_kernel_matrix(dataset.X_train, dataset.X_test, n_jobs=5)
```

### 2. Load existing experiment
```python
# load existing experiment from json file
exp = qxmt.Experiment().load_experiment(
    "experiments/operation_check/experiment.json")

# reproduction target run artifact
reproduction_model = exp.reproduce(run_id=1)

# run new experiment
artifact, result = exp.run(config_source="configs/best_params.yaml")

# output result
exp.runs_to_dataframe()
```


<!--
## Documentation
-->

<!--
## Contributing
-->
