Merge pull request #35 from Jij-Inc/update/datasets

Update Dataset and Docs

Author: ksk-jij

docs/en/_toc.yml

@@ -17,19 +17,18 @@ parts:
     chapters:
     - file: tutorial/usage/index_usage
       sections:
-        - file: tutorial/usage/basic_usage
-        - file: tutorial/usage/dataset_overview
+        - file: tutorial/usage/qoblib
 
   - caption: Examples
     chapters:
     - file: tutorial/examples/index_examples
       sections:
-        - file: tutorial/examples/labs_example
+        - file: tutorial/examples/qoblib_scip
 
   - caption: API Reference
     chapters:
     - file: autoapi/index
 
-  # - caption: "Release Notes"
-  #   chapters:
-  #     - file: release_note/index
+  - caption: "Release Notes"
+    chapters:
+      - file: release_note/0.1.0

docs/en/index.ipynb

@@ -19,123 +19,101 @@
     "\n",
     "- **Benchmark Collection**: Quantum optimization datasets converted to OMMX format\n",
     "- **Python API**: Simple interface for accessing benchmark instances\n",
-    "- **GitHub Container Registry**: Distributed storage for easy access\n",
-    "\n",
-    "## Currently Available Datasets\n",
-    "\n",
-    "### From QOBLIB Collection\n",
+    "- **GitHub Container Registry**: Distributed storage for easy access"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4e55c668",
+   "metadata": {},
+   "source": [
+    "## Currently Available Datasets"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fd1418d9",
+   "metadata": {},
+   "source": [
+    "### QOBLIB Collection\n",
     "\n",
     "**Available with instances**:\n",
-    "- **Labs** (`02_labs`) - 99 instances for integer and quadratic unconstrained models\n",
+    "- **Marketsplit** (`01_marketsplit`) - 120 instances per model for binary linear and binary unconstrained models\n",
+    "- **Labs** (`02_labs`) - 99 instances per model for integer and quadratic unconstrained models\n",
+    "- **Birkhoff** (`03_birkhoff`) - 800 instances for integer linear models\n",
+    "- **Steiner** (`04_steiner`) - 31 instances for integer linear models\n",
+    "- **Independent Set** (`07_independentset`) - 42 instances per model for binary linear and binary unconstrained models\n",
+    "- **Network** (`08_network`) - 20 instances for integer LP models\n",
+    "- **Routing** (`09_routing`) - 55 instances for integer linear models\n",
+    "- **Topology** (`10_topology`) - 16 instances per model for flow MIP, Seidel linear, and Seidel quadratic models\n",
     "\n",
     "**Framework defined for future expansion**:\n",
-    "- MarketSplit, Birkhoff, Steiner, Sports, Portfolio, Independent Set, Network, Routing, and Topology categories are implemented but do not contain instances yet\n",
+    "- **Sports** (`05_sports`) - Mixed integer linear sports scheduling problems\n",
+    "- **Portfolio** (`06_portfolio`) - Binary quadratic and quadratic unconstrained portfolio optimization\n",
     "\n",
     "**Note**: You can check current instance availability for any dataset using the `available_instances` property.\n",
     "\n",
-    "### Future Benchmark Sources\n",
+    "#### Attribution\n",
     "\n",
-    "The framework is designed to accommodate additional benchmark collections beyond QOBLIB as they become available.\n",
+    "This project includes data derived from [QOBLIB - Quantum Optimization Benchmarking Library](https://git.zib.de/qopt/qoblib-quantum-optimization-benchmarking-library):\n",
+    "- **Original authors**: Thorsten Koch, David E. Bernal Neira, Ying Chen, Giorgio Cortiana, Daniel J. Egger, Raoul Heese, Narendra N. Hegade, Alejandro Gomez Cadavid, Rhea Huang, Toshinari Itoko, Thomas Kleinert, Pedro Maciel Xavier, Naeimeh Mohseni, Jhon A. Montanez-Barrera, Koji Nakano, Giacomo Nannicini, Corey O'Meara, Justin Pauckert, Manuel Proissl, Anurag Ramesh, Maximilian Schicker, Noriaki Shimada, Mitsuharu Takeori, Victor Valls, David Van Bulck, Stefan Woerner, and Christa Zoufal.\n",
+    "- **License**: CC BY 4.0\n",
     "\n",
-    "## Quick Start\n",
+    "The instance data has been converted to OMMX format with additional modifications as needed.\n",
     "\n",
-    "To get started with OMMX Quantum Benchmarks, see the [Quick Start Guide](quickstart.ipynb) for installation instructions and basic usage examples.\n",
+    "#### Support\n",
     "\n",
-    "## Learn More\n",
+    "For issues with the benchmark datasets or OMMX Quantum Benchmarks library, please file an issue on our [GitHub repository](https://github.com/Jij-Inc/OMMX-OBLIB).\n",
     "\n",
-    "Explore our documentation to learn more about the benchmark collection capabilities:\n",
+    "For questions about the original datasets or problem formulations, refer to the respective source repositories (e.g., [original QOBLIB repository](https://git.zib.de/qopt/qoblib-quantum-optimization-benchmarking-library) for QOBLIB-derived datasets)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a70d1ea6",
+   "metadata": {},
+   "source": [
+    "## Quick Start\n",
     "\n",
-    "- [Quick Start Guide](quickstart.ipynb): Installation and basic usage examples\n",
-    "- [Usage Guide](tutorial/usage/index_usage.ipynb): Detailed information on working with datasets and instances\n",
-    "- [Examples](tutorial/examples/index_examples.ipynb): Practical examples for different problem types\n",
-    "- [API Reference](autoapi/index): Complete documentation of the Python API\n",
+    "To get started with OMMX Quantum Benchmarks, see the [Quick Start Guide](quickstart.ipynb) for installation instructions and basic usage examples.\n",
     "\n",
     "## Installation\n",
     "\n",
-    "Since this package is currently in development and not yet published on PyPI, install directly from the GitHub repository:\n",
+    "Install this package through pip!\n",
     "\n",
     "```bash\n",
-    "# Clone the repository\n",
-    "git clone https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
-    "cd OmmxQuantumBenchmarks\n",
-    "\n",
-    "# Install in development mode with pip\n",
-    "pip install -e .\n",
+    "# Using uv\n",
+    "uv pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
     "\n",
-    "# Or install in development mode with uv\n",
-    "uv pip install -e .\n",
+    "# Using pip\n",
+    "pip install ommx_quantum_benchmarks\n",
     "```\n",
     "\n",
-    "Alternatively, you can install directly from GitHub without cloning:\n",
+    "Or, you can install it from github, which is arguably the latest version:\n",
     "\n",
     "```bash\n",
-    "# Using pip\n",
-    "pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
-    "\n",
     "# Using uv\n",
     "uv pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
-    "```"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "7aeae262",
-   "metadata": {},
-   "source": [
-    "## Basic Usage"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "1c30ac64",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Objective value: 1.0\n",
-      "Feasible: True\n"
-     ]
-    }
-   ],
-   "source": [
-    "from ommx_quantum_benchmarks.qoblib import Labs\n",
     "\n",
-    "# Load a dataset\n",
-    "dataset = Labs()\n",
+    "# Using pip\n",
+    "pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
+    "```\n",
     "\n",
-    "# Get an instance and solution\n",
-    "model_name = \"integer\"\n",
-    "instance_name = \"labs002\"\n",
-    "instance, solution = dataset(model_name, instance_name)\n",
+    "## Learn More\n",
     "\n",
-    "# Evaluate the solution\n",
-    "evaluated_solution = instance.evaluate(solution.state)\n",
-    "print(f\"Objective value: {evaluated_solution.objective}\")\n",
-    "print(f\"Feasible: {evaluated_solution.feasible}\")"
+    "Explore our documentation to learn more about the benchmark collection capabilities:\n",
+    "\n",
+    "- [Quick Start Guide](quickstart.ipynb): Installation and basic usage examples\n",
+    "- [Usage Guide](tutorial/usage/index_usage.ipynb): Detailed information on working with datasets and instances\n",
+    "- [Examples](tutorial/examples/index_examples.ipynb): Practical examples for different problem types\n",
+    "- [API Reference](autoapi/index): Complete documentation of the Python API"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "4237c03a",
+   "id": "2b550407",
    "metadata": {},
-   "source": [
-    "## Attribution\n",
-    "\n",
-    "This project includes data derived from [QOBLIB - Quantum Optimization Benchmarking Library](https://git.zib.de/qopt/qoblib-quantum-optimization-benchmarking-library):\n",
-    "- **Original authors**: Thorsten Koch, David E. Bernal Neira, Ying Chen, Giorgio Cortiana, Daniel J. Egger, Raoul Heese, Narendra N. Hegade, Alejandro Gomez Cadavid, Rhea Huang, Toshinari Itoko, Thomas Kleinert, Pedro Maciel Xavier, Naeimeh Mohseni, Jhon A. Montanez-Barrera, Koji Nakano, Giacomo Nannicini, Corey O'Meara, Justin Pauckert, Manuel Proissl, Anurag Ramesh, Maximilian Schicker, Noriaki Shimada, Mitsuharu Takeori, Victor Valls, David Van Bulck, Stefan Woerner, and Christa Zoufal.\n",
-    "- **License**: CC BY 4.0\n",
-    "\n",
-    "The instance data has been converted to OMMX format with additional modifications as needed.\n",
-    "\n",
-    "## Support\n",
-    "\n",
-    "For issues with the benchmark datasets or OMMX Quantum Benchmarks library, please file an issue on our [GitHub repository](https://github.com/Jij-Inc/OMMX-OBLIB).\n",
-    "\n",
-    "For questions about the original datasets or problem formulations, refer to the respective source repositories (e.g., [original QOBLIB repository](https://git.zib.de/qopt/qoblib-quantum-optimization-benchmarking-library) for QOBLIB-derived datasets)."
-   ]
+   "source": []
   }
  ],
  "metadata": {

docs/en/quickstart.ipynb

@@ -15,28 +15,24 @@
    "source": [
     "## Installation\n",
     "\n",
-    "Since this package is currently in development and not yet published on PyPI, install directly from the GitHub repository:\n",
+    "Install this package through pip!\n",
     "\n",
     "```bash\n",
-    "# Clone the repository\n",
-    "git clone https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
-    "cd OmmxQuantumBenchmarks\n",
-    "\n",
-    "# Install in development mode with pip\n",
-    "pip install -e .\n",
+    "# Using uv\n",
+    "uv pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
     "\n",
-    "# Or install in development mode with uv\n",
-    "uv pip install -e .\n",
+    "# Using pip\n",
+    "pip install ommx_quantum_benchmarks\n",
     "```\n",
     "\n",
-    "Alternatively, you can install directly from GitHub without cloning:\n",
+    "Or, you can install it from github, which is arguably the latest version:\n",
     "\n",
     "```bash\n",
-    "# Using pip\n",
-    "pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
-    "\n",
     "# Using uv\n",
     "uv pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
+    "\n",
+    "# Using pip\n",
+    "pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git\n",
     "```"
    ]
   },

docs/en/references.bib

@@ -17,7 +17,7 @@ @article{ommx
 @misc{qoblib,
   title={QOBLIB: Quantum Optimization Benchmarking Library},
   author={ZIB Quantum Optimization Group},
-  year={2024},
+  year={2025},
   url={https://git.zib.de/qopt/qoblib-quantum-optimization-benchmarking-library},
   note={Original dataset source}
 }

docs/en/release_note/0.1.0.ipynb

@@ -0,0 +1,67 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "8ecdc601",
+   "metadata": {},
+   "source": [
+    "# Release Notes\n",
+    "\n",
+    "## Version 0.1.0\n",
+    "\n",
+    "**Initial Release - QOBLIB Dataset Collection**\n",
+    "\n",
+    "### Overview\n",
+    "This initial release establishes OMMX Quantum Benchmarks as a collection of optimization benchmark datasets in OMMX format. The first collection includes selected datasets from the [QOBLIB (Quantum Optimization Benchmarking Library)](https://git.zib.de/qopt/qoblib-quantum-optimization-benchmarking-library).\n",
+    "\n",
+    "**Scope**: This release focuses on QOBLIB datasets, with framework designed to accommodate additional benchmark sources in future releases.\n",
+    "\n",
+    "### Features\n",
+    "- Python API for accessing quantum optimization benchmark datasets\n",
+    "- OMMX format conversion and standardization\n",
+    "- GitHub Container Registry integration for distributed data access\n",
+    "- Consistent interface across all dataset categories\n",
+    "- Comprehensive documentation with usage guides and examples\n",
+    "- Bilingual documentation (English and Japanese)\n",
+    "\n",
+    "### Documentation\n",
+    "- **Quick Start Guide**: Installation instructions and basic usage examples\n",
+    "- **Usage Guide**: \n",
+    "  - QOBLIB collections and dataset access patterns\n",
+    "- **Examples**: \n",
+    "  - QOBLIB with SCIP solver integration\n",
+    "- **API Reference**: Complete documentation of the Python API\n",
+    "\n",
+    "### Currently Available Data\n",
+    "**From QOBLIB Collection**:\n",
+    "- **Marketsplit** (01): 120 instances per model for binary linear and binary unconstrained formulations\n",
+    "- **Labs** (02): 99 instances per model for integer and quadratic unconstrained formulations\n",
+    "- **Birkhoff** (03): 800 instances with integer linear formulations\n",
+    "- **Steiner** (04): 31 instances with integer linear formulations\n",
+    "- **Independent Set** (07): 42 instances per model for binary linear and binary unconstrained formulations\n",
+    "- **Network** (08): 20 instances for integer LP formulations\n",
+    "- **Routing** (09): 55 instances for integer linear formulations\n",
+    "- **Topology** (10): 16 instances per model for flow MIP, Seidel linear, and Seidel quadratic formulations\n",
+    "\n",
+    "**Framework Defined for Future Expansion**:\n",
+    "- **Sports** (05): Mixed integer linear sports scheduling problems\n",
+    "- **Portfolio** (06): Binary quadratic and quadratic unconstrained portfolio optimization\n",
+    "\n",
+    "### Attribution\n",
+    "All converted data is derived from the original QOBLIB repository created by Thorsten Koch, David E. Bernal Neira, Ying Chen, Giorgio Cortiana, Daniel J. Egger, Raoul Heese, Narendra N. Hegade, Alejandro Gomez Cadavid, Rhea Huang, Toshinari Itoko, Thomas Kleinert, Pedro Maciel Xavier, Naeimeh Mohseni, Jhon A. Montanez-Barrera, Koji Nakano, Giacomo Nannicini, Corey O'Meara, Justin Pauckert, Manuel Proissl, Anurag Ramesh, Maximilian Schicker, Noriaki Shimada, Mitsuharu Takeori, Victor Valls, David Van Bulck, Stefan Woerner, and Christa Zoufal, licensed under CC BY 4.0."
+   ]
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "cell_metadata_filter": "-all",
+   "main_language": "python",
+   "notebook_metadata_filter": "-all"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/en/release_note/index.ipynb

@@ -7,33 +7,10 @@
    "source": [
     "# Examples\n",
     "\n",
-    "This section provides practical examples for working with OMMX Quantum Benchmarks datasets.\n",
+    "This section provides examples to use this package.\n",
+    "**Note**: For now, we have only a part of QOBLIB collections, however, we are planning to add more datasets.\n",
     "\n",
-    "**Note**: All datasets from the QOBLIB collection follow the same API pattern. The examples shown here using Marketsplit apply to other QOBLIB datasets (Labs, Portfolio, Topology, etc.) with only the class name and available instances differing.\n",
-    "\n",
-    "## Representative Example\n",
-    "\n",
-    "- [Labs Example](labs_example.ipynb) - Complete usage example showing all common patterns\n",
-    "\n",
-    "## Common Usage Pattern for QOBLIB Datasets\n",
-    "\n",
-    "All QOBLIB datasets follow this consistent interface:\n",
-    "\n",
-    "```python\n",
-    "from ommx_quantum_benchmarks.qoblib import DatasetName\n",
-    "\n",
-    "# Instantiate any dataset\n",
-    "dataset = DatasetName()\n",
-    "\n",
-    "# Check properties\n",
-    "print(f\"Name: {dataset.name}\")\n",
-    "print(f\"Models: {dataset.model_names}\")\n",
-    "print(f\"Available instances: {dataset.available_instances}\")\n",
-    "\n",
-    "# Load instance and solution (if available)\n",
-    "if dataset.available_instances[model_name]:\n",
-    "    instance, solution = dataset(model_name, instance_name)\n",
-    "```"
+    "- [QOBLIB with SCIP](qoblib_scip.ipynb) - Use SCIP to solve QOBLIB instance data"
    ]
   }
  ],