Release Information

Project:	Siconos
Internal Release Number:	1.0
Last update:	September 15, 2005
Related Documents:	Design Glossary

 

What for?	To provide an easy-use interface for Siconos
Feature sets:	F-3.000 to F-3.003
Depencies:	Kernel
Sources directory name	Front-End

Python Interface

Python is an interpreted, interactive, object-oriented programming language. In python, Siconos platform is used as a library. When loaded, almost all Siconos/Kernel functions are available. This provides a direct and interactive way for computation with Siconos, without any re-compilation of  input-file.
A complete example using python interface is available in Examples/Mechanics/BouncingBall directory, and launched by typing " pySiconos BouncingBall.py ".
To find more on Python, see http://www.python.org/.

C++ - Python wrapper choice

To produce the interface, Siconos/Kernel function and class has to be embedded in Python. There mainly exists two free tools to wrap C++ code with python :
Swig and Boost.

• Swig  (http://www.swig.org/):

  SWIG is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. SWIG is
  used with different types of languages including common scripting languages such as Perl, Python, Tcl/Tk and Ruby.

  The main task to connect C++ with Python using SWIG is to write an interface file. It references the header files that must be wrap and some
  types declarations for the data structures that cannot be directly and automatically wrapped.

  SWIG is really easy to use, but does not support every features of advanced C++, especially: 

  • friend functions
  • overloaded operators with the same number of parameters and close types (int / double, etc.).

• Boost (http://www.boost.org/):

  Boost is a complete framework for C++ which provides advanced features and completes the Standard Template Library. Its Python wrapper
  is only one functionality among many others.

For the development of the Kernel-Python interface,  SWIG  has been chosen because of its easiest use. Moreover, using Boost just for wrapping
C++ with Python does not seem to be an appropriate solution.

Kernel wrapping

Connecting the Kernel with Python was pretty fast.  The only encountered problem was with down-casting operations. The Kernel have STL
containers of pointers.
For example, a NSDS stores the dynamical systems, but does not know their specific types. So it is impossible to access the type of dynamical
system after a down-casting operation (static_cast and dynamic_cast in C++). This operation is not allowed by Python. To solve this problem,
a cast method  has been written in each class which is not a base class. This method wraps the C++ operator of dynamic casting and returns
a pointer on the class.

The connection of STL containers is not fully automatic. A Python type has to be defined for each data type stored in such a container.
This type definition must be placed in the interface file. For example, to be able to use a container of pointers on Dynamical systems, 
the following command has to be added in the Swig interface file:

%include "std_vector.i";
namespace std {
 %template(dsVector) vector<DynamicalSystem*>;
}

How to add new functions or classes in Python interface?

The "wrapping" file is FrontEnd/python/pySiconos.i .
To have access to functions or classes of Siconos/Kernel,  the corresponding header files should be added in this pySiconos.i  file. 

Miscellaneous

In Swig last version (1.3.23, 1.3.24), a bug makes the compilation of the interface failed. This is a simple syntax error and we wrote a bash
script to correct this. This bug should be fixed soon in Swig distributions.

     

Scilab Interface

What is Scilab ?

Scilab is a scientific software package for numerical computations providing a powerful open computing environment for engineering and scientific applications. Developed since 1990 by researchers from INRIA and ENPC, it is now maintained and developed by Scilab Consortium since its creation in May 2003.

To find more on Scilab, see www.scilab.org

The interface

The directory Front-End/scilab/ contains a prototype of siconos interfaced with scilab. It allows a 'high-level' interaction with the siconos platformwith around 20 scilab functions. It allows flat acces without having deep siconos tree acces like proposed with python interface.

This interface consists in two main files :

• siconos.cpp : a C++ module with global objects (Model and Simulation) and "C" functions which uses it.
• siconos.sci : interface "C" functions of siconos.cpp in scilab function. It uses the simplest mechanism : scilab link and scilab call.

Scilab functions implemented are :

• sicLink() // Load siconos platform
• sicLoadModel(ModelXml) // Load a Xml model
• sicTimeGetH()
• sicTimeGetK()
• sicTimeGetN()
• sicInitSimulation()
• sicSTNextStep()
• sicSTComputeFreeState()
• sicSTformalisePb()
• sicSTcomputePb()
• sicSTupdateState()
• sicModelgetQ(index)

Example of use

Using the README in Front-End/scilab, you can use this interface to simulate the example BouncingBall. Normally, you will see during the simulation the ball animation; and after the simulation the plot of y(t).

Matlab Interface

TBD