From bc62e19ca4d14833aa802d5d741a78a03ad4ab8e Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Mon, 15 Dec 2014 23:26:45 +0100 Subject: [PATCH] Run wrapcomments.py, release step 0c --- include/deal.II/algorithms/any_data.h | 71 +- include/deal.II/algorithms/newton.h | 124 +- include/deal.II/algorithms/operator.h | 121 +- .../deal.II/algorithms/theta_timestepping.h | 266 +- include/deal.II/algorithms/timestep_control.h | 65 +- include/deal.II/base/aligned_vector.h | 32 +- .../deal.II/base/auto_derivative_function.h | 179 +- include/deal.II/base/conditional_ostream.h | 76 +- include/deal.II/base/convergence_table.h | 78 +- include/deal.II/base/data_out_base.h | 2140 +++++------ include/deal.II/base/derivative_form.h | 135 +- include/deal.II/base/event.h | 59 +- include/deal.II/base/exceptions.h | 354 +- include/deal.II/base/flow_function.h | 118 +- include/deal.II/base/function.h | 406 +- include/deal.II/base/function_derivative.h | 99 +- include/deal.II/base/function_lib.h | 500 +-- include/deal.II/base/function_parser.h | 99 +- include/deal.II/base/function_time.h | 68 +- include/deal.II/base/geometry_info.h | 1670 ++++----- include/deal.II/base/graph_coloring.h | 200 +- include/deal.II/base/index_set.h | 62 +- include/deal.II/base/iterator_range.h | 130 +- include/deal.II/base/job_identifier.h | 48 +- include/deal.II/base/logstream.h | 249 +- include/deal.II/base/memory_consumption.h | 330 +- include/deal.II/base/mg_level_object.h | 45 +- include/deal.II/base/mpi.h | 65 +- include/deal.II/base/multithread_info.h | 110 +- include/deal.II/base/named_data.h | 136 +- include/deal.II/base/numbers.h | 164 +- include/deal.II/base/parallel.h | 469 +-- include/deal.II/base/parameter_handler.h | 1202 +++--- include/deal.II/base/parsed_function.h | 153 +- include/deal.II/base/partitioner.h | 251 +- include/deal.II/base/path_search.h | 191 +- include/deal.II/base/point.h | 125 +- include/deal.II/base/polynomial.h | 303 +- include/deal.II/base/polynomial_space.h | 212 +- include/deal.II/base/polynomials_abf.h | 93 +- include/deal.II/base/polynomials_adini.h | 84 +- include/deal.II/base/polynomials_bdm.h | 105 +- include/deal.II/base/polynomials_nedelec.h | 94 +- include/deal.II/base/polynomials_p.h | 51 +- include/deal.II/base/polynomials_piecewise.h | 3 +- .../deal.II/base/polynomials_raviart_thomas.h | 91 +- include/deal.II/base/qprojector.h | 411 +- include/deal.II/base/quadrature.h | 276 +- include/deal.II/base/quadrature_lib.h | 305 +- include/deal.II/base/quadrature_selector.h | 46 +- include/deal.II/base/smartpointer.h | 197 +- include/deal.II/base/subscriptor.h | 184 +- include/deal.II/base/symmetric_tensor.h | 949 ++--- include/deal.II/base/synchronous_iterator.h | 63 +- include/deal.II/base/table.h | 1289 +++---- include/deal.II/base/table_handler.h | 548 ++- include/deal.II/base/table_indices.h | 251 +- include/deal.II/base/template_constraints.h | 99 +- include/deal.II/base/tensor.h | 511 ++- include/deal.II/base/tensor_base.h | 451 +-- include/deal.II/base/tensor_function.h | 55 +- .../deal.II/base/tensor_product_polynomials.h | 61 +- .../base/tensor_product_polynomials_const.h | 6 +- include/deal.II/base/thread_local_storage.h | 142 +- include/deal.II/base/thread_management.h | 1230 +++--- include/deal.II/base/time_stepping.h | 202 +- include/deal.II/base/timer.h | 426 +-- include/deal.II/base/types.h | 207 +- include/deal.II/base/utilities.h | 539 +-- include/deal.II/base/vector_slice.h | 46 +- include/deal.II/base/vectorization.h | 101 +- include/deal.II/base/work_stream.h | 323 +- include/deal.II/distributed/grid_refinement.h | 101 +- .../deal.II/distributed/solution_transfer.h | 227 +- include/deal.II/distributed/tria.h | 803 ++-- include/deal.II/dofs/block_info.h | 153 +- include/deal.II/dofs/dof_accessor.h | 1260 +++---- include/deal.II/dofs/dof_accessor.templates.h | 69 +- include/deal.II/dofs/dof_faces.h | 90 +- include/deal.II/dofs/dof_handler.h | 624 ++-- include/deal.II/dofs/dof_handler_policy.h | 44 +- include/deal.II/dofs/dof_iterator_selector.h | 9 +- include/deal.II/dofs/dof_levels.h | 68 +- include/deal.II/dofs/dof_objects.h | 123 +- include/deal.II/dofs/dof_renumbering.h | 564 ++- include/deal.II/dofs/dof_tools.h | 1967 +++++----- include/deal.II/dofs/function_map.h | 64 +- include/deal.II/dofs/number_cache.h | 52 +- include/deal.II/fe/block_mask.h | 167 +- include/deal.II/fe/component_mask.h | 166 +- include/deal.II/fe/fe.h | 682 ++-- include/deal.II/fe/fe_abf.h | 291 +- include/deal.II/fe/fe_base.h | 11 +- include/deal.II/fe/fe_bdm.h | 69 +- include/deal.II/fe/fe_dg_vector.h | 165 +- include/deal.II/fe/fe_dgp.h | 300 +- include/deal.II/fe/fe_dgp_monomial.h | 270 +- include/deal.II/fe/fe_dgp_nonparametric.h | 378 +- include/deal.II/fe/fe_dgq.h | 297 +- include/deal.II/fe/fe_face.h | 57 +- include/deal.II/fe/fe_nedelec.h | 354 +- include/deal.II/fe/fe_nothing.h | 223 +- include/deal.II/fe/fe_poly.h | 40 +- include/deal.II/fe/fe_poly_face.h | 209 +- include/deal.II/fe/fe_poly_tensor.h | 195 +- include/deal.II/fe/fe_q.h | 913 ++--- include/deal.II/fe/fe_q_base.h | 89 +- include/deal.II/fe/fe_q_dg0.h | 140 +- include/deal.II/fe/fe_q_hierarchical.h | 1190 ++---- include/deal.II/fe/fe_q_iso_q1.h | 23 +- include/deal.II/fe/fe_raviart_thomas.h | 307 +- include/deal.II/fe/fe_system.h | 157 +- include/deal.II/fe/fe_tools.h | 236 +- include/deal.II/fe/fe_trace.h | 50 +- include/deal.II/fe/fe_update_flags.h | 165 +- include/deal.II/fe/fe_values.h | 233 +- include/deal.II/fe/fe_values_extractors.h | 202 +- include/deal.II/fe/mapping.h | 635 ++-- include/deal.II/fe/mapping_c1.h | 25 +- include/deal.II/fe/mapping_cartesian.h | 84 +- include/deal.II/fe/mapping_q.h | 43 +- include/deal.II/fe/mapping_q1.h | 535 +-- include/deal.II/fe/mapping_q1_eulerian.h | 136 +- include/deal.II/fe/mapping_q_eulerian.h | 67 +- include/deal.II/grid/cell_id.h | 4 +- include/deal.II/grid/filtered_iterator.h | 507 +-- include/deal.II/grid/grid_generator.h | 414 +-- include/deal.II/grid/grid_in.h | 480 +-- include/deal.II/grid/grid_out.h | 822 ++-- include/deal.II/grid/grid_refinement.h | 268 +- include/deal.II/grid/grid_reordering.h | 658 ++-- .../deal.II/grid/grid_reordering_internal.h | 483 +-- include/deal.II/grid/grid_tools.h | 1187 +++--- include/deal.II/grid/intergrid_map.h | 105 +- include/deal.II/grid/manifold.h | 434 +-- include/deal.II/grid/manifold_lib.h | 182 +- include/deal.II/grid/persistent_tria.h | 207 +- include/deal.II/grid/tria.h | 3301 ++++++++--------- include/deal.II/grid/tria_accessor.h | 2644 +++++-------- .../deal.II/grid/tria_accessor.templates.h | 52 +- include/deal.II/grid/tria_boundary.h | 73 +- include/deal.II/grid/tria_boundary_lib.h | 476 +-- include/deal.II/grid/tria_faces.h | 71 +- include/deal.II/grid/tria_iterator.h | 803 ++-- include/deal.II/grid/tria_iterator_base.h | 7 +- include/deal.II/grid/tria_iterator_selector.h | 80 +- include/deal.II/grid/tria_levels.h | 187 +- include/deal.II/grid/tria_object.h | 57 +- include/deal.II/grid/tria_objects.h | 489 +-- include/deal.II/hp/dof_faces.h | 257 +- include/deal.II/hp/dof_handler.h | 837 ++--- include/deal.II/hp/dof_level.h | 223 +- include/deal.II/hp/fe_collection.h | 468 +-- include/deal.II/hp/fe_values.h | 140 +- include/deal.II/hp/mapping_collection.h | 92 +- include/deal.II/hp/q_collection.h | 92 +- include/deal.II/integrators/advection.h | 122 +- include/deal.II/integrators/divergence.h | 125 +- include/deal.II/integrators/elasticity.h | 44 +- include/deal.II/integrators/l2.h | 59 +- include/deal.II/integrators/laplace.h | 89 +- .../deal.II/integrators/local_integrators.h | 113 +- include/deal.II/integrators/maxwell.h | 57 +- include/deal.II/lac/arpack_solver.h | 102 +- include/deal.II/lac/block_indices.h | 166 +- include/deal.II/lac/block_list.h | 193 +- include/deal.II/lac/block_matrix.h | 16 +- include/deal.II/lac/block_matrix_array.h | 425 +-- include/deal.II/lac/block_matrix_base.h | 927 ++--- include/deal.II/lac/block_sparse_matrix.h | 294 +- include/deal.II/lac/block_sparse_matrix_ez.h | 209 +- include/deal.II/lac/block_sparsity_pattern.h | 721 ++-- include/deal.II/lac/block_vector.h | 331 +- include/deal.II/lac/block_vector_base.h | 768 ++-- include/deal.II/lac/chunk_sparse_matrix.h | 57 +- .../lac/chunk_sparse_matrix.templates.h | 8 +- include/deal.II/lac/chunk_sparsity_pattern.h | 110 +- .../lac/compressed_set_sparsity_pattern.h | 287 +- .../lac/compressed_simple_sparsity_pattern.h | 52 +- .../deal.II/lac/compressed_sparsity_pattern.h | 342 +- include/deal.II/lac/constraint_matrix.h | 291 +- .../deal.II/lac/constraint_matrix.templates.h | 6 +- include/deal.II/lac/eigen.h | 88 +- include/deal.II/lac/exceptions.h | 15 +- include/deal.II/lac/filtered_matrix.h | 433 +-- include/deal.II/lac/full_matrix.h | 142 +- include/deal.II/lac/generic_linear_algebra.h | 16 +- include/deal.II/lac/householder.h | 45 +- include/deal.II/lac/identity_matrix.h | 118 +- include/deal.II/lac/iterative_inverse.h | 52 +- include/deal.II/lac/lapack_full_matrix.h | 111 +- include/deal.II/lac/lapack_support.h | 30 +- include/deal.II/lac/matrix_block.h | 441 +-- include/deal.II/lac/matrix_iterator.h | 58 +- include/deal.II/lac/matrix_lib.h | 207 +- include/deal.II/lac/matrix_out.h | 208 +- include/deal.II/lac/parallel_block_vector.h | 53 +- include/deal.II/lac/parallel_vector.h | 194 +- .../deal.II/lac/petsc_block_sparse_matrix.h | 195 +- include/deal.II/lac/petsc_block_vector.h | 243 +- include/deal.II/lac/petsc_full_matrix.h | 26 +- include/deal.II/lac/petsc_matrix_base.h | 1025 ++--- include/deal.II/lac/petsc_matrix_free.h | 269 +- .../lac/petsc_parallel_block_sparse_matrix.h | 220 +- .../deal.II/lac/petsc_parallel_block_vector.h | 264 +- .../lac/petsc_parallel_sparse_matrix.h | 449 +-- include/deal.II/lac/petsc_parallel_vector.h | 485 +-- include/deal.II/lac/petsc_precondition.h | 563 +-- include/deal.II/lac/petsc_solver.h | 844 ++--- include/deal.II/lac/petsc_sparse_matrix.h | 300 +- include/deal.II/lac/petsc_vector.h | 172 +- include/deal.II/lac/petsc_vector_base.h | 569 +-- include/deal.II/lac/pointer_matrix.h | 341 +- include/deal.II/lac/precondition.h | 181 +- include/deal.II/lac/precondition_block.h | 585 +-- include/deal.II/lac/precondition_block_base.h | 207 +- include/deal.II/lac/precondition_selector.h | 67 +- include/deal.II/lac/relaxation_block.h | 161 +- include/deal.II/lac/schur_matrix.h | 99 +- include/deal.II/lac/shifted_matrix.h | 14 +- include/deal.II/lac/slepc_solver.h | 364 +- .../lac/slepc_spectral_transformation.h | 128 +- include/deal.II/lac/solver.h | 390 +- include/deal.II/lac/solver_bicgstab.h | 60 +- include/deal.II/lac/solver_cg.h | 111 +- include/deal.II/lac/solver_control.h | 142 +- include/deal.II/lac/solver_gmres.h | 105 +- include/deal.II/lac/solver_minres.h | 88 +- include/deal.II/lac/solver_qmrs.h | 120 +- include/deal.II/lac/solver_relaxation.h | 45 +- include/deal.II/lac/solver_richardson.h | 89 +- include/deal.II/lac/solver_selector.h | 73 +- include/deal.II/lac/sparse_decomposition.h | 384 +- include/deal.II/lac/sparse_direct.h | 153 +- include/deal.II/lac/sparse_ilu.h | 112 +- include/deal.II/lac/sparse_matrix.h | 164 +- include/deal.II/lac/sparse_matrix.templates.h | 39 +- include/deal.II/lac/sparse_matrix_ez.h | 706 ++-- include/deal.II/lac/sparse_mic.h | 113 +- include/deal.II/lac/sparse_vanka.h | 551 ++- include/deal.II/lac/sparsity_pattern.h | 220 +- include/deal.II/lac/sparsity_tools.h | 20 +- include/deal.II/lac/swappable_vector.h | 233 +- include/deal.II/lac/transpose_matrix.h | 51 +- include/deal.II/lac/tridiagonal_matrix.h | 256 +- .../lac/trilinos_block_sparse_matrix.h | 376 +- include/deal.II/lac/trilinos_block_vector.h | 65 +- .../lac/trilinos_parallel_block_vector.h | 57 +- include/deal.II/lac/trilinos_precondition.h | 452 ++- include/deal.II/lac/trilinos_solver.h | 122 +- include/deal.II/lac/trilinos_sparse_matrix.h | 295 +- .../deal.II/lac/trilinos_sparsity_pattern.h | 173 +- include/deal.II/lac/trilinos_vector.h | 343 +- include/deal.II/lac/trilinos_vector_base.h | 181 +- include/deal.II/lac/vector.h | 142 +- include/deal.II/lac/vector_memory.h | 283 +- include/deal.II/lac/vector_view.h | 267 +- include/deal.II/matrix_free/dof_info.h | 25 +- include/deal.II/matrix_free/fe_evaluation.h | 215 +- .../deal.II/matrix_free/helper_functions.h | 53 +- .../matrix_free/mapping_data_on_the_fly.h | 29 +- include/deal.II/matrix_free/mapping_info.h | 13 +- include/deal.II/matrix_free/matrix_free.h | 182 +- include/deal.II/matrix_free/operators.h | 30 +- include/deal.II/matrix_free/shape_info.h | 10 +- include/deal.II/meshworker/assembler.h | 296 +- include/deal.II/meshworker/dof_info.h | 153 +- include/deal.II/meshworker/functional.h | 82 +- include/deal.II/meshworker/integration_info.h | 328 +- include/deal.II/meshworker/local_integrator.h | 95 +- include/deal.II/meshworker/local_results.h | 255 +- include/deal.II/meshworker/loop.h | 81 +- include/deal.II/meshworker/output.h | 94 +- include/deal.II/meshworker/simple.h | 255 +- include/deal.II/meshworker/vector_selector.h | 124 +- include/deal.II/multigrid/mg_base.h | 152 +- include/deal.II/multigrid/mg_block_smoother.h | 64 +- include/deal.II/multigrid/mg_coarse.h | 47 +- .../deal.II/multigrid/mg_constrained_dofs.h | 52 +- include/deal.II/multigrid/mg_dof_handler.h | 68 +- .../multigrid/mg_dof_iterator_selector.h | 12 +- include/deal.II/multigrid/mg_matrix.h | 56 +- include/deal.II/multigrid/mg_smoother.h | 421 +-- include/deal.II/multigrid/mg_tools.h | 116 +- include/deal.II/multigrid/mg_transfer.h | 125 +- .../deal.II/multigrid/mg_transfer.templates.h | 35 +- include/deal.II/multigrid/mg_transfer_block.h | 249 +- .../deal.II/multigrid/mg_transfer_component.h | 211 +- include/deal.II/multigrid/multigrid.h | 369 +- .../multigrid/sparse_matrix_collection.h | 4 +- .../numerics/data_component_interpretation.h | 45 +- include/deal.II/numerics/data_out.h | 82 +- include/deal.II/numerics/data_out_dof_data.h | 209 +- include/deal.II/numerics/data_out_faces.h | 262 +- include/deal.II/numerics/data_out_rotation.h | 174 +- include/deal.II/numerics/data_out_stack.h | 278 +- include/deal.II/numerics/data_postprocessor.h | 402 +- .../numerics/derivative_approximation.h | 193 +- .../deal.II/numerics/dof_output_operator.h | 5 +- .../deal.II/numerics/dof_print_solver_step.h | 45 +- include/deal.II/numerics/error_estimator.h | 311 +- include/deal.II/numerics/fe_field_function.h | 479 +-- include/deal.II/numerics/histogram.h | 163 +- include/deal.II/numerics/matrix_tools.h | 698 ++-- .../deal.II/numerics/point_value_history.h | 715 ++-- include/deal.II/numerics/solution_transfer.h | 394 +- include/deal.II/numerics/time_dependent.h | 1595 +++----- include/deal.II/numerics/vector_tools.h | 26 +- .../deal.II/numerics/vector_tools.templates.h | 56 +- include/deal.II/opencascade/boundary_lib.h | 247 +- include/deal.II/opencascade/utilities.h | 294 +- 311 files changed, 34524 insertions(+), 51293 deletions(-) diff --git a/include/deal.II/algorithms/any_data.h b/include/deal.II/algorithms/any_data.h index d3f60edd5a..95bbb3df32 100644 --- a/include/deal.II/algorithms/any_data.h +++ b/include/deal.II/algorithms/any_data.h @@ -31,8 +31,8 @@ DEAL_II_NAMESPACE_OPEN /** * Store any amount of any type of data accessible by an identifier string. * - * @todo Deprecate access by index after NamedData has been deprecated - * for long enough, then change to a map. + * @todo Deprecate access by index after NamedData has been deprecated for + * long enough, then change to a map. */ class AnyData : public Subscriptor @@ -56,11 +56,10 @@ public: /** * @brief Access to stored data object by name. * - * Find the object with given name, try to convert it to - * type and return it. This function throws an exception - * if either the name does not exist or if the conversion - * fails. If such an exception is not desired, use try_read() - * instead. + * Find the object with given name, try to convert it to type and + * return it. This function throws an exception if either the name does not + * exist or if the conversion fails. If such an exception is not desired, + * use try_read() instead. */ template type entry (const std::string &name); @@ -68,11 +67,10 @@ public: /** * @brief Read-only access to stored data object by name. * - * Find the object with given name, try to convert it to - * type and return it. This function throws an exception - * if either the name does not exist or if the conversion - * fails. If such an exception is not desired, use try_read() - * instead. + * Find the object with given name, try to convert it to type and + * return it. This function throws an exception if either the name does not + * exist or if the conversion fails. If such an exception is not desired, + * use try_read() instead. */ template const type entry (const std::string &name) const; @@ -80,14 +78,13 @@ public: /** * @brief Dedicated read only access by name. * - * For a constant object, this function equals entry(). For a - * non-const object, it forces read only access to the data. In - * particular, it throws an exception if the object is not found - * or cannot be converted to type. If such an exception is not - * desired, use try_read() instead. + * For a constant object, this function equals entry(). For a non-const + * object, it forces read only access to the data. In particular, it throws + * an exception if the object is not found or cannot be converted to type. + * If such an exception is not desired, use try_read() instead. * - * @warning Do not use this function for stored objects which are - * pointers. Use read_ptr() instead! + * @warning Do not use this function for stored objects which are pointers. + * Use read_ptr() instead! */ template const type read (const std::string &name) const; @@ -95,19 +92,18 @@ public: /** * @brief Dedicated read only access by name for pointer data. * - * If the stored data object is a pointer to a constant object, the logic - * of access becomes fairly complicated. Namely, the standard read - * function may fail, depending on whether it was a const pointer - * or a regular pointer. This function fixes the logic and - * ascertains that the object does not become mutable by accident. + * If the stored data object is a pointer to a constant object, the logic of + * access becomes fairly complicated. Namely, the standard read function may + * fail, depending on whether it was a const pointer or a regular pointer. + * This function fixes the logic and ascertains that the object does not + * become mutable by accident. */ template const type *read_ptr (const std::string &name) const; /** - * Perform the same action as read_ptr(), but do not throw an - * exception if the pointer does not exist. Return a null pointer - * instead. + * Perform the same action as read_ptr(), but do not throw an exception if + * the pointer does not exist. Return a null pointer instead. */ template const type *try_read_ptr (const std::string &name) const; @@ -115,10 +111,9 @@ public: /** * @brief Dedicated read only access by name without exceptions. * - * This function tries to find the name in the list and return a - * pointer to the associated object. If either the name is not - * found or the object cannot be converted to the return type, a - * null pointer is returned. + * This function tries to find the name in the list and return a pointer to + * the associated object. If either the name is not found or the object + * cannot be converted to the return type, a null pointer is returned. */ template const type *try_read (const std::string &name) const; @@ -155,17 +150,16 @@ public: /** * @brief Find index of a named object * - * Try to find the objecty and return its index in the list. Throw - * an exception if the object has not been found. + * Try to find the objecty and return its index in the list. Throw an + * exception if the object has not been found. */ unsigned int find(const std::string &name) const; /** * @brief Try to find index of a named object * - * Try to find the objecty and return its index in the - * list. returns numbers::invalid_unsigned_int if the name was not - * found. + * Try to find the objecty and return its index in the list. returns + * numbers::invalid_unsigned_int if the name was not found. */ unsigned int try_find(const std::string &name) const; @@ -193,9 +187,8 @@ public: << " must coincide"); /** - * Exception indicating that a function expected a vector to have a - * certain name, but NamedData had a different name in that - * position. + * Exception indicating that a function expected a vector to have a certain + * name, but NamedData had a different name in that position. */ DeclException2(ExcNameMismatch, int, std::string, << "Name at position " << arg1 << " is not equal to " << arg2); diff --git a/include/deal.II/algorithms/newton.h b/include/deal.II/algorithms/newton.h index c06d026bbf..d8ec3683ef 100644 --- a/include/deal.II/algorithms/newton.h +++ b/include/deal.II/algorithms/newton.h @@ -29,36 +29,34 @@ class ParameterHandler; namespace Algorithms { /** - * Operator class performing Newton's iteration with standard step - * size control and adaptive matrix generation. + * Operator class performing Newton's iteration with standard step size + * control and adaptive matrix generation. * - * This class performs a Newton iteration up to convergence - * determined by #control. If after an update the norm of the residual - * has become larger, then step size control is activated and the - * update is subsequently divided by two until the residual actually - * becomes smaller (or the minimal scaling factor determined by - * #n_stepsize_iterations is reached). + * This class performs a Newton iteration up to convergence determined by + * #control. If after an update the norm of the residual has become larger, + * then step size control is activated and the update is subsequently + * divided by two until the residual actually becomes smaller (or the + * minimal scaling factor determined by #n_stepsize_iterations is reached). * - * Since assembling matrices, depending on the implementation, tends - * to be costly, this method applies an adaptive reassembling - * strategy. Only if the reduction factor for the residual is more - * than #threshold, the event Algorithms::bad_derivative is submitted to - * #inverse_derivative. It is up to this object to implement - * reassembling accordingly. + * Since assembling matrices, depending on the implementation, tends to be + * costly, this method applies an adaptive reassembling strategy. Only if + * the reduction factor for the residual is more than #threshold, the event + * Algorithms::bad_derivative is submitted to #inverse_derivative. It is up + * to this object to implement reassembling accordingly. * *

Contents of the AnyData objects

* * The only value used by the Newton method is the first vector in the - * parameter out of operator()(). It serves as the start - * vector of Newton's method and in the end contains the solution. All - * other vectors of out are ignored by Newton's method and - * its inner Operator objects. All vectors of in are forwarded to - * the inner Operator objects, with additional information added as follows. + * parameter out of operator()(). It serves as the start vector of + * Newton's method and in the end contains the solution. All other vectors + * of out are ignored by Newton's method and its inner Operator + * objects. All vectors of in are forwarded to the inner Operator + * objects, with additional information added as follows. * * When calling (*#residual)(), the NamedData in given to the - * Newton iteration is prepended by a vector "Newton iterate", - * the current value of the Newton iterate, which can be used to - * evaluate the residual at this point. + * Newton iteration is prepended by a vector "Newton iterate", the + * current value of the Newton iterate, which can be used to evaluate the + * residual at this point. * * For the call to (*#inverse_derivative), the vector "Newton * residual" is inserted before "Newton iterate". @@ -70,10 +68,8 @@ namespace Algorithms { public: /** - * Constructor, receiving the - * applications computing the - * residual and solving the - * linear problem, respectively. + * Constructor, receiving the applications computing the residual and + * solving the linear problem, respectively. */ Newton (Operator &residual, Operator &inverse_derivative); @@ -93,20 +89,14 @@ namespace Algorithms void initialize (ParameterHandler ¶m) DEAL_II_DEPRECATED; /** - * Initialize the pointer - * data_out for debugging. + * Initialize the pointer data_out for debugging. */ void initialize (OutputOperator &output); /** - * The actual Newton - * iteration. The initial value - * is in out(0), which - * also contains the result - * after convergence. Values in - * in are not used by - * Newton, but will be handed - * down to the objects + * The actual Newton iteration. The initial value is in out(0), + * which also contains the result after convergence. Values in in + * are not used by Newton, but will be handed down to the objects * #residual and #inverse_derivative. */ virtual void operator() (AnyData &out, const AnyData &in); @@ -119,17 +109,13 @@ namespace Algorithms virtual void notify(const Event &); /** - * Set the maximal residual - * reduction allowed without - * triggering assembling in the - * next step. Return the - * previous value. + * Set the maximal residual reduction allowed without triggering + * assembling in the next step. Return the previous value. */ double threshold(double new_value); /** - * Control object for the - * Newton iteration. + * Control object for the Newton iteration. */ ReductionControl control; private: @@ -139,73 +125,55 @@ namespace Algorithms SmartPointer, Newton > residual; /** - * The operator applying the - * inverse derivative to the residual. + * The operator applying the inverse derivative to the residual. */ SmartPointer, Newton > inverse_derivative; /** - * The operator handling the output - * in case the debug_vectors is true. + * The operator handling the output in case the debug_vectors is true. * Call the initialize function first. */ SmartPointer, Newton > data_out; /** - * This flag is set by the - * function assemble(), - * indicating that the matrix - * must be assembled anew upon - * start. + * This flag is set by the function assemble(), indicating that the matrix + * must be assembled anew upon start. */ bool assemble_now; /** - * A flag used to decide how - * many stepsize iteration - * should be made. Default is - * the original value of 21. + * A flag used to decide how many stepsize iteration should be made. + * Default is the original value of 21. * - * Enter zero here to turn of - * stepsize control. + * Enter zero here to turn of stepsize control. * - * @note Controlled by - * Stepsize iterations in - * parameter file + * @note Controlled by Stepsize iterations in parameter file */ unsigned int n_stepsize_iterations; /** * Threshold for re-assembling matrix. * - * If the quotient of two - * consecutive residuals is - * smaller than this threshold, - * the system matrix is not - * assembled in this step. + * If the quotient of two consecutive residuals is smaller than this + * threshold, the system matrix is not assembled in this step. * - * @note This parameter should be - * adjusted to the residual gain - * of the inner solver. + * @note This parameter should be adjusted to the residual gain of the + * inner solver. * - * The default values is zero, - * resulting in reassembling in - * every Newton step. + * The default values is zero, resulting in reassembling in every Newton + * step. */ double assemble_threshold; public: /** - * Print residual, update and - * updated solution after each - * step into file + * Print residual, update and updated solution after each step into file * Newton_NNN? */ bool debug_vectors; /** - * Write debug output to - * @p deallog; the higher the - * number, the more output. + * Write debug output to @p deallog; the higher the number, the more + * output. */ unsigned int debug; }; diff --git a/include/deal.II/algorithms/operator.h b/include/deal.II/algorithms/operator.h index 09315f2968..8aa1924691 100644 --- a/include/deal.II/algorithms/operator.h +++ b/include/deal.II/algorithms/operator.h @@ -29,10 +29,10 @@ DEAL_II_NAMESPACE_OPEN /** * Namespace containing numerical algorithms in a unified form. * - * All algorithmic classes in this namespace are derived from either - * Operator or OutputOperator, depending on whether they return a - * value or not. See the documentation of those classes for more - * detailed information on how to use them. + * All algorithmic classes in this namespace are derived from either Operator + * or OutputOperator, depending on whether they return a value or not. See the + * documentation of those classes for more detailed information on how to use + * them. * * @author Guido Kanschat * @date 2012, 2013 @@ -42,30 +42,28 @@ namespace Algorithms /** * @todo Update this documentation and the one of Operator * - * The abstract base class of all algorithms in this library. An - * operator is an object with an operator(), which transforms a set - * of named vectors into another set of named vectors. + * The abstract base class of all algorithms in this library. An operator is + * an object with an operator(), which transforms a set of named vectors + * into another set of named vectors. * - * Furthermore, an operator can be notified of parameter changes by - * the calling routine. The outer iteration can notify() the Operator - * of an Event, which could be for instance a change of mesh, a - * different time step size or too slow convergence of Newton's - * method, which would then trigger reassembling of a matrix or - * similar things. + * Furthermore, an operator can be notified of parameter changes by the + * calling routine. The outer iteration can notify() the Operator of an + * Event, which could be for instance a change of mesh, a different time + * step size or too slow convergence of Newton's method, which would then + * trigger reassembling of a matrix or similar things. * *

Usage for nested iterations

* - * This is probably the most prominent use for Operator, where an - * outer iterative method calls an inner solver and so on. Typically, - * the innermost method in such a nested system will have to compute a - * residual using values from all outer iterations. Since the depth - * and order of such a nesting is hardly predictable when designing a - * general tool, we use AnyData to access these vectors. Typically, - * the first vector in out contains the start vector when - * operator()() is called, and the solution when the function - * returns. The object in is providing additional information - * and forwarded to the inner Operator objects of the nested - * iteration. + * This is probably the most prominent use for Operator, where an outer + * iterative method calls an inner solver and so on. Typically, the + * innermost method in such a nested system will have to compute a residual + * using values from all outer iterations. Since the depth and order of such + * a nesting is hardly predictable when designing a general tool, we use + * AnyData to access these vectors. Typically, the first vector in + * out contains the start vector when operator()() is called, and + * the solution when the function returns. The object in is + * providing additional information and forwarded to the inner Operator + * objects of the nested iteration. * * @author Guido Kanschat * @date 2014 @@ -79,14 +77,12 @@ namespace Algorithms ~OperatorBase(); /** - * The actual operation, which - * is implemented in a derived class. + * The actual operation, which is implemented in a derived class. */ virtual void operator() (AnyData &out, const AnyData &in) = 0; /** - * Register an event triggered - * by an outer iteration. + * Register an event triggered by an outer iteration. */ virtual void notify(const Event &); /** @@ -95,11 +91,8 @@ namespace Algorithms void clear_events(); protected: /** - * Accumulate events here. If any of - * those is set, the function - * solve() of a terminal - * application must take care - * of reassembling the matrix. + * Accumulate events here. If any of those is set, the function solve() of + * a terminal application must take care of reassembling the matrix. */ Event notifications; @@ -108,30 +101,28 @@ namespace Algorithms /** * @deprecated This class has been replaced by OperatorBase. * - * The abstract base class of all algorithms in this library. An - * operator is an object with an operator(), which transforms a set - * of named vectors into another set of named vectors. + * The abstract base class of all algorithms in this library. An operator is + * an object with an operator(), which transforms a set of named vectors + * into another set of named vectors. * - * Furthermore, an operator can be notified of parameter changes by - * the calling routine. The outer iteration can notify() the Operator - * of an Event, which could be for instance a change of mesh, a - * different time step size or too slow convergence of Newton's - * method, which would then trigger reassembling of a matrix or - * similar things. + * Furthermore, an operator can be notified of parameter changes by the + * calling routine. The outer iteration can notify() the Operator of an + * Event, which could be for instance a change of mesh, a different time + * step size or too slow convergence of Newton's method, which would then + * trigger reassembling of a matrix or similar things. * *

Usage for nested iterations

* - * This is probably the most prominent use for Operator, where an - * outer iterative method calls an inner solver and so on. Typically, - * the innermost method in such a nested system will have to compute a - * residual using values from all outer iterations. Since the depth - * and order of such a nesting is hardly predictable when designing a - * general tool, we use NamedData to access these vectors. Typically, - * the first vector in out contains the start vector when - * operator()() is called, and the solution when the function - * returns. The object in is providing additional information - * and forwarded to the inner Operator objects of the nested - * iteration. + * This is probably the most prominent use for Operator, where an outer + * iterative method calls an inner solver and so on. Typically, the + * innermost method in such a nested system will have to compute a residual + * using values from all outer iterations. Since the depth and order of such + * a nesting is hardly predictable when designing a general tool, we use + * NamedData to access these vectors. Typically, the first vector in + * out contains the start vector when operator()() is called, and + * the solution when the function returns. The object in is + * providing additional information and forwarded to the inner Operator + * objects of the nested iteration. * * @author Guido Kanschat, 2010 */ @@ -143,16 +134,15 @@ namespace Algorithms /** * Implementation of the function in the base class in order to do - * compatibility conversions between the old and the new - * interface. + * compatibility conversions between the old and the new interface. */ virtual void operator() (AnyData &out, const AnyData &in); /** - * @deprecated It is in particular this function which should not be used anymore. + * @deprecated It is in particular this function which should not be used + * anymore. * - * The actual operation, which - * is implemented in a derived class. + * The actual operation, which is implemented in a derived class. */ virtual void operator() (NamedData &out, const NamedData &in); @@ -163,15 +153,15 @@ namespace Algorithms private: /** - * While we are providing compatibility functions to the old - * interface, this variable will ensure there is no endless loop. + * While we are providing compatibility functions to the old interface, + * this variable will ensure there is no endless loop. */ bool compatibility_flag; }; /** - * An unary operator base class, intended to output the vectors in - * NamedData in each step of an iteration. + * An unary operator base class, intended to output the vectors in NamedData + * in each step of an iteration. * * @author Guido Kanschat, 2010 */ @@ -187,11 +177,8 @@ namespace Algorithms virtual ~OutputOperator(); /** - * Set the stream @p os to - * which data is written. If - * no stream is selected with - * this function, data goes - * to @p deallog. + * Set the stream @p os to which data is written. If no stream is selected + * with this function, data goes to @p deallog. */ void initialize_stream(std::ostream &stream); /** diff --git a/include/deal.II/algorithms/theta_timestepping.h b/include/deal.II/algorithms/theta_timestepping.h index 77e8f0b796..e24c3a0194 100644 --- a/include/deal.II/algorithms/theta_timestepping.h +++ b/include/deal.II/algorithms/theta_timestepping.h @@ -28,14 +28,13 @@ class ParameterHandler; namespace Algorithms { /** - * A little structure, gathering the size of a timestep and the - * current time. Time stepping schemes can use this to provide time - * step information to the classes actually performing a single step. + * A little structure, gathering the size of a timestep and the current + * time. Time stepping schemes can use this to provide time step information + * to the classes actually performing a single step. * * The definition of what is considered "current time" depends on the - * scheme. For an explicit scheme, this is the time at the beginning - * of the step. For an implicit scheme, it is usually the time at the - * end. + * scheme. For an explicit scheme, this is the time at the beginning of the + * step. For an implicit scheme, it is usually the time at the end. */ struct TimestepData { @@ -49,20 +48,20 @@ namespace Algorithms * Application class performing the theta timestepping scheme. * * The theta scheme is an abstraction of implicit and explicit Euler - * schemes, the Crank-Nicholson scheme and linear combinations of - * those. The choice of the actual scheme is controlled by the - * parameter #theta as follows. + * schemes, the Crank-Nicholson scheme and linear combinations of those. The + * choice of the actual scheme is controlled by the parameter #theta as + * follows. *
    *
  • #theta=0: explicit Euler scheme *
  • #theta=1: implicit Euler scheme *
  • #theta=½: Crank-Nicholson scheme *
* - * For fixed #theta, the Crank-Nicholson scheme is the only second - * order scheme. Nevertheless, further stability may be achieved by - * choosing #theta larger than ½, thereby introducing a first order - * error term. In order to avoid a loss of convergence order, the - * adaptive theta scheme can be used, where #theta=½+c dt. + * For fixed #theta, the Crank-Nicholson scheme is the only second order + * scheme. Nevertheless, further stability may be achieved by choosing + * #theta larger than ½, thereby introducing a first order error term. In + * order to avoid a loss of convergence order, the adaptive theta scheme can + * be used, where #theta=½+c dt. * * Assume that we want to solve the equation u' + F(u) = 0 with a * step size k. A step of the theta scheme can be written as @@ -72,132 +71,118 @@ namespace Algorithms * @f] * * Here, M is the mass matrix. We see, that the right hand side - * amounts to an explicit Euler step with modified step size in weak - * form (up to inversion of M). The left hand side corresponds to an - * implicit Euler step with modified step size (right hand side - * given). Thus, the implementation of the theta scheme will use two - * Operator objects, one for the explicit, one for the implicit - * part. Each of these will use its own TimestepData to account for - * the modified step sizes (and different times if the problem is not - * autonomous). Note that once the explicit part has been computed, - * the left hand side actually constitutes a linear or nonlinear - * system which has to be solved. + * amounts to an explicit Euler step with modified step size in weak form + * (up to inversion of M). The left hand side corresponds to an implicit + * Euler step with modified step size (right hand side given). Thus, the + * implementation of the theta scheme will use two Operator objects, one for + * the explicit, one for the implicit part. Each of these will use its own + * TimestepData to account for the modified step sizes (and different times + * if the problem is not autonomous). Note that once the explicit part has + * been computed, the left hand side actually constitutes a linear or + * nonlinear system which has to be solved. * *

Usage AnyData

* - * ThetaTimestepping uses AnyData for communicating vectors and time - * step information. With - * outer or inner Operator objects. It does not use itself the input - * vectors provided, but forwards them to the explicit and implicit - * operators. + * ThetaTimestepping uses AnyData for communicating vectors and time step + * information. With outer or inner Operator objects. It does not use itself + * the input vectors provided, but forwards them to the explicit and + * implicit operators. * *

Vector data

* - * The explicit Operator #op_explicit receives in its input in first - * place the vector "Previous iterate", which is the solution - * value after the previous timestep. It is followed by all vectors - * provided to ThetaTimestepping::operator() as input - * argument. #op_explicit is supposed to write its result into the - * first position of its output argument, labeled "Result". + * The explicit Operator #op_explicit receives in its input in first place + * the vector "Previous iterate", which is the solution value after the + * previous timestep. It is followed by all vectors provided to + * ThetaTimestepping::operator() as input argument. #op_explicit is supposed + * to write its result into the first position of its output argument, + * labeled "Result". * - * The implicit Operator #op_implicit receives the result of - * #op_explicit in its first input vector labeled "Previous - * time". It is followed by all vectors provided to - * ThetaTimestepping::operator() as input argument. The output of - * #op_implicit is directly written into the output argument given to - * ThetaTimestepping. + * The implicit Operator #op_implicit receives the result of #op_explicit in + * its first input vector labeled "Previous time". It is followed by all + * vectors provided to ThetaTimestepping::operator() as input argument. The + * output of #op_implicit is directly written into the output argument given + * to ThetaTimestepping. * *

Scalar data

* * Since the introduction of AnyData, ThetaTimestepping is able to - * communicate the current time step information through AnyData as - * well. Therefore, the AnyData objects handed as input to - * #op_explicit and #op_implicit contain two entries of type - * `const double*` named "Time" and "Timestep". Note - * that "Time" refers to the time at the beginning of the current - * step for #op_explicit and at the end for #op_implicit, + * communicate the current time step information through AnyData as well. + * Therefore, the AnyData objects handed as input to #op_explicit and + * #op_implicit contain two entries of type `const double*` named "Time" and + * "Timestep". Note that "Time" refers to the time at the beginning of the + * current step for #op_explicit and at the end for #op_implicit, * respectively. * *

Usage of ThetaTimestepping

* - * The use ThetaTimestepping is more complicated than for instance - * Newton, since the inner operators will usually need to access the - * TimeStepData. Thus, we have a circular dependency of information, - * and we include the following example for its use. It can be found - * in examples/doxygen/theta_timestepping.cc + * The use ThetaTimestepping is more complicated than for instance Newton, + * since the inner operators will usually need to access the TimeStepData. + * Thus, we have a circular dependency of information, and we include the + * following example for its use. It can be found in + * examples/doxygen/theta_timestepping.cc * * @dontinclude theta_timestepping.cc * - * First, we define the two operators used by ThetaTimestepping and - * call them Implicit and Explicit. They - * both share the public interface of Operator, and additionally - * provide storage for the matrices to be used and a pointer to - * TimestepData. Note that we do not use a SmartPointer here, since - * the TimestepData will be destroyed before the operator. + * First, we define the two operators used by ThetaTimestepping and call + * them Implicit and Explicit. They both share the + * public interface of Operator, and additionally provide storage for the + * matrices to be used and a pointer to TimestepData. Note that we do not + * use a SmartPointer here, since the TimestepData will be destroyed before + * the operator. * - * @skip class Explicit - * @until End of declarations + * @skip class Explicit @until End of declarations * - * These operators will be implemented after the main program. But let - * us look first at how they get used. First, let us define a matrix to be - * used for our system and also an OutputOperator in order to write - * the data of each timestep to a file. + * These operators will be implemented after the main program. But let us + * look first at how they get used. First, let us define a matrix to be used + * for our system and also an OutputOperator in order to write the data of + * each timestep to a file. * - * @skipline main - * @until out.initialize + * @skipline main @until out.initialize * - * Now we create objects for the implicit and explicit parts of the - * steps as well as the ThetaTimestepping itself. We initialize the - * timestepping with the output operator in order to be able to see - * the output in every step. + * Now we create objects for the implicit and explicit parts of the steps as + * well as the ThetaTimestepping itself. We initialize the timestepping with + * the output operator in order to be able to see the output in every step. * * @until set_output * - * The next step is providing the vectors to be used. value - * is filled with the initial value and is also the vector where the - * solution at each timestep will be. Because the interface of - * Operator has to be able to handle several vectors, we need to store - * it in an AnyData object. Since our problem has no additional - * parameters, the input AnyData object remains empty. + * The next step is providing the vectors to be used. value is + * filled with the initial value and is also the vector where the solution + * at each timestep will be. Because the interface of Operator has to be + * able to handle several vectors, we need to store it in an AnyData object. + * Since our problem has no additional parameters, the input AnyData object + * remains empty. * * @until add * - * Finally, we are ready to tell the solver, that we are starting at - * the initial timestep and run it. + * Finally, we are ready to tell the solver, that we are starting at the + * initial timestep and run it. * * @until } * - * First the constructor, which simply copies the system matrix into - * the member pointer for later use. + * First the constructor, which simply copies the system matrix into the + * member pointer for later use. * - * @skip Explicit:: - * @until } + * @skip Explicit:: @until } * * Now we need to study the application of the implicit and explicit - * operator. We assume that the pointer matrix points to - * the matrix created in the main program (the constructor did this - * for us). Here, we first get the time step size from the AnyData - * object that was provided as input. Then, if we are in the first - * step or if the timestep has changed, we fill the local matrix - * $m$, such that with the given matrix $M$, it becomes - * \f[ - * m = I - \Delta t M. - * \f] - * After we have worked off the notifications, we clear them, such - * that the matrix is only generated when necessary. - * - * @skipline void - * @until clear + * operator. We assume that the pointer matrix points to the + * matrix created in the main program (the constructor did this for us). + * Here, we first get the time step size from the AnyData object that was + * provided as input. Then, if we are in the first step or if the timestep + * has changed, we fill the local matrix $m$, such that with the given + * matrix $M$, it becomes \f[ m = I - \Delta t M. \f] After we have worked + * off the notifications, we clear them, such that the matrix is only + * generated when necessary. + * + * @skipline void @until clear * * Now we multiply the input vector with the new matrix and store on output. * - * @until } - * The code for the implicit operator is almost the same, except - * that we change the sign in front of the timestep and use the - * inverse of t he matrix. + * @until } The code for the implicit operator is almost the same, except + * that we change the sign in front of the timestep and use the inverse of t + * he matrix. * - * @until vmult - * @until } + * @until vmult @until } * @author Guido Kanschat * @date 2010 */ @@ -206,11 +191,9 @@ namespace Algorithms { public: /** - * Constructor, receiving the - * two operators stored in - * #op_explicit and #op_implicit. For - * their meening, see the - * description of those variables. + * Constructor, receiving the two operators stored in #op_explicit and + * #op_implicit. For their meening, see the description of those + * variables. */ ThetaTimestepping (Operator &op_explicit, Operator &op_implicit); @@ -218,13 +201,13 @@ namespace Algorithms /** * The timestepping scheme. * - * @param in is ignored by - * ThetaTimestepping, but is merged into the AnyData objects used - * as input for the operators #op_explicit and #op_implicit. + * @param in is ignored by ThetaTimestepping, but is merged into the + * AnyData objects used as input for the operators #op_explicit and + * #op_implicit. * - * @param out in its first argument must contain a pointer to a - * `VECTOR`, which contains the initial value when the operator is - * called. It contains the final value when the operator returns. + * @param out in its first argument must contain a pointer to a `VECTOR`, + * which contains the initial value when the operator is called. It + * contains the final value when the operator returns. */ virtual void operator() (AnyData &out, const AnyData &in); @@ -234,14 +217,13 @@ namespace Algorithms virtual void operator() (NamedData &out, const NamedData &in); /** - * Register an event triggered - * by an outer iteration. + * Register an event triggered by an outer iteration. */ virtual void notify(const Event &); /** - * Define an operator which will output the result in each - * step. Note that no output will be generated without this. + * Define an operator which will output the result in each step. Note that + * no output will be generated without this. */ void set_output(OutputOperator &output); @@ -260,8 +242,7 @@ namespace Algorithms */ void initialize (ParameterHandler ¶m) DEAL_II_DEPRECATED; /** - * The current time in the - * timestepping scheme. + * The current time in the timestepping scheme. */ double current_time() const; /** @@ -281,16 +262,16 @@ namespace Algorithms /** * The data handed to the #op_explicit time stepping operator. * - * The time in here is the time at the beginning of the current - * step, the time step is (1-#theta) times the actual time step. + * The time in here is the time at the beginning of the current step, the + * time step is (1-#theta) times the actual time step. */ const TimestepData &explicit_data() const; /** * The data handed to the #op_implicit time stepping operator. * - * The time in here is the time at the beginning of the current - * step, the time step is #theta times the actual time step. + * The time in here is the time at the beginning of the current step, the + * time step is #theta times the actual time step. */ const TimestepData &implicit_data() const; @@ -301,14 +282,14 @@ namespace Algorithms private: /** - * The object controlling the time step size and computing the new - * time in each step. + * The object controlling the time step size and computing the new time in + * each step. */ TimestepControl control; /** - * The control parameter theta in the range [0,1]. It - * defaults to 0.5. + * The control parameter theta in the range [0,1]. It defaults to + * 0.5. */ double vtheta; /** @@ -328,29 +309,26 @@ namespace Algorithms /** - * The operator computing the explicit part of the scheme. This - * will receive in its input data the value at the current time - * with name "Current time solution". It should obtain the current - * time and time step size from explicit_data(). + * The operator computing the explicit part of the scheme. This will + * receive in its input data the value at the current time with name + * "Current time solution". It should obtain the current time and time + * step size from explicit_data(). * - * Its return value is $ Mu+cF(u) $, where $u$ is the - * current state vector, $M$ the mass matrix, $F$ the - * operator in space and $c$ is the adjusted - * time step size $(1-\theta) \Delta t$. + * Its return value is $ Mu+cF(u) $, where $u$ is the current state + * vector, $M$ the mass matrix, $F$ the operator in space and $c$ is the + * adjusted time step size $(1-\theta) \Delta t$. */ SmartPointer, ThetaTimestepping > op_explicit; /** - * The operator solving the implicit part of the scheme. It will - * receive in its input data the vector "Previous - * time". Information on the timestep should be obtained from - * implicit_data(). + * The operator solving the implicit part of the scheme. It will receive + * in its input data the vector "Previous time". Information on the + * timestep should be obtained from implicit_data(). * - * Its return value is the solution u of Mu-cF(u)=f, - * where f is the dual space vector found in the "Previous - * time" entry of the input data, M the mass matrix, - * F the operator in space and c is the adjusted - * time step size $ \theta \Delta t$ + * Its return value is the solution u of Mu-cF(u)=f, where + * f is the dual space vector found in the "Previous time" entry of + * the input data, M the mass matrix, F the operator in + * space and c is the adjusted time step size $ \theta \Delta t$ */ SmartPointer, ThetaTimestepping > op_implicit; diff --git a/include/deal.II/algorithms/timestep_control.h b/include/deal.II/algorithms/timestep_control.h index 0944d96b86..3e669efa43 100644 --- a/include/deal.II/algorithms/timestep_control.h +++ b/include/deal.II/algorithms/timestep_control.h @@ -29,65 +29,50 @@ class ParameterHandler; namespace Algorithms { /** - * Control class for timestepping schemes. Its main task is - * determining the size of the next time step and the according point - * in the time interval. Additionally, it controls writing the - * solution to a file. + * Control class for timestepping schemes. Its main task is determining the + * size of the next time step and the according point in the time interval. + * Additionally, it controls writing the solution to a file. * * The size of the next time step is determined as follows: *
    *
  1. According to the strategy, the step size is tentatively added to the * current time. - *
  2. If the resulting time exceeds the final time of the interval, - * the step size is reduced in order to meet this time. - *
  3. If the resulting time is below the final time by just a - * fraction of the step size, the step size is increased in order to - * meet this time. + *
  4. If the resulting time exceeds the final time of the interval, the + * step size is reduced in order to meet this time. + *
  5. If the resulting time is below the final time by just a fraction of + * the step size, the step size is increased in order to meet this time. *
  6. The resulting step size is used from the current time. *
* - * The variable @p print_step can be used to control the amount of - * output generated by the timestepping scheme. + * The variable @p print_step can be used to control the amount of output + * generated by the timestepping scheme. */ class TimestepControl : public Subscriptor { public: /** - * The time stepping - * strategies. These are - * controlled by the value of + * The time stepping strategies. These are controlled by the value of * tolerance() and start_step(). */ enum Strategy { /** - * Choose a uniform time - * step size. The step size - * is determined by - * start_step(), - * tolerance() is ignored. + * Choose a uniform time step size. The step size is determined by + * start_step(), tolerance() is ignored. */ uniform, /** - * Start with the time step - * size given by - * start_step() and double it - * in every - * step. tolerance() is - * ignored. + * Start with the time step size given by start_step() and double it in + * every step. tolerance() is ignored. * - * This strategy is - * intended for - * pseudo-timestepping - * schemes computing a + * This strategy is intended for pseudo-timestepping schemes computing a * stationary limit. */ doubling }; /** - * Constructor setting default - * values + * Constructor setting default values */ TimestepControl (double start = 0., double final = 1., @@ -110,8 +95,8 @@ namespace Algorithms */ double start () const; /** - * The right end of the time interval. The control mechanism - * ensures that the final time step ends at this point. + * The right end of the time interval. The control mechanism ensures that + * the final time step ends at this point. */ double final () const; /** @@ -129,9 +114,8 @@ namespace Algorithms double now () const; /** - * Compute the size of the next step and return true if it differs - * from the current step size. Advance the current time by the new - * step size. + * Compute the size of the next step and return true if it differs from + * the current step size. Advance the current time by the new step size. */ bool advance (); @@ -164,8 +148,8 @@ namespace Algorithms void max_step (double); /** - * Set now() equal to start(). Initialize step() and print() to - * their initial values. + * Set now() equal to start(). Initialize step() and print() to their + * initial values. */ void restart (); /** @@ -187,9 +171,8 @@ namespace Algorithms double max_step_val; double min_step_val; /** - * The size of the current time - * step. This may differ from - * @p step_val, if we aimed at @p final_val. + * The size of the current time step. This may differ from @p step_val, if + * we aimed at @p final_val. */ double current_step_val; double step_val; diff --git a/include/deal.II/base/aligned_vector.h b/include/deal.II/base/aligned_vector.h index 40cb2411c2..534510b3b7 100644 --- a/include/deal.II/base/aligned_vector.h +++ b/include/deal.II/base/aligned_vector.h @@ -41,13 +41,13 @@ DEAL_II_NAMESPACE_OPEN * VectorizedArray and derived data types. It allocates memory aligned to * addresses of a vectorized data type (in order to avoid segmentation faults * when a variable of type VectorizedArray which the compiler assumes to be - * aligned to certain memory addresses does not actually follow these - * rules). This could also be achieved by proving std::vector with a - * user-defined allocator. On the other hand, writing an own small vector - * class lets us implement parallel copy and move operations with TBB, insert - * deal.II-style assertions, and cut some unnecessary functionality. Note that - * this vector is a bit more memory-consuming than std::vector because of - * alignment, so it is recommended to only use this vector on long vectors. + * aligned to certain memory addresses does not actually follow these rules). + * This could also be achieved by proving std::vector with a user-defined + * allocator. On the other hand, writing an own small vector class lets us + * implement parallel copy and move operations with TBB, insert deal.II-style + * assertions, and cut some unnecessary functionality. Note that this vector + * is a bit more memory-consuming than std::vector because of alignment, so it + * is recommended to only use this vector on long vectors. * * @p author Katharina Kormann, Martin Kronbichler, 2011 */ @@ -228,15 +228,15 @@ public: size_type memory_consumption () const; /** - * Write the data of this object to - * a stream for the purpose of serialization. + * Write the data of this object to a stream for the purpose of + * serialization. */ template void save (Archive &ar, const unsigned int version) const; /** - * Read the data of this object - * from a stream for the purpose of serialization. + * Read the data of this object from a stream for the purpose of + * serialization. */ template void load (Archive &ar, const unsigned int version); @@ -265,15 +265,15 @@ private: // ------------------------------- inline functions -------------------------- /** - * This namespace defines the copy and set functions used in - * AlignedVector. These functions operate in parallel when there are enough - * elements in the vector. + * This namespace defines the copy and set functions used in AlignedVector. + * These functions operate in parallel when there are enough elements in the + * vector. */ namespace internal { /** - * Move and class that actually issues the copy commands in - * AlignedVector. This class is based on the specialized for loop base class + * Move and class that actually issues the copy commands in AlignedVector. + * This class is based on the specialized for loop base class * ParallelForLoop in parallel.h whose purpose is the following: When * calling a parallel for loop on AlignedVector with apply_to_subranges, it * generates different code for every different argument we might choose (as diff --git a/include/deal.II/base/auto_derivative_function.h b/include/deal.II/base/auto_derivative_function.h index 676bcfd834..a9d6691866 100644 --- a/include/deal.II/base/auto_derivative_function.h +++ b/include/deal.II/base/auto_derivative_function.h @@ -23,15 +23,15 @@ DEAL_II_NAMESPACE_OPEN /** - * This class automatically computes the gradient of a function by - * employing numerical difference quotients. This only, if the user - * function does not provide the gradient function himself. + * This class automatically computes the gradient of a function by employing + * numerical difference quotients. This only, if the user function does not + * provide the gradient function himself. * - * The following example of an user defined function overloads and - * implements only the value() function but not the gradient() - * function. If the gradient() function is invoked then the gradient - * function implemented by the AutoDerivativeFunction is called, - * where the latter function imployes numerical difference quotients. + * The following example of an user defined function overloads and implements + * only the value() function but not the gradient() function. If the + * gradient() function is invoked then the gradient function implemented by + * the AutoDerivativeFunction is called, where the latter function imployes + * numerical difference quotients. * * @code * class UserFunction: public AutoDerivativeFunction @@ -45,31 +45,29 @@ DEAL_II_NAMESPACE_OPEN * Tensor<1,dim> grad=user_function.gradient(some_point); * @endcode * - * If the user overloads and implements also the gradient function, - * then, of course, the users gradient function is called. + * If the user overloads and implements also the gradient function, then, of + * course, the users gradient function is called. * - * Note, that the usage of the value() and gradient() functions - * explained above, also applies to the value_list() and - * gradient_list() functions as well as to the vector valued - * versions of these functions, see e.g. vector_value(), - * vector_gradient(), vector_value_list() and + * Note, that the usage of the value() and gradient() functions explained + * above, also applies to the value_list() and gradient_list() functions as + * well as to the vector valued versions of these functions, see e.g. + * vector_value(), vector_gradient(), vector_value_list() and * vector_gradient_list(). * * The gradient() and gradient_list() functions make use of the * Function::value() function. The vector_gradient() and - * vector_gradient_list() make use of the Function::vector_value() - * function. Make sure that the user defined function implements the - * value() function and the vector_value() function, respectively. + * vector_gradient_list() make use of the Function::vector_value() function. + * Make sure that the user defined function implements the value() function + * and the vector_value() function, respectively. * * Furthermore note, that an object of this class does not represent - * the derivative of a function, like FunctionDerivative, that - * gives a directional derivate by calling the value() function. In - * fact, this class (the AutoDerivativeFunction class) can - * substitute the Function class as base class for user defined - * classes. This class implements the gradient() functions for - * automatic computation of numerical difference quotients and serves - * as intermediate class between the base Function class and the - * user defined function class. + * the derivative of a function, like FunctionDerivative, that gives a + * directional derivate by calling the value() function. In fact, this class + * (the AutoDerivativeFunction class) can substitute the Function class as + * base class for user defined classes. This class implements the gradient() + * functions for automatic computation of numerical difference quotients and + * serves as intermediate class between the base Function class and the user + * defined function class. * * @ingroup functions * @author Ralf Hartmann, 2001 @@ -85,8 +83,7 @@ public: enum DifferenceFormula { /** - * The symmetric Euler - * formula of second order: + * The symmetric Euler formula of second order: * @f[ * u'(t) \approx * \frac{u(t+h) - @@ -95,8 +92,7 @@ public: */ Euler, /** - * The upwind Euler - * formula of first order: + * The upwind Euler formula of first order: * @f[ * u'(t) \approx * \frac{u(t) - @@ -116,101 +112,70 @@ public: }; /** - * Constructor. Takes the - * difference step size - * h. It's within the user's - * responsibility to choose an - * appropriate value here. h - * should be chosen taking into - * account the absolute value as - * well as the amount of local - * variation of the function. - * Setting h=1e-6 might be a - * good choice for functions with - * an absolute value of about 1, - * that furthermore does not vary - * to much. + * Constructor. Takes the difference step size h. It's within the + * user's responsibility to choose an appropriate value here. h + * should be chosen taking into account the absolute value as well as the + * amount of local variation of the function. Setting h=1e-6 might + * be a good choice for functions with an absolute value of about 1, that + * furthermore does not vary to much. * - * h can be changed later - * using the set_h() function. + * h can be changed later using the set_h() function. * - * Sets DifferenceFormula - * formula to the default - * Euler formula of the - * set_formula() - * function. Change this preset - * formula by calling the - * set_formula() function. + * Sets DifferenceFormula formula to the default Euler + * formula of the set_formula() function. Change this preset formula by + * calling the set_formula() function. */ AutoDerivativeFunction (const double h, const unsigned int n_components = 1, const double initial_time = 0.0); /** - * Virtual destructor; absolutely - * necessary in this case. + * Virtual destructor; absolutely necessary in this case. */ virtual ~AutoDerivativeFunction (); /** - * Choose the difference formula. - * See the enum #DifferenceFormula - * for available choices. + * Choose the difference formula. See the enum #DifferenceFormula for + * available choices. */ void set_formula (const DifferenceFormula formula = Euler); /** - * Takes the difference step size - * h. It's within the user's - * responsibility to choose an - * appropriate value here. h - * should be chosen taking into - * account the absolute value of - * as well as the amount of local - * variation of the function. - * Setting h=1e-6 might be a - * good choice for functions with - * an absolute value of about 1, - * that furthermore does not vary - * to much. + * Takes the difference step size h. It's within the user's + * responsibility to choose an appropriate value here. h should be + * chosen taking into account the absolute value of as well as the amount of + * local variation of the function. Setting h=1e-6 might be a good + * choice for functions with an absolute value of about 1, that furthermore + * does not vary to much. */ void set_h (const double h); /** - * Return the gradient of the - * specified component of the - * function at the given point. + * Return the gradient of the specified component of the function at the + * given point. * - * Computes numerical difference - * quotients using the preset + * Computes numerical difference quotients using the preset * #DifferenceFormula. */ virtual Tensor<1,dim> gradient (const Point &p, const unsigned int component = 0) const; /** - * Return the gradient of all - * components of the - * function at the given point. + * Return the gradient of all components of the function at the given point. * - * Computes numerical difference - * quotients using the preset + * Computes numerical difference quotients using the preset * #DifferenceFormula. */ virtual void vector_gradient (const Point &p, std::vector > &gradients) const; /** - * Set gradients to the - * gradients of the specified - * component of the function at - * the points. It is assumed - * that gradients already has the - * right size, i.e. the same - * size as the points array. + * Set gradients to the gradients of the specified component of the + * function at the points. It is assumed that gradients + * already has the right size, i.e. the same size as the points + * array. * - * Computes numerical difference - * quotients using the preset + * Computes numerical difference quotients using the preset * #DifferenceFormula. */ virtual void gradient_list (const std::vector > &points, @@ -218,30 +183,22 @@ public: const unsigned int component = 0) const; /** - * Set gradients to the gradients of - * the function at the points, - * for all components. - * It is assumed that gradients - * already has the right size, i.e. - * the same size as the points array. + * Set gradients to the gradients of the function at the + * points, for all components. It is assumed that + * gradients already has the right size, i.e. the same size as the + * points array. * - * The outer loop over - * gradients is over the points - * in the list, the inner loop - * over the different components - * of the function. + * The outer loop over gradients is over the points in the list, + * the inner loop over the different components of the function. * - * Computes numerical difference - * quotients using the preset + * Computes numerical difference quotients using the preset * #DifferenceFormula. */ virtual void vector_gradient_list (const std::vector > &points, std::vector > > &gradients) const; /** - * Returns a - * #DifferenceFormula of the - * order ord at minimum. + * Returns a #DifferenceFormula of the order ord at minimum. */ static DifferenceFormula @@ -255,21 +212,17 @@ public: private: /** - * Step size of the difference - * formula. Set by the set_h() - * function. + * Step size of the difference formula. Set by the set_h() function. */ double h; /** - * Includes the unit vectors - * scaled by h. + * Includes the unit vectors scaled by h. */ std::vector > ht; /** - * Difference formula. Set by the - * set_formula() function. + * Difference formula. Set by the set_formula() function. */ DifferenceFormula formula; }; diff --git a/include/deal.II/base/conditional_ostream.h b/include/deal.II/base/conditional_ostream.h index 63242c22dc..38b1205556 100644 --- a/include/deal.II/base/conditional_ostream.h +++ b/include/deal.II/base/conditional_ostream.h @@ -25,12 +25,10 @@ DEAL_II_NAMESPACE_OPEN /** * A class that allows printing to an output stream, e.g. @p std::cout, - * depending on the ConditionalOStream object being active (default) - * or not. The condition of this object can be changed by - * set_condition() and in the constructor. This class is used in the - * step-17, step-18, step-32, - * step-33, and step-35 - * tutorial programs. + * depending on the ConditionalOStream object being active (default) or not. + * The condition of this object can be changed by set_condition() and in the + * constructor. This class is used in the step-17, step-18, step-32, step-33, + * and step-35 tutorial programs. * * This class is mostly useful in parallel computations. Ordinarily, you would * use @p std::cout to print messages like what the program is presently @@ -38,8 +36,8 @@ DEAL_II_NAMESPACE_OPEN * parallel programs, this means that each of the MPI processes write to the * screen, which yields many repetitions of the same text. To avoid it, one * would have to have a designated process, say the one with MPI process - * number zero, do the output, and guard each write statement with an - * if-condition. This becomes cumbersome and clutters up the code. Rather than + * number zero, do the output, and guard each write statement with an if- + * condition. This becomes cumbersome and clutters up the code. Rather than * doing so, the present class can be used: objects of its type act just like * a standard output stream, but they only print something based on a * condition that can be set to, for example, mpi_process==0, so that @@ -63,16 +61,16 @@ DEAL_II_NAMESPACE_OPEN * pout << "done" << std::endl; * @endcode * - * Here, `Reading parameter file on process xy' is printed by each - * process separately. In contrast to that, `Solving ...' and `done' - * is printed to standard output only once, namely by process 0. + * Here, `Reading parameter file on process xy' is printed by each process + * separately. In contrast to that, `Solving ...' and `done' is printed to + * standard output only once, namely by process 0. * * This class is not derived from ostream. Therefore * @code * system_matrix.print_formatted(pout); * @endcode - * is not possible. Instead use the is_active() function for a - * work-around: + * is not possible. Instead use the is_active() function for a work- + * around: * * @code * if (pout.is_active()) @@ -86,24 +84,17 @@ class ConditionalOStream { public: /** - * Constructor. Set the stream to which - * we want to write, and the condition - * based on which writes are actually - * forwarded. Per default the condition + * Constructor. Set the stream to which we want to write, and the condition + * based on which writes are actually forwarded. Per default the condition * of an object is active. */ ConditionalOStream (std::ostream &stream, const bool active = true); /** - * Depending on the - * active flag set the - * condition of this stream to - * active (true) or non-active - * (false). An object of this - * class prints to cout - * if and only if its condition - * is active. + * Depending on the active flag set the condition of this stream to + * active (true) or non-active (false). An object of this class prints to + * cout if and only if its condition is active. */ void set_condition (const bool active); @@ -113,50 +104,39 @@ public: bool is_active() const; /** - * Return a reference to the stream - * currently in use. + * Return a reference to the stream currently in use. */ std::ostream &get_stream () const; /** - * Output a constant something through - * this stream. This function must be @p - * const so that member objects of this - * type can also be used from @p const - * member functions of the surrounding - * class. + * Output a constant something through this stream. This function must be @p + * const so that member objects of this type can also be used from @p const + * member functions of the surrounding class. */ template const ConditionalOStream & operator << (const T &t) const; /** - * Treat ostream manipulators. This - * function must be @p const so that - * member objects of this type can also - * be used from @p const member functions - * of the surrounding class. + * Treat ostream manipulators. This function must be @p const so that member + * objects of this type can also be used from @p const member functions of + * the surrounding class. * - * Note that compilers want to see this - * treated differently from the general - * template above since functions like @p - * std::endl are actually overloaded and - * can't be bound directly to a template - * type. + * Note that compilers want to see this treated differently from the general + * template above since functions like @p std::endl are actually overloaded + * and can't be bound directly to a template type. */ const ConditionalOStream & operator<< (std::ostream& (*p) (std::ostream &)) const; private: /** - * Reference to the stream we - * want to write to. + * Reference to the stream we want to write to. */ std::ostream &output_stream; /** - * Stores the actual condition - * the object is in. + * Stores the actual condition the object is in. */ bool active_flag; }; diff --git a/include/deal.II/base/convergence_table.h b/include/deal.II/base/convergence_table.h index d4be5718b1..dd9a13e194 100644 --- a/include/deal.II/base/convergence_table.h +++ b/include/deal.II/base/convergence_table.h @@ -24,15 +24,15 @@ DEAL_II_NAMESPACE_OPEN /** - * The ConvergenceTable class is an application to the TableHandler - * class and stores some convergence data, such as residuals of the - * cg-method, or some evaluated L2-errors of - * discrete solutions, etc, and evaluates convergence rates or orders. + * The ConvergenceTable class is an application to the TableHandler class and + * stores some convergence data, such as residuals of the cg-method, or some + * evaluated L2-errors of discrete solutions, etc, and + * evaluates convergence rates or orders. * - * The already implemented #RateMode's are #reduction_rate, - * where the convergence rate is the quotient of two following rows, and - * #reduction_rate_log2, that evaluates the order of convergence. - * These standard evaluations are useful for global refinement, for local refinement + * The already implemented #RateMode's are #reduction_rate, where the + * convergence rate is the quotient of two following rows, and + * #reduction_rate_log2, that evaluates the order of convergence. These + * standard evaluations are useful for global refinement, for local refinement * this may not be an appropriate method, as the convergence rates should be * set in relation to the number of cells or the number of DoFs. The * implementations of these non-standard methods is left to a user. @@ -43,14 +43,14 @@ DEAL_II_NAMESPACE_OPEN * functions evaluate_convergence_rates() and evaluate_all_convergence_rates() * may be called. * - * There are two possibilities of how to evaluate the convergence rates of multiple - * columns in the same RateMode. + * There are two possibilities of how to evaluate the convergence rates of + * multiple columns in the same RateMode. *
    *
  1. call evaluate_convergence_rates() for all wanted columns - *
  2. call omit_column_from_convergence_rate_evaluation() for all - * columns for which this evaluation is not desired and then - * evaluate_all_convergence_rates() to evaluate the convergence rates of all columns - * that have not been flagged for omission. + *
  3. call omit_column_from_convergence_rate_evaluation() for all columns + * for which this evaluation is not desired and then + * evaluate_all_convergence_rates() to evaluate the convergence rates of all + * columns that have not been flagged for omission. *
* * A detailed discussion of this class can also be found in the step-7 and @@ -102,28 +102,26 @@ public: * $1/h$, remember to set the dimension to 1 also when working in 3D to get * correct rates. * - * The new rate column and the data column will be merged to a - * supercolumn. The tex caption of the supercolumn will be (by default) the - * same as the one of the data column. This may be changed by using the + * The new rate column and the data column will be merged to a supercolumn. + * The tex caption of the supercolumn will be (by default) the same as the + * one of the data column. This may be changed by using the * set_tex_supercaption (...) function of the base class * TableHandler. * * This method behaves in the following way: * - * If RateMode is reduction_rate, then the computed output is - * $ \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, $ - * where $k$ is the reference column (no dimension dependence!). + * If RateMode is reduction_rate, then the computed output is $ + * \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, $ where $k$ is the reference column (no + * dimension dependence!). * - * If RateMode is reduction_rate_log2, then the computed output is - * $ - * dim \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|} - * $. + * If RateMode is reduction_rate_log2, then the computed output is $ dim + * \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|} $. * * This is useful, for example, if we use as reference key the number of * degrees of freedom or better, the number of cells. Assuming that the * error is proportional to $ C (1/\sqrt{k})^r $ in 2D, then this method - * will produce the rate $r$ as a result. For general dimension, as described - * by the last parameter of this function, the formula needs to be + * will produce the rate $r$ as a result. For general dimension, as + * described by the last parameter of this function, the formula needs to be * $ C (1/\sqrt[dim]{k})^r $. * * @note Since this function adds columns to the table after several rows @@ -144,9 +142,9 @@ public: * types of the table entries of the data column is a number, i.e. double, * float, (unsigned) int, and so on. * - * The new rate column and the data column will be merged to a - * supercolumn. The tex caption of the supercolumn will be (by default) the - * same as the one of the data column. This may be changed by using the + * The new rate column and the data column will be merged to a supercolumn. + * The tex caption of the supercolumn will be (by default) the same as the + * one of the data column. This may be changed by using the * set_tex_supercaption() function of the base class TableHandler. * * @note Since this function adds columns to the table after several rows @@ -177,10 +175,10 @@ public: * convergence rate for almost all columns of a table without calling * evaluate_convergence_rates() for each column separately. * - * Example: - * Columns like n cells or n dofs columns may be wanted to - * be omitted in the evaluation of the convergence rates. Hence they should - * omitted by calling the omit_column_from_convergence_rate_evaluation(). + * Example: Columns like n cells or n dofs columns may be + * wanted to be omitted in the evaluation of the convergence rates. Hence + * they should omitted by calling the + * omit_column_from_convergence_rate_evaluation(). */ void evaluate_all_convergence_rates(const std::string &reference_column_key, @@ -194,16 +192,18 @@ public: * convergence rate for almost all columns of a table without calling * evaluate_convergence_rates() for each column separately. * - * Example: - * Columns like n cells or n dofs columns may be wanted to - * be omitted in the evaluation of the convergence rates. Hence they should - * omitted by calling the omit_column_from_convergence_rate_evaluation(). + * Example: Columns like n cells or n dofs columns may be + * wanted to be omitted in the evaluation of the convergence rates. Hence + * they should omitted by calling the + * omit_column_from_convergence_rate_evaluation(). */ void evaluate_all_convergence_rates(const RateMode rate_mode); - /** @addtogroup Exceptions - * @{ */ + /** + * @addtogroup Exceptions + * @{ + */ /** * Exception diff --git a/include/deal.II/base/data_out_base.h b/include/deal.II/base/data_out_base.h index aec159d46e..bffe08dac2 100644 --- a/include/deal.II/base/data_out_base.h +++ b/include/deal.II/base/data_out_base.h @@ -45,110 +45,104 @@ class ParameterHandler; class XDMFEntry; /** - * This is a base class for output of data on meshes of very general - * form. Output data is expected as a set of patches and - * written to the output stream in the format expected by the - * visualization tool. For a list of output formats, check the - * enumeration #OutputFormat. For each format listed there, this class - * contains a function write_format, writing the - * output. Refer to the documentation of those functions for details - * on a certain format. + * This is a base class for output of data on meshes of very general form. + * Output data is expected as a set of patches and written to the + * output stream in the format expected by the visualization tool. For a list + * of output formats, check the enumeration #OutputFormat. For each format + * listed there, this class contains a function write_format, writing + * the output. Refer to the documentation of those functions for details on a + * certain format. * *

Structure of the output data

* - * Data is not written with the deal.II mesh structure. Instead, it - * relies on a set of patches created by a derived class (for - * example the DataOut, DataOutStack, DataOutFaces, DataOutRotation, - * or MatrixOut classes). Each Patch describes a single logical cell - * of a mesh, possibly subdivided a number of times to represent - * higher order polynomials defined on this cell. To this end, a patch - * consists of a dim-dimensional regular grid with the same - * number of grid points in each direction. In the simplest case it - * may consist of the corner points of a single mesh cell. For each - * point of this local grid, the Patch contains an arbitrary number of - * data values, though the number of data sets must be the same for - * each point on each patch. + * Data is not written with the deal.II mesh structure. Instead, it relies on + * a set of patches created by a derived class (for example the + * DataOut, DataOutStack, DataOutFaces, DataOutRotation, or MatrixOut + * classes). Each Patch describes a single logical cell of a mesh, possibly + * subdivided a number of times to represent higher order polynomials defined + * on this cell. To this end, a patch consists of a dim-dimensional + * regular grid with the same number of grid points in each direction. In the + * simplest case it may consist of the corner points of a single mesh cell. + * For each point of this local grid, the Patch contains an arbitrary number + * of data values, though the number of data sets must be the same for each + * point on each patch. * - * By offering this interface to the different output formats, it is simple - * to extend this class to new formats without depending on such things - * as actual triangulations and handling of data vectors. These things shall - * be provided by derived class which have a user callable interface then. + * By offering this interface to the different output formats, it is simple to + * extend this class to new formats without depending on such things as actual + * triangulations and handling of data vectors. These things shall be provided + * by derived class which have a user callable interface then. * - * Inside each patch, the data is organized in the usual - * lexicographical order, x running fastest, then y and - * z. Nodes are stored in this order and cells as well. Each - * cell in 3D is stored such that the front face is in the - * xz-plane. In order to enhance intellegibility of this - * concept, the following two sections are kept from a previous - * version of this documentation. + * Inside each patch, the data is organized in the usual lexicographical + * order, x running fastest, then y and z. Nodes are + * stored in this order and cells as well. Each cell in 3D is stored such that + * the front face is in the xz-plane. In order to enhance + * intellegibility of this concept, the following two sections are kept from a + * previous version of this documentation. * * *

Patches

* * Grids can be thought of as a collection of cells; if you want to write out - * data on such a grid, you can do so by writing them one cell at a time. - * The functions in this class therefore take a list of objects describing the + * data on such a grid, you can do so by writing them one cell at a time. The + * functions in this class therefore take a list of objects describing the * data on one cell each. This data for each cell usually consists of a list * of vertices for this cell, and a list of data values (for example solution * data, error information, etc) at each of these vertices. * * In some cases, this interface to a cell is too restricted, however. For - * example, you may have higher order elements and printing the values at - * the vertices only is not enough. For this reason, we not only provide - * writing the data on the vertices only, but the data is organizes as a - * tensor product grid on each cell. The parameter n_subdivision, which is + * example, you may have higher order elements and printing the values at the + * vertices only is not enough. For this reason, we not only provide writing + * the data on the vertices only, but the data is organizes as a tensor + * product grid on each cell. The parameter n_subdivision, which is * given for each patch separately, denotes how often the cell is to be - * divided for output; for example, n_subdivisions==1 yields no subdivision - * of the cell, n_subdivisions==2 will produce a grid of 3 times 3 points - * in two spatial dimensions and 3 times 3 times 3 points in three dimensions, - * n_subdivisions==3 will yield 4 times 4 (times 4) points, etc. The actual - * location of these points on the patch will be computed by a multilinear - * transformation from the vertices given for this patch. - - * For cells at the boundary, a mapping might be used to calculate the position - * of the inner points. In that case the coordinates are stored inside the - * Patch, as they cannot be easily recovered otherwise. + * divided for output; for example, n_subdivisions==1 yields no + * subdivision of the cell, n_subdivisions==2 will produce a grid of + * 3 times 3 points in two spatial dimensions and 3 times 3 times 3 points in + * three dimensions, n_subdivisions==3 will yield 4 times 4 (times 4) + * points, etc. The actual location of these points on the patch will be + * computed by a multilinear transformation from the vertices given for this + * patch. For cells at the boundary, a mapping might be used to calculate the + * position of the inner points. In that case the coordinates are stored + * inside the Patch, as they cannot be easily recovered otherwise. * - * Given these comments, the actual data to be printed on this patch of - * points consists of several data sets each of which has a value at each - * of the patch points. For example with n_subdivisions==2 in two space - * dimensions, each data set has to provide nine values, and since the - * patch is to be printed as a tensor product (or its transformation to the - * real space cell), its values are to be ordered like - * (x0,y0) (x0,y1) (x0,y2) (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2), - * i.e. the z-coordinate runs fastest, then the y-coordinate, then x (if there - * are that many space directions). + * Given these comments, the actual data to be printed on this patch of points + * consists of several data sets each of which has a value at each of the + * patch points. For example with n_subdivisions==2 in two space + * dimensions, each data set has to provide nine values, and since the patch + * is to be printed as a tensor product (or its transformation to the real + * space cell), its values are to be ordered like (x0,y0) (x0,y1) (x0,y2) + * (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2), i.e. the z-coordinate + * runs fastest, then the y-coordinate, then x (if there are that many space + * directions). * * *

Generalized patches

* - * In general, the patches as explained above might be too - * restricted. For example, one might want to draw only the outer - * faces of a domain in a three-dimensional computation, if one is not - * interested in what happens inside. Then, the objects that should be - * drawn are two-dimensional in a three-dimensional world. The - * Patch class and associated output functions handle these - * cases. The Patch class therefore takes two template parameters, - * the first, named dim denoting the dimension of the object (in - * the above example, this would be two), while the second, named - * spacedim, denotes the dimension of the embedding space (this - * would be three). The corner points of a patch have the dimension of - * the space, while their number is determined by the dimension of the - * patch. By default, the second template parameter has the same value - * as the first, which would correspond to outputting a cell, rather - * than a face or something else. + * In general, the patches as explained above might be too restricted. For + * example, one might want to draw only the outer faces of a domain in a + * three-dimensional computation, if one is not interested in what happens + * inside. Then, the objects that should be drawn are two-dimensional in a + * three-dimensional world. The Patch class and associated output functions + * handle these cases. The Patch class therefore takes two template + * parameters, the first, named dim denoting the dimension of the + * object (in the above example, this would be two), while the second, named + * spacedim, denotes the dimension of the embedding space (this would + * be three). The corner points of a patch have the dimension of the space, + * while their number is determined by the dimension of the patch. By default, + * the second template parameter has the same value as the first, which would + * correspond to outputting a cell, rather than a face or something else. * *

DataOutBaseInterface

* * The members of this namespace are not usually called from user code - * directly. Rather, classes that use the functions declared here - * are typically derived from DataOutInterface. + * directly. Rather, classes that use the functions declared here are + * typically derived from DataOutInterface. * * The interface of this class basically consists of the declaration of a data * type describing a patch and a bunch of functions taking a list of patches * and writing them in one format or other to the stream. It is in the - * responsibility of the derived classes to provide this list of patches. - * In addition to the list of patches, a name for each data set may be given. + * responsibility of the derived classes to provide this list of patches. In + * addition to the list of patches, a name for each data set may be given. * * *

Querying interface

@@ -166,15 +160,15 @@ class XDMFEntry; *

Output parameters

* * All functions take a parameter which is a structure of type - * XFlags, where X is the name of the output - * format. To find out what flags are presently supported, read the - * documentation of the different structures. + * XFlags, where X is the name of the output format. To find + * out what flags are presently supported, read the documentation of the + * different structures. * * Note that usually the output formats used for scientific visualization - * programs have no or very few parameters (apart from some compatibility flags) - * because there the actual appearance of output is determined using the - * visualization program and the files produced by this class store more or less - * only raw data. + * programs have no or very few parameters (apart from some compatibility + * flags) because there the actual appearance of output is determined using + * the visualization program and the files produced by this class store more + * or less only raw data. * * The direct output formats, like Postscript or Povray need to be given a lot * more parameters, though, since there the output file has to contain all @@ -182,26 +176,26 @@ class XDMFEntry; * *

Writing backends

* - * An abstraction layer has been introduced to facilitate coding - * backends for additional visualization tools. It is applicable for - * data formats separating the information into a field of vertices, a - * field of connection information for the grid cells and data fields. + * An abstraction layer has been introduced to facilitate coding backends for + * additional visualization tools. It is applicable for data formats + * separating the information into a field of vertices, a field of connection + * information for the grid cells and data fields. * * For each of these fields, output functions are implemented, namely - * write_nodes(), write_cells() and write_data(). In order to use - * these functions, a format specific output stream must be written, - * following the examples of DXStream, GmvStream, VtkStream and so on, - * implemented in the .cc file. + * write_nodes(), write_cells() and write_data(). In order to use these + * functions, a format specific output stream must be written, following the + * examples of DXStream, GmvStream, VtkStream and so on, implemented in the + * .cc file. * - * In this framework, the implementation of a new output format is - * reduced to writing the section headers and the new output stream - * class for writing a single mesh object. + * In this framework, the implementation of a new output format is reduced to + * writing the section headers and the new output stream class for writing a + * single mesh object. * *

Credits

*
    * - *
  • EPS output based on an earlier implementation by Stefan Nauber - * for the old DataOut class + *
  • EPS output based on an earlier implementation by Stefan Nauber for the + * old DataOut class * *
  • Povray output by Thomas Richter * @@ -210,7 +204,8 @@ class XDMFEntry; *
* * @ingroup output - * @author Wolfgang Bangerth, Guido Kanschat 1999, 2000, 2001, 2002, 2005, 2006. + * @author Wolfgang Bangerth, Guido Kanschat 1999, 2000, 2001, 2002, 2005, + * 2006. */ namespace DataOutBase { @@ -221,18 +216,18 @@ namespace DataOutBase * A patch consists of the following data: *
    *
  • the corner #vertices, - *
  • the number #n_subdivisions of the number of cells the Patch - * has in each space direction, - *
  • the #data attached to each vertex, in the usual - * lexicographic ordering, + *
  • the number #n_subdivisions of the number of cells the Patch has in + * each space direction, + *
  • the #data attached to each vertex, in the usual lexicographic + * ordering, *
  • Information on #neighbors. *
* * See the general documentation of the DataOutBase class for more - * information on its contents and purposes. In the case of two - * dimensions, the next picture ist an example of - * n_subdivision = 4 because the number of (sub)cells - * within each patch is equal to 2dim. + * information on its contents and purposes. In the case of two dimensions, + * the next picture ist an example of n_subdivision = 4 because the + * number of (sub)cells within each patch is equal to + * 2dim. * * @ingroup output * @@ -247,18 +242,18 @@ namespace DataOutBase static const unsigned int space_dim=spacedim; /** - * Corner points of a patch. Inner points are computed by a - * multilinear transform of the unit cell to the cell specified by - * these corner points. The order of points is the same as for - * cells in the triangulation. + * Corner points of a patch. Inner points are computed by a multilinear + * transform of the unit cell to the cell specified by these corner + * points. The order of points is the same as for cells in the + * triangulation. */ Point vertices[GeometryInfo::vertices_per_cell]; /** - * Numbers of neighbors of a patch. OpenDX format requires - * neighbor information for advanced output. Here the neighborship - * relationship of patches is stored. During output, this must be - * transformed into neighborship of sub-grid cells. + * Numbers of neighbors of a patch. OpenDX format requires neighbor + * information for advanced output. Here the neighborship relationship of + * patches is stored. During output, this must be transformed into + * neighborship of sub-grid cells. */ unsigned int neighbors[dim > 0 ? @@ -267,37 +262,37 @@ namespace DataOutBase 1]; /** - * Number of this patch. Since we are not sure patches are handled - * in the same order, always, we better store this. + * Number of this patch. Since we are not sure patches are handled in the + * same order, always, we better store this. */ unsigned int patch_index; /** - * Number of subdivisions with which this patch is to be - * written. 1 means no subdivision, 2 means - * bisection, 3 trisection, etc. + * Number of subdivisions with which this patch is to be written. + * 1 means no subdivision, 2 means bisection, 3 + * trisection, etc. */ unsigned int n_subdivisions; /** - * Data vectors. The format is as follows: data(i,.) - * denotes the data belonging to the ith data - * vector. data.n() therefore equals the number of output - * points; this number is (subdivisions+1)^{dim}. - * data.m() equals the number of data vectors. + * Data vectors. The format is as follows: data(i,.) denotes the + * data belonging to the ith data vector. data.n() + * therefore equals the number of output points; this number is + * (subdivisions+1)^{dim}. data.m() equals the number of + * data vectors. * - * Within each column, data(.,j) are the data values at - * the output point j, where j denotes the usual - * lexicographic ordering in deal.II. This is also the order of - * points as provided by the QIterated class when used - * with the QTrapez class as subquadrature. + * Within each column, data(.,j) are the data values at the + * output point j, where j denotes the usual + * lexicographic ordering in deal.II. This is also the order of points as + * provided by the QIterated class when used with the + * QTrapez class as subquadrature. * - * Since the number of data vectors is usually the same for all - * patches to be printed, data.size() should yield the - * same value for all patches provided. The exception are patches - * for which points_are_available are set, where the actual - * coordinates of the point are appended to the 'data' field, see - * the documentation of the points_are_available flag. + * Since the number of data vectors is usually the same for all patches to + * be printed, data.size() should yield the same value for all + * patches provided. The exception are patches for which + * points_are_available are set, where the actual coordinates of the point + * are appended to the 'data' field, see the documentation of the + * points_are_available flag. */ Table<2,float> data; @@ -322,18 +317,17 @@ namespace DataOutBase Patch (); /** - * Compare the present patch for equality with another one. This - * is used in a few of the automated tests in our testsuite. + * Compare the present patch for equality with another one. This is used + * in a few of the automated tests in our testsuite. */ bool operator == (const Patch &patch) const; /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; @@ -341,8 +335,10 @@ namespace DataOutBase * Value to be used if this patch has no neighbor on one side. */ static const unsigned int no_neighbor = numbers::invalid_unsigned_int; - /** @addtogroup Exceptions - * @{ */ + /** + * @addtogroup Exceptions + * @{ + */ /** * Exception @@ -363,10 +359,9 @@ namespace DataOutBase struct DXFlags { /** - * Write neighbor information. This information is necessary for - * instance, if OpenDX is supposed to compute integral curves - * (streamlines). If it is not present, streamlines end at cell - * boundaries. + * Write neighbor information. This information is necessary for instance, + * if OpenDX is supposed to compute integral curves (streamlines). If it + * is not present, streamlines end at cell boundaries. */ bool write_neighbors; /** @@ -384,8 +379,8 @@ namespace DataOutBase bool data_binary; /** - * Write binary coordinate vectors as double (64 bit) numbers - * instead of float (32 bit). + * Write binary coordinate vectors as double (64 bit) numbers instead of + * float (32 bit). */ bool data_double; @@ -398,23 +393,22 @@ namespace DataOutBase const bool data_binary = false); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and set - * the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm); /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. + * Determine an estimate for the memory consumption (in bytes) of this + * object. */ std::size_t memory_consumption () const; }; @@ -427,11 +421,11 @@ namespace DataOutBase struct UcdFlags { /** - * Write a comment at the beginning of the file stating the date - * of creation and some other data. While this is supported by - * the UCD format and AVS, some other programs get confused by - * this, so the default is to not write a preamble. However, a - * preamble can be written using this flag. + * Write a comment at the beginning of the file stating the date of + * creation and some other data. While this is supported by the UCD + * format and AVS, some other programs get confused by this, so the + * default is to not write a preamble. However, a preamble can be written + * using this flag. * * Default: false. */ @@ -443,34 +437,32 @@ namespace DataOutBase UcdFlags (const bool write_preamble = false); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and - * set the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm); /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; /** - * Flags controlling the details of output in Gnuplot format. At - * present no flags are implemented. + * Flags controlling the details of output in Gnuplot format. At present no + * flags are implemented. * * @ingroup output */ @@ -479,8 +471,8 @@ namespace DataOutBase private: /** * Dummy entry to suppress compiler warnings when copying an empty - * structure. Remove this member when adding the first flag to - * this structure (and remove the private as well). + * structure. Remove this member when adding the first flag to this + * structure (and remove the private as well). */ int dummy; @@ -491,34 +483,32 @@ namespace DataOutBase GnuplotFlags (); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and set - * the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm) const; /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; /** - * Flags controlling the details of output in Povray format. Several - * flags are implemented, see their respective documentation. + * Flags controlling the details of output in Povray format. Several flags + * are implemented, see their respective documentation. * * @ingroup output */ @@ -539,8 +529,8 @@ namespace DataOutBase bool bicubic_patch; /** - * include external "data.inc" with camera, light and texture - * definition for the scene. + * include external "data.inc" with camera, light and texture definition + * for the scene. * * default = false */ @@ -554,59 +544,56 @@ namespace DataOutBase const bool external_data = false); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and - * set the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm); /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; /** - * Flags controlling the details of output in encapsulated - * postscript format. + * Flags controlling the details of output in encapsulated postscript + * format. * * @ingroup output */ struct EpsFlags { /** - * This denotes the number of the data vector which shall be used - * for generating the height information. By default, the first - * data vector is taken, i.e. height_vector==0, if there - * is any data vector. If there is no data vector, no height - * information is generated. + * This denotes the number of the data vector which shall be used for + * generating the height information. By default, the first data vector is + * taken, i.e. height_vector==0, if there is any data vector. If + * there is no data vector, no height information is generated. */ unsigned int height_vector; /** - * Number of the vector which is to be taken to colorize cells. - * The same applies as for #height_vector. + * Number of the vector which is to be taken to colorize cells. The same + * applies as for #height_vector. */ unsigned int color_vector; /** - * Enum denoting the possibilities whether the scaling should be - * done such that the given size equals the width or the - * height of the resulting picture. + * Enum denoting the possibilities whether the scaling should be done such + * that the given size equals the width or the height of the + * resulting picture. */ enum SizeType { @@ -622,9 +609,9 @@ namespace DataOutBase SizeType size_type; /** - * Width or height of the output as given in postscript units This - * usually is given by the strange unit 1/72 inch. Whether this is - * height or width is specified by the flag size_type. + * Width or height of the output as given in postscript units This usually + * is given by the strange unit 1/72 inch. Whether this is height or width + * is specified by the flag size_type. * * Default is 300, which represents a size of roughly 10 cm. */ @@ -643,13 +630,13 @@ namespace DataOutBase double azimut_angle; /** - * Angle by which the viewers position projected onto the - * x-y-plane is rotated around the z-axis, in positive sense when - * viewed from above. The unit are degrees, and zero equals a - * position above or below the negative y-axis. + * Angle by which the viewers position projected onto the x-y-plane is + * rotated around the z-axis, in positive sense when viewed from above. + * The unit are degrees, and zero equals a position above or below the + * negative y-axis. * - * Default is the Gnuplot-default of 30. An example of a - * Gnuplot-default of 0 is the following: + * Default is the Gnuplot-default of 30. An example of a Gnuplot-default + * of 0 is the following: * * @verbatim * @@ -668,50 +655,47 @@ namespace DataOutBase double turn_angle; /** - * Factor by which the z-axis is to be stretched as compared to - * the x- and y-axes. This is to compensate for the different - * sizes that coordinate and solution values may have and to - * prevent that the plot looks to much out-of-place (no elevation - * at all if solution values are much smaller than coordinate - * values, or the common "extremely mountainous area" in the - * opposite case. + * Factor by which the z-axis is to be stretched as compared to the x- and + * y-axes. This is to compensate for the different sizes that coordinate + * and solution values may have and to prevent that the plot looks to much + * out-of-place (no elevation at all if solution values are much smaller + * than coordinate values, or the common "extremely mountainous area" in + * the opposite case. * * Default is 1.0. */ double z_scaling; /** - * Flag the determines whether the lines bounding the cells (or - * the parts of each patch) are to be plotted. + * Flag the determines whether the lines bounding the cells (or the parts + * of each patch) are to be plotted. * * Default: true. */ bool draw_mesh; /** - * Flag whether to fill the regions between the lines bounding the - * cells or not. If not, no hidden line removal is performed, - * which in this crude implementation is done through writing the - * cells in a back-to-front order, thereby hiding the cells in the - * background by cells in the foreground. + * Flag whether to fill the regions between the lines bounding the cells + * or not. If not, no hidden line removal is performed, which in this + * crude implementation is done through writing the cells in a back-to- + * front order, thereby hiding the cells in the background by cells in the + * foreground. * - * If this flag is false and #draw_mesh is false - * as well, nothing will be printed. + * If this flag is false and #draw_mesh is false as + * well, nothing will be printed. * - * If this flag is true, then the cells will be drawn - * either colored by one of the data sets (if #shade_cells is - * true), or pure white (if #shade_cells is false or if - * there are no data sets). + * If this flag is true, then the cells will be drawn either + * colored by one of the data sets (if #shade_cells is true), or + * pure white (if #shade_cells is false or if there are no data sets). * * Default is true. */ bool draw_cells; /** - * Flag to determine whether the cells shall be colorized by the - * data set denoted by #color_vector, or simply be painted in - * white. This flag only makes sense if - * #draw_cells==true. Colorization is done through + * Flag to determine whether the cells shall be colorized by the data set + * denoted by #color_vector, or simply be painted in white. This flag only + * makes sense if #draw_cells==true. Colorization is done through * #color_function. * * Default is true. @@ -728,37 +712,36 @@ namespace DataOutBase float blue; /** - * Return true if the color represented by the three - * color values is a grey scale, i.e. all components are equal. + * Return true if the color represented by the three color + * values is a grey scale, i.e. all components are equal. */ bool is_grey () const; }; /** - * Definition of a function pointer type taking a value and - * returning a triple of color values in RGB values. + * Definition of a function pointer type taking a value and returning a + * triple of color values in RGB values. * - * Besides the actual value by which the color is to be computed, - * min and max values of the data to be colorized are given as - * well. + * Besides the actual value by which the color is to be computed, min and + * max values of the data to be colorized are given as well. */ typedef RgbValues (*ColorFunction) (const double value, const double min_value, const double max_value); /** - * This is a pointer to the function which is used to colorize the - * cells. By default, it points to the static function - * default_color_function() which is a member of this class. + * This is a pointer to the function which is used to colorize the cells. + * By default, it points to the static function default_color_function() + * which is a member of this class. */ ColorFunction color_function; /** - * Default colorization function. This one does what one usually - * wants: It shifts colors from black (lowest value) through blue, - * green and red to white (highest value). For the exact defition - * of the color scale refer to the implementation. + * Default colorization function. This one does what one usually wants: It + * shifts colors from black (lowest value) through blue, green and red to + * white (highest value). For the exact defition of the color scale refer + * to the implementation. * * This function was originally written by Stefan Nauber. */ @@ -768,10 +751,9 @@ namespace DataOutBase const double max_value); /** - * This is an alternative color function producing a grey scale - * between black (lowest values) and white (highest values). You - * may use it by setting the #color_function variable to the - * address of this function. + * This is an alternative color function producing a grey scale between + * black (lowest values) and white (highest values). You may use it by + * setting the #color_function variable to the address of this function. */ static RgbValues grey_scale_color_function (const double value, @@ -779,11 +761,10 @@ namespace DataOutBase const double max_value); /** - * This is one more alternative color function producing a grey - * scale between white (lowest values) and black (highest values), - * i.e. the scale is reversed to the previous one. You may use it - * by setting the #color_function variable to the address of this - * function. + * This is one more alternative color function producing a grey scale + * between white (lowest values) and black (highest values), i.e. the + * scale is reversed to the previous one. You may use it by setting the + * #color_function variable to the address of this function. */ static RgbValues reverse_grey_scale_color_function (const double value, @@ -807,37 +788,35 @@ namespace DataOutBase const ColorFunction color_function= &default_color_function); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. * - * For coloring, only the color functions declared in this class - * are offered. + * For coloring, only the color functions declared in this class are + * offered. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and set - * the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm); /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; /** - * Flags controlling the details of output in GMV format. At present - * no flags are implemented. + * Flags controlling the details of output in GMV format. At present no + * flags are implemented. * * @ingroup output */ @@ -846,8 +825,8 @@ namespace DataOutBase private: /** * Dummy entry to suppress compiler warnings when copying an empty - * structure. Remove this member when adding the first flag to - * this structure (and remove the private as well). + * structure. Remove this member when adding the first flag to this + * structure (and remove the private as well). */ int dummy; @@ -858,27 +837,25 @@ namespace DataOutBase GmvFlags (); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and set - * the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm) const; /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; @@ -894,47 +871,44 @@ namespace DataOutBase public: /** - * This variable is needed to hold the output file name when using - * the Tecplot API to write binary files. If the user doesn't set - * the file name with this variable only ASCII Tecplot output will - * be produced. + * This variable is needed to hold the output file name when using the + * Tecplot API to write binary files. If the user doesn't set the file + * name with this variable only ASCII Tecplot output will be produced. */ const char *tecplot_binary_file_name; /** - * Tecplot allows to assign names to zones. This variable stores - * this name. + * Tecplot allows to assign names to zones. This variable stores this + * name. */ const char *zone_name; /** * Constructor - **/ + */ TecplotFlags (const char *tecplot_binary_file_name = NULL, const char *zone_name = NULL); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and set - * the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm) const; /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; @@ -948,11 +922,11 @@ namespace DataOutBase { public: /** - * The time of the time step if this file is part of a time - * dependent simulation. + * The time of the time step if this file is part of a time dependent + * simulation. * - * The value of this variable is written into the output file - * according to the instructions provided in + * The value of this variable is written into the output file according to + * the instructions provided in * http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files * unless it is at its default value of * std::numeric_limits::min(). @@ -960,24 +934,23 @@ namespace DataOutBase double time; /** - * The number of the time step if this file is part of a time - * dependent simulation, or the cycle within a nonlinear or other - * iteration. + * The number of the time step if this file is part of a time dependent + * simulation, or the cycle within a nonlinear or other iteration. * - * The value of this variable is written into the output file - * according to the instructions provided in + * The value of this variable is written into the output file according to + * the instructions provided in * http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files - * unless it is at its default value of - * std::numeric_limits::min(). + * unless it is at its default value of std::numeric_limits::min(). */ unsigned int cycle; /** - * Flag to determine whether the current date and time shall be - * printed as a comment in the file's second line. - * - * Default is true. - */ + * Flag to determine whether the current date and time shall be printed as + * a comment in the file's second line. + * + * Default is true. + */ bool print_date_and_time; /** @@ -988,35 +961,33 @@ namespace DataOutBase const bool print_date_and_time = true); /** - * Declare the flags with name and type as offered by this class, - * for use in input files. + * Declare the flags with name and type as offered by this class, for use + * in input files. * - * Unlike the flags in many of the other classes similar to this one, we do - * not actually declare parameters for the #cycle and #time member variables - * of this class. The reason is that there wouldn't appear to be a case where - * one would want to declare these parameters in an input file. Rather, these - * are typically values that change during the course of a simulation and - * can only reasonably be set as part of the execution of a program, rather - * than a priori by a user who runs this program. + * Unlike the flags in many of the other classes similar to this one, we + * do not actually declare parameters for the #cycle and #time member + * variables of this class. The reason is that there wouldn't appear to be + * a case where one would want to declare these parameters in an input + * file. Rather, these are typically values that change during the course + * of a simulation and can only reasonably be set as part of the execution + * of a program, rather than a priori by a user who runs this program. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and - * set the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite all previous contents of this - * object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm) const; /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; @@ -1029,23 +1000,21 @@ namespace DataOutBase { public: /** - * Height of the image in SVG - * units. Default value is 4000. - */ + * Height of the image in SVG units. Default value is 4000. + */ unsigned int height; /** - * Width of the image in SVG - units. If left zero, the width is computed from the height. - */ + * Width of the image in SVG units. If left zero, the width is computed + * from the height. + */ unsigned int width; /** - * This denotes the number of the data vector which shall be used - * for generating the height information. By default, the first - * data vector is taken, i.e. #height_vector==0, if there - * is any data vector. If there is no data vector, no height - * information is generated. + * This denotes the number of the data vector which shall be used for + * generating the height information. By default, the first data vector is + * taken, i.e. #height_vector==0, if there is any data vector. If + * there is no data vector, no height information is generated. */ unsigned int height_vector; @@ -1057,18 +1026,18 @@ namespace DataOutBase unsigned int line_thickness; /** - * Draw a margin of 5% around the plotted area - */ + * Draw a margin of 5% around the plotted area + */ bool margin; /** - * Draw a colorbar encoding the cell coloring - */ + * Draw a colorbar encoding the cell coloring + */ bool draw_colorbar; /** - * Constructor. - */ + * Constructor. + */ SvgFlags(const unsigned int height_vector = 0, const int azimuth_angle = 37, const int polar_angle = 45, @@ -1077,20 +1046,19 @@ namespace DataOutBase const bool draw_colorbar = true); /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; /** - * Flags controlling the details of output in deal.II intermediate - * format. At present no flags are implemented. + * Flags controlling the details of output in deal.II intermediate format. + * At present no flags are implemented. * * @ingroup output */ @@ -1098,18 +1066,17 @@ namespace DataOutBase { /** * An indicator of the currect file format version used to write - * intermediate format. We do not attempt to be backward - * compatible, so this number is used only to verify that the - * format we are writing is what the current readers and writers - * understand. + * intermediate format. We do not attempt to be backward compatible, so + * this number is used only to verify that the format we are writing is + * what the current readers and writers understand. */ static const unsigned int format_version = 3; private: /** * Dummy entry to suppress compiler warnings when copying an empty - * structure. Remove this member when adding the first flag to - * this structure (and remove the private as well). + * structure. Remove this member when adding the first flag to this + * structure (and remove the private as well). */ int dummy; @@ -1120,27 +1087,25 @@ namespace DataOutBase Deal_II_IntermediateFlags (); /** - * Declare all flags with name and type as offered by this class, - * for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in declare_parameters() and - * set the flags for this output format accordingly. + * Read the parameters declared in declare_parameters() and set the flags + * for this output format accordingly. * - * The flags thus obtained overwrite - * all previous contents of this object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm) const; /** - * Determine an estimate for the memory consumption (in bytes) of - * this object. Since sometimes the size of objects can not be - * determined exactly (for example: what is the memory consumption - * of an STL std::map type with a certain number of - * elements?), this is only an estimate. however often quite close - * to the true value. + * Determine an estimate for the memory consumption (in bytes) of this + * object. Since sometimes the size of objects can not be determined + * exactly (for example: what is the memory consumption of an STL + * std::map type with a certain number of elements?), this is + * only an estimate. however often quite close to the true value. */ std::size_t memory_consumption () const; }; @@ -1154,15 +1119,15 @@ namespace DataOutBase struct DataOutFilterFlags { /** - * Filter duplicate vertices and associated values. This will - * drastically reduce the output data size but may affect the - * correctness of some calculated values. + * Filter duplicate vertices and associated values. This will drastically + * reduce the output data size but may affect the correctness of some + * calculated values. */ bool filter_duplicate_vertices; /** - * Whether the XDMF output refers to HDF5 files. - * This affects how output is structured. + * Whether the XDMF output refers to HDF5 files. This affects how output + * is structured. */ bool xdmf_hdf5_output; @@ -1173,27 +1138,21 @@ namespace DataOutBase const bool xdmf_hdf5_output = false); /** - * Declare all flags with name - * and type as offered by this - * class, for use in input files. + * Declare all flags with name and type as offered by this class, for use + * in input files. */ static void declare_parameters (ParameterHandler &prm); /** - * Read the parameters declared in - * declare_parameters and set the - * flags for this output format - * accordingly. + * Read the parameters declared in declare_parameters and set the + * flags for this output format accordingly. * - * The flags thus obtained overwrite - * all previous contents of this object. + * The flags thus obtained overwrite all previous contents of this object. */ void parse_parameters (const ParameterHandler &prm); /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this + * Determine an estimate for the memory consumption (in bytes) of this * object. */ std::size_t memory_consumption () const; @@ -1202,23 +1161,23 @@ namespace DataOutBase /** * DataOutFilter provides a way to remove redundant vertices and values * generated by the deal.II output. By default, DataOutBase and the classes - * that build on it output data at each corner of each cell. This means - * that data is output multiple times for each vertex of the mesh. The - * purpose of this scheme is to support output of discontinuous quantities, - * either because the finite element space is discontinuous or because the - * quantity that is output is computed from a solution field and is - * discontinuous across faces. + * that build on it output data at each corner of each cell. This means that + * data is output multiple times for each vertex of the mesh. The purpose of + * this scheme is to support output of discontinuous quantities, either + * because the finite element space is discontinuous or because the quantity + * that is output is computed from a solution field and is discontinuous + * across faces. * * This class is an attempt to rein in the amount of data that is written. * If the fields that are written to files are indeed discontinuous, the - * only way to faithfully represent them is indeed to write multiple - * values for each vertex (this is typically done by writing multiple - * node locations for the same vertex and defining data at these nodes). - * However, for fine meshes, one may not necessarily be interested in an - * exact representation of output fields that will likely only have - * small discontinuities. Rather, it may be sufficient to just output one - * value per vertex, which may be chosen arbitrarily from among those that - * are defined at this vertex from any of the adjacent cells. + * only way to faithfully represent them is indeed to write multiple values + * for each vertex (this is typically done by writing multiple node + * locations for the same vertex and defining data at these nodes). However, + * for fine meshes, one may not necessarily be interested in an exact + * representation of output fields that will likely only have small + * discontinuities. Rather, it may be sufficient to just output one value + * per vertex, which may be chosen arbitrarily from among those that are + * defined at this vertex from any of the adjacent cells. */ class DataOutFilter { @@ -1273,10 +1232,9 @@ namespace DataOutBase DataOutFilter(const DataOutBase::DataOutFilterFlags &flags) : flags(flags) {}; /** - * Write a point with the specified index into the filtered - * data set. If the point already exists and we are filtering - * redundant values, the provided index will internally refer - * to another recorded point. + * Write a point with the specified index into the filtered data set. If + * the point already exists and we are filtering redundant values, the + * provided index will internally refer to another recorded point. */ template void write_point(const unsigned int &index, const Point &p); @@ -1288,23 +1246,22 @@ namespace DataOutBase void write_cell(unsigned int index, unsigned int start, unsigned int d1, unsigned int d2, unsigned int d3); /** - * Filter and record a data set. If there are multiple values - * at a given vertex and redundant values are being removed, one - * is arbitrarily chosen as the recorded value. In the future - * this can be expanded to average/min/max multiple values - * at a given vertex. + * Filter and record a data set. If there are multiple values at a given + * vertex and redundant values are being removed, one is arbitrarily + * chosen as the recorded value. In the future this can be expanded to + * average/min/max multiple values at a given vertex. */ void write_data_set(const std::string &name, const unsigned int &dimension, const unsigned int &set_num, const Table<2,double> &data_vectors); /** - * Resize and fill a vector with all the filtered - * node vertex points, for output to a file. + * Resize and fill a vector with all the filtered node vertex points, for + * output to a file. */ void fill_node_data(std::vector &node_data) const; /** - * Resize and fill a vector with all the filtered - * cell vertex indices, for output to a file. + * Resize and fill a vector with all the filtered cell vertex indices, for + * output to a file. */ void fill_cell_data(const unsigned int &local_node_offset, std::vector &cell_data) const; @@ -1325,7 +1282,8 @@ namespace DataOutBase }; /** - * Get the raw double valued data of the data set indicated by the set number. + * Get the raw double valued data of the data set indicated by the set + * number. */ const double *get_data_set(const unsigned int &set_num) const { @@ -1351,8 +1309,8 @@ namespace DataOutBase }; /** - * Return the number of filtered data sets in this DataOutFilter. Data sets are - * not filtered so this will be the original number of data sets. + * Return the number of filtered data sets in this DataOutFilter. Data + * sets are not filtered so this will be the original number of data sets. */ unsigned int n_data_sets() const { @@ -1360,8 +1318,8 @@ namespace DataOutBase }; /** - * Empty functions to do base class inheritance. - */ + * Empty functions to do base class inheritance. + */ void flush_points () {}; /** @@ -1373,8 +1331,7 @@ namespace DataOutBase /** - * Provide a data type specifying the presently supported output - * formats. + * Provide a data type specifying the presently supported output formats. */ enum OutputFormat { @@ -1416,8 +1373,8 @@ namespace DataOutBase tecplot, /** - * Output for Tecplot in binary format. Faster and smaller than - * text format. + * Output for Tecplot in binary format. Faster and smaller than text + * format. */ tecplot_binary, @@ -1449,12 +1406,10 @@ namespace DataOutBase /** - * Write the given list of patches to the output stream in OpenDX - * format. + * Write the given list of patches to the output stream in OpenDX format. * - * Since OpenDX uses some kind of visual data flow oriented - * programming language, some of these programs are provided in - * contrib/dx. + * Since OpenDX uses some kind of visual data flow oriented programming + * language, some of these programs are provided in contrib/dx. */ template void write_dx (const std::vector > &patches, @@ -1466,49 +1421,46 @@ namespace DataOutBase /** * Write the given list of patches to the output stream in eps format. * - * Output in this format circumvents the use of auxiliary graphic - * programs converting some output format into a graphics - * format. This has the advantage that output is easy and fast, and - * the disadvantage that you have to give a whole bunch of - * parameters which determine the direction of sight, the mode of - * colorization, the scaling of the height axis, etc. (Of course, - * all these parameters have reasonable default values, which you + * Output in this format circumvents the use of auxiliary graphic programs + * converting some output format into a graphics format. This has the + * advantage that output is easy and fast, and the disadvantage that you + * have to give a whole bunch of parameters which determine the direction of + * sight, the mode of colorization, the scaling of the height axis, etc. (Of + * course, all these parameters have reasonable default values, which you * may want to change.) * - * This function only supports output for two-dimensional - * domains (i.e., with dim==2), with values in the vertical - * direction taken from a data vector. - * - * Basically, output consists of the mesh and the cells in between - * them. You can draw either of these, or both, or none if you are - * really interested in an empty picture. If written, the mesh uses - * black lines. The cells in between the mesh are either not printed - * (this will result in a loss of hidden line removal, i.e. you can - * "see through" the cells to lines behind), printed in white (which - * does nothing apart from the hidden line removal), or colorized - * using one of the data vectors (which need not be the same as the - * one used for computing the height information) and a customizable - * color function. The default color functions chooses the color - * between black, blue, green, red and white, with growing values of - * the data field chosen for colorization. At present, cells are - * displayed with one color per cell only, which is taken from the - * value of the data field at the center of the cell; bilinear - * interpolation of the color on a cell is not used. + * This function only supports output for two-dimensional domains (i.e., + * with dim==2), with values in the vertical direction taken from a data + * vector. + * + * Basically, output consists of the mesh and the cells in between them. You + * can draw either of these, or both, or none if you are really interested + * in an empty picture. If written, the mesh uses black lines. The cells in + * between the mesh are either not printed (this will result in a loss of + * hidden line removal, i.e. you can "see through" the cells to lines + * behind), printed in white (which does nothing apart from the hidden line + * removal), or colorized using one of the data vectors (which need not be + * the same as the one used for computing the height information) and a + * customizable color function. The default color functions chooses the + * color between black, blue, green, red and white, with growing values of + * the data field chosen for colorization. At present, cells are displayed + * with one color per cell only, which is taken from the value of the data + * field at the center of the cell; bilinear interpolation of the color on a + * cell is not used. * * By default, the viewpoint is chosen like the default viewpoint in - * GNUPLOT, i.e. with an angle of 60 degrees with respect to the - * positive z-axis and rotated 30 degrees in positive sense (as seen - * from above) away from the negative y-axis. Of course you can - * change these settings. + * GNUPLOT, i.e. with an angle of 60 degrees with respect to the positive + * z-axis and rotated 30 degrees in positive sense (as seen from above) away + * from the negative y-axis. Of course you can change these settings. * * EPS output is written without a border around the picture, i.e. the - * bounding box is close to the output on all four sides. Coordinates - * are written using at most five digits, to keep picture size at a - * reasonable size. + * bounding box is close to the output on all four sides. Coordinates are + * written using at most five digits, to keep picture size at a reasonable + * size. * * All parameters along with their default values are listed in the - * documentation of the EpsFlags member class of this - * class. See there for more and detailed information. + * documentation of the EpsFlags member class of this class. See + * there for more and detailed information. */ template void write_eps (const std::vector > &patches, @@ -1518,10 +1470,9 @@ namespace DataOutBase std::ostream &out); /** - * This is the same function as above except for domains that are - * not two-dimensional. This function is not implemented (and will - * throw an error if called) but is declared to allow for - * dimension-independent programs. + * This is the same function as above except for domains that are not two- + * dimensional. This function is not implemented (and will throw an error if + * called) but is declared to allow for dimension-independent programs. */ template void write_eps (const std::vector > &patches, @@ -1532,14 +1483,13 @@ namespace DataOutBase /** - * Write the given list of patches to the output stream in - * GMV format. + * Write the given list of patches to the output stream in GMV format. * - * Data is written in the following format: nodes are considered the - * points of the patches. In spatial dimensions less than three, - * zeroes are inserted for the missing coordinates. The data vectors - * are written as node or cell data, where for the first the data - * space is interpolated to (bi-,tri-)linear elements. + * Data is written in the following format: nodes are considered the points + * of the patches. In spatial dimensions less than three, zeroes are + * inserted for the missing coordinates. The data vectors are written as + * node or cell data, where for the first the data space is interpolated to + * (bi-,tri-)linear elements. */ template void write_gmv (const std::vector > &patches, @@ -1549,64 +1499,60 @@ namespace DataOutBase std::ostream &out); /** - * Write the given list of patches to the output stream in gnuplot - * format. Visualization of two-dimensional data can then be achieved by - * starting gnuplot and endtering the commands + * Write the given list of patches to the output stream in gnuplot format. + * Visualization of two-dimensional data can then be achieved by starting + * gnuplot and endtering the commands * * @verbatim * set data style lines * splot "filename" using 1:2:n * @endverbatim - * This example assumes that the number of the data vector displayed - * is n-2. + * This example assumes that the number of the data vector displayed is + * n-2. * * The GNUPLOT format is not able to handle data on unstructured grids - * directly. Directly would mean that you only give the vertices and - * the solution values thereon and the program constructs its own grid - * to represent the data. This is only possible for a structured - * tensor product grid in two dimensions. However, it is possible to - * give several such patches within one file, which is exactly what - * the respective function of this class does: writing each cell's - * data as a patch of data, at least if the patches as passed from - * derived classes represent cells. Note that the functions on patches - * need not be continuous at interfaces between patches, so this - * method also works for discontinuous elements. Note also, that - * GNUPLOT can do hidden line removal for patched data. + * directly. Directly would mean that you only give the vertices and the + * solution values thereon and the program constructs its own grid to + * represent the data. This is only possible for a structured tensor product + * grid in two dimensions. However, it is possible to give several such + * patches within one file, which is exactly what the respective function of + * this class does: writing each cell's data as a patch of data, at least if + * the patches as passed from derived classes represent cells. Note that the + * functions on patches need not be continuous at interfaces between + * patches, so this method also works for discontinuous elements. Note also, + * that GNUPLOT can do hidden line removal for patched data. * * While this discussion applies to two spatial dimensions, it is more - * complicated in 3d. The reason is that we could still use patches, - * but it is difficult when trying to visualize them, since if we use - * a cut through the data (by, for example, using x- and - * z-coordinates, a fixed y-value and plot function values in - * z-direction, then the patched data is not a patch in the sense - * GNUPLOT wants it any more. Therefore, we use another approach, - * namely writing the data on the 3d grid as a sequence of lines, - * i.e. two points each associated with one or more data sets. There - * are therefore 12 lines for each subcells of a patch. - * - * Given the lines as described above, a cut through this data in - * Gnuplot can then be achieved like this (& stands for the dollar - * sign in the following): + * complicated in 3d. The reason is that we could still use patches, but it + * is difficult when trying to visualize them, since if we use a cut through + * the data (by, for example, using x- and z-coordinates, a fixed y-value + * and plot function values in z-direction, then the patched data is not a + * patch in the sense GNUPLOT wants it any more. Therefore, we use another + * approach, namely writing the data on the 3d grid as a sequence of lines, + * i.e. two points each associated with one or more data sets. There are + * therefore 12 lines for each subcells of a patch. + * + * Given the lines as described above, a cut through this data in Gnuplot + * can then be achieved like this (& stands for the dollar sign in the + * following): * @verbatim * set data style lines * splot [:][:][0:] "T" using 1:2:(&3==.5 ? &4 : -1) * @endverbatim * * This command plots data in x- and y-direction unbounded, but in - * z-direction only those data points which are above the x-y-plane - * (we assume here a positive solution, if it has negative values, you - * might want to decrease the lower bound). Furthermore, it only takes - * the data points with z-values (&3) equal to 0.5, i.e. a - * cut through the domain at z=0.5. For the data points on - * this plane, the data values of the first data set (&4) are - * raised in z-direction above the x-y-plane; all other points are - * denoted the value -1 instead of the value of the data - * vector and are not plotted due to the lower bound in z plotting - * direction, given in the third pair of brackets. - * - * More complex cuts are possible, including nonlinear ones. Note - * however, that only those points which are actually on the - * cut-surface are plotted. + * z-direction only those data points which are above the x-y-plane (we + * assume here a positive solution, if it has negative values, you might + * want to decrease the lower bound). Furthermore, it only takes the data + * points with z-values (&3) equal to 0.5, i.e. a cut through the + * domain at z=0.5. For the data points on this plane, the data + * values of the first data set (&4) are raised in z-direction + * above the x-y-plane; all other points are denoted the value -1 + * instead of the value of the data vector and are not plotted due to the + * lower bound in z plotting direction, given in the third pair of brackets. + * + * More complex cuts are possible, including nonlinear ones. Note however, + * that only those points which are actually on the cut-surface are plotted. */ template void write_gnuplot (const std::vector > &patches, @@ -1616,31 +1562,29 @@ namespace DataOutBase std::ostream &out); /** - * Write the given list of patches to the output stream for the - * Povray raytracer. + * Write the given list of patches to the output stream for the Povray + * raytracer. * - * Output in this format creates a povray source file, include - * standard camera and light source definition for rendering with - * povray 3.1 At present, this format only supports output for - * two-dimensional data, with values in the third direction taken from - * a data vector. + * Output in this format creates a povray source file, include standard + * camera and light source definition for rendering with povray 3.1 At + * present, this format only supports output for two-dimensional data, with + * values in the third direction taken from a data vector. * * The output uses two different povray-objects: * *