Skip to content

manual-setup.md

Latest commit

 

History

History
92 lines (75 loc) · 3.82 KB

manual-setup.md

File metadata and controls

92 lines (75 loc) · 3.82 KB
Raw

Manual setup with Rust and Cargo

Advantages and limitations

  • Advantages: builds and calculations run directly on Linux, macOS, or Windows. No container or VM is required. This is suitable when native host execution, local profiling, or existing cluster build tools matter.
  • Maintenance: you install native build dependencies and optional tools yourself. The repository selects Rust through rust-toolchain.toml and Cargo dependencies through Cargo.lock, but does not pin the entire host environment.
  • Platforms: native Cargo supports the platforms in the compatibility table, including Windows and Intel macOS. Python development tools run natively on Windows; PySCF comparisons currently require Linux, macOS, or WSL2.
  • HPC use: this route can use the site's existing compiler environment without Docker or Nix. Build and run according to cluster policy, using the scheduler's assigned resources. A locally built binary still needs a compatible target OS, architecture, and runtime dependencies.

Install and build

Install a C/C++ build toolchain and CMake for native dependencies. On Linux, use your distribution's development packages; on macOS, install the Xcode Command Line Tools and CMake. On Windows, install Visual Studio C++ Build Tools with the Windows SDK, CMake, and the Rust MSVC toolchain.

Install Git and Rust through rustup, then use Cargo directly on Linux, macOS, or Windows:

git clone https://github.com/mveril/RustiQ.git
cd RustiQ
rustup show
cargo build --locked
cargo test
cargo run --locked -- basis import tests/data/sto-3g.json
cargo run --locked -- run samples/h2/sto-3g/calculation.toml

rustup show causes rustup to notice rust-toolchain.toml and install the requested stable toolchain and components if necessary. This route is enough to build and run RustiQ, but the extra tools and the PySCF reference environment from the Nix development shell must be installed separately if you need them. The repository uses uv for that environment on Linux, macOS, WSL2, and native Windows:

uv sync --locked
uv run --locked ruff --version
uv run --locked pytest tools/test_book_links.py tools/test_release_smoke.py tools/benchmarks

The project supports Python 3.12 through 3.14. The default groups install JupyterLab, ipykernel, Matplotlib, SciPy, NumPy, pytest, and Ruff. The lock also includes PySCF 2.14.0 on Linux and macOS, but that pinned release has no Windows wheel, so uv excludes it on native Windows. Binary wheels are required; source builds remain disabled. Run the reference suite with:

uv run --locked pytest tools/reference

On native Windows, only the PySCF calculation tests in tools/reference/test_compare_pyscf.py and tools/reference/test_integrals.py are skipped. Helper tests in test_compare_pyscf_helpers.py, report validation, and NumPy persistence tests, including Rust-generated persistence artifacts, remain available. Use WSL2 for PySCF comparisons and the scientific report generator (tools/reference/report.py). These Python tools support development and validation; building the RustiQ executable still requires the Rust toolchain and the Cargo commands above.

Build for calculations and install the executable

From the repository root, use an optimized build for substantial calculations or timing comparisons:

cargo build --release --locked
cargo run --locked -- basis import tests/data/sto-3g.json
cargo run --release --locked -- run samples/h2/sto-3g/calculation.toml

To install into Cargo's binary directory:

cargo install --locked --path .
rustiq --help

The executable is named rustiq (or rustiq.exe on Windows); use lowercase on case-sensitive systems. Ensure Cargo's binary directory is on PATH. Keep the checkout for the tutorial's sample files.