Obtaining and installing PyAnalog

PyAnalog can be used on a “vanilla” Python installation without any dependencies. Only make sure you use a recent Python 3 installation: We use f-strings, so at least Python 3.6 is required.

In order to use some of the advanced features, we recommend to install the following Python packages:

The code is primarily developed on Linux, but has also been used successfully on Mac OS X and even Microsoft Windows. If you run one of these platforms and never got in contact to Python coding there yet, the following guides and tips can be helpful for getting a PyAnalog running on Mac or Windows.

Obtaining the code

The PyAnalog code is public available at https://github.com/anabrid/pyanalog. Furthermore, we maintain an in-house (private) mirror at https://lab.analogparadigm.com/software/pyanalog. You don’t need access to the later repository right now.

Note

We try to keep the master branch in a working condition. If things do not work, you might want to checkout the last working commit in the master. You can recognize it at the github commit history where there is a green checkmark at the tests (and not a red crossmark). I promise there will be releases/versions/tags soon :-)

Mac OS X-specific installation notes

First, make sure you have some (recent) Python 3 installed on your machine. You can check by opening a terminal and executing python --version. If still have installed a very old version such as Python 2.7, you need to upgrade it. There are many guides in the web. It is likely that the manual installation of a newer Python version will give you two Pythons installed on your system. In many situations, you have to call the more recent version by invoking a command such as python3 in place of python. The same aplies with the Python package manager pip3 instead of pip. There is nothing wrong with this, and similar situations exist on some older Linux distributions where Python2 and Python3 live next to each other on the same system.

Mac OS X quickstart guide

The following code block shows a minimal way how quickly to start on Mac OS X. This assumes you have some C++ compiler available, e.g. from Xcode (Clang).

$ pip3 install scipy numpy matplotlib # the only dependencies you really need
$ git clone https://github.com/anabrid/pyanalog.git
$ cd pyanalog
$ python3 setup.py develop --user # this way you can import the python module from anwhere
$ cd examples/traditional-dda-circuits
$ python3 -m dda chua.dda c > chua.cpp
$ c++ --std=c++1z chua.cpp     # c++1z-Standard is specific to Mac / clang
$ ./a.out > chua.dat
$ gnuplot etc...

Note that with the Clang/LLVM compiler, you have to set --std=c++1z instead of --std=c++17 (as with GCC).

Microsoft Windows-specific installation notes

For Windows, there are several Python distributions available. The most prominent and mature is certainly Anaconda. Conda is much into Python enviroments, which is somewhat orthogonal to the standard Python package manager pip. However, there are straightforwards ways to install the requirements.txt in conda (see also here how to use pip in an environment).

Other options exist. For instance, you can install Python also directly from the Windows store (and use pip as usual). To do so, just open any Terminal (Powershell or cmd.exe) and type python. This will guide you straight to Windows store. You can also install the popular IDE Spyder which ships a Python installation with itself. This is particularly handy because it provides also a lean way to setup the developer machine. For instance, there is a menu item Tools/Current user environment variables… which allows you to set the system wide PATH.

Regarding C++ compilers, we have made best experiences with MinGW, the GCC port for Windows. Make sure you add the installation directory to your PATH in order to be able to access the compiler from everywhere (i.e. every terminal).

Regarding Windows Environment variables

The HKEY_CURRENT_USER\Environment should, as a list, probably contain paths such as (in this example assumung you have installed MinGW and Spyder, system-wide):

C:\MinGW\bin
C:\Program Files\Spyder\Python

This way, you are fully flexible to use both the C compiler as well as the Python binaries from everywhere. If you still experience that Windows wants you to visit the Microsoft store in order to do a second and independent installation of Python (which means you also have two sets of completely independent module installations, individually managed by pip), you might want to carry out these steps in order to get rid of the python stub pointers to the store:

cd C:\Users\<you name>\AppData\Local\Microsoft\WindowsApps
del python.exe
del python3.exe

In case you use Anaconda and do not want (or can) add Python to your path, then you can also start write some wrapper BAT script for your actual Python script:

run-script.bat
REM conda activate base
REM This activates (base) in  current scope
REM Probably have to change %HOMEPATH% to where conda is installed (user or system wide)
CALL %HOMEPATH%\anaconda3\Scripts\activate.bat

python.exe your-actual-script.py

PAUSE

Here, the Windows Batch call works the same way as source does in the unix bash, allowing you to invoke python.exe or pip.exe afterwards. Pause prevents the Windows terminal from closing after invoking, so you can still see the output when launching the script by double-clicking the Bat file in Windows explorer.

Further software recommendations for Windows

If you do not have a comfortable IDE, you might want to look into Microsoft Powershell as well as the new Windows Terminal which can be obtained in the Microsoft store for free.

While it is attractive to download the PyAnalog software as a ZIP file from Github, we recommend you instead to install a proper Git client, such as the comprehensible Github Desktop GUI. It can also be used independently from the Windows Git Command Line Interface, which itself can be installed with winget. With git, it is as easy as a single click on update or an invocation of git pull to obtain a more recent version of the PyAnalog code.

Note

At Windows, we have experienced some hazzles with UTF-16 encoded files. While we are working on improving the compatibility with the PyAnalog tools, you can convert any file to UTF-8 by using such a Powershell command:

Get-Content nameOfYourFile.txt | Out-File -Encoding UTF8 nameOfYourFile-fixed.txt

Also don’t forget that Windows generally does not allow you to open files for writing while they are opened for reading. If you are used to the unix kind of dealing with files, this can make some steps more cumbersome and result in more copies of files.

User (non-developer) installation

If you want to install the package, just call pip install or python3 setup.py install in the repository root directory after cloning or without any cloning by just running:

$ pip install git+ssh://git@github.com:anabrid/pyanalog.git

This will automatically install all the dependencies from the requirements.txt file.

You can also add the flags --user for a per-user (instead of system wide) installation. If you want to perform an upgrade on an existing installation, add the --upgrade flag.

Note that by using this installation method, you cannot easily make edits to the pyanalog code itself. This is perfectly fine if you only want to use the library.

Note

Since the overall code is still subject to heavy changes, you should also opt in for the developer machine setup installation method if you do not indend to work on the PyAnalog code. This is for easier updating or changing versions with git without having to perform a fresh installation. Basically, with the development installation way, you can change/update/downgrade the PyAnalog code and immediately profit in your applications.

Using without installation

We differentiate between installing dependencies for using PyAnalog and installing PyAnalog itself. While you should ensure having all the dependencies (which are not a lot, but see above), when it comes to installing PyAnalog, you can gratefully skip this step if you don’t bother or don’t like to do so.

That is, you can just checkout the repository, navigate to the root directory and open a python script from there. This way, you don’t have to install anything but have the modules right in your PYTHONPATH. This is really the easiest way of getting started if you don’t want to mess around with pip or setup.py.

However, it is usually good practice to use virtualenv. Using virtualenv was not covered in this document at all, but standard routines apply, given the presence of requirements.txt and setup.py.