Merge branch 'refactor-schema-generation' of https://github.com/QuEraComputing/bloqade-python into refactor-schema-generation

Author: weinbe58

.github/workflows/ci.yml

@@ -39,11 +39,4 @@ jobs:
         run: pdm install       # Then you can use pdm in the following steps.
       - name: Test with pytest & generate coverage
         run: |
-          pdm run coverage
-      - name: Upload Coverage to Codecov
-        uses: codecov/codecov-action@v3
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          files: coverage.xml # optional
-          fail_ci_if_error: true # optional (default = false)
-          verbose: true # optional (default = false)
+          pdm test

.github/workflows/cov.yml

@@ -0,0 +1,44 @@
+name: Coverage
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# See: https://github.com/pdm-project/pdm/issues/1879
+env:
+  PDM_DEPS: 'urllib3<2'
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+      - uses: pdm-project/setup-pdm@v3
+        name: Setup PDM
+        with:
+          python-version: 3.9  # Version range or exact version of a Python version to use, the same as actions/setup-python
+          # well we use virtualenv here
+          # prerelease: true     # Allow prerelease versions to be installed
+          # enable-pep582: true  # Enable PEP 582 package loading globally
+      - name: Install dependencies
+        run: pdm install       # Then you can use pdm in the following steps.
+      - name: Test with pytest & generate coverage
+        run: |
+          pdm run coverage
+      - name: Upload Coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml # optional
+          fail_ci_if_error: true # optional (default = false)
+          verbose: true # optional (default = false)

.github/workflows/deploy_dev.yml

@@ -20,10 +20,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python 3.11
         uses: actions/setup-python@v4
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: 3.11
       - uses: pdm-project/setup-pdm@v3
         name: Setup PDM
         with:
@@ -44,10 +44,10 @@ jobs:
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
-      - name: Depoly documentation
+      - name: Deploy documentation
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
         run: |
           git fetch origin gh-pages --depth=1
-          pdm run mike deploy --rebase --push -F ${GITHUB_WORKSPACE}/mkdocs.yml dev
+          pdm run mike deploy -p dev

.github/workflows/deploy_latest.yml

@@ -17,7 +17,7 @@ jobs:
     name: Deploy release documentation
     runs-on: ubuntu-latest
     steps:
-      - name: Wait for Dev documentation to deploy
+      - name: Wait for dev documentation to deploy
         uses: lewagon/[email protected]
         with:
           ref: main
@@ -55,11 +55,10 @@ jobs:
         run: |
           export RELEASE_TAG_VERSION=${{ github.event.release.tag_name }}
           echo "RELEASE_TAG_VERSION=${RELEASE_TAG_VERSION::3}" >> $GITHUB_ENV
-      - name: Depoly documentation
+      - name: Deploy documentation
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
         run: |
           git fetch origin gh-pages --depth=1
-          pdm run mike deploy --rebase --push -F ${GITHUB_WORKSPACE}/mkdocs.yml  --update-aliases latest ${RELEASE_TAG_VERSION}
-          pdm run mike set-default --rebase --push -F ${GITHUB_WORKSPACE}/mkdocs.yml latest
+          pdm run mike deploy -up ${RELEASE_TAG_VERSION} latest

.github/workflows/doc.yml

@@ -16,9 +16,16 @@ env:
 
 jobs:
   documentation:
-    name: Build documentation
+    name: Deploy preview documentation
     runs-on: ubuntu-latest
     steps:
+      - name: Wait for dev documentation to deploy
+        uses: lewagon/[email protected]
+        with:
+          ref: main
+          check-name: 'Deploy dev documentation'
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          wait-interval: 10
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4

README.md

@@ -1,7 +1,7 @@
 <div align="center">
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/docs/assets/logo-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="docs/docs/assets/logo.png">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo.png">
   <img alt="Bloqade Logo">
 </picture>
 </div>
@@ -24,7 +24,7 @@ Those coming from Bloqade.jl will most likely have this as their first question
 
 Bloqade.jl was designed as an ***emulation-first*** SDK enabling users to investigate novel physical phenomena and develop complex algorithms with bleeding-edge performance. The result of this focus is that not everything made in Bloqade.jl is compatible with quantum hardware. While the ability to submit to Braket is available in Bloqade.jl it becomes cumbersome to analyze results and keep track of parameter sweeps.
 
-In our mission to make neutral atom quantum computing more accessible to a broader community and the valuable feedback we've received in users of our quantum hardware, we took the opportunity to create a ***hardware-first*** SDK. One that is perfectly positioned to make it even easier to reap the benefits of neutral atoms while minimizing the pain points of initial program creation and post-processing results. 
+In our mission to make neutral atom quantum computing more accessible to a broader community and the valuable feedback we've received in users of our quantum hardware, we took the opportunity to create a ***hardware-first*** SDK. One that is perfectly positioned to make it even easier to reap the benefits of neutral atoms while minimizing the pain points of initial program creation and post-processing results.
 
 ## What does Bloqade do?
 
@@ -42,19 +42,19 @@ pip install bloqade
 
 ## Documentation
 
-If you're already convinced about what Bloqade brings to the table, feel free to take a look at our documentation with examples [here](https://queracomputing.github.io/bloqade-python/latest/). 
+If you're already convinced about what Bloqade brings to the table, feel free to take a look at our documentation with examples [here](https://queracomputing.github.io/bloqade-python/latest/).
 
 If you aren't convinced, keep scrolling!
 
 ## Features
 
 ### Smart Documentation
 
-Get where you need to go in your program development with documentation that knows *where* and *when* it's needed. Never get lost developing your algorithm ever again! 
+Get where you need to go in your program development with documentation that knows *where* and *when* it's needed. Never get lost developing your algorithm ever again!
 
 If you're a novice to neutral atoms, smart docs have your back. If you're an expert with neutral atoms, let smart docs give you some guidance on some new avenues for algorithm development.
 
-![](docs/docs/assets/readme-gifs/smart-docs.gif)
+![](docs/assets/readme-gifs/smart-docs.gif)
 
 
 ### Fully Parameterized Analog Programs
@@ -63,13 +63,13 @@ If you're a novice to neutral atoms, smart docs have your back. If you're an exp
 
 You used to have to manually keep track of all the small variations of your program per parameter, keeping careful track not to forget to submit one variation or lose one on top of a convoluted post-processing pipeline to incorporate all the results in one place.
 
-Bloqade eliminates this with its own support for variables and internal handling of program parameter variations. Just drop in a variable in almost any place a single value can live and you can either assign a value later or a whole sequence of values to create a parameter sweep. 
+Bloqade eliminates this with its own support for variables and internal handling of program parameter variations. Just drop in a variable in almost any place a single value can live and you can either assign a value later or a whole sequence of values to create a parameter sweep.
 
 Let Bloqade handle keeping track of all the variations while you focus on becoming a master of neutral atoms.
 
 Did we mention you can throw your program at hardware and emulation and still keep your parameter sweeps?
 
-```python 
+```python
 from bloqade import var
 from bloqade.atom_arrangement import Square
 
@@ -79,7 +79,7 @@ adiabatic_durations = [0.4, 3.2, 0.4]
 
 # create variables explicitly...
 max_detuning = var("max_detuning")
-# ...or implicitly inside the program definition. 
+# ...or implicitly inside the program definition.
 adiabatic_program = (
     Square(3, "lattice_spacing")
     .rydberg.rabi.amplitude.uniform.piecewise_linear(
@@ -109,13 +109,13 @@ hw_results = adiabatic_program.parallelize(24).braket.aquila().run_async(100)
 
 Simple and fast visualization for programs no matter how complex your program gets:
 
-![](docs/docs/assets/readme-gifs/locations-hover.gif)
-![](docs/docs/assets/readme-gifs/graph-select.gif)
+![](docs/assets/readme-gifs/locations-hover.gif)
+![](docs/assets/readme-gifs/graph-select.gif)
 
-The same holds for results: 
+The same holds for results:
 
-![](docs/docs/assets/readme-gifs/visualize-bitstrings.gif)
-![](docs/docs/assets/readme-gifs/hover-bitstrings.gif)
+![](docs/assets/readme-gifs/visualize-bitstrings.gif)
+![](docs/assets/readme-gifs/hover-bitstrings.gif)
 
 ### Maximum Composability
 
@@ -152,14 +152,14 @@ separate_rabi_amp_wf = piecewise_linear(durations = adiabatic_durations, values
 max_detuning = var("max_detuning")
 separate_rabi_detuning = piecewise_linear(durations = adiabatic_durations, values = [-max_detuning, -max_detuning, max_detuning, max_detuning])
 
-# Now bring it all together! 
+# Now bring it all together!
 # And why not sprinkle in some parameter sweeps for fun?
 full_program = (
     square_lattice.rydberg.rabi.amplitude.uniform
     .apply(separate_rabi_amp_wf)
     .detuning.uniform
     .apply(separate_rabi_detuning)
-    .assign(max_rabi = 15.8, 
+    .assign(max_rabi = 15.8,
             max_detuning = 16.33)
     .batch_assign(lattice_spacing = np.arange(4.0, 7.0, 0.5),
                   max_rabi = np.linspace(2 * np.pi * 0.5, 2 * np.pi * 2.5, 6))
@@ -185,6 +185,6 @@ program_with_few_atoms.parallelize(24).braket.aquila(24).run_async(100)
 
 Bloqade wouldn't exist if we weren't fortunate enough to obtain feedback from awesome members of our community such as yourself (:
 
-If you find a bug, have an idea, or find an issue with our documentation, please feel free to file an issue on the [Github repo itself](https://github.com/QuEraComputing/bloqade-python/issues/new/choose). 
+If you find a bug, have an idea, or find an issue with our documentation, please feel free to file an issue on the [Github repo itself](https://github.com/QuEraComputing/bloqade-python/issues/new/choose).
 
 *May the van der Waals force be with you!*

codecov.yml

@@ -8,3 +8,6 @@ coverage:
       default:
         target: auto
         threshold: 4%
+
+codecov:
+  token: 86b6a2b8-9acb-4b50-b0da-04f14035d704

docs/docs/builder-workflow/overview.md renamed to docs/builder-workflow/overview.md

@@ -1,6 +1,6 @@
 # Builder Overview
 
-You may have noticed from the [Usage](../getting_started/philosophy.md) and [Tutorials](https://queracomputing.github.io/bloqade-python-examples/latest/)
+You may have noticed from the [Usage](../getting_started/usage.md) and [Tutorials](https://queracomputing.github.io/bloqade-python-examples/latest/)
 that Bloqade uses this interesting, dot-intensive syntax.
 
 ```python
@@ -19,7 +19,7 @@ circuit = init_qubits(n_qubits)
 circuit.x(0).z(1).cnot(0, 1)...
 ```
 
-What's the deal with that? 
+What's the deal with that?
 
 ## Syntax Motivations
 
@@ -36,4 +36,4 @@ The linear structure implies a natural hiearchy in how you think about targeting
 
 While we hope the Smart Documentation (the ability to instantly see all your next possible steps and their capabilities in your favorite IDE/IPython) is sufficient to get you where you need to go, we undestand it's particularly beneficial to get a high-level overview of things before diving in.
 
-The [Standard Representation](standard.md) is a nice flow chart that gives a high-level overview of the different steps and components in the builder syntax.
+The [Standard Representation](standard.md) is a nice flow chart that gives a high-level overview of the different steps and components in the builder syntax.

docs/builder-workflow/standard.md

@@ -0,0 +1,103 @@
+
+# Build Workflow
+
+``` mermaid
+
+flowchart TD
+
+  ProgramStart(["start"])
+
+  Geometry("Geometry or Lattice")
+
+  Coupling["Coupling
+  -----------
+  rydberg
+  hyperfine"]
+
+  Detuning["detuning"]
+  Rabi["rabi"]
+
+  Amplitude["amplitude"]
+  Phase["phase"]
+
+  SpaceModulation("SpatialModulation
+  ----------------------
+  uniform
+  scale
+  location
+  ")
+  Waveform{"Waveform
+  ------------
+  piecewise_linear
+  piecewise_constant
+  constant
+  linear
+  poly
+  fn
+  "}
+
+  Options(["Options
+  ---------
+  assign
+  batch_assign
+  args
+  parallelize
+  "])
+
+  Services(["Services
+  ----------
+  bloqade
+  quera
+  braket"])
+
+  QuEraBackends(["Backends
+  ------------
+  mock
+  cloud_mock
+  aquila
+  device"])
+
+  BraketBackends(["Backends
+  ------------
+  aquila
+  local_emulator"])
+
+  BloqadeBackends(["Backends
+  ------------
+  python
+  julia"])
+
+  Submit("Execution
+  ------------
+  run_async()
+  run()
+  __call__")
+
+  ProgramStart -->|add_position| Geometry;
+  Geometry --> Coupling;
+  ProgramStart --> Coupling;
+
+  Coupling --> Detuning;
+  Coupling --> Rabi;
+
+  Rabi --> Amplitude;
+  Rabi --> Phase;
+
+  Detuning --> SpaceModulation;
+  Amplitude --> SpaceModulation;
+  Phase --> SpaceModulation;
+
+  SpaceModulation --> Waveform;
+
+  Waveform --> Coupling;
+  Waveform --> Services;
+  Waveform --> Options;
+  Options --> Services;
+
+  Services -->|quera| QuEraBackends;
+  Services -->|braket| BraketBackends;
+  Services -->|bloqade| BloqadeBackends;
+  QuEraBackends --> Submit;
+  BraketBackends --> Submit;
+  BloqadeBackends --> Submit;
+```