{"id":18565267,"url":"https://github.com/rigetti/gym-forest","last_synced_at":"2025-04-10T04:32:42.310Z","repository":{"id":40979982,"uuid":"203417668","full_name":"rigetti/gym-forest","owner":"rigetti","description":"Reinforcement learning environment for the classical synthesis of quantum programs. ","archived":false,"fork":false,"pushed_at":"2022-12-27T15:35:11.000Z","size":19,"stargazers_count":27,"open_issues_count":2,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2023-03-02T06:10:35.012Z","etag":null,"topics":["combinatorial-optimization","quantum-programs","reinforcement-learning"],"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/rigetti.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}},"created_at":"2019-08-20T16:53:37.000Z","updated_at":"2022-11-13T15:42:43.000Z","dependencies_parsed_at":"2023-01-31T05:30:55.450Z","dependency_job_id":null,"html_url":"https://github.com/rigetti/gym-forest","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Fgym-forest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Fgym-forest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Fgym-forest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Fgym-forest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rigetti","download_url":"https://codeload.github.com/rigetti/gym-forest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223424568,"owners_count":17142791,"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":["combinatorial-optimization","quantum-programs","reinforcement-learning"],"created_at":"2024-11-06T22:18:08.350Z","updated_at":"2024-11-06T22:18:08.568Z","avatar_url":"https://github.com/rigetti.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003eNotice: This is research code that will not necessarily be maintained to\n\u003esupport further releases of Forest and other Rigetti Software. We welcome bug\n\u003ereports and PRs but make no guarantee about fixes or responses.\n\n# gym-forest\n\nGym environment for classical synthesis of quantum programs. For more\ninformation about this, see our paper [\"Automated Quantum Programming via\nReinforcement Learning for Combinatorial\nOptimization\"](https://arxiv.org/abs/1908.08054).\n\n\n## Installation\n\nIn addition to cloning this repository, you will need to download the data\nfiles, which should be unzipped at the toplevel of the `gym-forest` code\ndirectory.\n\n```\ngit clone https://github.com/rigetti/gym-forest.git\ncd gym-forest\ncurl -OL https://github.com/rigetti/gym-forest/releases/download/0.0.1/data.tar.bz2\ntar -xvf data.tar.bz2\npip install -e .\n```\n\n**Note**: If installing on a Rigetti QMI, it is suggested that you install\nwithin a virtual environment. If you choose not to, you may need to instead\ninvoke `pip install -e . --user` in the last step of the above.\n\n## Usage\n\nThis library provides several [OpenAI gym](https://gym.openai.com/) environments\navailable for reinforcement learning tasks. For a very simple example, try the\nfollowing at a python repl:\n\n```\n\u003e\u003e\u003e import gym\n\u003e\u003e\u003e import gym_forest\n\n\u003e\u003e\u003e env = gym.make('forest-train-qvm-v0')\n\u003e\u003e\u003e obs = env.reset()\n\u003e\u003e\u003e print(obs)\n...\n```\n\nThis environment contains problem instances from the combined MaxCut, MaxQP, and\nQUBO training sets. Resetting the environment selects a random problem instance.\n\nActions are represented numerically, but encode a discrete set of gates:\n```\n\u003e\u003e\u003e action = env.action_space.sample()\n\u003e\u003e\u003e env.instrs[action]\n\u003cGate RX(3*pi/2) 9\u003e\n\u003e\u003e\u003e obs, reward, done, info = env.step(action)\n...\n```\n\nFor more information, please take a look at `gym_forest/envs/gym_forest.py` and\ncomments within. In particular, you can get a detailed look at the format of the\nobservation vector in in `ForestDiscreteEnv.observation`.\n\n## Available Environments\n\nWe provide sets of randomly generated combinatorial optimization problems, and\nGym environments for solving these using a quantum resource, either simulated\n(QVM) or real (QPU). The datasets are described in more detail in our paper, but\nwe summarize the environments below:\n\n\n| Environment Name           | Resource | Problem Type        | Split      |\n|----------------------------|----------|---------------------|------------|\n| `'forest-train-qvm-v0'`    | QVM      | Maxcut, MaxQP, QUBO | Training   |\n| `'forest-train-qpu-v0'`    | QPU      | Maxcut, MaxQP, QUBO | Training   |\n| `'forest-maxcut-valid-v0'` | QVM      | Maxcut              | Validation |\n| `'forest-maxqp-valid-v0'`  | QVM      | MaxQP               | Validation |\n| `'forest-qubo-valid-v0'`   | QVM      | QUBO                | Validation |\n| `'forest-maxcut-test-v0'`  | QVM      | Maxcut              | Testing    |\n| `'forest-maxqp-test-v0'`   | QVM      | MaxQP               | Testing    |\n| `'forest-qubo-test-v0'`    | QVM      | QUBO                | Testing    |\n\n## Examples\n\nThe models in our paper were developed using the [stable\nbaselines](https://github.com/hill-a/stable-baselines) library. To use this, you\nmay `pip install -r examples/requirements.txt`.\n\n### Example: Single-episode Rollout\n\nSee the code in `examples/rollout_episode.py` for an example showing the\nbehavior of at \"QVM-trained\" model on a a random maxcut test problem.\n\nNote: This example uses the saved model weights, included in `data.tar.bz2`.\n\n### Example: Training PPO agents.\n\nSee the code in `examples/train.py` for an example of how training can be\nperformed.\n\n## Citation\n\nIf you use this code, please cite:\n\n```\n@article{mckiernan2019automated,\n  title={Automated Quantum Programming via Reinforcement Learning for Combinatorial Optimization},\n  author={McKiernan, K. and Davis, E. and Alam, M. S. and Rigetti, C.},\n  note={arXiv:1908.08054},\n  year={2019}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frigetti%2Fgym-forest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frigetti%2Fgym-forest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frigetti%2Fgym-forest/lists"}