source: src/documentation/userinterfaces/python.dox@ 74459a

Action_Thermostats Add_AtomRandomPerturbation Add_FitFragmentPartialChargesAction Add_RotateAroundBondAction Add_SelectAtomByNameAction Added_ParseSaveFragmentResults AddingActions_SaveParseParticleParameters Adding_Graph_to_ChangeBondActions Adding_MD_integration_tests Adding_ParticleName_to_Atom Adding_StructOpt_integration_tests AtomFragments Automaking_mpqc_open AutomationFragmentation_failures Candidate_v1.5.4 Candidate_v1.6.0 Candidate_v1.6.1 ChangeBugEmailaddress ChangingTestPorts ChemicalSpaceEvaluator CombiningParticlePotentialParsing Combining_Subpackages Debian_Package_split Debian_package_split_molecuildergui_only Disabling_MemDebug Docu_Python_wait EmpiricalPotential_contain_HomologyGraph EmpiricalPotential_contain_HomologyGraph_documentation Enable_parallel_make_install Enhance_userguide Enhanced_StructuralOptimization Enhanced_StructuralOptimization_continued Example_ManyWaysToTranslateAtom Exclude_Hydrogens_annealWithBondGraph FitPartialCharges_GlobalError Fix_BoundInBox_CenterInBox_MoleculeActions Fix_ChargeSampling_PBC Fix_ChronosMutex Fix_FitPartialCharges Fix_FitPotential_needs_atomicnumbers Fix_ForceAnnealing Fix_IndependentFragmentGrids Fix_ParseParticles Fix_ParseParticles_split_forward_backward_Actions Fix_PopActions Fix_QtFragmentList_sorted_selection Fix_Restrictedkeyset_FragmentMolecule Fix_StatusMsg Fix_StepWorldTime_single_argument Fix_Verbose_Codepatterns Fix_fitting_potentials Fixes ForceAnnealing_goodresults ForceAnnealing_oldresults ForceAnnealing_tocheck ForceAnnealing_with_BondGraph ForceAnnealing_with_BondGraph_continued ForceAnnealing_with_BondGraph_continued_betteresults ForceAnnealing_with_BondGraph_contraction-expansion FragmentAction_writes_AtomFragments FragmentMolecule_checks_bonddegrees GeometryObjects Gui_Fixes Gui_displays_atomic_force_velocity ImplicitCharges IndependentFragmentGrids IndependentFragmentGrids_IndividualZeroInstances IndependentFragmentGrids_IntegrationTest IndependentFragmentGrids_Sole_NN_Calculation JobMarket_RobustOnKillsSegFaults JobMarket_StableWorkerPool JobMarket_unresolvable_hostname_fix MoreRobust_FragmentAutomation ODR_violation_mpqc_open PartialCharges_OrthogonalSummation PdbParser_setsAtomName PythonUI_with_named_parameters QtGui_reactivate_TimeChanged_changes Recreated_GuiChecks Rewrite_FitPartialCharges RotateToPrincipalAxisSystem_UndoRedo SaturateAtoms_findBestMatching SaturateAtoms_singleDegree StoppableMakroAction Subpackage_CodePatterns Subpackage_JobMarket Subpackage_LinearAlgebra Subpackage_levmar Subpackage_mpqc_open Subpackage_vmg Switchable_LogView ThirdParty_MPQC_rebuilt_buildsystem TrajectoryDependenant_MaxOrder TremoloParser_IncreasedPrecision TremoloParser_MultipleTimesteps TremoloParser_setsAtomName Ubuntu_1604_changes stable
Last change on this file since 74459a was 415ddd, checked in by Frederik Heber <heber@…>, 11 years ago

ActionQueue now contains a run thread.

  • otherwise the progress bar of the QtMainWindow cannot be seen as waitForResults() takes up all of the executing thread.
  • added mutex for operations modifying the queue.
  • added ActionQueue::run() and ::stop(), used by friend stopQueue().
  • insertAction() now makes use of a tempqueue that is added to true queue during run() instead of calling the actions directly.
  • new stopQueue() in cleanUp.hpp is used by module_exit in pyMoleCuilder and in main() before saveAll().
  • cleanup: printTiming() requires now list of action tokens and added new stopAndPurgeQueue() to place waiting for Actions to end into extra function.
  • added ActionQueue::wait() which allows for synchronization in python scripts, is ignored in session python scripts. Otherwise we wait for ActionQueue's queue to empty during execution of load-session which hangs.
  • DOCU: added note to python documentation.
  • added waitQueue() also to purgeStaticInstances().
  • static UIFactory::isFactoryPresent() added that allows checking whether we have a UI or are executed within a python script (i.e. pyMoleCuilder).
  • DOCU: Extended docu on threads and who this affects python scripts.
  • TESTFIX: changed regression tests on storing python sessions.
  • Property mode set to 100644
File size: 6.4 KB
Line 
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/Python/PythonScripting.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 * mol.wait()
46 * mol.getSelectedMolarMass()
47 * mol.wait()
48 * \endcode
49 * which loads a file \b test.xyz into the (internal) World, selects the first
50 * atom and removes it. Notice \b mol.wait() at the end. This might be necessary
51 * as actions are executed in a different thread than the python script itself.
52 * Hence, if you require values from molecuilder you have to make sure that
53 * all your actions have been processed by this second thread. That's what
54 * wait() is good for. It waits until action queue thread is idle. Then you
55 * can be sure that molecuilder has removed all atoms, performed all selections
56 * and any value you retrieve is up-to-date.
57 *
58 * Note that there are two \b wait()s present in the example. As the Actions
59 * are executed in another thread and the above commands just tell the MoleCuilder
60 * library (the ActionQueue to be precise) to enqueue the requested action,
61 * we have to wait (in the main thread) until the actions actually have been
62 * executed before we continue (i.e. when we need the new state where the
63 * atoms have been removed) and before we \b terminate!
64 *
65 * \section userinterfaces-python-running Running a test script
66 *
67 * In most cases however, python cannot find the library (except molecuilder
68 * has been installed in some system-default folder). In this case you should
69 * prefix your call to the python interpreter with:
70 * \code
71 * PYTHONPATH="<buildpath>/src/.libs" python
72 * \endcode
73 * where \a <buildpath> is the top build directory of molecuilder. If you have
74 * installed molecuilder (\code make install \endcode), but the
75 * \a <installpath> (i.e. the \a prefix given at to the configure call) is non-
76 * standard, then prepend this
77 * \code
78 * PYTHONPATH="<installpath>/share/site-packages" python
79 * \endcode
80 *
81 * \section userinterfaces-python-autostart Using python script as autostart file
82 *
83 * If in the current directory a file \b molecuilder.py is found, the contents
84 * is executed as a regular python script.
85 *
86 * \note Each commands needs to be taken from a molecule called \a pyMoleCuilder.
87 * Hence, use
88 * \code
89 * pyMoleCuilder.WorldInput("test.xyz")
90 * pyMoleCuilder.wait()
91 * \endcode
92 *
93 * \note Each command needs to be followed by brackets regardless of any present
94 * arguments.
95 * \code
96 * pyMoleCuilder.SelectionAllMolecules()
97 * pyMoleCuilder.wait()
98 * \endcode
99 *
100 * \note Each argument must be given as a string as it is basically as if the
101 * commands were given on the command line, \sa userinterfaces-commandline
102 * \code
103 * pyMoleCuilder.SelectAtomById("0")
104 * pyMoleCuilder.wait()
105 * \endcode
106 *
107 * \warning Again, take note of the added wait()s that ensure the all enqueued
108 * actions also have been executed. This is especially important in scripts as
109 * otherwise your script may deadlock. That's because ActionQueue's destructor
110 * waits for the thread that executes the actions to end, and in another thread
111 * we still want to access to ActionQueue whose instance is however locked as
112 * it is about the get destroyed.
113 *
114 * \subsection userinterfaces-python-notes-cleanup Cleaning up or reset state ...
115 *
116 * Whenever you need to reset the internal state of the molecuilder, i.e.
117 * you want to save the current file and work on something new, use
118 * \code
119 * mol.cleanUp()
120 * \endcode
121 * This frees all memory, removes all static instances on the heap, and saves
122 * your input file (\sa WorldInputAction).
123 *
124 * \subsection userinterfaces-python-help Help inside the interpreter
125 *
126 * Note that the pyMoleCuilder module is fully documented. I.e.
127 * \code
128 * import pyMoleCuilder as mol
129 * help(mol)
130 * \endcode
131 * gives you a complete list of present functions/Actions in the module
132 * including their signature and a brief description (this is all
133 * automatically generated via the proprocessor magic from the Action's
134 * \b .def files).
135 *
136 * Likewise you may obtain help on each single function, e.g.
137 * \code
138 * import pyMoleCuilder as mol
139 * help(mol.WorldInput)
140 * \endcode
141 * gives you the docu string on WorldInputAction.
142 *
143 * \subsection userinterfaces-python-notes-wait Waiting for the action queue
144 *
145 * Note again that actions are executed in a different thread as the python
146 * script. Hence, we require synchronization at certain intervals where you
147 * require molecuilder to be up to speed. All commands you executed such
148 * as
149 * \code
150 * import pyMoleCuilder as mol
151 * mol.WorldInput("foo.xyz")
152 * mol.wait()
153 * \endcode
154 * just queue this specific input action but not execute it right away. That's
155 * left to the other thread. Hence, you need to wait() before:
156 * -# you access mol.get...() functions as these are not actions themselves.
157 * -# you need to have files written by molecuilder to be parsed in the python
158 * script.
159 *
160 *
161 * \date 2013-09-28
162 *
163 */
Note: See TracBrowser for help on using the repository browser.