WIP: TOML Parameters

.github/workflows/docs.yml

@@ -21,14 +21,40 @@ jobs:
         - name: Checkout code
           uses: actions/checkout@v2
           with:
-            fetch-depth: 0
+            submodules: 'true'
         - name: Set system to non-interactive mode
           run: export DEBIAN_FRONTEND=noninteractive
         - name: install dependencies
           run: |
             pip install sphinx
             pip install sphinx-rtd-theme
             pip install sphinx-multiversion
+            sudo apt install -y --force-yes -qq build-essential cmake
+        - name: generate csv files
+          run: |
+            echo "Repo = ${GITHUB_REPOSITORY}"
+            mkdir -p build && cd build
+            cmake -DPARTHENON_DISABLE_HDF5=ON \
+                  -DPARTHENON_DISABLE_MPI=ON \
+                  -DREGRESSION_GOLD_STANDARD_SYNC=OFF \
+                  -DBUILD_TESTING=OFF \
+                  ..
+            make -j4
+            make param-docs
+            cd ..
+        - name: Check generated files for this branch are up to date
+          run: |
+            if git diff --exit-code -- doc/sphinx/src/generated/; then
+              echo "Generated doc files up to date."
+            else
+              echo "Generated doc files not up to date. Run make param-docs and commit changes."
+              exit 1
+            fi
+        - name: Get all git references, needed for sphinx multiversion
+          run: |
+            git fetch --prune --unshallow --tags
+            git branch -a
+            git tag --list
         - name: build docs
           run: |
             echo "Repo = ${GITHUB_REPOSITORY}"

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "external/kokkos"]
 	path = external/Kokkos
 	url = https://github.com/kokkos/kokkos.git
+[submodule "external/tomlplusplus"]
+	path = external/tomlplusplus
+	url = https://github.com/marzer/tomlplusplus.git

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Current develop
 
 ### Added (new features/APIs/variables/...)
+- [[PR 1283]](https://github.com/parthenon-hpc-lab/parthenon/pull/1283) Ability to automatically document ParameterInputs
 - [[PR 1258]](https://github.com/parthenon-hpc-lab/parthenon/pull/1258) Add "corehdf" version of hdf5 output that dumps everything
 - [[PR 1162]](https://github.com/parthenon-hpc-lab/parthenon/pull/1162) Add dev container (e.g., GitHub Codepsacer or VSCode)
 

CMakeLists.txt

@@ -268,6 +268,7 @@ if (NOT TARGET Kokkos::kokkos)
     endif()
   endif()
 endif()
+include_directories("external/tomlplusplus")
 
 # After we have imported Kokkos we can now report/check our config as Kokkos_ENABLE_XXX
 # is also availalbe when imported.
@@ -389,6 +390,7 @@ if (PARTHENON_ENABLE_UNIT_TESTS OR PARTHENON_ENABLE_INTEGRATION_TESTS OR PARTHEN
   add_subdirectory(tst)
 endif()
 
+
 if (PARTHENON_ENABLE_ASCENT)
   if (PARTHENON_USE_SYSTEM_PACKAGES)
     find_package(Ascent REQUIRED)
@@ -401,6 +403,9 @@ endif()
 include(GNUInstallDirs)
 set(CMAKE_INSTALL_INCLUDEDIR "${CMAKE_INSTALL_INCLUDEDIR}/parthenon")
 
+set(DOC_GEN_PATH "${CMAKE_SOURCE_DIR}/doc/sphinx/src/generated" CACHE STRING
+  "Path to save generated data for docs.")
+
 add_subdirectory(src)
 add_subdirectory(example)
 add_subdirectory(benchmarks)
@@ -410,6 +415,13 @@ include(cmake/CheckCopyright.cmake)
 
 configure_file("${PROJECT_SOURCE_DIR}/cmake/parthenonConfig.cmake.in" "${PROJECT_BINARY_DIR}/cmake/parthenonConfig.cmake" @ONLY)
 
+if (NOT PARTHENON_DISABLE_EXAMPLES)
+  add_custom_target(param-docs
+    DEPENDS
+    burgers-csv
+    diffusion-csv)
+endif()
+
 # Currently Ctest/Cmake doesn't ensure that tests are not stale
 # before running them.
 #

benchmarks/burgers/CMakeLists.txt

@@ -25,4 +25,21 @@ if( "burgers-benchmark" IN_LIST DRIVER_LIST OR NOT PARTHENON_DISABLE_EXAMPLES)
   )
   target_link_libraries(burgers-benchmark PRIVATE Parthenon::parthenon)
   lint_target(burgers-benchmark)
+
+  # JMM: Only run burgers in 2D so startup time is reasonable because
+  # -p flag goes through pgen
+  add_custom_command(
+    OUTPUT ${DOC_GEN_PATH}/burgers-table.csv
+    COMMAND ${CMAKE_COMMAND} -E env
+    bash -c
+    "${CMAKE_CURRENT_BINARY_DIR}/burgers-benchmark -i ${CMAKE_CURRENT_LIST_DIR}/burgers.pin parthenon/mesh/nx3=1 parthenon/meshblock/nx3=1 -p '^(?!.*parthenon/).*' > ${DOC_GEN_PATH}/burgers-table.csv"
+    DEPENDS burgers-benchmark burgers.pin
+    VERBATIM
+    )
+
+  add_custom_target(burgers-csv
+    DEPENDS
+    ${DOC_GEN_PATH}/burgers-table.csv
+    )
+
 endif()

doc/sphinx/_static/custom.css

@@ -0,0 +1,18 @@
+/* Enable word wrap in table cells */
+/* JMM: This is preferable IMO but it messed up the word wrapping for
+ * our hand-written tables, so I removed it and enabled wrapping only
+ * for csv-imported tables
+/*
+.rst-content table.docutils td {
+  white-space: normal !important;
+  word-wrap: break-word;
+  word-break: break-word;
+}
+*/
+/* Only apply word wrapping to CSV-imported tables with .csv-wrap class */
+.rst-content table.csv-wrap td {
+  white-space: normal !important;
+  word-wrap: break-word;
+  word-break: break-word;
+}
+

doc/sphinx/conf.py

@@ -50,5 +50,10 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+
+def setup(app):
+    app.add_css_file("custom.css")  # Sphinx >= 1.8
+
+
 # configuration for sphinx_multiversion
 smv_remote_whitelist = r"^(origin)$"

doc/sphinx/src/0_input_parameters_ref.rst

@@ -0,0 +1,48 @@
+.. _inputref:
+
+Input Parameters Reference
+===========================
+
+This reference is automatically generated with Parthenon's
+``ParameterInput`` class. To generate it, pass the ``-p`` flag into a
+parthenon-based executable (in addition to the other flags you would
+normally pass), and optionally a ``regex`` to specify which blocks
+you'd like to output. Parthenon will print a valid CSV file to the
+terminal.
+
+Every call to ``ParameterInput::Get*`` optionally takes a "docustring"
+as a final argument, which is the details column listed here. Default
+values are recorded if they are available.
+
+In Parthenon
+--------------
+
+An incomplete list of all input parameters provided by Parthenon is tabulated below
+
+.. csv-table:: Parthenon input parameters
+   :file: generated/diffusion-parth-table.csv
+   :header-rows: 1
+   :widths: 20 20 10 20 30
+   :class: csv-wrap
+
+In the diffusion example
+----------------------------
+
+The non-parthenon input parameters used in the diffusion example are tabulated below
+
+.. csv-table:: Parthenon input parameters
+   :file: generated/diffusion-table.csv
+   :header-rows: 1
+   :widths: 20 20 10 20 30
+   :class: csv-wrap
+
+In the Burgers benchmark, Parthenon-VIBE
+------------------------------------------
+
+The non-parthenon input parameters used in Parthenon-VIBE are tabulated below
+
+.. csv-table:: Parthenon input parameters
+   :file: generated/burgers-table.csv
+   :header-rows: 1
+   :widths: 20 20 10 20 30
+   :class: csv-wrap

doc/sphinx/src/generated/burgers-table.csv

@@ -0,0 +1,100 @@
+block,parameters,type,default,description
+"burgers","cfl","Real","0.8",""
+"burgers","kx_fact","Real","1",""
+"burgers","ky_fact","Real","1",""
+"burgers","kz_fact","Real","1",""
+"burgers","num_scalars","int","1",""
+"burgers","recon","string","weno5",""
+"","","","",""
+"parthenon.job","output_params_and_exit","bool","0","output a description of all input parameters accessed and quit"
+"parthenon.job","output_params_block_regex","string","(.*)","when outputting input parameters, this selects which input blocks to output; all are output by default"
+"parthenon.job","problem_id","string","parthenon","prefix for output files"
+"parthenon.job","run_only_analysis","bool","",""
+"","","","",""
+"parthenon.loadbalancing","balancer","string","default","load balancing strategy; Allowed values: automatic, default, manual"
+"parthenon.loadbalancing","interval","int","10","how frequently load balancing is performed if the mesh does not change"
+"parthenon.loadbalancing","tolerance","Real","0.5","load balancer tolerance"
+"","","","",""
+"parthenon.mesh","derefine_count","int","10","number of iterations a block must request derefinement before it is derefined"
+"parthenon.mesh","ix1_bc","string","outflow","global mesh boundary condition on inner X1 face"
+"parthenon.mesh","ix2_bc","string","outflow","global mesh boundary condition on inner X2 face"
+"parthenon.mesh","ix3_bc","string","outflow","global mesh boundary condition on inner X3 face"
+"parthenon.mesh","multigrid","bool","0","enable a multigrid mesh"
+"parthenon.mesh","nghost","int","2","number of ghost zones on a block"
+"parthenon.mesh","num_threads","int","1","number of host threads for infrastructure; unused"
+"parthenon.mesh","numlevel","int","1","maximum level of refinement globally"
+"parthenon.mesh","nx1","int","","number of cells on base mesh in x1 direction"
+"parthenon.mesh","nx2","int","","number of cells on base mesh in x2 direction"
+"parthenon.mesh","nx3","int","","number of cells on base mesh in x3 direction"
+"parthenon.mesh","ox1_bc","string","outflow","global mesh boundary condition on outer X1 face"
+"parthenon.mesh","ox2_bc","string","outflow","global mesh boundary condition on outer X2 face"
+"parthenon.mesh","ox3_bc","string","outflow","global mesh boundary condition on outer X3 face"
+"parthenon.mesh","packs_per_rank","int","1","number of meshblockpacks per rank, overrides pack_size"
+"parthenon.mesh","refinement","string","none","mesh refinement mode; Allowed values: adaptive, none, static"
+"parthenon.mesh","refinement_in_one_min_nbufs","int","64",""
+"parthenon.mesh","x1max","Real","","maximum x1 value of domain"
+"parthenon.mesh","x1min","Real","","minimum x1 value of domain"
+"parthenon.mesh","x1rat","Real","1","unused"
+"parthenon.mesh","x2max","Real","","maximum x2 value of domain"
+"parthenon.mesh","x2min","Real","","minimum x2 value of domain"
+"parthenon.mesh","x2rat","Real","1","unused"
+"parthenon.mesh","x3max","Real","","maximum x3 value of domain"
+"parthenon.mesh","x3min","Real","","minimum x3 value of domain"
+"parthenon.mesh","x3rat","Real","1","unused"
+"","","","",""
+"parthenon.meshblock","nx1","int","parthenon.mesh.nx1","logical size of a meshblock; defaults to the base size of the mesh"
+"parthenon.meshblock","nx2","int","parthenon.mesh.nx2","logical size of a meshblock; defaults to the base size of the mesh"
+"parthenon.meshblock","nx3","int","parthenon.mesh.nx3","logical size of a meshblock; defaults to the base size of the mesh"
+"","","","",""
+"parthenon.output0","dn","int","-1","output cadence in cycles"
+"parthenon.output0","dt","Real","0.4","output cadence in physical time"
+"","","","",""
+"parthenon.output1","analysis_output","bool","0",""
+"parthenon.output1","data_format","string","%12.5e",""
+"parthenon.output1","dn","int","-1","output cadence in cycles"
+"parthenon.output1","dt","Real","0.4","output cadence in physical time"
+"parthenon.output1","file_number_width","int","5",""
+"parthenon.output1","file_type","string","","output type"
+"parthenon.output1","ghost_zones","bool","0","whether or not ghost zones are output"
+"parthenon.output1","id","string","out1",""
+"parthenon.output1","use_final_label","bool","1","final output will use the word final instead of a number for its index"
+"","","","",""
+"parthenon.refinement0","derefine_tol","Real","0.05","magnitude that triggers de-refinement"
+"parthenon.refinement0","field","string","NO FIELD WAS SET","Field to refine on"
+"parthenon.refinement0","max_level","int","2","maximum level this refinement criterion will achieve"
+"parthenon.refinement0","method","string","PLEASE SPECIFY method",""
+"parthenon.refinement0","refine_tol","Real","0.5","magnitude that triggers refinement"
+"parthenon.refinement0","vector_i","int","",""
+"","","","",""
+"parthenon.sparse","alloc_threshold","Real","1e-12",""
+"parthenon.sparse","dealloc_count","int","5",""
+"parthenon.sparse","dealloc_threshold","Real","1e-14",""
+"parthenon.sparse","enable_sparse","bool","1",""
+"","","","",""
+"parthenon.swarm","ix1_bc","string","periodic","global particle boundary condition on inner X1 face"
+"parthenon.swarm","ix2_bc","string","periodic","global particle boundary condition on inner X2 face"
+"parthenon.swarm","ix3_bc","string","periodic","global particle boundary condition on inner X3 face"
+"parthenon.swarm","ox1_bc","string","periodic","global particle boundary condition on outer X1 face"
+"parthenon.swarm","ox2_bc","string","periodic","global particle boundary condition on outer X2 face"
+"parthenon.swarm","ox3_bc","string","periodic","global particle boundary condition on outer X3 face"
+"","","","",""
+"parthenon.time","dt","Real","1.7976931e+308","initial value of time step before constraining via cfl"
+"parthenon.time","dt_ceil","Real","1.7976931e+308","maximum allowed timestep"
+"parthenon.time","dt_factor","Real","2","maximum relative change in dt per timestep"
+"parthenon.time","dt_floor","Real","2.2250739e-308","minimum allowed timestep"
+"parthenon.time","dt_force","Real","-1.7976931e+308","if set manually enforces this time step exactly"
+"parthenon.time","dt_init","Real","1.7976931e+308","the first time step will be at least as small as dt_init"
+"parthenon.time","dt_init_force","bool","0","if set to true, the first time step will be exactly dt_init"
+"parthenon.time","dt_max","Real","1.7976931e+308","if timestep is above this level for dt_max_count_max iterations, parthenon throws an error"
+"parthenon.time","dt_max_cycle_limit","int","1","number of cycles where dt > dt_max before error"
+"parthenon.time","dt_min","Real","2.2250739e-308","if timestep falls below this level for dt_min_count_max iterations, parthenon throws an error"
+"parthenon.time","dt_min_cycle_limit","int","10","number of cycles where dt < dt_min before error"
+"parthenon.time","integrator","string","rk2",""
+"parthenon.time","ncycle","int","0","initial iteration count"
+"parthenon.time","ncycle_out","int","1","cadence of outputs to stdout"
+"parthenon.time","ncycle_out_mesh","int","0","cadence of outputs describing mesh"
+"parthenon.time","nlim","int","-1","maximum number of iterations, only limiting if non-negative"
+"parthenon.time","perf_cycle_offset","int","0","don't measure performance for some number of initial cycles"
+"parthenon.time","recv_bdry_buf_timeout_sec","Real","-1",""
+"parthenon.time","start_time","Real","0","physical time at which to start the simulation"
+"parthenon.time","tlim","Real","inf","physical time at which to end the simulation"

doc/sphinx/src/generated/diffusion-parth-table.csv

@@ -0,0 +1 @@
+block,parameters,type,default,description