From 255a6a904cf7360613cc696a10ac5d163866edc2 Mon Sep 17 00:00:00 2001
From: miha-q <>
Date: Sun, 19 Jan 2025 20:46:30 -0500
Subject: [PATCH] Sun Jan 19 08:46:30 PM EST 2025

---
 LICENSE   |  11 +++++
 README.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 123 insertions(+), 6 deletions(-)
 create mode 100644 LICENSE

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f8f5df7
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,11 @@
+QAnsel License
+
+Copyright (c) 2025 Foleosoft
+
+Permission is hereby granted to any person obtaining a copy of this software and associated documentation files (the "Software"), to use the Software without restriction, including without limitation the rights to use, copy, and distribute the Software, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+2. The Software shall not be modified in any way.
+3. Attribution must be given to the original author(s) in any use of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
index 6163f72..365875b 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,116 @@ acceleration (GPUs) as well as hardware random number generators.
 
 ## Compilation
 
-Please click the `tree` link at the top and click the `src.zip`
-file to download the source code. Compiling simply requires
-running `make` in the directory. You can run `make simple` to
-build the source code without hardware acceleration enabled
-which will allow for it to be easily compiled on lower-end
-devices.
+Please click the `tree` link at the top and navigate to the
+`bin` folder and download the following file to get the source
+code for the simulator.
+
+```
+qansel-source-base.zip
+```
+
+To compile it, navigate to the folder it installed within and
+run the following commands within that folder.
+
+```sh
+mkdir qansel
+mv *qansel-source-base.zip qansel
+cd qansel
+unzip *qansel-source-base.zip
+make
+```
+
+If you are compiling for a device which cannot support
+hardware acceleration, then you can use `make simple` which
+will build the program with those features stripped out.
+
+## Examples
+
+Many example programs that can be executed inside of QAnsel can
+be found by clicking the `tree` link at the top fo the page and
+then navigating to the `examples` folder. Simply click on one of
+the examples in order to see the source code.
+
+## Usage
+
+The QAnsel simulator expects programs to be written in a language
+similar to OpenQASM 2.0. These programs must be piped into QAnsel
+as standard input and the simulation results will be displayed as
+standard output. Below is an example using a here document.
+
+```sh
+$ ./QAnsel <<EOF
+> qreg q[2];
+> creg c[2];
+> h q[0];
+> cx q[0], q[1];
+> measure q[0] -> c[0];
+> measure q[1] -> c[1];
+> sample c;
+> EOF
+00: 50.7%
+01: 0.0%
+10: 0.0%
+11: 49.3%
+```
+
+Please use the `-?` flag to see a help document.
+
+## Special Hardware
+
+To enable a hardware random number generator, the `-r`
+flag must be used. This flag will select the hardware
+random number generator based on an order of precedence.
+The order is as follows.
+
+1. Quantis-PCIe-40M
+2. TrueRNG V3
+3. Secure Key Technology
+
+To enable GPU acceleration, the `-oX` flag has to be
+set replacing `X` with an optimization level equal to
+4 or greater.
+
+It is recommended that you run a simple program with the
+`-v` flag which will produce output stating which hardware
+devices were actually found and enabled.
+
+QAnsel can handle up to 16 qubits, however, qubit counts
+greater than 14 will not fit into most consumer-end GPUs.
+The amount of qubits that can fit is limited by the
+amount of VRAM. The GPU must have at least 8 GB for 14
+qubits, 16 GB for 15 qubits, and 48 GB for 16 qubits.
+
+## API and Web Interface
+
+There is a drag-and-drop interface that runs in the browser
+that can be found by clicking the `tree` button and navigating
+to the `bin` folder and downloading the following file.
+
+```
+qansel-source-www.zip
+```
+
+This web front end expects to connect to an API. The API
+service is handled through FoleoAPI. Please see the FoleoAPI
+project in order to set up this service.
+
+Once FoleoAPI is running, a ServiceInfo record will need to be
+added to the APIService schema. Below is an example of how this
+entry may look.
+
+```sql
+MariaDB [APIService]> select * from ServiceInfo;
++----+---------+---------------------------------+-------------+
+| id | service | path                            | parameters  |
++----+---------+---------------------------------+-------------+
+|  1 | qansel  | /home/server2/QAnsel/bin/QAnsel | -q14 -o5 -r |
++----+---------+---------------------------------+-------------+
+```
+
+The `-qX` parameter is useful here as it allows one to cap 
+the maximum qubit count allowed for the process in case the
+hardware running the simulator is not sufficient to handle large
+qubit counts. In this case, it is capped at 14 to make sure that
+programs that exceed the limitations of the GPU are rejected.
 
-- 
2.39.5