Authors
=======
Arpad Buermen

parts of the code contributed by 

Janez Puhan (HSPICE file interface)
Jernej Olensek (global optimization test problems)
Gregor Cijan (cost collector)


Credits 
=======
PyOPUS uses code from the following packages
- FORTRAN test problems implemented by
  - Napsu Karmitsa
  - Ladislav Luksan and Jan Vlcek
  - Jorge More and Stefan Wild
- MADS test problems MDO and STYRENE implemented by Sebastien Le Digabel,
  Charles Audet, et. al. 

See src/*.zip and src/*.tar.gz for details on respective licenses. 


Installation from wheel files
=============================

Installation for Linux
----------------------
Tested under Debian 13 (Trixie) amd64

1. Install Spice Opus (if you are not using some other supported simulator)
	Download from http://www.spiceopus.si
	Install to /usr/local

2. Install prerequisites (Debian packages)
	Become root
	Type
		apt-get install libstdc++6 libopenmpi-dev liblapack3 liblapack-dev libblas3 libblas-dev kicad python3 python3-venv python3-pip python3-wheel python3-setuptools python3-setuptools-scm python3-numpy python3-scipy python3-matplotlib python3-greenlet python3-mpi4py python3-pyqt5 python3-lxml python3-pyqtgraph python3-cvxopt gfortran
		
	This installs packages
		libstdc++6
		libopenmpi-dev
		liblapack3
		liblapack-dev
		libblas3
		libblas-dev
		kicad (needed for schematic entry)
		python3
		python3-venv
		python3-pip
		python3-wheel
		python3-setuptools
		python3-setuptools-scm
		python3-numpy
		python3-scipy
		python3-matplotlib
		python3-greenlet
		python3-mpi4py
		python3-pyqt5
		python3-lxml
		python3-pyqtgraph
		python3-cvxopt
		python3-pandas
		gfortran (for CUTEr support)

3. Python virtual environment (Debian 12 and newer)
	Starting with Debian 12 you will need a Python virtual environment. Since 
	Debian 12 .whl files are not allowed to be installed in the system-wide 
	Python environment because they can change the behavior of the interpreter 
	which could affect system packages that depend on Python. A virtual 
	environment is isolated from the system-wide Python installation. 
	
	Next, create a virtual environment. Give virtual environment access to 
	system site-packages directory (i.e. the virtual environment will include 
	all python modules that were installed with apt). 
	
	python3 -m venv --system-site-packages <path to virtual environment>
	
	To run the interpreter in the virtual environment, type
	
		<path to virtual environment>/bin/python3
	
	or 
	
		<path to virtual environment>/bin/python
	
	To install a .whl file in the environment, type
	
		<path to virtual environment>/bin/pip3 ...
	
	or
	
		<path to virtual environment>/bin/pip ...
	
	If you want a program that depends on python to use the virtual python 
	environment, you need to activate it by sourcing the appropriate shell 
	script in <path to virtual environment>/bin. If you are using Bash, type 
	
		source <path to virtual environment>/bin/activate
		
	The prompt will change to reflect the virtual environment you are using. 
	To deactivate the virtual environment, type
		
		deactivate
	
	You will need to activate the virtual environment before you use the 
	PyOPUS GUI (i.e. before you run the pyog command). 
	You will also need to activate it before you install any .whl file. 

4. Activate virtual environment
	source 	<path to virtual environment>/bin/activate

5. Datatable module (optional)
    You can also install datatable. It is faster than Pandas. Datatable is 
    not a replacement for Pandas, but PyOPUS uses it if it is available. 
    Because there is no Debian package for datatables you have to install 
    it manually with pip3 from PyPI. 
    
		pip3 install datatable
       
6. Install PyOPUS
	Get the PyOPUS .whl file for Linux from
		http://fides.fe.uni-lj.si/pyopus/download/0.12/PyOPUS-0.12-cp313-cp313-linux_x86_64.whl
	
	Now you can install PyOPUS. Become root and type 
		pip3 install PyOPUS-0.12-cp313-cp313-linux_x86_64.whl


Installation for Windows (quickstart)
-------------------------------------
Tested under Windows 11

1. Install KiCad (for schematic entry), tested with 6.0.4 x86_64
	Download from http://www.kicad.org/
    	Install

2. Install Spice Opus (if you are not using some other supported simulator)
	Download from http://www.spiceopus.si
    	Install to c:\SpiceOpus
	Reboot. 

3. Download PyOPUS 0.12 Windows quickstart from 
	http://fides.fe.uni-lj.si/pyopus/download/0.12/PyOPUS-0.12-quickstart-win_amd64.zip
	
    Unpack the zip file to c:\. 
    This will create folder c:\PyOPUS-0.12-quickstart-win_amd64
   
4. Install Python3
    In c:\PyOPUS-0.12-quickstart-win_amd64 run the Python3 installer
	python-3.13.11-amd64.exe
		Check "Add Python to path"
		Click "Customize installation"
		Check "PIP"
		Check "TCL/TK and Idle"
		Click "Next"
		Check "Install for all users"
		Check "Associate files with Python"
		Check "Add Python to environment variables"
		Check "Precompile standard library"
		Install to c:\Python313

    If asked, allow the Python installer to remove the 260 character 
    path length limitation. 

5. Install Microsoft MPI
    In c:\PyOPUS-0.12-quickstart-win_amd64 run the MSMPI installer
    msmpisetup.exe

6. Install prerequisite wheel files and PyOPUS
    The required wheel files are in c:\PyOPUS-0.12-quickstart-win_amd64
    along with the PyOPUS wheel file. Install them by running 
   	install.bat

7. Now you can delete
	c:\PyOPUS-0.12-quickstart-win_amd64
	
	
Installation for Windows (from your own package sources)
--------------------------------------------------------
Tested under Windows 11

1. Go through steps 1-3 of Installation for Windows (quickstart)

2. Download Python 3.13.11 and install it to c:\Python313. 
   Make sure the Python interpreter is in the system path, i.e. add
   c:\Python313 and c:\Python313\Scripts to the PATH environmental variable. 

3. Download Microsoft MPI and install it. 

4. Install Python libraries
   wheel setuptools setuptools-scm numpy scipy cvxopt matplotlib greenlet mpi4py lxml pyqt5 pyqtgraph pandas

   Optionally you can also install 
   python-datatable
   
   Make sure mpi4py you are using is linked against the installed version of Microsoft MPI. 
   
5. Download PyOPUS from 
	http://fides.fe.uni-lj.si/pyopus/download/0.12/PyOPUS-0.12-cp313-cp313-win_amd64.whl
   
   Install it by opening the command prompt and typing
	pip install PyOPUS-0.12-cp313-cp313-win_amd64.whl


Configuring KiCad
=================
PyOPUS uses KiCad 5+ as schematic editor. 
Start the schematic editor (eeschema). If you have a Python virtual 
environment, activate it first and then start eeschema. 
In KiCad 5 select Tools/Generate Netlist File in the menu. 
In KiCad 6+ select File/Export/Netlist in the menu. 
Click "Add Plugin". Under "Name" enter::

  Spice Opus

Under "Netlist command" enter::

  python3 -m pyopus.netlister.kicad -i "%I" -o "%O"

For Windows the command for running the netlister is::

  <full path to pythonw.exe> -m pyopus.netlister.kicad -i "%I" -o "%O"

Click "OK". A tab will appear for generating Spice Opus netlists. 
You need to do this only once. KiCad will store your settings in its 
configuration. For Linux make sure python3 is in your path. Also make 
sure the PyOPUS installation folder is listed in the PYTHONPATH 
environmental variable if PyOPUS is not installed in the Python libraries 
folder. 

To make KiCad 5 behave in the same manner as KiCad 4 when placing symbols, 
select Preferences/General Options in the menu. Select the Editing tab. 
Uncheck:
  
  * Automatically place symbol fields
  * Allow field autoplace to change justification
  * Always align autoplaced fields to the 50 mil grid

The pyopus symbol library for KiCad 5 is distributed with PyOPUS demos in 
demo/kicad/library as two files: pyopus.lib (symbol definitons) and 
pyopus.dcm (auxiliary data). 
For KiCad 6+ there is only one file named pyopus.kicad_sym. 
To specify the location of the pyopus symbol library, select 
Preferences/Manage Symbol Libraries in the menu. In the Global Libraries 
tab click on Append Library. Fill the created entry with the following values:

  * Active: mark checkbox
  * Nickname: pyopus
  * Library Path: <absolute path to pyopus.lib for V5 or pyopus.kicad_sym for V6>
  * Plugin Type: Legacy for V5, KiCad for V6
  * Description: PyOPUS symbol library

Leave the Options field empty. This procedure also needs to be done only once. 

To generate a Spice Opus netlist, select Tools/Generate Netlist File (KiCad 5)
or File/Export/Netlist (KiCad 6+) in the menu. Choose the "Spice Opus" tab, and 
click on "Generate". A window with the generated netlist will pop up. In case 
of an error the window will show the error message. To disable the popup 
window and show it only in case of an error add the ``-n`` option to the 
Netlist command. 

Generating the netlist via the File/Export/Netlist menu entry in KiCad 6+ is a 
bit awkward. An alternative approach is to set up the netlister as a bill of 
materials (BOM) generator script. You can achieve this in the following 
way. Select Tools/Generate BOM (in KiCad 9 it is called Generate Legacy Bill 
of Materials...). Click the "+" icon to add a new BOM script. Select any .py 
file on your computer and click Open. Give a name to to the script (e.g. 
PyOPUS Netlister for KiCad). Change the command line running the generator into: 

  "python3" -m pyopus.netlister.kicad -i "%I" -o "%O"
  
For Windows change it to

  "<full path to pythonw.exe>" -m pyopus.netlister.kicad -i "%I" -o "%O"
  
Now you can generate the netlist by clicking the BOM icon, choosing the 
"PyOPUS Netlister for KiCad" BOM generator script and clicking Generate. 

Note: netlisting in KiCad 9 under Windows works only if invoked from 
Tools/Generate Legacy Bill of Materials... with "Show console window" 
enabled. This seems to be a KiCad bug. 


Preparing PyOPUS for parallel processing with MPI 
=================================================
If you intend to run parallel processes on your local machine, there is 
nothing further to do. 

If you intend to run parallel processes on a computer farm and your home 
folder /home/<username> is nfs-mounted on all worker computers as 
/home/<username> there is nothing further to do. If this is not the case
see the documentation of pyopus.parallel.base and set the 
	PARALLEL_MIRRORED_STORAGE 

environmental variable on all computers participating in parallel 
processing. 

If you want your workers to use local copies of files (mirroring) for 
faster processing and you intend to use /tmp folder for storing the 
local copies, there is nothing further to do. If you want to store the 
local copies somewhere else see the documentation of pyopus.parallel.base 
and set the 
	PARALLEL_LOCAL_STORAGE 
	
environmentral variable on all computers participating in parallel 
processing. 

Under Windows you must start 
	
	smpd -d 3

in a command prompt on all hosts where you want to start MPI processes 
before starting any parallel runs. The ``-d 3`` option will produce debug 
output which will help you solve problems with your MPI setup. The smpd 
executable is a part of Microsoft MPI. 

Parallel processing on a computer farm was not tested under Windows. 
This is uncharted territory. Reports are welcome. 


Demos and documentation
=======================
Demos and documentation in html format are available as a .tar.gz archive at 
	http://fides.fe.uni-lj.si/pyopus/download/0.12/PyOPUS-0.12-doc-demo.tar.gz

Unpacked demos are available for browsing at
	http://fides.fe.uni-lj.si/pyopus/download/0.12/demo

Unpacked docs can be browsed at
	http://fides.fe.uni-lj.si/pyopus/download/0.12/docsrc/_build/html
	
	
Building PyOPUS from sources
============================
Download the source tarball from 
	http://fides.fe.uni-lj.si/pyopus/download/0.12/PyOPUS-0.12.tar.gz

and unpack it. Since 0.11.2 you can also clone the main branch from the 
repository to get the latest merged bugfixes
    git clone https://codeberg.org/arpadbuermen/PyOPUS.git

or clone a tagged version (0.12 or newer)
    git clone --branch v0.12 https://codeberg.org/arpadbuermen/PyOPUS.git


Building for Linux (wheel, demos and documentation, and source)
---------------------------------------------------------------
Tested under Debian 13 (Trixie) amd64

1. Install prerequisites for Linux PyOPUS installation

2. Install prerequisites for building. Type
	apt-get install gcc g++ libstdc++-14-dev make texlive texlive-latex-extra dvipng graphviz python3-wheel python3-dev python3-sphinx python3-sphinx-rtd-theme python3-setuptools python3-setuptools-scm python3-setuptools-whl python3-build

   This installs packages
	gcc
	g++
	libstdc++-14-dev
	make
	texlive
	texlive-latex-extra
	dvipng
	graphviz
	python3-dev
	python3-sphinx
	python3-sphinx-rtd-theme
	python3-wheel
	python3-setuptools
	python3-setuptools-scm
	python3-setuptools-whl
	python3-build

   Note: install libstdc++xx-dev where xx matches the version of the g++ compiler. 	

3. Activate the Python virtual environemnt (if you have one). 
   In the folder where PyOPUS sources are located type
	./pack
   
   The wheel file, demos and documentation, and the source package 
   will be placed under dist/

   
Building for Windows (wheel only)
---------------------------------
Tested under Windows 11

1. Install prerequisites for Windows PyOPUS installation

2. Install prerequisites for building
	Visual Studio 2022
	Python libraries (in command prompt)
		pip install setuptools
		pip install setuptools-scm
		pip install wheel
		pip install build

3. If PyOPUS was installed in development mode (editable install) 
   uninstall it before building by typing
	pip uninstall pyopus

   This command is commented out in the beginning of pack.bat. 

4. Start VS 2022 x64 Native Tools Command Prompt, 
   go to the folder where PyOPUS sources are located, and type
	pack.bat
   
   The wheel file will be placed under dist/
   

Install PyOPUS for development (in source folders)
--------------------------------------------------
In this way PyOPUS is installed in the folder where the sources 
used for building it are located. In this way all changes to .py 
files will affect te behavior of the library immediately. This 
kind of installation is also referred to as editable install. 

Enter the source folder (where pyopus/ subfolder is located). 
First, build PyOPUS with 
    python3 -m build --no-isolation --wheel
	
Under Linux type:
    pip3 install -e . --no-deps

Due to some quirk in pip that prevents editable installation of PyOPUS 
use the following command under Windows:
	python setup.py develop

Under Linux the editable installation of PyOPUS can be removed by typing: 
	pip3 uninstall pyopus

Under Windows use: 
	pip uninstall pyopus

This command is commented out at the end of the pack.bat script for 
Windows. 

Under Linux development install is performed by the pack script before 
the documetation is built in order for Sphinx to be able to import 
PyOPUS modules. 
