[unitaryDESIGN] Documentation Improvement for AI Agents#66
[unitaryDESIGN] Documentation Improvement for AI Agents#66ahkatlio wants to merge 17 commits intoharmoniqs:mainfrom
Conversation
There was a problem hiding this comment.
Looking great, a few things to fixup to get this ready.
If you haven't yet, try building the docs locally:
./docs/get_docs_utils.sh
julia --project=docs docs/make.jl
a lot of what I said can be cross-referenced there will a build. My review comments should guide you: primarily make sure that the files end up in the right paths that I recommend -- secondarily make sure that the literate examples you give are using similar literate syntax as done elsewhere so that everything renders correctly and is easy to follow/maintain (my comments should help guide here too).
Give me a ping if you have any additional questions
| # For cavity/oscillator systems, plot the Wigner quasi-probability distribution: | ||
|
|
||
| #nb # Uncomment if QuantumToolbox is available: | ||
| #nb # fig = plot_wigner(traj, 1) # Plot at first timestep |
There was a problem hiding this comment.
var should probably be traj_ket instead of traj to get back the wigner plot
| #nb # lines!(ax, 1:k, fidelities[1:k]) | ||
| #nb # end | ||
| #nb # | ||
| #nb # animate_figure(fig, 1:traj.N, update_frame!; fps=30) |
There was a problem hiding this comment.
same as https://github.com/harmoniqs/Piccolo.jl/pull/66/changes#r2813337379. helpful note here - if your code is generating animations, try saving this animations to a file in the docs assets directory like so:
fig = animate_wigner(traj_ket; fps=24, xvec=-4:0.1:4, yvec=-4:0.1:4)
save("<path-new-asset-file>.gif", fig)
and then animation can be included in the plain markdown via an image ref
or maybe there is a way using the WGLMakie backend to skip all of that. Either way works as long as the animations display correctly.
|
Hello, I have changed the files according to your suggestions. Check again, please. |
|
Thanks @ahkatlio - a few comments you will need to add the following packages to the docs/Project.toml in order for the docs pages to build on your end and these examples to render appropriately.
Also, changes that you made look great. Still some more lines to uncomment in the docs/literate/guides/visualization.jl literate file: I have resolved the other comments that your commit addresses. The other review comments still open are currently unresolved. Let me know if you have any questions!! |
|
Hello @jack-champagne, I have added packages to Project.toml and Uncommented lines in visualization.jl. Please check 🙏 |
Welcome to Codecov 🎉Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests. ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment Thanks for integrating Codecov - We've got you covered ☂️ |
|
hello @jack-champagne, how do I pass all the checks? |
|
it looks like these lines that are still commented out could still be uncommented to get the docs to build and render nicely: #66 (comment). I you want to see the docs, you can look at the job too - https://github.com/harmoniqs/Piccolo.jl/actions/runs/22136909817?pr=66, for this branch it was stored at: https://github.com/harmoniqs/Piccolo.jl/actions/runs/22136909817/artifacts/5565423921 |
|
I made this comment accidentally on one of your other pull requests: The checks don't worry about - just needs to be auto formatted before it gets merged. I think the only thing left outstanding are the comments I left on these two lines (I noted them again in the new diff) https://github.com/harmoniqs/Piccolo.jl/pull/71/changes#r2862149540 I left some details in this comment from earlier last week (sorry I didn't get back to you sooner!): #66 (comment) Let me know if you have any questions! |
|
@jack-champagne, Previously, the comments just said "To save animation to file:" or "To save animation to file instead:", but now they explicitly mention "To save animation to file, use CairoMakie with mode=:record:" for both the control evolution and Bloch sphere animation examples. This makes it more obvious that users need to switch backends and use the :record mode parameter, reducing potential confusion about why their animations aren't saving. |
|
Hi @ahkatlio, to pass the Documentation / Documentation (pull_request), you will need either comment out all instances of code that is relying upon GLMakie to do renders, or substitute with CairoMakie (leaving in a commented out GLMakie example if you will is fine.) Documentation won't build in a headless environment with no glfw + X11 display var as it relies on OpenGL, display output, and a graphics card - which these github runners won't have. |
2 participants
Closes #61
Summary
Improved documentation across Piccolo.jl's visualization components to be more AI-agent-friendly. The changes ensure AI coding assistants (Copilot, Cursor, Claude, etc.) can effectively help users write visualization code by providing comprehensive docstrings, complete examples, and structured reference documentation.
Changes
1. Enhanced Docstrings with Complete Examples
Added comprehensive docstrings to all visualization functions with:
Functions enhanced:
animate_figure- Generic animation with custom update functionsanimate_name- Progressive trajectory component animationplot_bloch- Bloch sphere visualization with mathematical contextanimate_bloch- Animated Bloch sphere evolutionplot_wigner- Wigner quasi-probability distribution plotsanimate_wigner- Animated Wigner function evolution2. Created AI-Friendly Reference Documents
VISUALIZATION_CONTEXT.md
A comprehensive AI-agent reference containing:
llms.txt
LLMs.txt standard-compliant document with:
3. Enhanced Visualization Guide
Updated visualization.jl with:
animate_figureBenefits for AI Agents
Files Modified
Files Added
Testing
Documentation Standards Applied
All enhanced docstrings include: