Platform backends API and logic structure

.pre-commit-config.yaml

@@ -8,19 +8,24 @@ repos:
       - id: check-added-large-files
 
 -   repo: https://github.com/ambv/black
-    rev: 24.4.2
+    rev: 24.8.0
     hooks:
       - id: black
 
 -   repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.4.2"
+    rev: "v0.6.2"
     hooks:
       - id: ruff
         args:
           - --fix
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.10.0
+    rev: v1.11.0
     hooks:
       - id: mypy
-        exclude: examples|docs
+        exclude: examples|docs|qadence2_platforms.utils.templates
+
+-   repo: https://github.com/DanielNoord/pydocstringformatter
+    rev: v0.7.3
+    hooks:
+      - id: pydocstringformatter

README.md

@@ -1,28 +1,70 @@
 # Qadence 2 Platforms
+
+**Notice**: Qadence 2 Platforms is currently a *work in progress* and is under active development. Please be aware that the software is in an early stage, and frequent updates, including breaking changes, are to be expected. This means that:
+* Features and functionalities may change without prior notice.
+* The codebase is still evolving, and parts of the software may not function as intended.
+* Documentation and user guides may be incomplete or subject to significant changes.
+
 Platform dependent APIs and engines (backends) to be used on Qadence 2.
 
 
 ## Installation
-Installation guidelines
 
-## Qadence Intermediate Representation
-Qadence2 expressions is being compiled into an IR comprised of both quantum and classical operations.
-## API
-The `backend` module exposes a single `compile` function which accepts a `Model` and a string denoting the `backend`.
-## Backend
-Each submodule under `backend`  is expected to handle the storage and embedding of parameters in a `Embedding` class, the compilation of `model.instructions` into native instructions in the particular backend via a `Compiler`
-and the handling of the register via a `RegisterInterface`.
+*Note*: it is advised to set up a python environment before installing the package.
+
+To install the current version, there is currently one option:
+
+
+### Installation from Source
+
+Clone this repository by typing on the terminal
+
+```bash
+git clone https://github.com/pasqal-io/qadence2-platforms.git
+```
+
+Go to `qadence2-platforms` folder and install it using [hatch](https://hatch.pypa.io/latest/)
+
+```bash
+hatch -v shell
+```
+
+## Platforms
+
+This package **should not** be used directly by the user. It is used to convert [Qadence IR](https://github.com/pasqal-io/qadence2-ir) into backend-compatible data, and to execute it with extra options (provided by the compilation process, either on [Qadence 2 expressions](https://github.com/pasqal-io/qadence2-expressions) or [Qadence 2 core](https://github.com/pasqal-io/qadence2-core)).
+
+### Qadence Intermediate Representation
+
+Qadence 2 expressions is being compiled into an IR comprised of both quantum and classical operations.
+
+### API
+
+The `backend` module exposes a single `compile_to_backend` function which accepts a `Model` and a string denoting the `backend`.
+
+### Backend
 
-## Usage
+Each submodule under `backend` is expected (1) to translate the `IR` data into backend-compatible data, (2) to provide instruction conversions from `IR` to backend, (3) to handle the storage and embedding of parameters, and (4) to implement execution process for `run`, `sample` and `expectation`.
+
+### Usage
 
 Example
-```python
-from qadence2_platforms import Model
+```python exec="on" source="material-block" session="model"
+from qadence2_ir.types import (
+    Model,
+    Alloc,
+    AllocQubits,
+    Call,
+    Assign,
+    QuInstruct,
+    Support,
+    Load
+)
+
 
 Model(
     register = AllocQubits(
         num_qubits = 3,
-        positions = [(-2,1), (0,1), (1,3)],
+        qubit_positions = [(-2,1), (0,1), (1,3)],
         grid_type = "triangular",
         grid_scale = 1.0,
         options = {"initial_state": "010"}
@@ -43,20 +85,28 @@ Model(
         QuInstruct("not", Support(target=(1,), control=(0,))),
         QuInstruct(
 		        "qubit_dyn",
-		        Support(0, 2),
+		        Support(control=(0,), target=(2,)),
 		        Load("t"),
 		        Load("Omega"),
 		        Load("delta"),
 		    )
     ],
     directives = {"digital-analog": True},
-    data_settings = {"result-type": "state-vector", "data-type": "f32"}
 )
 ```
 
 Compiling a `pyqtorch` circuit and computing gradients using `torch.autograd`
 
-```python
+```python exec="on" source="material-block" session="model"
+import torch
+import pyqtorch as pyq
+from qadence2_ir.types import (
+    Model, Alloc, AllocQubits, Load, Call, Support, QuInstruct, Assign
+)
+
+from qadence2_platforms.compiler import compile_to_backend
+
+
 model = Model(
     register=AllocQubits(num_qubits=2),
     inputs={
@@ -69,16 +119,35 @@ model = Model(
         QuInstruct("not", Support(target=(1,), control=(0,))),
     ],
     directives={"digital": True},
-    data_settings={"result-type": "state-vector", "data-type": "f64"},
 )
-api = compile(model, "pyqtorch")
+api = compile_to_backend("pyqtorch", model)
 f_params = {"x": torch.rand(1, requires_grad=True)}
-wf = api.run(pyq.zero_state(2), f_params)
+wf = api.run(state=pyq.zero_state(2), values=f_params)
 dfdx = torch.autograd.grad(wf, f_params["x"], torch.ones_like(wf))[0]
 ```
 
 ## Documentation
-Documentation guidelines
+
+**Notice**: Documentation in progress.
+
 
 ## Contribute
-Contribution guidelines
+
+Before making a contribution, please review our [code of conduct](docs/getting_started/CODE_OF_CONDUCT.md).
+
+- **Submitting Issues:** To submit bug reports or feature requests, please use our [issue tracker](https://github.com/pasqal-io/qadence2-platforms/issues).
+- **Developing in qadence 2 platforms:** To learn more about how to develop within `qadence 2 platforms`, please refer to [contributing guidelines](docs/getting_started/CONTRIBUTING.md).
+
+### Setting up qadence 2 platforms in development mode
+
+We recommend to use the [`hatch`](https://hatch.pypa.io/latest/) environment manager to install `qadence 2 platforms` from source:
+
+```bash
+python -m pip install hatch
+
+# get into a shell with all the dependencies
+python -m hatch shell
+
+# run a command within the virtual environment with all the dependencies
+python -m hatch run python my_script.py
+```

docs/getting_started/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

docs/getting_started/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# How to contribute
+
+We're grateful for your interest in participating in Qadence 2 Platforms. Please follow our guidelines to ensure a smooth contribution process.
+
+## Reporting an issue or proposing a feature
+
+Your course of action will depend on your objective, but generally, you should start by creating an issue. If you've discovered a bug or have a feature you'd like to see added to **qadence 2 platforms**, feel free to create an issue on [qadence 2 platforms' GitHub issue tracker](https://github.com/pasqal-io/qadence2-platforms/issues). Here are some steps to take:
+
+1. Quickly search the existing issues using relevant keywords to ensure your issue hasn't been addressed already.
+2. If your issue is not listed, create a new one. Try to be as detailed and clear as possible in your description.
+
+- If you're merely suggesting an improvement or reporting a bug, that's already excellent! We thank you for it. Your issue will be listed and, hopefully, addressed at some point.
+- However, if you're willing to be the one solving the issue, that would be even better! In such instances, you would proceed by preparing a [Pull Request](#submitting-a-pull-request).
+
+## Submitting a pull request
+
+We're excited that you're eager to contribute to Qadence 2 Platforms. To contribute, fork the `main` branch of qadence 2 platforms repository and once you are satisfied with your feature and all the tests pass create a [Pull Request](https://github.com/pasqal-io/qadence2-platforms/pulls).
+
+Here's the process for making a contribution:
+
+Click the "Fork" button at the upper right corner of the [repo page](https://github.com/pasqal-io/qadence2-platforms) to create a new GitHub repo at `https://github.com/USERNAME/qadence2-platforms`, where `USERNAME` is your GitHub ID. Then, `cd` into the directory where you want to place your new fork and clone it:
+
+```shell
+git clone https://github.com/USERNAME/qadence2-platforms.git
+```
+
+Next, navigate to your new qadence 2 platforms fork directory and mark the main qadence 2 platforms repository as the `upstream`:
+
+```shell
+git remote add upstream https://github.com/pasqal-io/qadence2-platforms.git
+```
+
+## Setting up your development environment
+
+We recommended to use `hatch` for managing environments:
+
+To develop within qadence 2 platforms, use:
+```shell
+pip install hatch
+hatch -v shell
+```
+
+To run qadence 2 platforms tests, use:
+
+```shell
+hatch -e tests run test
+```
+
+If you don't want to use `hatch`, you can use the environment manager of your
+choice (e.g. Conda) and execute the following:
+
+```shell
+pip install pytest
+pip install -e .
+pytest
+```
+
+### Useful things for your workflow: linting and testing
+
+Use `pre-commit` to lint your code and run the unit tests before pushing a new commit.
+
+Using `hatch`, it's simply:
+
+```shell
+hatch -e tests run pre-commit run --all-files
+hatch -e tests run test
+```
+
+Our CI/CD pipeline will also test if the documentation can be built correctly. To test it locally, please run:
+
+```shell
+hatch -e docs run mkdocs build --clean --strict
+```
+
+Without `hatch`, `pip` install those libraries first:
+"mkdocs",
+"mkdocs-material",
+"mkdocstrings",
+"mkdocstrings-python",
+"mkdocs-section-index",
+"mkdocs-jupyter",
+"mkdocs-exclude",
+"markdown-exec"
+
+
+And then:
+
+```shell
+ mkdocs build --clean --strict
+```

docs/index.md

@@ -1,12 +1,53 @@
-# "qadence2 platforms"
+# Qadence 2 Platforms
+
+**Notice**: Qadence 2 Platforms is currently a *work in progress* and is under active development. Please be aware that the software is in an early stage, and frequent updates, including breaking changes, are to be expected. This means that:
+* Features and functionalities may change without prior notice.
+* The codebase is still evolving, and parts of the software may not function as intended.
+* Documentation and user guides may be incomplete or subject to significant changes.
+
+
 ## Installation
-Installation guidelines
 
-## Usage
-Usage guidelines
+*Note*: it is advised to set up a python environment before installing the package.
+
+To install the current version, there is currently one option:
+
+
+### Installation from Source
+
+Clone this repository by typing on the terminal
+
+```bash
+git clone https://github.com/pasqal-io/qadence2-platforms.git
+```
+
+Go to `qadence2-platforms` folder and install it using [hatch](https://hatch.pypa.io/latest/)
+
+```bash
+hatch -v shell
+```
+
+## Contributing
+
+Before making a contribution, please review our [code of conduct](getting_started/CODE_OF_CONDUCT.md).
+
+- **Submitting Issues:** To submit bug reports or feature requests, please use our [issue tracker](https://github.com/pasqal-io/qadence2-platforms/issues).
+- **Developing in qadence 2 platforms:** To learn more about how to develop within `qadence 2 platforms`, please refer to [contributing guidelines](getting_started/CONTRIBUTING.md).
+
+### Setting up qadence 2 platforms in development mode
+
+We recommend to use the [`hatch`](https://hatch.pypa.io/latest/) environment manager to install `qadence 2 platforms` from source:
+
+```bash
+python -m pip install hatch
+
+# get into a shell with all the dependencies
+python -m hatch shell
+
+# run a command within the virtual environment with all the dependencies
+python -m hatch run python my_script.py
+```
 
-## Documentation
-Documentation guidelines
+## License
 
-## Contribute
-Contribution guidelines
+Qadence 2 Platforms is a free and open source software package, released under the [Apache License, Version 2.0](getting_started/LICENSE.md).

docs/sample_page.md

@@ -1,8 +1,7 @@
-This is just a sample notebook to showcase the rendering of Jupyter notebooks in the documentation.
+This is just a sample code to showcase the rendering in the documentation.
 
-```python exec="on" source="material-block" session="main"
-from qadence2_platforms.main import main
+```python exec="on" source="material-block" result="json" session="compile_to_backend"
+from qadence2_platforms.compiler import compile_to_backend
 
-msg = main()
-print(msg)
+print(compile_to_backend)
 ```