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:
- PyYAML, for the intended usage of :ref:`PyFPAA <fpaa>`
- SymPy, for the :ref:`SymPy/Computer Algebra interface <cas>` of PyDDA
- SciPy, for the :ref:`SciPy interface <dda-scipy>` of PyDDA. Furthermore, some additioanl postprocessing tools, as well as unit tests and examples of PyDDA require NumPy and Matplotlib to be installed.
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.
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 :-)
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.
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).
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).
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:
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
PAUSEHere, 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.
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.
We recommend the following way of obtaining and installing the PyAnalog code on your developer machine using setuptools by using the development mode (which creastes a user-wide softlink to the working copy):
$ cd prefered/directory/for/code/of/the/analogians
$ git clone https://github.com/anabrid/pyanalog.git # this works always
$ git clone [email protected]:anabrid/pyanalog.git # use this if you are experienced at github
$ cd pyanalog
$ python3 setup.py develop --userAfter these steps you are ready to use import the pyanalog package modules from any
Python3 script anywhere on your system, but only as your current user. The installation
is successful when you can for instance import dda somewhere:
$ python3
Python 3.8.6 (default, Sep 30 2020, 04:00:38)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import dda
>>> dda.Symbol("foo")
foo
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://[email protected]:anabrid/pyanalog.gitThis 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.
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.