2.3. Installation of the Python Client

FORCES PRO offers a Python interface that enables user to formulate a optimization problem, generating a solver for it through communication with the FORCES PRO server, and calling the generated solver directly from Python. It is contained within the FORCES PRO client package together with the MATLAB Client, which can be obtained with a valid license as described in Obtaining FORCES PRO.

2.3.1. Quick Guide

If you want to get up and running quickly, we have compiled the most common commands needed to go from a blank system to generating and executing the first solver in a example below. If you encounter issues, please have a look at the more detailed description of the required prerequisites below.

In the following, we assume you have obtained the FORCES PRO client as described in Obtaining FORCES PRO, and unzipped its files into the directory /path/to/forces/pro on Unix platforms or C:\path\to\forces\pro on Windows. The following installation instructions slightly differ for the operating systems supported, so please refer to the appropriate section.

2.3.1.1. Windows (PowerShell)

C:\PythonXY\Scripts\pip.exe install numpy scipy suds-jurko casadi matplotlib
$env:PYTHONPATH="C:\path\to\forces\pro"
C:\PythonXY\python.exe C:\path\to\forces\pro\examples\robot_sim.py

2.3.1.2. Linux Ubuntu

pip3 install numpy scipy suds-jurko casadi matplotlib
sudo apt-get install gcc libomp-dev
export PYTHONPATH="/path/to/forces/pro":$PYTHONPATH
python3 /path/to/forces/pro/examples/robot_sim.py

2.3.1.3. Mac

xcode-select --install
brew install python3 libomp
python3 -m pip install numpy scipy suds-jurko casadi matplotlib
export PYTHONPATH="/path/to/forces/pro":$PYTHONPATH
python3 /path/to/forces/pro/examples/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)"

2.3.2. Requirements

The Python client has been tested with the follwing configurations:

2.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

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

For purposes of readibility, 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.

2.3.2.2. Python Packages

For any Python version, the following packages from the Python package index (PyPI) must be installed in the PYTHONPATH:

  • numpy (Tested with version 1.18.3)

  • scipy (Tested with version 1.4.1)

  • casadi (Version 3.5.1 required only for high-level interface)

  • matplotlib (Required only for plotting in the example code)

Additionally, Python 2.7 requires the following packages:

  • suds

Additionally, Python versions 3.x require the following packages:

  • suds-jurko

All of these packages can be conveniently installed through the command-line by running the following command from a terminal (Linux, Mac):

pip3 install numpy scipy casadi matplotlib suds-jurko

Or, on Windows:

C:\PythonXX\Scripts\pip.exe install numpy scipy casadi matplotlib suds-jurko

2.3.2.3. Available Compiler

Nonlinear symbolic problem formulations are translated into C code by the FORCES PRO 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 FORCES PRO 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 MINL-problems, the following package must be installed through Homebrew:

brew install libomp

2.3.3. Adding the FORCES PRO Python Client to your Python path

Once the FORCES PRO 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 FORCES PRO client interface in Python. Doing so will allow you to write import forcespro or import forcespro.nlp in your scripts to import the FORCES PRO functionality. To make the FORCES PRO client available this way, you have several options:

2.3.3.1. Option A: Setting the PYTHONPATH environment variable

Add the FORCES PRO client directory to your PYTHONPATH before calling any scripts that require FORCES PRO from the command line. In a Windows PowerShell this is done by:

$env:PYTHONPATH="C:\path\to\forces\pro"

In Windows cmd.exe:

set PYTHONPATH=C:\path\to\forces\pro

On Unix (Linux and Mac):

export PYTHONPATH=/path/to/forces/pro

After doing so, you can call any script that requires FORCES PRO, and the script may include import forcespo or import forcespro.nlp statements without needing to know where your actual FORCES PRO client directory is.

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

Add the FORCES PRO client directory to sys.path before importing:

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

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

2.3.4. Keeping FORCES PRO up to date

In order to obtain the latest version of the FORCES PRO client, a Python script for automatic upgrading is available.

In order to use it, navigate to the FORCES PRO client directory and execute the updateClient.py script in Python.

$ cd /path/to/forces/pro
$ python updateClient.py

Alternatively, the FORCES PRO client can also be updated through MATLAB, see Keeping FORCES PRO up to date.