-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #334 from lanl/jmm/plugin
Add plugin infrastructure
- Loading branch information
Showing
17 changed files
with
717 additions
and
56 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| #------------------------------------------------------------------------------# | ||
| # © 2024. Triad National Security, LLC. All rights reserved. This | ||
| # program was produced under U.S. Government contract 89233218CNA000001 | ||
| # for Los Alamos National Laboratory (LANL), which is operated by Triad | ||
| # National Security, LLC for the U.S. Department of Energy/National | ||
| # Nuclear Security Administration. All rights in the program are | ||
| # reserved by Triad National Security, LLC, and the U.S. Department of | ||
| # Energy/National Nuclear Security Administration. The Government is | ||
| # granted for itself and others acting on its behalf a nonexclusive, | ||
| # paid-up, irrevocable worldwide license in this material to reproduce, | ||
| # prepare derivative works, distribute copies to the public, perform | ||
| # publicly and display publicly, and to permit others to do so. | ||
| #------------------------------------------------------------------------------# | ||
|
|
||
| set_property(GLOBAL PROPERTY EOS_HEADERS "") | ||
| set_property(GLOBAL PROPERTY _install_headers "") | ||
| function(register_headers) | ||
| set(keyword_args PLUGIN) | ||
| cmake_parse_arguments(ARG "" "${keyword_args}" "" ${ARGN}) | ||
| set(variadic_args ${ARG_UNPARSED_ARGUMENTS}) | ||
|
|
||
| get_property(eos_headers GLOBAL PROPERTY EOS_HEADERS) | ||
| get_property(install_headers GLOBAL PROPERTY _install_headers) | ||
|
|
||
| foreach(arg IN LISTS variadic_args) | ||
| file(RELATIVE_PATH relative_path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}) | ||
| if (ARG_PLUGIN) | ||
| list(APPEND eos_headers ${relative_path}/${ARG_PLUGIN}/${arg}) | ||
| list(APPEND install_headers ${ARG_PLUGIN}/${arg}) | ||
| else() | ||
| list(APPEND eos_headers ${relative_path}/${arg}) | ||
| list(APPEND install_headers ${relative_path}/${arg}) | ||
| endif() | ||
| endforeach() | ||
| set_property(GLOBAL PROPERTY EOS_HEADERS "${eos_headers}") | ||
| set_property(GLOBAL PROPERTY _install_headers "${install_headers}") | ||
| endfunction() | ||
|
|
||
| set_property(GLOBAL PROPERTY EOS_SRCS "") | ||
| function(register_srcs) | ||
| get_property(eos_srcs GLOBAL PROPERTY EOS_SRCS) | ||
| foreach(arg IN LISTS ARGN) | ||
| file(RELATIVE_PATH relative_path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}) | ||
| list(APPEND eos_srcs ${relative_path}/${arg}) | ||
| endforeach() | ||
| set_property(GLOBAL PROPERTY EOS_SRCS "${eos_srcs}") | ||
| endfunction() | ||
|
|
||
| set(PLUGIN_TESTS "") | ||
| set_property(GLOBAL PROPERTY PLUGIN_TESTS "") | ||
| function(register_tests) | ||
| get_property(plugin_tests GLOBAL PROPERTY PLUGIN_TESTS) | ||
| foreach(arg IN LISTS ARGN) | ||
| list(APPEND plugin_tests ${CMAKE_CURRENT_SOURCE_DIR}/${arg}) | ||
| endforeach() | ||
| set_property(GLOBAL PROPERTY PLUGIN_TESTS "${plugin_tests}") | ||
| endfunction() | ||
|
|
||
| set_property(GLOBAL PROPERTY PLUGIN_INCLUDE_PATHS "") | ||
| macro(export_plugin) | ||
| get_property(plugin_include_paths GLOBAL PROPERTY PLUGIN_INCLUDE_PATHS) | ||
| list(APPEND plugin_include_paths ${CMAKE_CURRENT_SOURCE_DIR}) | ||
| set_property(GLOBAL PROPERTY PLUGIN_INCLUDE_PATHS "${plugin_include_paths}") | ||
| endmacro() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,143 @@ | ||
| .. _customization: | ||
|
|
||
| Customizing ``singularity-eos`` | ||
| ================================ | ||
|
|
||
| Custom Variant | ||
| --------------- | ||
|
|
||
| If you would like to create your own custom variant with additional | ||
| models (or a subset of models), you may do so by using the | ||
| ``eos_variant`` class. For example, | ||
|
|
||
| .. code-block:: cpp | ||
|
|
||
| #include <singularity-eos/eos.hpp> | ||
| using namespace singularity; | ||
|
|
||
| using MyEOS_t = eos_variant<IdealGas, Gruneisen>; | ||
|
|
||
| This will create a new type, ``MyEOS_t`` which contains only the | ||
| ``IdealGas`` and ``Gruneisen`` classes. (All of these live under the | ||
| ``singularity`` namespace.) | ||
|
|
||
| Plugins | ||
| -------- | ||
|
|
||
| .. warning:: | ||
|
|
||
| Plugins are currently an experimental feature. Use at your own risk. | ||
|
|
||
| ``singularity-eos`` is also extensible via a plugins | ||
| infrastructure. Via plugins, you may define additional equations of | ||
| state and have them automatically built, tested, and installed by the | ||
| library. You may even include them in the default ``singularity-eos`` | ||
| variant type. | ||
|
|
||
| .. note:: | ||
|
|
||
| We note that a downstream code built on ``singularity-eos`` may | ||
| have no need of a plugin infrastructure, as you can write your own | ||
| EOS models and and choose your own ``Variant`` type for your code | ||
| all within your context. Plugins are a way of adding arbitrary code | ||
| to ``singularity-eos`` that you may wish to share accross multiple | ||
| downstream codes (for example). | ||
|
|
||
| The easiest way to explain how to add a plugin is probably by | ||
| example. In the ``example`` directory of the ``singularity-eos`` | ||
| source tree is a ``plugin`` subdirectory containing an example | ||
| plugin. The example plugin contains an implementation of astrophysical | ||
| dust. In this context dust is a pressure-less gas. We implement this | ||
| with an equation of state that always returns zero pressure, but has a | ||
| temperature and specific heat. | ||
|
|
||
| The plugin directory contains a ``CMakeLists.txt`` file (described | ||
| more below) and a subdirectory named ``dust``, which contains the | ||
| source code. The name of the subdirectory will specify how it may be | ||
| included in code referencing the plugin. For example, to include the | ||
| dust equation of state explicitly, a user of this plugin would use the | ||
| include statement | ||
|
|
||
| .. code-block:: cpp | ||
|
|
||
| #include <dust/dust.hpp> | ||
|
|
||
| You may have as many subdirectories as you like, one for each "include | ||
| path" you want to make available. | ||
|
|
||
| The plugin directory also contains a ``tst`` directory, which contains | ||
| an implementation file ``tst/test_dust.cpp``, which contains several | ||
| Catch2 tests. See the contribution guide for a longer discussion of | ||
| the ``singularity-eos`` testing infrastructure. | ||
|
|
||
| The ``CMakeLists.txt`` file registers the plugin with the build system | ||
| via several custom ``cmake`` functions provided by | ||
| ``singularity-eos``. To register a header file (and most files in | ||
| ``singularity-eos`` should be header files) we use (for example) | ||
|
|
||
| .. code-block:: | ||
|
|
||
| register_headers(PLUGIN dust dust.hpp dust_variant.hpp) | ||
|
|
||
| This specifies that the ``dust`` subdirectory contains two header | ||
| files that the infrastructure should know about: ``dust.hpp`` and | ||
| ``dust_variant.hpp``. One such line is required for every additional | ||
| top-level subdirectory of the plugin directory. | ||
|
|
||
| The dust plugin has no source files, however, these may be registered with | ||
|
|
||
| .. code-block:: | ||
|
|
||
| register_srcs(src1 src2 src3 ...) | ||
|
|
||
| note that ``register_srcs`` does **not** take the ``PLUGIN path`` | ||
| syntax. Simply use the relative path from the ``CMakeLists.txt`` file to the source | ||
| file. | ||
|
|
||
| To register the test, we call | ||
|
|
||
| .. code-block:: | ||
|
|
||
| register_tests(tst/test_dust.cpp) | ||
|
|
||
| As with source files, do not use the ``PLUGIN PATH`` syntax. Just use | ||
| the relative path to the ``cpp`` file containing the tests. | ||
|
|
||
| Finally, call | ||
|
|
||
| .. code-block:: | ||
|
|
||
| export_plugin() | ||
|
|
||
| to ensure the registrations described above are pushed to "top level" | ||
| scope of the build system. | ||
|
|
||
| To use a plugin so-defined, you must tell the build system that it | ||
| exists at configure time. To do so, call | ||
|
|
||
| .. code-block:: | ||
|
|
||
| -DSINGULARITY_PLUGINS="/path/to/my/plugin1;/path/to/my/plugin2" | ||
|
|
||
| where the above defines a semicolon-separated list of paths to plugin | ||
| directories. For example, to register the dust plugin: | ||
|
|
||
| .. code-block:: | ||
|
|
||
| -DSINGULARITY_PLUGINS=/path/to/singularity-eos/example/plugin | ||
|
|
||
| Re-defining the default variant | ||
| -------------------------------- | ||
|
|
||
| The ``dust`` plugin also contains a file ``dust/dust_variant.hpp``, | ||
| which contains a definition of the ``EOS`` type (i.e., a variant) but | ||
| with the dust equation of state included. To tell the infrastructure | ||
| to use **this** variant rather than the default, specify the "include | ||
| path" at configure time. For example: | ||
|
|
||
| .. code-block:: | ||
|
|
||
| -DSINGULARITY_VARIANT="dust/dust_variant.hpp" | ||
|
|
||
| There may only be *one* definition for the ``SINGULARITY_VARIANT`` at | ||
| a time, so only specify for one of your plugins, if you have multiple. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| #------------------------------------------------------------------------------# | ||
| # © 2024. Triad National Security, LLC. All rights reserved. This | ||
| # program was produced under U.S. Government contract 89233218CNA000001 | ||
| # for Los Alamos National Laboratory (LANL), which is operated by Triad | ||
| # National Security, LLC for the U.S. Department of Energy/National | ||
| # Nuclear Security Administration. All rights in the program are | ||
| # reserved by Triad National Security, LLC, and the U.S. Department of | ||
| # Energy/National Nuclear Security Administration. The Government is | ||
| # granted for itself and others acting on its behalf a nonexclusive, | ||
| # paid-up, irrevocable worldwide license in this material to reproduce, | ||
| # prepare derivative works, distribute copies to the public, perform | ||
| # publicly and display publicly, and to permit others to do so. | ||
| #------------------------------------------------------------------------------# | ||
|
|
||
| # Add the header file to the list of headers | ||
| register_headers(PLUGIN dust dust.hpp dust_variant.hpp) | ||
|
|
||
| # Register this test to be built in the test suite | ||
| register_tests(tst/test_dust.cpp) | ||
|
|
||
| # Export lists to parent scope | ||
| export_plugin() |
Oops, something went wrong.