Come analyze HEASARC, IRSA, and MAST data in the cloud! The Fornax Initiative is now welcoming all interested beta users.
Next: Building and Loading the Up: Adding a Custom Chain Previous: The randomize.dat Initialization File Contents
Writing a Chain Proposal Class
All user proposal classes must inherit from XSPEC's abstract class RandomizerBase, whose interface is defined in the file:
headas-<version>/Xspec/src/XSFit/Randomizer/RandomizerBase.h.The proposal class must declare a constructor as described in the previous section, and which explicitly calls the RandomizerBase constructor, passing it a lower-case name string. This name will become the proposal identifier when making a selection using the chain proposal option during an XSPEC session. For example:
MyProposal1.cxx
MyProposal1::MyProposal1()
: RandomizerBase("myprop1")
{
}
In XSPEC:
XSPEC> chain proposal myprop1 [<optional initializing args>]The RandomizerBase class contains 5 private virtual functions: doRandomize, doInitializeLoad, doInitializeRun, doAcceptedRejected, and getCovariance.
doRandomize
doRandomize is the only pure virtual function and therefore is the only one which must be overridden in the inheriting class. Its signature is:
virtual void doRandomize(RealArray& parameterValues, const Fit* fit)where RealArray is a typedef for std::valarray<double> and is defined in src/main/xsTypes.h. This function is called by XSPEC for each chain iteration, and XSPEC passes in the current variable model parameter values. The overridden doRandomize function performs the necessary parameter modifications and sends them back in the same array.
The function's second argument is a const pointer to XSPEC's global Fit class object. For those willing to further explore XSPEC's internals, this pointer provides access to various fit and chain information (such as covariance matrices), which may be necessary for the user's proposal scheme.
doInitializeLoad and doInitializeRun
doInitializeLoad and doInitializeRun may be optionally overridden to perform initialization tasks at different stages during runtime. The default versions of these functions in RandomizerBase do nothing. doInitializeLoad is called by XSPEC immediately after the proposal is selected with the chain proposal command. Therefore one may find it useful to have this function process any additional arguments which may be entered on the command line:
chain proposal myprop [<optional initializing args>]
XSPEC automatically bundles [<optional initializing args>] into a single string and places it in the m_initString data member of RandomizerBase, to which the inheriting class has access. doInitializeRun is called once at the start of a chain run, and is useful for any tasks which must be performed one time immediately after the chain run command is entered.
doAcceptedRejected is called after each iteration in the chain. Its first argument is an array filled with the most recently attempted model parameter values, and its second argument is a boolean true or false indicating whether the attempt was accepted or rejected. The base class function does nothing with this, but an inherited class may want to use this information in an overriden function.
In its simplest form, a proposal class may be declared and defined as in the following example. This doesn't actually do anything since the doRandomize function is empty and the parameterValues array is left unchanged.
MyProposal.h
#ifndef MYPROPOSAL_H
#define MYPROPOSAL_H
#include <xsTypes.h>
#include <XSFit/Randomizer/RandomizerBase.h>
class Fit; // only a forward declaration is required for Fit
class MyProposal : public RandomizerBase
{
public:
MyProposal();
virtual ~MyProposal();
private:
virtual void doRandomize(RealArray& parameterValues, const Fit* fit);
};
#endif
MyProposal.cxx
#include "MyProposal.h"
#include <XSFit/Fit/Fit.h>
MyProposal::MyProposal()
: RandomizerBase("myprop")
{
}
MyProposal::~MyProposal()
{
}
void MyProposal::doRandomize(RealArray& parameterValues, const Fit* fit)
{
// This is where the proposal algorithm should modify the variable
// model parameters in the parameterValues array.
}
Next: Building and Loading the Up: Adding a Custom Chain Previous: The randomize.dat Initialization File Contents