From ac0ea39fea7e78d458b88c8b75a55e4bdcbd2c5f Mon Sep 17 00:00:00 2001
From: Dmitri Naumov <github@naumov.de>
Date: Tue, 13 Nov 2018 23:59:34 +0100
Subject: [PATCH] [doc] Tag descriptions for test_definition subtree
---
Applications/ApplicationsLib/TestDefinition.cpp | 6 ++++++
Applications/CLI/ogs.cpp | 1 +
.../ProjectFile/prj/test_definition/i_test_definition.md | 1 +
.../ProjectFile/prj/test_definition/vtkdiff/i_vtkdiff.md | 3 +++
.../prj/test_definition/vtkdiff/t_absolute_tolerance.md | 1 +
.../ProjectFile/prj/test_definition/vtkdiff/t_field.md | 1 +
.../ProjectFile/prj/test_definition/vtkdiff/t_file.md | 3 +++
.../prj/test_definition/vtkdiff/t_relative_tolerance.md | 4 ++++
8 files changed, 20 insertions(+)
create mode 100644 Documentation/ProjectFile/prj/test_definition/i_test_definition.md
create mode 100644 Documentation/ProjectFile/prj/test_definition/vtkdiff/i_vtkdiff.md
create mode 100644 Documentation/ProjectFile/prj/test_definition/vtkdiff/t_absolute_tolerance.md
create mode 100644 Documentation/ProjectFile/prj/test_definition/vtkdiff/t_field.md
create mode 100644 Documentation/ProjectFile/prj/test_definition/vtkdiff/t_file.md
create mode 100644 Documentation/ProjectFile/prj/test_definition/vtkdiff/t_relative_tolerance.md
diff --git a/Applications/ApplicationsLib/TestDefinition.cpp b/Applications/ApplicationsLib/TestDefinition.cpp
index 7914a00116e..0611ac75736 100644
--- a/Applications/ApplicationsLib/TestDefinition.cpp
+++ b/Applications/ApplicationsLib/TestDefinition.cpp
@@ -140,11 +140,13 @@ TestDefinition::TestDefinition(BaseLib::ConfigTree const& config_tree,
std::string const vtkdiff = findVtkdiff();
// Construct command lines for each entry.
+ //! \ogs_file_param{prj__test_definition__vtkdiff}
auto const& vtkdiff_configs = config_tree.getConfigSubtreeList("vtkdiff");
_command_lines.reserve(vtkdiff_configs.size());
for (auto const& vtkdiff_config : vtkdiff_configs)
{
std::string const& field_name =
+ //! \ogs_file_param{prj__test_definition__vtkdiff__field}
vtkdiff_config.getConfigParameter<std::string>("field");
DBUG("vtkdiff will compare field '%s'.", field_name.c_str());
@@ -155,10 +157,12 @@ TestDefinition::TestDefinition(BaseLib::ConfigTree const& config_tree,
MPI_Comm_size(PETSC_COMM_WORLD, &mpi_size);
std::string const& filename =
MeshLib::IO::getVtuFileNameForPetscOutputWithoutExtension(
+ //! \ogs_file_param{prj__test_definition__vtkdiff__file}
vtkdiff_config.getConfigParameter<std::string>("file")) +
"_" + std::to_string(rank) + ".vtu";
#else
std::string const& filename =
+ //! \ogs_file_param{prj__test_definition__vtkdiff__file}
vtkdiff_config.getConfigParameter<std::string>("file");
#endif // OGS_USE_PETSC
std::string const& output_filename =
@@ -169,6 +173,7 @@ TestDefinition::TestDefinition(BaseLib::ConfigTree const& config_tree,
BaseLib::joinPaths(reference_path, filename);
auto const& absolute_tolerance =
+ //! \ogs_file_param{prj__test_definition__vtkdiff__absolute_tolerance}
vtkdiff_config.getConfigParameterOptional<double>(
"absolute_tolerance");
std::string const absolute_tolerance_parameter =
@@ -177,6 +182,7 @@ TestDefinition::TestDefinition(BaseLib::ConfigTree const& config_tree,
: "--abs " + convert_to_string(*absolute_tolerance);
auto const& relative_tolerance =
+ //! \ogs_file_param{prj__test_definition__vtkdiff__relative_tolerance}
vtkdiff_config.getConfigParameterOptional<double>(
"relative_tolerance");
std::string const relative_tolerance_parameter =
diff --git a/Applications/CLI/ogs.cpp b/Applications/CLI/ogs.cpp
index 541a009e214..0d3650f5e59 100644
--- a/Applications/CLI/ogs.cpp
+++ b/Applications/CLI/ogs.cpp
@@ -190,6 +190,7 @@ int main(int argc, char* argv[])
{
test_definition =
std::make_unique<ApplicationsLib::TestDefinition>(
+ //! \ogs_file_param{prj__test_definition}
project_config->getConfigSubtree("test_definition"),
reference_path_arg.getValue(),
outdir_arg.getValue());
diff --git a/Documentation/ProjectFile/prj/test_definition/i_test_definition.md b/Documentation/ProjectFile/prj/test_definition/i_test_definition.md
new file mode 100644
index 00000000000..17e7af12387
--- /dev/null
+++ b/Documentation/ProjectFile/prj/test_definition/i_test_definition.md
@@ -0,0 +1 @@
+Test definitions for post-simulation comparisons.
diff --git a/Documentation/ProjectFile/prj/test_definition/vtkdiff/i_vtkdiff.md b/Documentation/ProjectFile/prj/test_definition/vtkdiff/i_vtkdiff.md
new file mode 100644
index 00000000000..c61e662d54e
--- /dev/null
+++ b/Documentation/ProjectFile/prj/test_definition/vtkdiff/i_vtkdiff.md
@@ -0,0 +1,3 @@
+Test definition for vtkdiff comparison tool.
+
+See https://github.com/ufz/vtkdiff
diff --git a/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_absolute_tolerance.md b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_absolute_tolerance.md
new file mode 100644
index 00000000000..576f7d14590
--- /dev/null
+++ b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_absolute_tolerance.md
@@ -0,0 +1 @@
+Absolute tolerance \f$\epsilon\f$ for comparison \f$|a - b| < \epsilon\f$.
diff --git a/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_field.md b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_field.md
new file mode 100644
index 00000000000..ef446458e2b
--- /dev/null
+++ b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_field.md
@@ -0,0 +1 @@
+Name of the point data or the cell data field to be compared.
diff --git a/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_file.md b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_file.md
new file mode 100644
index 00000000000..266d913ccbe
--- /dev/null
+++ b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_file.md
@@ -0,0 +1,3 @@
+Full name of the output file including the `.vtu` ending. For parallel
+simulations specify the same name as for the serial case; conversion of the file
+names according to the number of ranks happens automatically.
diff --git a/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_relative_tolerance.md b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_relative_tolerance.md
new file mode 100644
index 00000000000..c59e7d59482
--- /dev/null
+++ b/Documentation/ProjectFile/prj/test_definition/vtkdiff/t_relative_tolerance.md
@@ -0,0 +1,4 @@
+Relative tolerance \f$\delta\f$ for comparison \f${|a - b| \over {\textrm
+min}(|a|, |b|)} < \delta\f$.
+If the absolute difference \f$|a - b|\f$ is zero, zero is returned.
+If \f$a\f$ or \f$b\f$ are zero, \f$+\infty\f$ is returned.
--
GitLab