You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[QuantumToolbox.jl](https://github.com/qutip/QuantumToolbox.jl) is a cutting-edge [`Julia`](https://julialang.org/) package designed for quantum physics simulations, closely emulating the popular Python [`QuTiP`](https://github.com/qutip/qutip) package. It uniquely combines the simplicity and power of [`Julia`](https://julialang.org/) with advanced features like GPU acceleration and distributed computing, making simulation of quantum systems more accessible and efficient.
@@ -174,7 +181,11 @@ Here we provide a brief performance comparison between `QuantumToolbox.jl` and o
174
181
175
182
## Contributing to QuantumToolbox.jl
176
183
177
-
You are most welcome to contribute to `QuantumToolbox.jl` development by forking this repository and sending pull requests (PRs), or filing bug reports at the issues page. You can also help out with users' questions, or discuss proposed changes in the [QuTiP discussion group](https://groups.google.com/g/qutip).
184
+
You are most welcome to contribute to `QuantumToolbox.jl` development by forking this repository and sending pull requests (PRs), or filing bug reports at the issues page.
185
+
186
+
Contributors and users for `QuantumToolbox.jl` are invited to [![Zulip][zulip-img]][zulip-url] for questions, development discussions, and community updates.
187
+
188
+
You can also help out with users' questions, or discuss proposed changes for the entire QuTiP organization in the [![QuTiP-discussion][QuTiP-discussion-img]][QuTiP-discussion-url].
178
189
179
190
For more information about contribution, including technical advice, please see the [Contributing to Quantum Toolbox in Julia](https://qutip.org/QuantumToolbox.jl/stable/resources/contributing).
`QuantumToolbox.jl` is developed using the [`git`](https://git-scm.com/) version-control system, with the [main repository](https://github.com/qutip/QuantumToolbox.jl) hosted in the [qutip organisation on GitHub](https://github.com/qutip). You will need to be familiar with [`git`](https://git-scm.com/) as a tool, and the [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) workflow for branching and making pull requests. The exact details of environment set-up, build process, and runtests vary by repository are discussed below. In overview, the steps to contribute are:
6
9
7
10
- Consider creating an issue on the GitHub page of the relevant repository, describing the change you think should be made and why, so we can discuss details with you and make sure it is appropriate.
@@ -13,16 +16,43 @@
13
16
- Write and make sure all the runtests pass. See [here](@ref doc-Contribute:Runtests) for more details.
14
17
- Make sure all the changes match the `Julia` code format (style). See [here](@ref doc-Contribute:Julia-Code-Format) for more details.
15
18
- Improve and make sure the documentation can be built successfully. See [here](@ref doc-Contribute:Documentation) for more details.
16
-
- Update changelog. See [here](@ref doc-Contribute:Update-ChangeLog) for more details.
19
+
- Update changelog. See [here](@ref doc-Contribute:ChangeLog) for more details.
17
20
- Add the changed files to the `git` staging area `git add <file1> <file2> ...`, and then create some commits with short-but-descriptive names: `git commit`.
18
21
- Push the changes to your fork (`origin`): `git push -u origin <branch-name>`. You won’t be able to push to the remote (`qutip`) repositories directly.
19
22
- Go to the GitHub website for the repository you are contributing to, click on the “Pull Requests” tab, click the “New Pull Request” button, and follow the instructions there.
20
23
21
24
Once the pull request (PR) is created, some members of the QuTiP admin team will review the code to make sure it is suitable for inclusion in the library, to check the programming, and to ensure everything meets our standards. For some repositories, several automated CI pipelines will run whenever you create or modify a PR. In general, these will basically be the same ones which you can run locally, and all CI pipelines are required to pass online before your changes are merged to the remote `main` branch. There might be some feedbacks and requested changes. You can add more commits to address these, and push them to the branch (`<branch-name>`) of your fork (`origin`) to update the PR.
22
25
23
-
The rest of this document covers programming standards.
The `make` command is not available by default on Windows. You will need to install a compatible version of `make` (for example via Git-for-Windows, MSYS2, or similar tools). A helpful reference for setting this up can be found here: https://stackoverflow.com/questions/66525016/how-to-run-make-command-in-gitbash-in-windows
30
+
31
+
To simplify common developer tasks, `QuantumToolbox.jl` provides a set of predefined `make` commands. These commands are defined in the repository’s file called `Makefile` and offer a convenient interface for running documentation builds, tests, formatting, and other maintenance routines.
32
+
33
+
If you are contributing for the first time, or have installed a fresh `julia` version, you should begin with:
34
+
35
+
```shell
36
+
make setup
37
+
```
38
+
39
+
to install necessary dependencies. Here are several other common commands:
40
+
41
+
```shell
42
+
make test# run the tests
43
+
make format # format codes with JuliaFormatter
44
+
make docs # instantiate and build the documentation
45
+
make changelog # generate changelog
46
+
make help# view all commands
47
+
```
48
+
49
+
Each command may accept additional options or environment variables to customize its behavior. The following sections describe these commands in detail and explain the available configuration options.
The rest of this document covers programming standards for `QuantumToolbox.jl`.
24
54
25
-
## [Runtests](@id doc-Contribute:Runtests)
55
+
###[Runtests](@id doc-Contribute:Runtests)
26
56
27
57
All the test scripts should be located in the folder `test` in the repository. To run the test, use the following command under the *__root directory of the repository__* you are working on:
28
58
@@ -38,13 +68,13 @@ The tests are divided into several test groups, where the group names are define
38
68
make GROUP=Core test
39
69
```
40
70
41
-
### [Test Item Framework for Core tests](@id doc-Contribute:Test-Item-Framework-for-Core-tests)
71
+
####[Test Item Framework for Core tests](@id doc-Contribute:Test-Item-Framework-for-Core-tests)
42
72
43
73
The tests in `GROUP=Core` are provided using the [Test Item Framework](https://www.julia-vscode.org/docs/stable/userguide/testitems/), which structures the test codes into `@testitems` and makes it easier to run individually.
44
74
45
75
The [VS Code](https://code.visualstudio.com/) and its [Julia extension](https://www.julia-vscode.org/) provides us with options to run individual `@testitems`. It is much easier to find the specific core test that failed since the [Julia extension](https://www.julia-vscode.org/) in [VS Code](https://code.visualstudio.com/) will collect all core test failures and then display them in a structured way, directly at the place in the code where a specific core test failed. See [here](https://www.julia-vscode.org/docs/stable/userguide/testitems/) for more details.
We use [`JuliaFormatter.jl`](https://github.com/domluna/JuliaFormatter.jl) to format all the source codes. The code style and extra formatting options is defined in the file `.JuliaFormatter.toml` in the repository.
50
80
@@ -57,7 +87,7 @@ To format the changed codes, use the following command under the *__root directo
All the documentation source files [in markdown (`.md`) format] and build scripts should be located in the folder `docs` in the repository.
63
93
@@ -74,6 +104,13 @@ make docs
74
104
75
105
This command will automatically rebuild `Julia` and run the script located in `docs/make.jl` (should be able to build the necessary files for the documentation).
76
106
107
+
One can also skip several processes in documentation build by adding arguments to the `make docs` command. For example,
108
+
109
+
```shell
110
+
make docs DOCTEST=false # skip doc tests
111
+
make docs DRAFT=true # disable cell evaluation
112
+
```
113
+
77
114
To read the documentation in a browser, you can run the following command:
78
115
79
116
```shell
@@ -82,7 +119,7 @@ make vitepress
82
119
83
120
This will start a local Vitepress site of documentation at `http://localhost:5173` in your computer.
The changelog is written in the file `CHANGELOG.md` in the repository. If you add some changes to the repository and made a PR, you should also add some messages or release notes together with the related PRs/issues entries to `CHANGELOG.md`. For example, add a new line in `CHANGELOG.md`:
0 commit comments