# ngspice

ngspice is Monata's current native simulator target. Monata renders native
`monata.netlist.Circuit` objects to ngspice-compatible text and executes them
through a user-installed ngspice runtime.

Monata has two ngspice runner paths:

- `ngspice-subprocess` is the stable default. It runs a local `ngspice`
  executable through a subprocess.
- `ngspice-shared` is the same-simulator shared-library path. It loads a local
  `libngspice` shared library through Monata's default Python FFI dependency.

The current ngspice backend support covers deterministic DC sweep, transient,
AC, operating-point, and noise runs. Unsupported analyses return
`SimResult(status="failed")` with an explicit reason until their native
implementations are added.

## Runtime Contract

- The public Monata package does not bundle `ngspice`.
- The backend resolves a local `ngspice` executable from `PATH` or
  `CONDA_PREFIX/bin`.
- The shared-library backend resolves a local `libngspice` library at runtime;
  Monata does not ship that library.
- Internal packaged environments may install `ngspice` as a separate package,
  but public users should install or build the tool in their own environment.
- DC, transient, and AC results are written with ngspice `wrdata` using a
  single sweep scale.
- DC, transient, AC, and operating-point tasks must provide explicit
  `output_names`; Monata does not infer output vectors from the netlist.
- Noise tasks use `NoiseSpec.output_node` and `NoiseSpec.input_source` as the
  explicit request. `SimTask.output_names` must be empty for noise.
- DC and transient outputs are emitted as `v(name)`.
- AC outputs are emitted as `mag(v(name))`.
- Operating-point outputs are emitted as one-row arrays parsed from
  `print v(name)`.
- Noise outputs are parsed from ngspice `noise1`/`noise2` print output as
  `onoise_spectrum`, `inoise_spectrum`, and totals metadata.
- OSDI libraries in `SimTask.osdi_paths` are loaded with `pre_osdi` before the
  analysis command.
- Plain `.include` model cards can be emitted by the native netlist renderer.

## Distribution and License Boundary

The ngspice source tree contains a primary modified-BSD license plus specific
subtree exceptions for components such as KLU, OSDI, numparam, XSPICE table
code models, and other bundled source. Public Monata packages avoid carrying
that native code by treating ngspice as an external runtime dependency.

When users or organizations build ngspice from source, they should keep the
upstream license files and notices with the resulting installation. Monata
documentation may provide build steps, but it does not redistribute the built
ngspice executable, `libngspice`, XSPICE `.cm` binaries, or compiled OSDI
artifacts.

## Supported Task Inputs

| Input | Current behavior |
| --- | --- |
| `DCSpec` | Executes `dc <source> <start> <stop> <step>` |
| `TranSpec` | Executes `tran <step> <stop> <start>` |
| `ACSpec` | Executes `ac <dec|oct|lin> <points> <start> <stop>` |
| `OPSpec` | Executes `op`, then parses requested `v(name)` values |
| `NoiseSpec` | Executes `noise v(output_node) input_source dec <points> <start> <stop>` |
| `output_names` | Required for DC/Tran/AC/OP; must be empty for Noise |
| `osdi_paths` | Existing files are loaded with `pre_osdi` |
| `param_overrides` | Simple `.param` names are emitted after existing params; `element.parameter` targets mutate native elements |
| corner temperature | Emits `.temp <temperature>` |
| corner voltage | Mutates matching voltage sources through `source.V` overrides |
| corner model file | Emits `.include "<model_file>"` |

## Explicit Limitations

The backend fails explicitly instead of silently ignoring unsupported inputs:

| Input | Failure reason |
| --- | --- |
| unsupported analysis type | `unsupported_analysis` |
| empty `output_names` for DC/Tran/AC/OP | `no_outputs_requested` |
| non-empty `output_names` for Noise | `invalid_task` |
| unsafe output names, OSDI paths, or analysis command fields | `invalid_task` |
| missing OSDI or corner model file | `model_missing` |
| missing or unsupported parameter/source override targets | `unsupported_param_overrides` |
| process or model-deck corner without a concrete model file | `unsupported_corner` |

Advanced ngspice work such as binary rawfile parsing, richer noise output
contracts, and richer model-deck projection is tracked in the maintainer
{doc}`../maintainers/roadmap`.