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.

3.3.1. Quick Guide

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.

3.3.1.1. Windows (PowerShell)

C:\PythonXY\Scripts\pip.exe install -r C:\path\to\forcespro\requirements.txt
$env:PYTHONPATH="C:\path\to\forcespro"
C:\PythonXY\python.exe C:\path\to\forcespro\examples\Python\HighLevelInterface\RobotArmSqpRti\robot_sim.py

3.3.1.2. Linux Ubuntu

pip3 install -r /path/to/forcespro/requirements.txt
sudo apt-get install gcc libomp-dev
export PYTHONPATH="/path/to/forcespro":$PYTHONPATH
python3 /path/to/forcespro/examples/Python/HighLevelInterface/RobotArmSqpRti/robot_sim.py

3.3.1.3. Mac

xcode-select --install
brew install python3 libomp
python3 -m pip install -r /path/to/forcespro/requirements.txt
export PYTHONPATH="/path/to/forcespro":$PYTHONPATH
python3 /path/to/forcespro/examples/Python/HighLevelInterface/RobotArmSqpRti/robot_sim.py

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)"

3.3.2. Requirements

The Python client has been tested with the following configurations:

3.3.2.1. Python

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)

  • Python 3.6

  • Python 3.7

  • Python 3.8

  • Python 3.9

If you require a different version, please contact us at forces@embotech.com.

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.

3.3.2.2. Python Packages

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

3.3.2.3. Available Compiler

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

3.3.3. Adding the FORCESPRO Python Client to your Python path

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:

3.3.3.1. Option A: Setting the PYTHONPATH environment variable

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:

$env:PYTHONPATH="C:\path\to\forcespro"

In Windows cmd.exe:

set PYTHONPATH=C:\path\to\forcespro

On Unix (Linux and Mac):

export PYTHONPATH=/path/to/forcespro

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.

3.3.3.2. Option B: Setting sys.path inside Python scripts

Add the FORCESPRO client directory to sys.path before importing:

import sys
sys.path.insert(0, '/path/to/forcespro')  # On Unix
sys.path.insert(0, 'C:\\path\\to\\forcespro')  # On Windows, note the doubly-escaped backslashes
import forcespro
import forcespro.nlp

Note that this reduces the portability of any scripts using FORCESPRO, as it hard-codes the location of FORCESPRO inside the script.

3.3.4. Keeping FORCESPRO up to date

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.

3.3.5. Installing and running older versions of FORCESPRO

Older versions of FORCESPRO can be installed and run by specifying the server URL as https://forces-X-Y-Z.embotech.com, replacing X-Y-Z with the version numbers of a selected FORCESPRO version vX.Y.Z. 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'