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,

#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

#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)

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

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

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

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

-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:

-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:

-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.