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.
22.214.171.124. 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
126.96.36.199. 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
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)"
The Python client has been tested with the follwing 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 email@example.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.
188.8.131.52. 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:
Additionally, Python versions 3.x require the following packages:
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
184.108.40.206. 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:
220.127.116.11. 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:
In Windows cmd.exe:
On Unix (Linux and Mac):
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.
18.104.22.168. 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.