From: David Wells Date: Sat, 9 Jan 2016 19:18:10 +0000 (-0500) Subject: Add annotations to the source to explain choices. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=264cf8426c58c7263a5f38abdb737d8c3cf49f75;p=code-gallery.git Add annotations to the source to explain choices. --- diff --git a/cdr/common/include/deal.II-cdr/parameters.h b/cdr/common/include/deal.II-cdr/parameters.h index 525c9ff..ddf2d15 100644 --- a/cdr/common/include/deal.II-cdr/parameters.h +++ b/cdr/common/include/deal.II-cdr/parameters.h @@ -5,6 +5,12 @@ #include +// I prefer to use the ParameterHandler class in a slightly different way than +// usual: The class Parameters creates, uses, and then destroys a +// ParameterHandler inside the read_parameter_file method instead +// of keeping it around. This is nice because now all of the run time +// parameters are contained in a simple class and it can be copied or passed +// around very easily. namespace CDR { using namespace dealii; diff --git a/cdr/common/include/deal.II-cdr/system_matrix.h b/cdr/common/include/deal.II-cdr/system_matrix.h index 4697587..348f419 100644 --- a/cdr/common/include/deal.II-cdr/system_matrix.h +++ b/cdr/common/include/deal.II-cdr/system_matrix.h @@ -10,6 +10,10 @@ #include +// One of the goals I had in writing this entry was to split up functions into +// different compilation units instead of using one large file. This is the +// header file for a pair of functions (only one of which I ultimately use) +// which build the system matrix. namespace CDR { using namespace dealii; diff --git a/cdr/common/include/deal.II-cdr/system_matrix.templates.h b/cdr/common/include/deal.II-cdr/system_matrix.templates.h index 41f7c4c..7cafd46 100644 --- a/cdr/common/include/deal.II-cdr/system_matrix.templates.h +++ b/cdr/common/include/deal.II-cdr/system_matrix.templates.h @@ -19,6 +19,9 @@ namespace CDR { using namespace dealii; + // This is the actual implementation of the create_system_matrix + // function described in the header file. It is similar to the system matrix + // assembly routine in step-40. template void internal_create_system_matrix (const DoFHandler &dof_handler, @@ -55,13 +58,13 @@ namespace CDR const auto convection_contribution = current_convection *fe_values.shape_grad(j, q); cell_matrix(i, j) += fe_values.JxW(q)* - // mass and reaction part + // Here are the time step, mass, and reaction parts: ((1.0 + time_step/2.0*parameters.reaction_coefficient) *fe_values.shape_value(i, q)*fe_values.shape_value(j, q) + time_step/2.0* - // convection part + // and the convection part: (fe_values.shape_value(i, q)*convection_contribution - // Laplacian part + // and, finally, the diffusion part: + parameters.diffusion_coefficient *(fe_values.shape_grad(i, q)*fe_values.shape_grad(j, q))) ); diff --git a/cdr/common/include/deal.II-cdr/system_rhs.h b/cdr/common/include/deal.II-cdr/system_rhs.h index 96c8cb4..966542d 100644 --- a/cdr/common/include/deal.II-cdr/system_rhs.h +++ b/cdr/common/include/deal.II-cdr/system_rhs.h @@ -12,6 +12,8 @@ #include +// Similarly to create_system_matrix, I wrote a separate function +// to compute the right hand side. namespace CDR { using namespace dealii; diff --git a/cdr/common/include/deal.II-cdr/system_rhs.templates.h b/cdr/common/include/deal.II-cdr/system_rhs.templates.h index efbac5c..9e49a5e 100644 --- a/cdr/common/include/deal.II-cdr/system_rhs.templates.h +++ b/cdr/common/include/deal.II-cdr/system_rhs.templates.h @@ -78,17 +78,17 @@ namespace CDR *fe_values.shape_grad(j, q); cell_rhs(i) += fe_values.JxW(q)* - // mass and reaction part + // Here are the mass and reaction part: (((1.0 - time_step/2.0*parameters.reaction_coefficient) *fe_values.shape_value(i, q)*fe_values.shape_value(j, q) - time_step/2.0* - // convection part + // the convection part: (fe_values.shape_value(i, q)*convection_contribution - // Laplacian part + // the diffusion part: + parameters.diffusion_coefficient *(fe_values.shape_grad(i, q)*fe_values.shape_grad(j, q)))) *current_fe_coefficients[j] - // forcing parts + // and, finally, the forcing function part: + time_step/2.0* (current_forcing + previous_forcing) *fe_values.shape_value(i, q)); diff --git a/cdr/common/include/deal.II-cdr/write_pvtu_output.h b/cdr/common/include/deal.II-cdr/write_pvtu_output.h index 92e793e..5b0b1c2 100644 --- a/cdr/common/include/deal.II-cdr/write_pvtu_output.h +++ b/cdr/common/include/deal.II-cdr/write_pvtu_output.h @@ -2,6 +2,7 @@ #define dealii__cdr_write_pvtu_output_h #include +// This is a small class which handles PVTU output. namespace CDR { using namespace dealii; diff --git a/cdr/common/include/deal.II-cdr/write_pvtu_output.templates.h b/cdr/common/include/deal.II-cdr/write_pvtu_output.templates.h index 5f2f63d..ec479a5 100644 --- a/cdr/common/include/deal.II-cdr/write_pvtu_output.templates.h +++ b/cdr/common/include/deal.II-cdr/write_pvtu_output.templates.h @@ -15,6 +15,8 @@ #include #include +// Here is the implementation of the important function. This is similar to +// what is presented in step-40. namespace CDR { using namespace dealii; @@ -39,6 +41,8 @@ namespace CDR DataOutBase::VtkFlags flags; flags.time = current_time; + // While the default flag is for the best compression level, using + // best_speed makes this function much faster. flags.compression_level = DataOutBase::VtkFlags::ZlibCompressionLevel::best_speed; data_out.set_flags(flags); diff --git a/cdr/common/source/system_matrix.cc b/cdr/common/source/system_matrix.cc index ae90c0b..ae14c4e 100644 --- a/cdr/common/source/system_matrix.cc +++ b/cdr/common/source/system_matrix.cc @@ -5,6 +5,10 @@ #include #include +// This file exists just to build template specializations of +// create_system_matrix. Even though the solver is run in +// parallel with Trilinos objects, other serial solvers can use the same +// function without recompilation by compiling everything here just one time. namespace CDR { using namespace dealii; diff --git a/cdr/common/source/system_rhs.cc b/cdr/common/source/system_rhs.cc index 4374d73..609e824 100644 --- a/cdr/common/source/system_rhs.cc +++ b/cdr/common/source/system_rhs.cc @@ -5,6 +5,8 @@ #include +// Like system_matrix.cc, this file just compiles template +// specializations. namespace CDR { using namespace dealii; diff --git a/cdr/common/source/write_pvtu_output.cc b/cdr/common/source/write_pvtu_output.cc index 4e27847..f74f2c2 100644 --- a/cdr/common/source/write_pvtu_output.cc +++ b/cdr/common/source/write_pvtu_output.cc @@ -3,6 +3,8 @@ #include +// Again, this file just compiles the constructor and also the templated +// functions. namespace CDR { using namespace dealii; diff --git a/cdr/solver/cdr.cc b/cdr/solver/cdr.cc index fffb442..2cfa733 100644 --- a/cdr/solver/cdr.cc +++ b/cdr/solver/cdr.cc @@ -14,7 +14,7 @@ #include -// for distributed computations +// These headers are for distributed computations: #include #include #include @@ -40,7 +40,8 @@ using namespace dealii; constexpr int manifold_id {0}; - +// This is the actual solver class which performs time iteration and calls the +// appropriate library functions to do it. template class CDRProblem { @@ -70,6 +71,13 @@ private: ConstraintMatrix constraints; bool first_run; + + // As is usual in parallel programs, I keep two copies of parts of the + // complete solution: locally_relevant_solution contains both + // the locally calculated solution as well as the layer of cells at its + // boundary (the @ref GlossGhostCells "ghost cells") while + // completely_distributed_solution only contains the parts of + // the solution computed on the current @ref GlossMPIProcess "MPI process". TrilinosWrappers::MPI::Vector locally_relevant_solution; TrilinosWrappers::MPI::Vector completely_distributed_solution; TrilinosWrappers::MPI::Vector system_rhs; @@ -284,6 +292,8 @@ constexpr int dim {2}; int main(int argc, char *argv[]) { + // One of the new features in C++11 is the chrono component of + // the standard library. This gives us an easy way to time the output. auto t0 = std::chrono::high_resolution_clock::now(); Utilities::MPI::MPI_InitFinalize mpi_initialization(argc, argv, 1);