* available "evaluate field" methods to store the data from each time step,
* and the class extracts data for the requested
* points to store it. Finally, once the computation is finished, the user can
- * request Gnuplot output files to be generated.
+ * request output files to be generated; these files are in Gnuplot format but
+ * are basically just regular text and can easily be imported into other
+ * programs well, for example into spreadsheets.
*
- * The user can store extra variables which do not relate to mesh location by
- * the parameter by specifying n_independent_variables. The class then expects
+ * The user can store extra variables which do not relate to mesh location
+ * specifying n_independent_variables. The class then expects
* a std::vector of size n_independent_variables to be added during each step
* using the method @p push_back_independent. This may be used for example for
* recording external input, logging solver performance data such as time
- * taken to solve the step and solver steps before convergence, or saving
- * norms calculated.
+ * taken to solve the step and solver steps before convergence, saving
+ * norms calculated, or simply saving the time, number of time step, or number
+ * of nonlinear iteration along with the data evaluated from the mesh.
*
* The three "evaluate field" methods each have different strengths and
* weaknesses making each suitable for different contexts:
* <ol>
* <li>Firstly, the @p evaluate_field version that does not take a @p DataPostprocessor object
- * selects the nearest support points to a given point to
+ * selects the nearest support point (see @ref GlossSupport "this entry in the glossary")
+ * to a given point to
* extract data from. This makes the code that needs to be run at each time step very short,
* since looping over the mesh to extract the needed dof_index can be done
* just once at the start. However, this method is not suitable for
* FiniteElement objects that do not assign dofs to actual mesh locations
* (i.e. FEs without @ref GlossSupport "support points") or if adaptive mesh refinement is used.
- * The class will throw an exception if any change to the triangulation is made. Although the
- * listeners that detect this change could be used to recompute the nearest support points,
+ * The reason for the latter restriction is that the location of the closest
+ * support point to a given point may change upon mesh refinement.
+ * The class will throw an exception if any change to the triangulation is made
+ * (Although the nearest support point could be re-computed upon mesh refinement,
* the location of the support point will most likely change slightly, making the interpretation
- * of the data difficult, hence this is not implemented currently.
+ * of the data difficult, hence this is not implemented currently.)
*
* <li> Secondly, @p evaluate_field_at_requested_location calls @p
* VectorTools::point_value to compute values at the specific point requested.
* the sense that the quadrature point selected is guaranteed to remain in the
* same vicinity, the class does not prevent the use of this method in adaptive
* codes. The class provides warnings in the output files if the mesh has changed.
+ * Note that one can reduce the error this procedure introduces by providing
+ * a quadrature formula that has more points, at the expense of performing more
+ * work since then the closest quadrature points is nearer to the point at which
+ * the evaluation is really supposed to happen. (As a sidenote: Why not do the
+ * evaluation at the requested point right away? The reason for this is that it
+ * would require setting up a new quadrature point object on each cell that has
+ * only a single point corresponding to the reference coordinates of the point you
+ * really want; then initializing a FEValues object with it; then evaluating the
+ * solution at this point; then handing the result to the DataPostprocessor object.
+ * This sequence of things is expensive -- which is the reason why
+ * VectorTools::point_value() is expensive. Using the same quadrature formula
+ * on each cell on which we want to evaluate the solution and only having to
+ * initialize a FEValue object once is a much cheaper alternative, albeit of
+ * course at the expense of getting only an approximate result.)
* </ol>
*
* When recording a new mnemonic name, the user must supply a std::vector<unsigned int>
- * components that lists the (generally FE) components to be extracted from the
+ * components that lists the @ref GlossComponent "(vector) components" to be extracted from the
* given input. If the user simply wants to extract all the components, or the first
- * n components then default parameters and overloaded functions mean that
- * the std::vector need not be explicitly supplied to the @p add_field_name method.
+ * n components then default parameters and overloaded functions mean that
+ * the std::vector need not be explicitly supplied to the @p add_field_name method.
* If the @p evaluate_field with a @p DataPostprocessor object is used, the components
- * are interpreted as the component of the @p DataPostprocessor return vector. This
+ * are interpreted as the component of the @p DataPostprocessor return vector. This
* vector can be larger than the FE space.
*
- * The class automatically generates names for the data stored based on the mnemoics
- * supplied. The methods @p add_component_names and @p add_independent_names allow
+ * The class automatically generates names for the data stored based on the mnemonics
+ * supplied. The methods @p add_component_names and @p add_independent_names allow
* the user to provide lists of names to use instead if desired.
*
* Following is a little code snippet that shows a common usage of this class:
* point are found and their details stored
* for use when @p evaluate_field is
* called. If more than one point is
- * required rather used the @p add_points
+ * required rather use the @p add_points
* method since this minimizes iterations
* over the mesh.
*/
* Put another mnemonic string (and hence
* @p VECTOR) into the class. This method
* adds storage space for components.size()
- * variables.
+ * variables.
* This also adds extra entries for points
* that are already in the class, so
* @p add_field_name and @p add_points can
* be called in any order.
*/
- void add_field_name(const std::string &vector_name,
+ void add_field_name(const std::string &vector_name,
const std::vector <unsigned int> &components = std::vector <unsigned int>());
-
+
/**
* Put another mnemonic string (and hence
* @p VECTOR) into the class. This method
* adds storage space for components.size()
- * variables.
+ * variables.
* This also adds extra entries for points
* that are already in the class, so
* @p add_field_name and @p add_points can
* be called in any order.
- * This method generates a std::vector
- * 0, ..., n_components-1 and calls the
+ * This method generates a std::vector
+ * 0, ..., n_components-1 and calls the
* previous function.
*/
- void add_field_name(const std::string &vector_name,
+ void add_field_name(const std::string &vector_name,
const unsigned int n_components);
-
+
/**
* Provide optional names for each component
- * of a field. These names will be used
- * instead of names generated from the
+ * of a field. These names will be used
+ * instead of names generated from the
* field name, if supplied.
*/
- void add_component_names(const std::string &vector_name,
+ void add_component_names(const std::string &vector_name,
const std::vector <std::string> &component_names);
-
+
/**
* Provide optional names for the
- * independent values. These names will
+ * independent values. These names will
* be used instead of "Indep_...", if
* supplied.
*/
* ExcDataLostSync error can occur.
*/
template <class VECTOR>
- void evaluate_field(const std::string &vector_name, const VECTOR & solution);
+ void evaluate_field(const std::string &name,
+ const VECTOR & solution);
/**
* are invalidated as the quadrature points are repicked
* each time the function is called.) Nevertheless
* the user must be aware that if the mesh changes the
- * point selected will also vary slightly, making
- * interpretation of the data more difficult.
+ * point selected will also vary slightly, making
+ * interpretation of the data more difficult.
* If a @p DoFHandler is used, one (and only
* one) evaluate_field method
* must be called for each dataset (time
* ExcDataLostSync error can occur.
*/
template <class VECTOR>
- void evaluate_field(const std::vector <std::string> &vector_names, const VECTOR & solution, const DataPostprocessor<dim> & data_postprocessor, const Quadrature<dim> & quadrature);
+ void evaluate_field(const std::vector <std::string> &names,
+ const VECTOR & solution,
+ const DataPostprocessor<dim> & data_postprocessor,
+ const Quadrature<dim> & quadrature);
- /**
- * Construct a std::vector <std::string>
+ /**
+ * Construct a std::vector <std::string>
* containing only vector_name and
* call the above function. The above function
* is more efficient if multiple fields
* use the same @p DataPostprocessor object.
*/
template <class VECTOR>
- void evaluate_field(const std::string &vector_name, const VECTOR & solution, const DataPostprocessor<dim> & data_postprocessor, const Quadrature<dim> & quadrature);
+ void evaluate_field(const std::string &name,
+ const VECTOR & solution,
+ const DataPostprocessor<dim> & data_postprocessor,
+ const Quadrature<dim> & quadrature);
/**
* has been modified because it uses calls to
* @p VectorTools::point_value to extract there
* data. Therefore, if only this method is used,
- * the class is fully compatible with
+ * the class is fully compatible with
* adaptive refinement.
* The list of components supplied when the
* field was added is used to select
* ExcDataLostSync error can occur.
*/
template <class VECTOR>
- void evaluate_field_at_requested_location(const std::string &vector_name, const VECTOR & solution); // changed
+ void evaluate_field_at_requested_location(const std::string &name,
+ const VECTOR & solution);
/**
* started. This prevents a @p
* ExcDataLostSync.
*/
- void start_new_dataset(double key);
+ void start_new_dataset (const double key);
/**
* If independent values have been set
* exception can be thrown if this method
* is not called.
*/
- void push_back_independent(const std::vector <double> &independent_values);
+ void push_back_independent (const std::vector <double> &independent_values);
/**
* were added to the class.
* The names of the data columns can
* be supplied using the functions
- * @p add_component_names and
+ * @p add_component_names and
* @p add_independent_names.
* The support point information is only
* meaningful if the dof_handler has not
* and will suppress postprocessor
* locations output.
*/
- void write_gnuplot(const std::string &base_name, const std::vector <Point <dim> > postprocessor_locations = std::vector <Point <dim> > ());
+ void write_gnuplot (const std::string &base_name,
+ const std::vector <Point <dim> > postprocessor_locations = std::vector <Point <dim> > ());
/**
* The function mark_support_locations replaces
* it and reflects the fact that the locations
* marked are actually the support points.
+ *
+ * @deprecated
*/
Vector<double> mark_locations();
* to the correct number of points by the
* method.
*/
- void get_postprocessor_locations (const Quadrature<dim> & quadrature, std::vector<Point <dim> > & locations);
+ void get_postprocessor_locations (const Quadrature<dim> & quadrature,
+ std::vector<Point <dim> > & locations);
/**
* Once datasets have been added to the
* must be exactly equal.
*/
- bool deep_check (bool strict);
-
-
- /**
- * A function that will be triggered
- * through signals whenever the
- * triangulation is modified.
- *
- * It is currently used to check
- * if the triangulation has changed,
- * invalidating precomputed values.
- */
- void tria_change_listener ();
-
+ bool deep_check (const bool strict);
/**
* A call has been made to @p
/**
* A method which requires access to a @p
* DoFHandler to be meaningful has been
- * called when @p have_dof_handler is
+ * called when @p have_dof_handler is
* false (most likely due to default
* constructor being called). Only
* independent variables may be logged
DeclException0(ExcDoFHandlerRequired);
/**
- * The triangulation indicated that mesh
+ * The triangulation indicated that mesh
* has been refined in some way. This suggests
* that the internal dof indices stored
* are no longer meaningful.
* location.
*/
std::vector <std::vector <double> > independent_values;
-
+
/**
* Saves a vector listing component
* names associated with a independent_values.
* FE.n_components () long.
*/
std::map <std::string, std::vector <std::vector <double> > > data_store;
-
-
+
+
/**
* Saves a vector listing components
- * associated with a mnemonic.
+ * associated with a mnemonic.
*/
std::map <std::string, std::vector<unsigned int> > field_components;
-
+
/**
* Saves a vector listing component
* names associated with a mnemonic.
* if the user does not supplies names.
*/
std::map <std::string, std::vector<std::string> > component_names_map;
-
+
/**
* Saves the location and other mesh info
* about support points.
* variables requested.
*/
unsigned int n_indep;
+
+
+ /**
+ * A function that will be triggered
+ * through signals whenever the
+ * triangulation is modified.
+ *
+ * It is currently used to check
+ * if the triangulation has changed,
+ * invalidating precomputed values.
+ */
+ void tria_change_listener ();
};
projects / dealii-svn.git / commitdiff