Skip to content

Latest commit

 

History

History
136 lines (98 loc) · 6.95 KB

README.md

File metadata and controls

136 lines (98 loc) · 6.95 KB
Raw

Parthenon documentation

This file provides an overview of different (not necessarily all) features in Parthenon and how to use them.

Building parthenon

See the build doc for details on building parthenon for specific systems.

Description of examples

Short feature description

Automated tests

Regression and convergence tests that cover the majority of features are based on the Advection example and defined in the advection-convergence and output_hdf5 test suites.

The tests currently cover

  • advection of wave in x, y, and z direction as well oblique to the static grid for different resolutions to demonstrate first order convergence (see tst/regression/outputs/advection_convergence/advection-errors.png file in the build directory after running the test)
  • Advection of a smoothed sphere at an angle on a static grid, on a static grid a twice the resolution, and with AMR covering the sphere at the effective higher resolution
  • Advection of a sharp sphere at an angle with AMR writing hdf5 output and comparing against a gold standard output.

To execute the tests run, e.g.,

# from within the build directory (add -V fore more detailed output)
ctest -R regression

The gold standard files (reference solutions) used in the regression tests should automatically be downloaded during the configure phase. Alternatively, you can download them as a release from GitHub and extract the contents of the archive to PARTHENON_ROOT/tst/regression/gold_standard directory. Make sure to get the correct version matching your source (stored in the REGRESSION_GOLD_STANDARD_VER CMake variable). Note: If you results are (slightly) different, that may stem from using different compiler/optimization options.

In case you adds new tests that require reference data just put all file in the PARTHENON_ROOT/tst/regression/gold_standard directory and either

  • increase the version integer by one (both in the PARTHENON_ROOT/tst/regression/gold_standard/current_version file and in the PARTHENON_ROOT/CMakeLists.txt file), or
  • configure with REGRESSION_GOLD_STANDARD_SYNC=OFF. The former is considered the safer option as it prevents accidental overwriting of those files during configure (as REGRESSION_GOLD_STANDARD_SYNC is ON by default). In the pull request of the suggested changes we will then update the official gold standard release file and appropriate hash prior to merging.

ParthenonManager

This class provides a streamlined capability to write new applications by providing a simple interface to initialize and finalize a simulation. It's usage is straightforward and demonstrated in the π example.

User-specified internal functions

During a simulation, Parthenon calls a number of default internal functions whose behavior can be redefined by an application. Currently, these functions are, by class:

ParthenonManager

  • SetFillDerivedFunctions Each package can register a function pointer in the Packages_t object that provides a callback mechanism for derived quantities (e.g. velocity, from momentum and mass) to be filled. Additionally, this function provides a mechanism to register functions to fill derived quantities before and/or after all the individual package calls are made. This is particularly useful for derived quantities that are shared by multiple packages.
  • ProcessProperties Constructs and returns a Properties_t object that is often filled with runtime specified (i. e. determined from the input file) settings and parameters. For example, this might hold an equation of state.
  • ProcessPackages Constructs and returns a Packages_t object that contains a listing of all the variables and their metadata associated with each package.

Mesh

  • InitUserMeshData
  • MeshUserWorkInLoop
  • UserWorkAfterLoop

MeshBlock

  • InitApplicationMeshBlockData
  • InitUserMeshBlockData
  • ProblemGenerator
  • MeshBlockUserWorkInLoop
  • UserWorkBeforeOutput

To redefine these functions, the user sets the respective function pointers in the ApplicationInput member app_input of the ParthenonManager class prior to calling ParthenonInit. This is demonstrated in the main() functions in the examples.

Error checking

Macros for causing execution to throw an exception are provided here

  • PARTHENON_REQUIRE(condition, message) exits if the condition does not evaluate to true.
  • PARTHENON_REQUIRE_THROWS(condition, message) throws a std::runtime_error exception if the condition does not evaluate to true.
  • PARTHENON_FAIL(message) always exits.
  • PARTHENON_THROW(message) throws a runtime error.
  • PARTHENON_DEBUG_REQUIRE(condition, message) exits if the condition does not evaluate to true when in debug mode.
  • PARTHENON_DEBUG_REQUIRE_THROWS(condition, message) throws if the condition does not evaluate to true when in debug mode.
  • PARTHENON_DEBUG_FAIL(message) always exits when in debug mode.
  • PARTHENON_DEBUG_THROW(message) throws a runtime error when in debug mode.

All macros print the message, and filename and line number where the macro is called. PARTHENON_REQUIRE also prints the condition. The macros take a std::string, a std::stringstream, or a C-style string. As a rule of thumb:

  • Use the exception throwing versions in non-GPU, non-performance critical code.
  • On GPUs and in performance-critical sections, use the non-throwing versions and give them C-style strings.

Developer guide

Please see the full development guide on how to use Kokkos-based performance portable abstractions available within Parthenon and how to write performance portable code.

State Management

Full Documentation

Parthenon provides a convenient means of managing simulation data. Variables can be registered with Parthenon to have the framework automatically manage the field, including updating ghost cells, prolongation, restriction, and I/O.

Application Drivers

A description of the Parthenon-provided classes that facilitate developing the high-level functionality of an application (e..g. time stepping) can be found here.

Adaptive Mesh Refinement

A description of how to enable and extend the AMR capabilities of Parthenon is provided here.

Tasks

The tasking capabilities in Parthenon are documented here.

Outputs

Check here for a description of how to get data out of Parthenon and how to visualize it.

Containers and Container Iterators

See here for a description of containers, container iterators, and variable packs.

Index Shape and Index Range

A description of mesh indexing classes here.