Commit 25c26d12 authored by Anders Markvardsen's avatar Anders Markvardsen
Browse files

Revert "Revert "initial translation using pandoc links need fixing. re #9923""

This reverts commit 2e49944e.
parent 2e49944e
.. _Algorithm:
Algorithm
=========
What are they?
--------------
Algorithms are the verbs of Mantid. They are the actors. If you want to
manipulate your data in any way it will be done through an algorithm.
Algorithms operate primarily on data in `workspaces <Workspace>`__. They
will normally take one or more `workspaces <Workspace>`__ as an input,
perform some processing on them and provide an output as another
`workspace <Workspace>`__ (although it is possible to have multiple
outputs).
Categories, Name and Versions
-----------------------------
Each algorithm has a category, a name and a version. The name and
version of an algorithm when taken together have to be unique.
Category
~~~~~~~~
A category is a group of algorithms that have some connection in their
usage. This is primarily used to make the list of algorithms easier to
work with in graphical user interfaces. Example categories include,
DataHandling, Diffraction, Muon, Workflow and are currently
subcategories of
`Algorithms <http://docs.mantidproject.org/algorithms>`__ category.
Name
~~~~
The name of an algorithm is what is used to refer to it. This can be
different from the class name in C++, as for example if you had two
versions of the same algorithm they would have the same name, but would
have to have different class names (or at least be in different
namespaces).
Version
~~~~~~~
Mantid allows multiple versions of the same algorithm. These are
differentiated by using a single integer as a version number, where a
higher version number denotes a more recent version. This allows you to
normally use the most recent version of an algorithm but also to access
previous versions if you prefer.
Parameters
----------
Each algorithm will have one or more parameters, known within Mantid as
`properties <properties>`__, that will control how it performs its
processing. These parameters specify both what the inputs and outputs of
the algorithm will be as well any other options that alter the
processing.
For examples of the parameters of an algorithm, look at the page for one
of the example algorithms below.
Usage
-----
From MantidScript(Python)
^^^^^^^^^^^^^^^^^^^^^^^^^
.. raw:: html
<div style="border:1pt dashed blue; background:#f9f9f9;padding: 1em 0;">
.. code:: python
# where p1,p2 & p3 are values for algorithm "Alg"'s properties
mtd.execute("Alg","p1;p2;p3") # using parameter ordinal position
#or
mtd.execute("Alg","Property1=p1;Property2=p2;Property3=p3") #using parameter names
#or
alg = mtd.createAlgorithm("Alg") # explicitly setting each parameter, then executing
alg.setPropertyValue("Property1","p1")
alg.setPropertyValue("Property2","p2")
alg.setPropertyValue("Property3","p3")
alg.execute()
# Properties of Algorithms can be read (but not written to) through a Python dictionary. So you may do:
print alg["Property1"]
# prints 'p1'
print alg["Property2"]
# prints 'p2', etc
.. raw:: html
</div>
Using the C++ API
^^^^^^^^^^^^^^^^^
(for algorithm "Alg" having properties InputWorkspace, OutputWorkspace &
prop)
.. raw:: html
<div style="border:1pt dashed blue; background:#f9f9f9;padding: 1em 0;">
.. code:: cpp
// Explicitly setting the parameters and then executing
API::IAlgorithm* alg = API::FrameworkManager::Instance().createAlgorithm("Alg");
alg->setPropertyValue("InputWorkspace", "InWS");
alg->setPropertyValue("OutputWorkspace", "OutWS");
alg->setPropertyValue("prop", "aValue");
alg->execute();
API::Workspace* ws = API::FrameworkManager::Instance().getWorkspace("OutWS");
// Or in one shot
API::FrameworkManager::Instance().exec("Alg","InWS,OutWS,aValue");
API::Workspace* ws = API::FrameworkManager::Instance().getWorkspace("OutWS");
.. raw:: html
</div>
Example Algorithms
------------------
- `Plus <http://docs.mantidproject.org/nightly/algorithms/Plus.html>`__
- An algorithm for adding data in two `workspaces <Workspace>`__
together
- `Rebin <http://docs.mantidproject.org/nightly/algorithms/Rebin.html>`__
- An algorithm for altering the binning of the data in a
`workspace <Workspace>`__.
- `LoadRaw <http://docs.mantidproject.org/nightly/algorithms/LoadRaw.html>`__
- An algorithm for loading the data from a RAW file into a
`workspace <Workspace>`__.
- `GroupDetectors <http://docs.mantidproject.org/nightly/algorithms/GroupDetectors.html>`__
- An algorithm for grouping two or more detectors into a larger
'logical' detector.
A full list of algorithms is avilable
`here <http://docs.mantidproject.org/nightly/algorithms/index.html>`__
category
Writing your own algorithm
--------------------------
A primer for this is `here <Writing an Algorithm>`__. Also look at the
examples in the `UserAlgorithms <UserAlgorithms>`__ directory of your
Mantid installation.
.. categories:: Concepts
\ No newline at end of file
.. _Analysis Data Service:
Analysis_Data_Service
=====================
What is it?
-----------
The Analysis Data Service is a `Data Service <Data Service>`__ that is
specialized to hold all of the `workspaces <Workspace>`__ that are
created by user run `algorithms <Algorithm>`__. Whenever an algorithm is
executed it automatically extracts its input workspaces from the
Analysis Data Service, and inserts its output workspaces upon
completion.
Extracting a workspace from the Analysis Data Service
-----------------------------------------------------
The most usual way in user code would be to use the `Framework
Manager <Framework Manager>`__.
``Workspace* result = FrameworkManager::Instance().getWorkspace("workspaceName")``
Or you could get it directly from the AnalysisDataService (as a `Shared
Pointer <Shared Pointer>`__)
``Workspace_sptr result = AnalysisDataService::Instance().retrieve("test_out1");``
If you were writing an algorithm however you would most likely use a
Workspace `Property <Properties>`__ to access or store your workspaces.
.. categories:: Concepts
\ No newline at end of file
.. _Data Service:
Data_Service
============
What are they?
--------------
Data Services are the internal storage locations within Mantid. Each
data service holds a list of objects that share a common base class (for
example the Instrument Data Service can hold anything which inherits
from instrument). Each item that is held is associated with a name that
uniquely describes the object. This name is them used when the object
needs to be retrieved, or for other operations such as overwriting it or
deleting it.
Data Services in Mantid
-----------------------
- `Analysis Data Service <Analysis Data Service>`__ - A data service
holding all of the `workspaces <Workspace>`__ used in this session.
- `Instrument Data Service <Instrument Data Service>`__ - A data
service holding all of the `instruments <Instrument>`__ used in this
session.
.. categories:: Concepts
\ No newline at end of file
.. _Dynamic Factory:
Dynamic_Factory
===============
What is it?
-----------
A dynamic factory is a software concept that in instrumental in
implementing the `Plugin <Plugin>`__ technology in Mantid.
A factory in software terms is an class that is responsible for creating
other objects on demand. In mantid terms the AlgorithmFactory is
responsible for creating instances of `Algorithms <Algorithm>`__ when
you need them.
As the factory is dynamic it does not have a set list of objects that it
can create instead it knows how to create instances of a particular base
class. During execution of the code any object of the appropriate base
class can be registered with the factory, and then the factory can be
used to create fresh instances of that object.
.. categories:: Concepts
\ No newline at end of file
.. _Error Propagation:
Error_Propagation
=================
The purpose of this document is to explain how Mantid deals with Error
Propogation and how it is used in its algorithms.
Theory
------
In order to deal with error propagation, Mantid treats errors as a
guassian curve (also known as a bell curve or normal curve). Meaning
that if X = 100 +- 1 then it is still possible for a value of 102 to
occur, but far less likely than 101 or 99, then a value of 105 is far
less likely still than 102, and then 110 is simply unheard of.
This allows Mantid to work with the errors quite simply.
Plus and Minus Algorithm
------------------------
The plus algorithm adds a selection of datasets together, including
their margin of errors. Mantid has to therefore adapt the margin of
error so it continues to work with just one margin of error. The way it
does this is by simply adding together the certain values, for this
example we will use X\ :sub:`1` and X\ :sub:`2`. X\ :sub:`1` = 101 ± 2
and X\ :sub:`2` = 99 ± 2, Just to make it easier. Mantid takes the
average of the two definite values, 101 and 99.
X = 200 = (101 + 99).
The average of the error is calculated by taking the root of the sum of
the squares of the two error margins:
(√2:sup:`2` + 2\ :sup:`2`) = √8
X = 200 ± √8
Mantid deals with the minus algorithm similarly, doing the inverse
function of Plus.
Multiply and Divide Algorithm
-----------------------------
The Multiply and Divide Algorithm work slightly different from the Plus
and Minus Algorithms, in the sense that they have to be more complex.
To calculate error propagation, of say X\ :sub:`1` and X\ :sub:`2`.
X\ :sub:`1` = 101 ± 2 and X\ :sub:`2` = 99 ± 2 again, Mantid would
undertake the following calculation for divide:
Q = X\ :sub:`1`/X:sub:`2` = 101/99
Error Propogation = (√ ± 2/99 + ±2/101) All multiplied by Q = 0.22425
For the multiply algorithm, the only difference is in how Q is created,
which in turn affects the Error Propogation,
Q = X\ :sub:`1`\ \*X\ :sub:`2` = 101\*99
Error Propogation = (√ ± 2/99 + ±2/101) All multiplied by Q = 0.22425
.. categories:: Concepts
\ No newline at end of file
.. _EventWorkspace:
EventWorkspace
==============
Quick Summary For Users
-----------------------
The EventWorkspace is a type of `MatrixWorkspace <MatrixWorkspace>`__,
where the information about each individual neutron detection event is
maintained. For you as a user, this means that:
- You can `rebin <rebin>`__ an EventWorkspace over and over and no
information is ever lost.
- The histogram (Y and E values) of an EventWorkspace are only
calculated when they are requested.
- You typically get better performance, even for very fine binning.
- You can convert an EventWorkspace to a `Workspace2D <Workspace2D>`__
by using the `Rebin <Rebin>`__ algorithm and changing the output
workspace name.
- You cannot modify the histogram Y values (for example, with the
Divide algorithm) and keep the event data. If you use an algorithm
that modifies the Y values, the output workspace will be a
`Workspace2D <Workspace2D>`__ using the current binning parameters.
If you set the same name on the output as the input of your
algorithm, then you will overwrite the EventWorkspace and lose that
event-based information.
- Some algorithms are EventWorkspace-aware, meaning that the output of
it can be another EventWorkspace. For example, the `Plus <Plus>`__
algorithm will append the event lists if given two input
EventWorkspaces.
- Since it retains the most information, it is advantageous to keep
your data as an EventWorkspace for as much processing as is possible
(as long as you have enough memory!).
For Developers/Writing Algorithms
---------------------------------
The following information will be useful to you if you want to write an
algorithm that is EventWorkspace-aware.
Individual Neutron Event Data (TofEvent)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The TofEvent class holds information for each neutron detection event
data:
- PulseTime: An absolute time of the pulse that generated this neutron.
This is saved as an INT64 of the number of nanoseconds since Jan 1,
1990; this can be converted to other date and time formats as needed.
- tof: Time-of-flight of the neutron, in microseconds, as a double.
Note that this field can be converted to other units, e.g. d-spacing.
Lists of Events (EventList)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The EventList class consists of a list of TofEvent's. The order of
this list is not significant, since various algorithms will resort by
time of flight or pulse time, as needed.
- Also contained in the EventList is a std::set of detector ID's. This
tracks which `detector <detector>`__\ (s) were hit by the events in
the list.
- The histogram bins (X axis) are also stored in EventList. The Y and E
histogram data are not, however, as they are calculated by the MRU
(below).
The += operator can be used to append two EventList's together. The
lists of TofEvent's get appended, as is the list of
`detector <detector>`__ ID's. Don't mess with the udetmap manually if
you start appending event lists - just call
EventWorkpspace->makeSpectraMap to generate the spectra map (map between
spectrum # and detector IDs) by using the info in each EventList.
Most Recently Used List (MRUList)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An EventWorkspace contains a list of the 100 most-recently used
histograms, a `MRUList <MRUList>`__. This MRU caches the last histogram
data generated for fastest display.
A note about workspace index / spectrum number / detector ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The loading algorithms **match** the workspace index and spectrum number
in the EventWorkspace. Therefore, in an EventWorkspace, the two numbers
will be the same, and your workspace's Axis[1] is a simple 1:1 map. As
mentioned above, the detectorID is saved in EventList, but the
makeSpectraMap() method generates the usual SpectraDetectorMap object.
Workspace2D compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~
EventWorkspace is designed to be able to be read (but not written to)
like a `Workspace2D <Workspace2D>`__. By default, if an algorithm
performs an operation and outputs a new workspace, the
`WorkspaceFactory <WorkspaceFactory>`__ will create a Workspace2D *copy*
of your EventWorkspace's histogram representation. If you attempt to
change an EventWorkspace's Y or E data in place, you will get an error
message, since that is not possible.
A Note about Thread Safety
~~~~~~~~~~~~~~~~~~~~~~~~~~
Thread safety can be surprising when using an EventWorkspace:
If two threads *read* a Y histogram at the same time, this *can* cause
problems. This is because the histogramming code will try to sort the
event list. If two threads try to sort the same event list, you can get
segfaults.
Remember that the PARALLEL\_FOR1(), PARALLEL\_FOR2() etc. macros will
perform the check Workspace->threadSafe() on the input EventWorkspace.
This function will return *false* (thereby disabling parallelization) if
any of the event lists are unsorted.
You can go around this by forcing the parallel loop with a plain
PARALLEL\_FOR() macro. **Make sure you do not read from the same
spectrum in parallel!**
.. categories:: Concepts
\ No newline at end of file
.. _Facilities File:
Facilities_File
===============
Summary
-------
The facilities file, called **facilities.xml**, contains properties of
facilities and instruments that Mantid is aware of. In order for Mantid
to function correctly for your facility then the facilites file should
contain the appropriate definitions as defined below.
File syntax
-----------
Each facility is described using XML with an instrument defined as a sub
component of a facility. A simple facility definition would be
.. raw:: html
<div style="border:1pt dashed blue; background:#f9f9f9;padding: 1em 0;">
.. code:: XML
<?xml version="1.0" encoding="UTF-8"?>
<facilities>
<facility name="BrandNew" delimiter="_" zeropadding="8" FileExtensions=".nxs,.n*">
<instrument name="ABCDEF"/>
</facility>
</facilities>
.. raw:: html
</div>
which would define a facility called *BrandNew* with an instrument
called *ABCDEF*. The facilities attributes have the following meanings:
- ``delimiter`` gives the delimiter that is inserted between the
instrument name and the run number when constructing a file name;
- ``zeroPadding`` gives the number of digits that a run number is
padded to when constructing a file name;
- ``FileExtensions`` should list the extensions of the data files for
the facility. The first is taken as the preferred extension.
An instrument can have further attributes which define properties of the
that instrument rather than the facility as a whole, e.g.
.. raw:: html
<div style="border:1pt dashed blue; background:#f9f9f9;padding: 1em 0;">
.. code:: XML
<?xml version="1.0" encoding="UTF-8"?>
<facilities>
<facility name="BrandNew" zeropadding="8" FileExtensions=".nxs,.n*">
<instrument name="ABCDEF" shortName="ABC">
<technique>Tech 1</technique>
<technique>Tech 2</technique>
<zeropadding size="12" startRunNumber="12345" prefix="FEDCBA"></zeropadding>
<zeropadding size="15" startRunNumber="54321" prefix="ZYXWUV"></zeropadding>
</instrument>
</facility>
</facilities>
.. raw:: html
</div>
where the attributes are defined as:
- ``shortName`` gives a shortened version of the instrument name
sometimes used in run filename generation;
- ``<technique>NAME<\technique>`` tags give a named technique supported
by the instrument. Mantid uses this to retrieve lists of instruments
based on a particular technique. Multiple techniques can be
specified.
- ``<zeropadding size="12" startRunNumber="12345" prefix="FEDCBA"\>``
is an optional tag to specify zero padding different from the default
for the facility. ``startRunNumber`` is an optional attribute
specifying the smallest run number at which this zero padding must be
used. If ``startRunNumber`` is omitted this zero padding is applied
from run number 0. The optional ``prefix`` attribute allows a
filename to have a different prefix. An ``instrument`` tag can have
multiple ``zeropadding`` tags.
Location
--------
The file should be located in the directory pointed to by the
**instrumentDefinition.directory** key in the
`.properties <Properties_File>`__ file.
.. categories:: Concepts
\ No newline at end of file
.. _FitConstraint:
FitConstraint
=============
.. role:: math(raw)
:format: html latex
..
How constraints on parameters work
----------------------------------
Consider the scenario where the aim is to fit a lorenzian function to a
1D dataset but a constraint applied on the peak centre parameter. Assume
the 1D dataset consists of :math:`N` data points
:math:`(x_1,y_1^{obs}), (x_2,y_2^{obs}), ... (x_N,y_N^{obs})`, where
:math:`x_i` is the ith x-value and :math:`y_i^{obs}` is the ith observed
value for that x-value. Write the lorentzian function as:
.. math:: y_i^{cal}(h, x0, w) = h \left( \frac{w^2}{(x_i-x0)^2+w^2} \right)
where he lorentzian fitting parameters here are
- :math:`h` - height of peak (at maximum)
- :math:`x0` - centre of peak
- :math:`w` - half-width at half-maximum
:math:`x_i` is the x-value of the ith data point and :math:`y_i^{cal}`
is the lorentzian calculated value at that data point.
We want to apply a constraint on the x0 parameter, i.e. the centre of
the peak. For example, apply the constraint that :math:`x0` should be in
between :math:`x0_{min}` and :math:`x0_{max}`. If this is not satisfied
we then add the following penalty function to :math:`y_i^{cal}` if
:math:`x0 < x0_{min}</`:
.. math:: p_i = C(x0_{min}-x0)*R(x_i)
where :math:`C` is a constant (default 1000) and :math:`R(x_i)` a spiky
function which takes the value 1 for the first and last data point and
for every 10th data point from the 1st data point, but is otherwise
zero. The penalty function when :math:`x0 > x0_{min}</` takes the form:
.. math:: p_i = C(x0-x0_{max})*R(x_i)
.
If more than one constraint is defined, then for each violated
constraint a penalty of the type defined above is added to the
calculated fitting function.
.. categories:: Concepts
\ No newline at end of file
.. _Framework Manager:
Framework_Manager
=================
What is it?
-----------
The framework manager is the main class through which user code will
interact with the Mantid framework. It is the center piece of the
application programming interface.
The main purpose of the frameworkManager is to simplfy the interaction
with the various internal services of the Mantid framework. Of course
this does not prevent you from accessing those services directly should
you so wish.
What does it allow you to do?
-----------------------------
The frameworkManager allows you to create and execute algorithms as well
as retrieving workspaces, and deleteing them if they are no longer
required.
It is good practice to delete workspaces that are no longer required to
free up the memory used.
For the most up to date listing of the methods that Framework Manager
provides look at the `Doxygen code
documentation <http://doxygen.mantidproject.org/>`__. Select the classes
tab and look for FrameworkManagerImpl (Mantid::API).