# External Tool Setup Monata is distributed as a Python framework. It does not bundle simulator, model-compiler, PDK, foundry, PTM, or commercial model binaries in the public package. Runtime tools are ordinary executables installed by the user and resolved from the local environment. Use this page when you need a simulator or model compiler on a new machine. ## Distribution Boundary Public Monata releases publish only the Python packages `monata` and, when needed, the optional `monata-techlib` package. They do not publish this repository's internal ngspice, OpenVAF, Xyce, XDM, Trilinos, or other native tool packages. Documentation can show how to install or build external tools locally, but the resulting executables, shared libraries, code models, and compiled model artifacts remain user-managed runtime assets. Users and downstream packagers are responsible for preserving the upstream licenses for those tools. ## How Monata Finds Tools - Monata discovers tools from `PATH` or `CONDA_PREFIX/bin`. - Simulator paths can also be passed explicitly through Monata task/backend configuration where supported. - Model files, PDK files, and compiled model artifacts are referenced by path; they are not copied into the Monata package. ## Current Required Backend The current native simulation backend is `ngspice-subprocess`. To run Monata simulations, install an `ngspice` executable that can be found by: ```bash which ngspice ngspice --version ``` If an operating-system package, conda-forge package, or site package provides a version that is good enough for your project, use that. If you need reproducible local circuit packages, prefer the `lizhangmai/skills` `monata-sim-env` and `conda-build` skills and let a coding agent create the pixi workflow below. The `ngspice-shared` backend loads a user-provided `libngspice` shared library at runtime through Monata's default Python FFI dependency. Installing `monata` does not install `libngspice`. ## Recommended: Agent-Managed Local Channel The public [`lizhangmai/skills`](https://github.com/lizhangmai/skills) repository includes a user-facing `monata-sim-env` skill and a lower-level `conda-build` skill that wraps `rattler-build` recipes for ngspice, OpenVAF, Xyce, XDM, ADMS, VACASK, Trilinos, and related packages. Use them through Codex, Claude Code, or another skill-aware coding agent. The agent should build only the native tools required by the requested workflow into a user-owned local conda channel, then consume that channel from pixi. In Claude Code, install the skill through the plugin marketplace: ```text /plugin marketplace add https://github.com/lizhangmai/skills /plugin install monata-sim-env@lizhangmai /plugin install conda-build@lizhangmai ``` In Codex or another agent, install both skills with the open skills installer or that agent's normal skill-install flow: ```bash npx skills add lizhangmai/skills --skill monata-sim-env --skill conda-build ``` Then ask the agent: ```text Use the monata-sim-env skill to set up this Monata environment. CONDA_BUILD_OUTPUT_DIR= ``` Replace `` with a real absolute path before sending the prompt. If the prompt does not include `CONDA_BUILD_OUTPUT_DIR=...`, the agent should ask for it before running build, pixi, or install commands. The skill inspects the Monata workspace before choosing tool packages; the current Monata baseline is `ngspice` plus `openvaf-r`. Do not use `/tmp` for final packages. ## Manual Fallback If you are not using a coding agent, the skill repository also exposes the underlying scripts: ```bash git clone https://github.com/lizhangmai/skills.git lizhangmai-agent-skills cd lizhangmai-agent-skills/skills/conda-build # Pick an absolute persistent directory. Do not use /tmp for final packages. export CONDA_BUILD_OUTPUT_DIR="" # Current Monata workflows need ngspice and OpenVAF/OSDI tooling. python3 scripts/rattler_channel.py build \ --recipe-set circuit-toolchain \ --package ngspice \ --package openvaf-r # Optional: run package tests before using the channel. python3 scripts/rattler_channel.py test-package \ --package-file "$CONDA_BUILD_OUTPUT_DIR"/linux-64/ngspice-*.conda ``` Build more tools only when your workflow explicitly needs them: ```bash # Full Xyce recipe stack. This is not required by Monata's current backend. python3 scripts/rattler_channel.py build --recipe-set circuit-toolchain --up-to xyce ``` ## Create a Pixi Runtime Environment Use the local channel first so pixi can install the circuit-tool packages built by the skill, while resolving ordinary dependencies from conda-forge. Run these commands inside the directory that should own the Monata runtime environment. ```bash pixi init . \ --channel "file://$CONDA_BUILD_OUTPUT_DIR" \ --channel https://prefix.dev/conda-forge pixi add python=3.12 ngspice openvaf-r pixi add --pypi monata pixi run python - <<'PY' from importlib.metadata import version import shutil import monata print(version("monata")) print(shutil.which("ngspice")) print(shutil.which("openvaf-r")) PY ``` Install first-party technology metadata only when you need it: ```bash pixi add --pypi monata-techlib ``` For a conda-only environment, build the `monata` recipe from the same skill and install `monata` through pixi as a conda package instead of using `--pypi`. ## Fallback: Build ngspice From Upstream Source The documentation repository includes a helper script that downloads the upstream ngspice source archive on the user's machine and installs it into a local prefix. Use this only when the local conda-channel workflow is not appropriate for your environment. ```bash cd src/monata-docs # Optional but recommended: pin the checksum from your trusted release source. export NGSPICE_SHA256="" PREFIX="$HOME/.local/monata-toolchain" \ ./scripts/build-ngspice-from-source.sh export PATH="$HOME/.local/monata-toolchain/bin:$PATH" ngspice --version ``` The default script target is ngspice 46: ```bash NGSPICE_VERSION=46 ./scripts/build-ngspice-from-source.sh ``` Set `NGSPICE_URL` if your organization mirrors upstream release archives: ```bash NGSPICE_URL="https://example.invalid/mirror/ngspice-46.tar.gz" \ NGSPICE_SHA256="" \ ./scripts/build-ngspice-from-source.sh ``` ## Optional and Deferred Tools These tools are useful for advanced flows, but they are not required by the current native Monata backend. | Tool | Upstream source | Monata status | Build guidance | | --- | --- | --- | --- | | ngspice | | Current subprocess backend | Prefer the `lizhangmai/skills` `monata-sim-env` and `conda-build` workflow. Use `scripts/build-ngspice-from-source.sh` only as a fallback. | | OpenVAF | | Current explicit Verilog-A to OSDI preparation | Build the `openvaf-r` recipe with the default `monata-sim-env` workflow. Pass resulting `.osdi` files explicitly through `SimTask.osdi_paths`. | | ADMS | | Deferred Xyce plugin path | Build the `adms` recipe only when you need simulator-specific Verilog-A plugin generation. | | Xyce | | Deferred scalable backend | Build the recipe stack with `--up-to xyce` only for workflows that explicitly need Xyce outside the current default Monata backend. | | XDM | | Separate netlist translator, not a Monata dependency | Build the `xdm` recipe only if you need PSpice/HSpice/Spectre to Xyce translation outside Monata. | | VACASK | Upstream project source | Not a Monata dependency | Build the `vacask` recipe only if your workflow explicitly needs it outside Monata. | ## Model and PDK Files Keep process files, foundry decks, PTM files, and project model sources in your own project area. Register local paths explicitly through Monata APIs. Generated netlists, `.osdi` files, and simulator output are project artifacts. Store them with your project outputs, not in the Monata package source tree.