qxmt 0.0.0__tar.gz

qxmt-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 kenya-sk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qxmt-0.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.1
+Name: qxmt
+Version: 0.0.0
+Summary: QXMT is a experiment management tool for quantum computing and quantum machine learning.
+Home-page: https://github.com/kenya-sk/qxmt
+License: MIT
+Author: kenya-sk
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: llm
+Requires-Dist: dill (>=0.3.8,<0.4.0)
+Requires-Dist: matplotlib (>=3.9.1,<4.0.0)
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: pennylane (>=0.37.0,<0.38.0)
+Requires-Dist: pydantic (>=2.8.2,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: scikit-learn (>=1.5.1,<2.0.0)
+Requires-Dist: torch (>=2.4.0,<3.0.0) ; extra == "llm"
+Requires-Dist: transformers (>=4.44.2,<5.0.0) ; extra == "llm"
+Project-URL: Repository, https://github.com/kenya-sk/qxmt
+Description-Content-Type: text/markdown
+
+# QXMT: Quantum Experiment Management Tool
+![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)
+[![Run unit tests with LLM](https://github.com/kenya-sk/qxmt/actions/workflows/unit_tests_llm.yaml/badge.svg)](https://github.com/kenya-sk/qxmt/actions/workflows/unit_tests_llm.yaml)
+[![Docs](https://img.shields.io/badge/docs-online-brightgreen)](https://kenya-sk.github.io/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 = artufact.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
+-->
+

qxmt-0.0.0/README.md

@@ -0,0 +1,123 @@
+# QXMT: Quantum Experiment Management Tool
+![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)
+[![Run unit tests with LLM](https://github.com/kenya-sk/qxmt/actions/workflows/unit_tests_llm.yaml/badge.svg)](https://github.com/kenya-sk/qxmt/actions/workflows/unit_tests_llm.yaml)
+[![Docs](https://img.shields.io/badge/docs-online-brightgreen)](https://kenya-sk.github.io/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 = artufact.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
+-->

qxmt-0.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[tool.poetry]
+name = "qxmt"
+version = "0.0.0"  # using poetry-dynamic-versioning
+description = "QXMT is a experiment management tool for quantum computing and quantum machine learning."
+authors = ["kenya-sk"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/kenya-sk/qxmt"
+packages = [
+    { include = "qxmt" }
+]
+
+[tool.poetry-dynamic-versioning]
+enable = true
+style = "pep440"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pydantic = "^2.8.2"
+pandas = "^2.2.2"
+scikit-learn = "^1.5.1"
+matplotlib = "^3.9.1"
+pennylane = "^0.37.0"
+dill = "^0.3.8"
+pyyaml = "^6.0.2"
+torch = {version = "^2.4.0", optional = true}
+transformers = {version = "^4.44.2", optional = true}
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.2.2"
+pytest-cov = "^5.0.0"
+black = "^24.4.2"
+isort = "^5.13.2"
+mypy = "^1.10.1"
+flake8 = "^7.1.0"
+ipykernel = "^6.29.5"
+pytest-mock = "^3.14.0"
+
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "^8.0.2"
+sphinx-book-theme = "^1.1.3"
+
+[tool.poetry.extras]
+llm = ["torch", "transformers"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

qxmt-0.0.0/qxmt/__init__.py

@@ -0,0 +1,45 @@
+from qxmt.configs import (
+    DatasetConfig,
+    DeviceConfig,
+    EvaluationConfig,
+    ExperimentConfig,
+    FeatureMapConfig,
+    KernelConfig,
+    ModelConfig,
+    PathConfig,
+)
+from qxmt.exceptions import (
+    ExperimentNotInitializedError,
+    ExperimentRunSettingError,
+    InputShapeError,
+    InvalidFileExtensionError,
+    InvalidModelNameError,
+    InvalidPlatformError,
+    InvalidQunatumDeviceError,
+    JsonEncodingError,
+    ModelSettingError,
+    ReproductionError,
+)
+from qxmt.experiment.experiment import Experiment
+
+__all__ = [
+    "ExperimentNotInitializedError",
+    "ExperimentRunSettingError",
+    "InputShapeError",
+    "InvalidFileExtensionError",
+    "InvalidModelNameError",
+    "InvalidPlatformError",
+    "InvalidQunatumDeviceError",
+    "JsonEncodingError",
+    "ModelSettingError",
+    "ReproductionError",
+    "Experiment",
+    "ExperimentConfig",
+    "DatasetConfig",
+    "DeviceConfig",
+    "EvaluationConfig",
+    "FeatureMapConfig",
+    "KernelConfig",
+    "ModelConfig",
+    "PathConfig",
+]

qxmt-0.0.0/qxmt/configs.py

@@ -0,0 +1,70 @@
+from pathlib import Path
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from qxmt.constants import MODULE_HOME
+
+
+class PathConfig(BaseModel):
+    data: Path | str
+    label: Path | str
+
+    def model_post_init(self, __context: dict[str, Any]) -> None:
+        if not Path(self.data).is_absolute():
+            self.data = MODULE_HOME / self.data
+
+        if not Path(self.label).is_absolute():
+            self.label = MODULE_HOME / self.label
+
+
+class DatasetConfig(BaseModel):
+    type: Literal["file", "generate"]
+    path: PathConfig
+    random_seed: int
+    test_size: float = Field(ge=0.0, le=1.0)
+    features: Optional[list[str]] = None
+    raw_preprocess_logic: Optional[dict[str, Any]] = None
+    transform_logic: Optional[dict[str, Any]] = None
+
+
+class DeviceConfig(BaseModel):
+    platform: str
+    name: str
+    n_qubits: int
+    shots: Optional[int] = None
+
+
+class FeatureMapConfig(BaseModel):
+    module_name: str
+    implement_name: str
+    params: Optional[dict[str, Any]] = None
+
+
+class KernelConfig(BaseModel):
+    module_name: str
+    implement_name: str
+    params: Optional[dict[str, Any]] = None
+
+
+class ModelConfig(BaseModel):
+    name: str
+    file_name: str
+    params: dict[str, Any]
+    feature_map: Optional[FeatureMapConfig] = None
+    kernel: Optional[KernelConfig] = None
+
+
+class EvaluationConfig(BaseModel):
+    default_metrics: list[str]
+
+
+class ExperimentConfig(BaseModel):
+    path: Path | str = ""
+    description: str = ""
+    dataset: DatasetConfig
+    device: DeviceConfig
+    feature_map: Optional[FeatureMapConfig] = None
+    kernel: Optional[KernelConfig] = None
+    model: ModelConfig
+    evaluation: EvaluationConfig

qxmt-0.0.0/qxmt/constants.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+from typing import Any
+
+import pennylane as qml
+import pytz
+
+MODULE_HOME: Path = Path(__file__).resolve().parents[1]
+MODULE_SRC: Path = Path(__file__).resolve().parents[0]
+
+DEFAULT_N_JOBS = 3
+
+DEFAULT_EXP_DIRC: Path = MODULE_HOME / "experiments"
+DEFAULT_EXP_DB_FILE: Path = Path("experiment.json")
+
+SUPPORTED_PLATFORMS: list[str] = ["pennylane"]
+PENNYLANE_DEVICES: tuple[Any, ...] = (qml.devices.Device, qml.Device, qml.QubitDevice)
+
+DEFAULT_MODEL_NAME: str = "model.pkl"
+
+DEFAULT_METRICS_NAME: list[str] = ["accuracy", "precision", "recall", "f1_score"]
+
+LLM_MODEL_PATH = "microsoft/Phi-3-mini-128k-instruct"
+
+TZ: pytz.BaseTzInfo = pytz.timezone("Asia/Tokyo")

qxmt-0.0.0/qxmt/datasets/__init__.py

@@ -0,0 +1,7 @@
+from qxmt.datasets.builder import DatasetBuilder
+from qxmt.datasets.schema import Dataset
+
+__all__ = [
+    "DatasetBuilder",
+    "Dataset",
+]