1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
\section{Overview}
\Index{Python} is an object-oriented scripting language~\cite{Python} that is
well-suited both as a language for embedding scripts into BALL applications and
as a rapid prototyping language using the underlying BALL objects.
BALL provides Python bindings for most of its classes in order to allow
\Index{Rapid Methodology Development} (RMD). Some of the functionality BALL
provides (\eg template classes, iterators) is unavailable due to the
fundamental differences between the two languages. However, the majority of
the classes is available and workarounds exist for some of the template- and
iterator-related problems.
Since release 1.2 of BALL, the Python support is enabled by default. The
remainder of this section assumes that you are somewhat familiar with the most
important language concepts of Python.
BALL relies on SIP~\cite{SIP} \index{SIP} to translate its class
headers semi-automatically into Python wrapper classes. For each \CPP class
SIP creates a subclass defining the Python interface and a Python class
using that \CPP interface class. The Python class has the same name as the
\CPP class, so porting code from \CPP to Python (and vice versa) gets trivial.
The \CPP code
\begin{lstlisting}{}
System S;
HINFile f("test.hin");
f >> S;
\end{lstlisting}
\noindent
translates to the Python code
\begin{lstlisting}{}
S = System()
f = HINFile("test.hin")
f >> S;
\end{lstlisting}
\noindent
In this example, the main difference is how \CPP and Python handle
constructors. Another important difference concerns iterators. The STL-like
kernel iterators of BALL map to a set of functions (called extractors). An
extractor traverses the whole container and creates a Python sequence object
from it. Instead of having an \class{AtomIterator} iterating over all atoms of
a residue
\begin{lstlisting}{}
AtomIterator ai = residue.beginAtom();
for (; +ai; ++ai)
{
std::cout << ai->getName() << std::endl;
}
\end{lstlisting}
\noindent
an \function{atoms} extractor is used to create a sequence object containing
all objects of the residue in Python:
\begin{lstlisting}{}
for atom in atoms(residue):
print atom.getName()
\end{lstlisting}
For the template problem, we pre-instantiated some of the
commonly used instances, \eg \class{Unary\-Processor\-<Atom>} maps to the
\class{AtomProcessor} class and classes derived from it in Python.
Any VIEW application (e.g., BALLView) can be extended by an interactive Python
interpreter through the Jupyter plugin. Using the PyBALL kernel for Jupyter,
you can even access the data structures of the viewer from there. Assuming that
you are currently displaying a structure in the viewer, you can retrieve a
reference to the first system displayed through the somewhat lengthy command
\begin{lstlisting}{}
system = MainControl::getInstance(0)\
.getCompositeManager().getComposites()[0]
\end{lstlisting}
\noindent
Since this is not very convenient, we added a Python module named \texttt{view\_utils}
providing aliases for many functions. The module can be found in the \texttt{data/python/}
directory. By using one of the functions defined in this file, it is possible to obtain
the first \class{System} by simply calling
\begin{lstlisting}{}
from view_utils import *
system = getSystems()[0].
\end{lstlisting}
\noindent
This is very useful for extracting properties of loaded molecules and other
datasets you are currently displaying, but not recommended if you start
modifying internals of the viewer. You should also not try to destroy those
objects in the viewer, or you will be rewarded with a core dump. Currently
there is no further documentation of the Python support available.
\section{Installation}
The \texttt{BALLCore} and \texttt{VIEW} Python modules are already included
in all source and binary distributions and installed automatically.
Alternatively, the modules can also be built manually using the
\texttt{BALLCoremodule} and \texttt{VIEWmodule} targets:
\begin{lstlisting}{language=sh}
make BALLCoremodule VIEWmodule
\end{lstlisting}
On Windows, the modules can be built using the \texttt{BALLPython.sln}
solution file.
Before the modules can finally be used, two environment variables need to be set:
\begin{lstlisting}{language=sh}
# Linux/Mac
export PYTHONPATH=<PATH to BALL libs>:<PATH to sip libs>:${PYTHONPATH}
export LD_LIBRARY_PATH=<PATH to BALL libs>:<PATH to QT libs>:\
<PATH to sip libs>:${LD_LIBRARY_PATH}
# Windows
set PYTHONPATH=<PATH to BALL libs>;<PATH to sip libs>;%PYTHONPATH%
set PATH=<PATH to BALL libs>;<PATH to QT libs>;<PATH to sip libs>;%PATH%
\end{lstlisting}
|
