-
Notifications
You must be signed in to change notification settings - Fork 115
Diagnostic output
Fluidity has a new mechanism for generating diagnostic output. This supercedes putting print or write statements in the code and it is essential that all developers follow this protocol.
The ewrite macro is the output command that should be used throughout fluidity. Its syntax is:
ewrite(<priority>, <format>) arg[, arg]...
Users will note the similarity between this and the usual Fortran write statement. can be any string expression who's value is a legal Fortran format string and may be * for list-directed output exactly as in the Fortran write statement.
The argument controls the debug level at which the message should appear. Only messages with a priority less than or equal to the current debug level are output.
The ewrite_minmax macro replaces the pminmax subroutine - which should no longer be used. It outputs the minimum and maximum values of an array using the syntax:
ewrite_minmax(<array>)
ewrite_minmax always has a priority of 2.
Because the ewrite macros expand to if statements, it is not possible to use an ewrite macro in an if statement. It is, however, possible to place an ewrite in an if block.
The ewrite macro depends on declarations made in the debug module. It is therefore necessary to insert:
use fldebug
in the top of any scoping unit using the macro. See Fortran modules for more information on using modules. It is also necessary to place the declaration:
#include "fdebug.h"
at the top of each source file which needs to access ewrite.
The lower the priority level, the more important the message. Correspondingly there should be few high priority messages and they should be sparing in what they output.
| Message Priority | Contents | Comment |
|---|---|---|
| -1 | Critical error messages only | Output at this level will be seen by ordinary users who have not asked for additional output. |
| 0 | Warning messages | This level is for non-fatal problem reports. Any out of the ordinary behaviour should be logged at this level. |
| 1 | Navigation information | At this level movement into important subroutines should be logged. Matrix solves, adapts, new timesteps etc. |
| 2+ | Detailed debugging information | |
| 3 | Legacy output | Lines automatically converted from print and write statements. |
The debug level can be set globally at runtime by providing the command line option -v to fluidity. Only messages with a priority strictly less than the debug level will be output.
For debugging purposes, developers can temporarily increase the debug level in their code by calling:
call set_debug_level(level)
After the relevant code block, the debug level can be reset to the current global value using:
call reset_debug_level
Calls to set_debug_level '''must not''' be committed to the svn trunk.
The default debug level is 0. If the -l option is specified then the default debug level is 2.
The trunk has been converted to (hopefully completely) use ewrite. For branches, the easiest way to move to the new system is as follows:
- Merge from the trunk. This will fix most of the problems immediately.
- In the fluidity source directory, run:
./scripts/fix_output_statements
This should automagically convert all offending output statements to ewrites. - Attempt to compile. Any compilation errors are most likely due to:
- Missing #include "fdebug.h"
- Missing use debug
- ewrite in an if statement.
- After or while fixing the compilation errors, check any important diagnostic output statements that you are responsible for to see that they have the right priority. By default most print and write statements will be converted to ewrites with a priority of 3, meaning they will very rarely occur.