Install the PYTHON module

This is an optional module that adds Python support in Chrono.

Features

The PYTHON module allows users to use Python
for creating simulations. As with any scripting language, this allows for immediate execution, no compilers involved, simple to use, etc. This module is used to build the PyChrono wrapper.

This module consists of two main sets of build targets:

  • The Python modules for PyChrono. Currently, the PyChrono Python modules that are built are:
    • pychrono, which wraps most Chrono classes, equivalent to the chrono namespace
    • pychrono.fea, which wraps FEA classes, equivalent to the chrono::fea namespace.
    • pychrono.postprocess, which wraps the POSTPROCESS module.
    • pychrono.irrlicht, which wraps the IRRLICHT module.
    • pychrono.pardisomkl, which wraps the Pardiso MKL module.
    • pychrono.cascade, which wraps the CASCADE module (doesn't work on the Mac).
  • A PYPARSER module, which is a C++ module for parsing / executing / interpreting Python instructions from C++ programs.

Requirements

  • To run applications based on this module:
    • you must have Python installed. On the Mac type brew install python to get python3. The preinstalled python(2) doesn't work with pychrono.
  • To build this module:
    • you must have Python installed,
    • you must have the SWIG wrapper generator installed. On the Mac type brew install swig.
Some previous SWIG versions have a bug related to processing private and protected C++11 enum classes. This bug has been fixed in recent releases. Use SWIG-3.0.12. On the Mac SWIG-4.0.1 is known to work. It is installed by homebrew.

Building instructions

  1. Install SWIG on your system. Version 3.0.12 or higher is required. (on Windows, just unzip where you want).
  2. Repeat the instructions for the full installation, but when you see the CMake window, you must add the following steps:
  3. Set the ENABLE_MODULE_PYTHON as 'on', then press 'Configure' (to refresh the variable list)
  4. If prompted, set the CH_PYTHONDIR variable to the directory where you have your copy of Python. For example, it could be C:/Python33
  5. When you pressed 'Configure', CMake should have detected your SWIG tools. This should create two variables in CMake called SWIG_DIR and SWIG_EXECUTABLE. If all is fine, they should automatically contain meaningful values, for example C:/swigwin-3.0.12/Lib and C:/swigwin-3.0.12/swig.exe , so you do not need to touch them. (On Windows, you may need to set them by hand).
  6. Press 'Configure' again, then 'Generate', and proceed as usual in the installation instructions.

If you have multiple Python installations on the same machine, you may need to explicitly specify which one to use in the call to CMake. For example, under Linux (Mac is similar to Linux):

% ccmake -DPYTHON_EXECUTABLE:FILEPATH=/usr/local/python/3.6.0/bin/python3
  -DPYTHON_LIBRARY=/usr/local/python/3.6.0/lib/libpython3.so
  -DPYTHON_INCLUDE_DIR=/usr/local/python/3.6.0/include
  ../../chrono
On the Mac:
% ccmake -DPYTHON_EXECUTABLE:FILEPATH=$(which python3) ../../chrono

After successful compilation, the PyChrono modules can be used either from the BUILD tree or, after installation, from the INSTALL tree. In order for the generated Python modules to be accessible, you must set/append to the PYTHONPATH environment variable. During configuration, the Chrono CMake script will output the proper paths to be used in setting the PYTHONPATH environment variables; for example:

  • Windows:
  • Linux:

Setting/changing environment variables is platform-specific.

  • On Windows, you can (globally) set environment variables in 'Control Panel -> System -> Advanced system settings':

  • On Linux, using bash shell:

    To permanently set PYTHONPATH, you can add the above to your .bashrc file (or the appropriate initialization file for your shell).

Usage

For more details on how to use the resulting modules, look here:

  • C++ functions (as Python parser)
    • Look at the API section of this module for documentation about C++ functions.
    • Look at the C++ source of demos to learn how to use the C++ functions of this module.
  • Python functions (as PyChrono )
    • Look at the reference of PyChrono, about using Chrono from the Python side.
    • Look at the Python source of demos.

Notes

The build process of the Python modules, as generated by CMake, consists of these automatic steps:

  • SWIG preprocesses C++ source code files in order to generate a .cxx wrapper file that contains the code for accessing C++ functions through the API, and some .py files,
  • the C++ compiler compiles the .cxx file and generates one or more library files,
  • the SWIG-generated files (*.py) and resulting library files (*.pyd on Windows and *.so on Linux/Mac) are collected in a single location in the BUILD tree, so that they can be used directly from there. Similarly, after installation, all Chrono::Python modules are copied in a single location in the INSTALL tree. See the comments above about these exact locations for your particular configuration and about setting the PYTHONPATH environment variable.
Note that the SWIG tool requires a few minutes to process the source and generate the .cxx wrapper file. When you start the compilation of the entire Chrono project, the process might look 'frozen' for one or two minutes when SWIG does its job.
This module is tested with Python 3.3 and 3.2. Support of the previous version Python 2.7 is discontinued.
If you installed Python for 32 bit, you must compile Chrono in 32 bit mode. If you installed Python for 64bit, you must compile Chrono in 64 bit mode.
In some distributions of Python, the debug library 'python33_d.lib' (the debug version of the python33.lib library) is not included by default. If you need it because you recompile the python module in debug mode, either you recompile the entire Python source, or you modify pyconfig.h to force the use of python33.lib by following these steps:
  1. Comment out the line:
    //#define Py_DEBUG
  2. Modify
    #if defined(_DEBUG)
    #pragma comment(lib,"python33_d.lib")
    to
    #if defined(_DEBUG)
    #pragma comment(lib,"python33.lib")
  3. Press 'Advanced' in CMake, set the PYTHON_DEBUG_LIBRARY to the same lib that you have in PYTHON_LIBRARY, and press 'Generate' so that your project will link 'python33.lib' instead than 'python33_d.lib'.