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:

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 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:

/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:

npx skills add lizhangmai/skills --skill monata-sim-env --skill conda-build

Then ask the agent:

Use the monata-sim-env skill to set up this Monata environment.
CONDA_BUILD_OUTPUT_DIR=<absolute-path-you-choose>

Replace <absolute-path-you-choose> 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:

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="<absolute-path-you-choose>"

# 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:

# 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.

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:

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.

cd src/monata-docs

# Optional but recommended: pin the checksum from your trusted release source.
export NGSPICE_SHA256="<expected 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:

NGSPICE_VERSION=46 ./scripts/build-ngspice-from-source.sh

Set NGSPICE_URL if your organization mirrors upstream release archives:

NGSPICE_URL="https://example.invalid/mirror/ngspice-46.tar.gz" \
  NGSPICE_SHA256="<expected 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	https://ngspice.sourceforge.io/	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	https://github.com/pascalkuthe/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	https://github.com/Qucs/ADMS	Deferred Xyce plugin path	Build the `adms` recipe only when you need simulator-specific Verilog-A plugin generation.
Xyce	https://xyce.sandia.gov/	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	https://github.com/Xyce/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.