# Encoder/Decoder
Helper library for encoding classical data into quantum state and vice versa. Primarily built for [Quantum Programming Studio](https://quantum-circuit.com).
## encode_input(input_data_row, input_encoding)
Function returns OpenQASM 2.0 code which prepares quantum state with input data encoded.
**Arguments:**
`input_data_row` dictionary containing single row of data to be encoded into quantum state in a form `{ "column_name": value, ... }`.
Example:
```json
{
"a": 11,
"b": 14
}
```
(in this example, we have two columns: `a` with value `11` and `b` with value `14`).
`input_encoding` dictionary describing encoding scheme and column definitions.
Fields:
- `type` encoding scheme. Currently, only two encoding schemes are implemented:
- `basis` basis encoding
- `custom` custom encoding, which expects you to provide encoding function
- `customFunction.python` used with `custom` encoding. Your custom encoding function, which receives the same arguments as this `encode_input` function and returns OpenQASM 2.0 string.
- `qubitOffset` used by `basis` encoding. For example, if input data requires 8 bits to be encoded and qubitOffset is 3, then data will be encoded into qubits [3..10] (from fourth to eleventh qubit).
- `colDefs` list of column definitions. Column definition is dictionary containing following fields:
- `name` column name string. Must be valid identifier consisting of letters, numbers or underscores and must start with a letter or underscore.
- `structure` string describing structure of a value. Can be one of: `scalar`, `vector` or `matrix`.
- `dimensions` dimension of a vector or matrix. List of integers. Empty if structure is `scalar`, single integer if structure is `vector` (number of elements in a vector) and two integers if structure is `matrix` (number of rows and number of columns in a matrix).
- `type` data type string of a scalar value or data type of the elements of a vector/matrix. Can be `integer` or `float`.
- `min` minimal value. Used by built-in `basis` encoder (or you can use it in your custom encoding function).
- `max` maximal value. Used by built-in `basis` encoder (or you can use it in your custom encoding function).
- `bits` number of (classical) bits. Used by built-in `basis` encoder: floating point numbers and integers whose range defined by min...max is out of range `[0..2**bits]` will be quantized to range `[0..2**bits]`. Or, you can use this field in your custom encoding function as Your Majesty wishes.
**Example for `basis` encoding:**
```python
from quantastica.encoder_decoder import encode_input
input_encoding = {
"type": "basis",
"qubitOffset": 1,
"colDefs": [
{
"name": "a",
"structure": "scalar",
"dimensions": [],
"type": "integer",
"min": 0,
"max": 15,
"bits": 4
},
{
"name": "b",
"structure": "scalar",
"dimensions": [],
"type": "integer",
"min": 0,
"max": 15,
"bits": 4
}
]
}
input_data_row = { "a": 11, "b": 14 }
qasm = encode_data(input_data_row, input_encoding)
```
Example will return following OpenQASM 2.0 string:
```
OPENQASM 2.0;
include "qelib1.inc";
qreg q[9];
x q[1];
x q[2];
x q[4];
x q[6];
x q[7];
x q[8];
```
**Example for `custom` encoding:**
```python
from quantastica.encoder_decoder import encode_input
def custom_encoder(input_data_row, input_encoding):
qasm = ""
qasm += "OPENQASM 2.0;\n"
qasm += "include \"qelib1.inc\";\n"
# ... your code here ..
return qasm
input_encoding = {
"type": "custom",
"customFunction": {
"python": custom_encoder
},
"qubitOffset": 1,
"colDefs": [
{
"name": "a",
"structure": "scalar",
"dimensions": [],
"type": "integer",
"min": 0,
"max": 15,
"bits": 4
},
{
"name": "b",
"structure": "scalar",
"dimensions": [],
"type": "integer",
"min": 0,
"max": 15,
"bits": 4
}
]
}
input_data_row = { "a": 11, "b": 14 }
qasm = encode_data(input_data_row, input_encoding)
```
## decode_output(counts, output_decoding, unpack_values=False)
Function returns output data which is decoded from sampling results of a quantum computer (or simulator).
**Arguments:**
`counts` dictionary in a form `{ "bitstring": occurrences, ... }`. For example: `{ "011010111": 970, "001101001": 30 }`.
`output_decoding` distionary describing encoding scheme and column definitions.
Fields:
- `type` decoding scheme. Currently, only two decoding schemes are implemented:
- `basis` basis decoding
- `custom` custom decoding, which expects you to provide decoding function
- `customFunction.python` used with `custom` decoding. Your custom decoding function, which receives the same arguments as this `decode_output` function and returns data row.
- `qubitOffset` used by `basis` decoding. For example, if output data is 8 bits wide and qubitOffset is 3, then data will be decoded from qubits [3..10] (from fourth to eleventh qubit).
- `colDefs` list of column definitions. Column definition is dictionary containing following fields:
- `name` column name string. Must be valid identifier consisting of letters, numbers or underscores and must start with a letter or underscore.
- `structure` string describing structure of a value. Can be one of: `scalar`, `vector` or `matrix`.
- `dimensions` dimension of a vector or matrix. List of integers. Empty if structure is `scalar`, single integer if structure is `vector` (number of elements in a vector) and two integers if structure is `matrix` (number of rows and number of columns in a matrix).
- `type` data type string of a scalar value or data type of the elements of a vector/matrix. Can be `integer` or `float`.
- `min` minimal value. Used by built-in `basis` decoder (or you can use it in your custom decoding function).
- `max` maximal value. Used by built-in `basis` decoder (or you can use it in your custom decoding function).
- `bits` number of (classical) bits. Used by built-in `basis` decoder: floating point numbers and integers will be dequantized from range `[0..2**bits]` to the range defined by min..max. Or, you can use this field in your custom encoding function as you wish.
`unpack_data` boolean. When this argument is `False` (default), function will return dictionary. For example: `{ "c": 25 }`. If `unpack_data` is `True`, the function will simply return only value (or tuple of values if multiple columns are defined).
**Example for `basis` decoding:**
```python
from quantastica.encoder_decoder import decode_output
output_decoding = {
"type": "basis",
"qubitOffset": 5,
"colDefs": [
{
"name": "c",
"structure": "scalar",
"dimensions": [],
"type": "integer",
"min": 0,
"max": 31,
"bits": 5
}
]
}
counts = { "1100110110": 1024 } # output from quantum computer or simulator
output_data_row = decode_output(counts, output_decoding)
```
Example output:
```python
{ "c": 25 }
```
**Example for `custom` decoding:**
```python
from quantastica.encoder_decoder import decode_output
def custom_decoder(counts, output_decoding):
output_data_row = {}
# ... your code here ...
return output_data_row
output_decoding = {
"type": "custom",
"customFunction": {
"python": custom_decoder
},
"qubitOffset": 5,
"colDefs": [
{
"name": "c",
"structure": "scalar",
"dimensions": [],
"type": "integer",
"min": 0,
"max": 31,
"bits": 5
}
]
}
counts = { "1100110110": 1024 } # output from quantum computer or simulator
output_data_row = decode_output(counts, output_decoding)
```
That's it. Enjoy! :P
Raw data
{
"_id": null,
"home_page": "https://github.com/quantastica/encoder-decoder",
"name": "quantastica-encoder-decoder",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Quantastica",
"author_email": "support@quantastica.com",
"download_url": "https://files.pythonhosted.org/packages/36/90/dd755f21d0e23ccfaae4af76811e5238c21ff27023651fbaa1d798336816/quantastica-encoder-decoder-0.1.1.tar.gz",
"platform": null,
"description": "# Encoder/Decoder\n\nHelper library for encoding classical data into quantum state and vice versa. Primarily built for [Quantum Programming Studio](https://quantum-circuit.com).\n\n\n## encode_input(input_data_row, input_encoding)\n\nFunction returns OpenQASM 2.0 code which prepares quantum state with input data encoded.\n\n**Arguments:**\n\n`input_data_row` dictionary containing single row of data to be encoded into quantum state in a form `{ \"column_name\": value, ... }`.\n\nExample:\n\n```json\n\n{\n \"a\": 11,\n \"b\": 14\n}\n\n```\n\n(in this example, we have two columns: `a` with value `11` and `b` with value `14`).\n\n\n`input_encoding` dictionary describing encoding scheme and column definitions.\n\nFields:\n\n- `type` encoding scheme. Currently, only two encoding schemes are implemented: \n\n - `basis` basis encoding\n\n - `custom` custom encoding, which expects you to provide encoding function\n\n- `customFunction.python` used with `custom` encoding. Your custom encoding function, which receives the same arguments as this `encode_input` function and returns OpenQASM 2.0 string.\n\n- `qubitOffset` used by `basis` encoding. For example, if input data requires 8 bits to be encoded and qubitOffset is 3, then data will be encoded into qubits [3..10] (from fourth to eleventh qubit).\n\n- `colDefs` list of column definitions. Column definition is dictionary containing following fields:\n\n - `name` column name string. Must be valid identifier consisting of letters, numbers or underscores and must start with a letter or underscore.\n\n - `structure` string describing structure of a value. Can be one of: `scalar`, `vector` or `matrix`.\n\n - `dimensions` dimension of a vector or matrix. List of integers. Empty if structure is `scalar`, single integer if structure is `vector` (number of elements in a vector) and two integers if structure is `matrix` (number of rows and number of columns in a matrix).\n\n - `type` data type string of a scalar value or data type of the elements of a vector/matrix. Can be `integer` or `float`.\n\n - `min` minimal value. Used by built-in `basis` encoder (or you can use it in your custom encoding function).\n\n - `max` maximal value. Used by built-in `basis` encoder (or you can use it in your custom encoding function).\n\n - `bits` number of (classical) bits. Used by built-in `basis` encoder: floating point numbers and integers whose range defined by min...max is out of range `[0..2**bits]` will be quantized to range `[0..2**bits]`. Or, you can use this field in your custom encoding function as Your Majesty wishes.\n\n\n**Example for `basis` encoding:**\n\n```python\n\nfrom quantastica.encoder_decoder import encode_input\n\ninput_encoding = {\n \"type\": \"basis\",\n \"qubitOffset\": 1,\n \"colDefs\": [\n {\n \"name\": \"a\",\n \"structure\": \"scalar\",\n \"dimensions\": [],\n \"type\": \"integer\",\n \"min\": 0,\n \"max\": 15,\n \"bits\": 4\n },\n {\n \"name\": \"b\",\n \"structure\": \"scalar\",\n \"dimensions\": [],\n \"type\": \"integer\",\n \"min\": 0,\n \"max\": 15,\n \"bits\": 4\n }\n ]\n}\n\ninput_data_row = { \"a\": 11, \"b\": 14 }\n\nqasm = encode_data(input_data_row, input_encoding)\n\n```\n\n\nExample will return following OpenQASM 2.0 string:\n\n```\n\nOPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[9];\nx q[1];\nx q[2];\nx q[4];\nx q[6];\nx q[7];\nx q[8];\n\n```\n\n\n**Example for `custom` encoding:**\n\n```python\n\nfrom quantastica.encoder_decoder import encode_input\n\ndef custom_encoder(input_data_row, input_encoding):\n qasm = \"\"\n qasm += \"OPENQASM 2.0;\\n\"\n qasm += \"include \\\"qelib1.inc\\\";\\n\"\n\n # ... your code here ..\n\n return qasm\n\n\ninput_encoding = {\n \"type\": \"custom\",\n \"customFunction\": {\n \"python\": custom_encoder\n },\n \"qubitOffset\": 1,\n \"colDefs\": [\n {\n \"name\": \"a\",\n \"structure\": \"scalar\",\n \"dimensions\": [],\n \"type\": \"integer\",\n \"min\": 0,\n \"max\": 15,\n \"bits\": 4\n },\n {\n \"name\": \"b\",\n \"structure\": \"scalar\",\n \"dimensions\": [],\n \"type\": \"integer\",\n \"min\": 0,\n \"max\": 15,\n \"bits\": 4\n }\n ]\n}\n\ninput_data_row = { \"a\": 11, \"b\": 14 }\n\nqasm = encode_data(input_data_row, input_encoding)\n\n```\n\n## decode_output(counts, output_decoding, unpack_values=False)\n\nFunction returns output data which is decoded from sampling results of a quantum computer (or simulator).\n\n**Arguments:**\n\n`counts` dictionary in a form `{ \"bitstring\": occurrences, ... }`. For example: `{ \"011010111\": 970, \"001101001\": 30 }`.\n\n`output_decoding` distionary describing encoding scheme and column definitions.\n\nFields:\n\n- `type` decoding scheme. Currently, only two decoding schemes are implemented: \n\n - `basis` basis decoding\n\n - `custom` custom decoding, which expects you to provide decoding function\n\n- `customFunction.python` used with `custom` decoding. Your custom decoding function, which receives the same arguments as this `decode_output` function and returns data row.\n\n- `qubitOffset` used by `basis` decoding. For example, if output data is 8 bits wide and qubitOffset is 3, then data will be decoded from qubits [3..10] (from fourth to eleventh qubit).\n\n- `colDefs` list of column definitions. Column definition is dictionary containing following fields:\n\n - `name` column name string. Must be valid identifier consisting of letters, numbers or underscores and must start with a letter or underscore.\n\n - `structure` string describing structure of a value. Can be one of: `scalar`, `vector` or `matrix`.\n\n - `dimensions` dimension of a vector or matrix. List of integers. Empty if structure is `scalar`, single integer if structure is `vector` (number of elements in a vector) and two integers if structure is `matrix` (number of rows and number of columns in a matrix).\n\n - `type` data type string of a scalar value or data type of the elements of a vector/matrix. Can be `integer` or `float`.\n\n - `min` minimal value. Used by built-in `basis` decoder (or you can use it in your custom decoding function).\n\n - `max` maximal value. Used by built-in `basis` decoder (or you can use it in your custom decoding function).\n\n - `bits` number of (classical) bits. Used by built-in `basis` decoder: floating point numbers and integers will be dequantized from range `[0..2**bits]` to the range defined by min..max. Or, you can use this field in your custom encoding function as you wish.\n\n`unpack_data` boolean. When this argument is `False` (default), function will return dictionary. For example: `{ \"c\": 25 }`. If `unpack_data` is `True`, the function will simply return only value (or tuple of values if multiple columns are defined).\n\n\n**Example for `basis` decoding:**\n\n```python\n\nfrom quantastica.encoder_decoder import decode_output\n\noutput_decoding = {\n \"type\": \"basis\",\n \"qubitOffset\": 5,\n \"colDefs\": [\n {\n \"name\": \"c\",\n \"structure\": \"scalar\",\n \"dimensions\": [],\n \"type\": \"integer\",\n \"min\": 0,\n \"max\": 31,\n \"bits\": 5\n }\n ]\n}\n\ncounts = { \"1100110110\": 1024 } # output from quantum computer or simulator\n\noutput_data_row = decode_output(counts, output_decoding)\n\n```\n\nExample output:\n\n```python\n\n{ \"c\": 25 }\n\n```\n\n**Example for `custom` decoding:**\n\n```python\n\nfrom quantastica.encoder_decoder import decode_output\n\ndef custom_decoder(counts, output_decoding):\n output_data_row = {}\n\n # ... your code here ...\n \n return output_data_row\n\n\noutput_decoding = {\n \"type\": \"custom\",\n \"customFunction\": {\n \"python\": custom_decoder\n },\n \"qubitOffset\": 5,\n \"colDefs\": [\n {\n \"name\": \"c\",\n \"structure\": \"scalar\",\n \"dimensions\": [],\n \"type\": \"integer\",\n \"min\": 0,\n \"max\": 31,\n \"bits\": 5\n }\n ]\n}\n\ncounts = { \"1100110110\": 1024 } # output from quantum computer or simulator\n\noutput_data_row = decode_output(counts, output_decoding)\n\n```\n\n\nThat's it. Enjoy! :P\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Helper library for encoding classical data into quantum state and vice versa",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/quantastica/encoder-decoder"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "05fc357e892fddd833ec7daa0a2669d5bacc0bff80d1e5c0c5cab6af887753f9",
"md5": "1851a06cface4627f3f593341e593c36",
"sha256": "da0391bd9ac52be29c167ca4b348131fb13f7370b66081b7ade221600b393da5"
},
"downloads": -1,
"filename": "quantastica_encoder_decoder-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1851a06cface4627f3f593341e593c36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10529,
"upload_time": "2024-08-03T23:51:43",
"upload_time_iso_8601": "2024-08-03T23:51:43.957818Z",
"url": "https://files.pythonhosted.org/packages/05/fc/357e892fddd833ec7daa0a2669d5bacc0bff80d1e5c0c5cab6af887753f9/quantastica_encoder_decoder-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3690dd755f21d0e23ccfaae4af76811e5238c21ff27023651fbaa1d798336816",
"md5": "215b1c0b4cf5c2d2e73b0342aa813437",
"sha256": "387bad2bdfbd5ffabaa44f4bbd0d964826cdc5e0917c1ba6e867def0ac8860ac"
},
"downloads": -1,
"filename": "quantastica-encoder-decoder-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "215b1c0b4cf5c2d2e73b0342aa813437",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9303,
"upload_time": "2024-08-03T23:51:45",
"upload_time_iso_8601": "2024-08-03T23:51:45.168491Z",
"url": "https://files.pythonhosted.org/packages/36/90/dd755f21d0e23ccfaae4af76811e5238c21ff27023651fbaa1d798336816/quantastica-encoder-decoder-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-03 23:51:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantastica",
"github_project": "encoder-decoder",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "quantastica-encoder-decoder"
}
JSON
