Installation

Applicable version · ArcQML 0.1.0

Release directory

Read Release status and license before use or distribution. Original public source is for noncommercial use only; the official closed-source Runtime has a separate noncommercial binary license. Each component in the wheel retains its own license.

This release is an experimental Windows preview using Rust 1.98.0 and CPython 3.11; Linux acceptance is deferred. The Linux directories and commands below are historical environment examples and do not imply that this release includes Linux artifacts. Install the matching libraries and wheel supplied with this release, without mixing historical artifacts. See the ArcQML repository for current installation steps and Security limitations for known memory-safety issue S01.

All paths below are relative to the ArcQML release directory you obtained. Replace PATH_TO_YOUR_FILES with its actual location and preserve the relative directory structure inside the package.

PATH_TO_YOUR_FILES/ArcQML/
├── crates/                 # Rust interface and supporting features
├── libs/
│   ├── x86_64-pc-windows-msvc/
│   │   └── arcqml_runtime_private.lib
│   └── x86_64-unknown-linux-gnu/
│       └── libarcqml_runtime_private.a
├── wheels/
│   └── arcqml-0.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
├── examples/               # Complete examples
├── docs/                   # Technical manual, API documentation, and tutorials
├── Cargo.toml
├── LICENSE-RUNTIME
└── ...

Binary libraries in libs must match the operating system and CPU architecture. Do not rename them or mix them with other ArcQML versions. The historical directory example above lists Rust Runtime paths for Windows x86_64-pc-windows-msvc and Linux x86_64-unknown-linux-gnu. Its Linux wheel is only for CPython 3.11 on Linux x86_64 and cannot be installed on Windows. Use the Windows Runtime and wheel supplied with this Windows preview.

Support for other operating systems, CPU architectures, and Python versions depends on the build artifacts actually provided in future releases.

Rust environment and Runtime configuration

The Rust interface uses Rust 2024 edition. The current stable toolchain is recommended; these examples were verified with Rust 1.98.0. Windows users can follow the official Rust installation page to install rustup, select the MSVC toolchain, and install the corresponding Visual Studio C++ Build Tools and Windows SDK. Linux users can use the official installation command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, run rustc --version and cargo --version to check availability. From the release root, set ARCQML_RUNTIME_LIB_DIR to the platform-matching subdirectory in libs. This variable selects the precompiled Runtime for linking.

Windows PowerShell:

Set-Location "PATH_TO_YOUR_FILES\ArcQML"
$env:ARCQML_RUNTIME_LIB_DIR = (Resolve-Path ".\libs\x86_64-pc-windows-msvc").Path
cargo check -p arcqml

Linux:

cd PATH_TO_YOUR_FILES/ArcQML
export ARCQML_RUNTIME_LIB_DIR="$PWD/libs/x86_64-unknown-linux-gnu"
cargo check -p arcqml

The environment variable applies only to the current terminal session; set it again in new terminals. cargo check checks source and types, not final application linking.

Your own Rust project can reference the release interface through a path dependency:

[dependencies]
arcqml = { path = "PATH_TO_YOUR_FILES/ArcQML/crates/arcqml" }

Set ARCQML_RUNTIME_LIB_DIR before running that project as well. If you copy or move the release package, update both the dependency and Runtime paths.

Python environment and wheel installation

The following historical example targets Linux x86_64, CPython 3.11, and a manylinux2014-compatible glibc environment. It does not apply to this Windows preview. A separate Conda environment is recommended to avoid interference from existing Python or NumPy versions. See the ArcQML repository for current Windows commands. All historical commands below run from the corresponding release root:

cd PATH_TO_YOUR_FILES/ArcQML
conda create -n arcqml-example python=3.11 -y
conda activate arcqml-example
python -m pip install --upgrade pip
python -m pip install ./wheels/arcqml-0.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

The wheel statically embeds its matching ArcQML Runtime. Python users do not need ARCQML_RUNTIME_LIB_DIR, Rust, Maturin, or source builds. Verify import with python -c "import arcqml; print(arcqml)". If pip reports an incompatible wheel, check python --version, python -c "import platform; print(platform.machine())", and the operating system.

Data flow through a trainable forward and backward pass

Circuit.parameters()
    │  Bind parameter values to Gates at execution time
    ▼
(Batch)StateVectorSimulator.run(circuit, observable)
    │  Interface validates and binds parameters; Runtime evolves the state; public Rust computes the expectation
    ▼
F64 scalar or [B] F64 Tensor
    │  Join ordinary Tensor losses in a single automatic-differentiation graph
    ▼
loss.backward()
    │  Classical VJP → Runtime quantum adjoint → Parameter.grad
    ▼
optimizer.step(circuit.parameters())

The entire quantum circuit enters the autograd graph as a custom Tensor operation. The public Rust layer validates parameters and shapes, evaluates observables, connects the graph, and updates the optimizer; the closed-source Runtime applies gates, executes circuit plans, and computes adjoint backpropagation. The parents of run include the initial state and circuit parameters, so external losses need not know how gates execute internally, and quantum expectations remain available to classical differentiable computation.