/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file fragmentation.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/** \page fragmentation Fragmentation
 *
 * Fragmentation contains all routines that are required to split a given
 * molecular system into fragments. This is part of the so-called BOSSANOVA
 * (Bond Order diSSection in an ANOVA-like fashion) approach to get linear
 * scaling complexity for ab-initio quantum chemistry methods. This method is
 * explained in the doctoral thesis of Frederik Heber.
 *
 * \secton fragmentation-fragmentation Fragmenting molecules
 *
 * Everything starts in the Action FragmentationFragmentationAction. We require
 * a list of selected atoms. These are browsed and we note down all the associated
 * molecules (fragmentation is molecule-based). Subsequently, we make sure that
 * the bond degree has correct bond degress with respect to the selected set.
 * Then, Fragmentation is created for each molecule in the list.
 * The class Fragmentation contains with Fragmentation::FragmentMolecule()
 * the main routine that dissect a given molecule
 * Afterwards, all KeySet's are obtained as a Graph from the Fragmentation 
 * instance and combined into a single graph.
 * Via a depth first search analysis cycles are detected and added as
 * cycle fragments to this sets of KeySet.
 * Finally, all fragments are placed in the FragmentationResultContainer.
 *
 * If desired, \b inter-fragments, that fragments are combined if they are only
 * a certain distance apart from another and their summed fragmentation orders
 * do not exceed the specified value. This is required for local correlation 
 * calculation. Otherwise correlation is only calculated (if supported by the 
 * solver) within covalently connected fragments, i.e. we do not get any van
 * der Waals interactions.
 *
 * These fragments may be exported to file if output file types \sa fileformats
 * are given. There, the current FormatParserParameters are used. If none are
 * given, fragments remain in the FragmentationResultContainer.
 *
 * \secton fragmentation-automation Calculating fragments
 *
 * If then FragmentationFragmentationAutomationAction is used, these are converted
 * into MPQCJobs (and VMGJobs) that are passed on via a network connection to a
 * JobMarket's server as a FragmentJob. 
 * Any idling connected clients will then process each one of the jobs until the 
 * whole bundle is completed. The Action checks on the current tatus of the jobs 
 * and requests any finished jobs (FragmentResult).
 * After all jobs' results have been received, they are stored in 
 * FragmentationShortRangeResults and FragmentationLongrangeResults.
 * FragmentationAnalyseFragmentResultsAction will process both these results and
 * sum up the approximate energy and forces (where these are set as the atoms'
 * forces for the current time step).
 * 
 * Alternatively to automation, where everything is done inside MoleCuilder, one
 * may also use the exported files to calculate an approximation. To this end,
 * the energies and forces are put together via \b joiner to approximation
 * to the total energy and forces of the whole molecular system. Later,
 * \b analyzer additionally gives data on how good this approximation has
 * worked out in plotable format.
 *
 *
 * \date 2014-03-10
 *
 */