LIBISIS - User contributions [en]

User:Dickon Champion

2008-09-09T16:24:13Z

Dickon Champion:

A one time employee at ISIS/RAL (2002 - 2008), developed Fortran data structure and manipulation functions. Developed homer scripting process as well as GUI.

Now a Consultant for Actica consulting.

User:Dickon Champion

2008-09-09T16:19:09Z

Dickon Champion:

Consultant for Actica consulting

Homer Utilities

2008-07-14T17:00:52Z

Dickon Champion: /* dae access */

== gget ==
generic raw file access

it is possible at the matlab comand line to extract any variable from the rawfile by making a call to a populated [[IXTraw_file]] object.

<pre>
>> rawfile=IXTraw_file('/path/to/my/file.raw')
>> value=gget(rawfile,'FIELD')
</pre>

== dae access ==

It is possible to access the data in the DAE by populating an [[IXTraw_file]] with a special string argument. We prefix <tt>DAE:</tt> to the name of the instrument control computer. Once this has been successfully populated all data access and get functions can be called.

<pre>
>> rawf=IXTraw_file('DAE:ndxmerlin')
>> w1=getspectrum(rawf,1)
>> title=gget(rawf,'TITL')
</pre>

This process is not possible with all instruments and requires the newest ICP to be installed. Full homer processes are possible but take a very long time, it is best used to access single spectra.

== head and mhead ==

head() returns the header information for the raw file defined by the run_number, or the path to a defined raw file. Multiple run numbers can be combined together with limited practical use.

<pre>
>> head(run_number)
>> head(path_to_raw_file)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>

* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

mhead() returns the header information for each raw file defined by an '''array''' of run numbers, or an '''array''' of paths to a raw file.

<pre>
>> mhead(run_numbers)
>> mhead(paths_to_raw_files)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

== get_ei and mget_ei ==
get_ei() returns the energy of given a monochromatic run number, a guide energy can optionally be provided to focus the search for a monitor peak. It also optionally returns a structure containing the peak position, area and normalised area of the two monitors used to determine the energy. Multiple run numbers may be combined.

<pre>
>> [ei,props]=get_ei(run_number,ei_guess)
>> [ei,props]=get_ei(path_to_raw_file,ei_guess)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
* ei_guess is a single numeric value containing the starting ei for get_ei to use in its calculation

mget_ei()

<pre>
>> [ei,props]=mget_ei(run_numbers,ei_guesses)
>> [ei,props]=mget_ei(path_to_raw_file,ei_guesses)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
*ei_guesses must be a numerical array equal to the number of run_numbers, containing the starting ei for mget_ei to use in the energy calculation for each run

Homer Utilities

2008-07-14T16:51:05Z

Dickon Champion: /* dae access */

== gget ==
generic raw file access

it is possible at the matlab comand line to extract any variable from the rawfile by making a call to a populated [[IXTraw_file]] object.

<pre>
>> rawfile=IXTraw_file('/path/to/my/file.raw')
>> value=gget(rawfile,'FIELD')
</pre>

== dae access ==

it is possible to access the data in the DAE, can i add this page...h

== head and mhead ==

head() returns the header information for the raw file defined by the run_number, or the path to a defined raw file. Multiple run numbers can be combined together with limited practical use.

<pre>
>> head(run_number)
>> head(path_to_raw_file)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>

* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

mhead() returns the header information for each raw file defined by an '''array''' of run numbers, or an '''array''' of paths to a raw file.

<pre>
>> mhead(run_numbers)
>> mhead(paths_to_raw_files)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

== get_ei and mget_ei ==
get_ei() returns the energy of given a monochromatic run number, a guide energy can optionally be provided to focus the search for a monitor peak. It also optionally returns a structure containing the peak position, area and normalised area of the two monitors used to determine the energy. Multiple run numbers may be combined.

<pre>
>> [ei,props]=get_ei(run_number,ei_guess)
>> [ei,props]=get_ei(path_to_raw_file,ei_guess)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
* ei_guess is a single numeric value containing the starting ei for get_ei to use in its calculation

mget_ei()

<pre>
>> [ei,props]=mget_ei(run_numbers,ei_guesses)
>> [ei,props]=mget_ei(path_to_raw_file,ei_guesses)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
*ei_guesses must be a numerical array equal to the number of run_numbers, containing the starting ei for mget_ei to use in the energy calculation for each run

Overriding and setting default values for homer processes

2008-07-04T11:07:10Z

Dickon Champion: /* Overriding instrument specific population */

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]:
<tt>/your_libisis_directory/matlab/</tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>

in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Setting homer defaults ==

For each instrument there can be particular default values specified for each step in the homering process. When homering using a script there are set default values for the [[Scripting_Homer_Functions#white_beam|white beam]] process (None of the following is relevant to the GUI system). For example the MARI white beam defaults are specified in the script:

<tt>MARI/setup_mari_white_beam.m</tt>
<pre>
function setup_mari_white_beam

ixf_global_var('homer_white_beam','remove');

% particular to white beam operation
ixf_global_var('homer_white_beam','set','ei','white');
ixf_global_var('homer_white_beam','set','d_int',[20,40]);

% more general settings
ixf_global_var('homer_white_beam','set','peak_scale',1000000);
ixf_global_var('homer_white_beam','set','uamp_scale',1000);
ixf_global_var('homer_white_beam','set','mon_scale',1000);
ixf_global_var('homer_white_beam','set','det_units','$e');

% default normalisation is with monitor 1
ixf_global_var('homer_white_beam','set','normalisation',int32(1));
ixf_global_var('homer_white_beam','set','range',[1000,2000]);
</pre>

all the values are stored in persistent matlab memory using the function <tt>ixf_global_var</tt>, the specific values which have been set all refer to keywords which are specific to the [[Scripting_Homer_Functions#white_beam|white beam]] process. To therefore set the default white beam integration limits to be 20 to 100 meV and for the monitor normalisation integration range to be 1000 to 5000 microseconds
<pre>
ixf_global_var('homer_white_beam','set','d_int',[20,100]);
ixf_global_var('homer_white_beam','set','range',[1000,5000]);
</pre>

It is also possible to change the normalisation process entirely, if we want instead to set normalisation by microamp hours we remove the 'range' and change the normalisation to be:
<pre>
ixf_global_var('homer_white_beam','set','normalisation','uamp');
</pre>

== Overriding homer defaults ==

To override homer defaults when using the [[Scripting_Homer_Functions]] it is quite simple. The keywords are simply specified with their value eg.
<pre>
>> rf=white_beam(dso,run_number,'range',[1000,5000],'d_int',[20,100])
</pre>

== Overriding instrument specific population ==
=== using defined nexus files ===
In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. The [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|creation of these files]] is defined below

For example the specific MERLIN population information is contained in the file

<tt>MERLIN/setup_merlin_data_source.m</tt>

This script defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with the libisis package as they can change. The '<tt>inst_nxs:::</tt>' path is a standard definition which is specified in the <tt>[[Homer_Gui_setup|inst_defs.m]]</tt> file or in the [[Instrument setup]]

=== using a reference file built from a detector.dat information ===

it is possible to generate detector information from the files specified to create detector.dat files, these contain extra information about the [[IXTgeometry]], [[IXTshape]], [[IXTtranslation] and [[IXTorientation]] of the detectors.

It is first necessary to [[Building a reference detector file|build a reference detector file]]. Once you have done this it is again necessary to edit a script.

For example for the MAPS instrument we need to edit the following script file:

<tt>MAPS/setup_maps_data_source.m</tt>

we add the line:

<pre>
DSO=add_item(DSO,'inst_nxs:::detref.nxs','detector','full_reference_detector');
</pre>

== Creating populated nexus files ==
Populate an [[IXTrunfile]] from a raw file containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided they are placed in the <tt>inst_nxs:::</tt> path

Overriding and setting default values for homer processes

2008-07-04T11:00:40Z

Dickon Champion: /* using a reference file built from a detector.dat information */

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]:
<tt>/your_libisis_directory/matlab/</tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>

in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Setting homer defaults ==

For each instrument there can be particular default values specified for each step in the homering process. When homering using a script there are set default values for the [[Scripting_Homer_Functions#white_beam|white beam]] process (None of the following is relevant to the GUI system). For example the MARI white beam defaults are specified in the script:

<tt>MARI/setup_mari_white_beam.m</tt>
<pre>
function setup_mari_white_beam

ixf_global_var('homer_white_beam','remove');

% particular to white beam operation
ixf_global_var('homer_white_beam','set','ei','white');
ixf_global_var('homer_white_beam','set','d_int',[20,40]);

% more general settings
ixf_global_var('homer_white_beam','set','peak_scale',1000000);
ixf_global_var('homer_white_beam','set','uamp_scale',1000);
ixf_global_var('homer_white_beam','set','mon_scale',1000);
ixf_global_var('homer_white_beam','set','det_units','$e');

% default normalisation is with monitor 1
ixf_global_var('homer_white_beam','set','normalisation',int32(1));
ixf_global_var('homer_white_beam','set','range',[1000,2000]);
</pre>

all the values are stored in persistent matlab memory using the function <tt>ixf_global_var</tt>, the specific values which have been set all refer to keywords which are specific to the [[Scripting_Homer_Functions#white_beam|white beam]] process. To therefore set the default white beam integration limits to be 20 to 100 meV and for the monitor normalisation integration range to be 1000 to 5000 microseconds
<pre>
ixf_global_var('homer_white_beam','set','d_int',[20,100]);
ixf_global_var('homer_white_beam','set','range',[1000,5000]);
</pre>

It is also possible to change the normalisation process entirely, if we want instead to set normalisation by microamp hours we remove the 'range' and change the normalisation to be:
<pre>
ixf_global_var('homer_white_beam','set','normalisation','uamp');
</pre>

== Overriding homer defaults ==

To override homer defaults when using the [[Scripting_Homer_Functions]] it is quite simple. The keywords are simply specified with their value eg.
<pre>
>> rf=white_beam(dso,run_number,'range',[1000,5000],'d_int',[20,100])
</pre>

== Overriding instrument specific population ==
=== using defined nexus files ===
In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. The [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|creation of these files]] is defined below

For example the specific MERLIN population information is contained in the file

<tt>MERLIN/setup_merlin_data_source.m</tt>

This script defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with the libisis package as they can change. The '<tt>inst_nxs:::</tt>' path is a standard definition which is specified in the <tt>[[Homer_Gui_setup|inst_defs.m]]</tt> file or in the [[Instrument setup]]

=== using a reference file built from a detector.dat information ===

it is possible to generate detector information from the files specified to create detector.dat files, these contain extra information about the [[IXTgeometry]], [[IXTshape]], [[IXTtranslation] and [[IXTorientation]] of the detectors.

It is first necessary to [[Building a reference detector file|build a reference detector file]]. Once you have done this it is again necessary to edit a script.

For example for the MAPS instrument we need to edit the following script file:

<tt>MAPS/setup_maps_data_source.m</tt>

we add the line

,'inst_nxs:::detref.nxs','detector','full_reference_detector'

== Creating populated nexus files ==
Populate an [[IXTrunfile]] from a raw file containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided they are placed in the <tt>inst_nxs:::</tt> path

Building a reference detector file

2008-07-04T10:57:18Z

Dickon Champion:

we can create a detector.dat file and also an [[IXTdetector]] object from file input

Using Homer and Getting Started

2008-07-04T10:56:00Z

Dickon Champion:

* [[Getting Started]] '''VERY IMPORTANT''' setup details defined

* [[Homer GUI]] - mini tutorial with screenshots

*[[Scripting Homer Functions]] are easy to use functions which call homer related functions underneath, as well as setting up the [[IXTdata_source]] object for use by homer

* [[Overriding and setting default values for homer processes]]

* [[Building a reference detector file]]

*[[Homer and mgenie style functions]] Direct calls to homer and some mgenie style functions

*[[Homer Utilities]] extra functions and utilities

*[[IXTrunfile operations]] including algebra, elementary functions and other manipulations

*[[diagnose]] diagnostic function for homer input

*[[Example Scripts]]

Overriding and setting default values for homer processes

2008-07-04T10:55:32Z

Dickon Champion: /* Overriding instrument specific population */

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]:
<tt>/your_libisis_directory/matlab/</tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>

in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Setting homer defaults ==

For each instrument there can be particular default values specified for each step in the homering process. When homering using a script there are set default values for the [[Scripting_Homer_Functions#white_beam|white beam]] process (None of the following is relevant to the GUI system). For example the MARI white beam defaults are specified in the script:

<tt>MARI/setup_mari_white_beam.m</tt>
<pre>
function setup_mari_white_beam

ixf_global_var('homer_white_beam','remove');

% particular to white beam operation
ixf_global_var('homer_white_beam','set','ei','white');
ixf_global_var('homer_white_beam','set','d_int',[20,40]);

% more general settings
ixf_global_var('homer_white_beam','set','peak_scale',1000000);
ixf_global_var('homer_white_beam','set','uamp_scale',1000);
ixf_global_var('homer_white_beam','set','mon_scale',1000);
ixf_global_var('homer_white_beam','set','det_units','$e');

% default normalisation is with monitor 1
ixf_global_var('homer_white_beam','set','normalisation',int32(1));
ixf_global_var('homer_white_beam','set','range',[1000,2000]);
</pre>

all the values are stored in persistent matlab memory using the function <tt>ixf_global_var</tt>, the specific values which have been set all refer to keywords which are specific to the [[Scripting_Homer_Functions#white_beam|white beam]] process. To therefore set the default white beam integration limits to be 20 to 100 meV and for the monitor normalisation integration range to be 1000 to 5000 microseconds
<pre>
ixf_global_var('homer_white_beam','set','d_int',[20,100]);
ixf_global_var('homer_white_beam','set','range',[1000,5000]);
</pre>

It is also possible to change the normalisation process entirely, if we want instead to set normalisation by microamp hours we remove the 'range' and change the normalisation to be:
<pre>
ixf_global_var('homer_white_beam','set','normalisation','uamp');
</pre>

== Overriding homer defaults ==

To override homer defaults when using the [[Scripting_Homer_Functions]] it is quite simple. The keywords are simply specified with their value eg.
<pre>
>> rf=white_beam(dso,run_number,'range',[1000,5000],'d_int',[20,100])
</pre>

== Overriding instrument specific population ==
=== using defined nexus files ===
In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. The [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|creation of these files]] is defined below

For example the specific MERLIN population information is contained in the file

<tt>MERLIN/setup_merlin_data_source.m</tt>

This script defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with the libisis package as they can change. The '<tt>inst_nxs:::</tt>' path is a standard definition which is specified in the <tt>[[Homer_Gui_setup|inst_defs.m]]</tt> file or in the [[Instrument setup]]

=== using a reference file built from a detector.dat information ===

it is possible to generate detector information from the files specified to create detector.dat files, these contain extra information about the [[IXTgeometry]], [[IXTshape]], [[IXTtranslation] and [[IXTorientation]] of the detectors.

It is first necessary to [[Building a reference detector file|build a reference detector file]]

== Creating populated nexus files ==
Populate an [[IXTrunfile]] from a raw file containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided they are placed in the <tt>inst_nxs:::</tt> path

Overriding and setting default values for homer processes

2008-07-04T10:45:47Z

Dickon Champion:

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]:
<tt>/your_libisis_directory/matlab/</tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>

in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Setting homer defaults ==

For each instrument there can be particular default values specified for each step in the homering process. When homering using a script there are set default values for the [[Scripting_Homer_Functions#white_beam|white beam]] process (None of the following is relevant to the GUI system). For example the MARI white beam defaults are specified in the script:

<tt>MARI/setup_mari_white_beam.m</tt>
<pre>
function setup_mari_white_beam

ixf_global_var('homer_white_beam','remove');

% particular to white beam operation
ixf_global_var('homer_white_beam','set','ei','white');
ixf_global_var('homer_white_beam','set','d_int',[20,40]);

% more general settings
ixf_global_var('homer_white_beam','set','peak_scale',1000000);
ixf_global_var('homer_white_beam','set','uamp_scale',1000);
ixf_global_var('homer_white_beam','set','mon_scale',1000);
ixf_global_var('homer_white_beam','set','det_units','$e');

% default normalisation is with monitor 1
ixf_global_var('homer_white_beam','set','normalisation',int32(1));
ixf_global_var('homer_white_beam','set','range',[1000,2000]);
</pre>

all the values are stored in persistent matlab memory using the function <tt>ixf_global_var</tt>, the specific values which have been set all refer to keywords which are specific to the [[Scripting_Homer_Functions#white_beam|white beam]] process. To therefore set the default white beam integration limits to be 20 to 100 meV and for the monitor normalisation integration range to be 1000 to 5000 microseconds
<pre>
ixf_global_var('homer_white_beam','set','d_int',[20,100]);
ixf_global_var('homer_white_beam','set','range',[1000,5000]);
</pre>

It is also possible to change the normalisation process entirely, if we want instead to set normalisation by microamp hours we remove the 'range' and change the normalisation to be:
<pre>
ixf_global_var('homer_white_beam','set','normalisation','uamp');
</pre>

== Overriding homer defaults ==

To override homer defaults when using the [[Scripting_Homer_Functions]] it is quite simple. The keywords are simply specified with their value eg.
<pre>
>> rf=white_beam(dso,run_number,'range',[1000,5000],'d_int',[20,100])
</pre>

== Overriding instrument specific population ==

In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. The [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|creation of these files]] is defined below

For example the specific MERLIN population information is contained in the file

<tt>MERLIN/setup_merlin_data_source.m</tt>

This script defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with the libisis package as they can change. The '<tt>inst_nxs:::</tt>' path is a standard definition which is specified in the <tt>[[Homer_Gui_setup|inst_defs.m]]</tt> file or in the [[Instrument setup]]

== Creating populated nexus files ==
Populate an [[IXTrunfile]] from a raw file containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided they are placed in the <tt>inst_nxs:::</tt> path

Overriding and setting default values for homer processes

2008-07-04T10:41:48Z

Dickon Champion: /* Setting homer defaults */

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]:
<tt>/your_libisis_directory/matlab/</tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>

in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Setting homer defaults ==

For each instrument there can be particular default values specified for each step in the homering process. When homering using a script there are set default values for the [[Scripting_Homer_Functions#white_beam|white beam]] process (None of the following is relevant to the GUI system). For example the MARI white beam defaults are specified in the script:

<tt>MARI/setup_mari_white_beam.m</tt>
<pre>
function setup_mari_white_beam

ixf_global_var('homer_white_beam','remove');

% particular to white beam operation
ixf_global_var('homer_white_beam','set','ei','white');
ixf_global_var('homer_white_beam','set','d_int',[20,40]);

% more general settings
ixf_global_var('homer_white_beam','set','peak_scale',1000000);
ixf_global_var('homer_white_beam','set','uamp_scale',1000);
ixf_global_var('homer_white_beam','set','mon_scale',1000);
ixf_global_var('homer_white_beam','set','det_units','$e');

% default normalisation is with monitor 1
ixf_global_var('homer_white_beam','set','normalisation',int32(1));
ixf_global_var('homer_white_beam','set','range',[1000,2000]);
</pre>

all the values are stored in persistent matlab memory using the function <tt>ixf_global_var</tt>, the specific values which have been set all refer to keywords which are specific to the [[Scripting_Homer_Functions#white_beam|white beam]] process. To therefore set the default white beam integration limits to be 20 to 100 meV and for the monitor normalisation integration range to be 1000 to 5000 microseconds
<pre>
ixf_global_var('homer_white_beam','set','d_int',[20,100]);
ixf_global_var('homer_white_beam','set','range',[1000,5000]);
</pre>

It is also possible to change the normalisation process entirely, if we want instead to set normalisation by microamp hours we remove the 'range' and change the normalisation to be:
<pre>
ixf_global_var('homer_white_beam','set','normalisation','uamp');
</pre>

== Overriding instrument specific population ==

In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. The [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|creation of these files]] is defined below

For example the specific MERLIN population information is contained in the file

<tt>MERLIN/setup_merlin_data_source.m</tt>

This script defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with the libisis package as they can change. The '<tt>inst_nxs:::</tt>' path is a standard definition which is specified in the <tt>[[Homer_Gui_setup|inst_defs.m]]</tt> file or in the [[Instrument setup]]

== Creating populated nexus files ==
Populate an [[IXTrunfile]] from a raw file containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided they are placed in the <tt>inst_nxs:::</tt> path

Overriding and setting default values for homer processes

2008-07-04T10:41:25Z

Dickon Champion: /* Setting homer defaults */

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]:
<tt>/your_libisis_directory/matlab/</tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>

in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Setting homer defaults ==

For each instrument there can be particular default values specified for each step in the homering process. When homering using a script there are set default values for the [[Scripting_Homer_Functions#white_beam|white beam]] process (None of the following is relevant to the GUI system). For example the MARI white beam defaults are specified in the script:

<tt>MARI/setup_mari_white_beam.m</tt>
<pre>
function setup_mari_white_beam

ixf_global_var('homer_white_beam','remove');

% particular to white beam operation
ixf_global_var('homer_white_beam','set','ei','white');
ixf_global_var('homer_white_beam','set','d_int',[20,40]);

% more general settings
ixf_global_var('homer_white_beam','set','peak_scale',1000000);
ixf_global_var('homer_white_beam','set','uamp_scale',1000);
ixf_global_var('homer_white_beam','set','mon_scale',1000);
ixf_global_var('homer_white_beam','set','det_units','$e');

% default normalisation is with monitor 1
ixf_global_var('homer_white_beam','set','normalisation',int32(1));
ixf_global_var('homer_white_beam','set','range',[1000,2000]);
</pre>

all the values are stored in persistent matlab memory using the function <tt>ixf_global_var</tt>, the specific values which have been set all refer to keywords which are specific to the [[Scripting_Homer_Functions#white_beam|white beam]] process. To therefore set the default white beam integration limits to be 20 to 100 meV and for the monitor normalisation integration range to be 1000 to 5000 microseconds
<pre>
ixf_global_var('homer_white_beam','set','d_int',[20,100]);
ixf_global_var('homer_white_beam','set','range',[1000,2000]);
</pre>

It is also possible to change the normalisation process entirely, if we want instead to set normalisation by microamp hours we remove the 'range' and change the normalisation to be:
<pre>
ixf_global_var('homer_white_beam','set','normalisation','uamp');
</pre>

== Overriding instrument specific population ==

In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. The [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|creation of these files]] is defined below

For example the specific MERLIN population information is contained in the file

<tt>MERLIN/setup_merlin_data_source.m</tt>

This script defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with the libisis package as they can change. The '<tt>inst_nxs:::</tt>' path is a standard definition which is specified in the <tt>[[Homer_Gui_setup|inst_defs.m]]</tt> file or in the [[Instrument setup]]

== Creating populated nexus files ==
Populate an [[IXTrunfile]] from a raw file containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided they are placed in the <tt>inst_nxs:::</tt> path

Overriding and setting default values for homer processes

2008-07-04T10:29:29Z

Dickon Champion: /* Setting homer defaults */

Overriding and setting default values for homer processes

2008-07-04T10:27:27Z

Dickon Champion: /* Setting homer defaults */

Overriding and setting default values for homer processes

2008-07-04T10:26:06Z

Dickon Champion:

Overriding and setting default values for homer processes

2008-07-04T10:21:49Z

Dickon Champion: /* Overriding instrument specific population */

Overriding and setting default values for homer processes

2008-07-04T10:16:38Z

Dickon Champion: /* Creating populated nexus files */

Overriding and setting default values for homer processes

2008-07-04T10:15:23Z

Dickon Champion: /* Overriding instrument specific population */

Overriding and setting default values for homer processes

2008-07-04T10:14:24Z

Dickon Champion: /* Overriding instrument specific population */

Overriding and setting default values for homer processes

2008-07-04T10:12:53Z

Dickon Champion: /* Overriding instrument specific population */

Overriding and setting default values for homer processes

2008-07-04T10:12:00Z

Dickon Champion: /* Where are the defaults specified */

Overriding and setting default values for homer processes

2008-07-04T10:11:22Z

Dickon Champion: /* Where are the defaults specified */

Overriding and setting default values for homer processes

2008-07-04T10:10:59Z

Dickon Champion: /* Where are the defaults specified */

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]
<tt>/your_libisis_directory/matlab</tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>
in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Overriding instrument specific population ==

In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|Creating populated nexus files]]

For example the specific MERLIN population information is contained in the file

<tt>setup_merlin_data_source.m</tt>

This file defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects from the we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with libisis package as they can change. the '<tt>inst_nxs:::/tt>' path is a standard definition which is specified in the <tt>inst_defs.m</tt> file or in the [[Instrument setup]]

== Creating populated nexus files ==
populate an IXTrunfile from a rawfile containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided thety are placed in the inst_nxs::: path

Overriding and setting default values for homer processes

2008-07-04T10:10:48Z

Dickon Champion: /* Overriding instrument specific population */

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]
<tt>/your_libisis_directory/matlab<tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>
in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Overriding instrument specific population ==

In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|Creating populated nexus files]]

For example the specific MERLIN population information is contained in the file

<tt>setup_merlin_data_source.m</tt>

This file defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects from the we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with libisis package as they can change. the '<tt>inst_nxs:::/tt>' path is a standard definition which is specified in the <tt>inst_defs.m</tt> file or in the [[Instrument setup]]

== Creating populated nexus files ==
populate an IXTrunfile from a rawfile containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided thety are placed in the inst_nxs::: path

Overriding and setting default values for homer processes

2008-07-04T10:09:30Z

Dickon Champion:

== Where are the defaults specified ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]
<tt>/your_libisis_directory/matlab<tt>

on a linux rpm installation:
<tt>/usr/local/libisis/applications/matlab/</tt>
in the svn repository:
<tt>/libisis/applications/matlab/</tt>

each instrument has a named directory where there are instrument specific scripts used to define default values and files which are used to set up and populate the [[IXTrunfile]] object.

== Overriding instrument specific population ==

In the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. [[Overriding_and_setting_default_values_for_homer_processes#Creating populated nexus files|Creating populated nexus files]]

For example the specific MERLIN population information is contained in the file

<tt>setup_merlin_data_source.m</tt>

This file defines the nexus files which are required for population of the [[IXTrunfile]] object which in turn the .spe file is produced from.

To define files used to populate the [[IXTdetector]] and [[IXTspectra]] objects from the we can add the following two lines to this file:
<pre>
DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');
</pre>

These files are not distributed with libisis package as they can change. the 'inst_nxs:::' path is a standard definition which is specified in the <tt>inst_defs.m</tt> file or

== Creating populated nexus files ==
populate an IXTrunfile from a rawfile containing the correct values and enough detectors to include all those used by the mapping you have chosen - ie if you have an [[IXTrunfile]] which has been populated by the 'mon' command then it will not contain enough detector information.
then you make the matlab command
<pre>
>> write_nxs(your_runfile.inst.detector,'mydetectorfile.nxs')
>> write_nxs(your_runfile.inst.spectra,'myspectrafile.nxs')
</pre>
these files can then be used in the lines above to populate the [[IXTrunfile]] object provided thety are placed in the inst_nxs::: path

Overriding and setting default values for homer processes

2008-07-04T10:03:00Z

Dickon Champion:

Overriding and setting default values for homer processes

2008-07-04T09:55:47Z

Dickon Champion:

== overriding instrument specific population ==

the homer distribution files are contained in

on a [[Download_and_setup_LIBISIS|windows distribution]]

on a linux system:
<tt>/my_libisis_directory/applications/matlab/</tt>
in the svn repository:
<tt>/libisis/applications/matlab/</tt>

there are instrument specific files used to set up

in the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. Of course creation of this file is another issue.

the specific MERLIN population information is contained in the file

setup_merlin_data_source.m

this defines the nexus files which are required for population of the IXTrunfile object which in turn the .spe file is produced from. i added the following two lines to this file, with these lines present the libisis system will try and load the IXTdetector and IXTspectra object from these files.

DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');

these files are not distributed with libisis package as they can change. the 'inst_nxs:::' path is a standard definition which is specified in the inst_defs.m file

Overriding and setting default values for homer processes

2008-07-04T09:54:40Z

Dickon Champion:

== overriding instrument specific population ==

the homer distribution files are contained in

on a windows distribution

on a linux system:
<tt>/my_libisis_directory/applications/matlab/</tt>
in the svn repository:
<tt>/libisis/applications/matlab/

there are instrument specific files used to set up

in the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. Of course creation of this file is another issue.

the specific MERLIN population information is contained in the file

setup_merlin_data_source.m

this defines the nexus files which are required for population of the IXTrunfile object which in turn the .spe file is produced from. i added the following two lines to this file, with these lines present the libisis system will try and load the IXTdetector and IXTspectra object from these files.

DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');

these files are not distributed with libisis package as they can change. the 'inst_nxs:::' path is a standard definition which is specified in the inst_defs.m file

Overriding and setting default values for homer processes

2008-07-04T09:49:17Z

Dickon Champion:

== overriding instrument specific population ==

the homer distribution files are contained in

<tt>/usr/local/libisis/applications/matlab/</tt>

there are specific files used to set up the MERLIN instrument in the MERLIN directory

in the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. Of course creation of this file is another issue.

the specific MERLIN population information is contained in the file

setup_merlin_data_source.m

this defines the nexus files which are required for population of the IXTrunfile object which in turn the .spe file is produced from. i added the following two lines to this file, with these lines present the libisis system will try and load the IXTdetector and IXTspectra object from these files.

DSO=add_item(DSO,'inst_nxs:::merlin_detector.nxs','detector');
DSO=add_item(DSO,'inst_nxs:::merlin_spectra.nxs','spectra');

these files are not distributed with libisis package as they can change. the 'inst_nxs:::' path is a standard definition which is specified in the inst_defs.m file

Overriding and setting default values for homer processes

2008-07-04T09:11:33Z

Dickon Champion:

last cycle when you started creating files with the wrong monitor distances i put a fix in the mordred homer files

the homer distribution files are contained in

/usr/local/libisis/applications/matlab/

there are specific files used to set up the MERLIN instrument in the MERLIN directory

in the case where there is incorrect information in the rawfile which has been generated we can populate detector and spectra information from a nexus file. Of course creation of this file is another issue.

Using Homer and Getting Started

2008-07-04T09:11:17Z

Dickon Champion:

* [[Getting Started]] '''VERY IMPORTANT''' setup details defined

* [[Homer GUI]] - mini tutorial with screenshots

*[[Scripting Homer Functions]] are easy to use functions which call homer related functions underneath, as well as setting up the [[IXTdata_source]] object for use by homer

* [[Overriding and setting default values for homer processes]]

*[[Homer and mgenie style functions]] Direct calls to homer and some mgenie style functions

*[[Homer Utilities]] extra functions and utilities

*[[IXTrunfile operations]] including algebra, elementary functions and other manipulations

*[[diagnose]] diagnostic function for homer input

*[[Example Scripts]]

Using Homer and Getting Started

2008-07-02T12:34:22Z

Dickon Champion:

* [[Getting Started]] '''VERY IMPORTANT''' setup details defined

* [[Homer GUI]] - mini tutorial with screenshots

*[[Scripting Homer Functions]] are easy to use functions which call homer related functions underneath, as well as setting up the [[IXTdata_source]] object for use by homer

*[[Homer and mgenie style functions]] Direct calls to homer and some mgenie style functions

*[[Homer Utilities]] extra functions and utilities

*[[IXTrunfile operations]] including algebra, elementary functions and other manipulations

*[[diagnose]] diagnostic function for homer input

*[[Example Scripts]]

Homer Utilities

2008-07-01T16:40:15Z

Dickon Champion: /* gget */

== gget ==
generic raw file access

it is possible at the matlab comand line to extract any variable from the rawfile by making a call to a populated [[IXTraw_file]] object.

<pre>
>> rawfile=IXTraw_file('/path/to/my/file.raw')
>> value=gget(rawfile,'FIELD')
</pre>

== dae access ==

it is possible to access the data in the DAE

== head and mhead ==

head() returns the header information for the raw file defined by the run_number, or the path to a defined raw file. Multiple run numbers can be combined together with limited practical use.

<pre>
>> head(run_number)
>> head(path_to_raw_file)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>

* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

mhead() returns the header information for each raw file defined by an '''array''' of run numbers, or an '''array''' of paths to a raw file.

<pre>
>> mhead(run_numbers)
>> mhead(paths_to_raw_files)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

== get_ei and mget_ei ==
get_ei() returns the energy of given a monochromatic run number, a guide energy can optionally be provided to focus the search for a monitor peak. It also optionally returns a structure containing the peak position, area and normalised area of the two monitors used to determine the energy. Multiple run numbers may be combined.

<pre>
>> [ei,props]=get_ei(run_number,ei_guess)
>> [ei,props]=get_ei(path_to_raw_file,ei_guess)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
* ei_guess is a single numeric value containing the starting ei for get_ei to use in its calculation

mget_ei()

<pre>
>> [ei,props]=mget_ei(run_numbers,ei_guesses)
>> [ei,props]=mget_ei(path_to_raw_file,ei_guesses)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
*ei_guesses must be a numerical array equal to the number of run_numbers, containing the starting ei for mget_ei to use in the energy calculation for each run

Homer Utilities

2008-07-01T16:29:27Z

Dickon Champion: /* gget */

== gget ==
generic raw file access

it is possible at the matlab comand line to extract any variable from the rawfile by making a call to a populated [[IXTrawfile]] object.

<pre>
>> rawfile=IXTraw_file('/path/to/my/file.raw')
>> value=gget(rawfile,'FIELD')
</pre>

== dae access ==

it is possible to access the data in the DAE

== head and mhead ==

head() returns the header information for the raw file defined by the run_number, or the path to a defined raw file. Multiple run numbers can be combined together with limited practical use.

<pre>
>> head(run_number)
>> head(path_to_raw_file)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>

* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

mhead() returns the header information for each raw file defined by an '''array''' of run numbers, or an '''array''' of paths to a raw file.

<pre>
>> mhead(run_numbers)
>> mhead(paths_to_raw_files)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

== get_ei and mget_ei ==
get_ei() returns the energy of given a monochromatic run number, a guide energy can optionally be provided to focus the search for a monitor peak. It also optionally returns a structure containing the peak position, area and normalised area of the two monitors used to determine the energy. Multiple run numbers may be combined.

<pre>
>> [ei,props]=get_ei(run_number,ei_guess)
>> [ei,props]=get_ei(path_to_raw_file,ei_guess)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
* ei_guess is a single numeric value containing the starting ei for get_ei to use in its calculation

mget_ei()

<pre>
>> [ei,props]=mget_ei(run_numbers,ei_guesses)
>> [ei,props]=mget_ei(path_to_raw_file,ei_guesses)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
*ei_guesses must be a numerical array equal to the number of run_numbers, containing the starting ei for mget_ei to use in the energy calculation for each run

Homer Utilities

2008-07-01T16:26:20Z

Dickon Champion: /* gget */

== gget ==
generic raw file access

it is possible at the matlab comand line to extract

== dae access ==

it is possible to access the data in the DAE

== head and mhead ==

head() returns the header information for the raw file defined by the run_number, or the path to a defined raw file. Multiple run numbers can be combined together with limited practical use.

<pre>
>> head(run_number)
>> head(path_to_raw_file)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>

* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

mhead() returns the header information for each raw file defined by an '''array''' of run numbers, or an '''array''' of paths to a raw file.

<pre>
>> mhead(run_numbers)
>> mhead(paths_to_raw_files)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

== get_ei and mget_ei ==
get_ei() returns the energy of given a monochromatic run number, a guide energy can optionally be provided to focus the search for a monitor peak. It also optionally returns a structure containing the peak position, area and normalised area of the two monitors used to determine the energy. Multiple run numbers may be combined.

<pre>
>> [ei,props]=get_ei(run_number,ei_guess)
>> [ei,props]=get_ei(path_to_raw_file,ei_guess)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
* ei_guess is a single numeric value containing the starting ei for get_ei to use in its calculation

mget_ei()

<pre>
>> [ei,props]=mget_ei(run_numbers,ei_guesses)
>> [ei,props]=mget_ei(path_to_raw_file,ei_guesses)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
*ei_guesses must be a numerical array equal to the number of run_numbers, containing the starting ei for mget_ei to use in the energy calculation for each run

Homer Utilities

2008-07-01T16:07:41Z

Dickon Champion:

== gget ==
generic raw file access

== head and mhead ==

head() returns the header information for the raw file defined by the run_number, or the path to a defined raw file. Multiple run numbers can be combined together with limited practical use.

<pre>
>> head(run_number)
>> head(path_to_raw_file)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>

* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

mhead() returns the header information for each raw file defined by an '''array''' of run numbers, or an '''array''' of paths to a raw file.

<pre>
>> mhead(run_numbers)
>> mhead(paths_to_raw_files)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]

== get_ei and mget_ei ==
get_ei() returns the energy of given a monochromatic run number, a guide energy can optionally be provided to focus the search for a monitor peak. It also optionally returns a structure containing the peak position, area and normalised area of the two monitors used to determine the energy. Multiple run numbers may be combined.

<pre>
>> [ei,props]=get_ei(run_number,ei_guess)
>> [ei,props]=get_ei(path_to_raw_file,ei_guess)
</pre>

* <tt>run_number</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt> or a single numeric
# an array of strings <tt>char('12345' '45673' '34436')</tt> or a single string
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>path_to_raw_file</tt> is defined as a string or a cell array of strings of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
* ei_guess is a single numeric value containing the starting ei for get_ei to use in its calculation

mget_ei()

<pre>
>> [ei,props]=mget_ei(run_numbers,ei_guesses)
>> [ei,props]=mget_ei(path_to_raw_file,ei_guesses)
</pre>

* <tt>run_numbers</tt> can be defined in the following ways
# a numerical array of numbers <tt> [12345 45673 34436]</tt>
# an array of strings <tt>char('12345' '45673' '34436')</tt>
# a cell array of strings <tt>{'12345' '45673' '34436'}</tt>
# a cell array of numerics <tt>{12345 45673 34436}</tt>
* <tt>paths_to_raw_files</tt> is defined as a cell or string array of the form <tt>'C:\data\myfile.raw'</tt>, relative paths are also possible as well as using the [[Global IXTpath objects]] <tt>'inst_data:::myfile.raw'</tt> provided they have been set properly in the [[Instrument setup]]
*ei_guesses must be a numerical array equal to the number of run_numbers, containing the starting ei for mget_ei to use in the energy calculation for each run

IXTrunfile operations

2008-06-30T11:02:16Z

Dickon Champion: /* Binary operators for two run files */

It is possible to perform algebraic and mathematical operations on populated [[IXTrunfile]] objects

== runfile algebra ==

a+b

a-b

a*b

a/b

a^b

as the [[IXTrunfile]] object is more complicated than other simple datasets there are certain rules as to how a simple algebraic operation might be performed

Consider a run file as a pair of [[IXTdata]] objects, one for the detector information and one for the monitor information, together with various objects that are for everything else. The ‘everything else’ includes the instrument description, user, source, but in particular the [[IXTspectra]] and [[IXTdetector]] classes as part of IXTinstrument. The [[IXTdata]] object contains bridging arrays to the IXTspectra object. For the purposes of the algebra, lets write an [[IXTrunfile]] as:
R= α(d,m)

where
α the ‘everything else’
d dataset2D or array of dataset2D, or (if no detector map given) unassigned.

=== Binary operators with a d1d, d2d, scalar, vector, array ===

We permit the addition if the two conditions are true:
(i) the operation is valid on both the detector and monitor dataset2D (using whatever rules apply to dataset2d as at the moment)
(ii) the resultant detector and monitor dataset2d have the same sizes as the initial ones (this ensures that the ‘everything else is valid)

In summary, (if a dash refers to the detector or monitor IXTdata being unassigned):

α(d,m) + a = α(d+a,m+a)

α(d,-) + a = α(d+a,-)

α(-,m) + a = α(-,m+a)

=== Binary operators for two run files ===

The different cases for consideration when combining two runfiles are legion – what if they have different numbers of detector and or monitor mapping, what if they have the same number of workspaces but different grouping of spectra, what if they have no monitor workspaces, what if from different instrument? The best criteria for algebra are
* Simple to implement, which will probably also satisfy:
* Simple for a user to predict the behaviour,
* Not place undue restrictions on what can be combined,
* Does the sensible thing in commonly encountered situations.

Simple to implement is important, as it means code is also less prone to bugs. Simple for a user to predict is important – the outcome should be intuitively obvious. This will probably follow from ‘simple to implement’: if we don’t treat lots of special cases then the user won’t be worrying about lots of rules that need to be remembered. We shouldn’t place unnecessary restrictions: e.g. if a user wants to add MARI and HET data let them: they probably have a good reason to be trying to do so. It also means that the code doesn’t have to make copious checks, or worry too much about how to combine the ‘everything else’. Finally, the first three rules mean that the scheme will almost certainly do the sensible thing in common situations.

For the sake of definiteness, consider addition. The rules for any other binary operation will be the same. The minimum scheme is:
(i) Add the D2D for each of the detector and monitor data (using implicitly whatever rules we have in place for the algebra of dataset2d regarding sizes of arrays, units, point or histogram) i.e.
(d1,m1) + (d2,m2) = (d1+d2, m1+m2)
(ii) The ‘everything else’ comes from the [[IXTrunfile]] whose number of detector workspaces and monitor workspaces match those of the pair of D2D resulting from the operations on the detector and monitor D2D. If the D2D operations produce a pair whose dimensions do not match one of the two input pairs, then the operation is invalid. That is, we require the number of y values to satisfy
(nd1+d2, nm1+m2) = (nd1, nm1) or (nd2, nm2)
In particular this forbids the case where have (nd1,nm1)=(41472,1) and (nd2,nm2)=(1,3) – this would result in (41472,3) following the rules for adding D2D of different dimensions together. In the case when both α1 and α2 match, then take α1.

These rules are fine when d and m are assigned for both runfiles. Likewise, if m is assigned for neither, or d is assigned for neither, then we apply the same principles to just the d or the m, respectively. In summary:

α1 (d1,m1) + α2 (d2,m2) = α (d1+d2, m1+m2)
α is whichever of α1 and α2 match (α1 if both match); operation invalid if neither α1 nor α2 match
α1 (d1,-) + α2 (d2,-) = α (d1+d2, -)

α1 (-,m1) + α2 (-,m2) = α (-, m1+m2)

The above forbids some operations we would like to perform, in particular if the operation is ‘divide’ and we want to normalise the detectors by a monitor. In this case we would want to be able to achieve this operation by having no detector map file, i.e. we want
R1/R2 = α1(d1,m1) / α2(-,m2) = α1(d1/m2, m1/m2)
for m2 corresponding to a single monitor. So let’s consider the various combinations of unassigned detector and/or monitor d2D:

α1 (d1,-) + α2 (d2,m2) = α (d1+d2, d1+m2)
α is α2 if it matches; else operation is invalid. (This rule is the same as the one above, as α1 is guaranteed not to match)
α1 (-,m1) + α2 (d2,m2) = α (m1+d2, m1+m2)

and by symmetry;

α1 (d1, m1) + α2 (d2,-) = α (d1+d2, m1+d2)
α is α1 if it matches; else operation is invalid (This rule is the same as the one above, as α1 is guaranteed not to match)

α1 (d1, m1) + α2 (-,m2) = α (d1+m2, m1+m2)

(The qualitative rule here is: ‘if one of d and m is unassigned for just one of the two runfiles, fill in the missing d or m with the m or d respectively, then add as when nothing is missing’)

Finally:

α1 (d1,-) + α2 (-,m2) = α (d1+m2, -) Same rule on α as always

α1 (-, m1) + α2 (d2,-) = α (m1+d2, -)

== elementary functions ==

sin/cos/tan/sinh/cosh/tanh/exp/log/log10/deriv1x/deriv2x/shift_x

all these functions have a basic syntax and do not take any parameters except for shift_x

<pre>
>> runfile_out=fn(runfile_in)
</pre>

the operation is appled to both the monitor data and the detector data.

== other manipulations ==

these functions can be applied to either the monitor data only, the detector data only or both [[IXTdata]] objects in the [[IXTrunfile]]. These functions also take specific parameters associated with them.

rebin_x/rebunch_x/regroup_x/integrate_x

rebin_x_mon/rebunch_x_mon/regroup_x_mon/integrate_x_mon

rebin_x_det/rebunch_x_det/regroup_x_det/integrate_x_det

<pre>
>> runfile_out=fn_x(runfile_in,parameters)
>> runfile_out=fn_x_mon(runfile_in,parameters)
>> runfile_out=fn_x_det(runfile_in,parameters)
</pre>

IXTrunfile operations

2008-06-30T11:01:36Z

Dickon Champion: /* Binary operators for two run files */

It is possible to perform algebraic and mathematical operations on populated [[IXTrunfile]] objects

== runfile algebra ==

a+b

a-b

a*b

a/b

a^b

as the [[IXTrunfile]] object is more complicated than other simple datasets there are certain rules as to how a simple algebraic operation might be performed

Consider a run file as a pair of [[IXTdata]] objects, one for the detector information and one for the monitor information, together with various objects that are for everything else. The ‘everything else’ includes the instrument description, user, source, but in particular the [[IXTspectra]] and [[IXTdetector]] classes as part of IXTinstrument. The [[IXTdata]] object contains bridging arrays to the IXTspectra object. For the purposes of the algebra, lets write an [[IXTrunfile]] as:
R= α(d,m)

where
α the ‘everything else’
d dataset2D or array of dataset2D, or (if no detector map given) unassigned.

=== Binary operators with a d1d, d2d, scalar, vector, array ===

We permit the addition if the two conditions are true:
(i) the operation is valid on both the detector and monitor dataset2D (using whatever rules apply to dataset2d as at the moment)
(ii) the resultant detector and monitor dataset2d have the same sizes as the initial ones (this ensures that the ‘everything else is valid)

In summary, (if a dash refers to the detector or monitor IXTdata being unassigned):

α(d,m) + a = α(d+a,m+a)

α(d,-) + a = α(d+a,-)

α(-,m) + a = α(-,m+a)

=== Binary operators for two run files ===

The different cases for consideration when combining two runfiles are legion – what if they have different numbers of detector and or monitor mapping, what if they have the same number of workspaces but different grouping of spectra, what if they have no monitor workspaces, what if from different instrument? The best criteria for algebra are
* Simple to implement, which will probably also satisfy:
* Simple for a user to predict the behaviour,
* Not place undue restrictions on what can be combined,
* Does the sensible thing in commonly encountered situations.

Simple to implement is important, as it means code is also less prone to bugs. Simple for a user to predict is important – the outcome should be intuitively obvious. This will probably follow from ‘simple to implement’: if we don’t treat lots of special cases then the user won’t be worrying about lots of rules that need to be remembered. We shouldn’t place unnecessary restrictions: e.g. if a user wants to add MARI and HET data let them: they probably have a good reason to be trying to do so. It also means that the code doesn’t have to make copious checks, or worry too much about how to combine the ‘everything else’. Finally, the first three rules mean that the scheme will almost certainly do the sensible thing in common situations.

For the sake of definiteness, consider addition. The rules for any other binary operation will be the same. The minimum scheme is:
(i) Add the D2D for each of the detector and monitor data (using implicitly whatever rules we have in place for the algebra of dataset2d regarding sizes of arrays, units, point or histogram) i.e.
(d1,m1) + (d2,m2) = (d1+d2, m1+m2)
(ii) The ‘everything else’ comes from the [[IXTrunfile]] whose number of detector workspaces and monitor workspaces match those of the pair of D2D resulting from the operations on the detector and monitor D2D. If the D2D operations produce a pair whose dimensions do not match one of the two input pairs, then the operation is invalid. That is, we require the number of y values to satisfy
(nd1+d2, nm1+m2) = (nd1, nm1) or (nd2, nm2)
In particular this forbids the case where have (nd1,nm1)=(41472,1) and (nd2,nm2)=(1,3) – this would result in (41472,3) following the rules for adding D2D of different dimensions together. In the case when both α1 and α2 match, then take α1.

These rules are fine when d and m are assigned for both runfiles. Likewise, if m is assigned for neither, or d is assigned for neither, then we apply the same principles to just the d or the m, respectively. In summary:

α1 (d1,m1) + α2 (d2,m2) = α (d1+d2, m1+m2) α is whichever of α1 and α2 match (α1 if both match); operation invalid if neither α1 nor α2 match
α1 (d1,-) + α2 (d2,-) = α (d1+d2, -)

α1 (-,m1) + α2 (-,m2) = α (-, m1+m2)

The above forbids some operations we would like to perform, in particular if the operation is ‘divide’ and we want to normalise the detectors by a monitor. In this case we would want to be able to achieve this operation by having no detector map file, i.e. we want
R1/R2 = α1(d1,m1) / α2(-,m2) = α1(d1/m2, m1/m2)
for m2 corresponding to a single monitor. So let’s consider the various combinations of unassigned detector and/or monitor d2D:

α1 (d1,-) + α2 (d2,m2) = α (d1+d2, d1+m2) α is α2 if it matches; else operation is invalid. (This rule is the same as the one above, as α1 is guaranteed not to match)
α1 (-,m1) + α2 (d2,m2) = α (m1+d2, m1+m2)

and by symmetry;

α1 (d1, m1) + α2 (d2,-) = α (d1+d2, m1+d2) α is α1 if it matches; else operation is invalid (This rule is the same as the one above, as α1 is guaranteed not to match)

α1 (d1, m1) + α2 (-,m2) = α (d1+m2, m1+m2)

(The qualitative rule here is: ‘if one of d and m is unassigned for just one of the two runfiles, fill in the missing d or m with the m or d respectively, then add as when nothing is missing’)

Finally:

α1 (d1,-) + α2 (-,m2) = α (d1+m2, -) Same rule on α as always

α1 (-, m1) + α2 (d2,-) = α (m1+d2, -)

== elementary functions ==

sin/cos/tan/sinh/cosh/tanh/exp/log/log10/deriv1x/deriv2x/shift_x

all these functions have a basic syntax and do not take any parameters except for shift_x

<pre>
>> runfile_out=fn(runfile_in)
</pre>

the operation is appled to both the monitor data and the detector data.

== other manipulations ==

these functions can be applied to either the monitor data only, the detector data only or both [[IXTdata]] objects in the [[IXTrunfile]]. These functions also take specific parameters associated with them.

rebin_x/rebunch_x/regroup_x/integrate_x

rebin_x_mon/rebunch_x_mon/regroup_x_mon/integrate_x_mon

rebin_x_det/rebunch_x_det/regroup_x_det/integrate_x_det

<pre>
>> runfile_out=fn_x(runfile_in,parameters)
>> runfile_out=fn_x_mon(runfile_in,parameters)
>> runfile_out=fn_x_det(runfile_in,parameters)
</pre>

IXTrunfile operations

2008-06-30T11:01:11Z

Dickon Champion:

It is possible to perform algebraic and mathematical operations on populated [[IXTrunfile]] objects

== runfile algebra ==

a+b

a-b

a*b

a/b

a^b

as the [[IXTrunfile]] object is more complicated than other simple datasets there are certain rules as to how a simple algebraic operation might be performed

Consider a run file as a pair of [[IXTdata]] objects, one for the detector information and one for the monitor information, together with various objects that are for everything else. The ‘everything else’ includes the instrument description, user, source, but in particular the [[IXTspectra]] and [[IXTdetector]] classes as part of IXTinstrument. The [[IXTdata]] object contains bridging arrays to the IXTspectra object. For the purposes of the algebra, lets write an [[IXTrunfile]] as:
R= α(d,m)

where
α the ‘everything else’
d dataset2D or array of dataset2D, or (if no detector map given) unassigned.

=== Binary operators with a d1d, d2d, scalar, vector, array ===

We permit the addition if the two conditions are true:
(i) the operation is valid on both the detector and monitor dataset2D (using whatever rules apply to dataset2d as at the moment)
(ii) the resultant detector and monitor dataset2d have the same sizes as the initial ones (this ensures that the ‘everything else is valid)

In summary, (if a dash refers to the detector or monitor IXTdata being unassigned):

α(d,m) + a = α(d+a,m+a)

α(d,-) + a = α(d+a,-)

α(-,m) + a = α(-,m+a)

=== Binary operators for two run files ===

The different cases for consideration when combining two runfiles are legion – what if they have different numbers of detector and or monitor mapping, what if they have the same number of workspaces but different grouping of spectra, what if they have no monitor workspaces, what if from different instrument? The best criteria for algebra are
* Simple to implement, which will probably also satisfy:
* Simple for a user to predict the behaviour,
* Not place undue restrictions on what can be combined,
* Does the sensible thing in commonly encountered situations.

Simple to implement is important, as it means code is also less prone to bugs. Simple for a user to predict is important – the outcome should be intuitively obvious. This will probably follow from ‘simple to implement’: if we don’t treat lots of special cases then the user won’t be worrying about lots of rules that need to be remembered. We shouldn’t place unnecessary restrictions: e.g. if a user wants to add MARI and HET data let them: they probably have a good reason to be trying to do so. It also means that the code doesn’t have to make copious checks, or worry too much about how to combine the ‘everything else’. Finally, the first three rules mean that the scheme will almost certainly do the sensible thing in common situations.

For the sake of definiteness, consider addition. The rules for any other binary operation will be the same. The minimum scheme is:
(i) Add the D2D for each of the detector and monitor data (using implicitly whatever rules we have in place for the algebra of dataset2d regarding sizes of arrays, units, point or histogram) i.e.
(d1,m1) + (d2,m2) = (d1+d2, m1+m2)
(ii) The ‘everything else’ comes from the [[IXTrunfile]] whose number of detector workspaces and monitor workspaces match those of the pair of D2D resulting from the operations on the detector and monitor D2D. If the D2D operations produce a pair whose dimensions do not match one of the two input pairs, then the operation is invalid. That is, we require the number of y values to satisfy
(nd1+d2, nm1+m2) = (nd1, nm1) or (nd2, nm2)
In particular this forbids the case where have (nd1,nm1)=(41472,1) and (nd2,nm2)=(1,3) – this would result in (41472,3) following the rules for adding D2D of different dimensions together. In the case when both α1 and α2 match, then take α1.

These rules are fine when d and m are assigned for both runfiles. Likewise, if m is assigned for neither, or d is assigned for neither, then we apply the same principles to just the d or the m, respectively. In summary:

α1 (d1,m1) + α2 (d2,m2) = α (d1+d2, m1+m2) α is whichever of α1 and α2 match (α1 if both match); operation invalid if neither α1 nor α2 match
α1 (d1,-) + α2 (d2,-) = α (d1+d2, -)

α1 (-,m1) + α2 (-,m2) = α (-, m1+m2)

The above forbids some operations we would like to perform, in particular if the operation is ‘divide’ and we want to normalise the detectors by a monitor. In this case we would want to be able to achieve this operation by having no detector map file, i.e. we want
R1/R2 = α1(d1,m1) / α2(-,m2) = α1(d1/m2, m1/m2)
for m2 corresponding to a single monitor. So let’s consider the various combinations of unassigned detector and/or monitor d2D:

α1 (d1,-) + α2 (d2,m2) = α (d1+d2, d1+m2) α is α2 if it matches; else operation is invalid. (This rule is the same as the one above, as α1 is guaranteed not to match)
α1 (-,m1) + α2 (d2,m2) = α (m1+d2, m1+m2)

and by symmetry;

α1 (d1, m1) + α2 (d2,-) = α (d1+d2, m1+d2) α is α1 if it matches; else operation is invalid (This rule is the same as the one above, as α1 is guaranteed not to match)

α1 (d1, m1) + α2 (-,m2) = α (d1+m2, m1+m2)

(The qualitative rule here is: ‘if one of d and m is unassigned for just one of the two runfiles, fill in the missing d or m with the m or d respectively, then add as when nothing is missing’)

Finally:

α1 (d1,-) + α2 (-,m2) = α (d1+m2, -) Same rule on α as always

α1 (-, m1) + α2 (d2,-) = α (m1+d2, -)

3. Unary operators
3.1 Operations on x-axis
Ones which apply only to the x-axis, such as rebin_x, integrate_x, shift_x etc. are straightforward:

Ux[α(d,m)] = α(Ux[d], Ux[m])

== elementary functions ==

sin/cos/tan/sinh/cosh/tanh/exp/log/log10/deriv1x/deriv2x/shift_x

all these functions have a basic syntax and do not take any parameters except for shift_x

<pre>
>> runfile_out=fn(runfile_in)
</pre>

the operation is appled to both the monitor data and the detector data.

== other manipulations ==

these functions can be applied to either the monitor data only, the detector data only or both [[IXTdata]] objects in the [[IXTrunfile]]. These functions also take specific parameters associated with them.

rebin_x/rebunch_x/regroup_x/integrate_x

rebin_x_mon/rebunch_x_mon/regroup_x_mon/integrate_x_mon

rebin_x_det/rebunch_x_det/regroup_x_det/integrate_x_det

<pre>
>> runfile_out=fn_x(runfile_in,parameters)
>> runfile_out=fn_x_mon(runfile_in,parameters)
>> runfile_out=fn_x_det(runfile_in,parameters)
</pre>

IXTrunfile operations

2008-06-30T10:53:49Z

Dickon Champion:

It is possible to perform algebraic and mathematical operations on populated IXTrunfile objects

== runfile algebra ==

a+b

a-b

a*b

a/b

a^b

as the [[IXTrunfile]] object is more complicated than other simple datasets there are certain rules as to how a simple algebraic operation might be performed

Consider a run file as a pair of [[IXTdata]] objects, one for the detector information and one for the monitor information, together with various objects that are for everything else. The ‘everything else’ includes the instrument description, user, source, but in particular the [[IXTspectra]] and [[IXTdetector]] classes as part of IXTinstrument. The [[IXTdata]] object contains bridging arrays to the IXTspectra object. For the purposes of the algebra, lets write an [[IXTrunfile]] as:
R= α(d,m)

where
α the ‘everything else’
d dataset2D or array of dataset2D, or (if no detector map given) unassigned.

=== Binary operators with a d1d, d2d, scalar, vector, array ===

We permit the addition if the two conditions are true:
(i) the operation is valid on both the detector and monitor dataset2D (using whatever rules apply to dataset2d as at the moment)
(ii) the resultant detector and monitor dataset2d have the same sizes as the initial ones (this ensures that the ‘everything else is valid)

In summary, (if a dash refers to the detector or monitor IXTdata being unassigned):

α(d,m) + a = α(d+a,m+a)

α(d,-) + a = α(d+a,-)

α(-,m) + a = α(-,m+a)

=== Binary operators for two run files ===

The different cases for consideration when combining two runfiles are legion – what if they have different numbers of detector and or monitor mapping, what if they have the same number of workspaces but different grouping of spectra, what if they have no monitor workspaces, what if from different instrument? The best criteria for algebra are
* Simple to implement, which will probably also satisfy:
* Simple for a user to predict the behaviour,
* Not place undue restrictions on what can be combined,
* Does the sensible thing in commonly encountered situations.

Simple to implement is important, as it means code is also less prone to bugs. Simple for a user to predict is important – the outcome should be intuitively obvious. This will probably follow from ‘simple to implement’: if we don’t treat lots of special cases then the user won’t be worrying about lots of rules that need to be remembered. We shouldn’t place unnecessary restrictions: e.g. if a user wants to add MARI and HET data let them: they probably have a good reason to be trying to do so. It also means that the code doesn’t have to make copious checks, or worry too much about how to combine the ‘everything else’. Finally, the first three rules mean that the scheme will almost certainly do the sensible thing in common situations.

For the sake of definiteness, consider addition. The rules for any other binary operation will be the same. The minimum scheme is:
(i) Add the D2D for each of the detector and monitor data (using implicitly whatever rules we have in place for the algebra of dataset2d regarding sizes of arrays, units, point or histogram) i.e.
(d1,m1) + (d2,m2) = (d1+d2, m1+m2)
(ii) The ‘everything else’ comes from the [[IXTrunfile]] whose number of detector workspaces and monitor workspaces match those of the pair of D2D resulting from the operations on the detector and monitor D2D. If the D2D operations produce a pair whose dimensions do not match one of the two input pairs, then the operation is invalid. That is, we require the number of y values to satisfy
(nd1+d2, nm1+m2) = (nd1, nm1) or (nd2, nm2)
In particular this forbids the case where have (nd1,nm1)=(41472,1) and (nd2,nm2)=(1,3) – this would result in (41472,3) following the rules for adding D2D of different dimensions together. In the case when both α1 and α2 match, then take α1.

These rules are fine when d and m are assigned for both runfiles. Likewise, if m is assigned for neither, or d is assigned for neither, then we apply the same principles to just the d or the m, respectively. In summary:

α1 (d1,m1) + α2 (d2,m2) = α (d1+d2, m1+m2) α is whichever of α1 and α2 match (α1 if both match); operation invalid if neither α1 nor α2 match
α1 (d1,-) + α2 (d2,-) = α (d1+d2, -)

α1 (-,m1) + α2 (-,m2) = α (-, m1+m2)

The above forbids some operations we would like to perform, in particular if the operation is ‘divide’ and we want to normalise the detectors by a monitor. In this case we would want to be able to achieve this operation by having no detector map file, i.e. we want
R1/R2 = α1(d1,m1) / α2(-,m2) = α1(d1/m2, m1/m2)
for m2 corresponding to a single monitor. So let’s consider the various combinations of unassigned detector and/or monitor d2D:

α1 (d1,-) + α2 (d2,m2) = α (d1+d2, d1+m2) α is α2 if it matches; else operation is invalid. (This rule is the same as the one above, as α1 is guaranteed not to match)
α1 (-,m1) + α2 (d2,m2) = α (m1+d2, m1+m2)

and by symmetry;

α1 (d1, m1) + α2 (d2,-) = α (d1+d2, m1+d2) α is α1 if it matches; else operation is invalid (This rule is the same as the one above, as α1 is guaranteed not to match)

α1 (d1, m1) + α2 (-,m2) = α (d1+m2, m1+m2)

(The qualitative rule here is: ‘if one of d and m is unassigned for just one of the two runfiles, fill in the missing d or m with the m or d respectively, then add as when nothing is missing’)

Finally:

α1 (d1,-) + α2 (-,m2) = α (d1+m2, -) Same rule on α as always

α1 (-, m1) + α2 (d2,-) = α (m1+d2, -)

3. Unary operators
3.1 Operations on x-axis
Ones which apply only to the x-axis, such as rebin_x, integrate_x, shift_x etc. are straightforward:

Ux[α(d,m)] = α(Ux[d], Ux[m])

== elementary functions ==

sin/cos/tan/sinh/cosh/tanh/exp/log/log10

== other manipulations ==

rebin/rebunch/regroup/integrate/shift_x/deriv1x/deriv2x

IXTrunfile operations

2008-06-27T15:40:44Z

Dickon Champion:

It is possible to perform algebraic and mathematical operations on populated IXTrunfile objects

There are three basic types of functions

elementary functions

sin/cos/tan/sinh/cosh/tanh/exp/log/log10

runfile algebra

a+b

a-b

a*b

a/b

a^b

as the IXTrunfile object is more complicated than other simple datasets there are certain rules as to how a simple algebraic operation might be performed

Consider a run file as a pair of IXTdata objects, one for the detector information and one for the monitor information, together with various objects that are for everything else. The ‘everything else’ includes the instrument description, user, source, but in particular the IXTspectra and IXTdetector classes as part of IXTinstrument. The IXTdata object contains bridging arrays to the IXTspectra object. For the purposes of the algebra, lets write a run file as:
R= α(d,m)

where
α the ‘everything else’
d dataset2D or array of dataset2D, or (if no detector map given) unassigned.

1. Binary operators with a d1d, d2d, scalar, vector, array

We permit the addition if the two conditions are true:
(i) the operation is valid on both the detector and monitor dataset2D (using whatever rules apply to dataset2d as at the moment)
(ii) the resultant detector and monitor dataset2d have the same sizes as the initial ones (this ensures that the ‘everything else is valid)
(iii)
In summary, (if a dash refers to the detector or monitor IXTdata being unassigned):

α(d,m) + a = α(d+a,m+a)

α(d,-) + a = α(d+a,-)

α(-,m) + a = α(-,m+a)

2. Binary operators for two run files

The different cases for consideration when combining two runfiles are legion – what if they have different numbers of detector and or monitor mapping, what if they have the same number of workspaces but different grouping of spectra, what if they have no monitor workspaces, what if from different instrument … The best criteria for algebra are
- Simple to implement, which will probably also satisfy:
- Simple for a user to predict the behaviour,
- Not place undue restrictions on what can be combined,
- Does the sensible thing in commonly encountered situations.

Simple to implement is important, as it means code is also less prone to bugs. Simple for a user to predict is important – the outcome should be intuitively obvious. This will probably follow from ‘simple to implement’: if we don’t treat lots of special cases then the user won’t be worrying about lots of rules that need to be remembered. We shouldn’t place unnecessary restrictions: e.g. if a user wants to add MARI and HET data let them: they probably have a good reason to be trying to do so. It also means that the code doesn’t have to make copious checks, or worry too much about how to combine the ‘everything else’. Finally, the first three rules mean that the scheme will almost certainly do the sensible thing in common situations.

For the sake of definiteness, consider addition. The rules for any other binary operation will be the same. The minimum scheme is:
(i) Add the D2D for each of the detector and monitor data (using implicitly whatever rules we have in place for the algebra of dataset2d regarding sizes of arrays, units, point or histogram) i.e.
(d1,m1) + (d2,m2) = (d1+d2, m1+m2)
(ii) The ‘everything else’ comes from the runfile whose number of detector workspaces and monitor workspaces match those of the pair of D2D resulting from the operations on the detector and monitor D2D. If the D2D operations produce a pair whose dimensions do not match one of the two input pairs, then the operation is invalid. That is, we require the number of y values to satisfy
(nd1+d2, nm1+m2) = (nd1, nm1) or (nd2, nm2)
In particular this forbids the case where have (nd1,nm1)=(41472,1) and (nd2,nm2)=(1,3) – this would result in (41472,3) following the rules for adding D2D of different dimensions together. In the case when both α1 and α2 match, then take α1.

These rules are fine when d and m are assigned for both runfiles. Likewise, if m is assigned for neither, or d is assigned for neither, then we apply the same principles to just the d or the m, respectively. In summary:

α1 (d1,m1) + α2 (d2,m2) = α (d1+d2, m1+m2) α is whichever of α1 and α2 match (α1 if both match); operation invalid if neither α1 nor α2 match
α1 (d1,-) + α2 (d2,-) = α (d1+d2, -)

α1 (-,m1) + α2 (-,m2) = α (-, m1+m2)

The above forbids some operations we would like to perform, in particular if the operation is ‘divide’ and we want to normalise the detectors by a monitor. In this case we would want to be able to achieve this operation by having no detector map file, i.e. we want
R1/R2 = α1(d1,m1) / α2(-,m2) = α1(d1/m2, m1/m2)
for m2 corresponding to a single monitor. So let’s consider the various combinations of unassigned detector and/or monitor d2D:

α1 (d1,-) + α2 (d2,m2) = α (d1+d2, d1+m2) α is α2 if it matches; else operation is invalid. (This rule is the same as the one above, as α1 is guaranteed not to match)
α1 (-,m1) + α2 (d2,m2) = α (m1+d2, m1+m2)

and by symmetry;

α1 (d1, m1) + α2 (d2,-) = α (d1+d2, m1+d2) α is α1 if it matches; else operation is invalid (This rule is the same as the one above, as α1 is guaranteed not to match)

α1 (d1, m1) + α2 (-,m2) = α (d1+m2, m1+m2)

(The qualitative rule here is: ‘if one of d and m is unassigned for just one of the two runfiles, fill in the missing d or m with the m or d respectively, then add as when nothing is missing’)

Finally:

α1 (d1,-) + α2 (-,m2) = α (d1+m2, -) Same rule on α as always

α1 (-, m1) + α2 (d2,-) = α (m1+d2, -)

3. Unary operators
3.1 Operations on x-axis
Ones which apply only to the x-axis, such as rebin_x, integrate_x, shift_x etc. are straightforward:

Ux[α(d,m)] = α(Ux[d], Ux[m])

other manipulations

rebin/rebunch/regroup/integrate/shift_x/deriv1x/deriv2x

IXTrunfile operations

2008-06-27T15:40:17Z

Dickon Champion:

It is possible to perform algebraic and mathematical operations on populated IXTrunfile objects

There are three basic types of functions

elementary functions

sin/cos/tan/sinh/cosh/tanh/exp/log/log10

runfile algebra

a+b
a-b
a*b
a/b
a^b

as the IXTrunfile object is more complicated than other simple datasets there are certain rules as to how a simple algebraic operation might be performed

Consider a run file as a pair of IXTdata objects, one for the detector information and one for the monitor information, together with various objects that are for everything else. The ‘everything else’ includes the instrument description, user, source, but in particular the IXTspectra and IXTdetector classes as part of IXTinstrument. The IXTdata object contains bridging arrays to the IXTspectra object. For the purposes of the algebra, lets write a run file as:
R= α(d,m)

where
α the ‘everything else’
d dataset2D or array of dataset2D, or (if no detector map given) unassigned.

1. Binary operators with a d1d, d2d, scalar, vector, array

We permit the addition if the two conditions are true:
(i) the operation is valid on both the detector and monitor dataset2D (using whatever rules apply to dataset2d as at the moment)
(ii) the resultant detector and monitor dataset2d have the same sizes as the initial ones (this ensures that the ‘everything else is valid)
(iii)
In summary, (if a dash refers to the detector or monitor IXTdata being unassigned):

α(d,m) + a = α(d+a,m+a)

α(d,-) + a = α(d+a,-)

α(-,m) + a = α(-,m+a)

2. Binary operators for two run files

The different cases for consideration when combining two runfiles are legion – what if they have different numbers of detector and or monitor mapping, what if they have the same number of workspaces but different grouping of spectra, what if they have no monitor workspaces, what if from different instrument … The best criteria for algebra are
- Simple to implement, which will probably also satisfy:
- Simple for a user to predict the behaviour,
- Not place undue restrictions on what can be combined,
- Does the sensible thing in commonly encountered situations.

Simple to implement is important, as it means code is also less prone to bugs. Simple for a user to predict is important – the outcome should be intuitively obvious. This will probably follow from ‘simple to implement’: if we don’t treat lots of special cases then the user won’t be worrying about lots of rules that need to be remembered. We shouldn’t place unnecessary restrictions: e.g. if a user wants to add MARI and HET data let them: they probably have a good reason to be trying to do so. It also means that the code doesn’t have to make copious checks, or worry too much about how to combine the ‘everything else’. Finally, the first three rules mean that the scheme will almost certainly do the sensible thing in common situations.

For the sake of definiteness, consider addition. The rules for any other binary operation will be the same. The minimum scheme is:
(i) Add the D2D for each of the detector and monitor data (using implicitly whatever rules we have in place for the algebra of dataset2d regarding sizes of arrays, units, point or histogram) i.e.
(d1,m1) + (d2,m2) = (d1+d2, m1+m2)
(ii) The ‘everything else’ comes from the runfile whose number of detector workspaces and monitor workspaces match those of the pair of D2D resulting from the operations on the detector and monitor D2D. If the D2D operations produce a pair whose dimensions do not match one of the two input pairs, then the operation is invalid. That is, we require the number of y values to satisfy
(nd1+d2, nm1+m2) = (nd1, nm1) or (nd2, nm2)
In particular this forbids the case where have (nd1,nm1)=(41472,1) and (nd2,nm2)=(1,3) – this would result in (41472,3) following the rules for adding D2D of different dimensions together. In the case when both α1 and α2 match, then take α1.

These rules are fine when d and m are assigned for both runfiles. Likewise, if m is assigned for neither, or d is assigned for neither, then we apply the same principles to just the d or the m, respectively. In summary:

α1 (d1,m1) + α2 (d2,m2) = α (d1+d2, m1+m2) α is whichever of α1 and α2 match (α1 if both match); operation invalid if neither α1 nor α2 match
α1 (d1,-) + α2 (d2,-) = α (d1+d2, -)

α1 (-,m1) + α2 (-,m2) = α (-, m1+m2)

The above forbids some operations we would like to perform, in particular if the operation is ‘divide’ and we want to normalise the detectors by a monitor. In this case we would want to be able to achieve this operation by having no detector map file, i.e. we want
R1/R2 = α1(d1,m1) / α2(-,m2) = α1(d1/m2, m1/m2)
for m2 corresponding to a single monitor. So let’s consider the various combinations of unassigned detector and/or monitor d2D:

α1 (d1,-) + α2 (d2,m2) = α (d1+d2, d1+m2) α is α2 if it matches; else operation is invalid. (This rule is the same as the one above, as α1 is guaranteed not to match)
α1 (-,m1) + α2 (d2,m2) = α (m1+d2, m1+m2)

and by symmetry;

α1 (d1, m1) + α2 (d2,-) = α (d1+d2, m1+d2) α is α1 if it matches; else operation is invalid (This rule is the same as the one above, as α1 is guaranteed not to match)

α1 (d1, m1) + α2 (-,m2) = α (d1+m2, m1+m2)

(The qualitative rule here is: ‘if one of d and m is unassigned for just one of the two runfiles, fill in the missing d or m with the m or d respectively, then add as when nothing is missing’)

Finally:

α1 (d1,-) + α2 (-,m2) = α (d1+m2, -) Same rule on α as always

α1 (-, m1) + α2 (d2,-) = α (m1+d2, -)

3. Unary operators
3.1 Operations on x-axis
Ones which apply only to the x-axis, such as rebin_x, integrate_x, shift_x etc. are straightforward:

Ux[α(d,m)] = α(Ux[d], Ux[m])

other manipulations

rebin/rebunch/regroup/integrate/shift_x/deriv1x/deriv2x

Using Homer and Getting Started

2008-06-27T15:34:21Z

Dickon Champion:

* [[Getting Started]] '''VERY IMPORTANT''' setup details defined

* [[Homer GUI]] - mini tutorial with screenshots

*[[Scripting Homer Functions]] are easy to use functions which call homer related functions underneath, as well as setting up the [[IXTdata_source]] object for use by homer

*[[Homer and mgenie style functions]] Direct calls to homer and some mgenie style functions

*[[Homer Utilities]] head and get_ei

*[[IXTrunfile operations]] including algebra, elementary functions and other manipulations

*[[diagnose]] diagnostic function for homer input

*[[Example Scripts]]

Using Homer and Getting Started

2008-06-27T15:30:52Z

Dickon Champion:

* [[Getting Started]] '''VERY IMPORTANT''' setup details defined

* [[Homer GUI]] - mini tutorial with screenshots

*[[Scripting Homer Functions]] are easy to use functions which call homer related functions underneath, as well as setting up the [[IXTdata_source]] object for use by homer

*[[Homer and mgenie style functions]] Direct calls to homer and some mgenie style functions

*[[Homer Utilities]] head and get_ei

*[[IXTrunfile algebra]]

*[[diagnose]] diagnostic function for homer input

*[[Example Scripts]]

Using Homer and Getting Started

2008-06-27T15:30:40Z

Dickon Champion:

* [[Getting Started]] '''VERY IMPORTANT''' setup details defined

* [[Homer GUI]] - mini tutorial with screenshots

*[[Scripting Homer Functions]] are easy to use functions which call homer related functions underneath, as well as setting up the [[IXTdata_source]] object for use by homer

*[[Homer and mgenie style functions]] Direct calls to homer and some mgenie style functions

*[[Homer Utilities]] head and get_ei

*[[Runfile algebra]]

*[[diagnose]] diagnostic function for homer input

*[[Example Scripts]]

Input and Output Functions

2008-06-27T15:23:07Z

Dickon Champion: /* Nexus Files */

== ASCII Files ==

* [[IXTdataset_1d]] objects may be stored in ASCII files.
* These files may contain x and y data ''or'' x, s, error data in a 2 or 3 column format.
* Column 1 will be x values, column 2 will be s values and if available column 3 will be error values, if not available then error is assumed to be 0.
* Any information at the start or end of the file that is not in a 2 or 3 column format is '''ignored''' (for instance, ''header information'' may be stored here).
* Columns may be separated by commas, tabs, or spaces.
* ASCII files may contain point or histogram data, the x column in histogram data will have one more value than the s and e columns.

* The following files would all be acceptable ASCII files

<pre>title = plots1 xaxis = wavelength yaxis = signal
490.2 30000
491.2 31923
492.2 40000</pre>

Represents a three point dataset with 0 error.

<pre>title = plots1 xaxis = wavelength yaxis = signal
490.2 30000 300
491.2 31923 300
492.2 40000 250
493.2</pre>

Represents a 3 column histogram dataset with error data.

<pre>490.2,30000,300
491.2,31923,300
492.2,40000,250
493.2
</pre>

Will represent the same 3 column histogram dataset with error data.

* When files are '''written''' by libisis a header is written at the top of the file with the following information

<pre>name = dataset name
title = dataset title
signal_units = dataset s axis label
x_units = dataset x axis label
x_distribution = 1

x1 s1 e1
x2 s2 e2
...</pre>

where the header information is taken from the dataset being written.

* To read and write ASCII files in the format (point or histogram) specified by the file or dataset use

<pre>>> read_ascii('filename')
>> write_ascii(dataset,'filename')</pre>

if no filename is given then the user will be prompted to locate the file.

=== Point Data ===
One can force the written or read ASCII file to be in the form of point data by using the commands

<pre>>>read_points('filename')
write_points(dataset, 'filename')</pre>

=== Histogram Data ===
One can force the written or read ASCII file to be in the form of histogram data by using the commands

<pre>>> read_hist('filename')
>> write_hist(dataset, 'filename')</pre>

== RAW Files ==

RAW files come directly from instruments and can also be read into Libisis. Data can then be extracted from the RAW file to form an [[IXTdataset_1d]] or an [[IXTdataset_2d]] object.

* To read in a rawfile (in the form of an [[IXTraw_file]] object) use the command

<pre>>> rawfile1 = IXTraw_file('filename')</pre>

* To read data into an [[IXTdataset_1d]] object use the command

<pre>>> dataset = getspectrum(rawfile1, spectrum_number)</pre>

where '''spectrum_number''' is the spectrum which is required.

* to read multiple runs into an [[IXTdataset_2d]] object use the command

<pre>>> dataset_2d = getspectra(rawfile1, [start:end])</pre>

where start and end are the initial and final spectrum to include in the dataset_2d.

''''' EXAMPLE: '''''

<pre>>> rawfile1 = IXTraw_file('c:/RAWfiles/HET15958');
>> nsp = geti(rawfile1,'nsp1');
>> d2a = getspectra(rawfile1, [1:nsp]);
>> d1a = getspectrum(rawfile1, 25); </pre>

this will load all spectra from the HET15958 raw file contained in the folder c:/RAWfiles into an [[IXTdataset_2d]] object called d2a and load spectrum 25 into an [[IXTdataset_1d]] object name d1a.

* Other information is contained in the rawfile, see [[IXTraw_file]] documentation for more information.

==Slices, Cuts and Masks==

Some other programs can generate a slice, cut or mask object. Two such programs are mslice and Horace.

A slice can be read into a Libisis [[IXTdataset_2d]] object using the command

<pre>>>w = read_slice(filename)
w = read_slice</pre>

* '''filename''' is a string containing the location of the .slc file
* If filename is not given then a prompt will ask the user to locate the file
* Output is an [[IXTdataset_2d]], with as much information taken from the slice as possible, otherwise fields are blank.

Similarly, a Mask or a cut from Horace / mslice can be read into Libisis [[IXTdataset_1d]] objects using the commands

<pre>>>w = read_cut(filename)
>> w = read_mask(filename)</pre>

* '''filename''' is a string containing the location of the .cut or .msk file
* If filename is not given then a prompt will ask the user to locate the file
* Output is an [[IXTdataset_1d]], with as much information taken from the cut / mask as possible, otherwise fields are blank.

== Nexus Files==

Objects can be written to file in hdf format using the nexus API, using the write_nxs function. These files can also be read in using the read_nxs command.

<pre>>> write_nxs(IXTobject,'filename', entry)</pre>

*'''IXTobject''' is the object that is being written out (i.e. [[IXTrunfile]], [[IXTdataset_2d]])
*'''filename''' is a string showing the location of the .nxs file which is being written
*'''entry''' is a string, the top level directory to write the object to (i.e. 'runfile'), by ''default'' it is 'object' (optional)

'''''Example:'''''

<tt> write_nxs(IXTrunfile,'C:/nexusfiles/maps1020.nxs')</tt>

writes the data from the IXTrunfile object into the top-level directory 'runfile' of the maps1020.nxs file

<pre>>>w = read_nxs(filename, IXTobject, entry)</pre>

*'''filename''' is a string showing the location of the .nxs file
*'''IXTobject''' is the type of object that the data is being read into (i.e. [[IXTrunfile]], [[IXTdataset_2d]])
*'''entry''' is a string, the top level directory to read the object from (i.e. 'runfile'), by ''default'' it is 'object' (optional)
* '''w''' is the actual object which will hold the data being read, it will be of the same object type as IXTobject (i.e. [[IXTrunfile]])

'''''Example:'''''

<tt>wout = read_nxs('C:/nexusfiles/maps1020.nxs', IXTrunfile, 'runfile')</tt>

reads the data from the runfile top directory into the wout object that will be an [[IXTrunfile]] object.

== Other Formats ==

Data can be read from other formats or in other ways, such as using [[Homer_and_mgenie_style_functions| Homer]] to populate an [[IXTrunfile]] object.

Download and setup LIBISIS

2008-06-27T14:28:34Z

Dickon Champion: /* Download LIBISIS */

== Download Homer 'blackbox' ==
* If you do not have matlab it is possible to download an executable which will run the homer GUI standalone

{| {{Tablestyle}}
|-
! {{Headcellstyle}} | Windows
!{{Headcellstyle}} | Linux
! {{Headcellstyle}} | MacOS
|-
| [[Media:homer_blackbox.zip|homer_blackbox.zip]]
| not available
| not available
|}

you must also install the matlab [[Media:mcrinstaller.exe|mcr runtime libraries]] for it to work

== Download LIBISIS ==
* Download the latest libisis build for your version of matlab,(currently the only download will work with Matlab 2007a or later)

{| {{Tablestyle}}
|-
! {{Headcellstyle}} | Windows
!{{Headcellstyle}} | Linux
! {{Headcellstyle}} | MacOS
|-
|
[[Media:7sp3_libisis.zip|matlab7sp3_libisis.zip]]

[[Media:2006a_libisis.zip|2006a_libisis.zip]]

[[Media:2006b_libisis.zip|2006b_libisis.zip]]

[[Media:libisis.zip|2007a_libisis.zip]]

[[Media:2007b_libisis.zip|2007b_libisis.zip]]

| not available at the moment, requires extra rpms
| not available at the moment
|}

===Windows===
* Unpack this file into <tt>'''C:\mprogs'''</tt> or a directory of your choice eg <tt>'''X:\analysis'''</tt>

===Requirements===

* Matlab 2007a (or later)
* 1GB RAM memory
* 40MB free hard drive space

== Setup Paths ==
* Copy the libisis_start.m file into <tt>C:\mprogs</tt> or into the directory where your matlab starts

* there are two ways you can make sure the paths are set in the matlab instance
# call the libisis_start function from the command line, with the name of the libisis directory which was unpacked see the example below
# or you can add the line below into your startup.m, the path to the libisis_start function '''must''' of course be in the matlab path, so you may have to add C:\mprogs or X:\analysis to the path in the startup.m already

<pre>
>> libisis_start('C:\mprogs\libisis_2008_01_18_1356')
>>
>> libisis_start('X:\analysis\libisis_2008_01_18_1356')
</pre>

== Setup Memory Usage ==

Sometimes when we are treating large datasets, such as on MAPS, we cannot load all the data into the memory of the computer at once, we need to 'chunk' the data into smaller pieces. We therefore need to set the default number of workspaces in each 'chunk' to treat at any one time during the population of an [[IXTrunfile]] and the total amount of memory to allow the computer to use.

If the memory required for the number of workspaces in each chunk is greater than that defined then the number of workspaces is reduced until it fits in the memory or a failure status is raised. These two values are defined in <tt>./matlab/homer/default_homer_nchunk.m</tt> which needs to be edited to suit the memory needs of your computer. Tests have shown that LIBISIS will populate data fastest when it is chunked in groups of 100 workspaces, so this is the default value in the file.

<pre>
function nchunk=default_homer_nchunk
% nchunk = default_homer_nchunk
% nchunk is a two membered array
% the first element is the default number of workspaces to be treated at
% one time, and the second element is the maximum amount of memory (in MB)
% that you want the computer to use
nchunk=int32([100,500]);
</pre>

Download and setup LIBISIS

2008-06-27T14:23:05Z

Dickon Champion: /* Download LIBISIS */

== Download Homer 'blackbox' ==
* If you do not have matlab it is possible to download an executable which will run the homer GUI standalone

{| {{Tablestyle}}
|-
! {{Headcellstyle}} | Windows
!{{Headcellstyle}} | Linux
! {{Headcellstyle}} | MacOS
|-
| [[Media:homer_blackbox.zip|homer_blackbox.zip]]
| not available
| not available
|}

you must also install the matlab [[Media:mcrinstaller.exe|mcr runtime libraries]] for it to work

== Download LIBISIS ==
* Download the latest libisis build for your version of matlab,(currently the only download will work with Matlab 2007a or later)

{| {{Tablestyle}}
|-
! {{Headcellstyle}} | Windows
!{{Headcellstyle}} | Linux
! {{Headcellstyle}} | MacOS
|-
|
[[Media:matlab7sp3_libisis.zip|matlab7sp3_libisis.zip]]

[[Media:2006a_libisis.zip|2006a_libisis.zip]]

[[Media:2006b_libisis.zip|2006b_libisis.zip]]

[[Media:libisis.zip|2007a_libisis.zip]]

[[Media:2007b_libisis.zip|2007b_libisis.zip]]

| not available at the moment, requires extra rpms
| not available at the moment
|}

===Windows===
* Unpack this file into <tt>'''C:\mprogs'''</tt> or a directory of your choice eg <tt>'''X:\analysis'''</tt>

===Requirements===

* Matlab 2007a (or later)
* 1GB RAM memory
* 40MB free hard drive space

== Setup Paths ==
* Copy the libisis_start.m file into <tt>C:\mprogs</tt> or into the directory where your matlab starts

* there are two ways you can make sure the paths are set in the matlab instance
# call the libisis_start function from the command line, with the name of the libisis directory which was unpacked see the example below
# or you can add the line below into your startup.m, the path to the libisis_start function '''must''' of course be in the matlab path, so you may have to add C:\mprogs or X:\analysis to the path in the startup.m already

<pre>
>> libisis_start('C:\mprogs\libisis_2008_01_18_1356')
>>
>> libisis_start('X:\analysis\libisis_2008_01_18_1356')
</pre>

== Setup Memory Usage ==

Sometimes when we are treating large datasets, such as on MAPS, we cannot load all the data into the memory of the computer at once, we need to 'chunk' the data into smaller pieces. We therefore need to set the default number of workspaces in each 'chunk' to treat at any one time during the population of an [[IXTrunfile]] and the total amount of memory to allow the computer to use.

If the memory required for the number of workspaces in each chunk is greater than that defined then the number of workspaces is reduced until it fits in the memory or a failure status is raised. These two values are defined in <tt>./matlab/homer/default_homer_nchunk.m</tt> which needs to be edited to suit the memory needs of your computer. Tests have shown that LIBISIS will populate data fastest when it is chunked in groups of 100 workspaces, so this is the default value in the file.

<pre>
function nchunk=default_homer_nchunk
% nchunk = default_homer_nchunk
% nchunk is a two membered array
% the first element is the default number of workspaces to be treated at
% one time, and the second element is the maximum amount of memory (in MB)
% that you want the computer to use
nchunk=int32([100,500]);
</pre>

Download and setup LIBISIS

2008-06-27T14:20:40Z

Dickon Champion:

== Download Homer 'blackbox' ==
* If you do not have matlab it is possible to download an executable which will run the homer GUI standalone

{| {{Tablestyle}}
|-
! {{Headcellstyle}} | Windows
!{{Headcellstyle}} | Linux
! {{Headcellstyle}} | MacOS
|-
| [[Media:homer_blackbox.zip|homer_blackbox.zip]]
| not available
| not available
|}

you must also install the matlab [[Media:mcrinstaller.exe|mcr runtime libraries]] for it to work

== Download LIBISIS ==
* Download the latest libisis build (This download will work with Matlab 2007a or later)

{| {{Tablestyle}}
|-
! {{Headcellstyle}} | Windows
!{{Headcellstyle}} | Linux
! {{Headcellstyle}} | MacOS
|-
|
[[Media:matlab7sp3_libisis.zip|matlab7sp3_libisis.zip]]

[[Media:2006a_libisis.zip|2006a_libisis.zip]]

[[Media:2006b_libisis.zip|2006b_libisis.zip]]

[[Media:libisis.zip|2007a_libisis.zip]]

[[Media:2007b_libisis.zip|2007b_libisis.zip]]

| not available at the moment, requires extra rpms
| not available at the moment
|}

===Windows===
* Unpack this file into <tt>'''C:\mprogs'''</tt> or a directory of your choice eg <tt>'''X:\analysis'''</tt>

===Requirements===

* Matlab 2007a (or later)
* 1GB RAM memory
* 40MB free hard drive space

== Setup Paths ==
* Copy the libisis_start.m file into <tt>C:\mprogs</tt> or into the directory where your matlab starts

* there are two ways you can make sure the paths are set in the matlab instance
# call the libisis_start function from the command line, with the name of the libisis directory which was unpacked see the example below
# or you can add the line below into your startup.m, the path to the libisis_start function '''must''' of course be in the matlab path, so you may have to add C:\mprogs or X:\analysis to the path in the startup.m already

<pre>
>> libisis_start('C:\mprogs\libisis_2008_01_18_1356')
>>
>> libisis_start('X:\analysis\libisis_2008_01_18_1356')
</pre>

== Setup Memory Usage ==

Sometimes when we are treating large datasets, such as on MAPS, we cannot load all the data into the memory of the computer at once, we need to 'chunk' the data into smaller pieces. We therefore need to set the default number of workspaces in each 'chunk' to treat at any one time during the population of an [[IXTrunfile]] and the total amount of memory to allow the computer to use.

If the memory required for the number of workspaces in each chunk is greater than that defined then the number of workspaces is reduced until it fits in the memory or a failure status is raised. These two values are defined in <tt>./matlab/homer/default_homer_nchunk.m</tt> which needs to be edited to suit the memory needs of your computer. Tests have shown that LIBISIS will populate data fastest when it is chunked in groups of 100 workspaces, so this is the default value in the file.

<pre>
function nchunk=default_homer_nchunk
% nchunk = default_homer_nchunk
% nchunk is a two membered array
% the first element is the default number of workspaces to be treated at
% one time, and the second element is the maximum amount of memory (in MB)
% that you want the computer to use
nchunk=int32([100,500]);
</pre>

Matlab Bindings

2008-05-16T16:27:13Z

Dickon Champion:

==Introduction==
The main binding to the Libisis framework which has been implemented is matlab. Each type defined in the framework has a module which contains type-specific methods for getting objects and variables from the matlab front-end and sending objects and variables back to the matlab front-end. These methods are called using two interfaces which are defined in a module <tt>IXMm_classname</tt>.

* <tt>IXBgetFromBinding</tt>
* <tt>IXBsendToBinding</tt>

This module is always defined in the file <tt>bindings/matlab/IXMclassname_m.f90</tt>. As a rule this module always contains the line <tt>use IXMclassname</tt> (it is however included automatically and does not need to be explicitly specified in the code)

The interfaces and methods of the <tt>IXMm_classname</tt> module are generated automatically using the preprocessor, in the following example for the <tt>IXTtestclass</tt> object in the <tt>IXMtestclass_m.f90</tt> file. These are the '''only''' statements required to define the <tt>IXMm_testclass</tt> module.

<pre>
module IXMm_testclass

#define IXD_TYPE testclass
#include "bindings_header.f90"

contains

#define IXD_TYPE testclass
#include "bindings_base.f90"

end module IXMm_testclass
</pre>

If a class method implemented in the fortran framework is to be called from the matlab front-end various steps need to be followed.

==define an appropriate binding subroutine in <tt>IXMclassname_m.f90</tt> ==

functions which are called from matlab are defined in the same file but outside of the <tt>IXMm_classname</tt> module. They are all prefixed with <tt>IXB</tt>. all the standard functions which are called such as <tt>IXBdisplay_classname, IXBcheck_classname</tt> are auto-generated using the preprocessor, so do not need any extra implementation.

<pre>
#define IXD_TYPE testclass
#include "bindings_extra.f90"
</pre>

only functions which are extra to the standard module subroutines which you need to call from matlab have to have a binding subroutine defined. We can create an <tt>IXBplus_testclass</tt> subroutine to allow matlab calling of the [[Libclasses#Example_object_method|IXFplus_testclass]] method of <tt>IXTtestclass</tt>.

The arguments of every <tt>IXBmethod_classname</tt> subroutine are the same
* <tt>nlhs</tt> is the number of left hand side arguments from matlab (ie what is the output of the matlab call)
* <tt>plhs(nlhs)</tt> is an array of pointers to the left hand side arguments
* <tt>nrhs</tt> is the number of right hand side arguments from matlab (ie what are the arguments of the matlab call)
* <tt>prhs(nrhs)</tt> is an array of pointers to the right hand side arguments

for the most part memory is shared between the matlab binding and fortran framework, so we work with pointers.

there are four types of subroutine which can be called, each with different variables which are returned to the matlab front-end
# functions which have no variable output eg. display,check (defined in <tt>bindings_base.f90</tt>)
# functions which return a simple type (<tt>real, integer, character</tt>) eg. getting a value from an object
# functions which return an object(s) (<tt>IXTtestclass, IXTdataset_2d</tt>) eg. the result of a plus operation (defined below)
# functions which return an object(s) and a simple type back to matlab

the <tt>IXBgetFromBinding</tt> command reads data into a variable which has been passed down to the bindings layer from the matlab front-end. the call syntax is defined below.
<pre>
call IXFgetFromBinding(prhs(number),' ',1,0,variable,status)
call IXFgetFromBindingPtr(prhs(number),' ',1,0,variable,status)
</pre>
* the 1st argument defines which matlab pointer to read the data from according to <tt>number</tt>, which refers to the position of the right hand side argument when the [[Matlab Bindings#write an appropriate matlab function|matlab function]] is called
* the 2nd, 3rd & 4th arguments are '''always''' <tt> ' ',1,0 </tt>
* the 5th argument is the variable to be populated
* if a variable length array is to be populated, the variable is defined as a <tt>pointer</tt> and the <tt>IXBgetFromBindingPtr</tt> subroutine is called, with the same syntax
* if a structure is to be returned to the matlab front-end <tt>prhs(1)</tt> is generally reserved for the object to be returned, it does not need to be read in, more details are specified [[Matlab Bindings#write an appropriate matlab function|below]]

when data is sent back to the matlab front-end the <tt>IXBsendToBinding</tt> subroutine is called. There are two possible syntaxes:

1) if we are returning a simple type variable
<pre>
call IXFsendToBinding(plhs(number_left),' ',1,0,variable,status)
</pre>
* the 1st argument defines which matlab pointer to write the data in to according to <tt>number_left</tt>, which refers to the position of the left hand side argument when the [[Matlab Bindings#write an appropriate matlab function|matlab function]] is called
* the 2nd, 3rd & 4th arguments are '''always''' <tt> ' ',1,0 </tt>
* the 5th argument is the variable to be sent back to the matlab front-end

2) if we are returning a structure
<pre>
call IXFsendToBinding(plhs(number_left),prhs(number_right),' ',1,0,variable,status)
</pre>
* the 1st argument defines which matlab pointer to write the data in to according to <tt>number_left</tt>, which refers to the position of the left hand side argument when the [[Matlab Bindings#write an appropriate matlab function|matlab function]] is called
* the 2nd argument is the return type which has been sent from matlab
* the 3rd, 4th & 5th arguments are '''always''' <tt> ' ',1,0 </tt>
* the 6th argument is the variable to be populated, it '''must''' agree with the type which has been sent in <tt>prhs(number_right)</tt>

an example <tt>IXBmethod_classname</tt> is defined below
<pre>
subroutine IXBplus_testclass(nlhs, plhs, nrhs, prhs, status)
</pre>
this provides access to the <tt>IXBgetFromBinding</tt> and <tt>IXBsendtoBinding</tt> interfaces to read/write variables from/to matlab
<pre>
use IXMm_testclass
implicit none
</pre>
standard declarations
<pre>
integer :: nlhs, nrhs
integer(cpointer_t) :: plhs(nlhs), prhs(nrhs)
</pre>
* declarations of input and output objects used by the method called
* array input is defined as a pointer
<pre>
type(IXTtestclass) :: wres, w1, w2
real(dp),pointer::array(:)
type(IXTstatus) :: status
</pre>
* read in two structures which will be added together
* check read went OK - report errors and return if not
<pre>
call IXBgetFromBinding(prhs(2),' ', 1, 0, w1, status)
call IXBgetFromBinding(prhs(3),' ', 1, 0, w2, status)
call IXBgetFromBindingPtr(prhs(4),' ', 1, 0, array, status)
if (status == IXCseverity_error) return
</pre>
do adding operation
<pre>
call IXFplus_testclass(wres, w1, w2,array, status)
</pre>
wres has now been filled and needs to be entered into the matlab memory if the process was successfull
<pre>
if (status == IXCseverity_error) then
plhs(1)=ixDuplicateArray(prhs(1))
else
call IXBsendToBinding(plhs(1), prhs(1), ' ', 1, 0, wres, status)
endif
end subroutine IXBplus_testclass
</pre>

===preprocessing operations===

preprocesing can also be used to generate common code in the bindings, for example to create general code for unary operations (log, exp,sin etc...) called from the matlab front-end, there is explanation on preprocessing files [[Libclasses#Preprocessing files|here]]

in the file <tt>bindings/matlab/IXMdataset_2d_m.f90</tt> the KEYWORDS are defined
<pre>
#define IXD_TYPE dataset_2d
#define IXD_NAME Sin_Dataset_2d
#include "unary_ops.f90"
</pre>

and in the include file <tt>bindings/matlab/unary_ops.f90</tt> they are substituted
<pre>
#if defined(IXD_TYPE) && defined(IXD_NAME)

subroutine IXB&/**/
&IXD_NAME (nlhs, plhs, nrhs, prhs, s)
use IXMm_&/**/
&IXD_TYPE
implicit none
integer :: nlhs,nrhs
integer(cpointer_t) :: plhs(nlhs),prhs(nrhs)
type(IXT&/**/
&IXD_TYPE ), allocatable :: wres(:), w1(:)
type(IXTstatus) :: s
integer n, i
n = ixGetNumberOfElements(prhs(2))
allocate(w1(n),wres(n))
call IXBgetFromBinding(prhs(2), ' ', 1, 0, w1, s)
if (s == IXCseverity_error) return
do i = 1,n
call IXF&/**/
&IXD_NAME (wres(i),w1(i),s)
enddo
if (s == IXCseverity_error) then
plhs(1)=ixDuplicateArray(prhs(1))
else
call IXBsendToBinding(plhs(1), prhs(1), ' ', 1, 0, wres, s)
endif
deallocate(w1,wres)
end subroutine

#undef IXD_NAME
#undef IXD_TYPE

#endif /* defined(IXD_TYPE) && defined(IXD_NAME) */
</pre>

==define object method pair in <tt>bindings/matlab/libisisexc.txt</tt> ==
we need to define all the subroutines which need to be accessed from the matlab front-end in another file, together with the number of input and output arguments. they are defined as a classname/method pair in the <tt>bindings/matlab/libisisexc.txt</tt> file with a general constuction:
<pre>
IXTclassname method no_of_output_args no_of_input_args
</pre>

if the number of arguments is variable then -1 is defined. the number of arguments is essentially <tt>nrhs</tt>

where <tt>#</tt> is a comment character, the definition for IXTtestclass is as follows:
<pre>
#
# IXTtestclass
#
IXTtestclass plus 1 4
IXTtestclass display 0 1
IXTtestclass create 1 2
IXTtestclass check 1 1
IXTtestclass read 1 3
IXTtestclass write 1 3
</pre>

==write an appropriate matlab function==
The last step to creating a new object in the framework is to create a <tt>bindings/matlab/classes/@IXTclassname</tt> directory. this identifies <tt>IXTclassname</tt> as a class to matlab. Within this directory you create <tt>.m</tt> files corresponding to the functions that operation on the class. these can have any name you wish, but there are two that you must create.
<tt>
* IXTclassname.m
* display.m
</tt>

The first of these is called the constructor and is named after the class i.e. the file <tt>@IXTtestclass/IXTtestclass.m</tt> - the constructor tells matlab the data members that are contained within the class and how they should/can be initialised. The second file tells matlab how to display (print) the class to the screen.

every any non-standard object method which is defined in <tt>libisisexc.txt</tt> will also need to have a <tt>.m</tt> file to make a call into the DLL. this file does not necessarily have to have the same name as the method.

<tt>display.m</tt> has a standard construction.
<pre>
function display(object)
libisisexc('IXTclassname','display',object);
</pre>

The constructor defines the data within a class and the order that these members are in if the class in indexed. It is thus important that the order defined in this class is followed '''EXACTLY''' in fortran when calling <tt>IXFoperationRun_classname</tt>. In our case the constructor should populate a default empty object and then pass this empty object and any arguments out to LIBISIS with a call to <tt>libisisexc()</tt>, which will check the arguments and then complete creation of the object. The first two string arguments to <tt>libisisexc()</tt> are the <tt>classname</tt> and <tt>method</tt>, inside the DLL they are mangled together and the DLL then calls the appropriate <tt>IXBmethod_classname</tt>, provided it has been defined in <tt>libisisexc.txt</tt>.

<pre>
function object = IXTtestclass(varargin)
object.base = IXTbase;
object.val = 0;
object.nx = int32(1);
object.val_static = ones(3);
object.int_static = ones(4);
object.val_array = zeros(2);
object.int_arr = int32(zeros(2,2));
object.spectra = IXTspectra;
object.xhist = true;
object.label='test';
object.cell_string = [ 'one' ];
object.d2d = [ IXTdataset_2d ];
object = class(object ,'IXTtestclass');

if (nargin > 0)
object = libisisexc('IXTtestclass','create',object ,varargin);
end
</pre>

We will often need to pass out an empty/default object as the first argument, this is because FORTRAN can modify, but not create, Matlab class objects (it sees them as structures), for example in <tt>bindings/matlab/classes/@IXTtestclass/plus.m</tt>
<pre>
function object = plus(a,b,array)
object = libisisexc('IXTtestclass','plus',IXTtestclass,a,b,array);
</pre>

the arguments to <tt>libisisexc()</tt> are directly related to the variables used in <tt>IXBplus_testclass</tt>
<tt>
* prhs(1) => IXTtestclass ,</tt>(empty objectused to populate return result)<tt>
* prhs(2) => a </tt> (a is a populated IXTtestclass object input argument)<tt>
* prhs(3) => b </tt> (a is a populated IXTtestclass object input argument)<tt>
* prhs(4) => array
</tt>