4. Installation

You must install a Python environment and the Ngspice/Xyce simulator to use PySpice on your computer. Since there are many ways to do this, we will only explain the easiest ones in details.

In Python, the standard way is to use a Virtual Environment and the pip tool, look at this guide for further information.

But if you are mainly doing data science, the easiest solution is probably to install the Anaconda Distribution which is specialised for this purpose. You can also prefer its lightweight counterpart Miniconda.

Anaconda has the advantage to provide a self consistent environment to the user, for example it installs automatically Ngspice for you when you install PySpice. But for this reason, especially on Linux, an Anaconda distribution will require much more disk space than a virtual environment.

Note

We recommend that you read the documentation in this order, first Windows to get the novice story, then Linux to get the Unix OS story and finally OSX if you are concerned.

4.1. PySpice Packages

Note to Linux Packagers: Please do not create a PySpice package, PyPI and Anaconda do the job.

PySpice is available as a Anaconda and PyPI package. For Anaconda there is two channels, the official one is conda-forge, the second one fabricesalvaire is only used for testing.

4.2. Ngspice on conda-forge

Note

If you decide to use the conda-forge package, you do not need to install Ngspice manually since it is provided as a dependency package: ngspice-lib.

However if you want the Ngspice executable on your system, then run this command:

conda install -c conda-forge ngspice-exe  # install the ngspice executable

conda install -c conda-forge ngspice      # install the master package
conda install -c conda-forge ngspice-lib  # install the ngspice library

4.3. PySpice Continuous Integration

PySpice is tested on theses platforms:

  • Travis CI :

    • Bionic Ubuntu Linux (Ngspice is compiled manually)

    • macOS 10.14.4 Mojave (use Brew)

    • Windows 10.0.17134 (use Chocolatey)

  • Azure CI

  • Fedora

4.4. On Windows

The preferred solution for installing a Python environment on Windows is to install Anaconda or Miniconda.

Once Anaconda is installed, open the Anaconda Navigator and launch a console for your root environment.

Then the only thing to do to get PySpice on Anaconda is to run this command:

conda install -c conda-forge pyspice

The following steps are not required for the conda-forge package.

As an alternative to conda, you can use the pip tool: pip install PySpice

The easiest solution to install Ngspice on Windows is to use the PySpice tool to donwload and install the Windows 64-bit DLL library for you:

pyspice-post-installation --install-ngspice-dll

Then check your installation using the multi-platform command:

pyspice-post-installation --check-install

4.5. On Linux

You are free to install the packages of your Linux distribution.

4.5.1. Ngspice Installation

If you do not want to use Anaconda, Ngspice and its shared library are available on many distributions:

Warning

However it is advisable to check how Ngspice is compiled, especially if the maintainer has enabled experimental features !

For RPM distributions, such Fedora, RHEL and Centos, you can use this Copr repository https://copr.fedorainfracloud.org/coprs/fabricesalvaire/ngspice

dnf copr enable fabricesalvaire/ngspice
dnf install libngspice

If you are not able to easily install the Ngspice shared library on your system, but you can install the Ngspice program, then you can use the “subprocess” mode instead of the “shared” mode. In this case, you must define the default simulator globally using the attribute PySpice.Spice.Simulation.CircuitSimulator.DEFAULT_SIMULATOR = 'ngspice-subprocess'.

4.5.2. Install the Python Environment

On Linux, you have several possibilities to install the required Python environment:

  1. if you are novice, the easiest solution is to install Anaconda or Miniconda

  2. you can install Python packages from your distributions

  3. if you are proficient with Python, you can manage a Virtual Environment for this purpose

Then you can install PySpice using the conda command if you are using Anaconda otherwise run the pip command:

conda install -c conda-forge pyspice

# or

pip install PySpice

# and eventually

pyspice-post-installation --check-install

4.6. On OSX

There are several ways to get Python on OSX:

To install PySpice, please read the Linux instructions.

The Ngspice shared library is also available from Brew:

brew install libngspice

Brew links:

4.7. How to get the Examples

Short answer, you can simply run this command:

pyspice-post-installation --download-example

Long answer, the examples are not installed by pip or setup.py. The installation process only install the PySpice module on your Python environment. You have to download the PySpice archive or clone the Git repository to get the examples. See “Installation from Source”.

4.8. Install a more Recent Version from GitHub using pip

If you want to install a version which is not yet released on PyPI, you can use one of these commands to install the stable or devel branch:

pip install git+https://github.com/FabriceSalvaire/PySpice

pip install git+https://github.com/FabriceSalvaire/PySpice@devel

4.9. Installation from Source

PySpice source code is hosted at https://github.com/FabriceSalvaire/PySpice

You have two solutions to get the source code, the first is to clone the repository, but if you are not familiar with Git, you can simply download an archive from the GitHub page (using the download button) or from the PySpice PyPI page.

To clone the Git repository, run this command:

git clone https://github.com/FabriceSalvaire/PySpice.git

Then to build and install PySpice run these commands:

python setup.py build
python setup.py install

4.10. Tips to Set the Development Environment

Set the PYTHONPATH on Windows:

  • To set this variable from PowerShell, use: $env:PYTHONPATH=’list;of;paths’ just before you launch Python.

  • To set this variable from the Command Prompt, use: set PYTHONPATH=list;of;paths

Fix CP1252 / Unicode errors on Windows:

In some circumstance Windows uses the CP1252 encoding, to change this use: $env:PYTHONIOENCODING="utf_8".

Set PySpice logging level on Windows: $env:PySpiceLogLevel="debug"

4.12. How to Generate the Documentation

To generate the documentation, you will need basically in addition theses Python modules (see requirements-dev.txt):

and also these dependencies (harder to install) to generate some figures:

Then the procedure is basically to run these commands:

inv doc.make-examples
inv doc.make-api

4.13. Ngspice Compilation

Usually Ngspice is available as a package on the most popular Linux distributions. But we recommend to check the compilation options before using it for serious projects.

The procedure to compile Ngspice is explained in the manual and in the INSTALLATION file. Ngspice is an example of complex software where we should not enable everything without care.

Warning

The compilation option –enable-ndev is known to break the server mode.

The recommended way to compile Ngspice on Linux is:

mkdir ngspice-32-build
pushd ngspice-32-build

/.../ngspice-32/configure \
  --prefix=/usr/local \
  --enable-xspice \
  --disable-debug \
  --enable-cider \
  --with-readline=yes \
  --enable-openmp \
  --with-ngshared

 make # -j4
 make install

Note

PySpice source has invoke tasks to compile the Ngspice shared library on Unix, look at ngspice. tasks using the command inv -l to list them.

4.14. How to get Xyce ?

Even though Xyce is released under the terms of the GPLv3 licence, Sandia actually requires that you create a user account on this sign-in page to get the source or download an executable, i.e. you have to provide an email address to Sandia.

The building procedure is clearly explained in the building guide.

You can also find the sources for a Xyce RPM package in this Git repository.