{"id":22668641,"url":"https://github.com/lanl/nchoosek","last_synced_at":"2025-04-12T11:08:57.011Z","repository":{"id":40661414,"uuid":"383579370","full_name":"lanl/NchooseK","owner":"lanl","description":"Portable programming across classical and quantum architectures","archived":false,"fork":false,"pushed_at":"2023-07-13T16:54:16.000Z","size":1193,"stargazers_count":5,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-02-15T12:35:20.100Z","etag":null,"topics":["programming-model","quantum-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-06T19:34:22.000Z","updated_at":"2023-06-22T13:28:25.000Z","dependencies_parsed_at":"2023-01-31T17:31:02.918Z","dependency_job_id":null,"html_url":"https://github.com/lanl/NchooseK","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FNchooseK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FNchooseK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FNchooseK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FNchooseK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/NchooseK/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228911888,"owners_count":17990774,"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":["programming-model","quantum-computing"],"created_at":"2024-12-09T15:16:05.742Z","updated_at":"2024-12-09T15:16:06.488Z","avatar_url":"https://github.com/lanl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"NchooseK\n========\n\nNchooseK is an experiment in providing portable programming across classical computers, quantum annealers, and circuit-model quantum computers.  Its initial implementation is as an embedded domain-specific language—a Python module that provides a set of basic programming primitives, which the programmer combines using ordinary Python code.\n\nKey concept\n-----------\n\nNchooseK is based on a single primitive, `nck`, which establishes a constraint, \"*k* of these *n* Boolean values must be True\".  For example, `nck([A, B, C], {1})` dictates that exactly one of variables *A*, *B*, and *C* must be True and the rest must be False.  *k* can be a set containing multiple values: `nck([A, B, C], {0, 3})` dictates that either all three of *A*, *B*, and *C* are False or all three are True.\n\nVariables can appear multiple times in the first argument.  All instances of a variable will receive the same True/False value.  As an example, `nck([A, B, B], {2})` has a single solution: *A* = False and *B* = True.  Any other assignment of True and False would result in 0, 1, or 3 of [*A*, *B*, *B*] being True.\n\nA program can—and typically does—specify multiple `nck` constraints.  `nck([A, B, C], {1}); nck([B, C, D], {1}); nck([C, D, E], {1})` dictates that exactly one of {*A*, *B*, *C*}, exactly one of [*B*, *C*, *D*], and exactly one of [*C*, *D*, *E*] must be True.  Hence, one possible solution sets *A* and *E* True and the rest of the variables False; another possible solution sets only *C* True and the rest False.\n\nConstraints can be either \"hard\" (the default) or \"soft\".  Hard constraints must be satisfied for a solution to be valid.  Soft constraints will be satisfied if possible but can be violated if necessary.  Indicate a soft constraint by appending a `soft=True` argument to an `nck` constraint.\n\nThat's it!  NchooseK may seem simplistic, but our hypothesis is that it is sufficiently general as to express a wide variety of computational problems yet sufficiently simple as to facilitate implementation across highly disparate computational platforms.\n\nInstallation\n------------\n\n```bash\npip install --use-feature=in-tree-build .\n```\n\nDocumentation\n-------------\n\nDocumentation is forthcoming.  For the time being, please refer to the examples in the [examples](examples) subdirectory.  The main idea is to instantiate an `nchoosek.Environment`, which is basically a name space.  The environment's `register_port` method defines a variable, and the environment's `nck` method establishes a constraint given a list of ports and a set of allowable numbers of True ports.\n\nDifferent solvers eventually will be supported.  Currently, only three exist: `z3`, which uses Microsoft Research's classical [Z3 Theorem Prover](https://github.com/Z3Prover/z3), `ocean`, which uses D-Wave's [Ocean](https://ocean.dwavesys.com/) to run either classically or on a quantum computer, and `qiskit`, which uses IBM's [Qiskit](https://www.qiskit.org/) to run either classically or on a quantum computer.  Specify one of those in your `NCHOOSEK_SOLVER` environment variable or as the optional `solver` argument to the environment's `solve` method (default: `z3`).  Invoke the `solve` method on the environment to solve for the value of every variable in the environment.  `solve` accepts solver-specific parameters, which also can be provided via the `NCHOOSEK_PARAMS` environment variable.\n\nAs a convenience, the environment's `new_type` method defines a reusable constraint that can be applied to different sets of inputs.\n\nPeer-reviewed publications\n--------------------------\n\nEllis Wilson, Frank Mueller and Scott Pakin, \"Combining Hard and Soft Constraints in Quantum Constraint-Satisfaction Systems,\" in SC22: International Conference for High Performance Computing, Networking, Storage, and Analysis. Dallas, Texas, USA, Nov. 2022, pp. 161–174. URL: https://www.computer.org/csdl/proceedings-article/sc/2022/544400a161/1I0bSO944Eg.\n\nEllis Wilson, Frank Mueller and Scott Pakin, \"Mapping Constraint Problems onto Quantum Gate and Annealing Devices,\" 2021 IEEE/ACM Second International Workshop on Quantum Computing Software (QCS), St. Louis, Missouri, USA, Nov. 2021, pp. 110–117, DOI: [10.1109/QCS54837.2021.00016](https://doi.org/10.1109/QCS54837.2021.00016).\n\nHarsh Khetawat, Ashlesha Atrey, George Li, Frank Mueller, and Scott Pakin, \"Implementing NChooseK on IBM Q Quantum Computer Systems\". In: Michael Kirkedal Thomsen and Mathias Soeken (eds.), Proceedings of the 11th International Conference on Reversible Computation (RC 2019), Lausanne, Switzerland. Lecture Notes in Computer Science, vol. 11497. Springer, Cham.  DOI: [10.1007/978-3-030-21500-2_13](https://doi.org/10.1007/978-3-030-21500-2_13).\n\nLegal statement\n---------------\n\nCopyright © 2021 Triad National Security, LLC.\nAll rights reserved.\n\nThis program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S.  Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.\n\nThis program is open source under the [BSD-3 License](LICENSE.md).  Its LANL-internal identifier is C21038.\n\nContact\n-------\n\nScott Pakin, *pakin@lanl.gov*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fnchoosek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fnchoosek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fnchoosek/lists"}