iFit: running the stand-alone application


  1. Starting
    1. Command options/arguments
  2. Limitations
  3. Short introduction to Matlab syntax
    1. Variables and data type
    2. Control statements
    3. Scripts and lists of statements
    4. Functions
    5. Importing data files

Commands we use in this page: ifit

the iFit standaloneIn this document, we demonstrate shortly how to use the iFit executable (stand-alone distribution), which mainly manipulates iData and iFunc objects. It provides a free fully functional iFit package for users without Matlab license. Refer to the Install page for the installation procedure.

The official iFit web site is <ifit.mccode.org>. You can get iFit there, as well as extensive documentation.

If you do not know about Matlab, refer to the quick tutorial below.

The object of these tools is to:
Each of these tasks has dedicated, detailed, documentation, as shown in links above.

If you are a regular iFit standalone user and get used to Matlab commands, you may consider to buy a license. Cost for students and academic institutes is reduced.

Starting

iFit standalone
            window (no Matlab license required)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.

miFitWhen 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.

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 >> 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:iFit_TextEdit
>> 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_PhononsSqw_Phonons Phonon dispersion computations using DFT and dynamical matrix. Read the dedicated Phonons documentation.
miFit miFit
a simple yet powerful User Interface. This one is automatically started with iFit.
TextEditiFit_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:

ifit Data/Ag_3_a.edf Data/ILL_IN6.dat --save --exit
imports two data files, exports them in a single MAT file (HDF based), and exit. The list of all available file formats for import is available in the Load page.
This is the same as save(iData({'Data/Ag_3_a.edf','Data/ILL_IN6.dat'}),'ifit.mat')
ifit Data/Ag_3_a.edf Data/ILL_IN6.dat subplot
imports two data files, display them with subplot (from iData/Plot) and waits for further commands (switch to interactive mode). The two files are stored in the 'this' cell array.
This is the same as subplot(iData({'Data/Ag_3_a.edf','Data/ILL_IN6.dat'}))
ifit Data/Ag_3_a.edf Data/ILL_IN6.dat "'save(this{:},'mydata','HDF')'"
imports two data files, then evaluates the iData/save command to save in HDF5 format. The list of all available file formats for export is available in the iData/Save page.
ifit Data/ILL_IN20.dat fits
imports a data file, and fit it to a Gaussian model (default). The list of all available fit models is available in the Models page.
This is the same as fits(gauss, iData('Data/ILL_IN20.dat'}))
ifit Data/ILL_IN20.dat '"lorz"'fits
imports a data file, and fit it to a Lorentzian model.
This is the same as fits(lorz, iData('Data/ILL_IN20.dat'}))
ifit Data/ILL_IN*.dat --run=SCRIPT --exit
imports a set of data files, and then run the Matlab SCRIPT, which can use the 'this' cell array in the further processing, and finally exits.

In addition, once in interactive mode, you can use the commands:

verbose and silent toggle the echo of commands in the terminal.
doc and help open the documentation
run <script.m> executes a script, supporting multi-line
propedit open the object browser GUI
TextEdit open the script editor GUI, supporting multi-line
mifit open the workspace GUI
d=iData('filename') import a file
m=iFunc('expr'); create a model from an expression
fits(iFunc) list of predefined models
fits(m,d) fit a model to data set
 

Limitations

The iFit stand-alone distribution provides a fully functional Matlab prompt (terminal) which includes:
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.


E. Farhi - iFit/executable - Aug. 22, 2017 1.10 - back to Main iFit Page ILL,
          Grenoble, France <www.ill.eu>