| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2013 Frederik Heber. 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/Python/PythonScripting.cpp.
|
|---|
| 23 | *
|
|---|
| 24 | * There again some preprocessor magic is happening, very similar to constructs
|
|---|
| 25 | * we used for the Action's. One the one hand we need GlobalListOfActions.hpp to
|
|---|
| 26 | * have a list of all actions available. Second, in AllActionPython.hpp we define
|
|---|
| 27 | * export functions for every Action (in essence we use the COMMAND function, see
|
|---|
| 28 | * Action_impl_pre.hpp, which makes an Action usable internally as a normal
|
|---|
| 29 | * function).
|
|---|
| 30 | *
|
|---|
| 31 | * Then, at the beginning of the BOOST_PYTHON_MODULE declaration we initialize
|
|---|
| 32 | * the ActionHistory (same as in main() in builder.cpp), and on exit we
|
|---|
| 33 | * perform cleanUp() via the atexit() hook to make sure that everything
|
|---|
| 34 | * is not only removed but more importantly in the correct orders. This is
|
|---|
| 35 | * required because we use many static elements which have to be deinitialized
|
|---|
| 36 | * in the correct sequence as they depend on one another.
|
|---|
| 37 | *
|
|---|
| 38 | * \section userinterfaces-python-first-test A first test script
|
|---|
| 39 | *
|
|---|
| 40 | * A small python test script would then look like this:
|
|---|
| 41 | * \code
|
|---|
| 42 | * import pyMoleCuilder as mol
|
|---|
| 43 | * mol.WorldInput("test.xyz")
|
|---|
| 44 | * mol.SelectAtomById("0")
|
|---|
| 45 | * mol.AtomRemove()
|
|---|
| 46 | * mol.wait()
|
|---|
| 47 | * mol.getSelectedMolarMass()
|
|---|
| 48 | * mol.wait()
|
|---|
| 49 | * \endcode
|
|---|
| 50 | * which loads a file \b test.xyz into the (internal) World, selects the first
|
|---|
| 51 | * atom and removes it.
|
|---|
| 52 | *
|
|---|
| 53 | * \subsection userinterfaces-python-first-test-wait Wait may be important ...
|
|---|
| 54 | *
|
|---|
| 55 | * \note Notice \b mol.wait() at the end. This might be necessary as actions are
|
|---|
| 56 | * executed in a different thread than the python script itself. This is only
|
|---|
| 57 | * enabled when configure is called with \b enable-action-thread.
|
|---|
| 58 | *
|
|---|
| 59 | * Hence, if you require values from molecuilder you have to make sure that
|
|---|
| 60 | * all your actions have been processed by this second thread. That's what
|
|---|
| 61 | * wait() is good for. It waits until action queue thread is idle. Then you
|
|---|
| 62 | * can be sure that molecuilder has removed all atoms, performed all selections
|
|---|
| 63 | * and any value you retrieve is up-to-date.
|
|---|
| 64 | *
|
|---|
| 65 | * Note that there are two \b wait()s present in the example. As the Actions
|
|---|
| 66 | * are executed in another thread and the above commands just tell the MoleCuilder
|
|---|
| 67 | * library (the ActionQueue to be precise) to enqueue the requested action,
|
|---|
| 68 | * we have to wait (in the main thread) until the actions actually have been
|
|---|
| 69 | * executed before we continue (i.e. when we need the new state where the
|
|---|
| 70 | * atoms have been removed) and before we \b terminate!
|
|---|
| 71 | *
|
|---|
| 72 | * \section userinterfaces-python-running Running a test script
|
|---|
| 73 | *
|
|---|
| 74 | * In most cases however, python cannot find the library (except molecuilder
|
|---|
| 75 | * has been installed in some system-default folder). In this case you should
|
|---|
| 76 | * prefix your call to the python interpreter with:
|
|---|
| 77 | * \code
|
|---|
| 78 | * PYTHONPATH="<buildpath>/src/.libs" python
|
|---|
| 79 | * \endcode
|
|---|
| 80 | * where \a <buildpath> is the top build directory of molecuilder. If you have
|
|---|
| 81 | * installed molecuilder (\code make install \endcode), but the
|
|---|
| 82 | * \a <installpath> (i.e. the \a prefix given at to the configure call) is non-
|
|---|
| 83 | * standard, then prepend this
|
|---|
| 84 | * \code
|
|---|
| 85 | * PYTHONPATH="<installpath>/share/site-packages" python
|
|---|
| 86 | * \endcode
|
|---|
| 87 | *
|
|---|
| 88 | * \section userinterfaces-python-autostart Using python script as autostart file
|
|---|
| 89 | *
|
|---|
| 90 | * If in the current directory a file \b molecuilder.py is found, the contents
|
|---|
| 91 | * is executed as a regular python script prior to any other Action's.
|
|---|
| 92 | *
|
|---|
| 93 | * \note Each commands needs to be taken from a molecule called \a pyMoleCuilder.
|
|---|
| 94 | * Hence, use
|
|---|
| 95 | * \code
|
|---|
| 96 | * pyMoleCuilder.WorldInput("test.xyz")
|
|---|
| 97 | * pyMoleCuilder.wait()
|
|---|
| 98 | * \endcode
|
|---|
| 99 | *
|
|---|
| 100 | * \note Each command needs to be followed by brackets regardless of any present
|
|---|
| 101 | * arguments.
|
|---|
| 102 | * \code
|
|---|
| 103 | * pyMoleCuilder.SelectionAllMolecules()
|
|---|
| 104 | * pyMoleCuilder.wait()
|
|---|
| 105 | * \endcode
|
|---|
| 106 | *
|
|---|
| 107 | * \note Each argument must be given as a string as it is basically as if the
|
|---|
| 108 | * commands were given on the command line, \sa userinterfaces-commandline
|
|---|
| 109 | * \code
|
|---|
| 110 | * pyMoleCuilder.SelectAtomById("0")
|
|---|
| 111 | * pyMoleCuilder.wait()
|
|---|
| 112 | * \endcode
|
|---|
| 113 | *
|
|---|
| 114 | * \warning Again, take note of the added wait()s that ensure the all enqueued
|
|---|
| 115 | * actions also have been executed. This is especially important in scripts as
|
|---|
| 116 | * otherwise your script may deadlock. That's because ActionQueue's destructor
|
|---|
| 117 | * waits for the thread that executes the actions to end, and in another thread
|
|---|
| 118 | * we still want to access to ActionQueue whose instance is however locked as
|
|---|
| 119 | * it is about the get destroyed.
|
|---|
| 120 | *
|
|---|
| 121 | * \subsection userinterfaces-python-notes-cleanup Cleaning up or reset state ...
|
|---|
| 122 | *
|
|---|
| 123 | * Whenever you need to reset the internal state of the molecuilder, i.e.
|
|---|
| 124 | * you want to save the current file and work on something new, use
|
|---|
| 125 | * \code
|
|---|
| 126 | * mol.cleanUp()
|
|---|
| 127 | * \endcode
|
|---|
| 128 | * This frees all memory, removes all static instances on the heap, and saves
|
|---|
| 129 | * your input file (\sa WorldInputAction).
|
|---|
| 130 | *
|
|---|
| 131 | * \subsection userinterfaces-python-help Help inside the interpreter
|
|---|
| 132 | *
|
|---|
| 133 | * Note that the pyMoleCuilder module is fully documented. I.e.
|
|---|
| 134 | * \code
|
|---|
| 135 | * import pyMoleCuilder as mol
|
|---|
| 136 | * help(mol)
|
|---|
| 137 | * \endcode
|
|---|
| 138 | * gives you a complete list of present functions/Actions in the module
|
|---|
| 139 | * including their signature and a brief description (this is all
|
|---|
| 140 | * automatically generated via the proprocessor magic from the Action's
|
|---|
| 141 | * \b .def files).
|
|---|
| 142 | *
|
|---|
| 143 | * Likewise you may obtain help on each single function, e.g.
|
|---|
| 144 | * \code
|
|---|
| 145 | * import pyMoleCuilder as mol
|
|---|
| 146 | * help(mol.WorldInput)
|
|---|
| 147 | * \endcode
|
|---|
| 148 | * gives you the docu string on WorldInputAction.
|
|---|
| 149 | *
|
|---|
| 150 | *
|
|---|
| 151 | *
|
|---|
| 152 | * \date 2014-03-10
|
|---|
| 153 | *
|
|---|
| 154 | */
|
|---|
