/*
 * 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 filling.dox
 *
 * Created on: Jan 16, 2012
 *    Author: heber
 */

/** \page filling Filling a domain
 *
 * The idea behind filling a domain is to cluster it with a set of \b nodes,
 * i.e. a position in space in such a way that e.g. around a node is sufficient
 * space to fill in the desired molecule. The logic of generating the nodes
 * is responsible to create them in such a way as to allow for dense (or
 * whatever specific) filling is desired. However, we must not make it too
 * complicated. The generation logic for these nodes should concentrate on
 * filling the specific domain (sphere, ellipsoid, cuboid, pyramid, ...)
 * in the best possible way.
 * Whether each node can be filled is then to be decided by a \b predicate.
 *
 * The filling routine uses then both to traverse the given nodes and
 * evaluate the predicate at each.
 *
 * Hence, the filling of a domain is abstracted into the following parts:
 *
 *  -# \ref Mesh - node containers
 *  -# \ref FillPredicate - predicates
 *  -# \ref Filler - a filling routine which itself requires
 *    -# \ref Cluster - a set of atoms alone(!) inside a specific Shape
 *    -# \ref CopyAtomsInterface - copy Method for atoms used by Cluster::clone
 *    -# \ref Inserter - an insertion routine for the cloned cluster
 *
 * \section filling-node-generation Node generation
 *
 * The node generation is basically just a point or mesh generator that fills
 * a specified region based on the class Shape with a mesh in such a way as to 
 * fulfill certain criteria:
 *
 *    -# equidistant
 *    -# containing certain primitive volumes (e.g. for fitting polymers)
 *    -# ...
 *
 * \section filling-predicate Predicates
 *
 * The Predicate pattern has already been used with Descriptors and Shapes.
 * These are simply function objects that return a boolean value. I.e. they
 * decide whether the current node in the mesh is vacant and can be filled or
 * not. As with the predicate() function in the class Descriptor, these should
 * be composable via logic operators such as || (or), && (and), ! (not), ...
 *
 * \note each predicate receives on construction all the required
 * information, e.g. LinkedCell_View or Tesselation references or objects, ...
 *
 * \section filling-filling-routine Filling routine
 *
 * The filling routine is then simply a function that goes through the given
 * number of nodes (completely unaware of the geometry) and evaluates for each
 * point the given predicates (which might be a composition of other predicates).
 *
 * It rejects all nodes that evaluate to false, the list of valid points is
 * then traversed again and at each node a Cluster is created by the copy method.
 *
 * Note that we rely on \ref Cluster's, objects containing a set of atomicId_t
 * and a \ref Shape, containing all of these atoms, to fill at each node. We use
 * Cluster::clone() to create a copy that is subsequently placed at the desired
 * node via an \ref Inserter functor. This allows to either simply shift the
 * Cluster or even to perform some random translations and rotations on it, see
 * the specific implementations of the class \ref Inserter.
 *
 *
 * \date 2014-03-10
 */