# 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` `conda-build` skill and
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: Build a Local Conda Channel

The public [`lizhangmai-skills`](https://github.com/lizhangmai/lizhangmai-skills)
repository includes a `conda-build` skill that wraps `rattler-build` recipes for
ngspice, OpenVAF, Xyce, XDM, ADMS, VACASK, Trilinos, and related packages. Use
it to build the native tools into a user-owned local conda channel, then consume
that channel from pixi.

```bash
git clone https://github.com/lizhangmai/lizhangmai-skills.git
cd lizhangmai-skills/skills/conda-build

# Pick a persistent directory. Do not use /tmp for final packages.
export CONDA_BUILD_OUTPUT_DIR="$HOME/.local/share/monata-conda-channel"

# Current Monata simulations need ngspice.
python3 scripts/rattler_channel.py build \
  --recipe-set circuit-toolchain \
  --package ngspice

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

```bash
# Verilog-A to OSDI preparation.
python3 scripts/rattler_channel.py build --recipe-set circuit-toolchain --package openvaf-r

# Full Xyce recipe stack. This is not required by Monata's current default 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.

```bash
pixi init monata-work \
  --channel "file://$CONDA_BUILD_OUTPUT_DIR" \
  --channel https://prefix.dev/conda-forge
cd monata-work

pixi add python=3.12 ngspice
pixi add --pypi monata

pixi run python - <<'PY'
from importlib.metadata import version
import shutil
import monata

print(version("monata"))
print(shutil.which("ngspice"))
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="<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:

```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="<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` `conda-build` recipe and pixi environment. Use `scripts/build-ngspice-from-source.sh` only as a fallback. |
| OpenVAF | <https://github.com/pascalkuthe/OpenVAF> | Optional Verilog-A to OSDI preparation | Build the `openvaf-r` recipe from the skill when you need `.va` to `.osdi` compilation. 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.