{"id":26306786,"url":"https://github.com/zapatacomputing/orqviz","last_synced_at":"2025-03-15T10:01:38.453Z","repository":{"id":38326565,"uuid":"413763217","full_name":"zapata-engineering/orqviz","owner":"zapata-engineering","description":"Python package for visualizing the loss landscape of parameterized quantum algorithms. ","archived":false,"fork":false,"pushed_at":"2023-12-18T15:54:18.000Z","size":6771,"stargazers_count":87,"open_issues_count":2,"forks_count":21,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-09T03:01:46.381Z","etag":null,"topics":["product-development"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zapata-engineering.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-10-05T10:03:13.000Z","updated_at":"2024-12-18T14:17:44.000Z","dependencies_parsed_at":"2024-01-15T02:28:44.182Z","dependency_job_id":null,"html_url":"https://github.com/zapata-engineering/orqviz","commit_stats":{"total_commits":87,"total_committers":9,"mean_commits":9.666666666666666,"dds":0.6436781609195402,"last_synced_commit":"ca26e714912930220c01af85020a325630c427fd"},"previous_names":["zapatacomputing/orqviz"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zapata-engineering%2Forqviz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zapata-engineering%2Forqviz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zapata-engineering%2Forqviz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zapata-engineering%2Forqviz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zapata-engineering","download_url":"https://codeload.github.com/zapata-engineering/orqviz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243713398,"owners_count":20335567,"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":["product-development"],"created_at":"2025-03-15T10:01:14.610Z","updated_at":"2025-03-15T10:01:38.221Z","avatar_url":"https://github.com/zapata-engineering.png","language":"Python","funding_links":[],"categories":["Quantum Software Packages","Quantum tools"],"sub_categories":[],"readme":"![Image](docs/orqviz_logo.png)\n\n# orqviz\n\nA Python package for easily **visualizing the loss landscape** of Variational Quantum Algorithms by [Zapata Computing Inc](https://www.zapatacomputing.com/).\n\n`orqviz` provides a collection of tools which quantum researchers and enthusiasts alike can use for their simulations. It works with any framework for running quantum circuits, for example `qiskit`, `cirq`, `pennylane`, and `Orquestra`. The package contains functions to generate data, as well as a range of flexible plotting and helper functions. `orqviz` is light-weight and has very few dependencies.\n\n## Getting started\n\nIn [doc/examples/](https://github.com/zapatacomputing/orqviz/tree/main/docs/examples) we provide a range of `Jupyter notebook` examples for `orqviz`. We have four Jupyter notebooks with tutorials for how to get started with any quantum circuit simulation framework you might use. You will find examples with `qiskit`, `cirq`, `pennylane` and Zapata's `Orquestra` library. The tutorials are not exhaustive, but they do provide a full story that you can follow along.\n\nIn [this notebook](https://github.com/zapatacomputing/orqviz/blob/main/docs/examples/sombrero.ipynb) we have the _Sombrero_ example that we showcase in our paper. We also have an [advanced example notebook](https://github.com/zapatacomputing/orqviz/blob/main/docs/examples/advanced_example_notebook.ipynb) which provides a thorough demonstration of the flexibility of the `orqviz` package.\n\nWe recently published a paper on arXiv where we review the tools available with `orqviz`:\\\n[ORQVIZ: Visualizing High-Dimensional Landscapes in Variational Quantum Algorithms](https://arxiv.org/abs/2111.04695)\n\nFind a brief overview of the visualization techniques on [YouTube](https://www.youtube.com/watch?v=_3x4NI6PcH4)!\n\n## Installation\n\nYou can install our package using the following command:\n\n```bash\npip install orqviz\n```\n\nAlternatively you can build the package from source. This is especially helpful if you would like to contribute to `orqviz`\n\n```bash\ngit clone https://github.com/zapatacomputing/orqviz.git\ncd orqviz\npip install -e ./\n```\n\n## Examples\n\n```python\nimport orqviz\nimport numpy as np\n\nnp.random.seed(42)\n\ndef loss_function(pars):\n    return np.sum(np.cos(pars))**2 + np.sum(np.sin(30*pars))**2\n\nn_params = 42\nparams = np.random.uniform(-np.pi, np.pi, size=n_params)\ndir1 = orqviz.geometric.get_random_normal_vector(n_params)\ndir2 = orqviz.geometric.get_random_orthonormal_vector(dir1)\n\nscan2D_result = orqviz.scans.perform_2D_scan(params, loss_function,\n                                direction_x=dir1, direction_y=dir2,\n                                n_steps_x=100)\norqviz.scans.plot_2D_scan_result(scan2D_result)\n```\n\nThis code results in the following plot:\n\n![Image](docs/example_plot.png)\n\n## FAQ\n\n**What are the expected type and shape for the parameters?**\\\nParameters should be of type `numpy.ndarray` filled with real numbers. In recent releases, the shape of the parameters can be arbitrary, as long as `numpy` allows it, i.e., you cannot have inconsistent sizes per dimension. Until version `0.1.1`, the parameter array needed to be one-dimensional.\n\n**What is the format of the `loss_function` that most `orqviz` methods expect?**\\\nWe define a `loss_function` as a function which receives only the parameters of the model and returns a floating point/ real number. That value could for example be the cost function of an optimization problem, the prediction of a classifier, or the fidelity with respect to a fixed quantum state. All the calculation that needs to be performed to get to these values needs to happen in your function. Check out the above code as a minimal example.\n\n**What can I do if my loss function requires additional arguments?**\\\nIn that case you need to wrap the function into another function such that it again receives only the parameters of the model. We built a wrapper class called `LossFunctionWrapper` that you can import from `orqviz.loss_function`. It is a thin wrapper with helpful perks such as measuring the average evaluation time of a single loss function call, and the total number of calls.\n\n## Authors\n\nThe leading developer of this package is Manuel Rudolph at Zapata Computing.\\\nFor questions related to the visualization techniques, contact Manuel via manuel.rudolph@zapatacomputing.com .\n\nThe leading software developer of this package is Michał Stęchły at Zapata Computing.\\\nFor questions related to technicalities of the package, contact Michał via michal.stechly@zapatacomputing.com .\n\nThank you to Sukin Sim and Luis Serrano from Zapata Computing for their contributions to the tutorials.\n\nYou can also contact us or ask general questions using [GitHub Discussions](https://github.com/zapatacomputing/orqviz/discussions).\n\nFor more specific code issues, bug fixes, etc. please open a [GitHub issue](https://github.com/zapatacomputing/orqviz/issues) in the `orqviz` repository.\n\nIf you are doing research using `orqviz`, please cite [our `orqviz` paper](https://arxiv.org/abs/2111.04695):\n\n\u003e Manuel S. Rudolph, Sukin Sim, Asad Raza, Michał Stęchły, Jarrod R. McClean, Eric R. Anschuetz, Luis Serrano, and Alejandro Perdomo-Ortiz. ORQVIZ: Visualizing High-Dimensional Landscapes in Variational Quantum Algorithms. 2021. arXiv:2111.04695\n\n## How to contribute\n\nPlease see our [Contribution Guidelines](docs/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzapatacomputing%2Forqviz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzapatacomputing%2Forqviz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzapatacomputing%2Forqviz/lists"}