From 3f311e0896799974a154638ef0ff62b85401becb Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 14:04:00 +0000 Subject: [PATCH 01/29] Docs: Fix some double-backtick issues --- manual/sphinx/user_docs/bout_options.rst | 30 ++++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/manual/sphinx/user_docs/bout_options.rst b/manual/sphinx/user_docs/bout_options.rst index 85a8a17d59..f63e65b6df 100644 --- a/manual/sphinx/user_docs/bout_options.rst +++ b/manual/sphinx/user_docs/bout_options.rst @@ -139,10 +139,10 @@ Boolean expressions Boolean values must be "true", "false", "True", "False", "1" or "0". All lowercase ("true"/"false") is preferred, but the uppercase versions are allowed to support Python string conversions. Booleans -can be combined into expressions using binary operators `&` (logical -AND), `|` (logical OR), and unary operator `!` (logical NOT). For -example "true & false" evaluates to `false`; "!false" evaluates to -`true`. Like real values and integers, boolean expressions can refer +can be combined into expressions using binary operators ``&`` (logical +AND), ``|`` (logical OR), and unary operator ``!`` (logical NOT). For +example "true & false" evaluates to ``false``; "!false" evaluates to +``true``. Like real values and integers, boolean expressions can refer to other variables: .. code-block:: cfg @@ -150,8 +150,8 @@ to other variables: switch = true other_switch = !switch -Boolean expressions can be formed by comparing real values using -`>` and `<` comparison operators: +Boolean expressions can be formed by comparing real values using ``>`` +and ``<`` comparison operators: .. code-block:: cfg @@ -160,15 +160,15 @@ Boolean expressions can be formed by comparing real values using is_false = value < 2 .. note:: - Previous BOUT++ versions (v5.1.0 and earlier) were case - insensitive when reading boolean values, so would read "True" or - "yEs" as `true`, and "False" or "No" as `false`. These earlier - versions did not allow boolean expressions. - -Internally, booleans are evaluated as real values, with `true` being 1 -and `false` being 0. Logical operators (`&`, `|`, `!`) check that -their left and right arguments are either close to 0 or close to 1 -(like integers, "close to" is within 1e-3). + Previous BOUT++ versions (v5.1.0 and earlier) were case insensitive + when reading boolean values, so would read "True" or "yEs" as + ``true``, and "False" or "No" as ``false``. These earlier versions + did not allow boolean expressions. + +Internally, booleans are evaluated as real values, with ``true`` being +1 and ``false`` being 0. Logical operators (``&``, ``|``, ``!``) check +that their left and right arguments are either close to 0 or close to +1 (like integers, "close to" is within 1e-3). Special symbols in Option names ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 0bc5206ed28aa41ab43e9f32707aa524318386eb Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:07:54 +0000 Subject: [PATCH 02/29] Docs: Update code layout Prefer linking to sections rather than specific files, as these have changed a fair bit --- manual/sphinx/developer_docs/code_layout.rst | 294 ++++--------------- manual/sphinx/developer_docs/mesh.rst | 4 + manual/sphinx/user_docs/variable_init.rst | 2 + 3 files changed, 58 insertions(+), 242 deletions(-) diff --git a/manual/sphinx/developer_docs/code_layout.rst b/manual/sphinx/developer_docs/code_layout.rst index 7605355d7f..e79245cde3 100644 --- a/manual/sphinx/developer_docs/code_layout.rst +++ b/manual/sphinx/developer_docs/code_layout.rst @@ -49,275 +49,85 @@ Directories ----------- The source code for the core of BOUT++ is divided into include files -(which can be used in physics models) in ``bout++/include``, and source -code and low-level includes in ``bout++/src``. Many parts of the code -are defined by their interface, and can have multiple different -implementations. An example is the time-integration solvers: many -different implementations are available, some of which use external -libraries, but all have the same interface and can be used +(which can be used in physics models) in ``bout++/include/bout``, and +source code and low-level includes in ``bout++/src``. Many parts of +the code are defined by their interface, and can have multiple +different implementations. An example is the time-integration solvers: +many different implementations are available, some of which use +external libraries, but all have the same interface and can be used interchangeably. This is reflected in the directory structure inside -``bout++/src``. A common pattern is to store individual implementations -of an interface in a subdirectory called ``impls``. +``bout++/src``. A common pattern is to store individual +implementations of an interface in a subdirectory called ``impls``. :: - include/foo.hxx + include/bout/foo.hxx src/.../foo.cxx - src/.../foo_factory.hxx - src/.../foo_factory.cxx src/.../impls/one/one.hxx src/.../impls/one/one.cxx where ``foo.hxx`` defines the interface, ``foo.cxx`` implements common -functions used in several implementations. ``foo_factory`` creates new -implementations, and is the only file which includes all the -implementations. Individual implementations are stored in their own -subdirectories of ``impls``. Components which follow this pattern -include ``fileio`` formats, ``invert/laplace`` and ``invert/parderiv`` -inversion codes, ``mesh``, and ``solver``. +functions used in several implementations. Individual implementations +are stored in their own subdirectories of ``impls``. Components which +follow this pattern include ``invert/laplace`` and ``invert/parderiv`` +inversions, ``mesh``, and ``solver``. -The current source code files are: +The layout of the ``src/`` directory is as follows: -- :doc:`bout++.cxx<../_breathe_autogen/file/bout_09_09_8cxx>`: Main - file which initialises, runs and finalises BOUT++. Currently - contains a `main()` function, though this is being removed shortly. +- :doc:`src/bout++.cxx<../_breathe_autogen/file/bout_09_09_8cxx>`: Main + file which initialises, runs and finalises BOUT++. -- field +- ``src/field`` - - :doc:`field2d.cxx<../_breathe_autogen/file/field2d_8cxx>` - implements the `Field2D` class. This is a scalar field which - varies only in :math:`x` and :math:`y` and is used for things - like metric tensor components and initial profiles. It supplies - lots of overloaded operators and functions on these objects. + - Implementations of "fields" (the scalars `Field2D`, `Field3D`, + `FieldPerp`, and vectors `Vector2D`, `Vector3D`), as well as basic + operations (arithmetic, :ref:`sec-algebraic-ops`, and vector + calculus), and :ref:`initialisation `. - - :doc:`field3d.cxx<../_breathe_autogen/file/field3d_8cxx>` - implements the `Field3D` class, which varies in :math:`x`, - :math:`y` and :math:`z`. Since these handle a lot more memory - than Field2D objects, the memory management is more complicated - and includes reference counting. See section - :ref:`sec-memorymanage` for more details. +- ``src/invert`` - - :doc:`field_data.cxx<../_breathe_autogen/file/field__data_8cxx>` - Implements some functions in the `FieldData` class. This is a - mainly pure virtual interface class which is inherited by - `Field2D` and `Field3D`. + - Implementations of different inverse operators, including Fourier + transforms (via an interface to `FFTW `_, see + `bout::fft::rfft` and `bout::fft::irfft`). - - :doc:`fieldperp.cxx<../_breathe_autogen/file/fieldperp_8cxx>` - implements a `FieldPerp` class to store slices perpendicular to - the magnetic field i.e. they are a function of :math:`x` and - :math:`z` only. This is mainly used for Laplacian inversion - routines, and needs to be integrated with the other fields - better. +- ``src/invert/laplace`` - - :doc:`initialprofiles.cxx<../_breathe_autogen/file/initialprofiles_8cxx>` - routines to set the initial values of fields when a simulation - first starts. Reads settings from the option file based on the name - of the variable. + - Implementations of some inverse generalised Laplacian operator + variations, where some directions may be constant. See + :ref:`sec-laplacian` for more details. - - :doc:`vecops.cxx<../_breathe_autogen/file/vecops_8cxx>` a - collection of function to operate on vectors. Contains things - like ``Grad``, ``Div`` and ``Curl``, and uses a combination of - field differential operators (in - :doc:`difops.cxx<../_breathe_autogen/file/difops_8cxx>`) and - metric tensor components (in `Mesh`). +- ``src/invert/parderiv`` - - :doc:`vector2d.cxx<../_breathe_autogen/file/vector2d_8cxx>` - implements the `Vector2D` class, which uses a `Field2D` object - for each of its 3 components. Overloads operators to supply - things like dot and cross products. + - Inversion of parallel derivatives, intended for use in + preconditioners. See `InvertPar` - - :doc:`vector3d.cxx<../_breathe_autogen/file/vector3d_8cxx>` - implements `Vector3D` by using a `Field3D` - object for each component. +- ``src/invert/pardiv`` - - :doc:`where.cxx<../_breathe_autogen/file/where_8cxx>` supplies - functions for choosing between values based on selection - criteria. + - Inversion of parallel divergence, intended for use in + :ref:`sec-nonlocal-heatflux`. -- invert +- ``src/mesh`` - - :doc:`fft_fftw.cxx<../_breathe_autogen/file/fft__fftw_8cxx>` - implements the :doc:`fft.hxx<../_breathe_autogen/file/fft_8hxx>` - interface by calling the Fastest Fourier Transform in the West - (FFTW) library. + - Implementations of low-level numerical routines. This includes + things like the :ref:`inter-process communications + `, :ref:`boundary conditions `, + :ref:`derivative operators `, interpolation, the + coordinate system (including :ref:`sec-parallel-transforms`), and + the :ref:`sec-mesh` itself. -- invert / laplace +- ``src/physics`` - - :doc:`invert_laplace.cxx<../_breathe_autogen/file/invert__laplace_8cxx>` uses Fourier - decomposition in :math:`z` combined with tri- and band-diagonal - solvers in :math:`x` to solve Laplacian problems. + - This contains some specialised physics operators and routines, + such as gyro-averaging and :ref:`sec-nonlocal-heatflux`. - - impls +- ``src/solver`` - - serial\_tri + - Implementations of :ref:`time integration solvers + ` - - :doc:`serial_tri.hxx<../_breathe_autogen/file/serial__tri_8hxx>` +- ``src/sys`` - - :doc:`serial_tri.cxx<../_breathe_autogen/file/serial__tri_8cxx>` - - - serial\_band - - - :doc:`serial_band.hxx<../_breathe_autogen/file/serial__band_8hxx>` - - - :doc:`serial_band.cxx<../_breathe_autogen/file/serial__band_8cxx>` - - - spt - - - :doc:`spt.hxx<../_breathe_autogen/file/spt_8hxx>` - - - :doc:`spt.cxx<../_breathe_autogen/file/spt_8cxx>` - -- invert / parderiv - - - - :doc:`invert_parderiv.cxx<../_breathe_autogen/file/invert__parderiv_8cxx>` - inverts a problem involving only parallel :math:`y` - derivatives. Intended for use in some preconditioners. - - - impls - - - cyclic - - - :doc:`cyclic.cxx<../_breathe_autogen/file/cyclic_8cxx>` - - - :doc:`cyclic.hxx<../_breathe_autogen/file/cyclic_8hxx>` - -- :doc:`lapack_routines.cxx<../_breathe_autogen/file/lapack__routines_8cxx>` supplies an - interface to the LAPACK linear solvers, which are used by the - ``invert_laplace`` routines. - -- mesh - - - :doc:`boundary_factory.cxx<../_breathe_autogen/file/boundary__factory_8cxx>` creates boundary - condition operators which can then be applied to - fields. Described in section :ref:`sec-BoundaryFactory`. - - - :doc:`boundary_region.cxx<../_breathe_autogen/file/boundary__region_8cxx>` implements a way - to describe and iterate over boundary regions. Created by the - mesh, and then used by boundary conditions. See - section :ref:`sec-BoundaryRegion` for more details. - - - :doc:`boundary_standard.cxx<../_breathe_autogen/file/boundary__standard_8cxx>` implements some - standard boundary operations and modifiers such as ``Neumann`` - and ``Dirichlet``. - - - :doc:`difops.cxx<../_breathe_autogen/file/difops_8cxx>` is a - collection of differential operators on scalar fields. It uses - the differential methods in :doc:`derivs.cxx<../_breathe_autogen/file/derivs_8cxx>` and the metric tensor - components in `Mesh` to compute operators. - - - :doc:`interpolation.cxx<../_breathe_autogen/file/interpolation_8cxx>` contains functions - for interpolating fields - - - :doc:`mesh.cxx<../_breathe_autogen/file/mesh_8cxx>` is the base - class for the `Mesh` object. Contains routines useful - for all `Mesh` implementations. - - - impls - - - bout - - - :doc:`boutmesh.cxx<../_breathe_autogen/file/boutmesh_8cxx>` - implements a mesh interface which is compatible with BOUT - grid files. - - - :doc:`boutmesh.hxx<../_breathe_autogen/file/boutmesh_8hxx>` - -- physics - - - :doc:`gyro_average.cxx<../_breathe_autogen/file/gyro__average_8cxx>` - gyro-averaging operators - - - :doc:`smoothing.cxx<../_breathe_autogen/file/smoothing_8cxx>` - provides smoothing routines on scalar fields - - - :doc:`sourcex.cxx<../_breathe_autogen/file/sourcex_8cxx>` contains - some useful routines for creating sources and sinks in physics - equations. - -- solver - - - :doc:`solver.cxx<../_breathe_autogen/file/solver_8cxx>` is the - interface for all solvers - - - impls - - - cvode - - - :doc:`cvode.cxx<../_breathe_autogen/file/cvode_8cxx>` is the - implementation of `Solver` which interfaces with - the SUNDIALS CVODE library. - - - :doc:`cvode.hxx<../_breathe_autogen/file/cvode_8hxx>` - - - ida - - - :doc:`ida.cxx<../_breathe_autogen/file/ida_8cxx>` is the - implementation which interfaces with the SUNDIALS IDA - library - - - :doc:`ida.hxx<../_breathe_autogen/file/ida_8hxx>` - - - petsc - - - :doc:`petsc.cxx<../_breathe_autogen/file/petsc_8cxx>` is the - interface to the PETSc time integration routines - - - :doc:`petsc.hxx<../_breathe_autogen/file/petsc_8hxx>` - - - pvode - - - :doc:`pvode.cxx<../_breathe_autogen/file/pvode_8cxx>` - interfaces with the 1998 (pre-SUNDIALS) version of PVODE - (which became CVODE). - - - :doc:`pvode.hxx<../_breathe_autogen/file/pvode_8hxx>` - -- sys - - - :doc:`boutcomm.cxx<../_breathe_autogen/file/boutcomm_8cxx>` - - - :doc:`boutexception.cxx<../_breathe_autogen/file/boutexception_8cxx>` - is an exception class which are used for error handling - - - :doc:`derivs.cxx<../_breathe_autogen/file/derivs_8cxx>` contains - basic derivative methods such as upwinding, central difference - and WENO methods. These are then used by - :doc:`difops.cxx<../_breathe_autogen/file/difops_8cxx>`. Details are - given in section :ref:`sec-diffops`. - - - :doc:`msg_stack.cxx<../_breathe_autogen/file/msg__stack_8cxx>` is - part of the error handling system. It maintains a stack of - messages which can be pushed onto the stack at the start of a - function, then removed (popped) at the end. If an error occurs or - a segmentation fault is caught then this stack is printed out and - can help to find errors. - - - :doc:`options.cxx<../_breathe_autogen/file/options_8cxx>` provides - an interface to the BOUT.inp option file and the command-line - options. - - - :doc:`optionsreader.cxx<../_breathe_autogen/file/optionsreader_8cxx>` - - - :doc:`output.cxx<../_breathe_autogen/file/output_8cxx>` - - - :doc:`range.cxx<../_breathe_autogen/file/range_8cxx>` Provides the - RangeIterator class, used to iterate over a set of - ranges. Described in section :ref:`sec-rangeiterator` - - - :doc:`timer.cxx<../_breathe_autogen/file/timer_8cxx>` a class for - timing parts of the code like communications and file - I/O. Described in section :ref:`sec-timerclass` - - - :doc:`utils.cxx<../_breathe_autogen/file/utils_8cxx>` contains - miscellaneous small useful routines such as allocating and - freeing arrays. - - - options - - - :doc:`optionparser.hxx<../_breathe_autogen/file/optionparser_8hxx>` - - - :doc:`options_ini.cxx<../_breathe_autogen/file/options__ini_8cxx>` - - - :doc:`options_ini.hxx<../_breathe_autogen/file/options__ini_8hxx>` + - General purpose utilities used throughout the library, such as + `BoutException`, wrappers for C libraries like ``PETSc`` and + ``HYPRE``, screen and file input and output. diff --git a/manual/sphinx/developer_docs/mesh.rst b/manual/sphinx/developer_docs/mesh.rst index ff3e40d4b0..c592773324 100644 --- a/manual/sphinx/developer_docs/mesh.rst +++ b/manual/sphinx/developer_docs/mesh.rst @@ -1,3 +1,5 @@ +.. _sec-mesh: + Mesh ==== @@ -99,6 +101,8 @@ it:: To read 2D and 3D fields, the branch-cuts need to be taken into account. +.. _sec-communications: + Communications -------------- diff --git a/manual/sphinx/user_docs/variable_init.rst b/manual/sphinx/user_docs/variable_init.rst index 4ac13e0ead..ebe989c233 100644 --- a/manual/sphinx/user_docs/variable_init.rst +++ b/manual/sphinx/user_docs/variable_init.rst @@ -1,3 +1,5 @@ +.. _sec-variable-init: + Variable initialisation ======================= From 297b28430988b871815947071e4bdd7ae461eca2 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:08:31 +0000 Subject: [PATCH 03/29] Docs: Fix underline too short --- manual/sphinx/user_docs/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/sphinx/user_docs/installing.rst b/manual/sphinx/user_docs/installing.rst index eb155909bf..22fc3e724f 100644 --- a/manual/sphinx/user_docs/installing.rst +++ b/manual/sphinx/user_docs/installing.rst @@ -397,7 +397,7 @@ installation for that. Working with an active ``conda`` environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When ``conda`` is used, it installs separate versions of several libraries. These can cause warnings or even failures when linking BOUT++ executables. There are From e6bc5c5d0e85b5e895b124b066bbf62aed6c45b1 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:12:09 +0000 Subject: [PATCH 04/29] Docs: Don't include boutdata/boututils in docs --- manual/sphinx/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/manual/sphinx/conf.py b/manual/sphinx/conf.py index 29c0985841..d8ab76cf23 100755 --- a/manual/sphinx/conf.py +++ b/manual/sphinx/conf.py @@ -31,7 +31,8 @@ import subprocess import sys -sys.path.append("../../tools/pylib") +sys.path.append("../../tools/pylib/boutpp") +sys.path.append("../../tools/pylib/boutconfig") # Are we running on readthedocs? on_readthedocs = os.environ.get("READTHEDOCS") == "True" From 41da8a816f3217c608ca3739330f9f3fc9186902 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:35:11 +0000 Subject: [PATCH 05/29] Docs: Fix reference link --- manual/sphinx/user_docs/physics_models.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/sphinx/user_docs/physics_models.rst b/manual/sphinx/user_docs/physics_models.rst index 56e3b719b4..fa62541f3d 100644 --- a/manual/sphinx/user_docs/physics_models.rst +++ b/manual/sphinx/user_docs/physics_models.rst @@ -28,7 +28,7 @@ either physics models (e.g. ``test-delp2`` and Building Physics Models ----------------------- -After building the library (see :ref:`sec-cmake`), you can build a +After building the library (see :ref:`sec-config-bout`), you can build a physics model in several different ways. For the bundled examples, perhaps the easiest is to build it directly From 96723d088369ad73e8e74329a860a1775395da6c Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:47:00 +0000 Subject: [PATCH 06/29] Docs: Fix bullet points (require blank line before start) --- manual/sphinx/user_docs/installing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/manual/sphinx/user_docs/installing.rst b/manual/sphinx/user_docs/installing.rst index 22fc3e724f..4f47255d2e 100644 --- a/manual/sphinx/user_docs/installing.rst +++ b/manual/sphinx/user_docs/installing.rst @@ -402,14 +402,17 @@ Working with an active ``conda`` environment When ``conda`` is used, it installs separate versions of several libraries. These can cause warnings or even failures when linking BOUT++ executables. There are several alternatives to deal with this problem: + * The simplest but least convenient option is to use ``conda deactivate`` before configuring, compiling, or running any BOUT++ program. + * You might sometimes want to link to the conda-installed libraries. This is probably not ideal for production runs on an HPC system (as conda downloads binary packages that will not be optimized for specific hardware), but can be a simple way to get packages for testing or on a personal computer. In this case just keep your ``conda`` environment active, and with luck the libraries should be picked up by the standard search mechanisms. + * In case you do want a fully optimized and as-stable-as-possible build for production runs, it is probably best not to depend on any conda packages for compiling or running BOUT++ executables (restrict ``conda`` to providing Python From 82c0708b6be5a2db608b5a1b884c76178404c89a Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:47:46 +0000 Subject: [PATCH 07/29] Docs: Fix wrong start of literal block --- manual/sphinx/user_docs/running_bout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/sphinx/user_docs/running_bout.rst b/manual/sphinx/user_docs/running_bout.rst index 59c5b53828..5ee7a9bfb3 100644 --- a/manual/sphinx/user_docs/running_bout.rst +++ b/manual/sphinx/user_docs/running_bout.rst @@ -457,7 +457,7 @@ values loaded, the solver can be started:: 3d fields = 2, 2d fields = 0 neq=100, local_N=100 This last line gives the number of equations being evolved (in this case -100), and the number of these on this processor (here 100).:: +100), and the number of these on this processor (here 100). The absolute and relative tolerances come next:: From e1591bcda65b93788e42392c470461a690307726 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:55:24 +0000 Subject: [PATCH 08/29] Docs: Fix snippet for Scorep --- .../developer_docs/performance_profiling.rst | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/manual/sphinx/developer_docs/performance_profiling.rst b/manual/sphinx/developer_docs/performance_profiling.rst index d93c1e904b..de14d695da 100644 --- a/manual/sphinx/developer_docs/performance_profiling.rst +++ b/manual/sphinx/developer_docs/performance_profiling.rst @@ -85,9 +85,7 @@ Configure and build Configure with ``-BOUT_USE_SCOREP`` to enable Scorep instrumentation, then build as normal. This option can be combined with other options, but it is usually desirable to profile the optimized code, configuring -with the flags ````. Build the code with ``make`` as normal. - -With CMake: +with the flags: .. code-block:: bash @@ -95,14 +93,13 @@ With CMake: -DCMAKE_C_COMPILER=scorep-mpicc \ -DCMAKE_CXX_COMPILER=scorep-mpicxx \ -DCMAKE_CXX_FLAGS=-O3 -DCHECK=0 \ + -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -This will turn off the instrumentation during the configure -step. Please be aware that if you change ``CMakeLists.txt``, CMake -will try to automatically reconfigure the build, which the Score-P -wrappers interfere with. In this case you will need to restart the -configure step from scratch (i.e. remove the build directory and start -again). +``SCOREP_WRAPPER=off`` is used turn off the instrumentation during the +configure step. You probably want to use a fresh build directory to +prevent any issues from cached results when setting the compilers like +this. Run and analysis ~~~~~~~~~~~~~~~~ From dcb33f44a215a267f98a8dcb69a3056e9a4dac5a Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 15:58:41 +0000 Subject: [PATCH 09/29] Docs: Fix unknown role --- manual/sphinx/developer_docs/file_io.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/sphinx/developer_docs/file_io.rst b/manual/sphinx/developer_docs/file_io.rst index aece8cfb1e..0d13e70cfc 100644 --- a/manual/sphinx/developer_docs/file_io.rst +++ b/manual/sphinx/developer_docs/file_io.rst @@ -114,5 +114,5 @@ in the first output file, which `collect` uses to get its type and dimensions. .. [2] Actually, the C++ I/O code should work fine even if a `FieldPerp` object is defined with different y-indices on different processors. This may be useful for diagnostic or debugging purposes. However, Python routines like `collect` and - :py:`boutdata.restart.redistribute` will fail because they find inconsistent + `boutdata.restart.redistribute` will fail because they find inconsistent `yindex_global` values. From aa4a6553394f9420564d12ff8df681a8ba6d0618 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 16:07:44 +0000 Subject: [PATCH 10/29] Docs: Fix syntax for footnote --- manual/sphinx/user_docs/boundary_options.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/sphinx/user_docs/boundary_options.rst b/manual/sphinx/user_docs/boundary_options.rst index 57c6658891..d5e1b9199c 100644 --- a/manual/sphinx/user_docs/boundary_options.rst +++ b/manual/sphinx/user_docs/boundary_options.rst @@ -108,7 +108,7 @@ Boundary conditions for non-orthogonal grids If non-orthogonal grids are used (meaning that the x- and y-directions are not orthogonal, so ``g12 != 0.``), then corner cells may be required. The boundary conditions are applied -in corner cells[#disablecorners]_ by applying the y-boundary condition using x-boundary +in corner cells [#disablecorners]_ by applying the y-boundary condition using x-boundary values. This requires that x-boundary conditions are applied before y-boundary conditions. The ordering is taken care of by the methods described in this section, but also needs to be respected by any custom boundary conditions in user code (e.g. sheath boundary From 6640e940e350c3636d83026f2ee2a60322fb9440 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 17:00:55 +0000 Subject: [PATCH 11/29] Fix a couple of "most vexing parse" that doxygen doesn't like --- include/bout/dcomplex.hxx | 4 +++- include/bout/sys/uuid.h | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/include/bout/dcomplex.hxx b/include/bout/dcomplex.hxx index 569b5f2c13..3bb360b055 100644 --- a/include/bout/dcomplex.hxx +++ b/include/bout/dcomplex.hxx @@ -37,7 +37,9 @@ using dcomplex = std::complex; -const dcomplex Im(0, 1); // 1i +/// Imaginary unit, ``1i`` +//NOLINTNEXTLINE(readability-identifier-length) +constexpr dcomplex Im{0, 1}; /// Complex type for passing data to/from FORTRAN struct fcmplx { diff --git a/include/bout/sys/uuid.h b/include/bout/sys/uuid.h index d043ea780e..edc252bb44 100644 --- a/include/bout/sys/uuid.h +++ b/include/bout/sys/uuid.h @@ -261,7 +261,7 @@ class sha1 { size_t m_byteCount; }; -static std::mt19937 clock_gen(std::random_device{}()); +static std::mt19937 clock_gen{std::random_device{}()}; static std::uniform_int_distribution clock_dis{-32768, 32767}; static std::atomic_short clock_sequence{clock_dis(clock_gen)}; } // namespace detail From 534fe4db38604369f111e1f2020f93e3f005edd6 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Mon, 22 Jan 2024 17:07:50 +0000 Subject: [PATCH 12/29] Docs: Don't keep separate doxygen config for readthedocs --- manual/doxygen/Doxyfile | 1390 +-------------------------- manual/doxygen/Doxyfile_readthedocs | 1119 --------------------- manual/sphinx/conf.py | 5 +- 3 files changed, 19 insertions(+), 2495 deletions(-) delete mode 100644 manual/doxygen/Doxyfile_readthedocs diff --git a/manual/doxygen/Doxyfile b/manual/doxygen/Doxyfile index 216ef60915..e27df586ec 100644 --- a/manual/doxygen/Doxyfile +++ b/manual/doxygen/Doxyfile @@ -246,34 +246,6 @@ ALIASES = TCL_SUBST = -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources -# only. Doxygen will then generate output that is more tailored for C. For -# instance, some of the names that are used will be different. The list of all -# members will be omitted, etc. -# The default value is: NO. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or -# Python sources only. Doxygen will then generate output that is more tailored -# for that language. For instance, namespaces will be presented as packages, -# qualified scopes will look different, etc. -# The default value is: NO. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources. Doxygen will then generate output that is tailored for Fortran. -# The default value is: NO. - -OPTIMIZE_FOR_FORTRAN = NO - -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for VHDL. -# The default value is: NO. - -OPTIMIZE_OUTPUT_VHDL = NO - # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it @@ -328,21 +300,7 @@ AUTOLINK_SUPPORT = YES # diagrams that involve STL classes more complete and accurate. # The default value is: NO. -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. -# The default value is: NO. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen -# will parse them like normal C++ but will assume all classes use public instead -# of private inheritance when no explicit protection keyword is present. -# The default value is: NO. - -SIP_SUPPORT = NO +BUILTIN_STL_SUPPORT = YES # For Microsoft's IDL there are propget and propput attributes to indicate # getter and setter methods for a property. Setting this option to YES will make @@ -352,7 +310,7 @@ SIP_SUPPORT = NO # should set this option to NO. # The default value is: YES. -IDL_PROPERTY_SUPPORT = YES +IDL_PROPERTY_SUPPORT = NO # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES then doxygen will reuse the documentation of the first @@ -435,13 +393,13 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = YES +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. # The default value is: NO. -EXTRACT_PRIVATE = YES +EXTRACT_PRIVATE = NO # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. @@ -463,14 +421,6 @@ EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. If set to YES, local methods, -# which are defined in the implementation section but not in the interface are -# included in the documentation. If set to NO, only methods in the interface are -# included. -# The default value is: NO. - -EXTRACT_LOCAL_METHODS = YES - # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called # 'anonymous_namespace{file}', where file will be replaced with the base name of @@ -508,7 +458,7 @@ HIDE_FRIEND_COMPOUNDS = NO # blocks will be appended to the function's detailed documentation block. # The default value is: NO. -HIDE_IN_BODY_DOCS = NO +HIDE_IN_BODY_DOCS = YES # The INTERNAL_DOCS tag determines if documentation that is typed after a # \internal command is included. If the tag is set to NO then the documentation @@ -590,7 +540,7 @@ SORT_BRIEF_DOCS = NO # detailed member documentation. # The default value is: NO. -SORT_MEMBERS_CTORS_1ST = NO +SORT_MEMBERS_CTORS_1ST = YES # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will @@ -623,19 +573,19 @@ STRICT_PROTO_MATCHING = NO # list. This list is created by putting \todo commands in the documentation. # The default value is: YES. -GENERATE_TODOLIST = YES +GENERATE_TODOLIST = NO # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test # list. This list is created by putting \test commands in the documentation. # The default value is: YES. -GENERATE_TESTLIST = YES +GENERATE_TESTLIST = NO # The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug # list. This list is created by putting \bug commands in the documentation. # The default value is: YES. -GENERATE_BUGLIST = YES +GENERATE_BUGLIST = NO # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) # the deprecated list. This list is created by putting \deprecated commands in @@ -673,7 +623,7 @@ SHOW_USED_FILES = YES # (if specified). # The default value is: YES. -SHOW_FILES = YES +SHOW_FILES = NO # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the @@ -791,7 +741,7 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = ../../include/bout \ - ../../src/ + ../../src # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -858,99 +808,6 @@ EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the -# output. The symbol name can be a fully qualified name, a word, or if the -# wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or directories -# that contain example code fragments that are included (see the \include -# command). - -EXAMPLE_PATH = - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and -# *.h) to filter out the source-files in the directories. If left blank all -# files are included. - -EXAMPLE_PATTERNS = * - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude commands -# irrespective of the value of the RECURSIVE tag. -# The default value is: NO. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or directories -# that contain images that are to be included in the documentation (see the -# \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command: -# -# -# -# where is the value of the INPUT_FILTER tag, and is the -# name of an input file. Doxygen will then use the output that the filter -# program writes to standard output. If FILTER_PATTERNS is specified, this tag -# will be ignored. -# -# Note that the filter must not add or remove lines; it is applied before the -# code is scanned, but not when the output code is generated. If lines are added -# or removed, the anchors will not be placed correctly. -# -# Note that for custom extensions or not directly supported extensions you also -# need to set EXTENSION_MAPPING for the extension otherwise the files are not -# properly processed by doxygen. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: pattern=filter -# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how -# filters are used. If the FILTER_PATTERNS tag is empty or if none of the -# patterns match the file name, INPUT_FILTER is applied. -# -# Note that for custom extensions or not directly supported extensions you also -# need to set EXTENSION_MAPPING for the extension otherwise the files are not -# properly processed by doxygen. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will also be used to filter the input files that are used for -# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). -# The default value is: NO. - -FILTER_SOURCE_FILES = NO - -# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file -# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and -# it is also possible to disable source filtering for a specific pattern using -# *.ext= (so without naming a filter). -# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. - -FILTER_SOURCE_PATTERNS = - -# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that -# is part of the input, its contents will be placed on the main page -# (index.html). This can be useful if you have a project on for instance GitHub -# and want to reuse the introduction page also for the doxygen output. - -USE_MDFILE_AS_MAINPAGE = - #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- @@ -1005,7 +862,7 @@ REFERENCES_LINK_SOURCE = YES # The default value is: YES. # This tag requires that the tag SOURCE_BROWSER is set to YES. -SOURCE_TOOLTIPS = YES +SOURCE_TOOLTIPS = NO # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in @@ -1048,21 +905,6 @@ VERBATIM_HEADERS = NO ALPHABETICAL_INDEX = NO -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all classes will -# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag -# can be used to specify a prefix (or a list of prefixes) that should be ignored -# while generating the index headers. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -IGNORE_PREFIX = - #--------------------------------------------------------------------------- # Configuration options related to the HTML output #--------------------------------------------------------------------------- @@ -1070,542 +912,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a -# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of -# it. -# The default directory is: html. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each -# generated HTML page (for example: .htm, .php, .asp). -# The default value is: .html. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a user-defined HTML header file for -# each generated HTML page. If the tag is left blank doxygen will generate a -# standard header. -# -# To get valid HTML the header file that includes any scripts and style sheets -# that doxygen needs, which is dependent on the configuration options used (e.g. -# the setting GENERATE_TREEVIEW). It is highly recommended to start with a -# default header using -# doxygen -w html new_header.html new_footer.html new_stylesheet.css -# YourConfigFile -# and then modify the file new_header.html. See also section "Doxygen usage" -# for information on how to generate the default header that doxygen normally -# uses. -# Note: The header is subject to change so you typically have to regenerate the -# default header when upgrading to a newer version of doxygen. For a description -# of the possible markers and block names see the documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each -# generated HTML page. If the tag is left blank doxygen will generate a standard -# footer. See HTML_HEADER for more information on how to generate a default -# footer and what special commands can be used inside the footer. See also -# section "Doxygen usage" for information on how to generate the default footer -# that doxygen normally uses. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style -# sheet that is used by each HTML page. It can be used to fine-tune the look of -# the HTML output. If left blank doxygen will generate a default style sheet. -# See also section "Doxygen usage" for information on how to generate the style -# sheet that doxygen normally uses. -# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as -# it is more robust and this tag (HTML_STYLESHEET) will in the future become -# obsolete. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_STYLESHEET = - -# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined -# cascading style sheets that are included after the standard style sheets -# created by doxygen. Using this option one can overrule certain style aspects. -# This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefore more robust against future updates. -# Doxygen will copy the style sheet files to the output directory. -# Note: The order of the extra style sheet files is of importance (e.g. the last -# style sheet in the list overrules the setting of the previous ones in the -# list). For an example see the documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_STYLESHEET = - -# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or -# other source files which should be copied to the HTML output directory. Note -# that these files will be copied to the base HTML output directory. Use the -# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these -# files. In the HTML_STYLESHEET file, use the file name only. Also note that the -# files will be copied as-is; there are no commands or markers available. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_FILES = - -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen -# will adjust the colors in the style sheet and background images according to -# this color. Hue is specified as an angle on a colorwheel, see -# http://en.wikipedia.org/wiki/Hue for more information. For instance the value -# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 -# purple, and 360 is red again. -# Minimum value: 0, maximum value: 359, default value: 220. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_HUE = 220 - -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors -# in the HTML output. For a value of 0 the output will use grayscales only. A -# value of 255 will produce the most vivid colors. -# Minimum value: 0, maximum value: 255, default value: 100. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_SAT = 100 - -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the -# luminance component of the colors in the HTML output. Values below 100 -# gradually make the output lighter, whereas values above 100 make the output -# darker. The value divided by 100 is the actual gamma applied, so 80 represents -# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not -# change the gamma. -# Minimum value: 40, maximum value: 240, default value: 80. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_GAMMA = 80 - -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_DYNAMIC_SECTIONS = NO - -# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries -# shown in the various tree structured indices initially; the user can expand -# and collapse entries dynamically later on. Doxygen will expand the tree to -# such a level that at most the specified number of entries are visible (unless -# a fully collapsed tree already exceeds this amount). So setting the number of -# entries 1 will produce a full collapsed tree by default. 0 is a special value -# representing an infinite number of entries and will result in a full expanded -# tree by default. -# Minimum value: 0, maximum value: 9999, default value: 100. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_INDEX_NUM_ENTRIES = 100 - -# If the GENERATE_DOCSET tag is set to YES, additional index files will be -# generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: http://developer.apple.com/tools/xcode/), introduced with -# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a -# Makefile in the HTML output directory. Running make will produce the docset in -# that directory and running make install will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at -# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_DOCSET = NO - -# This tag determines the name of the docset feed. A documentation feed provides -# an umbrella under which multiple documentation sets from a single provider -# (such as a company or product suite) can be grouped. -# The default value is: Doxygen generated docs. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_FEEDNAME = "Doxygen generated docs" - -# This tag specifies a string that should uniquely identify the documentation -# set bundle. This should be a reverse domain-name style string, e.g. -# com.mycompany.MyDocSet. Doxygen will append .docset to the name. -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_BUNDLE_ID = org.doxygen.Project - -# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. -# The default value is: org.doxygen.Publisher. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_PUBLISHER_ID = org.doxygen.Publisher - -# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. -# The default value is: Publisher. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_PUBLISHER_NAME = Publisher - -# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three -# additional HTML index files: index.hhp, index.hhc, and index.hhk. The -# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on -# Windows. -# -# The HTML Help Workshop contains a compiler that can convert all HTML output -# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML -# files are now used as the Windows 98 help format, and will replace the old -# Windows help format (.hlp) on all Windows platforms in the future. Compressed -# HTML files also contain an index, a table of contents, and you can search for -# words in the documentation. The HTML workshop also contains a viewer for -# compressed HTML files. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_HTMLHELP = NO - -# The CHM_FILE tag can be used to specify the file name of the resulting .chm -# file. You can add a path in front of the file if the result should not be -# written to the html output directory. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -CHM_FILE = - -# The HHC_LOCATION tag can be used to specify the location (absolute path -# including file name) of the HTML help compiler (hhc.exe). If non-empty, -# doxygen will try to run the HTML help compiler on the generated index.hhp. -# The file has to be specified with full path. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -HHC_LOCATION = - -# The GENERATE_CHI flag controls if a separate .chi index file is generated -# (YES) or that it should be included in the master .chm file (NO). -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -GENERATE_CHI = NO - -# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) -# and project file content. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -CHM_INDEX_ENCODING = - -# The BINARY_TOC flag controls whether a binary table of contents is generated -# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it -# enables the Previous and Next buttons. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members to -# the table of contents of the HTML help documentation and to the tree view. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -TOC_EXPAND = NO - -# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that -# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help -# (.qch) of the generated HTML documentation. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_QHP = NO - -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify -# the file name of the resulting .qch file. The path specified is relative to -# the HTML output folder. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QCH_FILE = - -# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help -# Project output. For more information please see Qt Help Project / Namespace -# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_NAMESPACE = org.doxygen.Project - -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt -# Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- -# folders). -# The default value is: doc. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_VIRTUAL_FOLDER = doc - -# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom -# filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_CUST_FILTER_NAME = - -# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_CUST_FILTER_ATTRS = - -# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_SECT_FILTER_ATTRS = - -# The QHG_LOCATION tag can be used to specify the location of Qt's -# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the -# generated .qhp file. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHG_LOCATION = - -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be -# generated, together with the HTML files, they form an Eclipse help plugin. To -# install this plugin and make it available under the help contents menu in -# Eclipse, the contents of the directory containing the HTML and XML files needs -# to be copied into the plugins directory of eclipse. The name of the directory -# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. -# After copying Eclipse needs to be restarted before the help appears. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_ECLIPSEHELP = NO - -# A unique identifier for the Eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have this -# name. Each documentation set should have its own identifier. -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. - -ECLIPSE_DOC_ID = org.doxygen.Project - -# If you want full control over the layout of the generated HTML pages it might -# be necessary to disable the index and replace it with your own. The -# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top -# of each HTML page. A value of NO enables the index and the value YES disables -# it. Since the tabs in the index contain the same information as the navigation -# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -DISABLE_INDEX = NO - -# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. If the tag -# value is set to YES, a side panel will be generated containing a tree-like -# index structure (just like the one that is generated for HTML Help). For this -# to work a browser that supports JavaScript, DHTML, CSS and frames is required -# (i.e. any modern browser). Windows users are probably better off using the -# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can -# further fine-tune the look of the index. As an example, the default style -# sheet generated by doxygen has an example that shows how to put an image at -# the root of the tree instead of the PROJECT_NAME. Since the tree basically has -# the same information as the tab index, you could consider setting -# DISABLE_INDEX to YES when enabling this option. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_TREEVIEW = NO - -# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that -# doxygen will group on one line in the generated HTML documentation. -# -# Note that a value of 0 will completely suppress the enum values from appearing -# in the overview section. -# Minimum value: 0, maximum value: 20, default value: 4. -# This tag requires that the tag GENERATE_HTML is set to YES. - -ENUM_VALUES_PER_LINE = 4 - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used -# to set the initial width (in pixels) of the frame in which the tree is shown. -# Minimum value: 0, maximum value: 1500, default value: 250. -# This tag requires that the tag GENERATE_HTML is set to YES. - -TREEVIEW_WIDTH = 250 - -# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to -# external symbols imported via tag files in a separate window. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -EXT_LINKS_IN_WINDOW = NO - -# Use this tag to change the font size of LaTeX formulas included as images in -# the HTML documentation. When you change the font size after a successful -# doxygen run you need to manually remove any form_*.png images from the HTML -# output directory to force them to be regenerated. -# Minimum value: 8, maximum value: 50, default value: 10. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_FONTSIZE = 10 - -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES - -# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# http://www.mathjax.org) which uses client side Javascript for the rendering -# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX -# installed or if you want to formulas look prettier in the HTML output. When -# enabled you may also need to install MathJax separately and configure the path -# to it using the MATHJAX_RELPATH option. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -USE_MATHJAX = NO - -# When MathJax is enabled you can set the default output format to be used for -# the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/latest/output.html) for more details. -# Possible values are: HTML-CSS (which is slower, but has the best -# compatibility), NativeMML (i.e. MathML) and SVG. -# The default value is: HTML-CSS. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_FORMAT = HTML-CSS - -# When MathJax is enabled you need to specify the location relative to the HTML -# output directory using the MATHJAX_RELPATH option. The destination directory -# should contain the MathJax.js script. For instance, if the mathjax directory -# is located at the same level as the HTML output directory, then -# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax -# Content Delivery Network so you can quickly see the result without installing -# MathJax. However, it is strongly recommended to install a local copy of -# MathJax from http://www.mathjax.org before deployment. -# The default value is: http://cdn.mathjax.org/mathjax/latest. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest - -# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax -# extension names that should be enabled during MathJax rendering. For example -# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_EXTENSIONS = - -# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces -# of code that will be used on startup of the MathJax code. See the MathJax site -# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an -# example see the documentation. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_CODEFILE = - -# When the SEARCHENGINE tag is enabled doxygen will generate a search box for -# the HTML output. The underlying search engine uses javascript and DHTML and -# should work on any modern browser. Note that when using HTML help -# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) -# there is already a search function so this one should typically be disabled. -# For large projects the javascript based search engine can be slow, then -# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to -# search using the keyboard; to jump to the search box use + S -# (what the is depends on the OS and browser, but it is typically -# , /