Horace File Format

The Horace file format is based on Native File Format, this page is intended to demonstrate where the format differs.

Examples of horace problems are:

# FitBenchmark Problem
software = 'Horace'
name = '1D Gaussian 1'
description = '1D Gaussian (Test example from test_multifit_herbert)'
input_file = 'testdata_multifit_1.mat'
function = 'foreground=m_scripts/functions/mftest_gauss_bkgd_fb_test.m ,height=100,centre=50,sigma=7,const=0,grad=0'
wye_function = 'matlab_script=m_scripts/wye_functions/fb_wye_IX_1D_test1.m'
simulate_function = 'matlab_script=m_scripts/simulate_functions/fb_simulate_IX_1D_test1.m'

# FitBenchmark Problem
software = 'Horace'
name = '3D_Gaussian'
description = '3D Gaussian (Horace\documentation\herbert\example_codes). The data in this example is generated in the wye_function'
input_file = 'dummy.txt'
function = 'foreground=m_scripts/functions/gauss3d_fb_test.m ,height=1100,centre_p1=66 ,centre_p2=1055,centre_p3=117,covmat_p1=15,covmat_p2=3,covmat_p3=5,covmat_p4=30,covmat_p5=-3,covmat_p6=20; background=m_scripts/functions/linear3D_bg_fb_test.m,bkgd_const=15'
wye_function = 'matlab_script=m_scripts/wye_functions/fb_wye_IX_1D_test6.m'
simulate_function = 'matlab_script=m_scripts/simulate_functions/fb_simulate_IX_1D_test6.m'

# FitBenchmark Problem
software = 'Horace'
name = 'PCSMO_at_001_data'
description = 'PCSMO data at 0.0001 data'
input_file = 'pcsmo_ei70_base_bkd.sqw'
function = 'foreground=m_scripts/functions/testfunc_nb_sqw_db_test.m ,JF1=-11.39,JA=1.5,JF2=-1.35,JF3=1.5,Jperp=0.88,D=0.074,en_width=0.1'
wye_function = 'matlab_script=m_scripts/wye_functions/fb_wye_pcsmo_test.m'
simulate_function = 'matlab_script=m_scripts/simulate_functions/fb_simulate_pcsmo_test.m'

The Horace file format requires you to have run the benchmark problem in Horace using fit() and simulate() successfully. Relevant links on how to run this are: Multifit , Advanced Multifit and Tobyfit problems as well as Running Horace in Parallel.

As in the native format, an input file must start with a comment indicating that it is a FitBenchmarking problem followed by a number of key value pairs. Available keys can be seen in Native File Format and below:

software, name, description

As described in the native format.

input_file

For Horace we require a .sqw or .mat file containing preprocessed, Horace-compatible data.

Note

The .mat file is the result of using save(file, sqw_objects) and should be used if you are loading in multiple sqw objects. Make sure to load the data in appropriately in the wye_function.

function

The function is defined by one or more matlab script (.m) files which return a model of the foreground or foreground and background respectively.

The format for defining the function is based on comma-separated key-value pairs, where the Matlab script files are defined by the variables “foreground” and “background”. The remaining pairs define the starting values for each of the models, respectively. It’s important to note that these pairs must be defined after their respective models.

If both the foreground and background models are defined, they should be given as a semicolon-separated list. In this case, there would be two comma-separated key-value pairs, one for the foreground and foreground parameters, and another for the background and background parameters, separated by a semicolon.

Examples:

Only foreground:

function = 'foreground=m_scripts/functions/mftest_gauss_bkgd.m ,height=100,centre=50,sigma=7,const=0,grad=0'

Foreground and background:

function = 'foreground=m_scripts/functions/gauss.m ,height=1100,centre=66 ,stdev=13; background=m_scripts/functions/linear_bg.m ,bkgd_const=15'

Note

All parameters must have unique names e.g.

function = 'foreground=gauss.m ,height=100,centre=50,sigma=7' ; background=gauss.m ,height_bkgd=100,centre_bkgd=50,sigma_bkgd=7'

wye_function

The wye_function is defined by a matlab file which returns the:

w

an sqw , dnd, ix_dataset object or xye struct. (see Multifit)

e

standard deviation data

y

intensity data

msk

logical mask array of which elements are to be retained

This function takes the path to the datafile and the path to the matlab functions as arguments.

Explained example of the wye_function:

The first three lines add the path to matlab functions needed for fitting and loads the w object.

addpath(genpath(path));
source_data = load(datafile);
w = source_data.w1 ;

The next line gets the y and e from the w object. These are the true y, e and msk values from the experiment.

[y, e, msk] = sigvar_get(w);

Any elements in msk that have a corresponding element in y that is equal to zero will be set to zero. The purpose of this is to exclude these elements from subsequent calculations, since they are not informative.

msk(y==0) = 0;

The last two lines of the wye_function applies the msk to the y and e data. As the e from retrieved above is the variance we have taken the square root of the value to get the standard deviation.

y = y(msk);
e = sqrt(e(msk));

Examples of the wye_function:

function [w, y, e, msk] = fb_wye_IX_1D_test(datafile, path)
% Gets the w , y, e and msk from the sqw object

addpath(genpath(path));
source_data = load(datafile);
w = source_data.w1 ;

[y, e, msk] = sigvar_get(w);

msk(y==0) = 0;

y = y(msk);
e = sqrt(e(msk));

end

function [w, y, e, msk] = fb_wye_pcsmo_test(datafile, path)
% Gets the w , x, y ,e and msk from the sqw object

sqw_file = datafile
addpath(genpath(path));

ne = 10;
frac = 1.e-6;
ei = [25, 35, 50, 70, 100, 140];
freq = [300, 200, 200, 250, 300, 400];
proj = ortho_proj([1, 0, 0], [0, 1, 0], 'type', 'rrr');

sample = IX_sample(true,[0,0,1],[0,1,0],'cuboid',[0.01,0.05,0.01]);
sample.angdeg = [90 90 90];
sample.alatt = [3.4 3.4 3.4];
maps = maps_instrument(ei(4), freq(4), 'S');
lower_e = ei(4)*0.2; upper_e = ei(4)*0.7;
ebin = [lower_e, ei(4)/25, upper_e];
w1 = cut_sqw(sqw_file, proj, [-1, 2/39, 1], [-1, 2/39, 1], [-10, 10], ebin);
w1 = set_sample(w1,sample);
w1 = set_instrument(w1,maps);
w1 = mask_random_fraction_pixels(w1, 0.1);

[y, e, msk] = sigvar_get(w1);

msk(y==0) = 0;

y = y(msk);
e = sqrt(e(msk));
w = w1; 

simulate_function

The simulate_function is defined by a matlab file which returns the derived y values from simulate() for the fitting function. This matlab file takes in the w, fitpars (fitting parameters) and msk. The w and msk are the same as the wye_function. The fitpars are determined by the current minimizer.

Explained Example of the simulate_function:

forefunc = @mftest_gauss_bkgd;
mf = multifit(w);
mf = mf.set_fun(forefunc);
mf = mf.set_pin(fitpars);
[wout,fitpar] = mf.simulate();
[y, e] = sigvar_get(wout);
y=y(msk);

Note

If the benchmark problem uses random numbers in any way (e.g. tobyfit). A persisent seed needs to be set before simulate is run. This makes sure that it uses the same seed everytime simulate() is ran.

persistent seed
if isempty (seed)
    rng(3,"twister");
    seed = rng();
else
    rng(seed);
end

Examples of the simulate_function:

function y = fb_simulate_IX_1D_test1(w,fitpars,msk)
% simulate loop to solve for the parameters 

forefunc = @mftest_gauss_bkgd_fb_test;
mf = multifit(w);
mf = mf.set_fun(forefunc);
mf = mf.set_pin(fitpars);
[wout,fitpar] = mf.simulate();
[y, e] = sigvar_get(wout);
y=y(msk);

end

function y = fb_simulate_pcsmo_test(w,fitpars,msk)
%simulate loop to solve for the parameters 

persistent seed
if isempty (seed)
    rng(3,"twister");
    seed = rng();
else 
    rng(seed);
end

JF1 = -11.39; JA = 1.5; JF2 = -1.35; JF3 = 1.5; Jperp = 0.88; D = 0.074; en_width = 0.1;
frac = 1.e-6;
sw_obj = pcsmo_fb_test(JF1, JA, JF2, JF3, Jperp, D);
%fitpars = [JF1 JA JF2 JF3 Jperp D en_width];

cpars = {fitpars 'mat', {'JF1', 'JA', 'JF2', 'JF3', 'Jperp', 'D(3,3)'}, ...
    'hermit', false, 'optmem', 0, 'useFast', false, 'formfact', ...
    true,'resfun', 'gauss', 'coordtrans', diag([2 2 1 1]), ...
    'use_brille', true, 'node_volume_fraction', frac, ...
    'use_vectors', false, 'Qtrans', diag([1./4 1./4 1.])};

tbf = tobyfit(w);
tbf = tbf.set_fun(@sw_obj.horace_sqw, {cpars{:}});
tbf = tbf.set_mc_points(5);
[fit_data , fit_pars] = tbf.simulate();

[y, e, ~] = sigvar_get(fit_data);

y=y(msk);
end

Note

All the functions needed in the fitting must be in the subdirectory of the benchmark problem.

Note

If you have a non standard installation of Horace please set the HORACE_LOCATION and the SPINW_LOCATION as environment variables(e.g on IDAaaS).

Note

Horace Problems currently does not support plotting. Please set make_plots: no in the options file.