Changeset 750cff for src/documentation/constructs/serialization.dox

Timestamp:

Oct 31, 2011, 5:13:52 PM (14 years ago)

Author:

Frederik Heber <heber@…>

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, Candidate_v1.7.0, 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:

5982c5

Parents:

19bc74

Message:

HUGE: Update on documenation.

• a general skeleton of the documentation is now in place with all the major components of MoleCuilder explained to some extent.
• some information has been transfered from TRAC (e.g. install procecure) into this doxygen documentation where it is general and not specific to the situation at our institute.

File:

• src/documentation/constructs/serialization.dox (modified) (1 diff)

src/documentation/constructs/serialization.dox

@@ -14 +14 @@
  *    Author: heber
  */
+
+/** \page serialization Serialization
+ *
+ *  Serialization is a mighty concept. The is only possible within an object-
+ *  oriented framework. The member variables of a class make up its internal
+ *  state. By storing this state, creating another instance and restoring
+ *  the variables to this state, we may in essence clone the instance. However,
+ *  we obtain additional control as to the moment of restoration because the
+ *  internal state is stored temporarily. To allow for this storage all of
+ *  these variables have to be \e serialized.
+ *
+ *  Serialization refers to putting one after another into a writable form
+ *  (e.g. convert to string and write into a stringstream) and eventually
+ *  in reverse order to read them one by one from this writable form and
+ *  cast them back into their original type.
+ *
+ *  Here, this is done via boost::serialization.
+ *
+ *  \attention The serialization headers do not mingle well with \b MemDebug.hpp.
+ *  Hence, place them before MemDebug.hpp as they do funny stuff with the
+ *  new() operator.
+ *
+ *  Serialization is so powerful because the stored state can be stored to
+ *  disk, transfered to another thread or even to another computer. If received
+ *  by a compatible code, the instance is recreated and computation can be
+ *  continued elsewhere.
+ *
+ *  For the moment we use it for creating an undo state within the Action's.
+ *  I.e. we store the state of all instances that are modified by an Action's
+ *  doings and may in Action::performUndo() just re-create the unmodified
+ *  instance by loading them from the serializing archive.
+ *
+ *  \section serialization-add How to make your class serializable.
+ *
+ *  \subsection serialization-add-simple The simple case
+ *
+ *  All you need to do with your newly created class foo is this:
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    template<class Archive>
+ *    void serialize(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    ...
+ *    double content;
+ *  };
+ *  \endcode
+ *  This will implement a serialization function for both directions for the
+ *  member variable content. I.e. we may now store a class instance as this:
+ *  \code
+ *  #include <boost/archive/text_oarchive.hpp>
+ *  std::stringstream stream;
+ *  boost::archive::text_oarchive oa(stream);
+ *  oa << diagonal;
+ *  \endcode
+ *  This will store the state of the class in the stringstream \a stream.
+ *  Getting the instance back is then as easy as
+ *  \code
+ *  #include <boost/archive/text_iarchive.hpp>
+ *  boost::archive::text_iarchive ia(stream);
+ *  RealSpaceMatrix *newm;
+ *  ia >> newm;
+ *  \endcode
+ *
+ *  \subsection serialization-add-complicated The more complicated case
+ *
+ *  It gets trickier when load and store need to be done differently, e.h.
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    // serialization
+ *    template<class Archive>
+ *    void save(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    template<class Archive>
+ *    void load(Archive & ar, const unsigned int version)
+ *    {
+ *      ar & content;
+ *      createViews();
+ *    }
+ *    BOOST_SERIALIZATION_SPLIT_MEMBER()
+ *    ...
+ *  }
+ *  \endcode
+ *  Here, we split serialize() function into distinct load() and save() because
+ *  we have to call an additional function to fully re-store the instance, i.e.
+ *  it creates some internal reference arrays (Views) in a specific manner.
+ *
+ *  The serialize functions can also be added externally, i.e. outside of the
+ *  scope of the class, but can then access only public members (except we
+ *  again make it a friend).
+ *
+ *
+ * \date 2011-10-31
+ */