N/M user guide for VS Code
Install the N/M extension, test your first program, step through the debugger and resolve common problems.
Install the extension
In VS Code Extensions, search for N/M Quantum Language. Check the publisher QuantumSoftware and extension ID quantumsoftware.nm-quantum-language. Use the regular Install button.
Desktop VS Code 1.96 or later is required. The language server and debugger are bundled; no separate Node.js installation is needed. Browser-only VS Code and virtual workspaces are unsupported.
Verified regular releases: Marketplace 0.6.0 Β· Open VSX 0.6.0.
Download 0.6.0 as a VSIX from Open VSX and use Extensions: Install from VSIX⦠in VS Code. Check the extension identity; regular installation does not require switching to a pre-release channel.
Your first program and test
Open a project folder you trust. Open the Command Palette with Ctrl+Shift+P (macOS: Cmd+Shift+P), run N/M: Create Quantum Example and save the file as hello.nm. This is the program generated by the extension.
hello.nm
1module hello_quantum;2fn main() {3 test "balanced qubit" {4 let q = qreg[1];5 H(q[0]);6 assert probability(|0>) > 0.45;7 assert probability(|1>) > 0.45;8 }9 return 0;10}Run N/M: Run Current File Tests to execute balanced qubit. The H gate makes both outcome probabilities 0.5, so both assertions should pass. Tests run in separate processes and can be cancelled.
Selected-test support requires extension 0.3.0 or later. Select top-level checks using Test Explorer Run/Debug profiles or the test CodeLens. Unselected siblings do not execute; shared setup and original source lines remain. Debugging uses the test report and recording from the same execution. Stale identities and direct selection of nested checks fail.
Tools introduced in 0.6.0
The numerical operations, workspace auto-import and complete project templates introduced in 0.6.0 remain available in current CLI 0.7.1 with Core 0.7.0. The language contract stays 0.2.0 and preview/experimental maturity remains unchanged.
Create a complete project
Choose Bell, parametric training or numerical computing. Each project includes src/main.nm, shared src/helper.nm, tests/main.test.nm, nm-workspace.json and a README.md in the selected language.
Run N/M: Create Project from the Command Palette, then choose a template, a parent folder and a project name. For example, bell-project creates a bell-project subfolder inside that parent. Names use 1β64 lowercase letters, digits, dots, underscores or hyphens and must start/end with a letter or digit. README language follows the VS Code interface language.
Open the created folder. Open src/main.nm for diagnostics, then open tests/main.test.nm and run N/M: Run Current File Tests. README terminal commands require a separate CLI installation; the bundled language server does not add an nm terminal command.
Creation does not overwrite occupied directories or run source automatically. The numerics README explicitly lists --experimental-classical-functions and --experimental-typed-classical-values. Neither the manifest nor a template grants experimental permissions; saved false settings remain off.
Import from your workspace
Start typing a public function, record or enum from the same workspace and accept its completion. The editor inserts the required use workspace.β¦ line. Private symbols stay excluded; alias, visibility and cycle checks remain. Open-file suggestions remain available while the disk index is being prepared.
Requires extension or standalone language server 0.6.0. Add these two files to the generated project's src folder and open both in the editor. Enable classicalFunctions and typedClassicalValues; this public declaration also needs moduleVisibility. The default VS Code profile enables them; previously saved false values must be changed explicitly.
src/math.nm
module guide_math;public fn double(value: Float) -> Float { return value * 2.0;}src/import-demo.nm
module import_demo;use workspace.guide_math;fn main() { let q = qreg[1]; let result: Float = double(0.5); return result;}The main example shows the accepted completion. To try it, remove use workspace.guide_math; and shorten double to dou. With the cursor after dou, press Ctrl+Space and select double from workspace.guide_math. Completion fixes the name and inserts the import together. Check the source module when multiple symbols have the same name.
The result variable has value 1.0. If no suggestion appears, check that you opened the project folder, the files are inside the manifest's src source root, and the relevant features are enabled. Auto-import is an editor action. The guide's CLI example makes the same grants explicit; saved or supplied false feature choices are not enabled automatically.
New numerical operations
- eigvecsh
- Returns column eigenvectors of a Float/Complex Hermitian matrix in the same order as eigvalsh. Phase and degenerate eigenspace bases are not unique. Parameter-dependent analytic eigenvector derivatives are unsupported.
- solve
- Computes first-order real derivatives of A*x=b through A*dx=db-dA*x. Primal and derivative right-hand sides share a pivoted factorization within one call. Complex and second derivatives are outside this scope.
- lstsq
- Uses column-pivoted QR for full-column-rank Float least squares on square or tall systems. Wide/rank-deficient matrices and parameter-dependent analytic derivatives are unsupported.
Existing 1β16 matrix dimensions, 256-element and shared work budgets remain unchanged. Extension tests and recorded debugging do not start the separate finite-shot training host; select that host with CLI --train.
Open the matrix and derivative guide βDebug step by step
Save this circuit as debug.nm and set a breakpoint on its H line. Select the N/M configuration in Run and Debug, or create this .vscode/launch.json and press F5 with debug.nm open.
debug.nm
1module debug_bell;2fn main() {3 let q = qreg[2];4 H(q[0]);5 CNOT(q[0], q[1]);6 return q;7}.vscode/launch.json
1{2 "version": "0.2.0",3 "configurations": [4 {5 "type": "nm",6 "request": "launch",7 "name": "N/M",8 "program": "${file}",9 "stopOnEntry": true10 }11 ]12}F11 steps into calls, F10 steps over them and Shift+F11 steps out. Variables and the call stack show recorded values. Restart rewinds the same recording; stop and start a new recording after editing the program or its settings.
The debugger records a local simulator execution once. Stepping does not repeat measurements or connect to physical quantum hardware.
Language features and settings
New installations enable these six features. Previously saved false choices remain off. Other nm.experimental.* settings are off by default. Search for N/M in VS Code Settings to change them.
nm.experimental.classicalFunctionsnm.experimental.typedClassicalValuesnm.experimental.functionResultsnm.experimental.moduleVisibilitynm.experimental.parameterGroupsnm.experimental.computeApply
Use N/M: Show Capability Status to check maturity and limits. The regular installation channel does not make every feature stable.
Version 0.3.0 and later: N/M: Show Toolchain Session shows the actual extension package, initialized server language/Core versions and LSP contract separately. CLI/MCP installations and unavailable server package metadata are explicitly unobserved.
If something goes wrong
The server does not start
Run N/M: Restart Language Server and read Output β N/M Language. A custom nm.languageServer.path must be an existing absolute file path; remove the override to use the bundled server.
Tests or debugging do not run
Save the file with a .nm extension, check that the N/M language is selected and that you trust the project folder. The extension does not execute code in Restricted Mode.
A language feature is rejected
Check its N/M setting. Saved false choices are not enabled by updates. Look up the reported error code in the diagnostics guide.
No release version is available
Select the current regular release. If a pre-release is installed, use Switch to Release Version.
The .nm file icon is missing
The blue NM file badge requires extension 0.4.1 or newer. Update the extension and run Developer: Reload Window. If the active file icon theme hides language icons, choose Preferences: File Icon Theme β Seti (Visual Studio Code). The extension does not switch themes automatically.
In the contact form, include your VS Code and extension versions, operating system, error code and a small reproducible example. Do not send API keys or private project files.
Report a problem βFree to use
Personal, educational and commercial use is free. QuantumSoftware retains code and asset rights; modifying or redistributing its source requires separate permission. Your own N/M programs and results remain yours.
Read the distribution license β