Changeset caece4 for src/documentation/constructs/serialization.dox

Timestamp:

May 20, 2014, 9:14:56 AM (11 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, 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:

6029a6

Parents:

74459a

git-author:

Frederik Heber <heber@…> (03/20/14 17:23:35)

git-committer:

Frederik Heber <heber@…> (05/20/14 09:14:56)

Message:

Enhanced documentation significantly.

• went through all of the constructs and updated each.
• enhanced documentation ofr Fragmentation::FragmentMolecule().

File:

• src/documentation/constructs/serialization.dox (modified) (5 diffs)

src/documentation/constructs/serialization.dox

@@ -17 +17 @@
 /** \page serialization Serialization
  *
- *  Serialization is a mighty concept. The is only possible within an object-
+ *  Serialization is a mighty concept. This 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
@@ -23 +23 @@
  *  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.
+ *  these variables have to be \e serializable.
  *
  *  Serialization refers to putting one after another into a writable form
@@ -114 +114 @@
  *  again make it a friend).
  *
+ *  \subsection serialization-add-complicated The more complicated case
+ *
+ *  Noted the additional \a version parameter up there in the serialize functions'
+ *  signature? When classes change, we might still want to be able to parse in
+ *  older states. As as state is always written to a default constructed object.
+ *  this is possible. You can check the version variable like this to make your
+ *  function compatible with older functions.
+ *
+ *  \code
+ *    void serialize(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *      if (version > 0)
+ *        are & newcontent;
+ *    }
+ *    ...
+ *    double newcontent;
+ *  };
+ *  \endcode
+ *
+ *  The version itself is set as follows,
+ *  \code
+ *    BOOST_CLASS_VERSION(foo, 1)
+ *  \endcode
+ *  where you give the name of your class and the version.
+ *
  *  \subsection serialization-important notes Some important notes
  *
@@ -119 +145 @@
  *  a stupid mistake is introduced that is trivial once understand but hard
  *  to find otherwise. This is especially so because compiler errors with
- *  respect to the serialization part are always length (whole page) and
+ *  respect to the serialization part are always lengthy (whole page) and
  *  very hard to read:
  *  \li Always obtain the same type from an archive that you put into it!
@@ -151 +177 @@
  *    boost::serialization::base_object<base type>(*this);
  *    \endcode
+ *  \li When you have code in header and implementation module, boost might get
+      confused, use \code BOOST_CLASS_EXPORT_KEY(foo) \endcode and
+          \code BOOST_CLASS_EXPORT_IMPLEMENT(foo) \encode for this.
+ *  \li The only other issues encountered so far is that a class needs to get
+ *    instantiated. Otherwise its (templated) serialization code is not present.
+ *    There are ..._EXPORT keywords in boost::serialization for this. Similarly
+ *    required when just the base class is created/instantiated but you also need
+ *    derived classes.
+ *  \li The boost::serialization documentation is in general quite helpful. Use
+ *    above mentioned keywords to look for more information.
  *
  * 
- * \date 2011-11-01
+ * \date 2014-03-10
  */