# QueRa codebase review
https://github.com/QuEraComputing/bloqade-python
https://github.com/QuEraComputing/Bloqade.jl

Hi Roger, Kai and Philip :)

Sorry for the long wait, I've taken a look at the two repositories. I think I'll start with the good and then the shortcomings later :)

I think you did a good job towards users and customers but there is some improvements to be made towards contributors and programmers of the codebase.

I'm sure the physics theory and implementation makes up a big part of the code and it's unfortunate that the lack of my physics understanding is prohibiting me from assessing the codebase more accurately.

I hope you enjoy :)
## +

### Good support
I think the two repository does a really good job, user and customer facing wise. There is a lot of documentation and a lot of toolings, including visualization and GUI. Package managing and integration with 3rd party tool and device like CUDA seems very easy to execute.

### CI/CD
I also really like the CI/CD pipeline. The repo has testing and linting support as well as docs ci/cd. It makes me feel really safe.
Code cov is also a big plus.

## -

I'm more familiar with Python than Julia so I think the majority of the criticism will probably be within the Python codebase.

### Pauses?
I think there's some pauses on the two repository for now? For example, For bloqade.jl, at the time of inspection Feb 9 2025:
- last issue was filed in Dec 21 2024.
- Last human update on the master branch is Sep 14 2024.
- Last technical update on the master branch is Aug 5 2024. SHA d86cccca7f856fe8256305734adc4037cd587692

### Websites and docs

I think the two repository shares different websites? For python it’s https://bloqade.quera.com/latest/. For Julia it’s https://queracomputing.github.io/Bloqade.jl/dev/. It'd be nice if we can somehow consolidate the two together?

### Consolidating misc files

In bloqade-python, I see a lot of miscellaneous items like CITATION.bib or codecov.yml, maybe they can be in some misc/ folder?

### Dead files

I think there's some empty files sitting in the codebase. For example, in bloqade.py, there's a dead folder in https://github.com/QuEraComputing/bloqade-python/tree/main/src/bloqade/compiler/codegen/julia.

The .gitsubmodule file is also empty in the same repository.

### Refactoring
In `emulation_ir.py`, there’s a function called construct_rab() with (271-131+1) lines. I think there's some opportunities for refactoring here.

### Testing

A lot of tests in the repository doesn't seem to have any comments and I'm not sure what it is that we're testing for.

### Code structure

I think a nice readme on the code structure / code topology about where certain things go would be nice.

### Contributing guidelines

I think we're missing a CONTRIBUTING.md from the repo. Certain things come to mind:

- Commit messages: Do you have a guideline on how a commit message should look like?

- Code style: For python, what coding guidelines are you following, for example https://google.github.io/styleguide/pyguide.html
- How can an open source contributor build your code base, how do they fetch the dependencies.

- Typechecking and typing ci/cd: I noticed you’re using type-hinting a lot, but I don’t see any static analysis tool on these type hints?

- Testing: I think some clarifications towards the contributor would be nice: Are you testing end to end? How are you performing unit tests? What’s the general procedure to add a test? For a contributor, how are they testing your code? Are you using pytest? Or some other tooling?

# Ending
I really enjoyed reviewing the codebase :) Thank you for reading.