3.3. Installation of the Python Client¶
FORCESPRO offers a Python interface that enables user to formulate a optimization problem, generating a solver for it through communication with the FORCESPRO server, and calling the generated solver directly from Python. It is contained within the FORCESPRO client package together with the MATLAB Client, which can be obtained with a valid license as described in Obtaining FORCESPRO.
This section describes the most common commands needed to go from a blank system to generating and executing the first solver for different operating systems. Before doing so, you may want to double-check the section Requirements below, in particular with respect to supported versions of Python and external packages.
In the following, we assume you have obtained the FORCESPRO client as described in Obtaining FORCESPRO, and unzipped its files into the directory /path/to/forcespro on Unix platforms or C:\path\to\forcespro on Windows. The following installation instructions slightly differ for the operating systems supported, so please refer to the appropriate section.
C:\PythonXY\Scripts\pip.exe install -r C:\path\to\forcespro\requirements.txt
pip3 install -r /path/to/forcespro/requirements.txt
sudo apt-get install gcc libomp-dev
brew install python3 libomp
python3 -m pip install -r /path/to/forcespro/requirements.txt
This assumes you have the Homebrew package manager already installed. If not, run the following before any of the above instructions:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
The Python client has been tested with the following configurations:
A Python installation is required. Note that only compiled Python bytecode for the versions listed below is currently shipped with the client:
Python 2.7 (low-level convex problems only)
If you require a different version, please contact us at firstname.lastname@example.org.
For purposes of readability, for Windows, we will assume you have installed the respective Python version into C:\PythonXY (where X is the major version number and Y the minor version number) throughout the rest of this documentation. On Linux and Mac, we assume you have Python 3 available in your PATH as python3, and Python 2.7 as python.
For any Python version, the following packages from the Python package index (PyPI) need to be installed in the PYTHONPATH:
numpy (tested with version 1.18.3)
scipy (tested with version 1.4.1)
requests (tested with version 2.5; required for server connections)
casadi (version 3.5.1 or 3.5.5 required; optional, only required for high-level interface)
All of these required packages can be conveniently installed through the command-line by running the following command from a terminal (Linux, Mac):
pip3 install -r /path/to/forcespro/requirements.txt
Or, on Windows:
C:\PythonXX\Scripts\pip.exe install -r C:\path\to\forcespro\requirements.txt
Additionally, the following optional packages from the Python package index (PyPI) may need to be installed in the PYTHONPATH for certain special use cases:
matplotlib (tested with version 3.1; optional, only required for plotting in the example code)
msgpack (tested with version 1.0.5; optional, only required for (de)serialization of C parameters)
suds-community (tested with version 0.7; optional, only required when connecting to code generation server via WSDL instead of RestAPI)
Those optional packages (along with the required packages above) can be conveniently installed through the command-line by running the following command from a terminal (Linux, Mac):
pip3 install -r /path/to/forcespro/requirements-full.txt
Or, on Windows:
C:\PythonXX\Scripts\pip.exe install -r C:\path\to\forcespro\requirements-full.txt
Nonlinear symbolic problem formulations are translated into C code by the FORCESPRO client. In order to generate solvers for these kinds of problems, a C compiler and linker must thus be present on the host machine. The following compilers have been tested and are supported by the FORCESPRO Python client:
On Windows: Microsoft Visual Studio C Compiler 2019 and 2015 (Can be obtained by downloading the Microsoft Visual Studio Community IDE)
On Linux: GNU Compiler Collection (GCC), tested with version 9.3.0
On Mac: Apple clang version 11.0.3 (Can be obtained by installing the XCode command-line tools)
Additionally, on Linux, the following package must be installed if you wish to generate solvers making use of parallel execution (options.parallel = True) or mixed-integer nonlinear problem (MINLP) solvers:
sudo apt-get install libomp-dev
On Mac, for parallel solver generation and MINLP problems, the following package must be installed through Homebrew:
brew install libomp
Once the FORCESPRO client has been downloaded and the requirements have been installed as outlined above, you will need to tell the Python interpreter where to look for the forcespro and forcespro.nlp packages which implement the FORCESPRO client interface in Python. Doing so will allow you to write import forcespro or import forcespro.nlp in your scripts to import the FORCESPRO functionality. To make the FORCESPRO client available this way, you have several options:
Add the FORCESPRO client directory to your PYTHONPATH before calling any scripts that require FORCESPRO from the command line. In a Windows PowerShell this is done by:
In Windows cmd.exe:
On Unix (Linux and Mac):
After doing so, you can call any script that requires FORCESPRO, and the script may include import forcespro or import forcespro.nlp statements without needing to know where your actual FORCESPRO client directory is.
Add the FORCESPRO client directory to sys.path before importing:
sys.path.insert(0, '/path/to/forcespro') # On Unix
sys.path.insert(0, 'C:\\path\\to\\forcespro') # On Windows, note the doubly-escaped backslashes
Note that this reduces the portability of any scripts using FORCESPRO, as it hard-codes the location of FORCESPRO inside the script.
In order to obtain the latest version of the FORCESPRO client, a Python script for automatic upgrading is available.
In order to use it, navigate to the FORCESPRO client directory and execute the updateClient.py script in Python.
$ cd /path/to/forcespro
$ python updateClient.py
Alternatively, the FORCESPRO client can also be updated through MATLAB, see Keeping FORCESPRO up to date.
Older versions of FORCESPRO can be installed and run by specifying the server URL as
X-Y-Z with the version
numbers of a selected FORCESPRO version
First, sync your client to the server by updating it with
python updateClient.py https://forces-X-Y-Z.embotech.com
Then, in order to generate a solver, set the code generation server as
codeoptions.server = 'https://forces-X-Y-Z.embotech.com'