Install

Setting up Vikshep

Vikshep has two independent install paths. Start with the loaders — they need no GPU, no build step, and no account.

Prerequisites

+Python 3.10 or later
+Git
+No GPU required for the Geant4 Direct Interface or any loader

Path 1 — Loaders (repo-local, no account)

Clone the public repo and install the ingest package in editable mode. This gives you all data loaders, the DisCo recipes, and the benchmark harness. No engine binary is required.

git clone https://github.com/samvardhan03/Vikshep.git
cd Vikshep
pip install -e backend/ingest

vikshep-ingest is not yet on PyPI — install from the repo clone only. Do not cargo install omnipulse-mcp; that path does not exist on crates.io.

Verify the install

vikshep-ingest --help
vikshep-recipe --help

Both commands should print usage without errors.

Path 2 — Engine wheel (GPU acceleration)

The vikshep wheel bundles the compiled engine and enables GPU-accelerated scattering. Install it alongside the loaders.

pip install vikshep

The first tagged engine binary release is pending. Until it ships, pilot access is available via shekhawatsamvardhan@gmail.com. The PyPI wheel (0.2.0) is available but carries stale metadata; a corrected release will follow the first GitHub Release.

Engine binary (`omnipulse-mcp`)

Download the omnipulse-mcp binary from the Releases page and point the environment variable at it:

export OMNIPULSE_MCP_BIN=/path/to/omnipulse-mcp

Add this to your shell profile (~/.zshrc, ~/.bashrc) or place it in a .env file loaded by your analysis script. The agent reads this variable on every invocation; if it is absent the agent fails loudly with install instructions.

Supported platforms

Platform	Loaders	Engine (GPU)
macOS 13+ (Apple Silicon)	Yes	Planned (Metal)
macOS 13+ (Intel)	Yes	No
Linux x86_64 (CUDA 12+)	Yes	Yes (pilot)
Windows	Untested	No

Troubleshooting

vikshep-ingest: command not found

Run pip install -e backend/ingest from the repo root. Ensure the active Python environment is the same one you installed into (check which pip).

OMNIPULSE_MCP_BIN not set — engine calls will fail

Download omnipulse-mcp from the Releases page and export OMNIPULSE_MCP_BIN=/path/to/omnipulse-mcp. The variable is read at agent startup, not at import time.

ImportError: No module named 'vikshep_ingest'

You are running Python from a different environment than where you installed the package. Confirm with which python3 and pip show vikshep-ingest.

vikshep-recipe tag hangs

The first call downloads sklearn dependencies. It should complete within 20 seconds on a fresh install. If it hangs beyond 60 seconds, check pip install scikit-learn.