Changeset a295d1 for src/Actions/Action.hpp

Timestamp:

Apr 8, 2010, 2:28:21 PM (15 years ago)

Author:

Tillmann Crueger <crueger@…>

Branches:

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

Children:

8a34392, fdd840

Parents:

2efa90

Message:

More documentation for Action class added

File:

• src/Actions/Action.hpp (modified) (2 diffs)

src/Actions/Action.hpp

@@ -181 +181 @@
  * removeLastAction() method. If the construction of the sequence is done, you can use the
  * callAll() method. Each action called this way will register itself with the History to allow
- * seperate undo of all actions in the sequence.
+ * separate undo of all actions in the sequence.
  *
  * <H4> Building larger Actions from simple ones </H4>
@@ -200 +200 @@
  *        might brake important assumptions for the undo/redo mechanism
  * </ul>
+ *
+ * <H3> Special kinds of Actions </H3>
+ *
+ * To make the usage of Actions more versatile there are two special kinds of actions defined,
+ * that contain special mechanisms. These are defined inside the class Process, for actions that
+ * take some time and indicate their own progress, and in the class Calculations for actions that
+ * have a retrievable result.
+ *
+ * <H4> Processes </H4>
+ *
+ * Processes are Actions that might take some time and therefore contain special mechanisms
+ * to indicate their progress to the user. If you want to implement a process you can follow the
+ * guidelines for implementing actions. In addition to the normal Action constructor parameters,
+ * you also need to define the number of steps the process takes to finish (use 0 if that number is
+ * not known upon construction). At the beginning of your process you then simply call start() to
+ * indicate that the process is taking up its work. You might also want to set the number of steps it
+ * needs to finish, if it has changed since the last invocation/construction. You can use the
+ * setMaxSteps() method for this. Then after each finished step of calulation simply call step(),
+ * to let the indicators know that it should update itself. If the number of steps is not known
+ * at the time of calculation, you should make sure the maxSteps field is set to 0, either through
+ * the constructor or by using setMaxSteps(0). Indicators are required to handle both processes that
+ * know the number of steps needed as well as processes that cannot predict when they will be finished.
+ * Once your calculation is done call stop() to let every indicator know that the process is done with
+ * the work and to let the user know.
+ *
+ * Indicators that want to know about processes need to implement the Observer class with all the
+ * methods defined there. They can then globally sign on to all processes using the static
+ * Process::AddObserver() method and remove themselves using the Process::RemoveObserver()
+ * methods. When a process starts it will take care that the notification for this process
+ * is invoked at the right time. Indicators should not try to observe a single process, but rather
+ * be ready to observe the status of any kind of process using the methods described here.
+ *
+ * <H4> Calculations </H4>
+ *
+ * Calculations are special Actions that also return a result when called. Calculations are
+ * always derived from Process, so that the progress of a calculation can be shown. Also
+ * Calculations should not contain side-effects and not consider the undo mechanism.
+ * When a Calculation is called using the Action mechanism this will cause it to calculate
+ * the result and make it available using the getResult() method. Another way to have a Calculation
+ * produce a result is by using the function-call operator. When this operator is used, the Calculation
+ * will try to return a previously calculated and cached result and only do any actuall calculations
+ * when no such result is available. You can delete the cached result using the reset() method.
  */