Metadata-Version: 2.4
Name: vacask
Version: 0.3.4.dev6
Summary: VACASK (Verilog-A Circuit Analysis Kernel) is an analog circuit simulator. 
Author-Email: Arpad Buermen <arpad.burmen@fe.uni-lj.si>
License-Expression: AGPL-3.0-only
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: numpy; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Description-Content-Type: text/markdown

<!--![cask](./cask1.png) -->
<img src="cask.svg" width="200" alt="Cask">

# About VACASK
VACASK (Verilog-A Circuit Analysis Kernel) is an analog circuit simulator. VACASK uses the [OpenVAF-Reloaded Verilog-A compiler](https://github.com/OpenVAF-Reloaded/OpenVAF) for building the device models as shared libraries. The compiled device models are loaded by the simulator on demand at runtime. The simulator communicates with the models via the [OSDI API](https://openvaf.semimod.de/docs/details/osdi/). Of course, you can also create device models using VACASK's APIs in C++ and link them statically with the simulator. 

Currently OSDI API 0.4 is used as default. OpenVAF-Reloaded from the master branch exposes this version of the API. The development version of the API (0.5) is also supported (mb-experimental branch). Binaries are bundled with the version that exposes the latest API (0.5). 

VACASK is not SPICE (although one could write a SPICE-compatible netlist parser for it with little effort). SPICE3 is more than 30 years old, written in C, and the code is hard to maintain. In some respect SPICE looks more like a proof of concept one writes before building the real thing. The way circuit equations are handled in SPICE makes it hard to extend the simulator with new algorithms. VACASK's goal is to be better than SPICE, not only in terms of what it offers, but also in terms of extensibility and ease of maintenance. 

# Wait... is it any good? 

The following benchmark results were obtained on the [C6288 16x16 multiplier circuit](benchmark/c6288) multiplying 0xFFFF with itself (simulated as an analog circuit). This is a medium size circuit with 10112 transistors and 25380 nodes. The transistors were modelled with the PSP103.4 model. Ngspice and Xyce tolerances were set so that the number of output timepoints is roughly equal to that of VACASK. OpenMP support was disabled to make the comparison fair. All simulators used KLU as the linear solver. Results output was disabled so that the impact of disk operations was minimized. The benchmark was run on a computer with an AMD Threadripper 7970 processor. 

|Simulator  |Time (s)        |Timepoints |Rejected |Iterations |
|-----------|----------------|-----------|---------|-----------|
|Xyce       | 151.57         |1013       |37       |3559       |
|Ngspice    |  71.81         |1020       |1        |3474       |
|VACASK     |  57.98         |1021       |7        |3487       |

If you want to find out more, there is [a page dedicated to benchmarks](benchmark). 

# What about memory usage? 

The following results were obtained on the above-mentioned [C6288 16x16 multiplier circuit](benchmark/c6288). Results storage in Ngspice was minimized to only two vectors (approximately 16kB of data). The table lists the memory usage of the simulator process reported by the OS during simulation. 

|Simulator  |Sparse matrix library |Total memory usage during simulation [MB] |
|-----------|----------------------|------------------------------------------|
|Xyce       |KLU                   |775.7 |
|Ngspice    |SPARSE                |135.3 |
|Ngspice    |KLU                   |200.5 |
|VACASK     |KLU                   |138.5 |

The increased Ngspice memory usage when KLU is used as the solver is probably due to the extra data structures Ngspice uses for setting up the sparse matrix for KLU. 

# How well does it scale?

We tested scalability of VACASK with [digital multiplier simulations ranging from 8-bit to 256-bit](demo/multiplier). The multipliers were simulated as analog circuits. The MOSFETs were modelled with the PSP103.4 model. All tests were run on a single core of an AMD Threadripper 7970 CPU. The 16-bit multiplier is equivalent to the C6288 benchmark problem, but has slightly fewer transistors (we suspect C6288 uses full adders where half adders should have been used). 

|Size [bits]|MOSFETs |Peak RAM [MB]|Elaboration [s]|Speed [ms/timestep]|
|-----------|--------|-------------|---------------|-------------------|
|8          |2256    |40.4         |0.029          |6.79               |
|16         |9888    |138.5        |0.152          |51.2               |
|32         |41280   |540.9        |0.888          |260                |
|64         |168576  |2173.1       |4.86           |1197               |
|128        |681216  |8756.7       |22.1           |5245               |
|256        |2738688 |35235.6      |100            |24766              |

Of course, simulation is slower for large circuits. The runtime grows slightly superlinearly because with increasing circuit size the share of runtime spent on linear algebra also increases. Linear algebra (LU decomposition, solve) scales superlinearly with matrix size and there is little one can do about it. Nevertheless, this demonstrates that VACASK can handle very large circuits. 

# Do you have a user's manual? 

Yes we do. It is bundled with the binary packages. [The user's manual](docs/index.md) is written in markdown. To read it in [Firefox](https://www.firefox.com/en-US/), instal the [Markdown Viewer Add-on](https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-chrome/) or the [Markdown Reader Add-on](https://addons.mozilla.org/en-US/firefox/addon/markdown-reader-ext/). 

# Want a quick overview of VACASK?

# Want to get started with VACASK right away?

# Maybe you want to build VACASK yourself or contribute to its codebase?

# Read on!

# What does VACASK offer? 

- fully parameterized hierarchical circuit description with user defined global and ground nodes
- behavioral voltage and current sources
- conditional netlist blocks (@if-@elseif-@else-@end) - can be used for implementing automated binning
- RPN interpreter for parameterized expression evaluation
- integer, real, and string data types; vectors (homogeneous containers) and lists (heterogeneous containers)
- a library of [built-in functions](docs/expr-functions.md) and [constants](docs/expr-constants.md) for use in parameterized expressions
- all SPICE analyses + [many more](#supported-analyses)
- [options](docs/cmd-options.md) for fine tuning the simulator
- selection of what should be saved during simulation (save directives)
- [parametric sweep](docs/cmd-sweep.md) of any analysis with arbitrary depth
- almost anything can be swept (instance, model, and subcircuit parameters, options, and circuit variables)
- anything that can be swept can also be modified without reloading the circuit (no need to build a new netlist and restart the simulator)
- automatic partial circuit elaboration when circuit topology changes due to a change in parameters, options, or variables
- a different topology can be elaborated without restarting the simulator (circuits with multiple testbenches can be simulated without restarting the simulator)
- residual-based convergence test (improved accuracy of the nonlinear solver)
- inactive instances bypass in nonlinear solver (disabled by default, see the `nr_bypass`, `nr_convtol`, and `nr_bypasstol` options)
- instance evaluation bypass in the first iteration of nonlinear solver running in continuation mode (enabled by default, see the `nr_contbypass` option)
- several homotopy algorithms (SPICE3/adaptive gmin stepping and source stepping) for finding the operating point of problematic circuits
- nodesets for improving convergence speed and reusing/selecting the operating point
- analysis results can be used as nodesets for subsequent analyses (combined with circuit variable sweeps this feature can be used for implementing custom homotopy algorithms at the netlist level)
- setting initial conditions (Spectre style and legacy SPICE3 style)
- backward Euler, trapezoidal, and Gear integration algorithms
- predictor-corrector local truncation error control in transient analysis
- KLU and SuperLU_MT as sparse linear solvers
- SPICE ASCII/binary raw file output
- embedded files in the netlist
- postprocessing of results with external tools (see [Python helpers](docs/python-overview.md) and [demos](demo))
- a growing [library of Verilog-A models](devices/) (diode, BSIM3, BSIM4, BSIMBULK, ...)
- simulator library that can be linked to 3rd party software (see API demo in  [demo/api](demo/api))
- netlist parser with Spectre-like syntax
- Ngspice netlist converter (under development, see [python/src/vacask/ng2vc.py](python/src/vacask/ng2vc.py))
- [Xschem](https://xschem.sourceforge.io/stefan/index.html) schematic entry, analysis setup, and results display (use the latest development release). See [demo/xschem](demo/xschem) for more information. 
- [IHP Open PDK](https://github.com/IHP-GmbH/IHP-Open-PDK) support for the sg13g2 and sg13cmos5l technologies. See [demo/ihp-sg13g2](demo/ihp-sg13g2) and [demo/ihp-sg13cmos5l](demo/ihp-sg13cmos5l) for more information. 
- Global Foundries GF180 PDK support. See [demo/gf180mcu](demo/gf180mcu) for more information. 
- Verilog-A natures and disciplines for setting absolute tolerances on unknowns and residuals (see [demo/natures](demo/natures)). 
- Monte Carlo analysis with Latin hypercube sampling (see [demo/mc](demo/mc)). 
- Touchstone file to VACASK lumped model converter based on scikit-rf (see [demo/ts](demo/ts)). 
- [Foreign language parsers](docs/input-include.md#foreign-format-includes-spice--spectre) (experimental), supporting ngspice, HSPICE, PSPICE, Xyce, and Spectre. 
- [Parallel](docs/startup-options.md#parallelism) device evaluation and solver support - see the `--ncpu` and the `--blas-ncpu` options. For best performance also set `OMP_PROC_BIND=close` and `OMP_PLACES=cores` in the environment (see [OpenMP environment](docs/startup-options.md#openmp-environment)).
- [Python bindings via pybind11](#python-bindings-experimental). 
 
VACASK is being developed by Árpád Bűrmen at the EDA Laboratory, University of Ljubljana, Slovenia. Several people have contributed to VACASK. See [contributors.md](contributors.md) for details. 

VACASK is written in C++20 and is free software released under the [GNU Affero General Public License 3.0](LICENSE). 


# Supported analyses

|Name    |   |
|--------|---|
|op      |[DC operating point](docs/cmd-analysis-op.md) |
|dcinc   |[incremental DC analysis (i.e. ac analysis at 0Hz)](docs/cmd-analysis-dcinc.md) |
|dcxf    |[small-signal DC transfer functions from independent sources to given output (i.e. acxf analysis at 0Hz)](docs/cmd-analysis-dcxf.md) |
|ac      |[small-signal AC analysis](docs/cmd-analysis-ac.md) |
|acxf    |[small-signal AC transfer functions from independent sources to given output](docs/cmd-analysis-acxf.md) |
|acstb   |[small-signal AC stability analysis (open loop gain without breaking the loop)](docs/cmd-analysis-acstb.md) |
|acsp    |[small-signal AC S-parameter analysis](docs/cmd-analysis-acsp.md) |
|noise   |[small-signal noise analysis](docs/cmd-analysis-noise.md) |
|tran    |[transient (time-domain) analysis](docs/cmd-analysis-tran.md) with optional [time-domain noise](docs/cmd-analysis-trannoise.md) |
|pss     |[periodic steady-state analysis (Newton shooting method)](docs/cmd-analysis-pss.md) |
|pac     |[periodic small-signal analysis (shooting-based)](docs/cmd-analysis-pac.md) |
|pnoise  |[periodic small-signal noise analysis (shooting-based)](docs/cmd-analysis-pnoise.md) |
|hb      |[(multitone) harmonic balance analysis](docs/cmd-analysis-hb.md) |
|hbac    |[(quasi)periodic small-signal analysis (harmonic balance-based)](docs/cmd-analysis-hbac.md) |
|hbnoise |[(quasi)periodic small-signal noise analysis (harmonic balance-based)](docs/cmd-analysis-hbnoise.md) |


# What about device models? 

Certain devices (independent voltage and current sources, linear controlled sources, and inductive coupling) are implemented as builtin devices because some features needed by these devices are not available in OpenVAF-Reloaded or even Verilog-A. 

|Builtin device                   |Name   |
|---------------------------------|-------|
|Independent voltage source       |vsource|
|Independent current source       |isource|
|Voltage-controlled voltage source|vcvs   |
|Voltage-controlled current source|vccs   |
|Current-controlled voltage source|ccvs   |
|Current-controlled current source|cccs   |
|Inductive coupling               |mutual |
|Behavioral voltage/current source|n/a    |

All Verilog-A models supplied with VACASK are located in [devices](devices). You can find several models at [www.mos-ak.org](https://www.mos-ak.org/open_dir/). All recent models developed by the [BSIM group at UC Berkeley](https://bsim.berkeley.edu/) are released in Verilog-A. Also take a look at [The Designer's Guide community](https://designers-guide.org/index.html) where various models are available in the [Verilog AMS section](https://designers-guide.org/verilog-ams/index.html). The VBIC model was taken from [Dietmar Warning's repository](https://github.com/dwarning/VA-Models). This repository is an excellent collection of public Verilog-A models. Many of these models have bugfixes and extensions not found elsewhere. When compiling these models, define the `__NGSPICE__` macro (add `-D__NGSPICE__` to your OpenVAF-Reloaded command line). 

We needed some devices for tests, demos, PDK translation, or we were just bored and created them to pass time. 

|Verilog-A device          |File               |OSDI file        |Module      |
|--------------------------|-------------------|-----------------|------------|
|Linear resistor           |resistor.va        |resistor.osdi    |resistor    |
|Linear capacitor          |capacitor.va       |capacitor.osdi   |capacitor   |
|Linear inductor           |inductor.va        |inductor.osdi    |inductor    |
|SPICE diode               |diode.va           |diode.osdi       |diode       |
|Ideal transmission line   |tline_ideal.va     |tline_ideal.osdi |tline_ideal |
|Opamp macromodel          |opamp.va           |opamp.osdi       |opamp       |
|VBIC 1.3, 3 terminals     |vbic/vbic_1p3.va   |vbic1p3.osdi     |vbic13      |
|VBIC 1.3, 4 terminals     |vbic/vbic_1p3.va   |vbic1p3_4t.osdi  |vbic13_4t   |
|VBIC 1.3, 5 terminals     |vbic/vbic_1p3.va   |vbic1p3_5t.osdi  |vbic13_5t   |
|BSIM3v3 MOSFET (Cogenda)  |bsim3v3.va         |bsim3v3.osdi     |bsim3       |
|BSIM4v8 MOSFET (Cogenda)  |bsim4v8.va         |bsim4v8.osdi     |bsim4       |
|PSP103.4 MOSFET           |psp103v4/psp103.va |psp103.osdi      |psp103va    |
|BSIMBULK MOSFET 106.2.0   |bsimbulk.va        |bsimbulk.osdi    |bsimbulk    |

The ([Verilog-A Distiller](https://codeberg.org/arpadbuermen/VADistiller)) project's aim is to create a converter from SPICE3 C model format to Verilog-A. At this point the following converted models are available in VACASK (converted with Verilog-A Distiller). 

|Verilog-A device (SPICE)  |File        |OSDI file      |Module       |
|--------------------------|------------|---------------|-------------|
|Linear resistor           |resistor.va |resistor.osdi  |sp_resistor  |
|Linear capacitor          |capacitor.va|capacitor.osdi |sp_capacitor |
|Linear inductor           |inductor.va |inductor.osdi  |sp_inductor  |
|Diode (levels 1 and 3)    |diode.va    |diode.osdi     |sp_diode     |
|Gummel-Poon BJT           |bjt.va      |bjt.osdi       |sp_bjt       |
|JFET level 1 (Schichman-Hodges)     |jfet1.va    |jfet1.osdi    |sp_jfet1     |
|JFET level 2 (Parker-Skellern) *    |jfet2.va    |jfet2.osdi    |sp_jfet2     |
|MESFET level 1 (Statz et. al.) *    |mes1.va     |mes1.osdi     |sp_mes1      |
|MOSFET level 1 (Schichman-Hodges) * |mos1.va     |mos1.osdi     |sp_mos1      |
|MOSFET level 2 (Grove-Frohman) *    |mos2.va     |mos2.osdi     |sp_mos2      |
|MOSFET level 3 (empirical) *        |mos3.va     |mos3.osdi     |sp_mos3      |
|MOSFET level 6 (Sakurai-Newton) *   |mos6.va     |mos6.osdi     |sp_mos6      |
|MOSFET level 9 (modified level 3) * |mos9.va     |mos9.osdi     |sp_mos9      |
|VDMOS *                             |vdmos.va    |vdmos.osdi    |sp_vdmos     |
|BSIM3 3.3.0                         |bsim3v3.va  |bsim3v3.osdi  |sp_bsim3v3   |
|BSIM4 4.8.0, 4.8.1, 4.8.2, 4.8.3    |bsim4v8.va  |bsim4v8.osdi  |sp_bsim4v8   |

Devices marked with an asterisk (*) do not conserve charge because of the modeling approach chosen by their respective authors. 

The converted SPICE models can be found in the [devices/spice](devices/spice) directory.

Most devices provide several model variants. The `sn` variant ([devices/spice/sn](devices/spice/sn) directory) models have a simplified noise model and do not expose output variables that would introduce extra internal nodes. These models are the fastest, but they cannot be used in advanced noise analyses (they give correct noise values in the ordinary small-signal noise analysis only). 

The `full` variant  ([devices/spice/full](devices/spice/full) directory) of a model exposes all output variables and the noise model is appropriate for all types of analysis. 

The `default` variant of models can be found in the [devices/spice](devices/spice) directory. These models do not expose output variables that introduce extra internal nodes. The noise model, however, is appropriate for all types of noise analysis. If a particular device does not have a `sn` or a `full` variant then that variant is equal to the `default` variant. For more information consult the [Verilog-A Distiller repository](https://codeberg.org/arpadbuermen/VADistiller). 

Examples of SPICE3 model usage are in [demo/spice](demo/spice). 

# Foreign language parsers

VACASK can read netlist files written in other simulators' dialects and pull them
into a native deck via the `include` directive. Supported dialects are ngspice,
HSPICE, PSPICE, Xyce, and Spectre. The included file's analysis and control cards
are ignored, and device/model names and a few parameters are rewritten to fit
VACASK's namespace. See [foreign-format includes](docs/input-include.md#foreign-format-includes-spice--spectre)
for details.

This feature is experimental and off by default. Enable it with the
`CADNIP_PARSERS` CMake option (`-DCADNIP_PARSERS=ON`). The parsers are written in
Rust, so a Rust toolchain (`cargo`) must be on `PATH`; the parser crate is
fetched automatically during configuration. When using `CADNIP_PARSERS`,
[Corrosion](https://github.com/corrosion-rs/corrosion) is also needed.
Corrosion can be automatically fetched (default), via system package (`-DCORROSION_USE_SYSTEM`),
or a local directory (`-DCORROSION_DIR=/path`). NOTE: `CORROSION_USE_SYSTEM` and `CORROSION_DIR`
are mutually exclusive. When built with the option off (the
default), no Rust toolchain is needed and including a foreign-format file reports
an error asking you to rebuild with it enabled.

The foreign parsers are an experimental feature and are still maturing. Expect
rough edges and incomplete dialect coverage. Bug reports should be raised as
issues and addressed to Pepijn de Vos (@pepijndevos on Codeberg).

# Installation from pre-built packages
[Pre-built packages](https://codeberg.org/arpadbuermen/VACASK/releases) for Linux (based on the stable version of Debian) and Windows are available. The OpenVAF-Reloaded compiler is included in all binary packages. Linux users can choose between a .tgz archive and a .deb package. The Windows package is a .zip file that you can unpack wherever you want. It is recommended to add the `bin` directory to the system path. 

A new version of VACASK is released every now and then. Between releases [(not quite) nightly builds](https://fides.fe.uni-lj.si/vacask/download/) are released. These are great if you want to try VACASK with latest bugfixes. 

All pre-built packages are built as generic binaries (no AVX-512 instructions). For GCC this is the default, while OpenVAF-Reloaded must be passed the `--target_cpu generic` option to disable AVX-512 code generation. You can achieve this by adding `-DOPENVAF_OPTIONS="--target_cpu generic"` to the CMake command line when creating the build system. To obtain maximum performance build VACASK without specifying the aforementioned `-DOPENVAF_OPTIONS` option. 

# Getting started
There are some examples available in the [`demo`](demo) directory. You can try the simulation of a Miller OTA by running
```
vacask demo/bsim3-ptm-amp/toplevel.sim
```

If you have Python 3, [NumPy](https://numpy.org/), and [Matplotlib](https://matplotlib.org/) installed the results will be plotted by the postprocessor script. Note that some of the demos also require [SciPy](https://scipy.org/) and [scikit-rf](https://scikit-rf.org/). 

You can learn about the netlist syntax by studying the demos in the [`demo`](demo) directory and the system tests in the [`test`](test) directory. We also have a [VACASK User's Manual](docs/index.md). 

If VACASK fails to find something, first check all the paths by typing
```
vacask -dp
```

If you specify the `-df` option VACASK will print the paths to the files it is loading, dumping, or compiling. 

VACASK detects the Python 3 interpreter and sets the `PYTHON` circuit variable to the interpreter's full path. This variable can then be used in the netlist for launching Python to postprocess the simulation results without having to specify its full path. For VACASK to find the Python interpreter the interpreter's binary directory must be in the system path. VACASK supplements the `PYTHONPATH` variable with the directory holding the supplied `vacask` Python package (`<vacask library directory>/python`). The package can be used for loading binary .raw files (`from vacask.rawfile import rawread`). They depend on the [NumPy library](https://numpy.org/). 

When a file is included with the `include` netlist directive and the given path is absolute VACASK loads it based on the given absolute path. If the path is relative VACASK first looks for the file in the directory where the netlist that invoked the `include` directive resides, then in the current working directory, and finally in the include files path. The include files path is by default set to`<vacask library directory>/inc`. You can override it by setting the `SIM_INCLUDE_PATH` environmental variable. The directories in the list must be separated by colons (in Windows they must be separated by semicolons). 

Models are loaded with the `load` netlist directive. If the given path is absolute VACASK looks for the model only at the given path. If, however, it is relative VACASK first searches for the model in the directory where the netlist invoking the `load` directive is located, followed by the current working directory, and the modules search path. The modules search path is by default set to `<vacask library directory>/mod`. You can override it with the `SIM_MODULE_PATH` environmental variable (same syntax as for `SIM_INCLUDE_PATH`). 

VACASK can compile Verilog-A files on the fly. For that purpose VACASK looks for the OpenVAF-Reloaded compiler in the directory where the VACASK binary is installed and in the system path. You can override this by specifying the path to the OpenVAF-Reloaded compiler in the `SIM_OPENVAF` environmental variable. If a `load` directive specifies a raw Verilog-A file (ending in .va), VACASK will try to compile it. The compiled model is placed in the current working directory and then loaded. 

VACASK can also be configured with a TOML configuration file. Take a look at [config/vacaskrc-sample.toml](config/vacaskrc-sample.toml). 

# Building VACASK
As VACASK grows the list of dependencies is getting longer. Currently VACASK depends on
- C++20 compiler and the standard C++ library
- OpenMP support in compiler (optional; libgomp1 under Linux)
- Bison (version 3.3 or newer) and Flex (version 2.6.4 or newer)
- Boost (version 1.88)
- toml++ (version 3.4)
- KLU (SuiteSparse)
- SuperLU_MT (optional, needs OpenMP)
- OpenBLAS (the OpenMP version) - VACASK links it for both BLAS and LAPACK and
  calls its `openblas_set_num_threads()` directly, so OpenBLAS (not reference
  Netlib BLAS/LAPACK) must be the provider the build finds
- FFTW (3.3.10 or newer) 
 
Most of these components come as pre-built packages for [Debian](https://www.debian.org) (and other Linux distributions). You will also need a working Python3 installation (for the system tests and demos) with the following libraries
- NumPy 2
- SciPy
- Scikit-rf
- Matplotlib

First, install the OpenVAF-Reloaded compiler. The latest development version of OpenVAF-Reloaded can be found at [https://fides.fe.uni-lj.si/openvaf/download](https://fides.fe.uni-lj.si/openvaf/download/). Make sure you download the OSDI 0.4 or 0.5 version. The `absdelay` operator is only described by OSDI 0.5 modules: with an OSDI 0.4 compiler a delay is silently zero, and the `test_delay*` tests report themselves as skipped. Of course, you can also take the OpenVAF-Reloaded binary from the VACASK binary packages (.deb and .tar.gz for Linux, .zip for Windows). If the OpenVAF-Reloaded binary you pick up is named `openvaf-r` you have the right one (it produces models with the OSDI 0.4/0.5 interface). If you decide to build the compiler yourself, git-clone the [OpenVAF-Reloaded repository](https://github.com/OpenVAF-Reloaded/OpenVAF). Note that the `main` branch contains the OSDI 0.4 version. The OSDI 0.5 version is in the `mb-experimental` branch. Instructions for building can be found in the [README.md](https://github.com/OpenVAF-Reloaded/OpenVAF/blob/master/README.md) file. 

macOS users must build OpenVAF-Reloaded from sources. Make sure you [install all prerequisites](#macos).  Then follow these [short instructions for building OpenVAF](#building-openvaf-reloaded). 

## Linux

### Prerequisites
Install gcc, bison, flex, CMake, and GNU make or Ninja for building. Install the
libraries toml++, KLU (SuiteSparse), FFTW, and the OpenMP build of OpenBLAS. On Debian
and derivatives these are `bison flex cmake ninja-build libtomlplusplus-dev
libsuitesparse-dev libfftw3-dev libopenblas-openmp-dev`.

VACASK uses OpenBLAS for both BLAS and LAPACK. Make sure it is the active
alternative so CMake's `find_package(BLAS)` / `find_package(LAPACK)` pick it up
and not the reference `libblas3` / `liblapack3`:
```
sudo update-alternatives --config libblas.so.3-x86_64-linux-gnu
sudo update-alternatives --config liblapack.so.3-x86_64-linux-gnu
```
Installing `libopenblas-openmp-dev` normally makes it the default already.

Unfortunately you will have to build your own Boost. We had problems with system-installed Boost 1.88 under Debian 13 (process library is not built). In Debian 14 this issue seems to be fixed. Download the linux version of Boost 1.88 sources from [https://www.boost.org/users/download/](https://www.boost.org/users/download/). Unpack it. Enter the directory created by unpacking (`boost_1_88_0`) and type
```
cd tools/build
./bootstrap.sh gcc
cd ../..
tools/build/b2 --with-filesystem --with-process --with-asio link=static toolset=gcc cxxflags=-fPIC cflags=-fPIC
```
Now Boost libraries are installed under `boost_1_88_0/stage` while the include files are in `boost_1_88_0`. The `-fPIC` flags are needed only if you want to build the Python package (scikit-build) because static libraries that are linked into the Python module must be compiled as position independent code. 

You will also have to build SuperLU_MT from the sources. Do not use SuperLU_dist, it won't work well. You can download the original package from [https://portal.nersc.gov/project/sparse/superlu/](https://portal.nersc.gov/project/sparse/superlu/), but you will have to edit the `Makefile` and create the `lib` directory manually. Make sure you build the OpenMP version. Add the `-fPIC` compiler option. To save you the trouble, we prepared a version of the sources where everything is ready for compiling [https://fides.fe.uni-lj.si/vacask/superlu_mt-4.0.0.tar.gz](https://fides.fe.uni-lj.si/vacask/superlu_mt-4.0.0.tar.gz). 
Unpack the sources and run
```
make
```
If you want to build the Python package, add `-fPIC` to `CFLAGS` and `NOOPTS` in `make.inc` before running `make`. 

### Building the simulator
Create a `build` directory and create the build system
```
cmake -G Ninja -S <sources directory> -B <build directory> -DCMAKE_BUILD_TYPE=Release \
    -DOPENVAF_DIR=<path to the OpenVAF-Reloaded compiler> \
    -DBoost_ROOT=<directory_where_you_unpacked_boost_sources>/stage \
    -DSuperluMT_DIR=<directory_where_you_unpacked_superlu_sources> \
    -DCADNIP_PARSERS=ON 
```

If you do not specify `-DSuperluMT_DIR` SuperLU support will not be compiled into the binary. Similarly, if you do not specify `-DCADNIP_PARSERS=ON` foreign netlist format parsers will not be built. For the latter to build successfully you will have to install the rust toolchain. 

To build with GNU make, replace `-G Ninja` with `-G "Unix Makefiles"`. The build process is started by typing
```
cmake --build <build directory>
```

After the build process is finished the binary can be found in `<build directory>/simulator`. 

The .tar.gz and .deb packages can be built by changing the current directory to `<build directory>` and typing
```
cpack
```
The packages are created in the `<build directory>`.

<a id="macos"></a>
## macOS

### Prerequisites
Install the required dependencies using [Homebrew](https://brew.sh/):
```
brew install llvm@18 cmake ninja bison flex suite-sparse openblas boost tomlplusplus fftw
```
Contrary to Linux you do not have to build Boost yourself because the Homebrew package includes the Process library. CMake locates the Homebrew installations of bison, flex, SuiteSparse, toml++, Boost, and FFTW on its own, so you do not have to specify their paths.

The system tests and the demos need Python3 with the libraries listed above. NumPy and SciPy are available as Homebrew packages
```
brew install numpy scipy
```
Matplotlib and scikit-rf are used by some demos only. Install them with `pip` if you need them.

### Building OpenVAF-Reloaded
You need to build the OpenVAF-Reloaded compiler from sources. First, install Rust (1.85 or newer):
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
```

The compiler links against LLVM 18 so it must be told where the Homebrew LLVM 18 lives. Clone the sources and build them with
```
export PATH="$(brew --prefix)/opt/llvm@18/bin:$PATH"
export LLVM_SYS_180_PREFIX="$(brew --prefix)/opt/llvm@18"
git clone --branch mb-experimental https://github.com/arpadbuermen/OpenVAF.git
cd OpenVAF
./configure
./build.sh --release
```
The compiler binary will be at `target/release/openvaf-r`. The `mb-experimental` branch exposes the OSDI 0.5 interface. Build the master branch of the [OpenVAF-Reloaded repository](https://github.com/OpenVAF-Reloaded/OpenVAF) the same way if you want the compiler that exposes the default OSDI 0.4 interface. 

### Building the simulator
Create a build directory and configure with CMake. Most dependencies are found in the Homebrew prefix automatically. What remains is the path to the OpenVAF-Reloaded compiler and the BLAS/LAPACK selection. `BLA_VENDOR` makes CMake use OpenBLAS instead of Apple's Accelerate framework. Because the OpenBLAS package is keg-only its prefix must be added to `CMAKE_PREFIX_PATH`. `Boost_USE_STATIC_LIBS` links Boost statically so that the simulator does not depend on the Homebrew Boost dynamic libraries. If you want SuperLU_MT support, download its sources and build the library. 
```
cmake -G Ninja -S <sources directory> -B <build directory> -DCMAKE_BUILD_TYPE=Release \
    -DOPENVAF_DIR=<directory holding the openvaf-r binary> \
    -DBoost_USE_STATIC_LIBS=ON \
    -DBLA_VENDOR=OpenBLAS \
    -DCMAKE_PREFIX_PATH=$(brew --prefix openblas)
    -DSuperluMT_DIR=<directory_where_you_unpacked_superlu_sources> \
    -DCADNIP_PARSERS=ON
```

Build the simulator:
```
cmake --build <build directory>
```

After the build process is finished the binary can be found in `<build directory>/simulator`.

To create a .tar.gz package, change to `<build directory>` and type:
```
cpack
```

## Windows
Building for Windows is performed with the Mingw64 compiler. Unfortunately you will have to build all of the prerequisites manually. Because OpenVAF-Reloaded requires the MSVC linker for building .osdi files under Windows install Visual Studio 2022. 

### Building the prerequisites
First, install the compiler and the tools. We will assume everything will be unpacked and built in `e:\`. Adjust the paths accordingly if you are going to use a different drive. Download Msys2 from [https://www.msys2.org/](https://www.msys2.org/) and install it to `e:\msys64`. Start the MSYS prompt and install bison, flex, and binutils. 
```
pacman -S bison
pacman -S flex
pacman -S binutils
```

Download MinGW64 from [https://winlibs.com/](https://winlibs.com/). Get the posix-seh-ucrt version without LLVM/Clang/LLD/LLDB (we don't need them). Unpack it to `e:\mingw64`. This version of MinGW64 comes with CMake and Ninja (required for building). 

Add MSYS2 and MinGW64 to the system path (Control Panel/System/Advanced System Settings/...). Make sure you add MinGW (`e:\mingw64\bin`) before MSYS2 (`e:\msys64\usr\bin`). 

Start the command prompt (`cmd.exe`). Create a directory for all the stuff we are going to build.
```
e:
cd \
mkdir build
```

Download the toml++ library from [https://github.com/marzer/tomlplusplus/releases/tag/v3.4.0](https://github.com/marzer/tomlplusplus/releases/tag/v3.4.0). Unpack it in `e:\build`. 

Next, download the Boost library from [https://www.boost.org/users/download/](https://www.boost.org/users/download/). Use Boost version 1.88.0. Get the Windows version and unpack it in `e:\build`. In the Boost sources directory type
```
cd tools\build
bootstrap mingw
cd ..\..
tools\build\b2 --with-filesystem --with-process --with-asio link=static toolset=gcc
```
After a short time the required part of Boost is built and placed in the `stage` subdirectory.

Prepare the toolchain file (`e:\build\mingw.cmake`) by putting the following definitions in the file. 
```
set(CMAKE_SYSTEM_NAME Windows)

set(CMAKE_C_COMPILER gcc)
set(CMAKE_CXX_COMPILER g++)
set(CMAKE_Fortran_COMPILER gfortran)
set(CMAKE_RC_COMPILER windres)

set(CMAKE_FIND_ROOT_PATH e:/mingw64/bin)

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
```
If needed, replace `e:/mingw64/bin` with your path. 

Now, download OpenBLAS from [https://www.openblas.net/](https://www.openblas.net/). There is a link to [GitHub where the released sources can be found](https://github.com/OpenMathLib/OpenBLAS/releases). Take the latest source (at the time of writing 0.3.29). Unpack it in `e:\build`. Enter the directory with the OpenBLAS sources and type
```
mkdir build
cd build
cmake .. -G Ninja -DCMAKE_TOOLCHAIN_FILE=e:\build\mingw.cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_STATIC_LIBS=ON -DUSE_THREADS=0 -DUSE_LOCKING=1 -DDYNAMIC_LIST="CORE2;NEHALEM;BARCELONA;SANDYBRIDGE;BULLDOZER;PILEDRIVER;STEAMROLLER;EXCAVATOR;HASWELL;ZEN;SKYLAKEX;COOPERLAKE;SAPPHIRERAPIDS" -DTARGET=NEHALEM
cmake --build . -j 8
cmake --install . --prefix e:/build/installation
```

The `-j 8` option enables parallel building with 8 processors. Since OpenBLAS is big, this will save you some time. In the end OpenBLAS will be installed in `e:\build\installation`. 

Next, download [SuiteSparse](https://people.engr.tamu.edu/davis/suitesparse.html) from [GitHub](https://github.com/DrTimothyAldenDavis/SuiteSparse/releases). Get the latest release source code (at the time of writing 7.10.3). Unpack it in `e:\build`. In the sources directory type
```
mkdir build
cd build
cmake .. -G Ninja -DCMAKE_TOOLCHAIN_FILE=e:\build\mingw.cmake -DSUITESPARSE_ENABLE_PROJECTS="klu" -DCMAKE_BUILD_TYPE=Release -DBLAS_LIBRARIES=e:\build\installation\lib\libopenblas.a -DLAPACK_INCLUDE_DIRS=e:\buid\installation\include\openblas -DBLAS_INCLUDE_DIRS=e:\build\installation\include\openblas
cmake --build . -j 8
cmake --install . --prefix e:/build/installation
```

You will also need FFTW. For your convenience we prepared a [tar.gz archive](https://fides.fe.uni-lj.si/vacask/fftw-3.3.11.tar.gz) (just changed the allowed CMake version, everything else is the same as in the [upstream file](https://www.fftw.org/fftw-3.3.11.tar.gz)). Unpack it in `e:\build`, enter the directory, and type
```
mkdir build
cd build
cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=e:\build\mingw.cmake -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release ..
cmake --build . -j 8
cmake --install . --prefix e:/build/installation
```

If you want SuperLU_MT support you wll have to download its sources (see the Linux section). Unpack them in `e:\build`, enter the unpacked directory, and type
```
make
```

For Cadnip parsers support make sure you have the `stable-x86_64-pc-windows-gnu` toolchain. You probably built OpenVAF-Reloaded so you have only the `x86_64-pc-windows-msvc` Rust toolchain. So type 
```
rustup toolchain install stable-x86_64-pc-windows-gnu
```

Replace the `e:\...` paths with your own, if needed. 

### Building the simulator
Unpack the sources, create a build directory, and type. 
```
cmake -G Ninja -S <sources directory> -B <build directory> -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=e:\build\mingw.cmake -DOPENVAF_DIR=<path to the OpenVAF-Reloaded compiler> -DBoost_ROOT=e:/build/boost_1_88_0/stage -DTOMLPP_DIR=e:/build/tomlplusplus-3.4.0 -DSuiteSparse_DIR=e:/build/installation -DTOMLPP_DIR=e:/build/tomlpusplus-3.4.0 -DOPENBLAS_DIR=e:/build/installation -DFFTW3_DIR=e:/build/installation
cmake --build <build directory>
```

For SuperLU_MT support add the following option to the first cmake command
```
-DSuperluMT_DIR=e:/build/superlu_mt-4.0.0
```

For Cadnip parsers add
```
-DCADNIP_PARSERS=ON -DRust_TOOLCHAIN=stable-x86_64-pc-windows-gnu
```

Replace the `e:\...` paths with your own, if needed. All paths must be absolute and therefore include the drive letter. In the end the simulator can be found in `<build directory>/simulator`. To create a package (.zip), go to the `<build directory>` and type. 
```
cpack
```
The created packages are located in the `<build directory>`. 

## Running the tests
The system tests are located in [`test`](test). They are run with CTest from the `<build directory>`
```
ctest --output-on-failure
```
Some tests need model libraries that are not part of the sources. Such tests carry a CTest label. Currently the only label in use is `requires_ihp_pdk`. It marks the tests that need a converted [IHP Open PDK](https://github.com/IHP-GmbH/IHP-Open-PDK) along with the `PDK_ROOT` and `PDK` environmental variables (see [demo/ihp-sg13g2](demo/ihp-sg13g2) for the conversion procedure). If you do not have the PDK, exclude these tests with
```
ctest --output-on-failure --label-exclude requires_ihp_pdk
```
This is what the CI scripts in [`ci`](ci) do when they build and test VACASK.

## Python bindings (EXPERIMENTAL)
VACASK now has experimental python bindings using pybind11. These can be installed via pip as such:
```
    git clone https://codeberg.org/arpadbuermen/VACASK.git
    cd VACASK 
    python -m venv venv
    source venv/bin/activate
    CMAKE_ARGS="-DCMAKE_BUILD_TYPE=Release \
    -DOPENVAF_DIR=<directory holding the openvaf-r binary> \
    -DBoost_USE_STATIC_LIBS=ON \
    -DBLA_VENDOR=OpenBLAS \
    -DCMAKE_PREFIX_PATH=$(brew --prefix openblas) \
    -DSuperluMT_DIR=<directory_where_you_unpacked_superlu_sources> \
    -DCADNIP_PARSERS=ON" pip install .[dev]
```
Test the installation by running `pytest`. Demos/tests are located in `test/test_demo.py`.

The biding can also be installed directly from git, e.g.:
```
CMAKE_ARGS="-DCMAKE_BUILD_TYPE=Release -DOPENVAF_DIR=.../openvaf/bin -DBoost_DIR=.../Boost-1.88.0" pip install git+https://https://codeberg.org/arpadbuermen/VACASK.git
```

Note that Boost and all other linked libraries must be build with position independent code enabled. 

Bug reports should be raised as issues and addressed to Jure Vreča (@jurevreca12 on Codeberg).

# Visual Studio Code project for developers
A [Visual Studio Code](https://code.visualstudio.com/) setup is available in the [`.vscode`](.vscode) subdirectory of the sources. Files [`settings-linux.json`](.vscode/settings-linux.json) and [`settings-windows.json`](.vscode/settings-windows.json) are the settings templates for Linux and Windows. Depending on your platform copy one of these two to `settings.json` and edit it to reflect your configuration. File `settings.json` is not tracked by git so editing it won't result in any changes that need committing. 

Install the following Visual Studio Code extensions: C/C++, CMake, CMake Tools, VSCode-YACC, and VSCode-YYLEX. Assuming the Visual Studio Code binary is in the system path you can start the IDE by entering the simulator source directory and typing
```
code .
```

In Windows select the MinGW64 toolchain. In Linux select GCC. Configure the project with Ctrl+Shift+P 'CMake: Delete Cache and Reconfigure', followed by building with Ctrl+Shift+P 'CMake: Build'. A full debugging setup is available in [`launch.json`](.vscode/launch.json). System tests are located in [`test`](test) and can be run via CMake/CTest. The path to the built debug version (relative to the sources) is `../build.VACASK/Debug`. The release version is built under `../build.VACASK/Release`. 
 
# AGPL interpretation
All components of VACASK, including its Python modules and C++ libraries, are licensed under the AGPLv3. We consider importing its Python modules or linking against its C++ libraries to create a combined work, to which the AGPLv3 applies as a whole.

VACASK can be used with non-GPL software when it runs as a separate program, invoked from the command line or communicating via stdio or other forms of inter-process communication (IPC). A wrapper or application that communicates with VACASK this way does not become subject to the AGPLv3 and may be licensed under any terms.

VACASK itself, however, remains under the AGPLv3 in all cases. If you distribute VACASK, modified or not, you must comply with the AGPLv3, including making the corresponding source code available to recipients. If you modify VACASK and users interact with the modified version over a network, you must offer those users its source code. We consider any such interaction to be covered, whether users access VACASK directly or indirectly through a wrapper, frontend, or other intermediary program.

# Use of generative AI
Development of VACASK relies on generative AI (GenAI) primarily for mathematical background preparation, bug audits, debugging, testing, build system management, and documentation. Contributors using GenAI should thoroughly review the code they contribute. All contributions will be subject to strict human review before merging into the core simulator. Low quality, vibe-coded, and bloated contributions will be rejected. 

# Publications mentioning VACASK

* Á. Bűrmen, ["VACASK: a Verilog-A Circuit Analysis Kernel"](https://wiki.f-si.org/index.php?title=VACASK:_a_Verilog-A_Circuit_Analysis_Kernel), Free Silicon Conference 2024, Paris, June 2024.
* Á. Bűrmen, ["OpenVAF - status update, ecosystem, and a roadmap"](https://zenodo.org/records/14622027), 17th International MOS-AK Workshop, Silicon Valley, December 2024."
* Á. Bűrmen, et. al. ["Free software support for compact modelling with Verilog-A"](https://doi.org/10.33180/InfMIDEM2024.404), Informacije MIDEM - Journal of Microelectronics, Electronic Components and Materials, 54 (2024), no. 4: 271-281.
* Á. Bűrmen, ["VACASK and Verilog-A Distiller - building a device library for an analog circuit simulator"](https://fosdem.org/2025/schedule/event/fosdem-2025-4681-vacask-and-verilog-a-distiller-building-a-device-library-for-an-analog-circuit-simulator/), FOSDEM 2025, Brussels, February 2025.
* Á. Bűrmen, ["Recent developments in the Verilog-A circuit analysis kernel"](https://wiki.f-si.org/index.php?title=Recent_developments_in_the_Verilog-A_circuit_analysis_kernel), Free Silicon Conference 2025, Frankfurt (Oder), July 2025. 
* Á. Bűrmen, ["The OpenVAF Verilog-A Compiler for the OpenPDK Ecosystem"](https://doi.org/10.5281/zenodo.17113774), MOS-AK Workshop/ESSERC 2025, Munich, September 2025. 
* Á. Bűrmen, ["VACASK - a novel analog integrated circuit simulator"](https://doi.org/10.5281/zenodo.17434615), 60th International Conference on Microelectronics, Devices and Materials (MIDEM2025), Ljubljana, October 2025. 
* Á. Bűrmen, ["VACASK: One year toward a modern open analog simulation stack"](https://wiki.f-si.org/index.php?title=VACASK:_One_year_toward_a_modern_open_analog_simulation_stack), Free Silicon Conference 2026, Ljubljana, July 2026. 

# Acknowledgement

This project is funded through [NGI0 Commons Fund](https://nlnet.nl/commonsfund), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/VACASK).

[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
[<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/commonsfund)
