{"id":13929917,"url":"https://github.com/cduck/bloch_sphere","last_synced_at":"2025-06-26T01:37:57.394Z","repository":{"id":52220658,"uuid":"268401134","full_name":"cduck/bloch_sphere","owner":"cduck","description":"Visualization tools for the qubit Bloch sphere","archived":false,"fork":false,"pushed_at":"2023-02-27T05:15:24.000Z","size":113575,"stargazers_count":107,"open_issues_count":0,"forks_count":32,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-02T20:13:37.257Z","etag":null,"topics":["bloch-sphere","quantum-computing","visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cduck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-06-01T01:56:05.000Z","updated_at":"2025-04-26T07:35:04.000Z","dependencies_parsed_at":"2024-01-17T05:25:09.357Z","dependency_job_id":"cafd797e-37ff-40ec-be4e-fdffc82a3ecd","html_url":"https://github.com/cduck/bloch_sphere","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/cduck/bloch_sphere","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cduck%2Fbloch_sphere","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cduck%2Fbloch_sphere/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cduck%2Fbloch_sphere/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cduck%2Fbloch_sphere/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cduck","download_url":"https://codeload.github.com/cduck/bloch_sphere/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cduck%2Fbloch_sphere/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261983684,"owners_count":23240218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bloch-sphere","quantum-computing","visualization"],"created_at":"2024-08-07T18:02:37.180Z","updated_at":"2025-06-26T01:37:57.017Z","avatar_url":"https://github.com/cduck.png","language":"Python","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"# Qubit Bloch Sphere Visualization\n\nA collection of visualization tools for the qubit Bloch sphere.\nThe Bloch sphere is a useful representation of the state of a single-qubit quantum computer.\n\n![X gate comparison with Hadamard-Z-Hadamard](https://raw.githubusercontent.com/cduck/bloch_sphere/master/examples/hzh_x_compare.gif)\n\n* [Animations for many common gates](https://github.com/cduck/bloch_sphere/blob/master/examples/common_gates.md)\n\nSee also: [Feynman path integral visualization](https://github.com/cduck/feynman_path)\n\n# Install\n\nbloch\\_sphere is available on PyPI:\n\n```bash\npython3 -m pip install bloch_sphere\n```\n\n## Prerequisites\n\nCairo needs to be installed separately to render videos.\nSee platform-specific [instructions for Linux, Windows, and macOS from Cairo](https://www.cairographics.org/download/).\nBelow are some examples for installing Cairo on Linux distributions and macOS.\n\n**Ubuntu**\n\n```bash\nsudo apt-get install libcairo2\n```\n\n**macOS**\n\nUsing [homebrew](https://brew.sh/):\n\n```bash\nbrew install cairo\n```\n\n# Usage\n\nThis package provides a command line tool to generate animations.\nIn your shell, run the following (run `animate_bloch -h` for help).\n```bash\nanimate_bloch hadamard x y s s\n```\n\n```bash\nanimate_bloch2 xy_vs_z x,y z\n```\n\nWith annotations:\n```bash\nanimate_bloch2 xy_vs_z_annotated \\\n    x,y z \\\n    --circuit '\u0026 \\gate{X} \u0026 \\gate{Y} \u0026 \\qw \u0026 \\push{=} \u0026 \u0026 \\gate{Z} \u0026 \\qw' \\\n    --equation '$YX\\ket{\\psi}=Z\\ket{\\psi}$' \\\n    --fps 20 \\\n    --mp4\n```\n\nCustom gates: `custom;\u003cx-axis\u003e;\u003cy-axis\u003e;\u003cz-axis\u003e;\u003cnumber half rotations\u003e;\u003clabel\u003e`\n```bash\nanimate_bloch2 custom_hzy \"custom;0;1;1;1;Hzy\" \"s,h,inv_s\"\n```\n\nAlternate drawing styles:\n```bash\nanimate_bloch ry_gate_arrows --style arrows ry,0.666667 ry,0.666667 ry,0.666667\n```\n\n![Ry(2π/3) gate](https://raw.githubusercontent.com/cduck/bloch_sphere/master/examples/ry_gate_arrows.gif)\n\n# Code Examples\n\n### Visualize a single Bloch sphere\n\n```python\nfrom bloch_sphere.animate_bloch import do_or_save_animation, AnimState\n\n@do_or_save_animation('my_animation', save=False, fps=20, preview=True)\n# Or\n#@do_or_save_animation('my_animation', save='gif', fps=20, preview=True)\n#@do_or_save_animation('my_animation', save='mp4', fps=20, preview=False)\ndef animate(state: AnimState):\n    state.x_gate()\n    state.y_gate()\n    state.s_gate()\n    state.s_gate()\n    ...\n    state.wait()  # Pause at the end\n```\n\n![Example output animation](https://raw.githubusercontent.com/cduck/bloch_sphere/master/examples/xyss_gate.gif)\n\n\n### Compare two sequences of gates\n\n```python\nfrom bloch_sphere.animate_bloch_compare import main\n\nmain('hzh_x', 'h,z,h'.split(','), 'x'.split(','),\n     r'\u0026 \\gate{H} \u0026 \\gate{Z} \u0026 \\gate{H} \u0026 \\qw \u0026 \\push{=} \u0026 \u0026 \\gate{X} \u0026 \\qw',\n     r'$HZH\\ket{\\psi}=X\\ket{\\psi}$',\n     mp4=False,\n     fps=20,\n     preview=True,\n)\n```\n\nOr\n\n```python\nimport drawsvg as draw\nimport latextools\nfrom bloch_sphere.animate_bloch_compare import render_animation\n\n# Add some extra labels\nzero_ket = draw.Group()\nzero_ket.draw(latextools.render_snippet('$\\ket{0}$', latextools.pkg.qcircuit),\n              x=0, y=0, center=True, scale=0.015)\none_ket = draw.Group()\none_ket.draw(latextools.render_snippet('$\\ket{1}$', latextools.pkg.qcircuit),\n             x=0, y=0, center=True, scale=0.015)\nzero_ket_inner = draw.Use(zero_ket, 0, 0, transform='scale(0.75)')\none_ket_inner = draw.Use(one_ket, 0, 0, transform='scale(0.75)')\n\nw = 624*2  # Output width\nfps = 20\ndraw_args = dict(\n    w = w/2,\n    outer_labels=[\n        [(0, 0, 1), (-0.15, 0.13), zero_ket],\n        [(0, 0, -1), (0.15, -0.13), one_ket],\n    ],\n    inner_labels=[\n        [(0, 0, 0.8), (0, 0), zero_ket_inner],\n        [(0, 0, -0.8), (0, 0), one_ket_inner],\n    ],\n)\n\ngates1 = 'h,z,h'.split(',')\ngates2 = 'x'.split(',')\ndef func1(state):\n    state.draw_args = dict(draw_args)\n    state.draw_args['inner_labels'] = []\n    state.sphere_fade_in()\n    state.apply_gate_list(gates1, final_wait=False)\n    state.wait()\n    for _ in gates2:\n        state.i_gate()\n    state.wait()\n    state.wait()\n    state.sphere_fade_out()\n    state.wait()\ndef func2(state):\n    state.draw_args = dict(draw_args)\n    state.draw_args['inner_labels'] = []\n    state.sphere_fade_in()\n    for _ in gates1:\n        state.i_gate()\n    state.wait()\n    state.apply_gate_list(gates2, final_wait=False)\n    state.wait()\n    state.wait()\n    state.sphere_fade_out()\n    state.wait()\nrender_animation('hzh_x_compare', func1, func2,\n                 r'\u0026 \\gate{H} \u0026 \\gate{Z} \u0026 \\gate{H} \u0026 \\qw \u0026 \\push{=} \u0026 \u0026 \\gate{X} \u0026 \\qw',\n                 r'$HZH\\ket{\\psi}=X\\ket{\\psi}$',\n                 save='gif',  # False, 'gif', or 'mp4'\n                 fps=fps,\n                 preview=True,\n                 w=w)\n```\n\n![Example output animation](https://raw.githubusercontent.com/cduck/bloch_sphere/master/examples/hzh_x_compare.gif)\n\n### Synthesize any gate as Rz, Rx, Rz\n\nAny single-qubit gate can be decomposed into a series of three rotations about fixed axes, most commonly as rotations about Z, X, and Z.\nSee [the example code](https://github.com/cduck/bloch_sphere/blob/master/examples/synthesize_from_rz_rx_rz.py) that generated the below animation.\n\n![Example output animation](https://raw.githubusercontent.com/cduck/bloch_sphere/master/examples/random_as_zxz.gif)\n\n### Synthesize any gate as Rz, Rx(π/2), Rz, Rx(π/2), Rz\n\nAny single-qubit gate can also be decomposed into a series of three Z rotations with fixed X rotations of π/2 (1/4 turn) in between.\nSee [the example code](https://github.com/cduck/bloch_sphere/blob/master/examples/synthesize_from_rz_rx_rz.py) that generated the below animation.\n\n![Example output animation](https://raw.githubusercontent.com/cduck/bloch_sphere/master/examples/random_as_zxzxz.gif)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcduck%2Fbloch_sphere","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcduck%2Fbloch_sphere","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcduck%2Fbloch_sphere/lists"}