| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 6 | */
|
|---|
| 7 |
|
|---|
| 8 | /**
|
|---|
| 9 | * \file python.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Nov 01, 2011
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /**
|
|---|
| 16 | * \page userinterfaces-python Python module
|
|---|
| 17 | *
|
|---|
| 18 | * Via boost::python all of Molecuilder Action's are exported into a python
|
|---|
| 19 | * module such that all functionality can also be directly used in a python
|
|---|
| 20 | * script.
|
|---|
| 21 | *
|
|---|
| 22 | * This is done in \b src/Actions/pyMoleCuilder.cpp.
|
|---|
| 23 | *
|
|---|
| 24 | * There again some preprocessor magic is happening. One the one hand we
|
|---|
| 25 | * need GlobalListOfActions.hpp to have a list of all actions available.
|
|---|
| 26 | * Second, in AllActionPython.hpp we define export functions for every
|
|---|
| 27 | * Action (in essence we use the COMMAND function, see Action_impl_pre.hpp,
|
|---|
| 28 | * which makes an Action usable internally as a normal function).
|
|---|
| 29 | *
|
|---|
| 30 | * Then, at the beginning of the BOOST_PYTHON_MODULE declaration we initialize
|
|---|
| 31 | * the ActionHistory (same as in main() in builder.cpp), and on exit we
|
|---|
| 32 | * perform cleanUp() via the atexit() hook to make sure that everything
|
|---|
| 33 | * is not only removed but more importantly in the correct orders. This is
|
|---|
| 34 | * required because we use many static elements which have to be deinitialized
|
|---|
| 35 | * in the correct sequence as they depend on one another.
|
|---|
| 36 | *
|
|---|
| 37 | * \section userinterfaces-python-first-test A first test script
|
|---|
| 38 | *
|
|---|
| 39 | * A small python test script would then look like this:
|
|---|
| 40 | * \code
|
|---|
| 41 | * import pyMoleCuilder as mol
|
|---|
| 42 | * mol.WorldInput("test.xyz")
|
|---|
| 43 | * mol.SelectAtomById("0")
|
|---|
| 44 | * mol.AtomRemove()
|
|---|
| 45 | * \endcode
|
|---|
| 46 | * which loads a file \b test.xyz into the (internal) World, selects the first
|
|---|
| 47 | * atom and removes it.
|
|---|
| 48 | *
|
|---|
| 49 | * \section userinterfaces-python-running Running a test script
|
|---|
| 50 | *
|
|---|
| 51 | * In most cases however, python cannot find the library (except molecuilder
|
|---|
| 52 | * has been installed in some system-default folder). In this case you should
|
|---|
| 53 | * prefix your call to the python interpreter with:
|
|---|
| 54 | * \code
|
|---|
| 55 | * PYTHONPATH="<buildpath>/src/.libs" python
|
|---|
| 56 | * \endcode
|
|---|
| 57 | * where \a <buildpath> is the top build directory of molecuilder. If you have
|
|---|
| 58 | * installed molecuilder (\code make install \endcode), but the
|
|---|
| 59 | * \a <installpath> (i.e. the \a prefix given at to the configure call) is non-
|
|---|
| 60 | * standard, then prepend this
|
|---|
| 61 | * \code
|
|---|
| 62 | * PYTHONPATH="<installpath>/share/site-packages" python
|
|---|
| 63 | * \endcode
|
|---|
| 64 | *
|
|---|
| 65 | * \section userinterfaces-python-autostart Using python script as autostart file
|
|---|
| 66 | *
|
|---|
| 67 | * If in the current directory a file \b molecuilder.py is found, the contents
|
|---|
| 68 | * is executed as a regular python script.
|
|---|
| 69 | *
|
|---|
| 70 | * \note Each commands needs to be taken from a molecule called \a pyMoleCuilder.
|
|---|
| 71 | * Hence, use
|
|---|
| 72 | * \code
|
|---|
| 73 | * pyMoleCuilder.WorldInput("test.xyz")
|
|---|
| 74 | * \endcode
|
|---|
| 75 | *
|
|---|
| 76 | * \note Each command needs to be followed by brackets regardless of any present
|
|---|
| 77 | * arguments.
|
|---|
| 78 | * \code
|
|---|
| 79 | * pyMoleCuilder.SelectionAllMolecules()
|
|---|
| 80 | * \endcode
|
|---|
| 81 | *
|
|---|
| 82 | * \note Each argument must be given as a string as it is basically as if the
|
|---|
| 83 | * commands were given on the command line, \sa userinterfaces-commandline
|
|---|
| 84 | * \code
|
|---|
| 85 | * pyMoleCuilder.SelectAtomById("0")
|
|---|
| 86 | * \endcode
|
|---|
| 87 | *
|
|---|
| 88 | * \subsection userinterfaces-python-notes-cleanup Cleaning up or reset state ...
|
|---|
| 89 | *
|
|---|
| 90 | * Whenever you need to reset the internal state of the molecuilder, i.e.
|
|---|
| 91 | * you want to save the current file and work on something new, use
|
|---|
| 92 | * \code
|
|---|
| 93 | * mol.cleanUp()
|
|---|
| 94 | * \endcode
|
|---|
| 95 | * This frees all memory, removes all static instances on the heap, and saves
|
|---|
| 96 | * your input file (\sa WorldInputAction).
|
|---|
| 97 | *
|
|---|
| 98 | * \subsection userinterfaces-python-help Help inside the interpreter
|
|---|
| 99 | *
|
|---|
| 100 | * Note that the pyMoleCuilder module is fully documented. I.e.
|
|---|
| 101 | * \code
|
|---|
| 102 | * import pyMoleCuilder as mol
|
|---|
| 103 | * help(mol)
|
|---|
| 104 | * \endcode
|
|---|
| 105 | * gives you a complete list of present functions/Actions in the module
|
|---|
| 106 | * including their signature and a brief description (this is all
|
|---|
| 107 | * automatically generated via the proprocessor magic from the Action's
|
|---|
| 108 | * \b .def files).
|
|---|
| 109 | *
|
|---|
| 110 | * Likewise you may obtain help on each single function, e.g.
|
|---|
| 111 | * \code
|
|---|
| 112 | * import pyMoleCuilder as mol
|
|---|
| 113 | * help(mol.WorldInput)
|
|---|
| 114 | * \endcode
|
|---|
| 115 | * gives you the docu string on WorldInputAction.
|
|---|
| 116 | *
|
|---|
| 117 | *
|
|---|
| 118 | * \date 2013-03-18
|
|---|
| 119 | *
|
|---|
| 120 | */
|
|---|
