• View
• Edit
• History
• Print

MulabAddAComponent

< How to install mulab | Index | Finer points about fit components >

Sequential steps to introduce a new function in 1.05

Suppose you want to add a function mydecay

1) Edit mu_initialize_models

Go to the bottom and copy the last block of the structure changing it according to this
brief desription

 MU_COMPONENT.NAME(9)={'md'}; % a unique two letter acronym 
 MU_COMPONENT.PARAMETER(9).NUMBER=4; % number of parameters
 MU_COMPONENT.PARAMETER(9).NAME={'Amp','Gau','DeL','DeLo'}; % their names
 MU_COMPONENT.PARAMETER(9).STEPBOUNDS=[0.01 0 0;...
                           0.1 0 0; 0.1 1e-3 1e3; 0.1 0 0]; % initial step lo bound hi bound
                                  % 0.1 0 0 means step=0.1, lo bound=-inf, hi bound=+inf
                                  % 0.1 0 1e4 means step=0.1, lo bound=0, hi bound=10000
 MU_COMPONENT.DEFINITION(9)={'mydecay(p,data)'}; % change function name but keep the argument list
 MU_COMPONENT.HELP(9)={['My decay' ...
                    'static in zero or longitudinal field, with T1']} ; % short description

2) Write the function f=mydecay(p,data) in the file mydecay.m:
it must provide a function value, f, at each time, assuming that t=data(1,:);
is the time of the center of each bin, in microseconds. See mubackground.m as an example

Debugging: temporarily place a copy of the new mydecay.m and mu_initialize_models.m
in the working directory (to see where, type pwd from the command window)
Invoke mu_initialize_models.m if you modified it, to reinitialize the list
Final version: save as mydecay.m and copy this file as well as the new mu_initialize_models.m
to the matlab-1.05 toolbox in the matlab path (where all toolboxes are installed). Restart matlab.

Sequential steps to introduce a new function in 1.04

(obsolete, install 1.05 instead)

Suppose you want to add the function mydecay.m

First edit mu_initialize_models

Go to the bottom and copy the last block of the structure

 MU_COMPONENT.NAME(9)={'md'}; % a new two letter acronym 
 MU_COMPONENT.PARAMETER(9).NUMBER=4; % number of parameters
 MU_COMPONENT.PARAMETER(9).NAME={'Amp','Gau','DeL','DeLo'};
 MU_COMPONENT.PARAMETER(9).TYPE={'unlim','unlim','positive','unlim'};
 MU_COMPONENT.DEFINITION(9)={'mydecay(p,data)'}; %change name and keep the argument list
 MU_COMPONENT.HELP(9)={['My decay' ...
                    'static in zero or longitudinal field, with T1']} ; % description

Parameter name convention. The name defines the bounds and the initial step size\\ (or initial error). This is a list of already defined parameters

 Amp unlimited partial asymmetry
 Gau unlimited field (G)
 LFG positive def field (G)
 Hypf unlimited hyperfine frequency (MHz)
 Phi unlimited phase (deg)
 DeLo unlimited rate, Lorentian (us^-1)
 DeGa unlimited rate, Gaussian (us^-1)
 DeL positive defined rate (us^-1)
 DeG positive defined rate (us^-1)
 DeCR positive defined rate for stretched (us^-1)

Write the function f=mydecay(p,data):
it must provide a fucntion value, f, at each time, assuming that t=data(1,:);
is the time of the center of each bin, in microseconds

If you need a new type of parameter, give it a new name\\ and define their initial step size and bounds in routine mupar.m Look at the end of the mupar function, where it defined steps and bounds\\ within the switch@ loop

            switch char(lower(parname))  % implies unique names for each
                                         % type of parameter               
              case {'lpha','amp'}
                error=0.01; % asymmetry

etc... For instance if your new parameter Myp must be limited within 1e-3 and 1e3, with initial step 0.01, add

              case{'myp}  % the list is translated to lowercase 
                error=0.01;
                lowbnd=1e-3; 
                highbnd=1000;

If you do not add the second two lines Myp will be unbounded (lowbnd, highbnd= 0,0)

When you are done, make sure the new .m files are in the toolbox and restart matlab (if you work in debugging mode you might be able to substitute the files without restarting matlab)

All the routines dealing with model components

mu_initialize_models is invoked by mulab (start point). It defines the global variables
MU_TABLE (constants, gyromagnetic ratios, lifetimes) and MU_COMPONENT, containing the list of

 component name  (two character codename, e,g. da, ba, mu ...)
 parameters number (how many paramenters)
 parameters names  (e.g. Amp, Gau, DeLo, etc.)
 parameters type (unlim positive etc - unused)  % in 1.04
 parameters steps and bounds ([0.01 0 0; 0.1 0 0; 0.01 0 0])  % in 1.05
 calling string (either the command or the function call, e.g. {'myfunct(p,data)'};)
 help string (used by mulistcomponents)

mupar prepares the full list of parameters, indexed according to the Fit Parameters list
providing index stepbounds name flag(~!=+)

mugetcomponent receives the n times two character codename (e.g. damu) of the model and returns
the indices in MU_COMPONENT (e.g. [1 3] since MU_COMPONENT(1)='da' and MU_COMPONENT(13)='mu')

muvalidatemodel calls mugetcomponent and compares the list of component codenames with the full name
to check that the model name uniquely determines these components (e.g. it rejects a damub or a dama model
Rejection yields an 'Invalid model' message in command window and wipes out the LdModel GUI input

mufit interprets the model in the same way

< How to install mulab | Index | Finer points about fit components >