Merge remote-tracking branch 'upstream/main' into dev/patch-1

Author: albertomercurio

.buildkite/pipeline.yml

@@ -2,14 +2,14 @@
 steps:
   - label: ":runner: Dynamically launch pipelines"
     plugins:
-      - staticfloat/forerunner:
+      - staticfloat/forerunner: # CUDA.jl tests
           watch:
             - ".buildkite/pipeline.yml"
             - ".buildkite/CUDA_Ext.yml"
             - "src/**"
             - "ext/QuantumToolboxCUDAExt.jl"
             - "test/runtests.jl"
-            - "test/cuda_ext.jl"
+            - "test/ext-test/cuda_ext.jl"
             - "Project.toml"
           target: ".buildkite/CUDA_Ext.yml"
     agents:

.github/pull_request_template.md

@@ -3,16 +3,16 @@ Thank you for contributing to `QuantumToolbox.jl`! Please make sure you have fin
 
 - [ ] Please read [Contributor Covenant Code of Conduct](https://github.com/qutip/QuantumToolbox.jl/blob/main/CODE_OF_CONDUCT.md)
 - [ ] Any code changes were done in a way that does not break public API
-- [ ] Appropriate tests were added.
-- [ ] Any code changes should be formatted by running: `julia -e 'using JuliaFormatter; format(".")'`
-- [ ] All documentation (in `docs/` folder) related to code changes were updated.
+- [ ] Appropriate tests were added and tested locally by running: `make test`.
+- [ ] Any code changes should be `julia` formatted by running: `make format`.
+- [ ] All documents (in `docs/` folder) related to code changes were updated and able to build locally by running `make docs`.
 
 Request for a review after you have completed all the tasks. If you have not finished them all, you can also open a [Draft Pull Request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) to let the others know this on-going work.
 
 ## Description
 Describe the proposed change here.
 
 ## Related issues or PRs
-Please mention the related issues or PRs here. If the PR fixes an issue, use the keyword close/closes/closed/fix/fixes/fixed/resolve/resolves/resolved followed by the issue id, e.g. fix #1234
+Please mention the related issues or PRs here. If the PR fixes an issue, use the keyword close/closes/closed/fix/fixes/fixed/resolve/resolves/resolved followed by the issue id, e.g. fix #[id]
 
-## Additional context
+## Additional context

.github/workflows/CI-Julia-nightly.yml

@@ -0,0 +1,61 @@
+name: Runtests (Julia nightly)
+
+on:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - '.github/workflows/CI-Julia-nightly.yml'
+      - 'src/**'
+      - 'ext/**'
+      - 'test/runtests.jl'
+      - 'test/core-test/**'
+      - 'Project.toml'
+  pull_request:
+    branches:
+      - 'main'
+    paths:
+      - '.github/workflows/CI-Julia-nightly.yml'
+      - 'src/**'
+      - 'ext/**'
+      - 'test/runtests.jl'
+      - 'test/core-test/**'
+      - 'Project.toml'
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+
+jobs:
+  test:
+    name: ${{ matrix.os }} - ${{ matrix.arch }} ( ${{ matrix.group }} )
+    runs-on: ${{ matrix.os }}
+    permissions: # needed to allow julia-actions/cache to delete old caches that it has created
+      actions: write
+      contents: read
+    if: ${{ !github.event.pull_request.draft }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - 'nightly'
+        os:
+          - 'ubuntu-latest'
+        arch:
+          - 'x64'
+        group:
+          - 'Core'
+          - 'Code-Quality'
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+        env:
+          GROUP: ${{ matrix.group }}

.github/workflows/CI.yml

@@ -8,7 +8,8 @@ on:
       - '.github/workflows/CI.yml'
       - 'src/**'
       - 'ext/**'
-      - 'test/**'
+      - 'test/runtests.jl'
+      - 'test/core-test/**'
       - 'Project.toml'
   pull_request:
     branches:
@@ -17,7 +18,8 @@ on:
       - '.github/workflows/CI.yml'
       - 'src/**'
       - 'ext/**'
-      - 'test/**'
+      - 'test/runtests.jl'
+      - 'test/core-test/**'
       - 'Project.toml'
     types:
       - opened
@@ -27,8 +29,8 @@ on:
 
 jobs:
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} ( ${{ matrix.group }} )
-    runs-on: ${{ matrix.os }}
+    name: Julia ${{ matrix.version }} - ${{ matrix.node.os }} - ${{ matrix.node.arch }} ( ${{ matrix.group }} )
+    runs-on: ${{ matrix.node.os }}
     permissions: # needed to allow julia-actions/cache to delete old caches that it has created
       actions: write
       contents: read
@@ -40,43 +42,37 @@ jobs:
         version:
           - '1.10' # oldest
         #  - '1'    # latest
-        os:
-          - ubuntu-latest
-          - windows-latest
-        arch:
-          - x64
+        node:
+          - os: 'ubuntu-latest'
+            arch: 'x64'
+          - os: 'windows-latest'
+            arch: 'x64'
+          - os: 'macOS-latest'
+            arch: 'arm64'
         group:
-          - Core
+          - 'Core'
 
         include:
-          # for core tests on macOS (M-series chip)
-          - version: '1.10'    # oldest
-            os: 'macOS-latest'
-            arch: 'x64'
-            group: 'Core'
-          # - version: '1'       # latest
-          #   os: 'macOS-latest'
-          #   arch: 'arm64'
-          #   group: 'Core'
+          # for code quality tests
+          - version: '1'
+            node: 
+              os: 'ubuntu-latest'
+              arch: 'x64'
+            group: 'Code-Quality'
 
           # for core tests (intermediate versions)
           # - version: '1.x'
-          #   os: 'ubuntu-latest'
-          #   arch: 'x64'
+          #   node:
+          #     os: 'ubuntu-latest'
+          #     arch: 'x64'
           #   group: 'Core'
 
-          # for code quality tests
-          - version: '1'
-            os: 'ubuntu-latest'
-            arch: 'x64'
-            group: 'Code-Quality'
-
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
-          arch: ${{ matrix.arch }}
+          arch: ${{ matrix.node.arch }}
       - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1

.github/workflows/FormatCheck.yml

@@ -45,6 +45,6 @@ jobs:
                 write(stdout, output)
                 write(stdout, "-----\n")
                 write(stdout, "Please format them by running the following command:\n")
-                write(stdout, "julia -e \"using JuliaFormatter; format(\\\".\\\")\"")
+                write(stdout, "make format")
                 exit(1)
             end'

Makefile

@@ -0,0 +1,21 @@
+JULIA:=julia
+
+default: help
+
+docs:
+	${JULIA} --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+	${JULIA} --project=docs docs/make.jl
+
+format:
+	${JULIA} -e 'using JuliaFormatter; format(".")'
+
+test:
+	${JULIA} --project -e 'using Pkg; Pkg.resolve(); Pkg.test()'
+
+help:
+	@echo "The following make commands are available:"
+	@echo " - make docs: instantiate and build the documentation"
+	@echo " - make format: format codes with JuliaFormatter"
+	@echo " - make test: run the tests"
+
+.PHONY: default docs format test help

Project.toml

@@ -1,7 +1,7 @@
 name = "QuantumToolbox"
 uuid = "6c2fb7c5-b903-41d2-bc5e-5a7c320b9fab"
 authors = ["Alberto Mercurio", "Luca Gravina", "Yi-Te Huang"]
-version = "0.13.1"
+version = "0.14.0"
 
 [deps]
 ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"

README.md

@@ -144,8 +144,6 @@ We can extract the expectation value of the number operator $\hat{a}^\dagger \ha
 
 We can easily pass the computation to the GPU, by simply passing all the `Qobj`s to the GPU:
 
-> **_NOTE:_** The described feature requires `Julia 1.9+`.
-
 ```julia
 using QuantumToolbox
 using CUDA

docs/README.md

@@ -3,16 +3,25 @@
 ## Working Directory
 All the commands should be run under the root folder of the package: `/path/to/QuantumToolbox.jl/`
 
-## Build Pkg
+The document pages will be generated in the directory: `/path/to/QuantumToolbox.jl/docs/build/` (which is ignored by git).
+
+## Method 1: Run with `make` command
+Run the following command:
+```shell
+make docs
+```
+
+## Method 2: Run `julia` command manually
+
+### Build Pkg
 Run the following command:
 ```shell
 julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
 ```
 > **_NOTE:_** `Pkg.develop(PackageSpec(path=pwd()))` adds the local version of `QuantumToolbox` as dev-dependency instead of pulling from the registered version.
 
-## Build Documentation
+### Build Documentation
 Run the following command:
 ```shell
 julia --project=docs docs/make.jl
 ```
-The document pages will be generated in the directory: `/path/to/QuantumToolbox.jl/docs/build/` (which is ignored by git).

docs/make.jl

@@ -21,14 +21,14 @@ const PAGES = [
     "Getting Started" => [
         "Introduction" => "index.md",
         "Key differences from QuTiP" => "qutip_differences.md",
+        "The Importance of Type-Stability" => "type_stability.md",
         # "Cite QuantumToolbox.jl" => "cite.md",
     ],
     "Users Guide" => [
         "Basic Operations on Quantum Objects" => [
             "users_guide/QuantumObject/QuantumObject.md",
             "users_guide/QuantumObject/QuantumObject_functions.md",
         ],
-        "The Importance of Type-Stability" => "users_guide/type_stability.md",
         "Manipulating States and Operators" => "users_guide/states_and_operators.md",
         "Tensor Products and Partial Traces" => "users_guide/tensor.md",
         "Time Evolution and Dynamics" => [