QArray: a GPU-accelerated constant capacitance model simulator for large quantum dot arrays

- new algorithm with improved runtime
- python interface with optimized backends allowing for parallelization on CPU and GPU
- unit tests

- documentation of functions often lacking
- validity of the improved algorithms sometimes unclear (see report)
- some parts of manuscript/usage of the package are hard to follow (see report)

The paper describes a package to efficiently compute the ground state of quantum dot arrays within the approximation of the constant capacitor model. In addition, it contains functionality to simulate the response of an actual experimental probe, such as a charge sensing dot.

This is a topic of great current interest (two similar packages were published almost simultaneously), driven by the interest to generate artificial training data for machine learning. The algorithm shows a clear improvement over the standard brute-force method, and the implementation has an emphasis on efficiency, including options to parallelize on a CPU and GPU. The package overall seems well-organized, with a structured API and useful comments in the code.

I installed the package on my personal laptop (Ubuntu 22.04) using conda. The command 'pip install qarray' worked after I also installed 'cmake' via 'conda install cmake'. (See some comments in requested changes with regards to installation). I then ran the example provided in the main text (copied from the README on the github page), and tried another of the examples provided on github. These ran without any problems.

In general, I believe that in principle this package and accompanying paper should be publised in SciPost Physics Codebases. However, currently the paper and code are lacking with regards to the following acceptance criteria:

2. At least one example application must be presented in detail
6. The documentation must be complete, including detailed instructions on downloading, installing and running the software

In particular, I encountered the following problems:
- Many functions in the code are not documented properly. Moreover, many docstrings are very short and hard to understand. Take the example of the function 'charge_state_contrast'. The docstring only says 'Function to compute the charge state contrast'. It is missing an explanation though what charge state contrast even is (google only finds 5 instances for this expression, so it is not widely used). I can guess it from the result, but I should not need to guess.
- I don't find the package very intuitive to use. I can run the examples, but I would find it hard to code my own simulation. A reason for this is that the example in the paper is very short and incomplete (not even the output is shown). The different concepts used by the classes that build the system are barely explained. There are many examples in the repository, but these also lack a proper tutorial-like documentation that would explain how to build the system, and how to use the different functions.
- Moreover, for the advanced examples shown in Fig. 3, I found it hard to find the corresponding code in the repository: I eventually found the code for Fig. 3b by clicking on names that seemed relevant, but I gave up to find Fig. 3a after 5 minutes. It should not be that hard to find these examples.
- The package provides functionality to mimic experimental signatures, but I find this intransparent: The description in IV.A is very hard to follow. What is exactly done? Can this be explained with formulas/sketches? Moreover, Fig. 3b does some tricks to simulate the response to a QPC, but this is only explained in a single sentence in the caption
- The authors argue for the validity of their algorithm in the appendix, and show limits on the condition number of the capacitance matrix. They argue that this is usually fulfilled in experiment, but does the code actually check this criterion? Given that correctness is essential for the package, the default algorithm must be completely robust, and this check seems essential.
- I find it hard to judge the threshold algorithm. Is it possible to warn the user if the threshold is wrong, or is it up to the user completely? There are estimates for thresholds, but they are not good enough to be used automatically?

- Improve docstrings in code
- Explain usage of code better (either in paper or in a separate documentation): add tutorials, explain the concepts to build the system better, show several explicit examples with extended explanation
- Make code of all examples in the paper easy to find
- Explain in detail how the experimental signatures (charge sensor dot) are calculated. Note that I found the term ''non-charge sensor dot'' very confusing. I guess you mean the regular dots?
- Eq. C.3 talkes about differentiating L, but there is no L introduced in C.
- address the issues regarding validity mentioned in the report.

Ask for major revision

1. Implemented useful algorithm for quantum dot array computations
2. Faster algorithm than state of art
3. Well written and overall clear paper

1. Several modules of the package are not sufficiently tested
2. Lacks package documentation
3. Unclear if and why the thresholded algorithm is always valid

## Summary

The paper introduces a Python package and two useful algorithms for finding the ground state configuration of weakly coupled quantum dots. This is a costly computation relevant to the quantum dot arrays community. This work reduces the time costs of such simulations significantly, allowing for the creation of larger data sets and data analysis.

Because the paper introduces a software package, QArray, I have additionally reviewed its code. The Github repository describes the package, indicates how to install it, and contains the package's license, automated tests, examples, and entire code.

The package has unit tests that are run systematically using Github actions. I have, however, found that several files have large untested amounts of code. This can be confirmed running "pytest --cov --cov-report=html". While some of these files contain only a few functions, some of these are important functions for the package functionality, computing ground states and charge configurations. Without tests, the package's code may become unreliable over time and its current functionality is hard to validate.

While most of the code in the repository has comments about usage and input types, several public functions lack docstrings. This can be confirmed installing ruff and running "ruff check . --select D103". Documentation may increase the package's visibility and help potential users and contributors. The examples currently in the repo contain code, but lack context to serve as documentation. Having complete documentation is a requirement for the acceptance criteria of SciPost Physics Codebases.

## Questions

1. Is the integer minimum unique? If the configurations of two dots is completely symmetric with respect to gate voltages, would the default algorithm and thresholded algorithm find both configurations or would they only find one? It is not clear to me that the thresholded algorithm always returns the correct integer number configuration.
2. Is there an intuitive way to understand why the thresholded algorithm works for any potential? Fig 2b delivers the point, but the potential is fairly specific.
3. Is it possible to combine quantum dots where some are electron dots and others are hole dots? The fact that $\vec{Q} = \pm e \vec{N}$ suggests not, because elements $\vec{N}$ are defined as integers. Is this a limitation?

1. I would like to ask the authors to improve and extend the package tests.
2. I would like to ask the authors to document public functions and write tutorials, not just examples. The authors could also consider writing package documentation, e.g. using https://readthedocs.org/.
3. Not all figures are referenced in the main text, e.g Fig. 1a and 1b., and Section II would benefit from referring to Fig. 1a. Please ensure that all figures are referenced.
4. Gray and black lines in Fig. 1a are hard to distinguish. I would like to suggest using a different color or dashing one of the lines.
5. The paper contains a few typos ("Compted"), please fix these.
6. The references are not formatted, please format them.

Ask for major revision

1 - the article follows the lines of the newspaper
2 - the proposed method seems to offer a significant advantage over current practice
3 - comparison with experimental data is proposed
4 - the code is carefully commented and accompanied by examples.

- the code lacks a complete description of all available functionalities and the general structure of the implementation (Doxygen type)

In this paper, the authors present a code for the simulation of quantum dot arrays represented by a capacitance model in order to deduce charge stability diagrams.
Instead of a brute force search for the ground state involving the study of all possible occupied states, it is proposed to obtain a continuous minimum of the free energy, and then deduce a discrete solution by exploring the neighborhood of this continuous solution, which considerably reduces the algorithmic cost. A second method is also proposed, using a threshold to further reduce the number of configurations to be covered, offering an advantage in some cases.
The stability diagrams obtained experimentally are compared with the method and found to be in agreement. A performance study is also carried out to demonstrate the benefits of the approach. The appendices provide analytical and numerical proofs of the validity of the approximations made by the techniques.
This article is accompanied by a QArray python package whose implementation also uses Rust, a compiled language and offers a GPU implementation with Jax.
Given the editorial quality of the article, the scientific interest associated with it and the package provided, it seems to me that this article following the guidelines of the journal has its place in SciPost Physics Codebases. I would like to suggest a few comments and changes.

1 - Introduction : it would be interesting to have a few sentences in the introduction on the general background to the usefulness of charge stability diagrams.

2 - In Part II, it may be useful to restate the conditions for studying the system in the classical constant capacitance model approach.

3 - It seems to me that the formula for F(q_d,V_g) should also be recalled before injecting equation (3) and obtaining (4).

4 - In part IV .B. equation (10) reintroduce Vg in the arguments of F.

5 - On which configuration is the summation performed to obtain the softmin in the case of thermal enlargement? It seems to me that it refers to all the configurations around the continuous optimum, otherwise the problem back to the brute-force case. This is not very clear in the paragraph.

6 - I think it would be useful to add a few sentences on the benefits of charge sensors, optimal gates voltages and virtual gates. Perhaps a figure would be welcome here.

7 - Part VI: it seems to me that the article is rather allusive on the minimization method used (OSQP). I think this is an important point in the method (when the explicit result cannot be used) and the general principle should be explained. In addition, it doesn't say how precise the continuous optimum must be, how many iterations must be performed, or how much computing time must be devoted to this step.

8 - the origin of the error bars in the figures and the method of obtaining them should be more explicit.

9 - I am uncertain by Figure 5. Smaller values of t give a faster result. However, according to the authors, this is linked to a more approximate result. I think it would be good to be able to see on the figure the competition between calculation time and error committed than just running time.

10 - Appendix C : Reintroduce Q notation, introduce L and lambda

11 - the code lacks a complete description of all available functionalities and the general structure of the implementation (Doxygen type)

12 - I find it confusing that some rust code is in .py and not .rs. In order to see which part of the code is in rust, python or jax, this could typically appear in the documentation

Ask for minor revision