# Chromobius: color code decoder
Chromobius is an implementation of a ["mobius decoder"](https://arxiv.org/abs/2108.11395), which approximates the color code decoding problem as a minimum weight matching problem.
Chromobius uses [PyMatching](https://github.com/oscarhiggott/PyMatching/) to solve the minimum weight matching problem.
See ((((the paper "New circuits and an open source decoder for the color code")))) for more details on how Chromobius works.
## How to use Chromobius
See the [**getting started notebook**](doc/getting_started.ipynb).
Also see the [python api reference](doc/chromobius_api_reference.md).
Programmers who want to edit and build Chromobius can check the [developer documentation](doc/developers.md).
## Example Snippets
### Decoding a shot with Chromobius
From python:
```python
import stim
import chromobius
import numpy as np
def count_mistakes(circuit: stim.Circuit, shots: int) -> int:
# Sample the circuit.
dets, actual_obs_flips = circuit.compile_detector_sampler().sample(
shots=shots,
separate_observables=True,
bit_packed=True,
)
# Decode with Chromobius.
decoder = chromobius.compile_decoder_for_dem(circuit.detector_error_model())
predicted_obs_flips = decoder.predict_obs_flips_from_dets_bit_packed(dets)
# Count mistakes.
return np.count_nonzero(np.any(predicted_obs_flips != actual_obs_flips, axis=1))
```
From the command line:
```bash
# Sample shots of detectors and observable flips.
stim detect \
--shots 100000 \
--in "example_circuit.stim" \
--out "dets.b8" \
--out_format "b8" \
--obs_out "obs_actual.txt" \
--obs_out_format "01"
# Extract a detector error model used to configure Chromobius.
stim analyze_errors \
--in "example_circuit.stim" \
--fold_loops \
--out "dem.dem"
# Decode the shots.
chromobius predict \
--dem "dem.dem" \
--in "dets.b8" \
--in_format "b8" \
--out "obs_predicted.txt" \
--out_format "01"
# Count the number of shots with a prediction mistake.
paste obs_actual.txt obs_predicted.txt \
| grep -Pv "^([01]*)\\s*\\1$" \
| wc -l
```
From python using sinter:
```python
import sinter
import chromobius
import os
tasks: list[sinter.Task] = ...
stats: list[sinter.TaskStats] = sinter.collect(
decoders=["chromobius"],
custom_decoders=chromobius.sinter_decoders(),
tasks=tasks,
num_workers=os.cpu_count(),
max_shots=100_000,
max_errors=100,
)
```
From the command line using sinter:
```bash
sinter collect \
--circuits "example_circuit.stim" \
--decoders chromobius \
--custom_decoders_module_function "chromobius:sinter_decoders" \
--max_shots 100_000 \
--max_errors 100
--processes auto \
--save_resume_filepath "stats.csv" \
```
Raw data
{
"_id": null,
"home_page": "https://github.com/quantumlib/chromobius",
"name": "chromobius",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Craig Gidney",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ab/a1/e10b3af5027163bcfee7351f596025fbeb246def21f843c02596d24f95b8/chromobius-1.1.0.tar.gz",
"platform": null,
"description": "# Chromobius: color code decoder\n\nChromobius is an implementation of a [\"mobius decoder\"](https://arxiv.org/abs/2108.11395), which approximates the color code decoding problem as a minimum weight matching problem.\nChromobius uses [PyMatching](https://github.com/oscarhiggott/PyMatching/) to solve the minimum weight matching problem.\n\nSee ((((the paper \"New circuits and an open source decoder for the color code\")))) for more details on how Chromobius works.\n\n## How to use Chromobius\n\nSee the [**getting started notebook**](doc/getting_started.ipynb).\n\nAlso see the [python api reference](doc/chromobius_api_reference.md).\n\nProgrammers who want to edit and build Chromobius can check the [developer documentation](doc/developers.md).\n\n## Example Snippets\n\n### Decoding a shot with Chromobius\n\nFrom python:\n\n```python\nimport stim\nimport chromobius\nimport numpy as np\n\ndef count_mistakes(circuit: stim.Circuit, shots: int) -> int:\n # Sample the circuit. \n dets, actual_obs_flips = circuit.compile_detector_sampler().sample(\n shots=shots,\n separate_observables=True,\n bit_packed=True,\n )\n\n # Decode with Chromobius.\n decoder = chromobius.compile_decoder_for_dem(circuit.detector_error_model())\n predicted_obs_flips = decoder.predict_obs_flips_from_dets_bit_packed(dets)\n\n # Count mistakes.\n return np.count_nonzero(np.any(predicted_obs_flips != actual_obs_flips, axis=1))\n```\n\nFrom the command line:\n\n```bash\n# Sample shots of detectors and observable flips.\nstim detect \\\n --shots 100000 \\\n --in \"example_circuit.stim\" \\\n --out \"dets.b8\" \\\n --out_format \"b8\" \\\n --obs_out \"obs_actual.txt\" \\\n --obs_out_format \"01\"\n \n# Extract a detector error model used to configure Chromobius.\nstim analyze_errors \\\n --in \"example_circuit.stim\" \\\n --fold_loops \\\n --out \"dem.dem\"\n\n# Decode the shots.\nchromobius predict \\\n --dem \"dem.dem\" \\\n --in \"dets.b8\" \\\n --in_format \"b8\" \\\n --out \"obs_predicted.txt\" \\\n --out_format \"01\"\n\n# Count the number of shots with a prediction mistake.\npaste obs_actual.txt obs_predicted.txt \\\n | grep -Pv \"^([01]*)\\\\s*\\\\1$\" \\\n | wc -l\n```\n\nFrom python using sinter:\n\n```python\nimport sinter\nimport chromobius\nimport os\n\ntasks: list[sinter.Task] = ...\nstats: list[sinter.TaskStats] = sinter.collect(\n decoders=[\"chromobius\"], \n custom_decoders=chromobius.sinter_decoders(),\n tasks=tasks,\n num_workers=os.cpu_count(),\n max_shots=100_000,\n max_errors=100,\n)\n```\n\nFrom the command line using sinter:\n\n```bash\nsinter collect \\\n --circuits \"example_circuit.stim\" \\\n --decoders chromobius \\ \n --custom_decoders_module_function \"chromobius:sinter_decoders\" \\\n --max_shots 100_000 \\\n --max_errors 100\n --processes auto \\\n --save_resume_filepath \"stats.csv\" \\\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A fast implementation of the mobius color code decoder.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/quantumlib/chromobius"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cd395b9a7cd01cc265e918ebac79df684a196e18c09921bf1424ecf7ff4ad17f",
"md5": "7050862a3bb206cdb4f8d1a7c7208e84",
"sha256": "7c1b24ce858bedac9c42b3088b6514dce39adbc739c53ead49d7433345a260c4"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp310-cp310-macosx_10_15_x86_64.whl",
"has_sig": false,
"md5_digest": "7050862a3bb206cdb4f8d1a7c7208e84",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 927706,
"upload_time": "2024-09-24T09:12:48",
"upload_time_iso_8601": "2024-09-24T09:12:48.166384Z",
"url": "https://files.pythonhosted.org/packages/cd/39/5b9a7cd01cc265e918ebac79df684a196e18c09921bf1424ecf7ff4ad17f/chromobius-1.1.0-cp310-cp310-macosx_10_15_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e2139a91d17172da331cc2b031c0517364d3c224d2aa2bfcd57ed1df57fceee",
"md5": "ab430e0d363c60d9a2312b5cd81145ea",
"sha256": "25009231fe0425e6cc45051742abdaca7d012d470b1b813becdaeb08e1671de9"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp310-cp310-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "ab430e0d363c60d9a2312b5cd81145ea",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 865516,
"upload_time": "2024-09-24T09:12:50",
"upload_time_iso_8601": "2024-09-24T09:12:50.909083Z",
"url": "https://files.pythonhosted.org/packages/4e/21/39a91d17172da331cc2b031c0517364d3c224d2aa2bfcd57ed1df57fceee/chromobius-1.1.0-cp310-cp310-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0cae25459673ca074fff4ac082ff0214d1cdb41a310b0319694eededd500585f",
"md5": "173f4cce7947a530bf867ddb8d41c81a",
"sha256": "0d5800d0b7c2d97ea943481ca741a7bd60dcaddc01dc1984aa6e29b1f07ad6c4"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "173f4cce7947a530bf867ddb8d41c81a",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1173541,
"upload_time": "2024-09-24T09:12:52",
"upload_time_iso_8601": "2024-09-24T09:12:52.277937Z",
"url": "https://files.pythonhosted.org/packages/0c/ae/25459673ca074fff4ac082ff0214d1cdb41a310b0319694eededd500585f/chromobius-1.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "846a1e0ed815cebfb195f22ee0f7022e31061739432cedb862e40734019c095d",
"md5": "ba9537588ed9917379267907672270b1",
"sha256": "a789e17a8e2c4ed2c59137f2818a22bd5451993581fca7e7eb9ff52aa92aaf8d"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp311-cp311-macosx_10_15_x86_64.whl",
"has_sig": false,
"md5_digest": "ba9537588ed9917379267907672270b1",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 927798,
"upload_time": "2024-09-24T09:12:54",
"upload_time_iso_8601": "2024-09-24T09:12:54.083531Z",
"url": "https://files.pythonhosted.org/packages/84/6a/1e0ed815cebfb195f22ee0f7022e31061739432cedb862e40734019c095d/chromobius-1.1.0-cp311-cp311-macosx_10_15_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "48f756248b552d741d824059be7eae9f7eabb23e6004e5834f16469897535c99",
"md5": "f748bc47ec260d12e62cabc1202133d2",
"sha256": "02739e862b15ff908c5ac2379cfb2431c277c60c271094713f488143ed55cbbb"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp311-cp311-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "f748bc47ec260d12e62cabc1202133d2",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 865435,
"upload_time": "2024-09-24T09:12:55",
"upload_time_iso_8601": "2024-09-24T09:12:55.374341Z",
"url": "https://files.pythonhosted.org/packages/48/f7/56248b552d741d824059be7eae9f7eabb23e6004e5834f16469897535c99/chromobius-1.1.0-cp311-cp311-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0a5e97785ca9b02a7c577cb2e5aa2d93077aadc06fc39dfc07a67e1882225f56",
"md5": "ae8b7a5acae42e50f81783ef25d950f2",
"sha256": "029898b0e9caf878fc01d64cd08972df180334643f4f6f3263129cb0ba1e1bf9"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "ae8b7a5acae42e50f81783ef25d950f2",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 1173494,
"upload_time": "2024-09-24T09:12:57",
"upload_time_iso_8601": "2024-09-24T09:12:57.514340Z",
"url": "https://files.pythonhosted.org/packages/0a/5e/97785ca9b02a7c577cb2e5aa2d93077aadc06fc39dfc07a67e1882225f56/chromobius-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10bf6258e3e23ebce4f611239330caeaea7370601fd8dbcf7ffa0d1a559ab6fd",
"md5": "af4956f84ebb1d15873b23e2930bd6d7",
"sha256": "9db402694e1ffc813dddb37fddd74c74dc15b68fa1813860f4e2b3b170253995"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp312-cp312-macosx_10_15_x86_64.whl",
"has_sig": false,
"md5_digest": "af4956f84ebb1d15873b23e2930bd6d7",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 928926,
"upload_time": "2024-09-24T09:12:59",
"upload_time_iso_8601": "2024-09-24T09:12:59.228276Z",
"url": "https://files.pythonhosted.org/packages/10/bf/6258e3e23ebce4f611239330caeaea7370601fd8dbcf7ffa0d1a559ab6fd/chromobius-1.1.0-cp312-cp312-macosx_10_15_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d9120f6119e8a9a77244b9be0fb02848b6f08f31d80fe1ebe0b21fe32412115d",
"md5": "d2c240bd66967645c4e245a6fa8a8223",
"sha256": "5f9bc1594100420f43cfa9ee7f904cd931b84a99e999074bcfddc4c797d5ada8"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp312-cp312-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "d2c240bd66967645c4e245a6fa8a8223",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 866319,
"upload_time": "2024-09-24T09:13:01",
"upload_time_iso_8601": "2024-09-24T09:13:01.146707Z",
"url": "https://files.pythonhosted.org/packages/d9/12/0f6119e8a9a77244b9be0fb02848b6f08f31d80fe1ebe0b21fe32412115d/chromobius-1.1.0-cp312-cp312-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a9b543c260d3bcd04a27d87ad197a2d342dcd720614f473f13055787f96c9e09",
"md5": "67399082745edaa27ecb4e425c8d8a50",
"sha256": "58d947cc3a11e072ab36e2f0053d69e41a83231954ea5f38ef1c8c6f5eedd5c2"
},
"downloads": -1,
"filename": "chromobius-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "67399082745edaa27ecb4e425c8d8a50",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 1173263,
"upload_time": "2024-09-24T09:13:02",
"upload_time_iso_8601": "2024-09-24T09:13:02.825964Z",
"url": "https://files.pythonhosted.org/packages/a9/b5/43c260d3bcd04a27d87ad197a2d342dcd720614f473f13055787f96c9e09/chromobius-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aba1e10b3af5027163bcfee7351f596025fbeb246def21f843c02596d24f95b8",
"md5": "661dbeb6957aedb0262bf815ace04f64",
"sha256": "085ebd50bf897df63076e6dfe89cde20afc412260d7462c0415735ee0a8eb338"
},
"downloads": -1,
"filename": "chromobius-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "661dbeb6957aedb0262bf815ace04f64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 55567,
"upload_time": "2024-09-24T09:13:04",
"upload_time_iso_8601": "2024-09-24T09:13:04.704436Z",
"url": "https://files.pythonhosted.org/packages/ab/a1/e10b3af5027163bcfee7351f596025fbeb246def21f843c02596d24f95b8/chromobius-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-24 09:13:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantumlib",
"github_project": "chromobius",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "chromobius"
}
JSON
