You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/documentation/src/developer_guide/codingguidelines.rst
+79-7Lines changed: 79 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ in the future.
28
28
.. _avoid-define-flags:
29
29
30
30
Avoid define flags
31
-
^^^^^^^^^^^^^^^^^^
31
+
~~~~~~~~~~~~~~~~~~
32
32
33
33
Do not introduce new define flags. They complicate testing and lead to untested code.
34
34
@@ -40,7 +40,7 @@ Do not introduce new define flags. They complicate testing and lead to untested
40
40
flags are all managed via CMake.
41
41
42
42
Avoid header-in-header inclusion
43
-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
43
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44
44
45
45
Avoid and actively resolve header-in-header inclusion to speed up compilation time. Use forward declarations instead.
46
46
@@ -49,7 +49,7 @@ want to avoid including an (expensive) header file via a forward declaration, pu
49
49
file and include this header. This way, the forward declaration is only in one place.
50
50
51
51
Use of smart pointers
52
-
^^^^^^^^^^^^^^^^^^^^^
52
+
~~~~~~~~~~~~~~~~~~~~~
53
53
54
54
If necessary, use smart pointers for their memory management capabilities, e.g., ``std::shared_ptr``, ``std::unique_ptr``
55
55
(you may find more information on passing smart pointers
@@ -60,7 +60,7 @@ By default, pass parameters by const reference and only expose smart pointers if
60
60
See also `<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-owner>`_.
61
61
62
62
Use of ``Teuchos::ParameterList``
63
-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
63
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64
64
65
65
Prefer parameter container classes over ``Teuchos::ParameterList`` for passing parameters to functions. Often,
66
66
a simple struct with all necessary data as public, non-const members is sufficient.
@@ -69,15 +69,15 @@ Reason: ``Teuchos::ParameterList`` is a flexible container for input(!) paramete
69
69
In addition, the string-based lookup is not compile-time checked.
70
70
71
71
Const-correctness
72
-
^^^^^^^^^^^^^^^^^
72
+
~~~~~~~~~~~~~~~~~
73
73
74
74
Make code const-correct. Const-correctness is mainly relevant for function parameters and member functions.
75
75
76
76
**Note:** The member fields of a struct or class should often not be ``const``, as this would prevent the struct or
77
77
class from being moved or copied. Instead, use ``const`` member functions to access the fields in a ``const`` context.
78
78
79
79
Enums
80
-
^^^^^
80
+
~~~~~
81
81
82
82
- By default, use scoped ``enum class`` instead of unscoped ``enum``.
83
83
- Use enums instead of strings for parameters that take one from a fixed set of values.
@@ -90,7 +90,7 @@ See also `Enum.3 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#e
90
90
91
91
92
92
|FOURC|-specific Naming Conventions
93
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93
+
-----------------------------------
94
94
95
95
- **Namespaces** use CamelCase: ``LinAlg::``
96
96
- **class**, **struct** and **enum** types use CamelCase: ``ClassName``, ``StructName``, ``EnumName``
@@ -108,3 +108,75 @@ The full specification of the naming convention is listed in the
108
108
109
109
Variable names must not be just a single letter, because they are impossible to find in a global search operation.
110
110
(Exception: loop indices such as i, j, but remember that even loop indices could/should have descriptive names.)
111
+
112
+
113
+
Directory structure
114
+
--------------------
115
+
The |FOURC| code comes with documentation, example input files and
116
+
support scripts. The important subdirectories are the following:
117
+
118
+
.. list-table::
119
+
:header-rows: 1
120
+
121
+
* - Directory
122
+
- Description
123
+
* - ``apps``
124
+
- Contains executables built on top of the |FOURC| library code.
125
+
* - ``cmake``
126
+
- Contains the CMake configuration files to build |FOURC|.
127
+
* - ``dependencies``
128
+
- Contains installation scripts for the external dependencies of |FOURC|.
129
+
* - ``doc``
130
+
- Contains the sources of the documentation you are currently reading.
131
+
* - ``docker``
132
+
- Contains the setup files for docker images for running |FOURC| inside of it.
133
+
* - ``presets``
134
+
- Contains preset files for CMake.
135
+
* - ``src``
136
+
- Contains the bulk of the |FOURC| code organized into several modules.
137
+
* - ``tests``
138
+
- Contains end-to-end tests that run |FOURC| as a whole with optional pre- and post-processing steps. The tests are not directly related to one specific feature (these reside next to the sources).
139
+
* - ``tests/input_files``
140
+
- Contains various valid and running input files. These input files are also used for automated testing.
141
+
* - ``unittests``
142
+
- [Legacy] Contains the source files for stand-alone tests aka unittests. These tests will move closer to the source code into the respective modules.
143
+
* - ``utilities``
144
+
- Contains useful scripts to develop and test |FOURC|.
145
+
146
+
The top-level directory should only contain files that are commonly expected in this location,
147
+
such as the README, LICENSE, and configuration files for tools like clang-format and clang-tidy.
148
+
149
+
Details of the ``src`` directory
150
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
+
152
+
The ``src`` directory contains the modules that make up the |FOURC| library. Each module is
153
+
split into a ``src`` and ``tests`` directory. The ``src`` directory contains the production code
154
+
of the module, while the ``tests`` directory contains the module-related tests.
155
+
156
+
Types of source files used within |FOURC|
157
+
"""""""""""""""""""""""""""""""""""""""""
158
+
159
+
The code base consists almost exclusively of C++ source files. To better indicate the intended usage
160
+
of a file, both to the build system and developers, the following file extensions are used:
161
+
162
+
.. list-table::
163
+
:header-rows: 1
164
+
165
+
* - File Extension
166
+
- Description
167
+
* - ``.cpp``
168
+
- C++ source files. These files are compiled.
169
+
* - ``.hpp``
170
+
- C++ header files. These files are included in other source files.
171
+
* - ``.fwd.hpp``
172
+
- C++ forward declaration header files. These files contain forward declarations of classes and functions that appear over and over again. They are especially useful for external dependencies to isolate the exposed surface area of the dependency. This type of file is usually included in other header files.
173
+
* - ``.templates.hpp``
174
+
- C++ header files which contain additional template definitions. The reason why you might want to separate certain expensive template definitions from the main header file is to speed up compilation times. Sometimes a template definition requires additional expensive includes, which are not necessary for the main header file. In this case, the template definition is best moved to a ``.templates.hpp`` file.
175
+
* - ``.inst.hpp``
176
+
- C++ header files which contain explicit template instantiations. These files are included in the corresponding ``.cpp`` file to instantiate the templates. These files are not strictly necessary as you can also instantiate the templates directly in the ``.cpp`` file. However, by moving the instantiations to a separate file, you can reuse the same instantiations in multiple ``.cpp`` files which contain parts of the implementation of the same classes.
177
+
* - ``.<ext>.in``
178
+
- These files are templates (not in the C++ sense!) requiring additional configuration via CMake. The CMake script will generate the actual file by replacing placeholders in the template file. The generated file will be placed in the build directory with the extension ``.<ext>``.
**Note:** For general information about configuring and building of |FOURC| refer to :ref:`Configure and Build <4Cinstallation>` and the ``README.md``.
@@ -205,3 +205,64 @@ It is also possible to only open the output of a specific mpi rank with processo
205
205
.. figure:: /_assets/kcachegrind.png
206
206
:alt:Picture of kcachegrind
207
207
:width:100%
208
+
209
+
210
+
.. _teuchos-time-monitor:
211
+
212
+
Teuchos Time Monitor
213
+
~~~~~~~~~~~~~~~~~~~~
214
+
215
+
The ``TimeMonitor`` from ``Trilinos`` package ``Teuchos`` provides MPI collective timer statistics.
216
+
Refer to the ``Teuchos::TimeMonitor`` Class Reference https://trilinos.org/docs/dev/packages/teuchos/doc/html/classTeuchos_1_1TimeMonitor.html for a detailed documentation.
217
+
218
+
Add a timer for a method in |FOURC|
219
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220
+
221
+
In order to get parallel timing statistics of a method in |FOURC| include the following header
222
+
223
+
::
224
+
225
+
#include <Teuchos_TimeMonitor.hpp>
226
+
227
+
228
+
in the ``.cpp``-file that contains the implementation of the method and add the macro ``TEUCHOS_FUNC_TIME_MONITOR``
229
+
with the name of the method in the implementation of the method:
The output gives the minimum, maximum, and mean ``execution time (number of counts)`` for all processors and also the mean execution time over all counts.
256
+
257
+
**Note:** The ``TimeMonitor`` output of a |FOURC| simulation in general already contains a variety of methods that are monitored, meaning there is a line with timings for each method in the output.
258
+
259
+
How to interpret the output of the ``TimeMonitor``
Examining the output of the ``TimeMonitor`` is probably one of the easiest steps in profiling the behaviour of a program. The information given in the output of the `TimeMonitor` may server for
263
+
264
+
- getting an idea of the execution time of a method
265
+
- knowing how often a method is called during the runtime of the program
266
+
- investigating the parallel load balancing of a method (compare ``MinOverProcs`` with ``MaxOverProcs``)
267
+
268
+
and thereby helps identifying bottlenecks in the overall program.
0 commit comments