Contribution Guide

Introduction

We welcome contributiuons to Piccolo.jl! This document outlines the guidelines for contributing to the project. If you know what you want to see, but are unsure of the best way to achieve it, add an issue on the relevant repository (like QuantumCollocation.jl) and start a discussion with the community!

Tips for Visual Studio Code

Julia extension You can run Julia notebooks and much more with the Julia extension. Upon opening your project folder in VS code and attempting to run an .ipynb, you will see that VS Code finds the interpreters managed by juliaup and defaults to using the environment based on the Project.toml in the project directory.

Fonts VS Code will not display all characters allowed by Julia. You can change the editor font family in the settings to 'JuliaMono' to get full support. If you don't want to mix and mash, you can create a new VS Code settings profile for working in Julia at File>Preferences>Profile.

Tests Tests should automatically populate in VS Code when working with a Piccolo package. For example, just by adding the QuantumCollocation.jl folder to your workspace, you should see tests appear if you click on the Testing sidebar icon. If you run one of these tests, a new Julia kernel is spawned for the test. You can find the kernel if you click on the Julia sidebar icon (after installing the Julia extensions). Sometimes, for the tests to recognize new changes, you may need to manually kill this kernel to see your changes reflected.

Developing

Install JuliaJuliaup is an installer and version manager. This is one useful way to manage Julia versions and keep up with the latest changes. After installing, run julia to obtain the Julia REPL.

Julia environments(Documentation) Your project's environment is stored in Project.toml. You can interactively add packages to an environment by using the Julia command line REPL and package manager. Start Julia in the project folder. Type ] to enter the package manager. Type activate . to activate or create an environment specified by Project.toml located in the current folder. Separately, you generate a manifest (solving the versions to create a valid environment) by running instantiate; instantiate will check that the environment is correct after you add all the packages you want.

Adding packages(Documentation) The initial cell for a Piccolo notebook might look something like the following:

# Standard packages
using LinearAlgebra
using CairoMakie

# Piccolo
using Piccolo

First off are the standard packages (these are like Numpy and Matplotlib). Open the package manager in the current environment (type julia, ], and activate .), type add LinearAlgebra to install and precompile LinearAlgebra. Same with CairoMakie. Second, let's install Piccolo. We do add Piccolo to get the entire ecosystem as a bundle from the Julia repository.

Sometimes you will want to develop individual Piccolo packages, so our header might look like

# Standard packages
using LinearAlgebra
using CairoMakie

# Piccolo packages
using QuantumCollocation
using NamedTrajectories

These are two packages (QuantumCollocation, NamedTrajetories) inside Piccolo.

As a developer, we want to use the git repositories directly from the harmoniqs Quantum Github page. Clone, then add the local packages to the Project file with e.g. dev ../relative/path/to/repo/QuantumCollocation. This command installs the development version of QuantumCollocation pointing to the local Github code instead of the package repository. You can repeat this for the others, also.

ReviseRevise.jl will let you edit source code, update packages, and reload the changes in a notebook–-automatically! This is a great tool for development. add Revise from the REPL and then include it before any packages you intend to edit:

using Revise
using QuantumCollocation

Documentation

Documentation is built using Documenter.jl and uses Literate.jl to generate markdown files from scripts stored in docs/literate. To build the documentation locally, start Julia with the docs environment:

julia --project=docs

Then (for ease of development) load the following packages:

using Revise, LiveServer, QuantumCollocation

To live-serve the docs, run

servedocs(literate_dir="docs/literate", skip_dir="docs/src/generated")

The extra arguments prevent an infinite loop caused by the generated Literate files. If the index.md is also dynamically generated from the README.md, run

servedocs(literate_dir="docs/literate", skip_dir="docs/src/generated", skip_files=["docs/src/index.md"])

Changes made to files in the docs directory should be automatically reflected in the live server. To reflect changes in the source code (e.g. doc strings), since we are using Revise, simply kill the live server running in the REPL (with, e.g., Ctrl-C) and restart it with the above command.

Writing tests

Tests are implemented using the TestItems.jl package.

@testitem "Hadamard gate" begin
    H_drift, H_drives = GATES[:Z], [GATES[:X], GATES[:Y]]
    U_goal = GATES[:H]
    T = 51
    Δt = 0.2

    prob = UnitarySmoothPulseProblem(
        H_drift, H_drives, U_goal, T, Δt,
        ipopt_options=IpoptOptions(print_level=1)
    )

    solve!(prob, max_iter=100)
    @test unitary_rollout_fidelity(prob) > 0.99
end

Individual tests will populate in the Testing panel in VSCode. All tests are integrated into the base test system for CI, which occurs at each PR submission.

Tests should be included in the same file as the code they test, so problemtemplates/unitarysmoothpulseproblem.jl contains the test items for UnitarySmoothPulseProblem.

Reporting Issues

Issue templates are available on GitHub. We are happy to take feature requests!