Merge pull request #75 from oqc-community/release/v0.1.6

Release/v0.1.6

README.md

@@ -9,7 +9,7 @@ Some of the key things this approach enables:
 2. Enabling hybrid algorithms to be run on machines and tools with only a gate-level API available. This includes QASM API's if you use its simulation framework.
 3. Lots of optimization potential when passed large amounts of classical context that a quantum algorithm uses to accentuate its own execution.
 
-We also have a [full feature list and quick intro to its concepts](https://github.com/oqc-community/rasqal/blob/develop/features_and_concepts.md) as well as a [draft paper](https://github.com/oqc-community/rasqal/blob/develop/docs/papers/Rasqal%20Draft%20v2.pdf) that covers its internals in excruciating detail.
+We also have a [full feature list and quick intro to its concepts](https://github.com/oqc-community/rasqal/blob/develop/docs/features_and_concepts.md) as well as a [draft paper](https://github.com/oqc-community/rasqal/blob/develop/docs/papers/Rasqal%20Draft%20v2.pdf) that covers its internals in excruciating detail.
 
 If you have any features or ideas you'd like to see implemented feel free to raise a [feature request](https://github.com/oqc-community/Rasqal/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=)!
 
@@ -18,13 +18,13 @@ If you have any features or ideas you'd like to see implemented feel free to rai
 ### Getting Started
 
 1. Install Rasqal in your favourite Python venv by running `pip install rasqal`. Our current testing is done with `v3.10` of Python.
-2. Read the [quick start](https://github.com/oqc-community/rasqal/blob/develop/examples.md) and look at our [Python example](https://github.com/oqc-community/Rasqal/blob/develop/docs/examples.py).
-3. (Optional) Read the [paper](https://github.com/oqc-community/rasqal/blob/develop/docs/papers/Rasqal%20Draft%20v2.pdf) for a deep-dive into Rasqals concepts and data structures.
+2. Read the [quick start](https://github.com/oqc-community/rasqal/blob/develop/docs/quick_start.md) and look at our [examples](https://github.com/oqc-community/Rasqal/blob/develop/examples/examples.py).
+3. (Optional) Read the [paper](https://github.com/oqc-community/rasqal/blob/develop/docs/papers/Rasqal%20Draft%20v3.pdf) for a deep-dive into Rasqals concepts and data structures.
 
 ### Contributing
 
-If you'd like to contribute your first destination will be to [build the system locally](https://github.com/oqc-community/rasqal/blob/develop/building.md).
-There's also a [getting started](https://github.com/oqc-community/rasqal/blob/develop/development.md) page that covers some of the most important bits you'd need to know about the project before jumping into writing code.
+If you'd like to contribute your first destination will be to [build the system locally](https://github.com/oqc-community/rasqal/blob/develop/docs/building.md).
+There's also a [getting started](https://github.com/oqc-community/rasqal/blob/develop/docs/development.md) page that covers some of the most important bits you'd need to know about the project before jumping into writing code.
 
 After that feel free to fork the project and put up PRs with any work you would like to add.
 All experimental work that isn't ready for prime time has to be disabled by default and have no impact on core execution time and stability.

docs/FAQ.md

@@ -0,0 +1,14 @@
+# FAQ
+
+> After reading this it seems like any other hybrid runtime. What makes it different?
+ 
+Rasqal shares more DNA with formal verification tools and [model checkers](https://en.wikipedia.org/wiki/Model_checking) than it does with runtimes even though superficially it does, indeed, run your code.
+But it doesn't view it as running, in fact it's just generating a quantum equation from all the information you've given it, in the form it deduces will give you the best results.
+
+It uses all the classical information provided to provide the constraints that the algorithm is running within, as well as analysing the evolving quantum state as much as it can.
+Many of the classical constraints evaluation comes from existing ideas, but it also tries to do the same to the quantum circuit it's building (within reason).
+
+Many of its systems are currently in their infancy so may not be immediately noticeable, but in time they will.
+
+Rasqal works with other runtimes and sits at the exact point where they have generated the hybrid IR they consider encapsulates, fully, the algorithm they are trying to run. 
+Rasqal then takes this output and crunches it down even further.

docs/building.md

@@ -0,0 +1,46 @@
+## Building from Source
+
+Prerequisites:
+
+1. [Python 3.10](https://www.python.org/downloads/).
+2. [Rust](https://www.rust-lang.org/tools/install).
+
+With these installed then run:
+
+[Linux]
+
+`sudo apt-get install -y ninja-build`
+
+[Windows]
+
+[Chocolatey](https://chocolatey.org/install) is a windows package manager that we use to organize some installs.
+
+`choco install --accept-license -y ninja`
+
+Optional: 
+`choco uninstall -y llvm` if you are having problems with the correct LLVM install being found. 
+
+[Mac]
+
+`brew install ccache ninja`
+
+When this is all done run `build.ps1` at `/src/build.ps1`. 
+
+This will install and build LLVM, build all the Rust projects, build a wheel and install it into the local venv, perform style formatting and more.
+
+Once this has been done you can open up the Rust projects and run cargo like normal as LLVM has been built and cached. You cna also use the built venv to run the Python as well.
+
+You'll have to re-run the build script if you want to build a new wheel to be available from the Python, but beyond that you can develop in whatever environment most suits you.
+
+#### Potential issues
+
+[PyCharm]
+
+To get PyCharm to recognize the LLVM file path you need to add  `LLVM_SYS_150_PREFIX={path_to_repo}/src/target/llvm15-0` to the environment variables for any Rust command. You can also use a config.toml with the same value.
+
+[Windows]
+
+Main issue is to do with path lengths. These two changes may be needed:
+
+* Open the registry, go to `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem` and set `LongPathsEnabled` to 1.
+* Enable long file names via git by running this: `git config --system core.longpaths true`. This will set it for every user on the system, to be only your user use `--global`.

features_and_concepts.md → docs/features_and_concepts.md

@@ -1,64 +1,54 @@
-Whenever Rasqal is first introduced to people they usually ask "How is this different from other hybrid runtimes? It looks exactly the same!".
-On the surface it operates very similarly, so this question isn't that suprising.
-
-Its goals and the way it views the hybrid IRs is actually quite different, but to highlight these differences requires a bit of an explainer about some of its foundational concepts and philosophies.
-Giving an introduction to them will paint its features (and how it works) in a different light, so we'll quickly cover them
-
-If you don't need that feel free to skip to the features list.
-
-### Concepts
+### Core Ideas
 
 Describing Rasqal as a symbolic-execution driven optimizing runtime, while accurate from a high level, also manages to tell us very little about how it works.
 
-A more precise description is that it's a quantum algorithm synthesis engine. 
+A more precise description is that it's a quantum algorithm synthesis engine.
 It treats hybrid IRs as nothing but a blueprint for the algorithms logic, but how that algorithm is actually realized is up to it.
-It may decide to recursively squash classical expressions into your circuit, alternatively expand quantum results into classical, or squash two quantum methods together. 
+It may decide to recursively squash classical expressions into your circuit, alternatively expand quantum results into classical, or squash two quantum methods together.
 As long as the codes logic ends up with the same result, how it gets there is entirely up to Rasqal to decide.
-Multiple -PU machines may also be roped in to run the algorithm or power its optimization passes: QPU, GPU, CPU, HPC(U). 
+Multiple -PU machines may also be roped in to run the algorithm or power its optimization passes: QPU, GPU, CPU, HPC(U).
 Entirely depends upon what machines are nearby.
 
-_Note: As of writing it only uses local CPU and QPU, GPU/HPC support will come later. 
+_Note: As of writing it only uses local CPU and QPU, GPU/HPC support will come later.
 The decision to do many of these transforms is also 'no' right now, since they aren't in or have a rather specific trigger condition._
 
-To make these decisions accurately it needs to know everything about an algorithm as it runs. 
-Here's where its internal structures come into play: the graphs it builds are almost entirely constant. 
+To make these decisions accurately it needs to know everything about an algorithm as it runs.
+Here's where its internal structures come into play: the graphs it builds are almost entirely constant.
 No system calls, no IO, the only variables are the ones passed in from our entry-point.
 The only exception to this rule is when it's decided we need to call out to a QPU or other external hardware.
 But as all our information is towards making these executions as optimized as possible this is an acceptable area of nondeterminism.
 
 These nearly-constant graphs allow very strong assertions to be given around data- and control-flow, and inform us to how the circuit to be sent to the QPU should be built.
 The graphs are then executed, and as we step through them we dynamically build up the queries to send to other hardware, executing when we reach a point that we absolutely need the result.
 
-Rasqal doesn't execute QIR in a traditional sense, it uses it as a schema for encoding the logic that a hybrid algorithm uses. 
+Rasqal doesn't execute QIR in a traditional sense, it uses it as a schema for encoding the logic that a hybrid algorithm uses.
 Sometimes it will run very close to the QIR as-written because it's simple enough to not need transformation.
 In early versions this might happen more often than not, but this is not its function.
 In fact the less the execution run looks like the incoming QIR the better, because it means we've been able to do a lot of optimization and prediction.
 
-
-
-If you are interested in a more thorough breakdown of its internals and concepts it has [a paper](https://github.com/oqc-community/rasqal/blob/develop/docs/papers/Rasqal%20Draft%20v2.pdf) which goes into them in detail.
+If you are interested in a more thorough breakdown of its internals and concepts it has [a paper](https://github.com/oqc-community/rasqal/blob/develop/docs/papers/Rasqal%20Draft%20v3.pdf) which goes into them in detail.
 
 ### Features
 
-This is a loose list of the most important features and capabilities it has right now, as well as what we want to build in the future. 
+This is a loose list of the most important features and capabilities it has right now, as well as what we want to build in the future.
 Like most documentation this may be slightly behind its actual capabilities, so if there's something marked as 'soon' that you'd like it may already be in.
 
 Currently available:
 
 1. Full-spec QIR support [1] including the majority of classical LLVM instructions. Any profile which inherits off the base spec is by implicitly supported.
 2. Variational algorithm capabilities via entry-point arguments and return values.
-3. Multi-QPU execution capabilities - the quantum parts of an algorithm will only run on machines capable of supporting it. 
+3. Multi-QPU execution capabilities - the quantum parts of an algorithm will only run on machines capable of supporting it.
    1. This will also support parallel and distributed QPU execution in the future.
 4. Ability to route hybrid circuits. Initially supported by Tket [2].
 5. Classical and quantum instructions can be fully interwoven including data- and control-flow.
 6. Support for more traditional constructs such as logging and exceptions. These in the future could be lowered into the hardware.
 
 The combination of these means that even if a QPU doesn't have built-in hybrid instruction support you can use Rasqal to execute hybrid code against it.
-All it needs is gate-level operation support. 
+All it needs is gate-level operation support.
 
 We also have a QASM builder that is used to power our simulators, but this could also be used for integrations with anything that has a QASM API.
 
-[1] Big int is the one exception here, this isn't supported. 
+[1] Big int is the one exception here, this isn't supported.
 There are also some instructions we silently ignore because they have no impact on how Rasqal views the world, such as qubit reference counting.
 
 [2] The wording here is rather precise as we don't route the QIR, we route the circuit we generate just before its sent to the QPU.
@@ -68,18 +58,16 @@ Soon to be implemented/improved:
 
 1. Automatically lowering logic into the hardware if support is available, such as conditionals, loops and exceptions.
 2. Aggressive classical operation deference and folding. Currently, if you do a measure and immediately do classical operations on the result then it'll execute the circuit built up to that point.
-We want to also defer the classical operations until we find a point where we _absolutely_ need to execute.
-3. More circuit metadata to be passed to the backend when working out if it can run something. Circuit size, included gates, hardware features, as much as possible. 
+   We want to also defer the classical operations until we find a point where we _absolutely_ need to execute.
+3. More circuit metadata to be passed to the backend when working out if it can run something. Circuit size, included gates, hardware features, as much as possible.
 4. Predicted execution plans. Allows tools to pass in QIR and get back precise information about each quantum execution: what circuit, values, features it requires etc.
-This will allow tools sitting in front of Rasqal to tailor their own optimization passes.
-
-5. LLVM-15+.
+   This will allow tools sitting in front of Rasqal to tailor their own optimization passes.
 
-Then we also have highly experimental features that will be worked on until proven viable or not. 
+Then we also have highly experimental features that will be worked on until proven viable or not.
 
 These will be available only if you enable them explicitly:
 
 1. Quantum state analysis structures for performing indepth static analysis as we go. This powers many other features.
 2. Quantum fragment simulation. Finding points in a circuit that if simulated/predicted allow for better optimization or distributed processing.
 3. Using our analysis tools and splice/weaving techniques to split up and run large quantum circuits across multiple smaller machines.
-community/rasqal/blob/develop/examples.md) for the sorts of code you could send to Rasqal as well as what it returns.
+   community/rasqal/blob/develop/examples.md) for the sorts of code you could send to Rasqal as well as what it returns.