Marg Driver Development

A marg driver is the executable that evaluates the (marginalized) likelihood for each hyperparameter point. The hyperpipeline expects drivers to accept a specific CLI contract; a base class and a Gaussian toy driver are provided in RIFT.hyperpipe.drivers.

Driver Contract

Every marg driver must accept the following CLI contract to integrate with the pipeline:

Flag

Description

--using-eos PATH

Input hyperparameter grid. The file: prefix is tolerated. Format: # lnL sigma_lnL <params...>

--eos_start_index INT

First row to evaluate (inclusive).

--eos_end_index INT

Last row to evaluate (exclusive).

--fname-output-integral PATH

Output file path. Driver must write back same rows with evaluated lnL and sigma_lnL.

--outdir PATH

Output directory; created if absent.

--conforming-output-name

If set, append +annotation.dat to the output file name.

--fname

Legacy passthrough; may be None or ignored.

Built-in Driver: util_HyperMargGaussian.py

The simplest way to run the Gaussian demo without authoring an executable is to use the structured driver installed as a command-line tool:

util_HyperMargGaussian.py \
    --using-eos file:my_grid.dat \
    --eos_start_index 0 --eos_end_index 1000 \
    --outdir out \
    --fname-output-integral lnL.txt \
    --conforming-output-name

The driver is a thin shim around RIFT.hyperpipe.drivers.gaussian.GaussianMargDriver and supports:

--x-offset FLOAT

Position of the two modes along x (default: 4.0).

--sigma2 FLOAT

Diagonal of the covariance matrix (default: 2.0).

--unimodal

Drop the second mode at -x_offset for a single-mode Gaussian.

--params X,Y,Z

Comma-separated names of the three grid columns (default: x,y,z).

DIY Driver with MargDriverBase

For custom physics, subclass MargDriverBase:

from RIFT.hyperpipe.drivers.base import MargDriverBase

class MyDriver(MargDriverBase):
    description = "My custom marg driver."

    def log_likelihood(self, row_values, column_names, opts):
        # row_values: strings from columns 2.. of the grid
        # column_names: list of parameter names from the header
        params = dict(zip(column_names, map(float, row_values)))
        # your physics here
        lnL = -0.5 * (params["x"]**2 + params["y"]**2)
        return lnL, 1e-3

if __name__ == "__main__":
    MyDriver().run()

MargDriverBase handles all CLI parsing, grid I/O, and output formatting. Implement log_likelihood and (optionally) add_arguments for driver-specific flags.