iFit: running the stand-alone application

Start the iFit command line by launching the 'ifit' program in the stand-alone installation directory, or by clicking on the iFit icon (when available).

% ifit
% ifit datafile

You can also drag-n-drop data files on the program in order to directly import them into iData objects (linux and Windows versions). These are then stored in the 'this' variable (cell array), and the last one is stored as well in the 'ans' variable. When only one data file/directory is imported, it is automatically plotted.

When starting, the miFit graphical user interface will be displayed, allowing a mouse-driven data treatment and fitting. The -nodesktop option when starting suppresses this behavior to only provide the command prompt. Type 'mifit' to start the GUI.

The miFit interface provides, in its miFit:File/Evaluate code menu item, access to the TextEdit application, which allows to write scripts and commands, and execute them (TextEdit:File/Evaluate). The advantage is that you can keep track of all your commands as a script, with highlight syntaxing, and it is not sensitive to the localised character crash [bug 624817].

Working with iFit

The iFit prompt behaves just like a normal Matlab session, in a Terminal. You can type any Matlab command, as well as iFit features. To interrupt a running computation, press Ctrl-C once. A second key press will exit iFit. To copy-paste text, rather use the Terminal menus to avoid accidental Ctrl-C. You can use full Matlab syntax, but all your input is executed line by line, so that any control statements (if, for, while, ...) must remain on a single line.

iFit >> run script.m
iFit >> for index=1:10; disp(index); end    % this works

but the following will fail:

iFit >> for index=1:10
iFit >>   disp(index);
iFit >> end

A way to be able to access the full Matlab control statement syntax (multi-line) and keep track of your work, is to start the TextEdit window:

>> TextEdit

You can type Matlab/iFit commands in there, and then use the File/Evaluate menu item to evaluate either all the content, or a selection. The result is sent into the iFit Terminal. Any variable used in the TextEdit window appears in the iFit Terminal, and vice-versa. You can open as many TextEdit windows as you wish, load/save files (e.g. .m), copy/paste filenames and raw text.

The TextEdit and miFit windows both have a Help menu which links to the main iFit functionalities.

Applications with User Interface

iFit is a very general infrastructure, which is mostly used through commands and scripts. However, there exist a few dedicated Applications which provide a User Interface.

ResLibCal	Triple-Axis neutron spectrometer simulator
Sqw_Phonons	Phonon dispersion computations using DFT and dynamical matrix. Read the dedicated Phonons documentation.
miFit	a simple yet powerful User Interface. This one is automatically started with iFit.
TextEdit	an editor which allows to evaluate code

When using the Debian installer, these Applications can be launched directly from the 'Dash' by searching their name.

Command options/arguments

You can start the iFit program with additional arguments which allow to perform predefined operations when starting.

--save	saves automatically all files to 'ifit.mat' (HDF format) before exiting the program (except with Ctrl-C). You can then re-import the workspace with 'load ifit.mat' in any further Matlab or iFit session.
--save=FILE	same as above, but specify the name of the file to save to.
--run=SCRIPT -r=SCRIPT	reads the whole SCRIPT and executes it. The script can contain any list of Matlab commands, but can not include new function definitions, except anonymous functions. New fit models can be defined with iFunc objetcs.
--help -h	Displays the help for the iFit stand-alone program (command arguments)
--exit	Exits iFit when all commands have been executed. The Ctrl-C key exits immediately (aborts)
-nodesktop	Do not start the miFit GUI (prompt only)
data	the data can be any valid URL (http://, ftp://) or filename, or directory. The data is imported into iData objects, which are stored in the 'this' cell array (list). You can then plot them with e.g. 'plot(this{:})'.
any single Matlab command	Any Matlab command is executed with the expanded 'this' list as argument.
'"any string"'	An argument containing a double quote string is interpreted as a static string, stored in 'this', and can be passed to further commands. Be cautious regarding the use of special characters such as ()[]{} and even the space which may require escape backslash ( \ ).
"'any expression'"	An argument containing a single quote string is evaluated as a Matlab statement/expression.

Examples for commands to start iFit:

Limitations

The iFit stand-alone distribution provides a fully functional Matlab prompt (terminal) which includes:

• Scripting and command execution
• All Matlab variables, functions and commands
• All iData/iFunc object methods and interfaces
• Plotting capabilities with e.g. openGL rendering and plot editor
  
• Third-party tools such as slice-o-matic
• The ResLibCal application
• Hooks to the McStas and McXtrace ray-tracing software
  

However, new Matlab functions can not be defined, except anonymous functions (inline). You may use iFunc models as a substitute. Also, the doc, web, help and edit commands are limited, and may not work properly, depending on the system.

To edit graphical objects (plot elements such as titles, axes labels, ...), you can use:

>> edit(gcf);	% edit the current figure. Select the 'arrow' tool in the tool bar then double-click objects.
>> inspect(gcf) % open a property editor

The edit command also works with files, to launch the system text editor or a simplistic editor.

The Ctrl-C key in the iFit terminal exits immediately iFit. It is safer to use the 'exit' command which will give a chance to opened interfaces to properly quit.

Any localised character entered at the prompt, out the the usual US keyboard ones (e.g. e.g. é, ö, ø, õ, etc), may result in a crash [bug 624817].

---

Short introduction to Matlab syntax

Matlab can be regarded as a powerful numeric calculator. It works in interactive mode (with a prompt waiting for new instructions). Type exit to exit Matlab, and doc to get the Matlab help (not in stand-alone version). The full Matlab help can be accessed freely at <http://www.mathworks.com/help/techdoc/>.

Variables and data type

Matlab supports real ('double'), complex, integer, character strings, structures and lists ('cell'). With iFit, we provide 2 new data types: iData to store data sets, and iFunc to store models for e.g. fitting. These data types can be stored in named variables with the equal sign, or in the 'ans' (latest answer) variable: The ';' sign at the end of a statement suppresses the display of the result. The '%' character indicates a comment. The square brackets [] are used to define vectors and matrices. The curly brackets {} are used to access cell array (lists) elements. To access elements from a string or an array, use the the parenthesis (index) with an index starting from 1 for the 1st element. To access a cell array element, use {index}. The ':' character indicates a range.

>> 1+2
ans =
     3
>> a=1+2;
>> a = [ 1 2 3 4 ];			% a vector of numbers
>> b='a string';
>> c.first=1;				% a structure with two fields
>> c.second='string in a structure';
>> d={a,b,c};				% a cell array (list) containing the 3 variables a,b,c values
>> d{2}
ans =
    a string

Control statements

Matlab supports a set of control statements:

if condition statements end	if condition statements1 else statements2 end	if condition1 statements1 elseif condition2 statements2 end
for variable=vector statements end	while condition statements end	switch variable case value1 statements1 case value2 statements2 otherwise statements_default end

All Matlab statements can be written on multiple lines in scripts and functions, or on a single line from the iFit prompt when separating each statement with the ';' character. We use below disp to display a value.

>> for index=1:10; disp(index); end

Scripts and lists of statements

Matlab scripts are text files containing a list of statements and control keywords as listed above. To execute them, use

>> run SCRIPT.m

where the script can contain a full path name, and should have a .m extension.
The iFit program supports single line statements from the prompt, and multiple lines lists from scripts.

Functions

A function is a script that takes input arguments, and returns output arguments. It is stored in a '.m' extension file with the name of the function (my_function.m)

function [out1, out2, ...] = my_function(in1, in2, ...)
  % comments
  statements

To call a function, simply use its name:

>> my_function(1,2,3)
>> a = my_function(1,2,3);

Anonymous functions are simple functions which consist in a single statement, and return at most one value. They are defined as a variable, and called with the syntax:

>> my_function = @(in1, in2, ...) statement;
>> my_function(1,2,3);

Matlab (and iFit) contain a very large set of functions.
iFit stand-alone does not allow to define new user functions. You are bound to use existing ones, or anonymous functions.

Within iFit, the iFunc objects provide a work-around solution for numerical functions to be used for models. Such objects use 'p' as parameters (which can be given names), and axes 'x,y,z,t,u,v,w'.

>> f = iFunc('p(1)*x + p(2)')
>> plot(f)

iFunc objects can be manipulated just as numbers, and you can create more complex models by assembling simpler ones. iFunc objects support additional parameters, which in principle allow for storing any function there-in.

Importing data files

The simplest way to import data in Matlab and iFit is to use the iData objects.

>> d = iData('filename');
>> plot(d)
>> fits(d, gauss)

A large set of functions and operators allow to manipulate these objects just as numbers. Refer to the Methods, Load, Save, Plot, Fit and Math pages. The same remark holds for iFunc fit models.

As seen above, data files can be directly imported when starting iFit, if the corresponding file names are given as arguments to the ifit program.

To save your work, issue the save command:

>> save
>> save(iData_objects, 'filename', 'format')

Refer to the iData/Save page for more information on the available formats and procedures.