From 7a6bb6eec7277381596bb1531f00295ac1b61c58 Mon Sep 17 00:00:00 2001 From: Dhairya Malhotra Date: Thu, 3 Aug 2023 00:24:31 -0400 Subject: [PATCH] Update doxygen, add Github pages --- .github/workflows/ghpages.yml | 42 ++ ChangeLog | 0 Doxyfile | 1003 ++++++++++++++++++++++----------- Makefile.am | 13 +- NEWS | 0 README.md | 10 +- TODO | 23 - configure.ac | 5 +- doc/.gitignore | 11 - doc/doc/Makefile.am | 63 --- doc/doc/bibsync.bib | 30 - doc/doc/doc.tex | 499 ---------------- doc/doc/tmp/.dummy | 1 - include/cheb_node.hpp | 3 + include/fmm_cheb.hpp | 6 +- include/fmm_pts.hpp | 16 +- include/fmm_tree.hpp | 4 +- include/mpi_tree.hpp | 2 +- include/pvfmm.h | 31 +- include/pvfmm.hpp | 159 +++--- include/pvfmm.txx | 18 +- src/pvfmm-wrapper.cpp | 10 +- 22 files changed, 880 insertions(+), 1069 deletions(-) create mode 100644 .github/workflows/ghpages.yml delete mode 100644 ChangeLog delete mode 100644 NEWS delete mode 100644 TODO delete mode 100644 doc/.gitignore delete mode 100644 doc/doc/Makefile.am delete mode 100644 doc/doc/bibsync.bib delete mode 100644 doc/doc/doc.tex delete mode 100644 doc/doc/tmp/.dummy diff --git a/.github/workflows/ghpages.yml b/.github/workflows/ghpages.yml new file mode 100644 index 0000000..8ad8050 --- /dev/null +++ b/.github/workflows/ghpages.yml @@ -0,0 +1,42 @@ +name: GitHub Pages + +on: + push: + branches: + - master # Set a branch to deploy + pull_request: + +jobs: + deploy: + runs-on: ubuntu-22.04 + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + steps: + - uses: actions/checkout@v3 + with: + submodules: true + fetch-depth: 0 + + + - name: 'Get Previous tag' + id: previoustag + uses: "WyriHaximus/github-action-get-previous-tag@v1" + with: + fallback: 1.0.0 + + - name: Set env + run: echo "VERSION=${{ steps.previoustag.outputs.tag }}" >> $GITHUB_ENV + + - name: Doxygen Action + uses: mattnotmitt/doxygen-action@v1.1.0 + with: + doxyfile-path: ./Doxyfile + working-directory: . + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/master' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/html + diff --git a/ChangeLog b/ChangeLog deleted file mode 100644 index e69de29..0000000 diff --git a/Doxyfile b/Doxyfile index 1dea9d4..c6ce24f 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.8.5 +# Doxyfile 1.9.2 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -17,11 +17,11 @@ # Project related configuration options #--------------------------------------------------------------------------- -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all text -# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv -# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv -# for the list of possible encodings. +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = $(PROJECT)-$(VERSION) +PROJECT_NAME = PVFMM-$(VERSION) # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -44,12 +44,12 @@ PROJECT_NUMBER = # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = +PROJECT_BRIEF = Parallel Volume Fast Multipole Method -# With the PROJECT_LOGO tag one can specify an logo or icon that is included in -# the documentation. The maximum height of the logo should not exceed 55 pixels -# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo -# to the output directory. +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. PROJECT_LOGO = @@ -58,9 +58,9 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = $(DOCDIR) +OUTPUT_DIRECTORY = ./docs/ -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and # will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where @@ -70,27 +70,37 @@ OUTPUT_DIRECTORY = $(DOCDIR) CREATE_SUBDIRS = NO +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. -# Possible values are: Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese- -# Traditional, Croatian, Czech, Danish, Dutch, English, Esperanto, Farsi, -# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Japanese-en, -# Korean, Korean-en, Latvian, Norwegian, Macedonian, Persian, Polish, -# Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, -# Turkish, Ukrainian and Vietnamese. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. # The default value is: English. OUTPUT_LANGUAGE = English -# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. # The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief # description of a member or function before the detailed description # # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the @@ -108,7 +118,17 @@ REPEAT_BRIEF = YES # the entity):The $name class, The $name widget, The $name file, is, provides, # specifies, contains, represents, a, an and the. -ABBREVIATE_BRIEF = +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief @@ -123,9 +143,9 @@ ALWAYS_DETAILED_SEC = NO # operators of the base classes will not be shown. # The default value is: NO. -INLINE_INHERITED_MEMB = YES +INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the # shortest path that makes the file name unique will be used # The default value is: YES. @@ -142,7 +162,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = $(SRCDIR) +STRIP_FROM_PATH = # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -169,6 +189,16 @@ SHORT_NAMES = NO JAVADOC_AUTOBRIEF = NO +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus @@ -189,15 +219,23 @@ QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. INHERIT_DOCS = YES -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a -# new page for each member. If set to NO, the documentation of a member will be -# part of the file/class/namespace that contains it. +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. # The default value is: NO. SEPARATE_MEMBER_PAGES = NO @@ -212,20 +250,19 @@ TAB_SIZE = 4 # the documentation. An alias has the form: # name=value # For example adding -# "sideeffect=@par Side Effects:\n" +# "sideeffect=@par Side Effects:^^" # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading -# "Side Effects:". You can put \n's in the value part of an alias to insert -# newlines. +# "Side Effects:". Note that you cannot put \n's in the value part of an alias +# to insert newlines (in the resulting output). You can put ^^ in the value part +# of an alias to insert a newline as if a physical newline was in the original +# file. When you need a literal { or } or , in the value part of an alias you +# have to escape them by means of a backslash (\), this can lead to conflicts +# with the commands \{ and \} for these it is advised to use the version @{ and +# @} or use a double escape (\\{ and \\}) ALIASES = -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -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 @@ -254,25 +291,40 @@ OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = 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 # using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# C#, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice, +# VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. # -# Note For files without extension you can use no_extension as a placeholder. +# Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. +# the files are not read by doxygen. When specifying no_extension you should add +# * to the FILE_PATTERNS. +# +# Note see also the list of default file extension mappings. EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable -# documentation. See http://daringfireball.net/projects/markdown/ for details. +# documentation. See https://daringfireball.net/projects/markdown/ for details. # The output of markdown processing is further processed by doxygen, so you can # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. @@ -280,10 +332,19 @@ EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 5. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 5 + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can -# be prevented in individual cases by by putting a % sign in front of the word -# or globally by setting AUTOLINK_SUPPORT to NO. +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. AUTOLINK_SUPPORT = YES @@ -305,7 +366,7 @@ BUILTIN_STL_SUPPORT = YES 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 +# https://www.riverbankcomputing.com/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. @@ -323,13 +384,20 @@ SIP_SUPPORT = NO IDL_PROPERTY_SUPPORT = YES # 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 +# tag is set to YES then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. # The default value is: NO. DISTRIBUTE_GROUP_DOC = NO +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent @@ -384,11 +452,24 @@ TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 0 +# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which effectively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in # documentation are documented, even if no documentation was available. Private # class members and static file members will be hidden unless the # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. @@ -398,35 +479,41 @@ LOOKUP_CACHE_SIZE = 0 EXTRACT_ALL = NO -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will +# 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 = NO -# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. EXTRACT_PACKAGE = NO -# If the EXTRACT_STATIC tag is set to YES all static members of a file will be +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. # The default value is: NO. EXTRACT_STATIC = NO -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined -# locally in source files will be included in the documentation. If set to NO +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, # only classes defined in header files are included. Does not have any effect # for Java sources. # The default value is: YES. EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local methods, +# 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 in the documentation. If set to NO, only methods in the interface are # included. # The default value is: NO. @@ -441,6 +528,13 @@ EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation @@ -451,21 +545,21 @@ HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set -# to NO these classes will be included in the various overviews. This option has -# no effect if EXTRACT_ALL is enabled. +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO these declarations will be -# included in the documentation. +# declarations. If set to NO, these declarations will be included in the +# documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any -# documentation blocks found inside the body of a function. If set to NO these +# documentation blocks found inside the body of a function. If set to NO, these # blocks will be appended to the function's detailed documentation block. # The default value is: NO. @@ -478,28 +572,55 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. +# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# able to match the capabilities of the underlying filesystem. In case the +# filesystem is case sensitive (i.e. it supports files in the same directory +# whose names only differ in casing), the option must be set to YES to properly +# deal with such files in case they appear in the input. For filesystems that +# are not case sensitive the option should be be set to NO to properly deal with +# output files written for symbols that only differ in casing, such as for two +# classes, one named CLASS and the other named Class, and to also support +# references to files without having to specify the exact matching casing. On +# Windows (including Cygwin) and MacOS, users should typically set this option +# to NO, whereas on Linux or other Unix flavors it should typically be set to +# YES. # The default value is: system dependent. CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with -# their full class and namespace scopes in the documentation. If set to YES the +# their full class and namespace scopes in the documentation. If set to YES, the # scope will be hidden. # The default value is: NO. HIDE_SCOPE_NAMES = NO +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_HEADERFILE tag is set to YES then the documentation for a class +# will show which file needs to be included to use the class. +# The default value is: YES. + +SHOW_HEADERFILE = YES + # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. SHOW_INCLUDE_FILES = YES +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. @@ -514,14 +635,15 @@ INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the # (detailed) documentation of file and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. +# name. If set to NO, the members will appear in declaration order. # The default value is: YES. SORT_MEMBER_DOCS = YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. # The default value is: NO. SORT_BRIEF_DOCS = NO @@ -565,27 +687,25 @@ SORT_BY_SCOPE_NAME = NO STRICT_PROTO_MATCHING = NO -# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the -# todo list. This list is created by putting \todo commands in the -# documentation. +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. # The default value is: YES. GENERATE_TODOLIST = YES -# 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 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 -# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug +# 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 -# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( 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 # the documentation. # The default value is: YES. @@ -610,8 +730,8 @@ ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at -# the bottom of the documentation of classes and structs. If set to YES the list -# will mention the files that were used to generate the documentation. +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. # The default value is: YES. SHOW_USED_FILES = YES @@ -645,7 +765,8 @@ FILE_VERSION_FILTER = # output files in an output format independent way. To create the layout file # that represents doxygen's defaults, run doxygen with the -l option. You can # optionally specify a file name after the option, if omitted DoxygenLayout.xml -# will be used as the name of the layout file. +# will be used as the name of the layout file. See also section "Changing the +# layout of pages" for information. # # Note that if you run doxygen from a directory containing a file called # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE @@ -656,11 +777,10 @@ LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the -# search path. Do not use file names with spaces, bibtex cannot handle them. See -# also \cite for info how to create references. +# search path. See also \cite for info how to create references. CITE_BIB_FILES = @@ -676,7 +796,7 @@ CITE_BIB_FILES = QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are -# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES # this implies that the warnings are on. # # Tip: Turn warnings on while writing the documentation. @@ -684,7 +804,7 @@ QUIET = NO WARNINGS = YES -# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. @@ -692,21 +812,39 @@ WARNINGS = YES WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some parameters -# in a documented function, or documenting parameters that don't exist or using -# markup commands wrongly. +# potential errors in the documentation, such as documenting some parameters in +# a documented function twice, or documenting parameters that don't exist or +# using markup commands wrongly. # The default value is: YES. WARN_IF_DOC_ERROR = YES +# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete +# function parameter documentation. If set to NO, doxygen will accept that some +# parameters have no documentation without warning. +# The default value is: YES. + +WARN_IF_INCOMPLETE_DOC = YES + # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return -# value. If set to NO doxygen will only warn about wrong or incomplete parameter -# documentation, but not about the absence of documentation. +# value. If set to NO, doxygen will only warn about wrong parameter +# documentation, but not about the absence of documentation. If EXTRACT_ALL is +# set to YES then this flag will automatically be disabled. See also +# WARN_IF_INCOMPLETE_DOC # The default value is: NO. WARN_NO_PARAMDOC = NO +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# The default value is: NO. + +WARN_AS_ERROR = NO + # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated @@ -730,39 +868,96 @@ WARN_LOGFILE = # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like myfile.cpp or # directories like /usr/src/myproject. Separate the files or directories with -# spaces. +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = $(SRCDIR)/src \ - $(SRCDIR)/include +INPUT = ./ \ + include/ \ + src/ \ + examples/include/ \ + examples/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 # libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: http://www.gnu.org/software/libiconv) for the list of -# possible encodings. +# documentation (see: +# https://www.gnu.org/software/libiconv/) for the list of possible encodings. # The default value is: UTF-8. INPUT_ENCODING = UTF-8 # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and -# *.h) to filter out the source-files in the directories. If left blank the -# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, -# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, -# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, -# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, -# *.qsf, *.as and *.js. - -FILE_PATTERNS = *.cpp \ +# *.h) to filter out the source-files in the directories. +# +# 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 +# read by doxygen. +# +# Note the list of default checked file patterns might differ from the list of +# default file extension mappings. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, +# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C +# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, +# *.vhdl, *.ucf, *.qsf and *.ice. + +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.txx \ + *.c++ \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ *.hpp \ - *.txx + *.h++ \ + *.l \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ + *.m \ + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f18 \ + *.f \ + *.for \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf \ + *.ice + +# *.f90 \ # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. # The default value is: NO. -RECURSIVE = YES +RECURSIVE = NO # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a @@ -811,7 +1006,7 @@ EXAMPLE_PATH = # *.h) to filter out the source-files in the directories. If left blank all # files are included. -EXAMPLE_PATTERNS = +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 @@ -840,6 +1035,10 @@ IMAGE_PATH = # 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 = @@ -849,11 +1048,15 @@ INPUT_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 +# 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. @@ -872,7 +1075,7 @@ FILTER_SOURCE_PATTERNS = # (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 = +USE_MDFILE_AS_MAINPAGE = README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -901,19 +1104,19 @@ INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented -# function all documented functions referencing it will be listed. +# entity all documented functions referencing it will be listed. # The default value is: NO. -REFERENCED_BY_RELATION = YES +REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES then for each documented function # all documented entities called/used by that function will be listed. # The default value is: NO. -REFERENCES_RELATION = YES +REFERENCES_RELATION = NO # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set -# to YES, then the hyperlinks from functions in REFERENCES_RELATION and +# to YES then the hyperlinks from functions in REFERENCES_RELATION and # REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will # link to the documentation. # The default value is: YES. @@ -933,12 +1136,12 @@ SOURCE_TOOLTIPS = YES # 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 # source browser. The htags tool is part of GNU's global source tagging system -# (see http://www.gnu.org/software/global/global.html). You will need version +# (see https://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: # - Install the latest version of global -# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file # - Make sure the INPUT points to the root of the source tree # - Run doxygen as normal # @@ -969,14 +1172,7 @@ VERBATIM_HEADERS = YES # classes, structs, unions or interfaces. # The default value is: YES. -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 +ALPHABETICAL_INDEX = YES # 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 @@ -990,10 +1186,10 @@ IGNORE_PREFIX = # Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = $(GENERATE_HTML) +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 @@ -1052,13 +1248,15 @@ HTML_FOOTER = HTML_STYLESHEET = -# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user- -# defined cascading style sheet that is included after the standard style sheets +# 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 therefor more robust against future updates. -# Doxygen will copy the style sheet file to the output directory. For an example -# see the documentation. +# 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 = @@ -1074,9 +1272,9 @@ HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen -# will adjust the colors in the stylesheet 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 +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a color-wheel, see +# https://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. @@ -1085,7 +1283,7 @@ HTML_EXTRA_FILES = 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 +# in the HTML output. For a value of 0 the output will use gray-scales 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. @@ -1105,11 +1303,23 @@ 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 NO can help when comparing the output of multiple runs. +# 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_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_TIMESTAMP = YES +HTML_DYNAMIC_MENUS = YES # 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 @@ -1134,13 +1344,14 @@ 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 +# environment (see: +# https://developer.apple.com/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. +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1179,8 +1390,12 @@ 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. +# on Windows. In the beginning of 2021 Microsoft took the original page, with +# a.o. the download links, offline the HTML help workshop was already many years +# in maintenance mode). You can download the HTML help workshop from the web +# archives at Installation executable (see: +# http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo +# ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). # # 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 @@ -1192,38 +1407,39 @@ DOCSET_PUBLISHER_NAME = Publisher # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_HTMLHELP = $(GENERATE_HTMLHELP) +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 = ../$(PROJECT).chm +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 +# 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 = $(HHC_PATH) +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 GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the main .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. -GENERATE_CHI = $(GENERATE_CHI) +GENERATE_CHI = NO -# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) +# 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. +# 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. @@ -1234,7 +1450,7 @@ BINARY_TOC = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. -TOC_EXPAND = 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 @@ -1254,7 +1470,8 @@ 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). +# (see: +# https://doc.qt.io/archives/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. @@ -1262,8 +1479,8 @@ 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). +# Folders (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1271,30 +1488,30 @@ 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). +# Filters (see: +# https://doc.qt.io/archives/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). +# Filters (see: +# https://doc.qt.io/archives/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). +# https://doc.qt.io/archives/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. +# The QHG_LOCATION tag can be used to specify the location (absolute path +# including file name) 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 = @@ -1336,16 +1553,28 @@ DISABLE_INDEX = NO # 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 stylesheets (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. +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine tune the look of the index (see "Fine-tuning the output"). 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 + +# When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the +# FULL_SIDEBAR option determines if the side bar is limited to only the treeview +# area (value NO) or if it should extend to the full height of the window (value +# YES). Setting this to YES gives a layout similar to +# https://docs.readthedocs.io with more room for contents, but less room for the +# project logo, title, and description. If either GENERATOR_TREEVIEW or +# DISABLE_INDEX is set to NO, this option has no effect. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = YES +FULL_SIDEBAR = 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. @@ -1364,13 +1593,24 @@ ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to +# 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 +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + # 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 @@ -1380,7 +1620,7 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# Use the FORMULA_TRANSPARENT 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. # @@ -1391,9 +1631,15 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + # 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 prerendered bitmaps. Use this if you do not have LaTeX +# https://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. @@ -1402,11 +1648,29 @@ FORMULA_TRANSPARENT = YES USE_MATHJAX = NO +# With MATHJAX_VERSION it is possible to specify the MathJax version to be used. +# Note that the different versions of MathJax have different requirements with +# regards to the different settings, so it is possible that also other MathJax +# settings have to be changed when switching between the different MathJax +# versions. +# Possible values are: MathJax_2 and MathJax_3. +# The default value is: MathJax_2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_VERSION = MathJax_2 + # 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. +# the MathJax output. For more details about the output format see MathJax +# version 2 (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3 +# (see: +# http://docs.mathjax.org/en/latest/web/components/output.html). # Possible values are: HTML-CSS (which is slower, but has the best -# compatibility), NativeMML (i.e. MathML) and SVG. +# compatibility. This is the name for Mathjax version 2, for MathJax version 3 +# this will be translated into chtml), NativeMML (i.e. MathML. Only supported +# for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This +# is the name for Mathjax version 3, for MathJax version 2 this will be +# translated into HTML-CSS) and SVG. # The default value is: HTML-CSS. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1419,22 +1683,29 @@ MATHJAX_FORMAT = HTML-CSS # 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. +# MathJax from https://www.mathjax.org before deployment. The default value is: +# - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2 +# - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3 # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_RELPATH = # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example +# for MathJax version 2 (see https://docs.mathjax.org/en/v2.7-latest/tex.html +# #tex-and-latex-extensions): # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# For example for MathJax version 3 (see +# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): +# MATHJAX_EXTENSIONS = ams # 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 +# (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1459,15 +1730,15 @@ MATHJAX_CODEFILE = # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -SEARCHENGINE = NO +SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a web server instead of a web client using Javascript. There -# are two flavours of web server based searching depending on the -# EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for -# searching and an index file used by the script. When EXTERNAL_SEARCH is -# enabled the indexing and searching needs to be provided by external tools. See -# the section "External Indexing and Searching" for details. +# implemented using a web server instead of a web client using JavaScript. There +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. # The default value is: NO. # This tag requires that the tag SEARCHENGINE is set to YES. @@ -1479,9 +1750,10 @@ SERVER_BASED_SEARCH = NO # external search engine pointed to by the SEARCHENGINE_URL option to obtain the # search results. # -# Doxygen ships with an example indexer ( doxyindexer) and search engine +# Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). +# Xapian (see: +# https://xapian.org/). # # See the section "External Indexing and Searching" for details. # The default value is: NO. @@ -1492,10 +1764,11 @@ EXTERNAL_SEARCH = NO # The SEARCHENGINE_URL should point to a search engine hosted by a web server # which will return the search results when EXTERNAL_SEARCH is enabled. # -# Doxygen ships with an example indexer ( doxyindexer) and search engine +# Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). See the section "External Indexing and -# Searching" for details. +# Xapian (see: +# https://xapian.org/). See the section "External Indexing and Searching" for +# details. # This tag requires that the tag SEARCHENGINE is set to YES. SEARCHENGINE_URL = @@ -1530,10 +1803,10 @@ EXTRA_SEARCH_MAPPINGS = # Configuration options related to the LaTeX output #--------------------------------------------------------------------------- -# If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output. +# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. # The default value is: YES. -GENERATE_LATEX = $(GENERATE_LATEX) +GENERATE_LATEX = YES # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1546,22 +1819,36 @@ LATEX_OUTPUT = latex # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be # invoked. # -# Note that when enabling USE_PDFLATEX this option is only used for generating -# bitmaps for formulas in the HTML output, but not in the Makefile that is -# written to the output directory. -# The default file is: latex. +# Note that when not enabling USE_PDFLATEX the default is latex when enabling +# USE_PDFLATEX the default is pdflatex and when in the later case latex is +# chosen this is overwritten by pdflatex. For specific output languages the +# default can have been set differently, this depends on the implementation of +# the output language. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_CMD_NAME = # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate # index for LaTeX. +# Note: This tag is used in the Makefile / make.bat. +# See also: LATEX_MAKEINDEX_CMD for the part in the generated output file +# (.tex). # The default file is: makeindex. # This tag requires that the tag GENERATE_LATEX is set to YES. -MAKEINDEX_CMD_NAME = +MAKEINDEX_CMD_NAME = makeindex + +# The LATEX_MAKEINDEX_CMD tag can be used to specify the command name to +# generate index for LaTeX. In case there is no backslash (\) as first character +# it will be automatically added in the LaTeX code. +# Note: This tag is used in the generated output file (.tex). +# See also: MAKEINDEX_CMD_NAME for the part in the Makefile / make.bat. +# The default value is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. -# If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX +LATEX_MAKEINDEX_CMD = makeindex + +# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. @@ -1576,42 +1863,60 @@ COMPACT_LATEX = NO # The default value is: a4. # This tag requires that the tag GENERATE_LATEX is set to YES. -PAPER_TYPE = $(PAPER_SIZE) +PAPER_TYPE = a4 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names -# that should be included in the LaTeX output. To get the times font for -# instance you can specify -# EXTRA_PACKAGES=times +# that should be included in the LaTeX output. The package can be specified just +# by its name or with the correct syntax as to be used with the LaTeX +# \usepackage command. To get the times font for instance you can specify : +# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times} +# To use the option intlimits with the amsmath package you can specify: +# EXTRA_PACKAGES=[intlimits]{amsmath} # If left blank no extra packages will be included. # This tag requires that the tag GENERATE_LATEX is set to YES. EXTRA_PACKAGES = -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the -# generated LaTeX document. The header should contain everything until the first -# chapter. If it is left blank doxygen will generate a standard header. See -# section "Doxygen usage" for information on how to let doxygen write the -# default header to a separate file. +# The LATEX_HEADER tag can be used to specify a user-defined LaTeX header for +# the generated LaTeX document. The header should contain everything until the +# first chapter. If it is left blank doxygen will generate a standard header. It +# is highly recommended to start with a default header using +# doxygen -w latex new_header.tex new_footer.tex new_stylesheet.sty +# and then modify the file new_header.tex. See also section "Doxygen usage" for +# information on how to generate the default header that doxygen normally uses. # -# Note: Only use a user-defined header if you know what you are doing! The -# following commands have a special meaning inside the header: $title, -# $datetime, $date, $doxygenversion, $projectname, $projectnumber. Doxygen will -# replace them by respectively the title of the page, the current date and time, -# only the current date, the version number of doxygen, the project name (see -# PROJECT_NAME), or the project number (see PROJECT_NUMBER). +# Note: Only use a user-defined header if you know what you are doing! +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. The following +# commands have a special meaning inside the header (and footer): For a +# description of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HEADER = -# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the -# generated LaTeX document. The footer should contain everything after the last -# chapter. If it is left blank doxygen will generate a standard footer. -# -# Note: Only use a user-defined footer if you know what you are doing! +# The LATEX_FOOTER tag can be used to specify a user-defined LaTeX footer for +# the generated LaTeX document. The footer should contain everything after the +# last chapter. If it is left blank doxygen will generate a standard footer. See +# LATEX_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. Note: Only use a user-defined footer if you know what you are +# doing! # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_FOOTER = +# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# LaTeX style sheets that are included after the standard style sheets created +# by doxygen. Using this option one can overrule certain style aspects. 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). +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_STYLESHEET = + # The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the LATEX_OUTPUT output # directory. Note that the files will be copied as-is; there are no commands or @@ -1629,22 +1934,23 @@ LATEX_EXTRA_FILES = PDF_HYPERLINKS = YES -# If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate -# the PDF file directly from the LaTeX files. Set this option to YES to get a -# higher quality PDF documentation. +# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as +# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX +# files. Set this option to YES, to get a higher quality PDF documentation. +# +# See also section LATEX_CMD_NAME for selecting the engine. # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. -USE_PDFLATEX = $(GENERATE_PDF) +USE_PDFLATEX = YES # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode # command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. This option is also used -# when generating formulas in HTML. +# if errors occur, instead of asking the user for help. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_BATCHMODE = YES +LATEX_BATCHMODE = NO # If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the # index chapters (such as File Index, Compound Index, etc.) in the output. @@ -1653,34 +1959,40 @@ LATEX_BATCHMODE = YES LATEX_HIDE_INDICES = NO -# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source -# code with syntax highlighting in the LaTeX output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_SOURCE_CODE = NO - # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See -# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. # The default value is: plain. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_BIB_STYLE = plain +# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_TIMESTAMP = NO + +# The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) +# path from which the emoji images will be read. If a relative path is entered, +# it will be relative to the LATEX_OUTPUT directory. If left blank the +# LATEX_OUTPUT directory will be used. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EMOJI_DIRECTORY = + #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- -# If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The +# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The # RTF output is optimized for Word 97 and may not look too pretty with other RTF # readers/editors. # The default value is: NO. -GENERATE_RTF = $(GENERATE_RTF) +GENERATE_RTF = NO # The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1690,13 +2002,13 @@ GENERATE_RTF = $(GENERATE_RTF) RTF_OUTPUT = rtf -# If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF +# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. # This tag requires that the tag GENERATE_RTF is set to YES. -COMPACT_RTF = YES +COMPACT_RTF = NO # If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will # contain hyperlink fields. The RTF file will contain links (just like the HTML @@ -1710,9 +2022,9 @@ COMPACT_RTF = YES RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's config -# file, i.e. a series of assignments. You only have to provide replacements, -# missing definitions are set to their default value. +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# configuration file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. # # See also section "Doxygen usage" for information on how to generate the # default style sheet that doxygen normally uses. @@ -1721,8 +2033,8 @@ RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = # Set optional variables used in the generation of an RTF document. Syntax is -# similar to doxygen's config file. A template extensions file can be generated -# using doxygen -e rtf extensionFile. +# similar to doxygen's configuration file. A template extensions file can be +# generated using doxygen -e rtf extensionFile. # This tag requires that the tag GENERATE_RTF is set to YES. RTF_EXTENSIONS_FILE = @@ -1731,11 +2043,11 @@ RTF_EXTENSIONS_FILE = # Configuration options related to the man page output #--------------------------------------------------------------------------- -# If the GENERATE_MAN tag is set to YES doxygen will generate man pages for +# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for # classes and files. # The default value is: NO. -GENERATE_MAN = $(GENERATE_MAN) +GENERATE_MAN = NO # The MAN_OUTPUT tag is used to specify where the man pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1755,6 +2067,13 @@ MAN_OUTPUT = man MAN_EXTENSION = .3 +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + # If the MAN_LINKS tag is set to YES and doxygen generates man output, then it # will generate one additional man file for each entity documented in the real # man page(s). These additional files only source the real man page, but without @@ -1768,11 +2087,11 @@ MAN_LINKS = NO # Configuration options related to the XML output #--------------------------------------------------------------------------- -# If the GENERATE_XML tag is set to YES doxygen will generate an XML file that +# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = $(GENERATE_XML) +GENERATE_XML = NO # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1782,19 +2101,7 @@ GENERATE_XML = $(GENERATE_XML) XML_OUTPUT = xml -# The XML_SCHEMA tag can be used to specify a XML schema, which can be used by a -# validating XML parser to check the syntax of the XML files. -# This tag requires that the tag GENERATE_XML is set to YES. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify a XML DTD, which can be used by a -# validating XML parser to check the syntax of the XML files. -# This tag requires that the tag GENERATE_XML is set to YES. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program +# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program # listings (including syntax highlighting and cross-referencing information) to # the XML output. Note that enabling this will significantly increase the size # of the XML output. @@ -1803,11 +2110,18 @@ XML_DTD = XML_PROGRAMLISTING = YES +# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include +# namespace members in file scope as well, matching the HTML output. +# The default value is: NO. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_NS_MEMB_FILE_SCOPE = NO + #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- -# If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files +# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files # that can be used to generate PDF. # The default value is: NO. @@ -1825,10 +2139,10 @@ DOCBOOK_OUTPUT = docbook # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- -# If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen -# Definitions (see http://autogen.sf.net) file that captures the structure of -# the code including all documentation. Note that this feature is still -# experimental and incomplete at the moment. +# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an +# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# the structure of the code including all documentation. Note that this feature +# is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO @@ -1837,7 +2151,7 @@ GENERATE_AUTOGEN_DEF = NO # Configuration options related to the Perl module output #--------------------------------------------------------------------------- -# If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module +# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module # file that captures the structure of the code including all documentation. # # Note that this feature is still experimental and incomplete at the moment. @@ -1845,7 +2159,7 @@ GENERATE_AUTOGEN_DEF = NO GENERATE_PERLMOD = NO -# If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary +# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary # Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI # output from the Perl module output. # The default value is: NO. @@ -1853,9 +2167,9 @@ GENERATE_PERLMOD = NO PERLMOD_LATEX = NO -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely +# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely # formatted so it can be parsed by a human reader. This is useful if you want to -# understand what is going on. On the other hand, if this tag is set to NO the +# understand what is going on. On the other hand, if this tag is set to NO, the # size of the Perl module output will be much smaller and Perl will parse it # just the same. # The default value is: YES. @@ -1875,14 +2189,14 @@ PERLMOD_MAKEVAR_PREFIX = # Configuration options related to the preprocessor #--------------------------------------------------------------------------- -# If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all +# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all # C-preprocessor directives found in the sources and include files. # The default value is: YES. ENABLE_PREPROCESSING = YES -# If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names -# in the source code. If set to NO only conditional compilation will be +# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names +# in the source code. If set to NO, only conditional compilation will be # performed. Macro expansion can be done in a controlled way by setting # EXPAND_ONLY_PREDEF to YES. # The default value is: NO. @@ -1898,7 +2212,7 @@ MACRO_EXPANSION = NO EXPAND_ONLY_PREDEF = NO -# If the SEARCH_INCLUDES tag is set to YES the includes files in the +# If the SEARCH_INCLUDES tag is set to YES, the include files in the # INCLUDE_PATH will be searched if a #include is found. # The default value is: YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. @@ -1910,7 +2224,7 @@ SEARCH_INCLUDES = YES # preprocessor. # This tag requires that the tag SEARCH_INCLUDES is set to YES. -INCLUDE_PATH = . +INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the @@ -1928,7 +2242,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = _DOXYGEN +PREDEFINED = # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -1940,9 +2254,9 @@ PREDEFINED = _DOXYGEN EXPAND_AS_DEFINED = # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will -# remove all refrences to function-like macros that are alone on a line, have an -# all uppercase name, and do not end with a semicolon. Such function macros are -# typically used for boiler-plate code, and will confuse the parser if not +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not # removed. # The default value is: YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. @@ -1962,7 +2276,7 @@ SKIP_FUNCTION_MACROS = YES # where loc1 and loc2 can be relative or absolute paths or URLs. See the # section "Linking to external documentation" for more information about the use # of tag files. -# Note: Each tag file must have an unique name (where the name does NOT include +# Note: Each tag file must have a unique name (where the name does NOT include # the path). If a tag file is not located in the directory in which doxygen is # run, you must also specify the path to the tagfile here. @@ -1972,39 +2286,34 @@ TAGFILES = # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = $(DOCDIR)/$(PROJECT).tag +GENERATE_TAGFILE = -# If the ALLEXTERNALS tag is set to YES all external class will be listed in the -# class index. If set to NO only the inherited external classes will be listed. +# If the ALLEXTERNALS tag is set to YES, all external class will be listed in +# the class index. If set to NO, only the inherited external classes will be +# listed. # The default value is: NO. ALLEXTERNALS = NO -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in -# the modules index. If set to NO, only the current project's groups will be +# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. EXTERNAL_GROUPS = YES -# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in +# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in # the related pages index. If set to NO, only the current project's pages will # be listed. # The default value is: YES. EXTERNAL_PAGES = YES -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -PERL_PATH = /usr/bin/false - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram +# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram # (in HTML and LaTeX) for classes with base or super classes. Setting the tag to # NO turns the diagrams off. Note that this option also works with HAVE_DOT # disabled, but it is recommended to install and use dot, since it yields more @@ -2013,16 +2322,14 @@ PERL_PATH = /usr/bin/false CLASS_DIAGRAMS = YES -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. -MSCGEN_PATH = +DIA_PATH = -# If set to YES, the inheritance and collaboration graphs will hide inheritance +# If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2035,7 +2342,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: NO. -HAVE_DOT = $(HAVE_DOT) +HAVE_DOT = NO # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of @@ -2047,7 +2354,7 @@ HAVE_DOT = $(HAVE_DOT) DOT_NUM_THREADS = 0 -# When you want a differently looking font n the dot files that doxygen +# When you want a differently looking font in the dot files that doxygen # generates you can specify the font name using DOT_FONTNAME. You need to make # sure dot is able to find the font, which can be done by putting it in a # standard location or by setting the DOTFONTPATH environment variable or by @@ -2095,7 +2402,7 @@ COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. # The default value is: NO. @@ -2112,17 +2419,39 @@ UML_LOOK = NO # but if the number exceeds 15, the total amount of fields shown is limited to # 10. # Minimum value: 0, maximum value: 100, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. +# This tag requires that the tag UML_LOOK is set to YES. UML_LIMIT_NUM_FIELDS = 10 +# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS +# tag is set to YES, doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# will not generate fields with class member information in the UML graphs. The +# class diagrams will look similar to the default class diagrams but using UML +# notation for the relationships. +# Possible values are: NO, YES and NONE. +# The default value is: NO. +# This tag requires that the tag UML_LOOK is set to YES. + +DOT_UML_DETAILS = NO + +# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters +# to display on a single line. If the actual line length exceeds this threshold +# significantly it will wrapped across multiple lines. Some heuristics are apply +# to avoid ugly line breaks. +# Minimum value: 0, maximum value: 1000, default value: 17. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_WRAP_THRESHOLD = 17 + # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their # instances. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -TEMPLATE_RELATIONS = YES +TEMPLATE_RELATIONS = NO # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to # YES then doxygen will generate a graph for each documented file showing the @@ -2147,7 +2476,8 @@ INCLUDED_BY_GRAPH = YES # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. +# functions only using the \callgraph command. Disabling a call graph can be +# accomplished by means of the command \hidecallgraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2158,7 +2488,8 @@ CALL_GRAPH = NO # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable caller graphs for selected -# functions only using the \callergraph command. +# functions only using the \callergraph command. Disabling a caller graph can be +# accomplished by means of the command \hidecallergraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2181,11 +2512,15 @@ GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. +# generated by dot. For an explanation of the image formats see the section +# output formats in the documentation of the dot tool (Graphviz (see: +# http://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, jpg, gif and svg. +# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# png:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2207,7 +2542,7 @@ INTERACTIVE_SVG = NO # found. If left blank, it is assumed the dot tool can be found in the path. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_PATH = $(DOT_PATH) +DOT_PATH = # The DOTFILE_DIRS tag can be used to specify one or more directories that # contain dot files that are included in the documentation (see the \dotfile @@ -2222,6 +2557,30 @@ DOTFILE_DIRS = MSCFILE_DIRS = +# The DIAFILE_DIRS tag can be used to specify one or more directories that +# contain dia files that are included in the documentation (see the \diafile +# command). + +DIAFILE_DIRS = + +# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the +# path where java can find the plantuml.jar file. If left blank, it is assumed +# PlantUML is not used or called during a preprocessing step. Doxygen will +# generate a warning when it encounters a \startuml command in this case and +# will not generate output for the diagram. + +PLANTUML_JAR_PATH = + +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + +# When using plantuml, the specified paths are searched for files specified by +# the !include statement in a plantuml block. + +PLANTUML_INCLUDE_PATH = + # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes # that will be shown in the graph. If the number of nodes in a graph becomes # larger than this value, doxygen will truncate the graph, which is visualized @@ -2258,7 +2617,7 @@ MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support # this, this feature is disabled by default. @@ -2275,9 +2634,11 @@ DOT_MULTI_TARGETS = NO GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate # files that are used to generate the various graphs. +# +# Note: This setting is not only used for dot files but also for msc temporary +# files. # The default value is: YES. -# This tag requires that the tag HAVE_DOT is set to YES. DOT_CLEANUP = YES diff --git a/Makefile.am b/Makefile.am index ffff45e..c5d553f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -16,8 +16,8 @@ RESULT_DIR = ./result # the subdirectories of the project to go into #SUBDIRS = -DIST_SUBDIRS= \ - doc/doc +#DIST_SUBDIRS = doc/doc + EXTRA_DIST = \ $(EX_DIR)/src \ @@ -26,7 +26,7 @@ EXTRA_DIST = \ $(DX_CONFIG) \ scripts -# additional include pathes necessary to compile the C++ library +# additional include paths necessary to compile the C++ library AM_CXXFLAGS = #AM_LDFLAGS = -static @@ -210,10 +210,7 @@ $(EX_DIR)/bin/%: core # BUILD DOCUMENTATION #------------------------------------------------------------------------------ -pdf-doc: - cd doc/doc && $(MAKE); - -all-docs: doxygen-doc pdf-doc +all-docs: doxygen-doc ############################################################################### # INSTALL/UNINSTALL MakeVariables, pvfmm_config.h @@ -282,10 +279,8 @@ install: install-am @echo '=======================================================================' install-data-local: install-make-variables install-libtool install-doxygen-doc - cd doc/doc && $(MAKE) install; uninstall-local: uninstall-make-variables uninstall-libtool uninstall-doxygen-doc - cd doc/doc && $(MAKE) uninstall; ############################################################################### diff --git a/NEWS b/NEWS deleted file mode 100644 index e69de29..0000000 diff --git a/README.md b/README.md index d8b8404..9992131 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,4 @@ -# PVFMM [![Build Status](https://github.com/dmalhotra/pvfmm/actions/workflows/build.yml/badge.svg)](https://github.com/dmalhotra/pvfmm/actions/workflows/build.yml) -[![Stable Version](https://badgen.net/github/tag/dmalhotra/pvfmm)](https://github.com/dmalhotra/pvfmm/tags) -[![Latest Release](https://img.shields.io/github/v/release/dmalhotra/pvfmm?color=%233D9970)](https://github.com/dmalhotra/pvfmm/releases) +# PVFMM [![Build Status](https://github.com/dmalhotra/pvfmm/actions/workflows/build.yml/badge.svg)](https://github.com/dmalhotra/pvfmm/actions/workflows/build.yml) [![Stable Version](https://badgen.net/github/tag/dmalhotra/pvfmm)](https://github.com/dmalhotra/pvfmm/tags) [![Latest Release](https://img.shields.io/github/v/release/dmalhotra/pvfmm?color=%233D9970)](https://github.com/dmalhotra/pvfmm/releases) ### What is PVFMM? @@ -22,12 +20,12 @@ ### License PVFMM is distributed under the LGPLv3 licence. See COPYING in - the top-level directory of the distribution. + the top-level directory of the distribution. ### Installing PVFMM To install PVFMM, follow the steps in the INSTALL file, which is - located in the top directory of the source distribution. + located in the top directory of the source distribution. ### Using PVFMM @@ -39,7 +37,7 @@ Two very simple examples illustrating usage of the library are available: For particle N-body : examples/src/example1.cpp - For volume potentials: examples/src/example2.cpp + For volume potentials: examples/src/example2.cpp To compile these examples: make examples/bin/example1 diff --git a/TODO b/TODO deleted file mode 100644 index 6ba5229..0000000 --- a/TODO +++ /dev/null @@ -1,23 +0,0 @@ -* Code cleanup. - -* Documentation. - -* Support for Complex: Although we can use tensor kernels to do this, it will -be nice to support complex datatype. - -* GPU support. - - ------------- plots - -** building the function interpolation; -. test functions -Gaussian, very pointed -. order: o=5, o=9 - -Polynomial (discontinuous not grid aligned (triangle)) -. order=5 - -* gaussian and triangle -. n/p is fixed, increase number of processors 8, 64, 512, 4096, 16384, 22656 - diff --git a/configure.ac b/configure.ac index 047daac..e8db531 100644 --- a/configure.ac +++ b/configure.ac @@ -221,10 +221,9 @@ AC_ARG_WITH(precomp-dir, [PRECOMP_DIR="$withval"; AX_NORMALIZE_PATH([PRECOMP_DIR], ["/"]) ]) AC_DEFINE_UNQUOTED(PRECOMP_DATA_PATH,"$PRECOMP_DIR",[Path for precomputed data files.]) -#AC_CONFIG_FILES([Makefile doc/doc/Makefile]) +#AC_CONFIG_FILES([Makefile]) AC_CONFIG_FILES([Makefile - MakeVariables - doc/doc/Makefile]) + MakeVariables]) AC_OUTPUT echo " diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index 67f3aa0..0000000 --- a/doc/.gitignore +++ /dev/null @@ -1,11 +0,0 @@ -*~ -*.aux -*.bbl -*.pdf -*.dvi -*.blg -*.log -/def -/doxygen -/doc/Makefile -/doc/Makefile.in diff --git a/doc/doc/Makefile.am b/doc/doc/Makefile.am deleted file mode 100644 index 0a28dd4..0000000 --- a/doc/doc/Makefile.am +++ /dev/null @@ -1,63 +0,0 @@ -compilePdfOptions= #-interaction=nonstopmode -compile= ${compPdftex} -compPdftex=pdflatex ${compilePdfOptions} - -TARGET = doc.pdf -TEXINFO_TEX = doc.tex -EXTRA_DIST = doc.tex bibsync.bib -INSTALL_DIR = $(DESTDIR)$(datadir)/$(PACKAGE) - -############################################################################### -# COMPILE DOCS -#------------------------------------------------------------------------------ - -if PDFLATEX_OK -filename=doc -doc.pdf: ${SOURCES} - ${compile} ${filename} - -bibtex ${filename} - -bibtex ${filename} - ${compile} ${filename} - ${compile} ${filename} - ${compile} ${filename} - @echo Done ....! - - -############################################################################### -# INSTALL DOCS -#------------------------------------------------------------------------------ - -install-pdf-doc: doc.pdf - $(MKDIR_P) $(INSTALL_DIR)/doc; - $(INSTALL_DATA) ${TARGET} $(INSTALL_DIR)/doc/${TARGET}; - -uninstall-pdf-doc: - $(RM) $(INSTALL_DIR)/doc/${TARGET} - -else - -install-pdf-doc: - -uninstall-pdf-doc: - -endif - - -############################################################################### -# LOCAL INSTALL/UNINSTALL -#------------------------------------------------------------------------------ - -install-data-local: install-pdf-doc - -uninstall-local: uninstall-pdf-doc - - -############################################################################### -# LOCAL CLEAN -#------------------------------------------------------------------------------ - -clean-local: - rm -r -f *.aux *.log *.dvi *.blg *.bbl *.pdf tmp/* - @echo Cleaned ....! - -#------------------------------------------------------------------------------ diff --git a/doc/doc/bibsync.bib b/doc/doc/bibsync.bib deleted file mode 100644 index cb1d2f7..0000000 --- a/doc/doc/bibsync.bib +++ /dev/null @@ -1,30 +0,0 @@ - -@Inproceedings{I_Lashuk_2009, - author = {Lashuk, I. and Chandramowlishwaran, A. and Nguyen, T-A. and Langston, H. and Sampath, R. and Shringarpure, A. and Vuduc, R. and Zorin, D. and Ying, L. and Biros, G.}, - title = {A massively parallel adaptive fast-multipole method on heterogeneous architectures}, - year = {2009}, - booktitle = {SC '09: Proceedings of the 2009 ACM/IEEE conference on Supercomputing}, - pages = {1-12}, - address = {Piscataway, NJ, USA, 2009. IEEE Press} -} -@article{Mousavi_2010, - author = {S. E. Mousavi and N. Sukumar}, - title = {Generalized Duffy transformation for integrating vertex singularities}, - journal = {Computational Mechanics}, - volume = {45}, - year = {2010}, - pages = {127--140}, - doi = {10.1007/s00466-009-0424-1}, - masid = {26198277} -} -@MISC{Sampath_dendro:parallel, - author = {Rahul S. Sampath and Santi S. Adavani and Hari Sundar and Ilya Lashuk and George Biros}, - title = {Dendro: Parallel algorithms for multigrid and AMR methods on 2:1 balanced octrees}, - year = {} -} -@MISC{Ying03akernel-independent, - author = {Lexing Ying and George Biros and Denis Zorin}, - title = {A kernel-independent adaptive fast multipole algorithm in two and three dimensions }, - year = {2003} -} - diff --git a/doc/doc/doc.tex b/doc/doc/doc.tex deleted file mode 100644 index c9d3b1c..0000000 --- a/doc/doc/doc.tex +++ /dev/null @@ -1,499 +0,0 @@ -\documentclass[11pt]{article} -\usepackage{amsmath,amssymb} -\usepackage{subfigure} -\usepackage{algorithm,algorithmic} -\usepackage{graphicx} -\usepackage{url} -\usepackage{fullpage} -%\usepackage{program} -\usepackage{epsfig} -\graphicspath{{figures/}} -\usepackage[usenames,dvipsnames]{color} - -\renewcommand{\algorithmiccomment}[1]{\textcolor{OliveGreen}{//#1}} -\newcommand\LONGCOMMENT[1]{\textcolor{OliveGreen}{/* #1 */}} - -%\newcommand\PARFOR[1]{\\\textbf{parfor} {#1} \textbf{do}\\ \begin{minipage}[b]{0.1\linewidth} { } \end{minipage} \begin{minipage}[b]{\linewidth} } -%\newcommand\ENDPARFOR{\end{minipage}\\\textbf{end parfor}} -\newcommand\PARFOR[1]{\hspace{20 mm}\\\textbf{par}\algorithmicfor\ {#1}\ \algorithmicdo\\\begin{ALC@for}} -\newcommand\ENDPARFOR{\end{ALC@for}\algorithmicend\ \textbf{par}\algorithmicfor} - -\title{KIFMM based Poisson Solver} -\author{Dhairya Malhotra} -%\date{April 12, 2011} - -\begin{document} -\maketitle - - -\section{Problem Statement} -To build a scalable free space Poisson solver using Chebyshev Trees and Kernel -Independent Fast Multipole Method in three dimensions using MPI and OpenMP for -parallelism. - -\section{Outline} -The algorithm consists of two major components, the octree construction and the -Fast Multipole evaluation. - - -\subsection{Octree Construction} -We construct a piecewise polynomial representation of the input from point -samples. A vector of point coordinates and input function values at those -points is taken as the input. The coordinates and the values are sorted -according to their Morton id using a distributed sample sort and a OpenMP -version of merge sort (\ref{merge_sort}). Next, an octree is constructed from -these points by specifying the maximum number of points per box. The sorted -array of points is partitioned among the processes and each process -independently constructs a linear octree for its local set of points using the -algorithm p2oLocal (\ref{p2o_local}). Finally, each of the local octrees is -merged, i.e. the first and the last octant of each partial octree is merged -with the last and the first octant on the previous and the next process -respectively. All of this is done using the tree construction package DENDRO -\cite{Sampath_dendro:parallel}. - - -A chebyshev approximation of the input function is now generated for each -octant of the octree. This is embaressingly parallel. We, determine the -coefficients $c_{i,j,k}$ by solving the following least squares problem. - -\begin{equation} -\underset{c_{i,j,k}}{\operatorname{argmin}}\sum_{p\in{B}}{\Big(f_p-\sum_{0 \le i,j,k A[i+N]$} - \STATE $curr\_node.subdivide()$ - \STATE $curr\_node = curr\_node.child(0)$ \COMMENT {First child (least Morton id).} - \ELSE - \STATE $k = bin\_search( A[i,...,i+N], nxt\_mid )$ - \STATE $curr\_node.assign\_points( A[i, i+1, ... , k-1] )$ - \STATE $curr\_node = curr\_node.preorder\_next()$ \COMMENT {Next node in preorder traversal.} - \STATE $i = k$ - \ENDIF - \ENDWHILE -\end{algorithmic} -\end{algorithm} - -\paragraph{Time Complexity:} -$T(N) = O( \frac{N}{m} \log m )$ \\ -Where, N is the total number of points and m is the maximum number of points -per node of the tree. - -\paragraph{OpenMP Parallelization:} -Shared memory parallelization can be achieved similar to distributed memory -parallelization. The array of sorted points is partitioned equally between each -thread. The octree is now constructed for each part independently by each -thread. And the final octree is obtained by mergin the first and last octant of -each partial octree with the previous and next partial octree respectively. - - -\subsection{Multipole Reduce} -Following the upward FMM pass, we need to add up the multipole expansions of -the nodes which span regions controlled by more than one processor. The -communication between processes required for the reduction of multipole -expansion is mapped to a hypercube network topology. Each process identifies -the list of tree nodes it shares with other processes. These will be the -ancestors of either the first or the last node in the morton sorted list of -leaf nodes. - -Now, in each step, a process exchanges shared nodes with another process that -it is directly connected to in the hypercube topology, moving in the order of -least significant dimension to the most significant dimension of the hypercube. -In each step, shared tree nodes among pairs of adjacent regions are merged -forming a bigger regions such that the only nodes which still need to be -updated are shared across the new bigger regions and the nodes contained -entirely within a region now have the correct multipole expansions. At any -stage in this process, each processor maintains a list of nodes which its -region (the region to which the process belongs) shares with adjacent regions, -i.e. a maximum of $2 * d$ nodes, where d is the maximum depth of the tree. In -each communication step, the shared nodes are exchanged and then each process -independently adds up the multipole expansions of the nodes shared between the -two regions and builds the list of nodes shared by the new region with adjacent -regions. - -\begin{algorithm}[H] -\caption{$MULTIPOLE\_REDUCE$} -\label{multipole_reduce} -\begin{algorithmic} - \STATE $pid$: Rank of this process. - \STATE $p$ : Number of MPI processes. - \STATE $T$ : The partial tree of this process. - \STATE {} - \STATE \COMMENT {Get references to shared nodes.} - \STATE $S1 = \{n: n \in $Ancestors$(\min $ LeafNodes$(T))\}$ - \STATE $S2 = \{n: n \in $Ancestors$(\max $ LeafNodes$(T))\}$ - \FOR {$i=0$ to $\log p$} - \STATE $partner = pid$ XOR $2^i$ - \STATE Send$([S1, S2], partner)$ - \STATE Recv$([R1, R2], partner)$ - \IF {$pid \le partner$} - \STATE Reduce($S2$, $R1$) - \STATE $S2 = R2$ - \ELSE - \STATE Reduce($S1$, $R2$) - \STATE $S1 = R1$ - \ENDIF - \ENDFOR -\end{algorithmic} -\end{algorithm} - -\paragraph{Time Complexity:} -$T(n)=O(t_s \log p + t_w \log p \log N + \log p \log N)$ \\ -Where, $t_s$, $t_w$ are the communication latency and the per-word transfer -time respectively, $p$ is the number of processes, $N$ is the number of nodes -in the complete tree. - - - - -\subsection{Multipole Broadcast} -After the Multipole Reduce step, each octant has its correct multipole -expansion. Now, we build the Locally Essential Tree (LET) by sending octants -from its owner to each of its users. Since we have already completed the -multipole reduction, we make sure that each node that must be broadcast -originates from exactly one process and therefore, we avoid the process of -removing duplicates. - -\begin{algorithm}[H] -\caption{$MULTIPOLE\_BROADCAST$} -\label{multipole_broadcast} -\begin{algorithmic} - \STATE $pid$: Rank of this process. - \STATE $p$ : Number of MPI processes. - \STATE $T$ : The partial tree of this process. - \STATE $mins[]$: Array of minimum Morton id for each process. - \STATE $P_u(x)$: Set of user processes of node x. - \STATE {} - \STATE \COMMENT {Find nodes to be sent.} - \STATE $S = \{s : s \in T$ and $\left|{P_u(s)}\right|>1$ and $s{ public: + /** + * \brief Evaluator function class for input volume density. + */ class Function_t{ typedef void (*FnPtr_t)(const Real_t* coord, int n, Real_t* out); diff --git a/include/fmm_cheb.hpp b/include/fmm_cheb.hpp index d9a8a25..1fafc4e 100644 --- a/include/fmm_cheb.hpp +++ b/include/fmm_cheb.hpp @@ -80,7 +80,7 @@ class FMM_Cheb: public FMM_Pts{ virtual void Source2Up (SetupData& setup_data, bool device=false); /** - * \brief Compute X-List intractions. + * \brief Compute X-List interactions. */ virtual void X_ListSetup(SetupData& setup_data, FMMTree_t* tree, std::vector >& node_data, std::vector >& n_list, int level, bool device); virtual void X_List (SetupData& setup_data, bool device=false); @@ -92,13 +92,13 @@ class FMM_Cheb: public FMM_Pts{ virtual void Down2Target (SetupData& setup_data, bool device=false); /** - * \brief Compute W-List intractions. + * \brief Compute W-List interactions. */ virtual void W_ListSetup(SetupData& setup_data, FMMTree_t* tree, std::vector >& node_data, std::vector >& n_list, int level, bool device); virtual void W_List (SetupData& setup_data, bool device=false); /** - * \brief Compute U-List intractions. + * \brief Compute U-List interactions. */ virtual void U_ListSetup(SetupData& setup_data, FMMTree_t* tree, std::vector >& node_data, std::vector >& n_list, int level, bool device); virtual void U_List (SetupData& setup_data, bool device=false); diff --git a/include/fmm_pts.hpp b/include/fmm_pts.hpp index fd9fe71..41fba18 100644 --- a/include/fmm_pts.hpp +++ b/include/fmm_pts.hpp @@ -90,6 +90,9 @@ struct SetupData{ template class FMM_Tree; +/** + * \brief This class manages all the translation operators for particle FMM. + */ template class FMM_Pts{ @@ -121,8 +124,9 @@ class FMM_Pts{ /** * \brief Initialize all the translation matrices (or load from file). - * \param[in] mult_order Order of multipole expansion. - * \param[in] kernel Kernel functions and related data. + * \param mult_order [in]: the multipole order to be used (even number 2,4,6,8,10,12) + * \param comm [in]: MPI communicator. + * \param kernel [in]: the kernel function pointer to be used. */ void Initialize(int mult_order, const MPI_Comm& comm, const Kernel* kernel); @@ -165,13 +169,13 @@ class FMM_Pts{ virtual void SetM2C(Real_t* dataPtr); /** - * \brief Compute V-List intractions. + * \brief Compute V-List interactions. */ virtual void V_ListSetup(SetupData& setup_data, FMMTree_t* tree, std::vector >& node_data, std::vector >& n_list, int level, bool device); virtual void V_List (SetupData& setup_data, bool device=false); /** - * \brief Compute X-List intractions. + * \brief Compute X-List interactions. */ virtual void X_ListSetup(SetupData& setup_data, FMMTree_t* tree, std::vector >& node_data, std::vector >& n_list, int level, bool device); virtual void X_List (SetupData& setup_data, bool device=false); @@ -189,13 +193,13 @@ class FMM_Pts{ virtual void Down2Target (SetupData& setup_data, bool device=false); /** - * \brief Compute W-List intractions. + * \brief Compute W-List interactions. */ virtual void W_ListSetup(SetupData& setup_data, FMMTree_t* tree, std::vector >& node_data, std::vector >& n_list, int level, bool device); virtual void W_List (SetupData& setup_data, bool device=false); /** - * \brief Compute U-List intractions. + * \brief Compute U-List interactions. */ virtual void U_ListSetup(SetupData& setup_data, FMMTree_t* tree, std::vector >& node_data, std::vector >& n_list, int level, bool device); virtual void U_List (SetupData& setup_data, bool device=false); diff --git a/include/fmm_tree.hpp b/include/fmm_tree.hpp index 90f3d08..b151829 100644 --- a/include/fmm_tree.hpp +++ b/include/fmm_tree.hpp @@ -53,7 +53,7 @@ class FMM_Tree: public MPI_Tree{ void InitFMM_Tree(bool refine, BoundaryType bndry=FreeSpace); /** - * \brief Run FMM + * \brief Setup FMM */ void SetupFMM(FMM_Mat_t* fmm_mat_); @@ -73,7 +73,7 @@ class FMM_Tree: public MPI_Tree{ void BuildInteracLists(); /** - * \brief Upward FMM pass (Including MultipoleReduceBcast). + * \brief Upward FMM pass (including MultipoleReduceBcast). */ void UpwardPass(); diff --git a/include/mpi_tree.hpp b/include/mpi_tree.hpp index 35611a6..ff4df66 100644 --- a/include/mpi_tree.hpp +++ b/include/mpi_tree.hpp @@ -134,7 +134,7 @@ class MPI_Tree: public Tree{ /** * \brief Returns a pointer to the comm object. */ - const MPI_Comm* Comm() {return &comm;} + const MPI_Comm* Comm() const {return &comm;} protected: diff --git a/include/pvfmm.h b/include/pvfmm.h index fb3a8a6..78473ba 100644 --- a/include/pvfmm.h +++ b/include/pvfmm.h @@ -15,6 +15,9 @@ extern "C" { #endif +/** + * \brief Kernel functions + */ enum PVFMMKernel{ PVFMMLaplacePotential = 0, PVFMMLaplaceGradient = 1, @@ -57,26 +60,30 @@ void* PVFMMCreateVolumeFMMF(int m, int q, enum PVFMMKernel kernel, MPI_Comm comm * * \param[in] fn_ptr the input function pointer. * + * \param[in] fn_ctx a context pointer to be passed to fn_ptr. + * * \param[in] trg_coord the target coordinate vector with values: [x1 y1 z1 ... * xn yn zn] where (x1 y1 z1) are the coordinates of the first target point. * + * \param[in] n_trg number of target points. + * * \param[in] comm MPI communicator. * * \param[in] tol the tolerance for adaptive refinement. * - * \param[in] max_ptr the maximum number of target points per leaf node. + * \param[in] max_pts the maximum number of target points per leaf node. * * \param[in] periodic whether to use periodic boundary conditions. * - * \param[in] init_depth the depth of the initial tree defore adaptive + * \param[in] init_depth the depth of the initial tree before adaptive * refinement. If zero then the depth is the minimum depth so that the number * of leaf nodes is greater than the size of the MPI communicator. * * \return the pointer to the constructed tree. It must be destroyed using * PVFMMDestroyVolumeTreeD to free the resources. */ -void* PVFMMCreateVolumeTreeD(int cheb_deg, int data_dim, void (*fn_ptr)(const double* coord, long n, double* out, void* ctx), void* fn_ctx, double* trg_coord, long n_trg, MPI_Comm comm, double tol, int max_pts, bool periodic, int init_depth); -void* PVFMMCreateVolumeTreeF(int cheb_deg, int data_dim, void (*fn_ptr)(const float* coord, long n, float* out, void* ctx), void* fn_ctx, float* trg_coord, long n_trg, MPI_Comm comm, float tol, int max_pts, bool periodic, int init_depth); +void* PVFMMCreateVolumeTreeD(int cheb_deg, int data_dim, void (*fn_ptr)(const double* coord, long n, double* out, const void* ctx), const void* fn_ctx, const double* trg_coord, long n_trg, MPI_Comm comm, double tol, int max_pts, bool periodic, int init_depth); +void* PVFMMCreateVolumeTreeF(int cheb_deg, int data_dim, void (*fn_ptr)(const float* coord, long n, float* out, const void* ctx), const void* fn_ctx, const float* trg_coord, long n_trg, MPI_Comm comm, float tol, int max_pts, bool periodic, int init_depth); /** * \brief Construct a piecewise Chebyshev volume discretization in [0,1]^3. It @@ -89,6 +96,8 @@ void* PVFMMCreateVolumeTreeF(int cheb_deg, int data_dim, void (*fn_ptr)(const fl * coefficients in each leaf node is * data_dim*(cheb_deg+1)(cheb_deg+2)(cheb_deg+3)/6. * + * \param[in] data_dim the number of scalar values per point in the input density. + * * \param[in] leaf_coord A vector of points [x1 y1 z1 ... xn yn zn] where each * point corresponds to a leaf node in the tree. * @@ -99,6 +108,8 @@ void* PVFMMCreateVolumeTreeF(int cheb_deg, int data_dim, void (*fn_ptr)(const fl * \param[in] trg_coord the target coordinate vector with values: [x1 y1 z1 ... * xn yn zn] where (x1 y1 z1) are the coordinates of the first target point. * + * \param[in] n_trg number of target points. + * * \param[in] comm MPI communicator. * * \param[in] periodic whether to use periodic boundary conditions. @@ -117,15 +128,15 @@ void* PVFMMCreateVolumeTreeFromCoeffF(long Nleaf, int cheb_deg, int data_dim, co * \param[out] trg_value the computed potential at the target points (in * array-of-structure order). * - * \param[in] tree the pointer to the Chebyshev tree. + * \param[in,out] tree the pointer to the Chebyshev tree. * * \param[in] fmm the volume FMM context pointer. * * \param[in] loc_size the local size of the output vector (used to partition * it among the MPI ranks). */ -void PVFMMEvaluateVolumeFMMD(double* trg_val, void* tree, const void* fmm, long loc_size); -void PVFMMEvaluateVolumeFMMF(float* trg_val, void* tree, const void* fmm, long loc_size); +void PVFMMEvaluateVolumeFMMD(double* trg_value, void* tree, const void* fmm, long loc_size); +void PVFMMEvaluateVolumeFMMF(float* trg_value, void* tree, const void* fmm, long loc_size); /** @@ -162,7 +173,7 @@ long PVFMMGetLeafCountF(const void* tree); /** * \brief Get the leaf node coordinates. * - * \param[in] leaf_coord A vector of points [x1 y1 z1 ... xn yn zn] where each + * \param[out] leaf_coord A vector of points [x1 y1 z1 ... xn yn zn] where each * point corresponds to a leaf node in the tree. * * \param[in] tree the pointer to the Chebyshev tree. @@ -273,8 +284,8 @@ void* PVFMMCreateContextF(float box_size, int n, int m, enum PVFMMKernel kernel, * \param[in] setup a flag to indicate if the source or target particle * positions have changed and therefore additional setup must be performed. */ -void PVFMMEvalD(const double* src_pos, const double* sl_den, const double* dl_den, long n_src, const double* trg_pos, double* trg_val, long n_trg, void* ctx, int setup); -void PVFMMEvalF(const float* src_pos, const float* sl_den, const float* dl_den, long n_src, const float* trg_pos, float* trg_val, long n_trg, void* ctx, int setup); +void PVFMMEvalD(const double* src_pos, const double* sl_den, const double* dl_den, long n_src, const double* trg_pos, double* trg_val, long n_trg, const void* ctx, int setup); +void PVFMMEvalF(const float* src_pos, const float* sl_den, const float* dl_den, long n_src, const float* trg_pos, float* trg_val, long n_trg, const void* ctx, int setup); /** * \brief Destroy the particle FMM context. diff --git a/include/pvfmm.hpp b/include/pvfmm.hpp index e7d2333..34db708 100644 --- a/include/pvfmm.hpp +++ b/include/pvfmm.hpp @@ -20,12 +20,31 @@ namespace pvfmm{ // Volume FMM interface -// Volume FMM data types +/** + * \brief Octree node class for volume FMM. + * \see pvfmm::FMM_Node, pvfmm::Cheb_Node + */ template using ChebFMM_Node = FMM_Node>; -template using ChebFMM = FMM_Cheb>; + +/** + * \brief Manages all the translation operators for volume FMM. + * \see pvfmm::FMM_Cheb + */ +template using ChebFMM = FMM_Cheb>; + +/** + * \brief The octree class for volume FMM. + * \see pvfmm::FMM_Tree + */ template using ChebFMM_Tree = FMM_Tree>; -template using ChebFMM_Data = typename ChebFMM_Node::NodeData; -template using ChebFn = typename ChebFMM_Node::Function_t; + +//template using ChebFMM_Data = typename ChebFMM_Node::NodeData; + +/** + * \brief Evaluator function class for input volume density. + * \see pvfmm::Cheb_Node::Function_t + */ +template using ChebFn = typename ChebFMM_Node::Function_t; /** * \brief Construct a piecewise Chebyshev volume discretization in [0,1]^3. It @@ -35,35 +54,35 @@ template using ChebFn = typename ChebFMM_Node::Function * node are less than max_pts. It further refines the tree to satisfy the 2:1 * balance constraint. * - * \param[in] cheb_deg The degree of the Chebyshev polynomials. The number of + * \param[in] cheb_deg degree of the Chebyshev polynomials. The number of * coefficients in each leaf node is * data_dim*(cheb_deg+1)(cheb_deg+2)(cheb_deg+3)/6. * - * \param[in] data_dim The number of scalar values per point in the evaluation + * \param[in] data_dim number of scalar values per point in the evaluation * of the input function pointer (fn_ptr). * - * \param[in] fn_ptr The input function pointer. + * \param[in] fn_ptr input function pointer. * - * \param[in] trg_coord The target coordinate vector with values: [x1 y1 z1 ... + * \param[in] trg_coord target coordinate vector with values: [x1 y1 z1 ... * xn yn zn] where (x1 y1 z1) are the coordinates of the first target point. * * \param[in] comm MPI communicator. * - * \param[in] tol the tolerance for adaptive refinement. + * \param[in] tol tolerance for adaptive refinement. * - * \param[in] max_ptr The maximum number of target points per leaf node. + * \param[in] max_pts maximum number of target points per leaf node. * - * \param[in] bndry The type of boundary conditions (FreeSpace or Periodic) + * \param[in] bndry type of boundary conditions (FreeSpace or Periodic) * - * \param[in] init_depth The depth of the initial tree defore adaptive + * \param[in] init_depth depth of the initial tree before adaptive * refinement. If zero then the depth is the minimum depth so that the number * of leaf nodes is greater than the size of the MPI communicator. * - * \return The pointer to the constructed tree. It must be destroyed using + * \return pointer to the constructed tree. It must be destroyed using * delete to free the resources. */ template -ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, int data_dim, ChebFn fn_ptr, std::vector& trg_coord, MPI_Comm comm, +ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, int data_dim, ChebFn fn_ptr, const std::vector& trg_coord, MPI_Comm comm, Real tol=1e-6, int max_pts=100, BoundaryType bndry=FreeSpace, int init_depth=0); @@ -72,27 +91,27 @@ ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, int data_dim, ChebFn * first constructs a tree with the given leaf node coordinates and then adds * the Chebyshev coefficient to each leaf node. * - * \param[in] cheb_deg The degree of the Chebyshev polynomials. + * \param[in] cheb_deg degree of the Chebyshev polynomials. * - * \param[in] leaf_coord A vector of points [x1 y1 z1 ... xn yn zn] where each + * \param[in] leaf_coord vector of points [x1 y1 z1 ... xn yn zn] where each * point corresponds to a leaf node in the tree. * - * \param[in] fn_coeff The vector of Chebyshev coefficients of size + * \param[in] fn_coeff vector of Chebyshev coefficients of size * Nleaf*data_dim*(cheb_deg+1)(cheb_deg+2)(cheb_deg+3)/6, where * Nleaf=leaf_coord.size()/3 is the number of leaf nodes. * - * \param[in] trg_coord The target coordinate vector with values: [x1 y1 z1 ... + * \param[in] trg_coord target coordinate vector with values: [x1 y1 z1 ... * xn yn zn] where (x1 y1 z1) are the coordinates of the first target point. * * \param[in] comm MPI communicator. * - * \param[in] bndry The type of boundary conditions (FreeSpace or Periodic) + * \param[in] bndry type of boundary conditions (FreeSpace or Periodic) * - * \return The pointer to the constructed tree. It must be destroyed using + * \return pointer to the constructed tree. It must be destroyed using * delete to free the resources. */ template -ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, std::vector& leaf_coord, std::vector& fn_coeff, std::vector& trg_coord, MPI_Comm comm, BoundaryType bndry); +ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, const std::vector& leaf_coord, const std::vector& fn_coeff, const std::vector& trg_coord, MPI_Comm comm, BoundaryType bndry); /** @@ -101,47 +120,51 @@ ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, std::vector& leaf_coo * \note ChebFMM_Tree::SetupFMM(ChebFMM*) must be called before evaluating FMM for * the first time with a tree, or when a tree has changed. * - * \param[out] trg_value The computed potential at the target points (in + * \param[out] trg_value computed potential at the target points (in * array-of-structure order). * - * \param[in] tree The pointer to the Chebyshev tree. + * \param[in,out] tree pointer to the Chebyshev tree. * - * \param[in] loc_size The local size of the output vector (used to partition + * \param[in] loc_size local size of the output vector (used to partition * it among the MPI ranks). */ template -void ChebFMM_Evaluate(std::vector& trg_val, ChebFMM_Tree* tree, size_t loc_size=0); +void ChebFMM_Evaluate(std::vector& trg_value, ChebFMM_Tree* tree, size_t loc_size=0); /** * \brief Get the Chebyshev coefficients for the potential. * - * \param[out] coeff The vector of Chebyshev coefficients for the potential of + * \param[out] coeff vector of Chebyshev coefficients for the potential of * size Nleaf*data_dim*(cheb_deg+1)(cheb_deg+2)(cheb_deg+3)/6, where Nleaf is * the number of leaf nodes. + * + * \param[in] tree pointer to the Chebyshev tree. */ template -void ChebFMM_GetPotentialCoeff(std::vector& coeff, ChebFMM_Tree* tree); +void ChebFMM_GetPotentialCoeff(std::vector& coeff, const ChebFMM_Tree* tree); /** * \brief Get the leaf node coordinates. * - * \param[in] leaf_coord A vector of points [x1 y1 z1 ... xn yn zn] where each + * \param[out] leaf_coord vector of points [x1 y1 z1 ... xn yn zn] where each * point corresponds to a leaf node in the tree. + * + * \param[in] tree pointer to the Chebyshev tree. */ template -void ChebFMM_GetLeafCoord(std::vector& leaf_coord, ChebFMM_Tree* tree); +void ChebFMM_GetLeafCoord(std::vector& leaf_coord, const ChebFMM_Tree* tree); /** * \brief Evaluate Chebyshev coefficients at tensor product Chebyshev nodes of * first kind. * - * \param[out] node_val node_val The function values at tensor product Chebyshev nodes. + * \param[out] node_val node_val function values at tensor product Chebyshev nodes. * - * \param[in] ChebDeg The degree of Chebyshev polynomials. + * \param[in] ChebDeg degree of Chebyshev polynomials. * - * \param[in] dof The number of scalar values at each node point. + * \param[in] dof number of scalar values at each node point. * - * \param[in] coeff The vector of Chebyshev coefficients. + * \param[in] coeff vector of Chebyshev coefficients. */ template void ChebFMM_Coeff2Nodes(std::vector& node_val, int ChebDeg, int dof, const std::vector& coeff); @@ -151,13 +174,13 @@ void ChebFMM_Coeff2Nodes(std::vector& node_val, int ChebDeg, int dof, cons * \brief Convert function values on tensor product Chebyshev nodes (first * kind nodes) to coefficients. * - * \param[out] coeff The vector of Chebyshev coefficients. + * \param[out] coeff vector of Chebyshev coefficients. * - * \param[in] ChebDeg The degree of Chebyshev polynomials. + * \param[in] ChebDeg degree of Chebyshev polynomials. * - * \param[in] dof The number of scalar values at each node point. + * \param[in] dof number of scalar values at each node point. * - * \param[in] node_val The function values at tensor product Chebyshev nodes. + * \param[in] node_val function values at tensor product Chebyshev nodes. */ template void ChebFMM_Nodes2Coeff(std::vector& coeff, int ChebDeg, int dof, const std::vector& node_val); @@ -169,28 +192,30 @@ namespace pvfmm{ // Particle FMM interface /** * \brief Manages all the precomputed matrices and implements all the * translation operations in FMM. An instance of PtFMM must be created and - * initialized with the kernel function to be used: - * PtFMM::Initialize(int mult_order, MPI_Comm comm, const Kernel* kernel, const Kernel* aux_kernel=NULL); + * initialized with the kernel function to be used. * - * mult_order [in]: the multipole order to be used (even number 2,4,6,8,10,12) - * comm [in]: MPI communicator. - * kernel_fn [in]: the kernel function pointer to be used. - * kernel_fn_aux [in]: (optional) Used for V-list translations. + * \see pvfmm::FMM_Pts, pvfmm::PtFMM::Initialize */ template using PtFMM = FMM_Pts>>; /** - * \brief The FMM tree data structure. + * \brief The FMM tree data structure. + * + * \see pvfmm::FMM_Tree */ template using PtFMM_Tree = FMM_Tree>; /** * \brief The node data structure used in the tree. + * + * \see pvfmm::FMM_Node, pvfmm::MPI_Node */ template using PtFMM_Node = FMM_Node>; /** - * The data used to initialize the tree. + * \brief The data used to initialize the tree. + * + * \see pvfmm::FMM_Node::NodeData, pvfmm::MPI_Node::NodeData */ template using PtFMM_Data = typename PtFMM_Node::NodeData; @@ -200,33 +225,33 @@ template using PtFMM_Data = typename PtFMM_Node::NodeData; * \brief Create a new instance of the tree and return a pointer. The tree must * eventually be be destroyed by calling delete. * - * \param[in] sl_coord The single-layer source coordinate vector with values: + * \param[in] sl_coord single-layer source coordinate vector with values: * [x1 y1 z1 ... xn yn zn] where (x1 y1 z1) are the coordinates of the first * source point. The coordinates must be in [0,1]^3. * - * \param[in] sl_density The single-layer source density vector with values: + * \param[in] sl_density single-layer source density vector with values: * [u1 v1 w1 ... un vn wn] where (u1 v1 w1) is the density vector for the first * particle. * - * \param[in] dl_coord The double-layer source coordinate vector with values: + * \param[in] dl_coord double-layer source coordinate vector with values: * [x1 y1 z1 ... xn yn zn] where (x1 y1 z1) are the coordinates of the first * source point. The coordinates must be in [0,1]^3. * - * \param[in] dl_density The double-layer source density vector with values: + * \param[in] dl_density double-layer source density vector with values: * [u1 v1 w1 nx1 ny1 nz1 ... un vn wn nxn nyn nzn] where (u1 v1 w1) is the * density vector for the first particle and (nx1 ny1 nz1) is the normal vector * for the first particle. * - * \param[in] trg_coord The target coordinate vector with values: [x1 y1 z1 ... + * \param[in] trg_coord target coordinate vector with values: [x1 y1 z1 ... * xn yn zn] where (x1 y1 z1) are the coordinates of the first target point. * * \param[in] comm MPI communicator. * - * \param[in] max_pts Maximum number of source points per octant. + * \param[in] max_pts maximum number of source points per octant. * - * \param[in] bndry Boundary type (FreeSpace or Periodic) + * \param[in] bndry boundary type (FreeSpace or Periodic) * - * \param[in] init_depth Minimum depth for any octant + * \param[in] init_depth minimum depth for any octant */ template PtFMM_Tree* PtFMM_CreateTree(const std::vector& sl_coord, const std::vector& sl_density, @@ -238,26 +263,26 @@ PtFMM_Tree* PtFMM_CreateTree(const std::vector& sl_coord, const std: * \brief Create a new instance of the tree and return a pointer. The tree must * eventually be be destroyed by calling delete. * - * \param[in] sl_coord The single-layer source coordinate vector with values: + * \param[in] sl_coord single-layer source coordinate vector with values: * [x1 y1 z1 ... xn yn zn] where (x1 y1 z1) are the coordinates of the first * source point. The coordinates must be in [0,1]^3. * - * \param[in] sl_density The single-layer source density vector with values: + * \param[in] sl_density single-layer source density vector with values: * [u1 v1 w1 u2 ... un vn wn] where (u1 v1 w1) is the density vector for the * first particle. * - * \param[in] trg_coord The target coordinate vector with values: [x1 y1 z1 ... + * \param[in] trg_coord target coordinate vector with values: [x1 y1 z1 ... * xn yn zn] where (x1 y1 z1) are the coordinates of the first target point. * * \param[in] comm MPI communicator. * - * \param[in] max_pts Maximum number of source points per octant. + * \param[in] max_pts maximum number of source points per octant. * - * \param[in] bndry Boundary type (FreeSpace or Periodic) + * \param[in] bndry boundary type (FreeSpace or Periodic) * - * \param[in] init_depth Minimum depth for any octant. + * \param[in] init_depth minimum depth for any octant. * - * \return The pointer to the constructed tree. + * \return pointer to the constructed tree. */ template PtFMM_Tree* PtFMM_CreateTree(const std::vector& sl_coord, const std::vector& sl_density, @@ -270,22 +295,22 @@ PtFMM_Tree* PtFMM_CreateTree(const std::vector& sl_coord, const std: * called before evaluating FMM for the first time with a tree, or if a tree * has changed. * - * \note PtFMM_Tree::SetupFMM(PtFMM*) must be called before evaluating FMM for + * \note pvfmm::PtFMM_Tree::SetupFMM(PtFMM*) must be called before evaluating FMM for * the first time with a tree, or when a tree has changed. * - * \param[in] tree Pointer to the octree. + * \param[in] tree pointer to the octree. * - * \param[out] trg_val The target potential vector with values: [p1 q1 r1 ... + * \param[out] trg_val target potential vector with values: [p1 q1 r1 ... * pn qn rn] where (p1 q1 r1) is the potential at the first target point. * - * \param[in] loc_size Number of local target points. + * \param[in] loc_size number of local target points. * - * \param[in] sl_density The new single-layer source density vector. + * \param[in] sl_density new single-layer source density vector. * - * \param[in] dl_density The new double-layer source density vector. + * \param[in] dl_density new double-layer source density vector. */ template -void PtFMM_Evaluate(PtFMM_Tree* tree, std::vector& trg_val, size_t loc_size=0, const std::vector* sl_density=NULL, const std::vector* dl_density=NULL); +void PtFMM_Evaluate(const PtFMM_Tree* tree, std::vector& trg_val, size_t loc_size=0, const std::vector* sl_density=NULL, const std::vector* dl_density=NULL); } diff --git a/include/pvfmm.txx b/include/pvfmm.txx index 2074b14..09d9ad2 100644 --- a/include/pvfmm.txx +++ b/include/pvfmm.txx @@ -14,13 +14,13 @@ namespace pvfmm{ template -inline ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, int data_dim, ChebFn fn_ptr, std::vector& trg_coord, MPI_Comm comm, +inline ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, int data_dim, ChebFn fn_ptr, const std::vector& trg_coord, MPI_Comm comm, Real tol, int max_pts, BoundaryType bndry, int init_depth){ int np, myrank; MPI_Comm_size(comm, &np); MPI_Comm_rank(comm, &myrank); - ChebFMM_Data tree_data; + typename ChebFMM_Node::NodeData tree_data; tree_data.cheb_deg=cheb_deg; tree_data.data_dof=data_dim; tree_data.input_fn=fn_ptr; @@ -57,12 +57,12 @@ inline ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, int data_dim, ChebFn } template -inline ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, std::vector& node_coord, std::vector& fn_coeff, std::vector& trg_coord, MPI_Comm comm, BoundaryType bndry){ +inline ChebFMM_Tree* ChebFMM_CreateTree(int cheb_deg, const std::vector& node_coord, const std::vector& fn_coeff, const std::vector& trg_coord, MPI_Comm comm, BoundaryType bndry){ int np, myrank; MPI_Comm_size(comm, &np); MPI_Comm_rank(comm, &myrank); - ChebFMM_Data tree_data; + typename ChebFMM_Node::NodeData tree_data; tree_data.input_fn=ChebFn(); tree_data.tol=0; bool adap=false; @@ -254,10 +254,10 @@ inline PtFMM_Tree* PtFMM_CreateTree(const std::vector& src_coord, co } template -inline void PtFMM_Evaluate(PtFMM_Tree* tree, std::vector& trg_val, size_t loc_size, const std::vector* src_val, const std::vector* surf_val){ +inline void PtFMM_Evaluate(const PtFMM_Tree* tree, std::vector& trg_val, size_t loc_size, const std::vector* src_val, const std::vector* surf_val){ if(src_val){ std::vector src_scatter_; - const auto& nodes=tree->GetNodeList(); + const auto& nodes=((PtFMM_Tree*)tree)->GetNodeList(); for(size_t i=0;iIsLeaf() && !nodes[i]->IsGhost()){ const auto& src_scatter=nodes[i]->src_scatter; @@ -282,7 +282,7 @@ inline void PtFMM_Evaluate(PtFMM_Tree* tree, std::vector& trg_val, s } if(surf_val){ std::vector surf_scatter_; - const auto& nodes=tree->GetNodeList(); + const auto& nodes=((PtFMM_Tree*)tree)->GetNodeList(); for(size_t i=0;iIsLeaf() && !nodes[i]->IsGhost()){ const auto& surf_scatter=nodes[i]->surf_scatter; @@ -305,13 +305,13 @@ inline void PtFMM_Evaluate(PtFMM_Tree* tree, std::vector& trg_val, s } } } - tree->RunFMM(); + ((PtFMM_Tree*)tree)->RunFMM(); Vector trg_value; Vector trg_scatter; { std::vector trg_value_; std::vector trg_scatter_; - const auto& nodes=tree->GetNodeList(); + const auto& nodes=((PtFMM_Tree*)tree)->GetNodeList(); for(size_t i=0;iIsLeaf() && !nodes[i]->IsGhost()){ const auto& trg_value=nodes[i]->trg_value; diff --git a/src/pvfmm-wrapper.cpp b/src/pvfmm-wrapper.cpp index f84979c..546135a 100644 --- a/src/pvfmm-wrapper.cpp +++ b/src/pvfmm-wrapper.cpp @@ -26,7 +26,7 @@ void* PVFMMCreateVolumeFMMF(int m, int q, enum PVFMMKernel kernel, MPI_Comm comm return (void*)matrices; } -void* PVFMMCreateVolumeTreeF(int cheb_deg, int data_dim, void (*fn_ptr)(const float* coord, long n, float* out, void* ctx), void* fn_ctx, float* trg_coord, long n_trg, MPI_Comm comm, float tol, int max_pts, bool periodic, int init_depth) { +void* PVFMMCreateVolumeTreeF(int cheb_deg, int data_dim, void (*fn_ptr)(const float* coord, long n, float* out, const void* ctx), const void* fn_ctx, const float* trg_coord, long n_trg, MPI_Comm comm, float tol, int max_pts, bool periodic, int init_depth) { const int COORD_DIM = 3; std::vector trg_coord_(n_trg*COORD_DIM); #pragma omp parallel for schedule(static) @@ -134,7 +134,7 @@ void* PVFMMCreateVolumeFMMD(int m, int q, enum PVFMMKernel kernel, MPI_Comm comm return (void*)matrices; } -void* PVFMMCreateVolumeTreeD(int cheb_deg, int data_dim, void (*fn_ptr)(const double* coord, long n, double* out, void* ctx), void* fn_ctx, double* trg_coord, long n_trg, MPI_Comm comm, double tol, int max_pts, bool periodic, int init_depth) { +void* PVFMMCreateVolumeTreeD(int cheb_deg, int data_dim, void (*fn_ptr)(const double* coord, long n, double* out, const void* ctx), const void* fn_ctx, const double* trg_coord, long n_trg, MPI_Comm comm, double tol, int max_pts, bool periodic, int init_depth) { const int COORD_DIM = 3; std::vector trg_coord_(n_trg*COORD_DIM); #pragma omp parallel for schedule(static) @@ -433,7 +433,7 @@ template static void* PVFMMCreateContext(Real box_size, int n, in return ctx; } -template static void PVFMMEval(const Real* src_pos, const Real* sl_den, const Real* dl_den, size_t n_src, const Real* trg_pos, Real* trg_val, size_t n_trg, void* ctx_, int setup){ +template static void PVFMMEval(const Real* src_pos, const Real* sl_den, const Real* dl_den, size_t n_src, const Real* trg_pos, Real* trg_val, size_t n_trg, const void* ctx_, int setup){ size_t omp_p=omp_get_max_threads(); typedef pvfmm::FMM_Node > Node_t; @@ -880,7 +880,7 @@ void* PVFMMCreateContextF(float box_size, int n, int m, enum PVFMMKernel kernel, return PVFMMCreateContext(box_size, n, m, PVFMM_MAX_DEPTH, ker, comm); } -void PVFMMEvalF(const float* src_pos, const float* sl_den, const float* dl_den, long n_src, const float* trg_pos, float* trg_val, long n_trg, void* ctx, int setup) { +void PVFMMEvalF(const float* src_pos, const float* sl_den, const float* dl_den, long n_src, const float* trg_pos, float* trg_val, long n_trg, const void* ctx, int setup) { PVFMMEval(src_pos, sl_den, dl_den, n_src, trg_pos, trg_val, n_trg, ctx, setup); } @@ -900,7 +900,7 @@ void* PVFMMCreateContextD(double box_size, int n, int m, enum PVFMMKernel kernel return PVFMMCreateContext(box_size, n, m, PVFMM_MAX_DEPTH, ker, comm); } -void PVFMMEvalD(const double* src_pos, const double* sl_den, const double* dl_den, long n_src, const double* trg_pos, double* trg_val, long n_trg, void* ctx, int setup) { +void PVFMMEvalD(const double* src_pos, const double* sl_den, const double* dl_den, long n_src, const double* trg_pos, double* trg_val, long n_trg, const void* ctx, int setup) { PVFMMEval(src_pos, sl_den, dl_den, n_src, trg_pos, trg_val, n_trg, ctx, setup); }