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