@qctrl/visualizer
Advanced tools
An animated and interactive quantum state visualisation built with THREE.js
This is the base library/module for the Q-CTRL JavaScript Visualizer. It is framework/library agnostic and can be implemented in a vanilla JavaScript app/website
importnpm login your npm account must be linked and have access to the qtrl org (This will be unnecessary if the package becomes publicly available)lodash if it is not already installed in your project) into your project with yarn add @qctrl/visualizer or npm i @qctrl/visualizer
import feature and will also need a transpiler such as Babel and/or a build pipeline such as Parcel (easy) or Webpack (Advanced)import Visualizer from '@qctrl/visualizer'The UMD version is hosted at: https://cdn.jsdelivr.net/npm/@qctrl/visualizer/umd/visualizer.min.js
You must also include lodash before the Visualizer script. See example below:
<!-- at the bottom inside of the body of your main index.html file -->
...
<script src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@qctrl/visualizer/umd/visualizer.min.js"></script>
<script src="path/to/index.js"></script>
</body>
Note: For a more in-depth version of this guide please see the user guide here
In your project's JavaScript, get a reference to a <div> element/DOM-Node that will be used as a wrapper for the visualizer (or create a new <div> element). The Element should have width and height CSS properties set as the visualizer will use the wrapping <div> width and height parameters to set it's own size parameters internally. Note: The wrapper element will have its style property position set to relative by the visualizer
<!-- inside the body of your main index.html file -->
<body>
...
<div id="visualizer-wrapper" style="width: 500px; height: 500px;"></div>
...
</body>
const visualizerWrapper = document.getElementById("visualizer-wrapper");
Next create a new Visualizer instance, passing in the wrapper reference, like so:
const myVisualizer = new Visualizer({ wrapper: visualizerWrapper });
This will create and initialize a new Visualizer object and store a reference to it in the myVisualizer variable. Also, a canvas/DOM element that the visualizer will be rendered to will be attached to the passed in wrapper element
If you now preview the HTML file you should be able to see a single Bloch sphere on the page
A Visualizer instance has an update method that can be used to pass in new "props" or settings, for example you can set whether the animation is playing or not with the isPlaying prop. To try that now, below from where you have created your Visualizer instance, use this code snippet to have the visualizer start playing when the page loads:
myVisualizer.update({ isPlaying: true });
Now when your HTML preview loads the Visualizer will start playing immediately. Since no data was provided to the Visualizer instance when you created it, it will have generated some default data: A single 180 degree rotation around the x axis. (If you have predefined data you can pass it in to the constructor when creating a new Visualizer instance and this will be used for the visualization. See the DOCS section on Data for more info
If you do not have access to data you can instead pass in a collection of gates to the gates prop either in the update function or the constructor. To try this, where you have initialized the visualizer instance update the code like so:
const myVisualizer = new Visualizer({
wrapper: visualizerWrapper,
gates: [{ gateType: "X" }, { gateType: "H" }, { gateType: "Z" }, { gateType: "T" }]
})
You can also pass in an optional rotation percentage, as a fraction, for each gate which will then tell the visualizer to rotate the gate by only the specified percentage of a standard rotation for that gate operation:
gates: [{ gateType: "X", rotationPercentage: 0.3 }, { gateType: "H", rotationPercentage: 0.8 }, { gateType: "Z", rotationPercentage: 0.5 }, { gateType: "T", rotationPercentage: 0.4 }]
You could also pass in an instantGates prop set to true and this would cause the gates animation to jump to each gate without animating a path for it
The Visualizer will generate the correct data to animate from the gate sequence you passed in. Now when you preview your HTML you will see an animated visualization of the above gate sequence. See the DOCS section on Gates for more info and available gate types
At this point you could also simulate a measurement on the Bloch sphere. There is a special "gate" operation type you can pass in: MEASUREMENT. This will simulate taking a measurement of the qubit from the final state after the gate sequence has been run. The state indicator will jump to the north or south pole depending on the probability of the measurement calculation. The MEASUREMENT operation will only have an effect if added at the end of the gate sequence
You could update the above line of code to be:
gates: [{ gateType: "X", rotationPercentage: 0.3 }, { gateType: "H", rotationPercentage: 0.8 }, { gateType: "Z", rotationPercentage: 0.5 }, { gateType: "T", rotationPercentage: 0.4 }, { gateType: "MEASUREMENT" }]
cd into the repo folderyarn to install the necessary packagesWhen you run yarn dev first of all a symlink to the project directory will be created and registered with yarn using yarn link. The code will then be built and a watch process for any changes will be started. You can then use the symlinked version of the visualizer module you are working on by running yarn link @qctrl/visualizer in your dev app project
Documentation generation relies on Sphinx. Automated builds are done by Read The Docs.
Note: If you have made changes to the code base and updated or added JSDoc strings, you will need to first rebuild and convert the JSDoc strings to .md format using the script in the packages.json file: From the root of the project run yarn build:jsdoc. This command will ony work from a Unix based OS. If using windows you will need to use a bash emulator or Linux subsystem for windows
To build the docs locally:
nodeJS, python3 and the following modules must be installed on your system for the build to succeed: Sphinx, recommonmark and sphinx-js (Also requires the jsdoc NPM package installed globally for node as stated in the sphinx-js documentation)
Execute the make file from the docs directory:
Mac/Linux:
cd docs
make html
Windows:
cd docs
make.bat html
The generated HTML will appear in the docs/_build/html directory.
javascript-visualizer module to the npm registry, you first need to update the version number in package.json. The best way to do this is to run npm version <update_type> update_type should be patch, minor or major, see here for semantic versioning explanationnpm run build:publish Note: yarn currently will not work for this publishing script. This will first build/compile using babel then publish the compiled lib to NPM. Note: You need to be logged in to NPM and your account needs to be linked and have access to the QCTRL Org./build directoryHere is the hierarchy of conventions to follow for coding style. If in doubt about a certain style, follow this from the top down until you find an answer everyone can agree to.
When performing a code review and making a suggestion on coding style, try to find the corresponding rule from the list below and link to it in the pull request.
Any new decisions which can be applied as a convention should be posted in this section.
See LICENSE.
FAQs
The Q-CTRL Visualizer is a package for displaying animated 3d Bloch sphere visualizations.
The npm package @qctrl/visualizer receives a total of 126 weekly downloads. As such, @qctrl/visualizer popularity was classified as not popular.
We found that @qctrl/visualizer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Newly introduced telemetry in devenv 1.4 sparked a backlash over privacy concerns, leading to the removal of its AI-powered feature after strong community pushback.
Security News
TC39 met in Seattle and advanced 9 JavaScript proposals, including three to Stage 4, introducing new features and enhancements for a future ECMAScript release.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.