diff --git a/Code/Mantid/docs/source/concepts/Algorithm.rst b/Code/Mantid/docs/source/concepts/Algorithm.rst
new file mode 100644
index 0000000000000000000000000000000000000000..15613d8674ddd988063dd09372b179b23a6c0988
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Algorithm.rst
@@ -0,0 +1,153 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/Analysis_Data_Service.rst b/Code/Mantid/docs/source/concepts/Analysis_Data_Service.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f219bd05b5f373ab8af3b524f31df994703a47cf
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Analysis_Data_Service.rst
@@ -0,0 +1,34 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/Data_Service.rst b/Code/Mantid/docs/source/concepts/Data_Service.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4462ece86a82a62201a5ccc00266e0466ae133a8
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Data_Service.rst
@@ -0,0 +1,28 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/Dynamic_Factory.rst b/Code/Mantid/docs/source/concepts/Dynamic_Factory.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e52bdeb1c37fad5a39592917a8ccdfa42702912f
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Dynamic_Factory.rst
@@ -0,0 +1,25 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/Error_Propagation.rst b/Code/Mantid/docs/source/concepts/Error_Propagation.rst
new file mode 100644
index 0000000000000000000000000000000000000000..636e35c7212e752cd49253cd12034582461d0469
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Error_Propagation.rst
@@ -0,0 +1,66 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/EventWorkspace.rst b/Code/Mantid/docs/source/concepts/EventWorkspace.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a364ae053ae023c842f23bceab925a675cc73b61
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/EventWorkspace.rst
@@ -0,0 +1,126 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/Facilities_File.rst b/Code/Mantid/docs/source/concepts/Facilities_File.rst
new file mode 100644
index 0000000000000000000000000000000000000000..19f134edf297792b895e41cd1688ce3be30a4ef6
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Facilities_File.rst
@@ -0,0 +1,106 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/FitConstraint.rst b/Code/Mantid/docs/source/concepts/FitConstraint.rst
new file mode 100644
index 0000000000000000000000000000000000000000..880d1eb6c887d5d3e3e9f9b0fff387ee62d930ab
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/FitConstraint.rst
@@ -0,0 +1,54 @@
+.. _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
diff --git a/Code/Mantid/docs/source/concepts/Framework_Manager.rst b/Code/Mantid/docs/source/concepts/Framework_Manager.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1003315f89d095eea0232e293bd6672e0981be5c
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Framework_Manager.rst
@@ -0,0 +1,35 @@
+.. _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).
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Geometry.rst b/Code/Mantid/docs/source/concepts/Geometry.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0c5ad980f42e346010e421bf6cb4a18d409f374e
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Geometry.rst
@@ -0,0 +1,39 @@
+.. _Geometry:
+
+Geometry
+========
+
+What is it?
+-----------
+
+Geometry is the description of the physical shape (volume) of an object
+within a Mantid `instrument <Instrument>`__ and the distances and
+rotations between them.
+
+Geometry in Mantid
+------------------
+
+In Mantid we seperate the `Geometry of the shape <Geometry of Shape>`__
+of an object from the `Geometry of it's
+position <Geometry of Position>`__. This is done primarily to save on
+memory usage but also to improve performance. Many operations within
+Mantid need to know where for example a detector is, but do not need to
+know what shape it is. By keeping the Geometry and Position seperate we
+can keep the performance high. Also while in any one instrument we may
+have over 10,000 detector pixels all with different locations they will
+all have the same shape, therefore by keeping the shape seperate we can
+greatly reduce the amount of memory required.
+
+Basics of Geometry
+------------------
+
+Both of the forms of Geometry share certain basic concepts. These are
+that co-ordinates are stored as `3D
+Vectors <http://en.wikipedia.org/wiki/Vector_(spatial)>`__ (the class in
+Mantid is called V3D), directions are described as similar unit 3D
+Vectors, and rotations are described using
+`quaternions <http://en.wikipedia.org/wiki/Quaternion>`__.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Geometry_of_Position.rst b/Code/Mantid/docs/source/concepts/Geometry_of_Position.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4007e956d07197d6a825b215bd93b2c675cecabf
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Geometry_of_Position.rst
@@ -0,0 +1,68 @@
+.. _Geometry of Position:
+
+Geometry_of_Position
+====================
+
+What is it?
+-----------
+
+In Mantid we need to be able to define the position and orientation of
+every component within an `instrument <instrument>`__.
+
+What is a component?
+--------------------
+
+A component is an abstract concept that is anything that we want to
+define a position for, it could be a detector pixel, a whole detector
+bank, a sample position or the whole instrument itself. For each
+component we store:
+
+- A link to it's parent component.
+- Position co-ordinates as a `3D
+ Vector <http://en.wikipedia.org/wiki/Vector_(spatial)>`__, internally
+ these store the location in `cartesian
+ co-ordinates <http://en.wikipedia.org/wiki/Cartesian_coordinate_system>`__
+ in metres, but can also be set in `spherical
+ co-ordinates <http://en.wikipedia.org/wiki/Spherical_coordinate_system>`__.
+ This position is the relative position compared to it's parent.
+- Orientation as a
+ `quaternion <http://en.wikipedia.org/wiki/Quaternion>`__. The
+ orientation is applied after any position adjustment relative to the
+ parent.
+
+Subtypes of Component
+~~~~~~~~~~~~~~~~~~~~~
+
+Object Component
+^^^^^^^^^^^^^^^^
+
+An object component is a component that has a
+`shape <Geometry_of_Shape>`__. Shapes can contain a lot more information
+to properly define them, and therefore take more memory. Where an
+instrument contains a lot of instances of the same shape Mantid shares
+one instance of the object(shape) across all of the object components
+that need it.
+
+Component Assembly
+^^^^^^^^^^^^^^^^^^
+
+This component that is a logical collection of several smaller
+components, an example of this is a bank of detector pixels. The whole
+instrument itself is a Component Assembly which contains all of the
+other top level components in the Instrument tree.
+
+Instrument Tree
+---------------
+
+|SimpleInstrumentTree.png| Most instruments in Mantid are defined using
+a tree structure allowing the top level structure objects to be reused
+if they are repeated in an instrument. This is an example of a
+simplified instrument tree, the lines show the links between the parent
+and child relationships of the components. Full details on how to define
+an instrument can be found `here <InstrumentDefinitionFile>`__.
+
+
+
+.. |SimpleInstrumentTree.png| image:: SimpleInstrumentTree.png
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Geometry_of_Shape.rst b/Code/Mantid/docs/source/concepts/Geometry_of_Shape.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e232f7e90f72e9c009db685086d8125a33c51369
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Geometry_of_Shape.rst
@@ -0,0 +1,57 @@
+.. _Geometry of Shape:
+
+Geometry_of_Shape
+=================
+
+What is it?
+-----------
+
+In Mantid we use `constructive solid geometry
+(CSG) <http://en.wikipedia.org/wiki/Constructive_solid_geometry>`__ to
+describe the shape of an object. This involves the creation of more
+complex shapes by the union, complement or intersection of simple
+primitive surfaces.
+
+Why did we use CSG
+------------------
+
+Defining our object shape using CSG was selected for a number of
+reasons:
+
+#. Using Surfaces based on mathematical equations rather than meshes of
+ vertices give much better accuracy when tracking the interaction of
+ particles through objects.
+#. Scientists think in the shape of objects this way, for example if
+ they have a sample that is a sphere radius 0.03m with a conical
+ extrusion on top then that is exactly how they describe it in CSG.
+ Otherwise they would need to be able to describe the co-ordinates for
+ each vertex of the surface.
+
+What shapes can be constructed
+------------------------------
+
+Mantid has direct support for creating various shapes directly,
+including
+
+- Sphere
+- Infinite Cylinder
+- Cylinder (finite height)
+- Slice of cylinder ring
+- Infinite Plane
+- Cuboid
+- Infinite Cone
+
+Some of these shapes are infinite surfaces (the infinite plane, cone and
+cylinder) these are therefore not very useful on there own, but in
+combination with other shapes they can be capped as required.
+
+For example if you cap and infinite Cylinder with two infinite planes
+you get a finite capped cylinder. This is in fact how the Cylinder shape
+is defined internally within Mantid.
+
+For more on this see
+`HowToDefineGeometricShape <HowToDefineGeometricShape>`__.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/HowToDefineGeometricShape.rst b/Code/Mantid/docs/source/concepts/HowToDefineGeometricShape.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c9251bcd851eef49ca9dc5a67e98fb4e1118c59b
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/HowToDefineGeometricShape.rst
@@ -0,0 +1,468 @@
+.. _HowToDefineGeometricShape:
+
+HowToDefineGeometricShape
+=========================
+
+Overview
+--------
+
+Primitive Shapes
+~~~~~~~~~~~~~~~~
+
+There is direct support for defining any of the following geometric
+shapes to add `Instrument Definition File <IDF>`__.
+
+- Sphere
+- Infinite Cylinder
+- Cylinder (finite height)
+- Slice of cylinder ring
+- Infinite Plane
+- Cuboid
+- Infinite Cone
+- Cone
+
+Combining Primitive shapes
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to the shapes listed above, other shapes may be defined by
+combining already defined shapes into new ones. This is done using an
+algebra that follows the following notation:
+
++------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
+| Operator | Description | Example |
++============+================================================================================================================================================================+======================================================================================================+
+| | Union (i.e two or more things making up one shape). See e.g. also `1 <http://en.wikipedia.org/wiki/Union_(set_theory)>`__ | a body = legs : torso : arms : head |
++------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
+| " " | "space" shared between shapes, i,e. intersection (the common region of shapes). See e.g. also `2 <http://en.wikipedia.org/wiki/Intersection_(set_theory)>`__ | "small-circle = big-circle small-circle" (where the small circle placed within the big-circle) |
++------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
+| #. | Complement | #. sphere = shape defined by all points outside sphere |
+
++------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
+| ( ) | Brackets are used to emphasise which shapes an operation should be applied to. | box1 (# box2) is the intersection between box1 and the shape defined by all points not inside box2 |
++------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
+
+Axes and units of measure
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All objects are defined with respect to cartesian axes (x,y,z), and the
+`default <IDF#Using_.3Cdefaults.3E>`__ unit of all supplied values are
+metres(m). Objects may be defined so that the origin (0,0,0) is at the
+centre, so that when rotations are applied they do not also apply an
+unexpected translation.
+
+Within instrument definitions we support the concept of defining a
+rotation by specifying what point the object is
+`facing <InstrumentDefinitionFile#Using_.3Cfacing.3E>`__. To apply that
+correctly the side of the object we consider to be the front is the xy
+plane. Hence, when planning to use
+`facing <InstrumentDefinitionFile#Using_.3Cfacing.3E>`__ the shape
+should be defined such that the positive y-axis is considered to be up,
+the x-axis the width, and the z-axis the depth of the shape.
+
+To be aware off
+---------------
+
+When defining a shape you have complete freedom to define it with
+respect to whatever coordinate system you like. However, we have a least
+the following recommendation
+
+- The origin of coordinate system of a shape is used for calculating
+ the L2 distances. Therefore at least for any TOF instruments where
+ you care about L2 distances, the origin should be chosen to be at the
+ position on your detector shape that is best used for calculation the
+ L2 distance
+
+Examples
+--------
+
+Defining a sphere
+~~~~~~~~~~~~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <sphere id="some-sphere">
+ <centre x="0.0" y="0.0" z="0.0" />
+ <radius val="0.5" />
+ </sphere>
+
+ <algebra val="some-sphere" />
+
+.. raw:: html
+
+ </div>
+
+Any shape must be given an ID name. Here the sphere has been given the
+name "some-sphere". The purpose of the ID name is to use it in the
+description, here this is done with the line . The description is
+optional. If it is left out the algebraic intersection is taken between
+any shapes defined.
+
+Defining a ball with a hole through it along the x-axis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <cylinder id="stick">
+ <centre-of-bottom-base x="-0.5" y="0.0" z="0.0" />
+ <axis x="1.0" y="0.0" z="0.0" />
+ <radius val="0.05" />
+ <height val="1.0" />
+ </cylinder>
+
+ <sphere id="some-sphere">
+ <centre x="0.0" y="0.0" z="0.0" />
+ <radius val="0.5" />
+ </sphere>
+
+ <algebra val="some-sphere (# stick)" />
+
+.. raw:: html
+
+ </div>
+
+This algebra string reads as follows: take the *intersection* between a
+sphere and the shape defined by all points *not* inside a cylinder of
+length 1.0 along the x-axis. Note the brackets around # stick in the
+algebraic string are optional, but here included to emphasis that the
+"space" between the "some-sphere" and "(# stick)" is the intersection
+operator.
+
+Notation used to defined any of the predefined geometric shapes
+---------------------------------------------------------------
+
+Sphere
+~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <sphere id="A">
+ <centre x="4.1" y="2.1" z="8.1" />
+ <radius val="3.2" />
+ </sphere>
+
+.. raw:: html
+
+ </div>
+
+Cylinder
+~~~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <cylinder id="A">
+ <centre-of-bottom-base r="0.0" t="0.0" p="0.0" /> <!-- here position specified using spherical coordinates -->
+ <axis x="0.0" y="0.2" z="0" />
+ <radius val="1" />
+ <height val="10.2" />
+ </cylinder>
+
+.. raw:: html
+
+ </div>
+
+.. figure:: XMLcylinderDescription.png‎
+ :alt: XMLcylinderDescription.png‎
+
+ XMLcylinderDescription.png‎
+Infinite cylinder
+~~~~~~~~~~~~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <infinite-cylinder id="A" >
+ <centre x="0.0" y="0.2" z="0" />
+ <axis x="0.0" y="0.2" z="0" />
+ <radius val="1" />
+ </infinite-cylinder>
+
+.. raw:: html
+
+ </div>
+
+Slice of cylinder ring
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <slice-of-cylinder-ring id="A">
+ <inner-radius val="0.0596"/>
+ <outer-radius val="0.0646"/>
+ <depth val="0.01"/>
+ <arc val="45.0"/>
+ </slice-of-cylinder-ring>
+
+.. raw:: html
+
+ </div>
+
+This XML element defines a slice of a cylinder ring. Most importantly
+the part of this shape facing the sample is flat and looks like this:
+
+.. figure:: XMLsliceCylinderRingDescription.png
+ :alt: XMLsliceCylinderRingDescription.png
+
+ XMLsliceCylinderRingDescription.png
+For this shape you may find it useful to specify a
+`Bounding-Box <HowToDefineGeometricShape#Bounding-Box>`__.
+
+Cone
+~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <cone id="A" >
+ <tip-point x="0.0" y="0.2" z="0" />
+ <axis x="0.0" y="0.2" z="0" />
+ <angle val="30.1" />
+ <height val="10.2" />
+ </cone>
+
+.. raw:: html
+
+ </div>
+
+.. figure:: XMLconeDescription.png
+ :alt: XMLconeDescription.png
+
+ XMLconeDescription.png
+Infinite cone
+~~~~~~~~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <infinite-cone id="A" >
+ <tip-point x="0.0" y="0.2" z="0" />
+ <axis x="0.0" y="0.2" z="0" />
+ <angle val="30.1" />
+ </infinite-cone>
+
+.. raw:: html
+
+ </div>
+
+Infinite plane
+~~~~~~~~~~~~~~
+
+Is the 3D shape of all points on the plane and all points on one side of
+the infinite plane, the side which point away from the infinite plane in
+the direction of the normal vector.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <infinite-plane id="A">
+ <point-in-plane x="0.0" y="0.2" z="0" />
+ <normal-to-plane x="0.0" y="0.2" z="0" />
+ </infinite-plane>
+
+.. raw:: html
+
+ </div>
+
+Cuboid
+~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <cuboid id="shape">
+ <left-front-bottom-point x="0.0025" y="-0.1" z="0.0" />
+ <left-front-top-point x="0.0025" y="-0.1" z="0.02" />
+ <left-back-bottom-point x="-0.0025" y="-0.1" z="0.0" />
+ <right-front-bottom-point x="0.0025" y="0.1" z="0.0" />
+ </cuboid>
+ <algebra val="shape" />
+
+.. raw:: html
+
+ </div>
+
+This particular example describes a cuboid with the origin at the centre
+of the front face, which is here facing the negative z-axis and has the
+dimensions 0.005mm x 0.2mm (in the xy-plane), and the depth of this
+cuboid is 0.02mm.
+
+.. figure:: XMLcuboidDescription.png
+ :alt: XMLcuboidDescription.png
+
+ XMLcuboidDescription.png
+Another example of a cuboid is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <cuboid id="shape">
+ <left-front-bottom-point x="0.0" y="-0.1" z="-0.01" />
+ <left-front-top-point x="0.0" y="0.1" z="-0.01" />
+ <left-back-bottom-point x="0.001" y="-0.1" z="-0.01" />
+ <right-front-bottom-point x="0.0" y="-0.1" z="0.01" />
+ </cuboid>
+ <algebra val="shape" />
+
+.. raw:: html
+
+ </div>
+
+which describes a cuboid with a front y-z plane (looking down the
+x-axis). The origin is assumed to be the centre of this front surface,
+which has dimensions 200mm along y and 20mm along z. The depth of this
+cuboid is taken to be 1mm (along x).
+
+Hexahedron
+~~~~~~~~~~
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <hexahedron id="Bertie">
+ <left-back-bottom-point x="0.0" y="0.0" z="0.0" />
+ <left-front-bottom-point x="1.0" y="0.0" z="0.0" />
+ <right-front-bottom-point x="1.0" y="1.0" z="0.0" />
+ <right-back-bottom-point x="0.0" y="1.0" z="0.0" />
+ <left-back-top-point x="0.0" y="0.0" z="2.0" />
+ <left-front-top-point x="0.5" y="0.0" z="2.0" />
+ <right-front-top-point x="0.5" y="0.5" z="2.0" />
+ <right-back-top-point x="0.0" y="0.5" z="2.0" />
+ </hexahedron>
+
+.. raw:: html
+
+ </div>
+
+.. figure:: XMLhexahedronDescription.png
+ :alt: XMLhexahedronDescription.png
+
+ XMLhexahedronDescription.png
+For this shape you may find it useful to specify a
+`Bounding-Box <HowToDefineGeometricShape#Bounding-Box>`__.
+
+Tapered Guide
+~~~~~~~~~~~~~
+
+Available from version 3.0 onwards.
+
+A tapered guide is a special case of hexahedron; a "start" rectangular
+aperture which in a continued fashion changes into an "end" rectangular
+aperture.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <tapered-guide id="A Guide">
+ <aperture-start height="2.0" width="2.0" />
+ <length val="3.0" />
+ <aperture-end height="4.0" width="4.0" />
+ <centre x="0.0" y="5.0" z="10.0" /> <!-- Optional. Defaults to (0, 0 ,0) -->
+ <axis x="0.5" y="1.0" z="0.0" /> <!-- Optional. Defaults to (0, 0 ,1) -->
+ </tapered-guide>
+
+.. raw:: html
+
+ </div>
+
+The centre value denotes the centre of the start aperture. The specified
+axis runs from the start aperture to the end aperture. "Height" is along
+the y-axis and "width" runs along the x-axis, before the application of
+the "axis" rotation.
+
+For this shape you may find it useful to specify a
+`Bounding-Box <HowToDefineGeometricShape#Bounding-Box>`__.
+
+Bounding-Box
+------------
+
+When a geometric shape is rendered in the MantidPlot instrument viewer a
+bounding box is automatically created for each geometric shape. This
+works well for shapes such as cylinders and cuboids. However, for more
+complex shapes and combined shapes the library used for the
+visualization sometimes struggle, which can results in your instrument
+being viewed artifically very small (and you have to zoom in for a long
+time to see your instrument) and often in this context that the
+visualization axes does not display properly. For such cases this can be
+fixed by explicitely adding a bounding-box using the notation
+demonstrated below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <hexahedron id="shape">
+ <left-front-bottom-point x="0.0" y="-0.037" z="-0.0031" />
+ <right-front-bottom-point x="0.0" y="-0.037" z="0.0031" />
+ <left-front-top-point x="0.0" y="0.037" z="-0.0104" />
+ <right-front-top-point x="0.0" y="0.037" z="0.0104" />
+ <left-back-bottom-point x="0.005" y="-0.037" z="-0.0031" />
+ <right-back-bottom-point x="0.005" y="-0.037" z="0.0031" />
+ <left-back-top-point x="0.005" y="0.037" z="-0.0104" />
+ <right-back-top-point x="0.005" y="0.037" z="0.0104" />
+ </hexahedron>
+ <algebra val="shape" />
+
+ <bounding-box>
+ <x-min val="0.0"/>
+ <x-max val="0.005"/>
+ <y-min val="-0.037"/>
+ <y-max val="0.037"/>
+ <z-min val="-0.0104"/>
+ <z-max val="0.0104"/>
+ </bounding-box>
+
+.. raw:: html
+
+ </div>
+
+Note for the best effect this bounding box should be enclosing the shape
+as tight as possible.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Instrument.rst b/Code/Mantid/docs/source/concepts/Instrument.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f0a453ddb681eb45b6cfb93d65d84d5f9e903447
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Instrument.rst
@@ -0,0 +1,47 @@
+.. _Instrument:
+
+Instrument
+==========
+
+What are they?
+--------------
+
+The Instrument is a geometrical description of the components that make
+up the beam line. The components described will generally include:
+
+- The source
+- The sample position
+- Each detector 'pixel'
+- Each monitor
+
+Other components may also be included such as
+
+- Slits
+- Mirrows
+- Guides
+- Choppers
+- Engineering obstacles in the beam path
+- Link between log-files and variable parameters of the instrument
+ (such as the height of a detector table)
+
+An instrument is described using an `instrument definition
+file <InstrumentDefinitionFile>`__.
+
+The Mantid geometry is further explained `here <Geometry>`__.
+
+Why do we have a full instrument description, and not just a list of L2 and 2Theta values?
+------------------------------------------------------------------------------------------
+
+A list of L2 and 2Theta values will provide information to perform unit
+conversions and several other algorithms, however a full geometric
+instrument description allows much more.
+
+- Visualization of the instrument internals with data overlays
+- Complex absorption corrections
+- Montecarlo simulations of experiments
+- Updating the instrument geometry according to values stored in
+ log-files
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/InstrumentDefinitionFile.rst b/Code/Mantid/docs/source/concepts/InstrumentDefinitionFile.rst
new file mode 100644
index 0000000000000000000000000000000000000000..171fa718aa1b4262d6ea627e8df1a2c33003f84e
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/InstrumentDefinitionFile.rst
@@ -0,0 +1,1698 @@
+.. _InstrumentDefinitionFile:
+
+InstrumentDefinitionFile
+========================
+
+.. role:: math(raw)
+ :format: html latex
+..
+
+The documentation on this wiki page is the full detailed description of
+the syntax you can use in an IDF to describe an instrument (note
+parameters of instrument components may optionally be stored in
+`parameter file <InstrumentParameterFile>`__).
+
+To get started creating an IDF follow the instructions on the `Create an
+IDF <Create_an_IDF>`__ page, then return here for more detailed
+explanations of syntax and structures.
+
+Introduction
+------------
+
+An instrument definition file (IDF) aims to describe an instrument, in
+particular providing details about those components of the instruments
+that are critically affecting the observed signal from an experiment.
+Parameter values of components may also be specified such as information
+about the opening height of a slit, the final energy of a detector and
+so on. The value of such parameters can optionally be linked to values
+stored in log-files.
+
+In summary an IDF may be used to describe any or all of the following:
+
+#. Instrument components defined using a hierarchical structure. Take,
+ for example, a detector bank containing 100 identical tubes each
+ containing 100 detector pixels. One option is to describe this setup
+ using a flat structure of 100\*100=10000 pixel components. Although
+ this is a valid approach it 1) create uncessarily large files 2) but
+ most importantly it does not capture the layout of the instrument.
+ The prefered option is to describe this example by first defining a
+ “pixel†type, then a “tube†type containing 100 "pixels" and finally
+ a “bank†component containing 100 "tubes". This latter approach
+ requires the specification of 1(the bank)+100(tubes)+100(pixels)=201
+ components as compared to specifying 10000 components using the
+ former approach. The other benefit of organising the IDF according to
+ the layout of the instrument is that users can subsequently refer to
+ the structure of the instrument as it is layed out. For example can
+ then subsequently easily move entire 'bank' or associate parameters
+ which relevant for a specific say 'tube' or 'bank'.
+#. The geometric shape and position of any component including: slits,
+ mirrors, detectors etc.
+#. A number of `specialised component
+ types <InstrumentDefinitionFile#Special_.3Ctype.3Es>`__ are defined
+ including:
+
+ - detector and monitor components: required to be associated with
+ unique detector or monitor ID numbers. The importance of these IDs
+ are described further in
+ `1 <http://www.mantidproject.org/IDF#Using_detector.2Fmonitor_IDs_.3Cidlist.3E>`__
+ - SamplePos component: Purpose to store the sample position. Needed
+ e.g. to calculate sample-to-detector distances
+ - Source component: Purpose to store the source position or a
+ position along the beamline but before the sample. Needed e.g. for
+ spallation source instruments to calculate neutron flightpaths
+ including the source-to-sample (primary path) distance. Also, used
+ to define a point along the beam located before the sample. The
+ direction from this position to the SamplePos is currently used to
+ calculate the beam direction in some calculates (for example
+ two-theta scattering angles).
+
+#. Handling of log-files. Values specified in log-files can be used to
+ modify parameters of components, such as a detector position
+ coordinate or a slit opening height, in addition to assign values to
+ such parameters directly
+#. Specifying 'fitting' parameters of instrument profile functions and
+ other function to be used when data from the instrument are analysed.
+#. Choice of preferred coordinate system. For example the default is to
+ define the beam along the z-axis and the y-axis to point up.
+
+An IDF is structured as an `XML <http://en.wikipedia.org/wiki/XML>`__
+document. For the purpose here it is enough to know that an XML document
+follows a tree-based structure of elements with attributes. For example:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <type name="main-detector-bank">
+ <component type="main-detector-pixel" >
+ <location x="-0.31" y="0.1" z="0.0" />
+ <location x="-0.32" y="0.1" z="0.0" />
+ <location x="-0.33" y="0.1" z="0.0" />
+ </component>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+defines an XML element with has the attribute name="main-detector-bank".
+This element contains one sub-element , which again contains 3 elements.
+In plain English the above XML code aims to describe a
+“main-detector-bank†that contains 3 detector pixels and their locations
+within the bank.
+
+If a component is a cylindrical tube where slices of this types are
+treated as detector pixels the tube detector performance enhacement can
+optionally be used, which will e.g. make the display of this tube in the
+instrument viewer faster. This can be done by adding 'outline' attribute
+to the tag and setting its value to "yes".
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <type name="standard-tube" outline="yes">
+ <component type="standard-pixel" >
+ <location y="-1.4635693359375"/>
+ <location y="-1.4607080078125"/>
+ <location y="-1.4578466796875"/>
+ </component>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+The 'outline attribute' only affects the 3D view of the instrument,
+which appears by default. It may lead to a less accurate placing of the
+detector pixels and in particular may not show the effects of tube
+calibration. However a 2D view of the instrument will still place pixel
+detectors accurately.
+
+IDF filename convention
+-----------------------
+
+An IDF can be loaded manually from any file with extension .xml or .XML
+using `LoadInstrument <LoadInstrument>`__ or
+`LoadEmptyInstrument <LoadEmptyInstrument>`__.
+
+IDFs located in the MantidInstall instrument directory are automatically
+loaded together with e.g. the loading of raw data file. Such files are
+required to have the format INSTRUMENTNAME\_DefinitionANYTHING.xml,
+where INSTRUMENTNAME is the name of the instrument and ANYTHING can be
+any string including an empty string. Where more than one IDF is defined
+for an instrument the appropriate IDF is loaded based on its
+`valid-from <#Top_level_.3Cinstrument.3E>`__ and
+`valid-to <#Top_level_.3Cinstrument.3E>`__ dates. Note for this to work
+the `Workspace <Workspace>`__ for which an IDF is loaded into must
+contain a record of when the data were collected. This information is
+taken from the workspace's `Run <Run>`__ object, more specifically the
+*run\_start* property of this object.
+
+In order to programmatically determine which is the correct filename for
+a given date/time you can access a helper method from Python:
+
+.. raw:: html
+
+ <div style="border:1pt dashed blue; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: python
+
+ import mantid.api
+ # if no date is given it will default to returning the IDF filename that is currently valid.
+ currentIDF = mantid.api.ExperimentInfo.getInstrumentFilename("ARCS")
+ otherIDF = mantid.api.ExperimentInfo.getInstrumentFilename("ARCS", "2012-10-30")
+
+.. raw:: html
+
+ </div>
+
+More detailed descriptions of various parts of the IDF
+------------------------------------------------------
+
+Geometry shapes
+~~~~~~~~~~~~~~~
+
+For information on how to define geometric shapes see
+`HowToDefineGeometricShape <HowToDefineGeometricShape>`__.
+
+Top level
+~~~~~~~~~~
+
+ is the top level XML element of an IDF. It takes attributes, two of
+which must be included. An example is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <instrument name="ARCS"
+ valid-from="1900-01-31 23:59:59"
+ valid-to="2100-01-31 23:59:59"
+ last-modified="2010-10-12 08:54:07.279621">
+
+.. raw:: html
+
+ </div>
+
+Of the four attributes in the example above
+
+- name is (at present) optional, although it is recommended to specify
+ something sensible
+- valid-from is compulsory and is the date from which the IDF is valid
+ from (+). This date must be larger than or equal to 1900-01-31
+ 23:59:01
+- valid-to may optionally be added to indicate the date to which the
+ IDF is valid to. If not used, the file is permenently valid. (+)
+- last-modified is optional. Changing it can be used as an alternative
+ to force MantidPlot to reload the IDF, which e.g. might be useful
+ during the build up of an IDF
+
+(+) Both valid-from and valid-to are required to be set using the ISO
+8601 date-time format, i.e. as YYYY-MM-DD HH:MM:SS or
+YYYY-MM-DDTHH:MM:SS `2 <http://en.wikipedia.org/wiki/ISO_8601YYYY>`__.
+Valid ranges may overlap, provided the valid-from times are all
+different. If several files are currently valid, the one with the most
+recent valid-from time is selected.
+
+Using and
+~~~~~~~~~~
+
+Use the element to define a physical part of the instrument. A requires
+two things
+
+#. It must have a type="some type" attribute. This specify the 'type' of
+ the component and this type must be specified somewhere in the IDF
+ using: .
+#. It must contain at least one element. If multiple are specified then
+ this is essentially a shorthand notation for defining multiple
+ components of the same type at different locations.
+
+Here is an example
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="slit" name="bob">
+ <location x="10.651"/>
+ <location x="11.983"/>
+ </component>
+
+ <type name="slit"></type>
+
+.. raw:: html
+
+ </div>
+
+Which defined two slits at two difference locations. Optionally a can be
+given a 'name', in the above example this name is "bob". If no 'name'
+attribute is specified the name of the defaults to the 'type' string, in
+the above this is "slit". Giving sensible names to components is
+recommended for a number of reasons including 1) The 'Instrument Tree'
+view of an instrument in MantidPlot uses these names 2) when specifying
+s through s these names are used.
+
+Special s
+^^^^^^^^^
+
+Within Mantid certain s have special meaning. A special is specified by
+including an 'is' attribute as demonstrated below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <type name="pixel" is="detector">
+ <cuboid id="app-shape">
+ <left-front-bottom-point x="0.0025" y="-0.1" z="0.0" />
+ <left-front-top-point x="0.0025" y="-0.1" z="0.0002" />
+ <left-back-bottom-point x="-0.0025" y="-0.1" z="0.0" />
+ <right-front-bottom-point x="0.0025" y="0.1" z="0.0" />
+ </cuboid>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+where the 'is' attribute of is used to say this is a detector- (note
+this particular detector- has been assigned a geometric shape, in this
+case a cuboid, see
+`HowToDefineGeometricShape <HowToDefineGeometricShape>`__). Special
+types recognised are:
+
+#. Detector (or detector)
+#. Monitor (or monitor)
+#. `RectangularDetector <InstrumentDefinitionFile#Creating_Rectangular_Area_Detectors>`__
+ (or rectangularDetector, rectangulardetector, or
+ rectangular\_detector)
+#. Source (or source)
+#. SamplePos (or samplePos)
+#. ChopperPos (or chopperPos)
+
+For example it is important to specify the location of one Source- and
+one SamplePos- in order for Mantid to be able to calculate L1 and L2
+distances and convert time-of-flight to, for instance, d-spacing. An
+example of specifying a Source and SamplePos is shown below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="neutron moderator"> <location z="-10.0"/> </component>
+ <type name="neutron moderator" is="Source"/>
+
+ <component type="some sample holder"> <location /> </component>
+ <type name="some sample holder" is="SamplePos" />
+
+.. raw:: html
+
+ </div>
+
+Using detector/monitor IDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any component that is either a detector or monitor must be assigned a
+unique detector/monitor ID numbers (note this is *not* spectrum ID
+numbers but detector/monitor ID numbers). There are at least two
+important reason to insist on this.
+
+- Data stored in files need to have a way to be linked to
+ detectors/monitors defined in the IDF. For example, at the ISIS
+ facility, data are recorded together with unique detector ID numbers.
+ Hence the job here to match the IDs in the data file with the IDs of
+ the IDF. Where unique IDs are not stored with the data the creator of
+ an IDF have some flexibility to chose these ID numbers since the data
+ themself does not contain such number. However a link between the IDs
+ and spectra in a workspace still needs to be made. By default the
+ `LoadInstrument <LoadInstrument>`__ algorithm, see in particular the
+ RewriteSpectraMap parameter of this algorithm, will map the
+ detector/monitor IDs with spectrum numbers as follows: the
+ detector/monitor IDs in the IDF are ordered from smallest to largest
+ number and then assigned in that order to the spectra in the
+ workspace used to hold the data in Mantid.
+- Mantid needs to have a way to associate data which the
+ detectors/monitors of the instrument, which is do this using the
+ detector IDs. Although not mandatory it is recommended to give
+ memorizable names to collection of detectors/monitors or individual
+ detectors/monitors that a user is likely to want to refer. This allow
+ a user to refer to a collection of detectors by name rather than
+ trying to remember a sequence of IDs. Note the counts in a histogram
+ spectrum may be the sum of counts from a number of detectors and
+ Mantid, behind the scene, use the IDs to keep track of this.
+
+The element and the idlist attribute of the elements is used to assign
+detector IDs. The notation for using idlist is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="monitor" idlist="monitor-id-list">
+ <location r="5.15800" t="180.0" p="0.0" /> <!-- set to ID=500 in list below -->
+ <location r="5.20400" t="180.0" p="0.0" /> <!-- set to ID=510 -->
+ <location r="5.30400" t="180.0" p="0.0" /> <!-- set to ID=520 -->
+ <location r="5.40400" t="180.0" p="0.0" /> <!-- set to ID=531 -->
+ <location r="6.10400" t="180.0" p="0.0" /> <!-- set to ID=611 -->
+ <location r="6.24700" t="0.000" p="0.0" /> <!-- set to ID=612 -->
+ <location r="6.34700" t="0.000" p="0.0" /> <!-- set to ID=613 -->
+ <location r="6.50000" t="0.000" p="0.0" /> <!-- set to ID=650 -->
+ </component>
+
+ <type name="monitor" is="monitor"/>
+
+ <idlist idname="monitor-id-list">
+ <id start="500" step="10" end="530" /> <!-- specifies IDs: 500, 510, 520, 530 -->
+ <id start="611" end="613" /> <!-- specifies IDs: 611, 612 and 613 -->
+ <id val="650" /> <!-- specifies ID: 650 -->
+ </idlist>
+
+.. raw:: html
+
+ </div>
+
+As can be seen to specify a sequence of IDs use the notation , where if
+the step attribute defaults to step="1" if it is left out. Just specify
+just a single ID number you may alternatively use the notation . Please
+note the number of ID specified must match the number of
+detectors/monitors defined.
+
+Creating Rectangular Area Detectors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a shortcut way to create 2D arrays of detector pixels. Here is
+an example of how to do it:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="panel" idstart="1000" idfillbyfirst="y" idstepbyrow="300">
+ <location r="0" t="0" name="bank1">
+ </location>
+ </component>
+
+ <component type="panel" idstart="100000" idfillbyfirst="y" idstepbyrow="300">
+ <location r="45.0" t="0" name="bank2">
+ </location>
+ </component>
+
+ <!-- Rectangular Detector Panel. Position 100 "pixel" along x from -0.1 to 0.1
+ and 200 "pixel" along y from -0.2 to 0.2 (relative to the coordinate system of the bank) -->
+ <type name="panel" is="RectangularDetector" type="pixel"
+ xpixels="100" xstart="-0.100" xstep="+0.002"
+ ypixels="200" ystart="-0.200" ystep="+0.002" >
+ </type>
+
+ <!-- Pixel for Detectors. Shape defined to be a (0.001m)^2 square in XY-plane with tickness 0.0001m -->
+ <type is="detector" name="pixel">
+ <cuboid id="pixel-shape">
+ <left-front-bottom-point y="-0.001" x="-0.001" z="0.0"/>
+ <left-front-top-point y="0.001" x="-0.001" z="0.0"/>
+ <left-back-bottom-point y="-0.001" x="-0.001" z="-0.0001"/>
+ <right-front-bottom-point y="-0.001" x="0.001" z="0.0"/>
+ </cuboid>
+ <algebra val="pixel-shape"/>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+- The "panel" type defined above has the special "is" tag of
+ "RectangularDetector". The same type definition then needs these
+ attributes specified:
+
+ - type: point to another type defining your pixel shape and size.
+ - xpixels: number of pixels in X
+ - xstart: x-position of the 0-th pixel (in length units, normally
+ meters)
+ - xstep: step size between pixels in the horizontal direction (in
+ length units, normally meters)
+ - ypixels: number of pixels in Y
+ - ystart: y-position of the 0-th pixel (in length units, normally
+ meters)
+ - ystep: step size between pixels in the vertical direction (in
+ length units, normally meters)
+
+- Detectors of the type specified ("pixel" in the example) will be
+ replicated at the X Y coordinates given. The usual rotation and
+ translation of the panel will rotate the pixels as needed.
+- Each instance of a "panel" needs to set these attributes, at the tag,
+ in order to specify the Pixel IDs of the 2D array.
+
+ - idstart: detector ID of the first pixel
+ - idfillbyfirst: set to true if ID numbers increase with Y indices
+ first. That is: (0,0)=0; (0,1)=1, (0,2)=2 and so on. Default is
+ idfillbyfirst="y".
+ - idstepbyrow: amount to increase the ID number on each row. e.g, if
+ you fill by Y first,and set idstepbyrow = 100, and have 50 Y
+ pixels, you would get: (0,0)=0; (0,1)=1; ... (0,49)=49; (1,0)=100;
+ (1,1)=101; etc.
+ - idstep. Default to 1. Set the ID increment within a row.
+
+- DO NOT also specify an "idlist" attribute for rectangular detectors,
+ as it will not be used.
+
+- Advantages of using a Rectangular Detector tag instead of defining
+ every single pixel:
+
+ - The data will be displayed as a bitmap in the instrument 3D view,
+ making rendering much faster.
+ - Smaller IDF and faster instrument loading times.
+ - No need to make a script to generate the pixel positions.
+
+- Disadvantages/Limitations:
+
+ - Must have constant pixel spacing in each direction.
+ - Must be rectangular shape.
+
+Using
+~~~~~~
+
+The element allows the specification of both the position of a component
+and a rotation or the component's coordinate system. The position part
+can be specified either using standard x, y and z coordinates or using
+spherical coordinates: r, t and p, which stands for radius, theta and
+phi, t is the angle from the z-axis towards the x-axis and p is the
+azimuth angle in the xy-plane
+`3 <http://en.wikipedia.org/wiki/Spherical_coordinate_system>`__.
+Examples of translations include
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="something" name="bob">
+ <location x="1.0" y="0.0" z="0.0" name="benny" />
+ <location r="1.0" t="90.0" p="0.0"/>
+ </component>
+
+.. raw:: html
+
+ </div>
+
+The above two translations have identical effect. They both translate a
+component along the x-axis by "1.0". Note that optionally a can be given
+a name similarly to how a can optionally be given a name. In a 'name'
+attribtute is not specified for a element it defaults to the name of the
+.
+
+The rotation part is specified using the attributes 'rot', 'axis-x',
+'axis-y', 'axis-z' and these result in a rotation about the axis defined
+by the latter three atttributes. As an example the effect of
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <location rot="45.0" axis-x="0.0" axis-y="0.0" axis-z="1.0"/>
+
+.. raw:: html
+
+ </div>
+
+is to set the coordinate frame of the this component equal to that of
+the parent component rotated by 45 degrees around the z-axis.
+
+Both a translation and rotation can be defined within one element. For
+example
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <location x="1.0" y="0.0" z="0.0" rot="45.0" axis-x="0.0" axis-y="0.0" axis-z="1.0"/>
+
+.. raw:: html
+
+ </div>
+
+will cause this componet to be translation along the x-axis by "1.0"
+relative to the coordinate frame of the parent component followed by a
+rotation of the coordinate frame by 45 degrees around the z-axis as
+demonstrated in the figure below.
+
+.. figure:: Location-element-transformation.png
+ :alt: Location-element-transformation.png
+
+ Location-element-transformation.png
+Any rotation of a coordinate system can be performed by a rotation about
+some axis, however, sometime it may be advantageous to think of such a
+rotation as a composite of two or more rotations. For this reason a
+element is allowed to have sub-rotation-elements, and an example of a
+composite rotation is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <location r="4.8" t="5.3" p="102.8" rot="-20.6" axis-x="0" axis-y="1" axis-z="0">
+ <rot val="102.8">
+ <rot val="50" axis-x="0" axis-y="1" axis-z="0" />
+ </rot>
+ </location>
+
+.. raw:: html
+
+ </div>
+
+The outermost is applied first followed by the 2nd outermost operation
+and so on. In the above example this results in a -20.6 degree rotation
+about the y-axis followed by a 102.8 degree rotation about the z-axis
+(of the frame which has just be rotated by -20.6 degrees) and finally
+followed by another rotation about the y-axis, this time by 50 degrees.
+The ISIS NIMROD instrument (NIM\_Definition.xml) uses this feature.
+
+The translation part of a element can like the rotation part also be
+split up into a nested set of translations. This is demonstrated below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <location r="10" t="90" >
+ <trans r="8" t="-90" />
+ </location>
+
+.. raw:: html
+
+ </div>
+
+This combination of two translations: one moving 10 along the x-axis in
+the positive direction and the other in the opposite direction by 8 adds
+up to a total translation of 2 in the positive x-direction. This
+feature, for example, is useful when the positions of detectors are best
+described in spherical coordinates with respect to an origin different
+from the origin of the parent component. For example, say you have
+defined a with contains 3 pixels. The centre of the bank is at the
+location r="1" with respect to the sample and the positions of the 3
+pixels are known with respect to the sample to be at r="1" and with
+t="-1", t="0" and t="1". One option is to describe this bank/pixels
+structure as
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="bank">
+ <location />
+ </component>
+
+ <type name="bank">
+ <component type="pixel">
+ <location r="1" t="-1" />
+ <location r="1" t="0" />
+ <location r="1" t="1" />
+ </component>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+However a better option for this case is to use nested translations as
+demonstrated below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="bank">
+ <location r="1"/>
+ </component>
+
+ <type name="bank">
+ <component type="pixel">
+ <location r="1" t="180"> <trans r="1" t="-1" /> </location>
+ <location r="1" t="180"> <trans r="1" t="0" /> </location>
+ <location r="1" t="180"> <trans r="1" t="1" /> </location>
+ </component>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+since this means the bank is actually specified at the right location,
+and not artificially at the sample position.
+
+Finally a combination of and sub-elements of a element can be used as
+demonstrated below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <location x="10" >
+ <rot val="90" >
+ <trans x="-8" />
+ </rot>
+ </location>
+
+.. raw:: html
+
+ </div>
+
+which put something at the location (x,y,z)=(10,-8,0) relative to the
+parent component and with a 90 rotation around the z-axis, which causes
+the x-axis to be rotated onto the y-axis.
+
+Most of the attributes of have default values. These are: x="0" y="0"
+z="0" rot="0" axis-x="0" axis-y="0" axis-z="1"
+
+Using
+^^^^^^
+
+The element is an element you can use together with a . Its purpose is
+to be able, with one line of IDF code, to make a given component face a
+point in space. For example many detectors on ISIS instruments are setup
+to face the sample. A element must be specified as a sub-element of a
+element, and the facing operation is applied after the translation
+and/or rotation operation as specified by the location element. An
+example of a element is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <facing x="0.0" y="0.0" z="0.0"/>
+ or
+ <facing r="0.0" t="0.0" p="0.0"/>
+
+.. raw:: html
+
+ </div>
+
+In addition if the is set under , i.e. by default any component in the
+IDF will be rotated to face a default position then
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <facing val="none"/>
+
+.. raw:: html
+
+ </div>
+
+can be used to overwrite this default to say you don't want to apply
+'facing' to given component.
+
+The process of facing is to make the xy-plane of the geometric shape of
+the component face the position specified in the element. The z-axis is
+normal to the xy-plan, and the operation of facing is to change the
+direction of the z-axis so that it points in the direction from the
+position specified in the facing towards the position of the component.
+
+ supports a rot attribute, which allow rotation of the z-axis around it
+own axis before changing its direction. The effect of rot here is
+identical to the effect of using rot in a where axis-x="0.0"
+axis-y="0.0" axis-z="1.0". Allowing rot here perhpas make it slightly
+clearly that such a rot is as part of facing a component towards another
+component.
+
+which rotate the is a convenient element for adjusting the orientation
+of the z-axis. The base rotation is to take the direction the z-axis
+points and change it to point from the position specified by the element
+to the positon of the component.
+
+Using
+^^^^^^
+
+A specifies the location of a . If this type consists of a number of
+sub-parts can be used to exclude certain parts of a type. For example
+say the type below is defined in an IDF
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <type name="door">
+ <component type="standard-tube">
+ <location r="2.5" t="19.163020" name="tube1"/>
+ <location r="2.5" t="19.793250" name="tube2"/>
+ <location r="2.5" t="20.423470" name="tube3"/>
+ <location r="2.5" t="21.053700" name="tube4"/>
+ <location r="2.5" t="21.683930" name="tube5"/>
+ </component>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+and the instrument consists of a number of these doors but where some of
+the doors are different in the sense that for example the 1st and/or the
+2nd tube is missing from some of these. Using this can be succinctly
+described as follows:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="door">
+ <location x="0">
+ <exclude sub-part="tube1"/>
+ <exclude sub-part="tube3"/>
+ </location>
+ <location x="1" />
+ <location x="2" />
+ <location x="3">
+ <exclude sub-part="tube3"/>
+ </location>
+ </component>
+
+.. raw:: html
+
+ </div>
+
+where the sub-part of refers to the 'name' of a part of the type 'door'.
+
+Extra options for indirect geometry instruments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Optionally, both physical and 'neutronic' detector positions can be
+specified for indirect geometry instrument. This is described
+`here <Indirect Instrument Definition Options>`__.
+
+Using
+~~~~~~
+
+Most instruments have detectors which are orderered in some way. For a
+`rectangular array of
+detectors <IDF#Creating_Rectangular_Area_Detectors>`__ we have a
+shorthand notation. The tag is a shorthand notation to use for a
+linear/spherical sequence of detectors, as any of the position
+coordinates or the coordinate rotation angles of a tag are changing.
+
+For example a element may be used to describe the position of equally
+distanced pixels along a tube, in the example below along the y variable
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <locations y="1.0" y-end="10.0" n-elements="10" name="det"/>
+
+.. raw:: html
+
+ </div>
+
+The above one line of XML is shorthand notation for
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <location y="1.0" name="det0"/>
+ <location y="2.0" name="det1" />
+ <location y="3.0" name="det2" />
+ <location y="4.0" name="det3" />
+ <location y="5.0" name="det4" />
+ <location y="6.0" name="det5" />
+ <location y="7.0" name="det6" />
+ <location y="8.0" name="det7" />
+ <location y="9.0" name="det8" />
+ <location y="10.0" name="det9" />
+
+.. raw:: html
+
+ </div>
+
+As is seen n-elements is the number of elements this element is
+shorthand for. y-end specifies the y end position, and the equal
+distance in y between the pixels is calculated in the code as
+('y'-'y-end')/('n-elements'-1). Multiple 'variable'-end attributes can
+be specified for the tag, where 'variable' here is any of the
+attributes: x, y, z, r, t, p and rot. The example below describes a list
+of detectors aligned in a semi-circle:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <locations n-elements="7" r="0.5" t="0.0" t-end="180.0" rot="0.0" rot-end="180.0" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+
+.. raw:: html
+
+ </div>
+
+The above one line of XML is shorthand notation for
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <location r="0.5" t="0" rot="0" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+ <location r="0.5" t="30" rot="30" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+ <location r="0.5" t="60" rot="60" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+ <location r="0.5" t="90" rot="90" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+ <location r="0.5" t="120" rot="120" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+ <location r="0.5" t="150" rot="150" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+ <location r="0.5" t="180" rot="180" axis-x="0.0" axis-y="1.0" axis-z="0.0"/>
+
+.. raw:: html
+
+ </div>
+
+If name is specified, e.g. as name="det" in the first example, then as
+seen the elements are given the 'name' plus a counter, where by default
+this counter starts from zero. This counter can optionally be changed by
+using attribute name-count-start, e.g. setting name-count-start="1" in
+the above example would have named the 10 elements det1, det2, ...,
+det10.
+
+When one tag was used in ISIS LET\_Definition.xml the number of lines of
+this file reduced from 1590 to 567.
+
+Using
+~~~~~~
+
+Parameters which do not change or are changed via should be stored using
+this element inside the IDF, however parameters which may need to be
+accessed and changed manually on a regular basis should be stored in a
+separate `parameter file <InstrumentParameterFile>`__.
+
+ is used to specify a value to a parameter which can then be extracted
+from Mantid. One usage of is to link values stored in log-files to
+parameter names. For example
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="x">
+ <logfile id="trolley2_x_displacement" extract-single-value-as="position 1" />
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+reads: “take the first value in the “trolley2\_x\_displacement" log-file
+and use this value to set the parameter named 'x'.
+
+The name of the is specified using the 'name' tag. You may specify any
+name for a parameter except for name="pos" and name="rot". These are
+reserved keywords. Further a few names have a special effect when
+processed by Mantid
+
+- "x", "y", and "z" overwrite the x, y and z coordinate respectively of
+ the element of the component the is a sub-element of.
+- "r-position", "t-position" and "p-position" like "x", "y" and "z"
+ overwrite the x, y, z coordinates but specified using spherical
+ coordinates (as defined ). Note that the parameters "t-position" and
+ "p-position" are ignored if the parameter "r-position" is not also
+ set for the same component. If only "r-position" is set, say to
+ r-position="10.0", than the component will be set to
+ (x,y,z)=(0,0,10.0) i.e. theta and phi default to zero where not
+ specified.
+- "rotx", "roty" and "rotz" rotate the component's coordinate system
+ around the x-axis, y-axis and z-axis respectively in units of
+ degrees. If any of these are specified they re-define the rotation
+ for the component. You can specify two or three of these to create
+ any rotation. Regardless of what order rotx, roty and rotz is
+ specified in the IDF the combined rotation is equals that obtained by
+ applying rotx, then roty and finally rotz.
+- "Efixed". If specified the `ConvertUnits <ConvertUnits>`__ algorithm
+ uses this value in unit conversion
+- "SplitInto". How many MD boxes to split into when converting to MD.
+- "SplitThreshold". The threshold number of MDEvents in an MDBox before
+ splitting into a new MDBox. Concerns convert to MD.
+- "MaxRecursionDepth". The maximum depth of the MDBox tree when
+ converting to MD.
+- "offset-phi". Effective boolean for turning on/off Phi offsets by PI.
+ Set to Always to apply.
+
+The value of the parameter is in the above example specified using a
+log-file as specified with the element . The required attribute of is
+
+- *id* - the logfile name minus the file extension and the ISIS raw
+ file name. For example the id for the logfile 'CSP78173\_height.txt'
+ is 'height'.
+
+Optional attributes of are:
+
+- *extract-single-value-as* - specify which value (or values) from the
+ logfile should be used to. This attribute takes any of the following
+ strings
+
+ - **mean** (default)
+ - **position n** where n is an integer
+ - **first\_value** The first value in the run
+ - **last\_value** The last value in the run
+ - **median** The median value in the run
+ - **minimum** The minimum value in the run
+ - **maximum** The maximum value in the run
+
+- *eq* - the values in the log-file may not directly specify the
+ parameter you want to set in the IDF. A simple example is where the
+ values in the logfile are in units of mm, whereas the unit of length
+ in the IDF is meters. Hence for this case by setting
+ eq="0.001\*value" the values in the logfile are automatically
+ converted to meters. A more complicated example is where the height
+ of a detector is recorded in a log-file as the angle between from the
+ horizontal plane to the detector in unit of degrees. Say the distance
+ between the sample (which is assumed to be in the horizontal plane)
+ and the detector is 1.863m then by specifying
+ eq="1.863\*sin(value\*0.0174533)" the values in the log-file are
+ automatically converted into the height of the detector from the
+ horizontal plane in units of meters. Note pi/180=0.0174533 in
+ "sin(value\*0.0174533)" above is to transform degrees to radians.
+
+Another option for specifying a value for a parameter is to use the
+notation:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="x">
+ <value val="7.2"/>
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+Here a value for the parameter with name "x" is set directly to 7.2. The
+only and required attribute of the element is 'val'.
+
+For a given you should specify its value only once. If by mistake you
+specify a value twice as demonstrated in the example below then the
+first encountered element is used, and if no element is present then the
+first encountered element is used.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="x">
+ <value val="7.2"/>
+ <logfile id="trolley2_x_displacement" extract-single-value-as="position 1" />
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+In the above example is used.
+
+Accessing
+~~~~~~~~~~
+
+Parameters are by default accessed recursively, see for instance methods
+of
+`ParametrizedComponent <http://doxygen.mantidproject.org/classMantid_1_1Geometry_1_1ParametrizedComponent.html>`__.
+Demonstrated with an example:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="dummy">
+ <location/>
+ <parameter name="something"> <value val="35.0"/> </parameter>
+ </component>
+
+ <type name="dummy">
+ <component type="pixel" name="pixel1">
+ <location y="0.0" x="0.707" z="0.707"/>
+ <parameter name="something1"> <value val="25.0"/> </parameter>
+ </component>
+
+ <component type="pixel" name="pixel2">
+ <location y="0.0" x="1.0" z="0.0"/>
+ <parameter name="something2"> <value val="15.0"/> </parameter>
+ </component>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+this implies that if you for instance ask the component with
+name="pixel1" what parameters it has then the answer is two:
+something1=25.5 and something=35.0. If you ask the component
+name="dummy" the same question the answer is one: something=35.0 and so
+on. Recursive look-up can be diabled see for instance
+`ParametrizedComponent <http://doxygen.mantidproject.org/classMantid_1_1Geometry_1_1ParametrizedComponent.html>`__.
+
+Using *string*
+~~~~~~~~~~~~~~~
+
+This is a special category of parameters where the value specified for
+the paramter is string rather than a double. The syntax is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="instrument-status" type="string">
+ <value val="closed"/>
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+Using *fitting*
+~~~~~~~~~~~~~~~~
+
+This is a special category of parameters, which follows the same syntax
+as other but allows a few extra features. Fitting parameters are meant
+to be used when raw data are fitted against models that contain
+parameters, where some of these parameters are instrument specific. If
+such parameters are specified these will be pulled in before the fitting
+process starts, where optionally these may, for instance, be specified
+to be treated as fixed by default. To specify a fitting parameter use
+the additional tag type="fitting" as shown in the example below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="IkedaCarpenterPV:Alpha0" type="fitting">
+ <value val="7.2"/>
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+It is required that the parameter name uses the syntax
+NameOfFunction:Parameter, where NameOfFunction is the name of the
+fitting function the parameter is associated with. In the example above
+the fitting function name is `IkedaCarpenterPV <IkedaCarpenterPV>`__ and
+the parameter name is Alpha0.
+
+To specify that a parameter should be treated as fixed in the fitting
+process use the element as demonstrated in the example below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="IkedaCarpenterPV:Alpha0" type="fitting">
+ <value val="7.2"/>
+ <fixed />
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+A parameter can be specified to have a min/max value, which results in a
+constraint being applied to this parameter. An example of this is shown
+below
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="IkedaCarpenterPV:Alpha0" type="fitting">
+ <value val="7.2"/>
+ <min val="4"/> <max val="12"/>
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+The min/max values may also be specified as percentage values. For
+example:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="IkedaCarpenterPV:Alpha0" type="fitting">
+ <value val="250"/>
+ <min val="80%"/> <max val="120%"/>
+ <penalty-factor val="2000"/>
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+results in Alpha0 being constrained to sit between 250\*0.8=200 and
+250\*1.20=300. Further this example also demonstrates how a can be
+specified to tell how strongly the min/max constraints should be
+enforced. The default value for the penalty-factor is 1000. For more
+information about this factor see `FitConstraint <FitConstraint>`__.
+
+A value for a parameter may alternatively be set using a look-up-table
+or a formula. An example demonstrating a formula is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="IkedaCarpenterPV:Alpha0" type="fitting">
+ <formula eq="100.0+10*centre+centre^2" unit="TOF" result-unit="1/dSpacing^2"/>
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+'centre' in the formula is substituted with the centre-value of the peak
+shape function as known prior to the start of the fitting process. The
+attributes 'unit' is optional. If it is not set then the peak
+centre-value is directly substituted for the centre variable in the
+formula. If it is set then it must be set to no one of the units defined
+in `Unit\_Factory <Unit_Factory>`__, and what happens is that the peak
+centre-value is converted to this unit before assigned to the centre
+variable in the formula.
+
+The optional 'result-unit' attribute tells what the unit is of the
+output of the formula. In the example above this unit is "1/dSpacing^2"
+(for the 'result-unit' this attribute can be set to an algebraic
+expression of the units defined in `Unit\_Factory <Unit_Factory>`__). If
+the x-axis unit of the data you are trying to fit is dSpacing then the
+output of the formula is left as it is. But for example if the x-axis
+unit of the data is TOF then the formula output is converted into, it in
+this case, the unit "1/TOF^2". Examples where 'unit' and 'result-unit'
+are used include:
+`CreateBackToBackParameters <CreateBackToBackParameters>`__ and
+`CreateIkedaCarpenterParameters <CreateIkedaCarpenterParameters>`__.
+
+An example which demonstrate using a look-up-table is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <parameter name="IkedaCarpenterPV:Alpha0" type="fitting">
+ <lookuptable interpolation="linear" x-unit="TOF" y-unit="dSpacing">
+ <point x="1" y="1" />
+ <point x="3" y="100" />
+ <point x="5" y="1120" />
+ <point x="10" y="1140" />
+ </lookuptable>
+ </parameter>
+
+.. raw:: html
+
+ </div>
+
+As with a formula the look-up is done for the 'x'-value that corresponds
+to the centre of the peak as known prior to the start of the fitting
+process. The only interpolation option currently supported is 'linear'.
+The optional 'x-unit' and 'y-unit' attributes must be set to one of the
+units defined in `Unit\_Factory <Unit_Factory>`__. The 'x-unit' and
+'y-unit' have very similar effect to the 'unit' and 'result-unit'
+attributes for described above. 'x-unit' converts the unit of the centre
+before lookup against the x-values. 'y-axis' is the unit of the y values
+listed, which for the example above correspond to Alpha0.
+
+Using
+~~~~~~
+
+Allow s to be linked to components without needing s to be defined
+inside, as sub-elements, of the components they belong to. The standard
+approach for defining a parameter is
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="bank" name="bank_90degnew">
+ <location />
+ <parameter name="test"> <value val="50.0" /> </parameter>
+ </component>
+
+.. raw:: html
+
+ </div>
+
+where a parameter 'test' is defined to belong to the component with the
+name 'bank\_90degnew'. However, alternatively the parameter can be
+defined using the notation in the an example below. Note that if more
+than one component e.g. have the name 'bank\_90degnew' then the
+specified parameters are applied to all such components.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="bank" name="bank_90degnew">
+ <location />
+ </component>
+
+ <component-link name="bank_90degnew" >
+ <parameter name="test"> <value val="50.0" /> </parameter>
+ </component-link>
+
+.. raw:: html
+
+ </div>
+
+ is the only way parameters can be defined in a **parameter file** used
+by the `LoadParameterFile <LoadParameterFile>`__ algorithm.
+
+If there are several components with name 'bank\_90degnew' but you want
+specified paramentes to apply to only one of them, then you can specify
+the name by a path name.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component-link name="HRPD/leftside/bank_90degnew" >
+ <parameter name="test"> <value val="50.0" /> </parameter>
+ </component-link>
+
+.. raw:: html
+
+ </div>
+
+The path name need not be complete provided it specifies a unique
+component. Here we drop the instrument name HRPD.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component-link name="leftside/bank_90degnew" >
+ <parameter name="test"> <value val="50.0" /> </parameter>
+ </component-link>
+
+.. raw:: html
+
+ </div>
+
+.
+
+Using
+~~~~~~
+
+The standard way of making up geometric shapes as a collection of parts
+is described here:
+`HowToDefineGeometricShape <HowToDefineGeometricShape>`__. However,
+offers in some circumstances a more convenient way of defining more
+complicated shapes, as for example is the case for the ISIS POLARIS
+instrument. This tag combining components into one shape as demonstrated
+below:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="adjusted cuboid"
+ <location />
+ </component>
+
+ <type name="adjusted cuboid" is="detector">
+ <combine-components-into-one-shape />
+ <component type="cuboid1">
+ <location name="A"/>
+ <!-- "A" translated by y=10 and rotated around x-axis by 90 degrees -->
+ <location name="B" y="10" rot="90" axis-x="1" axis-y="0" axis-z="0" />
+ </component>
+ <algebra val="A : B" />
+
+ <!-- this bounding box is used for this combined into one shape-->
+ <bounding-box>
+ <x-min val="-0.5"/>
+ <x-max val="0.5"/>
+ <y-min val="-5.0"/>
+ <y-max val="10.5"/>
+ <z-min val="-5.0"/>
+ <z-max val="5.0"/>
+ </bounding-box>
+
+ </type>
+
+ <type name="cuboid1" is="detector">
+ <cuboid id="bob">
+ <left-front-bottom-point x="0.5" y="-5.0" z="-0.5" />
+ <left-front-top-point x="0.5" y="-5.0" z="0.5" />
+ <left-back-bottom-point x="-0.5" y="-5.0" z="-0.5" />
+ <right-front-bottom-point x="0.5" y="5.0" z="-0.5" />
+ </cuboid>
+
+ <!-- this bounding box is not used in the combined shape -->
+ <!-- Note you would not normally need to add a bounding box
+ for a single cuboid shape. The reason for adding one
+ here is just to illustrate that a bounding added here
+ will not be used in created a combined shape as in
+ "adjusted cuboid" above -->
+ <bounding-box>
+ <x-min val="-0.5"/>
+ <x-max val="0.5"/>
+ <y-min val="-5.0"/>
+ <y-max val="5.0"/>
+ <z-min val="-0.5"/>
+ <z-max val="0.5"/>
+ </bounding-box>
+ </type>
+
+.. raw:: html
+
+ </div>
+
+which combines two components "A" and "B" into one shape. The resulting
+shape is shape is shown here:\ |CombineIntoOneShapeExample.png‎|.
+
+Note for this to work, a unique name for each component must be provided
+and these names must be used in the algebra sting (here "A : B", see
+`HowToDefineGeometricShape <HowToDefineGeometricShape>`__). Further a
+bounding-box may optionally be added to the to the type , see
+`HowToDefineGeometricShape#Bounding-Box <HowToDefineGeometricShape#Bounding-Box>`__.
+Note the above geometric shape can alternatively be defined with the XML
+(Mantid behind the scene translates the above XML to the XML below
+before proceeding):
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="adjusted cuboid">
+ <location />
+ </component>
+
+ <type name="adjusted cuboid" is="detector">
+ <cuboid id="A">
+ <left-front-bottom-point x="0.5" y="-5.0" z="-0.5" />
+ <left-front-top-point x="0.5" y="-5.0" z="0.5" />
+ <left-back-bottom-point x="-0.5" y="-5.0" z="-0.5" />
+ <right-front-bottom-point x="0.5" y="5.0" z="-0.5" />
+ </cuboid>
+ <!-- cuboid "A" translated along y by 10 and rotated around x by 90 degrees -->
+ <cuboid id="B">
+ <left-front-bottom-point x="0.5" y="10.5" z="-5.0" />
+ <left-front-top-point x="0.5" y="9.5" z="-5.0" />
+ <left-back-bottom-point x="-0.5" y="9.5" z="-5.0" />
+ <right-front-bottom-point x="0.5" y="10.5" z="5.0" />
+ </cuboid>
+ <algebra val="A : B" />
+ </type>
+
+.. raw:: html
+
+ </div>
+
+ for now works only for combining cuboids. Please do not hesitate to
+contact the Mantid team if you would like to extend this.
+
+This applies when defining any geometric shape, but perhaps something
+which a user has to be in particular aware of when defining more
+complicated geometry shapes, for example, using the tag: the coordinate
+system in which a shape is defined can be chosen arbitrary, and the
+origin of this coordinate system is the position returned when a user
+asked for its position. It is therefore highly recommended that when a
+user define a detector geometric shape, this could be simple cuboid,
+that it is defined with the origin at the centre of the front of the
+detector. For detector shapes build up of for example multiple cuboids
+the origin should be chosen perhaps for the center of the front face of
+the 'middle' cuboid. When Mantid as for the position of such a shape it
+will be with reference to coordinate system origin of the shape.
+However, sometimes it may simply be inconvenient to build up a geometry
+shape with an coordinate system as explained above. For this case, and
+for now only when using it possible to get around this by using the
+element , which takes the same attributes as a element. The effect of
+this element is basically to redefine the shape coordinate system origin
+(in fact also rotate it if requested).
+
+Using
+~~~~~~
+
+Used for setting various defaults.
+
+Used to make the xy-plane of the geometric shape of any component by
+default face a given location. For example
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <components-are-facing x="0.0" y="0.0" z="0.0" />
+
+.. raw:: html
+
+ </div>
+
+If this element is not specified the default is to *not* attempt to
+apply facing.
+
+Originally introduced to handle detector position coordinates as defined
+by the
+`Ariel <http://www.isis.rl.ac.uk/Disordered/GEM/ariel/index_ariel.htm>`__
+software.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <offsets spherical="delta" />
+
+.. raw:: html
+
+ </div>
+
+When this is set all components which have coordinates specified using
+spherical coordinates (i.e. using the r, t, p attributes, see
+description of ) are then treated as offsets to the spherical position
+of the parent, i.e. the value given for :math:`r` are added to the
+parent's :math:`r` to give the total radial coordinate, and the same for
+:math:`\theta` and :math:`\phi`. Note using this option breaks the
+symmetry that the element of a child component equals the position of
+this component relative to its parent component.
+
+Reference frame in which instrument is described. The author/reader of
+an IDF can chose the reference coordinate system in which the instrument
+is described. The default reference system is the one shown below.
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <reference-frame>
+ <!-- The z-axis is set parallel to and in the direction of the beam. the
+ y-axis points up and the coordinate system is right handed. -->
+ <along-beam axis="z"/>
+ <pointing-up axis="y"/>
+ <handedness val="right"/>
+ </reference-frame>
+
+.. raw:: html
+
+ </div>
+
+This reference frame is e.g. used when a signed theta detector values
+are calculated where it is needed to know which direction is defined as
+up. The direction here means the direction of the beam if it was not
+modified by any mirrows etc.
+
+This tag is used to control how the instrument first appears in the
+`Instrument View <MantidPlot:_Instrument_View>`__. Attribute ``view``
+defines the type of the view that opens by default. It can have the
+following values: "3D", "cylindrical\_x", "cylindrical\_y",
+"cylindrical\_z", "spherical\_x", "spherical\_y", "spherical\_z". If the
+attribute is omitted value "3D" is assumed. Opening the 3D view on
+start-up is also conditioned on the value of the
+``MantidOptions.InstrumentView.UseOpenGL`` property in the `Properties
+File <Properties_File>`__. If set to "Off" this property prevents the
+Instrument View to start in 3D mode and "cylindrical\_y" is used
+instead. The user can change to 3D later.
+
+Another attribute, ``axis-view`` governs on which axis the instrument is
+initially viewed from in 3D and can be set equal to one of "Z-", "Z+",
+"X-", etc. If "Z-" were selected then the view point would be on the
+z-axis on the negative of the origin looking in the +z direction.
+
+If
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <angle unit="radian"/>
+
+.. raw:: html
+
+ </div>
+
+is set then all angles specified in elements and 's with names "rotx",
+"roty", "rotz", "t-position" and "p-position" are assumed to in radians.
+The default is to assume all angles are specified in degrees.
+
+Other defaults
+^^^^^^^^^^^^^^
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <length unit="meter"/>
+
+.. raw:: html
+
+ </div>
+
+This default, for now, does not do anything, but is the default unit for
+length used by Mantid. If it would be useful for you to specify user
+defined units do not hesitate to `request
+this <mailto:mantid-help@mantidproject.org>`__.
+
+Parameter Files
+---------------
+
+To prevent an IDF file from getting too long and complicated,
+information not related to the geometry of the instrument may be put
+into a separate file, whose content is automatically included into the
+IDF file.
+
+For more information see the **`parameter file
+page <InstrumentParameterFile>`__**.
+
+Deprecated Features
+-------------------
+
+=== mark-as="monitor" === The following notation to mark a detector as a
+monitor is now deprecated:
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="monitor" idlist="monitor">
+ <location r="3.25800" t="180.0" p="0.0" mark-as="monitor"/>
+ </component>
+
+ <type name="monitor" is="detector"/>
+
+ <idlist idname="monitor">
+ <id val="11" />
+ </idlist>
+
+.. raw:: html
+
+ </div>
+
+The above XML should be replaced with
+
+.. raw:: html
+
+ <div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
+
+.. code:: xml
+
+ <component type="monitor" idlist="monitor">
+ <location r="3.25800" t="180.0" p="0.0"/>
+ </component>
+
+ <type name="monitor" is="monitor"/>
+
+ <idlist idname="monitor">
+ <id val="11" />
+ </idlist>
+
+.. raw:: html
+
+ </div>
+
+
+
+.. |CombineIntoOneShapeExample.png‎| image:: CombineIntoOneShapeExample.png‎
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Instrument_Data_Service.rst b/Code/Mantid/docs/source/concepts/Instrument_Data_Service.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8acf9cbeffeee6c6b3a5268b764d917d6bd78957
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Instrument_Data_Service.rst
@@ -0,0 +1,33 @@
+.. _Instrument Data Service:
+
+Instrument_Data_Service
+=======================
+
+What is it?
+-----------
+
+The Instrument Data Service (IDS) is a `Data Service <Data Service>`__
+that is specialized to hold all of the `instruments <Instrument>`__ that
+are created during a user session. Whenever an instrument definition is
+loaded it is saved in the IDS and further workspaces that refer to the
+same instrument share the same definition.
+
+Extracting an instrument from the Instrument Data Service
+---------------------------------------------------------
+
+This is rarely something that a user or an algorithm writer would need
+to do as it is all handled by the framework internals. Normally you
+would access the instrument relating to a workspace directly though that
+workspace.
+
+``workspace->getInstrument();``
+
+However if you really did want to access the instrument from the IDS (as
+a `Shared Pointer <Shared Pointer>`__), although this would then lack
+any workspace specific alterations or properties.
+
+``boost::shared_ptr``\ \ `` intrument = workspace->getInstrument();``
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Lattice.rst b/Code/Mantid/docs/source/concepts/Lattice.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1d955201ca5f22ac3d0a78bf481a2167caf7903a
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Lattice.rst
@@ -0,0 +1,265 @@
+.. _Lattice:
+
+Lattice
+=======
+
+.. role:: math(raw)
+ :format: html latex
+..
+
+The purpose of this document is to explain how Mantid is using
+information about unit cells and their orientation with respect to the
+laboratory frame. For a detailed description, see
+http://github.com/mantidproject/documents/blob/master/Design/UBMatriximplementationnotes.pdf
+
+Theory
+------
+
+The physics of a system studied by neutron scattering is described by
+the conservation of energy and momentum. In the laboratory frame:
+
+:math:`Q_l= \hbar \mathbf{k}_i^{} - \hbar \mathbf{k}_f`
+
+:math:`\Delta E_l= \frac{\hbar^2}{2m} (k_i^2 - k_f^2)`
+
+Note that the left side in the above equations refer to what is
+happening to the lattice, not to the neutron.
+
+Let's assume that we have a periodic lattice, described by lattice
+parameters :math:`a,\ b,\ c,\ \alpha,\ \beta,\ \gamma`. The reciprocal
+lattice will be described by parameters
+:math:`a^*,\ b^*,\ c^*,\ \alpha^*,\ \beta^*,\ \gamma^*`. Note that
+Mantid uses :math:`a^*=\frac{1}{a}` type of notation, like in
+crystallography.
+
+For such a lattice, the physics will be described in terms of reciprocal
+lattice parameters by
+:math:`Q= 2 \pi\left(h \mathbf{a}^* + k \mathbf{b}^* +l \mathbf{c}^* \right) = \left(\begin{array}{c}
+
+ h \\
+
+ k \\
+
+ l
+
+ \end{array}\right)`.
+The :math:`UB_{}^{}` matrix formalism relates :math:`Q_l^{}` and
+:math:`Q_{}^{}` with the following equation:
+
+:math:`Q_l = 2 \pi R \cdot U \cdot B \left(\begin{array}{c}
+
+ h \\
+
+ k \\
+
+ l
+
+ \end{array}\right)`
+
+The :math:`B_{}^{}` matrix transforms the :math:`h^{}_{}, k, l` triplet
+into a Cartesian system, with the first axis along
+:math:`\ \mathbf{a}^*`, the second in the plane defined by
+:math:`\ \mathbf{a}^*` and :math:`\ \mathbf{b}^*`, and the third axis
+perpendicular to this plane. In the Busing and Levi convention (W. R.
+Busing and H. A. Levy, Angle calculations for 3- and 4-circle X-ray and
+neutron diffractometers - Acta Cryst. (1967). 22, 457-464):
+
+:math:`B = \left( \begin{array}{ccc}
+ a^* & b^*\cos(\gamma^*) & c^*\cos(\beta^*) \\
+ 0 & b^*\sin(\gamma^*) & -c^*\sin(\beta^*)\cos(\alpha) \\
+ 0 & 0 & 1/c \end{array} \right)`
+
+The :math:`U_{}^{}` matrix represents the rotation from this Cartesian
+coordinate frame to the Cartesian coordinate frame attached to the
+innermost axis of the goniometer that holds the sample.
+
+The :math:`R_{}^{}` matrix is the rotation matrix of the goniometer
+
+Other useful equations:
+
+:math:`G^* = (UB)^T UB = B^T B = \left( \begin{array}{ccc}
+ a^*a^* & a^*b^*\cos(\gamma^*) & a^*c^*\cos(\beta^*) \\
+ a^*b^*\cos(\gamma^*) & b^*b^* & b^*c^*\cos(\alpha^*) \\
+ a^*c^*\cos(\beta^*) & b^*c^*\cos(\alpha^*) & c^*c^* \end{array} \right)`
+
+:math:`G=(G^*)^{-1}=\left( \begin{array}{ccc}
+ aa & ab\cos(\gamma) & ac\cos(\beta) \\
+ ab\cos(\gamma) & bb & bc\cos(\alpha) \\
+ ac\cos(\beta) & bc\cos(\alpha) & cc \end{array} \right)`
+
+The distance in reciprocal space to the :math:`\left(h,k,l\right)` plane
+is given by :math:`d^* =\left| B \left(\begin{array}{c}
+
+ h \\
+
+ k \\
+
+ l
+
+ \end{array}\right)\right|`
+
+The distance in real space to the :math:`\left(h,k,l\right)` plane is
+given by :math:`d=\frac{1}{d^*}`
+
+The angle between :math:`Q_1^{}` and :math:`Q_2^{}` is given by
+:math:`\cos( Q_1^{}, Q_2^{})=\frac{(BQ_1)(BQ_2)}{|(BQ_1)| |(BQ_2)|}`
+
+Unit cells
+----------
+
+The UnitCell class provides the following functions to access direct and
+reciprocal lattices. The examples can be run from the script console in
+Mantid
+
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Function | Example | Description |
++================================================+=================================================================================+================================================================================================================================================================================================================================================================================================================================+
+| UnitCell() | u = UnitCell() | default constructor, with :math:`a=b=c=1\rm \AA, \ \alpha=\beta=\gamma=90^\circ` |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| UnitCell(other unit cell) | | u = UnitCell() | copy constructor |
+| | | u2 = UnitCell(u) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| UnitCell(a,b,c) | u = UnitCell(2,3.5,4) | constructor using :math:`a, b, c\ (\rm {in \ \AA}), \ \alpha=\beta=\gamma=90^\circ` |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| UnitCell(a,b,c,alpha,beta,gamma,Unit = unit) | | u = UnitCell(2,3.5,4,90,90,90) | constructor using :math:`a, b, c\ (\rm {in \ \AA}), \ \alpha, \ \beta,\ \gamma \ (\rm {in \ degrees \ or \ radians})`. The optional parameter "Unit" controls the units for the angles, and can have the value of "Degrees" or "Radians". By default Unit = Degrees |
+| | | u = UnitCell(2,3.5,4,90,90,90,Unit = Degrees) | |
+| | | u = UnitCell(2,3.5,4,0.5\*math.pi,0.5\*math.pi,0.5\*math.pi,Unit = Radians) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | a() | | u = UnitCell(2,3.5,4) | returns lattice parameters :math:`a, b, c\ (\rm {in \ \AA})` |
+| | b() | | print u.c() | |
+| | c() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | a1() | | u = UnitCell(2,3.5,4) | returns lattice parameters :math:`a_1=a, a_2=b, a_3=c\ (\rm {in \ \AA})`. Note: `"International Tables for Crystallography" <http://it.iucr.org/Ba/ch1o1v0001/>`__ notation |
+| | a2() | | print u.a2() | |
+| | a3() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | alpha() | | u = UnitCell(2,3.5,4,95,95,105) | returns lattice parameters :math:`\alpha,\ \beta, \gamma\ (\rm {in \ degrees})` |
+| | beta() | | print u.alpha() | |
+| | gamma() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | alpha1() | | u = UnitCell(2,2,4,90,90,60) | returns lattice parameters :math:`\alpha_1=\alpha,\ \alpha_2=\beta, \ \alpha_3=\gamma \ (\rm {in \ radians})`. Note: `"International Tables for Crystallography" <http://it.iucr.org/Ba/ch1o1v0001/>`__ notation |
+| | alpha2() | | print u.alpha3() | |
+| | alpha3() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | astar() | | u = UnitCell(2,3.5,4) | returns reciprocal lattice parameters :math:`a^*, b^*, c^* \ (\rm {in \ \AA^{-1}})` |
+| | bstar() | | print u.cstar() | |
+| | cstar() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | b1() | | u = UnitCell(2,3.5,4) | returns lattice parameters :math:`b_1=a^*, b_2=b^*, b_3=c^*\ (\rm {in \ \AA^{-1}})`. Note: `"International Tables for Crystallography" <http://it.iucr.org/Ba/ch1o1v0001/>`__ notation |
+| | b2() | | print u.b2() | |
+| | b3() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | alphastar() | | u = UnitCell(2,3.5,4,95,95,105) | returns lattice parameters :math:`\alpha^*,\ \beta^*, \gamma^*\ (\rm {in \ degrees})` |
+| | betastar() | | print u.alphastar() | |
+| | gammastar() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | beta1() | | u = UnitCell(2,2,4,90,90,60) | returns lattice parameters :math:`\beta_1=\alpha^*,\ \beta_2=\beta^*, \ \beta_3=\gamma^* \ (\rm {in \ radians})`. Note: `"International Tables for Crystallography" <http://it.iucr.org/Ba/ch1o1v0001/>`__ notation |
+| | beta2() | | print u.beta3() | |
+| | beta3() | | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| set(a,b,c,alpha,beta,gamma,Unit=unit) | | u = UnitCell() | sets :math:`a, b, c\ (\rm {in \ \AA}), \ \alpha, \ \beta,\ \gamma \ (\rm {in \ degrees \ or \ radians})` values. The optional parameter "Unit" controls the units for the angles, and can have the value of "Degrees" or "Radians". By default Unit = Degrees |
+| | | u.set(2,3.5,4,90,90,90) | |
+| | | u.set(2,3.5,4,90,90,90,Unit = Degrees) | |
+| | | u.set(2,3.5,4,0.5\*math.pi,0.5\*math.pi,0.5\*math.pi,Unit = Radians) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | seta(a) | | u = UnitCell(2,3.5,4) | sets lattice parameters :math:`a, b, c\ (\rm {in \ \AA})` |
+| | setb(b) | | u.setc(5) | |
+| | setc(c) | | print u.c() | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | setalpha(alpha,Unit=unit) | | u = UnitCell() | sets :math:`\alpha, \ \beta,\ \gamma \ (\rm {in \ degrees \ or \ radians})` values. The optional parameter "Unit" controls the units for the angles, and can have the value of "Degrees" or "Radians". By default Unit = Degrees |
+| | setbeta(beta,Unit=unit) | | u.setalpha(88) | |
+| | setgamma(gamma,Unit=unit) | | u.setbeta(95,Unit = Degrees) | |
+| | | u.setgamma(0.5\*math.pi,Unit = Radians) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | d(h,k,l) | | u = UnitCell(2,3.5,4) | returns :math:`d^{}_{}`-spacing :math:`(\rm in \ \rm \AA)` for given h,k,l coordinates |
+| | d(V3D vector) | | print u.d(1,1,1) | |
+| | | print u.d(V3D(1,1,1)) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | dstar(h,k,l) | | u = UnitCell(2,3.5,4) | returns :math:`d^*=1/d \ (\rm in \ \rm \AA^{-1})` for given h,k,l coordinates |
+| | dstar(V3D vector) | | print u.dstar(1,1,1) | |
+| | | print u.dstar(V3D(1,1,1)) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| recAngle(h1,k1,l1,h2,k2,l2,Unit=unit) | | u = UnitCell(2,3.5,4) | returns the angle in reciprocal space between vectors given by :math:`\left(h_1, k_1, l_1\right)` and :math:`\left(h_2, k_2, l_2\right) \ (\rm {in \ degrees \ or \ radians})`. The optional parameter "Unit" controls the units for the angles, and can have the value of "Degrees" or "Radians". By default Unit = Degrees |
+| | | print u.recAngle(1,0,0,1,1,0) | |
+| | | print u.recAngle(1,0,0,1,1,1,Unit=Degrees) | |
+| | | print u.recAngle(1,0,0,1,1,0,Unit = Radians) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | volume() | | u = UnitCell(2,3.5,4) | return the volume of the direct or reciprocal unit cell :math:`(\rm {in \ \AA^3 \ respectively \ \AA^{-3}})` |
+| | recVolume() | | print u.volume() | |
+| | | print u.recVolume() | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | getB() | | u = UnitCell(2,3.5,4) | return the :math:`B^{}_{}` and :math:`B^{-1}_{}` matrices |
+| | getBinv() | | print u.getB() | |
+| | | print u.getBinv() | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | getG() | | u = UnitCell(2,3.5,4) | return the :math:`G^{}_{}` and :math:`G^{*}_{}` metric tensors of the direct and reciprocal lattices |
+| | getGstar() | | print u.getG() | |
+| | | print u.getGstar() | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| recalculateFromGstar(Gstar 2D 3x3 array) | | newGstar=array([[2,0,0],[0,0.5,0],[0,0,1]]) | recalculates the lattice parameters from the new :math:`G^{*}_{}` and sets them to the current UnitCell object |
+| | | u=UnitCell() | |
+| | | u.recalculateFromGstar(newGstar) | |
++------------------------------------------------+---------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Oriented lattices
+-----------------
+
+All the functions defined for UnitCell are inherited by the
+OrientedLattice objects. In addition, the following functions are
+defined for OrientedLattice only:
+
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Function | Example | Description |
++=======================================================+========================================================================================+=================================================================================================================================================================================================================================================================================================================================================+
+| OrientedLattice() | o = OrientedLattice() | default constructor, with :math:`a=b=c=1\rm \AA, \ \alpha=\beta=\gamma=90^\circ`. The :math:`U^{}_{}` matrix is set to identity |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| OrientedLattice(other oriented lattice) | | o = OrientedLattice() | copy constructor |
+| | | o2 = OrientedLattice(o) | |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| OrientedLattice(a,b,c) | o = OrientedLattice(2,3.5,4) | constructor using :math:`a, b, c\ (\rm {in \ \AA}), \ \alpha=\beta=\gamma=90^\circ`. The :math:`U^{}_{}` matrix is set to identity |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| OrientedLattice(a,b,c,alpha,beta,gamma,Unit = unit) | | o = OrientedLattice(2,3.5,4,90,90,90) | constructor using :math:`a, b, c\ (\rm {in \ \AA}), \ \alpha, \ \beta,\ \gamma \ (\rm {in \ degrees \ or \ radians})`. The optional parameter "Unit" controls the units for the angles, and can have the value of "Degrees" or "Radians". By default Unit = Degrees. The :math:`U^{}_{}` matrix is set to identity |
+| | | o = OrientedLattice(2,3.5,4,90,90,90,Unit = Degrees) | |
+| | | o = OrientedLattice(2,3.5,4,0.5\*math.pi,0.5\*math.pi,0.5\*math.pi,Unit = Radians) | |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| OrientedLattice(unit cell) | | u=UnitCell(2,3,4) | constructor from UnitCell. The :math:`U^{}_{}` matrix is set to identity |
+| | | o = OrientedLattice(u) | |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | getU() | | o.OrientedLattice(2,3.5,4) | return the :math:`U^{}_{}` and :math:`UB^{}_{}` matrices |
+| | getUB() | | print u.getU() | |
+| | | print u.getUB() | |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | setU() | | o.OrientedLattice(2,3.5,4) | sets the :math:`U^{}_{}` and :math:`UB^{}_{}` matrices. for setUB function, it will calculate first the lattice parameters, then the :math:`B^{}_{}` matrix, and then :math:`U^{}_{}`. See `#Note about orientation <#Note_about_orientation>`__ |
+| | setUB() | | newU=array([[0,1,0],[1,0,0],[0,0,-1]]) | |
+| | | o.setU(newU) | |
+| | | newUB=array([[2,1,0],[1,2,0],[2,0,-1]]) | |
+| | | o.setUB(newUB) | |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| setUFromVectors(v1,v2) | | o.OrientedLattice(2,3.5,4) | recalculates and sets the :math:`U^{}_{}` matrix, such as the first vector is along the beam direction, and the second vector is in the horizontal plane. See `#Note about orientation <#Note_about_orientation>`__. In python, the v1 and v2 vectors can be of type V3D, or length 3 list, or length 3 numpy array, not necessarily the same |
+| | | o.setUFromVectors([1,0,0],[0,1,0]) | |
+| | | o.setUFromVectors(array([1,0,0]),array([0,1,0])) | |
+| | | o.setUFromVectors(V3D(1,0,0),V3D(0,1,0)) | |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| | getuVector() | | o.OrientedLattice(2,3.5,4) | getuVector returns a vector along beam direction, while getvVector returns a vector in the horizontal plane, perpendicular to the beam direction (see `http://horace.isis.rl.ac.uk/Getting_started <http://horace.isis.rl.ac.uk/Getting_started>`__). See `#Note about orientation <#Note_about_orientation>`__ |
+| | getvVector() | | o.setUFromVectors([5,5,0],[-2,1,0]) | |
+| | | print o.getuVector() | |
+| | | print o.getvVector() | |
++-------------------------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Note about orientation
+----------------------
+
+Most of the instruments have incident beam along the :math:`\mathbf{z}`
+direction. For an orthogonal lattice with :math:`\mathbf{a}^*` along
+:math:`\mathbf{z}`, :math:`\mathbf{b}^*` along :math:`\mathbf{x}`, and
+:math:`\mathbf{c}^*` along :math:`\mathbf{y}`, the :math:`U^{}_{}`
+matrix has the form:
+
+:math:`U = \left( \begin{array}{ccc}
+ 0 & 1 & 0 \\
+ 0 & 0 & 1 \\
+ 1 & 0 & 0 \end{array} \right)`
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/MDHistoWorkspace.rst b/Code/Mantid/docs/source/concepts/MDHistoWorkspace.rst
new file mode 100644
index 0000000000000000000000000000000000000000..622926d68137688bfe5e2f2982a5025180909ff4
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/MDHistoWorkspace.rst
@@ -0,0 +1,131 @@
+.. _MDHistoWorkspace:
+
+MDHistoWorkspace
+================
+
+The MDHistoWorkspace is a simple multi-dimensional workspace. In
+contrast to the `MDEventWorkspace <MDEventWorkspace>`__, which contains
+points in space, the MDHistoWorkspace consists of a signal and error
+spread around space on a regular grid.
+
+In a way, the MDHistoWorkspace is to a
+`MDEventWorkspace <MDEventWorkspace>`__ is what the
+`Workspace2D <Workspace2D>`__ is to the
+`EventWorkspace <EventWorkspace>`__.
+
+Creating a MDHistoWorkspace
+---------------------------
+
+MDHistoWorkspaces typically have 3 or 4 dimensions, although they can be
+created in up to 9 dimensions.
+
+- You can bin a `MDEventWorkspace <MDEventWorkspace>`__ to a
+ MDHistoWorkspace using the `BinMD <BinMD>`__ algorithm.
+
+ - You can use `CreateMDWorkspace <CreateMDWorkspace>`__ to create a
+ blank MDEventWorkspace first, if you do not have data to bin.
+
+- `Paraview <Paraview>`__ and the `Vates Simple
+ Interface <VatesSimpleInterface>`__ will create a MDHistoWorkspace
+ from a `MDWorkspace <MDWorkspace>`__ when rebinning on a regular
+ grid.
+
+Viewing a MDHistoWorkspace
+--------------------------
+
+- MDHistoWorkspaces can be created and visualized directly within
+ `Paraview <Paraview>`__ and the `Vates Simple
+ Interface <VatesSimpleInterface>`__ when rebinning along a regular
+ grid.
+- You can right-click on the workspace and select:
+
+ - **Plot MD**: to perform a 1D plot of the signal in the workspace
+ (only works on 1D MDHistoWorkspaces).
+ - **Show Slice Viewer**: to open the `Slice
+ Viewer <MantidPlot:_SliceViewer>`__, which shows 2D slices of the
+ multiple-dimension workspace.
+
+Arithmetic Operations
+---------------------
+
+The following algorithms allow you to perform simple arithmetic on the
+values:
+
+- `MinusMD <MinusMD>`__, `PlusMD <PlusMD>`__, `DivideMD <DivideMD>`__,
+ `MultiplyMD <MultiplyMD>`__
+- `ExponentialMD <ExponentialMD>`__, `PowerMD <PowerMD>`__,
+ `LogarithmMD <LogarithmMD>`__
+
+These arithmetic operations propagate errors as described
+`here <http://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas>`__.
+The formulas used are described in each algorithm's wiki page.
+
+The basic arithmetic operators are available from python. For example:
+
+| ``# Get two workspaces``
+| ``AÂ =Â mtd['workspaceA']``
+| ``BÂ =Â mtd['workspaceB']``
+| ``# Creating a new workspace``
+| ``CÂ =Â AÂ +Â B``
+| ``CÂ =Â AÂ -Â B``
+| ``CÂ =Â AÂ *Â B``
+| ``CÂ =Â AÂ /Â B``
+| ``# Modifying a workspace in-place``
+| ``CÂ +=Â A``
+| ``CÂ -=Â A``
+| ``CÂ *=Â A``
+| ``CÂ /=Â A``
+| ``# Operators with doubles``
+| ``CÂ =Â AÂ *Â 12.3``
+| ``CÂ *=Â 3.45``
+
+Compound arithmetic expressions can be made, e.g:
+
+``EÂ =Â (AÂ -Â B)Â /Â (CÂ -Â D)``
+
+Boolean Operations
+~~~~~~~~~~~~~~~~~~
+
+The MDHistoWorkspace can be treated as a boolean workspace. In this
+case, 0.0 is "false" and 1.0 is "true".
+
+The following operations can create a boolean MDHistoWorkspace:
+
+- `LessThanMD <LessThanMD>`__, `GreaterThanMD <GreaterThanMD>`__,
+ `EqualToMD <EqualToMD>`__
+
+These operations can combine/modify boolean MDHistoWorkspaces:
+
+- `NotMD <NotMD>`__, `AndMD <AndMD>`__, `OrMD <OrMD>`__,
+ `XorMD <XorMD>`__
+
+These boolean operators are available from python. Make sure you use the
+bitwise operators: & \| ^ ~ , not the "word" operators (and, or, not).
+For example:
+
+| ``# Create boolean workspaces by comparisons``
+| ``CÂ =Â AÂ >Â B``
+| ``DÂ =Â BÂ <Â 12.34``
+| ``# Combine boolean workspaces using not, or, and, xor:``
+| ``not_CÂ =Â ~C``
+| ``C_or_DÂ =Â CÂ |Â D``
+| ``C_and_DÂ =Â CÂ &Â D``
+| ``C_xor_DÂ =Â CÂ ^Â D``
+| ``CÂ |=Â D``
+| ``CÂ &=Â D``
+| ``CÂ ^=Â D``
+
+| ``# Compound expressions can be used:``
+| ``DÂ =Â (AÂ >Â 123)Â &Â (AÂ >Â B)Â &Â (AÂ <Â 456)``
+
+Using Boolean Masks
+^^^^^^^^^^^^^^^^^^^
+
+The `SetMDUsingMask <SetMDUsingMask>`__ algorithm allows you to modify
+the values in a MDHistoWorkspace using a mask created using the boolean
+operations above. See the `algorithm wiki page <SetMDUsingMask>`__ for
+more details.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/MDWorkspace.rst b/Code/Mantid/docs/source/concepts/MDWorkspace.rst
new file mode 100644
index 0000000000000000000000000000000000000000..804a8434a6d692bad267e8a152f93eeece67a3d5
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/MDWorkspace.rst
@@ -0,0 +1,106 @@
+.. _MDWorkspace:
+
+MDWorkspace
+===========
+
+The MDWorkspace (short for "Multi-Dimensional" Workspace) is a generic
+data structure holdings points (MDEvents) that are defined by their
+position in several dimensions. See also
+`MDHistoWorkspace <MDHistoWorkspace>`__.
+
+Description of MDWorkspace
+--------------------------
+
+- **Dimensions**: A MDWorkspace can have between 1 and 9 dimensions.
+
+ - Each dimension is defined with a name, units, and minimum/maximum
+ extents.
+
+- **MDEvent**: A MDEvent is simply a point in space defined by its
+ coordinates, plus a signal (weight) and error.
+
+ - The MDLeanEvent type contains only coordinates, signal and error.
+ - The MDEvent type also contains a run index (for multiple runs
+ summed into one workspace) and a detector ID, allowing for more
+ information to be extracted.
+
+- The class is named MDEventWorkspace.
+
+Structure
+~~~~~~~~~
+
+The MDWorkspace is a container that can hold a large number of MDEvents.
+The events are organized into "boxes": types are MDBox and MDGridBox. At
+the simplest level, an MDWorkspace will be a single MDBox with an
+unsorted bunch of events.
+
+In order to allow for efficient searching and binning of these events,
+the boxes are organized into a recursive boxing structure (adaptive mesh
+refinement). During MDWorkspace construction, if a MDBox is found to
+contain too many events, it will be split into smaller boxes.
+
+.. figure:: MDWorkspace_structure.png
+ :alt: MDWorkspace_structure.png
+
+ MDWorkspace\_structure.png
+The threshold for splitting is defined in
+`CreateMDWorkspace <CreateMDWorkspace>`__ as the SplitThreshold
+parameter. Each parent box will get split into N sub-boxes in each
+dimension. For example, in a 2D workspace, you might split a parent box
+into 4x4 sub-boxes, creating 16 MDBoxes under the parent box (which
+becomes a MDGridBox). The level of splitting is defined in the SplitInto
+parameter.
+
+Creating a MDWorkspace
+----------------------
+
+There are several algorithms that will create a MDWorkspace:
+
+- `CreateMDWorkspace <CreateMDWorkspace>`__ creates a blank MDWorkspace
+ with any arbitrary set of dimensions.
+- `ConvertToDiffractionMDWorkspace <ConvertToDiffractionMDWorkspace>`__
+ converts an `EventWorkspace <EventWorkspace>`__ or
+ `Workspace2D <Workspace2D>`__ from detector space to reciprocal
+ space, for elastic single-crystal or powder diffraction experiments.
+- `ConvertToMDEvents <ConvertToMDEvents>`__ converts workspaces for
+ inelastic experiments.
+- `SliceMD <SliceMD>`__ takes a slice out of a MDWorkspace to create a
+ new one.
+- `LoadSQW <LoadSQW>`__ converts from the SQW format.
+
+File-Backed MDWorkspaces
+------------------------
+
+For workspaces with a large number of events that would not fit in
+memory, it is possible to use a NXS file back-end as a data store. The
+box structure will always remain in memory, but the underlying events
+will be stored in a file and retrieved only when required. This can be
+set at creation (`CreateMDWorkspace <CreateMDWorkspace>`__) or when
+loading from a file, or an in-memory MDWorkspace can be converted to
+file-backed with the `SaveMD <SaveMD>`__ algorithm.
+
+Because of disk IO, file-backed MDWorkspaces are slower to process for
+some operations (e.g. binning or slicing). Some types of visualization
+and analysis, however, are just as fast with file-backed MDWorkspaces as
+their in-memory equivalent.
+
+Viewing MDWorkspaces
+--------------------
+
+- Right-click on a MDWorkspace and select:
+
+ - **Show Vates Simple Interface**: to open a `simplified 3D
+ view <VatesSimpleInterface>`__ based on `Paraview <Paraview>`__.
+ - **Show Slice Viewer**: to open the `Slice
+ Viewer <MantidPlot:_SliceViewer>`__, which shows 2D slices of the
+ multiple-dimensional workspace.
+
+- You can also `use Python script to open the
+ SliceViewer <SliceViewer Python Interface>`__.
+
+Or, you can load a MDWorkspace .nxs file in `Paraview <Paraview>`__ if
+the proper plugin is installed.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/MatrixWorkspace.rst b/Code/Mantid/docs/source/concepts/MatrixWorkspace.rst
new file mode 100644
index 0000000000000000000000000000000000000000..95e58ef449f5775a5b45f09cc4e7be0340798b75
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/MatrixWorkspace.rst
@@ -0,0 +1,41 @@
+.. _MatrixWorkspace:
+
+MatrixWorkspace
+===============
+
+What information is in a MatrixWorkspace
+----------------------------------------
+
+Mandatory:
+
+- Measured or derived data with associated errors
+
+Optionally:
+
+- `Axes <Interacting_with_Workspaces#Axes>`__ with
+ `Units <Unit Factory>`__
+- Sample and sample environment data
+- Run logs
+- A full `instrument <instrument>`__ geometric definition, along with
+ an instrument parameter map
+- A spectra - detector map
+- A distribution flag
+- A list of 'masked' bins
+
+Concrete Matrix Workspaces
+--------------------------
+
+- WorkspaceSingleValue - Holds a single number (and X & error value, if
+ desired). Mainly used for workspace algebra, e.g. to divide all bins
+ in a 2D workspace by a single value.
+- `Workspace2D <Workspace2D>`__ - A workspace for holding two
+ dimensional data in memory. This is the most commonly used workspace.
+- `EventWorkspace <EventWorkspace>`__ - A workspace that retains the
+ individual neutron event data.
+
+More information on working with them: `Interacting with Matrix
+Workspaces <Interacting with Matrix Workspaces>`__.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Nexus_file.rst b/Code/Mantid/docs/source/concepts/Nexus_file.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6b233d12d9ab427b67ffde74719670abad84c13c
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Nexus_file.rst
@@ -0,0 +1,26 @@
+.. _Nexus file:
+
+Nexus_file
+==========
+
+A **Nexus file** is a type of data file used by ISIS traget station 2
+and by MantidPlot. The format appears to be like an XML file plus some
+unprintable characters.
+
+ManditPlot is capable of saving certain types of
+`workspace <workspace>`__ as a Nexus file. It can also save a
+`project <project>`__ as a mantid file plus Nexus files.
+
+Structure
+---------
+
+To be completed.
+
+See also
+--------
+
+`RAW File <RAW File>`__ an older data file format.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Plugin.rst b/Code/Mantid/docs/source/concepts/Plugin.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8184f95fabdf5077f473f71fa6cf860cedd6308c
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Plugin.rst
@@ -0,0 +1,74 @@
+.. _Plugin:
+
+Plugin
+======
+
+What is it?
+-----------
+
+Mantid is designed to be extensible by anyone who can write a simple
+library in C++. There are several areas that have been built so that new
+version and instances can be added just by copying a library with the
+new code into the plugin directory before starting mantid. This
+eliminates the need to recompile the main Mantid code or any user
+interfaces derived from it when you want to extend it by, for example,
+adding a new algorithm.
+
+What is a plugin?
+-----------------
+
+A plugin is a library of one or more classes that include the
+functionality that you need. Within the outputs of the Mantid project
+Several of the libraries we deliver are created as plugins. Examples
+are:
+
+- MantidAlgorithms - Contains the general `algorithms <Algorithm>`__
+- MantidDataHandling - Contains the basic data loading and saving
+ `algorithms <Algorithm>`__
+- MantidNexus - Contains the `algorithms <Algorithm>`__ for handling
+ nexus files
+- MantidDataObjects - Contains the definitions of the standard
+ `workspaces <Workspace>`__
+
+How can you extend Mantid?
+--------------------------
+
+The following areas have been designed to be easily extensible through
+using plugins. Each one contains more details in case you wish to create
+one of your own.
+
+- `Algorithm <Algorithm>`__
+- `Workspace <Workspace>`__
+- `Unit <Unit>`__
+
+How do you create a plugin?
+---------------------------
+
+There is nothing special about the library you build in order for it to
+be used as a plugin, as long as it contains one or more algorithms,
+workspaces or units (they can be mixed) they will automatically be
+registered and available for use.
+
+How does it work?
+-----------------
+
+Each of the extensible units within Mantid shares a base class that all
+further objects of that type inherit from. For example all algorithms
+must inherit from the Algorithm base class. This allows all uses of
+those objects to work through the interface of the base class, and the
+user (or other code) does not need to know what the algorithm actually
+is, just that it is an algorithm.
+
+In addition each of the extensible units has a macro that adds some code
+that automatically registers the class with the appropriate `dynamic
+factory <Dynamic_Factory>`__. This code executes immediately when the
+library is loaded and is what makes you new objects available for use.
+All of these macros start DECLARE and, for example, the one for
+algorithms is:
+
+- ``DECLARE_ALGORITHM(classname)`` (or ``namespace::classname`` if the
+ declaration is not enclosed in the algorithm's namespace)
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Project.rst b/Code/Mantid/docs/source/concepts/Project.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3972edb7c759bba6fa1f0f873445f21abfc66f52
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Project.rst
@@ -0,0 +1,24 @@
+.. _Project:
+
+Project
+=======
+
+In MantidPlot, you can save your work into project. Then when you run
+MantidPlot at a later time you can recover this work by loading the
+project.
+
+What a Project Consists of
+--------------------------
+
+A project consists of a .mantid file and a collection of `Nexus
+files <Nexus file>`__ it refers to. For this reason, a project is put
+into its own folder when saved.
+
+See Also
+--------
+
+MantidPlot:_The_File_Menu for how to save or load a project
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Properties.rst b/Code/Mantid/docs/source/concepts/Properties.rst
new file mode 100644
index 0000000000000000000000000000000000000000..ca99e0d6fa34050c8ce95dd3ccba3a6f98180df0
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Properties.rst
@@ -0,0 +1,191 @@
+.. _Properties:
+
+Properties
+==========
+
+Properties in Mantid are the mechanism by which we pass parameters into
+`algorithms <algorithm>`__. There are a number of different types of
+properties, and these are described below.
+
+Types of Properties
+-------------------
+
+Single Value Properties
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the simplest type of property, which is essentially a name-value
+pair. Currently, single value properties of type integer (``int``),
+floating point (``double``), string (``std::string``) and boolean
+(``bool``) are supported. The C++ class which implements this kind of
+property is called
+`PropertyWithValue <http://doxygen.mantidproject.org/classMantid_1_1Kernel_1_1PropertyWithValue.html>`__.
+
+Array Properties
+~~~~~~~~~~~~~~~~
+
+Sometimes, a multi-element parameter may be required (a list of spectra
+to process, for example). This is achieved using an
+`ArrayProperty <http://doxygen.mantidproject.org/classMantid_1_1Kernel_1_1ArrayProperty.html>`__
+(which is actually a PropertyWithValue - see above - of type
+std::vector). It can be created in a number of ways:
+
+- As an empty vector: ``ArrayProperty<double>("PropertyName");``
+- By passing in an existing vector:
+ ``ArrayProperty<double>("PropertyName",myStdVecOfDoubles);``
+- By passing in a string of comma-separated values:
+ ``ArrayProperty<int>("PropertyName","1,2,3,4");``
+
+A validator (see below) argument can optionally be appended to all of
+these options.
+
+An ArrayProperty can be declared in a algorithm as follows:
+
+``declareProperty(new ArrayProperty``\ \ ``(...));``
+
+or, if creating using an already existing vector:
+
+``declareProperty("PropertyName",myVector);``
+
+File Properties
+~~~~~~~~~~~~~~~
+
+These properties are for capturing and holding the path and filename to
+an external file. File properties have a FileAction property that
+controls it's purpose and behavior.
+
+Save :to specify a file to write to, the file may or may not exist
+OptionalSave :to specify a file to write to but an empty string is
+allowed here which will be passed to the algorithm
+Load :to specify a file to open for reading, the file must exist
+OptionalLoad :to specify a file to read but the file doesn't have to
+exist
+
+If the file property is has a FileAction of Load as is given a relative
+path (such as "input.txt" or "\\data\\input.txt" as its value it will
+search for matching files in this order:
+
+#. The current directory
+#. The entries in order from the datasearch.directories entry in the
+ `Properties File <Properties File#Directory_Properties>`__
+
+If the file property is has a FileAction of Save as is given a relative
+path (such as "input.txt" or "\\data\\input.txt" as its value it will
+assume that path starts from the location definied in the
+defaultsave.directory entry in the `Properties
+File <Properties File#Directory_Properties>`__.
+
+A FileProperty can be declared in a algorithm as follows:
+
+| ``declareProperty(new Kernel::FileProperty("Filename","",``
+| ``  Kernel::FileProperty::Load), "Descriptive text");``
+
+or for saving a file providing a suggested extension
+
+| ``declareProperty(new Kernel::FileProperty("Filename","",``
+| ``  Kernel::FileProperty::Save, ``
+| ``  std::vector``\ \ ``(1,"cal")), "Descriptive text");``
+
+Workspace Properties
+~~~~~~~~~~~~~~~~~~~~
+
+Properties for holding `workspaces <workspace>`__ are more complicated,
+in that they need to hold links both to the workspace name (in the
+`Analysis Data Service <Analysis Data Service>`__) and the workspace
+itself. When setting or retrieving the value as a string (i.e. using the
+``setValue`` or ``value`` methods) you are interacting with the
+workspace's name; other methods interact with a `shared
+pointer <Shared Pointer>`__ to the workspace.
+
+The syntax to declare a
+`WorkspaceProperty <http://doxygen.mantidproject.org/classMantid_1_1API_1_1WorkspaceProperty.html>`__
+in an algorithm is:
+
+``declareProperty(new WorkspaceProperty("PropertyName","WorkspaceName",direction));``
+
+In this case, the direction (see below) must be explicitly declared. An
+optional `validator <Properties#Validators>`__ may also be appended to
+the above declaration.
+
+Other 'Property Properties'
+---------------------------
+
+Default values
+~~~~~~~~~~~~~~
+
+If a property is empty
+
+- in a GUI algorithm call, then the property's default value is used
+ (if there is any)
+- in a Python API call, then the property's value is left empty.
+
+Direction
+~~~~~~~~~
+
+All properties have a direction. They can be input or output properties,
+or both. The default is always input. Technically, these are a C++ enum,
+which can have the following values:
+
+| ``Mantid::Kernel::Direction::Input``
+| ``Mantid::Kernel::Direction::Output``
+| ``Mantid::Kernel::Direction::InOut``
+
+This is what should be passed in when a direction argument is required.
+The InOut option is principally used by workspace properties, when a
+single workspace is to be input and manipulated by as algorithm rather
+than a new one created to store the result.
+
+Validators
+~~~~~~~~~~
+
+A validator is an external object that is used to verify that the value
+of a property is suitable for a particular algorithm. If no validator is
+given, then the property can have any value (of the correct type).
+Validators are checked immediately before an algorithm is executed, when
+the value of a property is set (which will fail if it doesn't pass the
+validator) and through the MantidPlot interface to an algorithm.
+
+The validators currently included in Mantid are:
+
+- BoundedValidator - restricts a numeric property to a particular
+ range.
+- MandatoryValidator - requires that a string or array property not be
+ empty.
+- ListValidator - restricts a string property to one of a particular
+ set of values.
+- FileValidator - ensures that a file (given as a string property)
+ exists (used internally by the FileProperty).
+
+In addition, there are a number of validators specifically for use with
+Workspace properties:
+
+- InstrumentValidator - checks that the workspace has an Instrument
+ object.
+- WorkspaceUnitValidator - checks that the workspace has a specified
+ unit.
+- HistogramValidator - requires that the workspace contains histogram
+ data (or not).
+- RawCountValidator - requires that the workspace data is raw counts.
+- CommonBinsValidator - checks that all spectra in a workspace have the
+ same bins.
+- SpectraAxisValidator - checks that the axis of the workspace contains
+ spectra numbers.
+- NumericAxisValidator - checks that the axis of the workspace contains
+ numeric data.
+- CompositeValidator - enables combination of more that one of the
+ above validators for the same WorkspaceProperty.
+
+In addition to the above, if used, Workspace properties also have a
+built in validator that requires that input workspaces exist and are of
+the correct type and that output workspaces have a name set.
+
+For more details on using validators, see the
+`PropertyAlgorithm <https://github.com/mantidproject/mantid/blob/master/Code/Mantid/Framework/UserAlgorithms/PropertyAlgorithm.cpp>`__
+example or the full documentation for the individual validators (linked
+above).
+
+Writing your own validator is relatively straightforward - it simply has
+to implement the IValidator interface.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Properties_File.rst b/Code/Mantid/docs/source/concepts/Properties_File.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8be3575067c123553bf6b9f3549ff183e9d47c9e
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Properties_File.rst
@@ -0,0 +1,7 @@
+.. _Properties File:
+
+Properties_File
+===============
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/RAW_File.rst b/Code/Mantid/docs/source/concepts/RAW_File.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4816964d89afdbd4738b3ccf4b0504ddeb603652
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/RAW_File.rst
@@ -0,0 +1,85 @@
+.. _RAW File:
+
+RAW_File
+========
+
+The RAW file format has been for many years the primary data format of
+the ISIS facility.
+
+Structure
+---------
+
+The Raw file is a binary formatted file that uses a simple but effective
+compression system to achieve 4-1 compression of the data in holds.
+
+Compression
+-----------
+
+To be completed later
+
+Alternate Data Streams
+----------------------
+
+When the Raw file is archived to the NTFS archive additional information
+about it is added as an Alternate Data Stream. This includes a list of
+all of the files that were archived with this RAW file and a checksum
+for each. This can provide a fast way of finding the log files
+associated with a RAW file in a crowded directory.
+
+For example:
+
+::
+
+ d28cb560cdefc765fc8d550b6f335006 *SANS2D00000799.log
+ 52526cd14652284c2748e905ff74fc4b *SANS2D00000799.nxs
+ 7d3b5776c32b63aa76b9e36d2e7ec348 *SANS2D00000799.raw
+ de230169cda344118d26315dd31c0fb4 *SANS2D00000799.s001
+ cbd0685b6ce19781fca13ba4395318d9 *SANS2D00000799.s01
+ f9b9aa805179598207d6bf713eacd5a7 *SANS2D00000799_Beam_Shutter.txt
+ d10238be18d69d21f8890f73805795bb *SANS2D00000799_Changer.txt
+ acc92b1223bb93ad85e03b523639142a *SANS2D00000799_Fast_Shutter.txt
+ 671d77b4d2d9a1deee3e6dc9c3db9875 *SANS2D00000799_Height.txt
+ 2eb44a65f79f73e194cdcd48d38385b4 *SANS2D00000799_ICPdebug.txt
+ 0268e471a0ae4c0382ffb81622e03dde *SANS2D00000799_ICPevent.txt
+ 3cda6c3f179c6f70fea82e9ad9e75360 *SANS2D00000799_ICPstatus.txt
+ 19ea5cbe0e57b01db61b01ba24f70bc5 *SANS2D00000799_Julabo.txt
+ 2e6bb0fe5965527d1cb319fff0df928d *SANS2D00000799_Moderator_Temp.txt
+ 604946b7385f8d08ff9c9eb47b0803c2 *SANS2D00000799_Sample.txt
+ cf5022506705b6ba5c850edd824088be *SANS2D00000799_Status.txt
+ 54e4a8e82fe00cd5e9263bb14506682f *SANS2D00000799_Table.txt
+
+In the links below you will streams or DIR on Vista can list the streams
+on a file. Not many programs can display the contents of an alternate
+data stream, but so far I have discovered that the following work, at
+least for RAW files.
+
+::
+
+ notepad2.exe SANS2D00000799.raw:checksum
+ more < SANS2D00000799.raw:checksum
+
+If a file with an alternate data stream is copied to an FAT file system
+the alternate data stream is lost. It has been reported that if a file
+with an ADS is copied using SAMBA to a unix file system the streams are
+extracted into seperate files with automatically generates suffixes.
+
+More information about Alternate Data Streams
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `Microsoft support
+ article <http://support.microsoft.com/kb/105763>`__
+- `DIR command on Vista can list Alternate
+ streams <http://bartdesmet.net/blogs/bart/archive/2006/07/13/4129.aspx>`__
+- `Streams.exe from SysInternals can list alternate
+ streams <http://technet.microsoft.com/en-us/sysinternals/bb897440.aspx>`__
+- `Practical Guide to Alternative Data Streams in
+ NTFS <http://www.irongeek.com/i.php?page=security/altds>`__
+
+See also
+~~~~~~~~
+
+`Nexus file <Nexus file>`__ a newer type of data file
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Run.rst b/Code/Mantid/docs/source/concepts/Run.rst
new file mode 100644
index 0000000000000000000000000000000000000000..53df6475223985e8cb27309e824841423ed815e0
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Run.rst
@@ -0,0 +1,71 @@
+.. _Run:
+
+Run
+===
+
+What is it?
+-----------
+
+A Run holds data related to the properties of the experimental run, e.g.
+good proton charge, total frames etc. It also holds all of the sample
+log files as sets of time-series data. Currently used properties within
+Mantid includes *run\_start*, which specified the date the data were
+collected. Where an instrument has been modified over time, and multiple
+`instrument definition files <InstrumentDefinitionFile>`__ have been
+defined for it, this property is used to loads the IDF valid when the
+data were collected.
+
+What information is stored here?
+--------------------------------
+
+On loading experimental data there is a default set of properties that
+are populated within the run. These are as follows:
+
+ISIS (not including ISIS Muon data)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- **run\_header** - The complete header for this run
+- **run\_title** - The run title
+- **run\_start** - Start date and time. Format: YYYY-MM-DD HH:MM:SS (+)
+- **run\_end** - End date and time. Format: YYYY-MM-DD HH:MM:SS (+)
+- **nspectra** - The number of spectra in the raw data file
+- **nchannels** - The number of time channels in the raw data
+- **nperiods** - The number of periods within the raw data
+- **dur** - The run duration
+- **durunits** - The units of the run duration, 1 = seconds
+- **dur\_freq** - Test interval for above
+- **dmp** - Dump interval
+- **dmp\_units** - The units (scaler) for above
+- **dmp\_freq** - Test interval for above
+- **freq** - 2\*\*k where source frequency = 50 / 2\*\*k
+- **gd\_prtn\_chrg** - Good proton charge (uA.hour)
+- '''tot\_prtn\_chrg\* '''- Total proton charge (uA.hour)
+- **goodfrm** - Good frames
+- '''rawfrm\* '''- Raw frames
+- **dur\_wanted** - Requested run duration (units as for "duration"
+ above)
+- **dur\_secs** - Actual run duration in seconds
+- **mon\_sum1** - Monitor sum 1
+- **mon\_sum2** - Monitor sum 2
+- **mon\_sum3** - Monitor sum 3
+- **rb\_proposal** - The proposal number
+
+ISIS Muon data
+^^^^^^^^^^^^^^
+
+- **run\_title** - The run title
+- **run\_start** - Start date and time. Format: YYYY-MM-DD HH:MM:SS (+)
+- **run\_end** - End date and time. Format: YYYY-MM-DD HH:MM:SS (+)
+- **nspectra** - The number of spectra in the raw data file
+- **goodfrm** - Good frames
+- **dur\_secs** - Run duration in seconds
+- **run\_number** - Run number
+- **sample\_temp** - Temperature of the sample
+- **sample\_magn\_field** - Magnetic field of the sample
+
+(+) or YYYY-MM-DDTHH:MM:SS (ISO 8601 format, see
+`1 <http://en.wikipedia.org/wiki/ISO_8601>`__)
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Shared_Pointer.rst b/Code/Mantid/docs/source/concepts/Shared_Pointer.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f6454bb03fc79c962e6145cb405af700ba48af17
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Shared_Pointer.rst
@@ -0,0 +1,61 @@
+.. _Shared Pointer:
+
+Shared_Pointer
+==============
+
+What are they?
+--------------
+
+Shared pointers are used extensively within the Mantid Framework to
+simplify memory management and reduce memory leaks. We use the Shared
+Pointer `definition from the Boost
+library <http://www.boost.org/doc/libs/1_35_0/libs/smart_ptr/smart_ptr.htm>`__.
+
+Shared pointers are objects which store pointers to dynamically
+allocated (heap) objects. They behave much like built-in C++ pointers
+except that they automatically delete the object pointed to at the
+appropriate time. Shared pointers are particularly useful in the face of
+exceptions as they ensure proper destruction of dynamically allocated
+objects. They can also be used to keep track of dynamically allocated
+objects shared by multiple owners.
+
+Conceptually, Shared pointers are seen as owning the object pointed to,
+and thus responsible for deletion of the object when it is no longer
+needed.
+
+Declaring a shared pointer
+--------------------------
+
+creating a shared pointer to a new object
+
+``boost::shared_ptr``\ \ `` ptr(new C);``
+
+assigning a shared pointer
+
+``boost::shared_ptr``\ \ `` instrument = workspace->getInstrument();``
+
+Several of our shared pointers have typedefs to give them much shorter
+definitions. For example instead of boost::shared\_ptr you can just type
+workspace\_sptr (where sptr stands for shared pointer).
+
+Using a shared pointer
+----------------------
+
+Shared pointer can be used just like any pointer.
+
+``workspacePointer->readX(1);``
+
+The only real differences are when casting the pointer instead of
+
+``Workspace2D*Â input2DÂ =Â dynamic_cast``\ \ ``(m_input);``
+
+you would use
+
+``Workspace2D_sptr input2D = boost::dynamic_pointer_cast``\ \ ``(input);``
+
+and that you should not delete a shared pointer, it will take care of
+itself.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Table_Workspaces.rst b/Code/Mantid/docs/source/concepts/Table_Workspaces.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e43ec07a44235244b343d1809c43c4a9c8f1176b
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Table_Workspaces.rst
@@ -0,0 +1,99 @@
+.. _Table Workspaces:
+
+Table_Workspaces
+================
+
+- *This page focusses on dealing with Table Workspaces in C++, and is
+ aimed at developers. For details on interacting with Table Workspaces
+ in Python, please see `this page <Python_ITableWorkspace>`__.*
+
+Overview
+--------
+
+Table workspaces are general purpose workspaces for storing data of
+mixed types. A table workspace is organized in columns. Each column has
+a name and a type - the type of the data in that column. Table wokspaces
+can be created using the workspace factory:
+
+``ITableWorkspace_sptr table = WorkspaceFactory::Instance().createTable("TableWorkspace");``
+
+Columns are added using the addColumn method:
+
+| ``table->addColumn("str","Parameter Name");``
+| ``table->addColumn("double","Value");``
+| ``table->addColumn("double","Error");``
+| ``table->addColumn("int","Index");``
+
+Here the first argument is a symbolic name of the column's data type and
+the second argument is the name of the column. The predefined types are:
+
++-----------------+-------------------------+
+| Symbolic name | C++ type |
++=================+=========================+
+| int | int |
++-----------------+-------------------------+
+| float | float |
++-----------------+-------------------------+
+| double | double |
++-----------------+-------------------------+
+| bool | bool |
++-----------------+-------------------------+
+| str | std::string |
++-----------------+-------------------------+
+| V3D | Mantid::Geometry::V3D |
++-----------------+-------------------------+
+| long64 | int64\_t |
++-----------------+-------------------------+
+
+The data in the table can be accessed in a number of ways. The most
+simple way is to call templated method T& cell(row,col), where col is
+the index of the column in the workspace and row is the index of the
+cell in the comlumn. Colunms are indexed in the order they are created
+with addColumn. There are also specialized methods for four predefined
+data types: int& Int(row,col), double& Double(row,col), std::string&
+String(row,col), bool& Bool(row,col). Columns use std::vector to store
+the data. To get access to the vector use getVector(name). To get the
+column object use getColumn(name).
+
+Only columns of type int, double and str can currently be saved to Nexus
+by `SaveNexus <SaveNexus>`__ or
+`SaveNexusProcessed <SaveNexusProcessed>`__. Columns of other types will
+simply be ommitted from the Nexus file without any error message.
+
+Table rows
+----------
+
+Cells with the same index form a row. TableRow class represents a row.
+Use getRow(int) or getFirstRow() to access existing rows. For example:
+
+| ``std::string key;``
+| ``double value;``
+| ``TableRow row = table->getFirstRow();``
+| ``do``
+| ``{``
+| ``  row >> key >> value;``
+| ``  std::cout << "key=" << key << " value=" << value << std::endl;``
+| ``}``
+| ``while(row.next());``
+
+TableRow can also be use for writing into a table:
+
+| ``for(int i=0; i < n; ++i)``
+| ``{``
+| ``  TableRow row = table->appendRow();``
+| ``  row << keys[i] << values[i];``
+| ``}``
+
+Defining new column types
+-------------------------
+
+Users can define new data types to be used in TableWorkspace.
+TableColumn.h defines macro
+DECLARE\_TABLECOLUMN(c\_plus\_plus\_type,symbolic\_name).
+c\_plus\_plus\_type must be a copyable type and operators << and >> must
+be defined. There is also DECLARE\_TABLEPOINTERCOLUMN macro for
+declaring non-copyable types, but it has never been used.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Unit_Factory.rst b/Code/Mantid/docs/source/concepts/Unit_Factory.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0b063750a9c249112fb6c475c43e3e28ae20183e
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Unit_Factory.rst
@@ -0,0 +1,76 @@
+.. _Unit Factory:
+
+Unit_Factory
+============
+
+.. role:: math(raw)
+ :format: html latex
+..
+
+What is it?
+-----------
+
+The Unit Factory is a `Dynamic Factory <Dynamic Factory>`__ that creates
+and hands out instances of Mantid Unit objects.
+
+Available units
+~~~~~~~~~~~~~~~
+
+The following units are available in the default Mantid distribution.
+
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Name | ID (as known by Unit Factory) | Unit | Relevant equation |
++===========================================+=================================+=============================+==================================================================================================================+
+| Time of flight | TOF | :math:`\mu s` | TOF |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Wavelength | Wavelength | :math:`\mathrm{\AA}` | :math:`\lambda = \frac{h}{p} = \frac{h \times \mathrm{tof}}{m_N \times L_{tot}}` (see below) |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Energy | Energy | :math:`meV` | :math:`E = \frac{1}{2} mv^2 = \frac{m_N}{2} \left ( \frac{L_{tot}}{\mathrm{tof}} \right )^2` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Energy in wavenumber | Energy\_inWavenumber | :math:`cm^{-1}` | :math:`8.06554465 \times E` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Momentum (k) | Momentum | :math:`\mathrm{\AA}^{-1}` | :math:`k = \frac{2 \pi }{\lambda}=\frac{2 \pi \times m_N \times L_{tot}}{h \times \mathrm{tof}}` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| d-spacing | dSpacing | :math:`\mathrm{\AA}` | :math:`d = \frac{n \, \lambda}{2 \, sin \, \theta}` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Momentum transfer (Q) | MomentumTransfer | :math:`\mathrm{\AA}^{-1}` | :math:`Q = 2 \, k \, sin \, \theta = \frac{4 \pi sin \theta}{\lambda}` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Momentum transfer squared (:math:`Q^2`) | QSquared | :math:`\mathrm{\AA}^{-2}` | :math:`Q^2 \frac{}{}` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Energy transfer | DeltaE | :math:`meV` | :math:`\Delta E = E_{i}-\frac{1}{2}m_N \left ( \frac{L_2}{\mathrm{tof}-L_1\sqrt{\frac{m_N}{2E_i}}} \right )^2` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Energy transfer in wavenumber | DeltaE\_inWavenumber | :math:`cm^{-1}` | :math:`8.06554465 \times \Delta E` |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Spin Echo Length | SpinEchoLength | :math:`nm` | | :math:`constant \times \lambda^2` |
+| | | | | The constant is supplied in eFixed |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+| Spin Echo Time | SpinEchoTime | :math:`ns` | | :math:`constant \times \lambda^3` |
+| | | | | The constant is supplied in eFixed |
++-------------------------------------------+---------------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------+
+
+Where :math:`L_1` and :math:`L_2` are sample to the source and sample to
+detector distances respectively, :math:`L_{tot} = L_1+L_2` and
+:math:`E_i` is the energy of neutrons leaving the source. :math:`\theta`
+here is the Bragg scattering angle (e.g. half of the
+:math:`\theta`-angle used in spherical coordinate system directed along
+Mantid z-axis)
+
+**Note on Wavelength**: If the emode property in
+`ConvertUnits <http://docs.mantidproject.org/nightly/algorithms/ConvertUnits.html>`__
+is specified as inelastic Direct/Indirect (inelastic) then the
+conversion to wavelength will take into account the fixed initial/final
+energy respectively. Units conversion into elastic momentum transfer
+(MomentumTransfer) will throw in elastic mode (emode=0) on inelastic
+workspace (when energy transfer is specified along x-axis)
+
+Adding new units
+~~~~~~~~~~~~~~~~
+
+Writing and adding a new unit is relatively straightforward.
+Instructions will appear here in due course. In the meantime if a unit
+that you require is missing, then please contact the development team
+and we will add it to the default Mantid library.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Workflow_Algorithm.rst b/Code/Mantid/docs/source/concepts/Workflow_Algorithm.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2ea111cef71a77401a338dcceb9e69483778e5f2
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Workflow_Algorithm.rst
@@ -0,0 +1,47 @@
+.. _Workflow Algorithm:
+
+Workflow_Algorithm
+==================
+
+A workflow algorithm is a special subset of algorithms that perform
+higher level tasks by solely making use of other algorithms. These
+algorithms inherit from a specialized base class DataProcessorAlgorithm,
+to indicate that these are indeed WorkflowAlgorithms. Due to the special
+functions that can be applied to these algorithms it is vital that they
+do not alter the data in any way directly themselves and rather use
+child algorithms to do so.
+
+Special Functions
+~~~~~~~~~~~~~~~~~
+
+.. figure:: NestedHistory.png
+ :alt: NestedHistory.png
+
+ NestedHistory.png
+Nested History
+^^^^^^^^^^^^^^
+
+As workflow algorithms are effectively just a collection of sub
+algorithms tied together with some logic it is possible to represent
+them as a simple flow diagram, and extract out the child algorithms from
+any particular run. The nested history approach on Mantid allow any
+workflow algorithm to be "unrolled" into the child algorithms that were
+used by it.
+
+Flow Diagrams
+^^^^^^^^^^^^^
+
+As workflow algorithms are effectively just a collection of sub
+algorithms tied together with some logic it is possible to represent
+them as a simple flow diagram. Each worklow algorithm should provide a
+flow diagram of it's operations.
+
+Examples
+''''''''
+
+- `DGSReduction <http://docs.mantidproject.org/algorithms/DgsReduction.html>`__
+- `MuonLoad <http://docs.mantidproject.org/algorithms/MuonLoad.html>`__
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Workspace.rst b/Code/Mantid/docs/source/concepts/Workspace.rst
new file mode 100644
index 0000000000000000000000000000000000000000..010cc4c0fc3f5d482a5b8a0bb9972b4624f58d4c
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Workspace.rst
@@ -0,0 +1,105 @@
+.. _Workspace:
+
+Workspace
+=========
+
+What are they?
+--------------
+
+Workspaces are the nouns of Mantid (while `algorithms <algorithm>`__ are
+the verbs). Workspaces hold the data in Mantid.
+
+They come in several forms, but the most common by far is the
+`MatrixWorkspace <MatrixWorkspace>`__ which contains measured or derived
+data with associated errors. Matrix Workspaces are typically created
+initially by executing one of Mantid's 'Load' algorithms, for example
+`LoadRaw <http://docs.mantidproject.org/nightly/algorithms/LoadRaw.html>`__
+or
+`LoadNexus <http://docs.mantidproject.org/nightly/algorithms/LoadNexus.html>`__,
+or they are the output of algorithms which took a matrix workspace as
+input. In `MantidPlot <MantidPlot:_Help>`__ the data from the workspace
+can viewed as a table, and graphed in many ways.
+
+Another form of workspace is the `TableWorkspace <Table Workspaces>`__.
+This stores data of (somewhat) arbitrary type in rows and columns, much
+like a spreadsheet. These typically are created as the output of certain
+specialized algorithms (e.g. curve fitting).
+
+In addition to data, workspaces hold a `workspace
+history <WorkspaceHistory>`__, which details the algorithms which have
+been run on this workspace.
+
+In software engineering terms, the 'abstract' concept of a workspace is
+an 'interface', in that it defines common properties that are
+implemented by various 'concrete' workspaces. Interaction with
+workspaces is typically through an interface. The concrete workspaces
+themselves are loaded in via Mantid's `plugin <plugin>`__ mechanism and
+are created using the `Workspace Factory <Workspace Factory>`__.
+
+Example Workspaces
+------------------
+
+- `MatrixWorkspace <MatrixWorkspace>`__ - A base class that contains
+ among others:
+
+ - `Workspace2D <Workspace2D>`__ - A workspace for holding two
+ dimensional data in memory, this is the most commonly used
+ workspace.
+ - `EventWorkspace <EventWorkspace>`__ - A workspace that retains the
+ individual neutron event data.
+
+- `TableWorkspace <Table Workspaces>`__ - A workspace holding data in
+ rows of columns having a particular type (e.g. text, integer, ...).
+- `WorkspaceGroup <WorkspaceGroup>`__ - A container for a collection of
+ workspaces. Algorithms given a group as input run sequentially on
+ each member of the group.
+
+Writing you own workspace
+-------------------------
+
+This is perfectly possible, but not as easy as creating your own
+algorithm. Please talk to a member of the development team if you wish
+to implement you own workspace.
+
+Workspace Types
+---------------
+
+The workspace type id identifies the type (underlying class) of a
+Workspace object. These IDs are listed here for ease of reference, so
+you needn't navigate Doxygen for a list of workspace types. These values
+are needed in such functions as the AnalysisDataService's
+createWorkspace if you are writing C++ or Python algorithms.
+
++-------------------------------+-------------------------------------------+
+| ID | Workspace Type |
++===============================+===========================================+
+| "IEventWorkspace" | IEventWorkspace |
++-------------------------------+-------------------------------------------+
+| "ITableWorkspace" | ITableWorkspace |
++-------------------------------+-------------------------------------------+
+| "WorkspaceGroup" | WorkspaceGroup |
++-------------------------------+-------------------------------------------+
+| "AbsManagedWorkspace2D" | AbsManagedWorkspace2D |
++-------------------------------+-------------------------------------------+
+| "CompressedWorkspace2D" | CompressedWorkspace2D |
++-------------------------------+-------------------------------------------+
+| "EventWorkspace" | `EventWorkspace <EventWorkspace>`__ |
++-------------------------------+-------------------------------------------+
+| "ManagedWorkspace2D" | ManagedWorkspace2D |
++-------------------------------+-------------------------------------------+
+| "TableWorkspace" | TableWorkspace |
++-------------------------------+-------------------------------------------+
+| "Workspace2D" | `Workspace2D <Workspace2D>`__ |
++-------------------------------+-------------------------------------------+
+| "WorkspaceSingleValue" | WorkspaceSingleValue |
++-------------------------------+-------------------------------------------+
+| "ManagedRawFileWorkspace2D" | ManagedRawFileWorkspace2D |
++-------------------------------+-------------------------------------------+
+| "MDEventWorkspace" | `MDEventWorkspace <MDEventWorkspace>`__ |
++-------------------------------+-------------------------------------------+
+| "MDHistoWorkspace" | `MDHistoWorkspace <MDHistoWorkspace>`__ |
++-------------------------------+-------------------------------------------+
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/Workspace2D.rst b/Code/Mantid/docs/source/concepts/Workspace2D.rst
new file mode 100644
index 0000000000000000000000000000000000000000..76bd44da45bbaee0203ed5519fb7451ed11af28b
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/Workspace2D.rst
@@ -0,0 +1,20 @@
+.. _Workspace2D:
+
+Workspace2D
+===========
+
+The Workspace2D is a Mantid data type for a
+`MatrixWorkspace <MatrixWorkspace>`__.
+
+It consists of a workspace with 1 or more spectra. Typically, each
+spectrum will be a histogram. For example, you might have 10 bins, and
+so have 11 X-value, 10 Y-values and 10 E-values in a workspace.
+
+In contrast to an `EventWorkspace <EventWorkspace>`__, a Workspace2D
+only contains bin information and does not contain the underlying event
+data. The `EventWorkspace <EventWorkspace>`__ presents itself as a
+histogram (with X,Y,E values) but preserves the underlying event data.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/concepts/WorkspaceGroup.rst b/Code/Mantid/docs/source/concepts/WorkspaceGroup.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9544412892c2c60f0e99a26cebef0d1a40cd7d06
--- /dev/null
+++ b/Code/Mantid/docs/source/concepts/WorkspaceGroup.rst
@@ -0,0 +1,26 @@
+.. _WorkspaceGroup:
+
+WorkspaceGroup
+==============
+
+A WorkspaceGroup is a group of workspaces.
+
+Most algorithms will execute on a WorkspaceGroup by simply executing the
+algorithm on each workspace contained within.
+
+Creating a Workspace Group
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Select a few workspaces in MantidPlot and click the "Group" button
+ above the list of workspaces.
+- Use the `GroupWorkspaces <GroupWorkspaces>`__ algorithm.
+
+Un-grouping Workspaces
+~~~~~~~~~~~~~~~~~~~~~~
+
+- Select the WorkspaceGroup and click "Ungroup".
+- Use the `UnGroupWorkspace <UnGroupWorkspace>`__ algorithm.
+
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/Code/Mantid/docs/source/images/MDWorkspace_structure.png b/Code/Mantid/docs/source/images/MDWorkspace_structure.png
new file mode 100644
index 0000000000000000000000000000000000000000..a30dc7fdb5c75558c79f1889af81abfeda2b9bb6
Binary files /dev/null and b/Code/Mantid/docs/source/images/MDWorkspace_structure.png differ
diff --git a/Code/Mantid/docs/source/images/NestedHistory.png b/Code/Mantid/docs/source/images/NestedHistory.png
new file mode 100644
index 0000000000000000000000000000000000000000..62be27353b227772e643b459efd8b93ccc9df786
Binary files /dev/null and b/Code/Mantid/docs/source/images/NestedHistory.png differ
diff --git a/Code/Mantid/docs/source/images/XMLconeDescription.png b/Code/Mantid/docs/source/images/XMLconeDescription.png
new file mode 100644
index 0000000000000000000000000000000000000000..321083be38798c4fec5fc0dca67ac65483afd583
Binary files /dev/null and b/Code/Mantid/docs/source/images/XMLconeDescription.png differ
diff --git a/Code/Mantid/docs/source/images/XMLcuboidDescription.png b/Code/Mantid/docs/source/images/XMLcuboidDescription.png
new file mode 100644
index 0000000000000000000000000000000000000000..c6cb54145c281b39e38413f3ad8fe2648ac61000
Binary files /dev/null and b/Code/Mantid/docs/source/images/XMLcuboidDescription.png differ
diff --git a/Code/Mantid/docs/source/images/XMLcylinderDescription.png b/Code/Mantid/docs/source/images/XMLcylinderDescription.png
new file mode 100644
index 0000000000000000000000000000000000000000..ef1c16c2b5f97da15d514e4091f6026c95f8af90
Binary files /dev/null and b/Code/Mantid/docs/source/images/XMLcylinderDescription.png differ
diff --git a/Code/Mantid/docs/source/images/XMLhexahedronDescription.png b/Code/Mantid/docs/source/images/XMLhexahedronDescription.png
new file mode 100644
index 0000000000000000000000000000000000000000..0bb687bf03023fbb2c6e9cf23d0d71c3f86f2392
Binary files /dev/null and b/Code/Mantid/docs/source/images/XMLhexahedronDescription.png differ
diff --git a/Code/Mantid/docs/source/images/XMLsliceCylinderRingDescription.png b/Code/Mantid/docs/source/images/XMLsliceCylinderRingDescription.png
new file mode 100644
index 0000000000000000000000000000000000000000..468caf5bec6a0346b3f19b6fb53b6cbdf1ec0755
Binary files /dev/null and b/Code/Mantid/docs/source/images/XMLsliceCylinderRingDescription.png differ
diff --git a/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py b/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py
index 2a93e455d8fa243a1e46335caf293fdeb5cb4e57..50e1870186719edf93edd1e4e8e9630c2601dc08 100644
--- a/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py
+++ b/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py
@@ -17,7 +17,7 @@ CATEGORIES_DIR = "categories"
# List of category names that are considered the index for everything in that type
# When this category is encountered an additional index.html is written to both the
# directory of the document and the category directory
-INDEX_CATEGORIES = ["Algorithms", "FitFunctions"]
+INDEX_CATEGORIES = ["Algorithms", "FitFunctions","Concepts"]
class LinkItem(object):
"""
diff --git a/Code/Tools/scripts/AddAlgorithmWikiLinksToText.py b/Code/Tools/scripts/AddAlgorithmWikiLinksToText.py
new file mode 100644
index 0000000000000000000000000000000000000000..fafd7ee3bd1e332f9722a9ae6f9ffb2a2a80efb5
--- /dev/null
+++ b/Code/Tools/scripts/AddAlgorithmWikiLinksToText.py
@@ -0,0 +1,17 @@
+text = """
+===Algorithms===
+* PlotPeakByLogValue now optionally outputs calculated spectra like the Fit algorithm.
+* StartLiveData now checks whether the instrument listener supports the provision of historic values.
+* LiveData processing now handles the transition between runs much better at facilities that support this functionality (at present only the SNS).
+* LoadEventNexus reads the Pause log and discards any events found during Paused time spans.
+* GenerateEventsFilter has been improved to make it easier to use and allowing split sections to be added together into workplaces on a cyclic basis.
+* LoadPreNexus is now more forgiving if it encounters bad event indexes in pulse ID file .
+
+"""
+
+import re
+
+algs = AlgorithmFactory.getRegisteredAlgorithms(True)
+for alg in algs:
+ text = re.sub(r'\b' + alg+ r'\b',r'[http://docs.mantidproject.org/algorithms/' + alg + '.html ' + alg + '] ',text)
+print text
\ No newline at end of file
diff --git a/Code/Tools/scripts/FindIncompleteAlgRSTPages.py b/Code/Tools/scripts/FindIncompleteAlgRSTPages.py
new file mode 100644
index 0000000000000000000000000000000000000000..33139d28057d2ff495b7ff78c5f85df2420b5196
--- /dev/null
+++ b/Code/Tools/scripts/FindIncompleteAlgRSTPages.py
@@ -0,0 +1,51 @@
+import os, re
+import urllib2
+
+def readWebPage(url):
+ proxy = urllib2.ProxyHandler({'http': 'wwwcache.rl.ac.uk:8080'})
+ opener = urllib2.build_opener(proxy)
+ urllib2.install_opener(opener)
+ aResp =urllib2.urlopen(url)
+ web_pg = aResp.read();
+ return web_pg
+
+def ticketExists(alg, ticketHash):
+ retVal = ""
+ algPattern = re.compile(alg, re.IGNORECASE)
+ for ticket in ticketHash:
+ ticketText = ticketHash[ticket]
+ if algPattern.search(ticketText):
+ retVal = str(ticket)
+ break
+ return retVal
+
+def outputError(alg, algVersion, description, notes=""):
+ print "%s, %i, %s, %s" % (alg, algVersion, description, notes)
+
+rstdir = r"C:\Mantid\Code\Mantid\docs\source\algorithms"
+ticketList = [9582,9586,9607,9610,9704,9804,9726]
+
+ticketHash = {}
+for ticket in ticketList:
+ ticketHash[ticket] = readWebPage( r"http://trac.mantidproject.org/mantid/ticket/" + str(ticket))
+
+usagePattern = re.compile('Usage', re.IGNORECASE)
+excusesPattern = re.compile('(rarely called directly|designed to work with other algorithms|only used for testing|deprecated)', re.IGNORECASE)
+
+
+algs = AlgorithmFactory.getRegisteredAlgorithms(True)
+for alg in algs:
+ algVersion = algs[alg][0]
+ fileFound = False
+ filename = os.path.join(rstdir,alg + "-v" + str(algVersion) + ".rst")
+ if os.path.exists(filename):
+ with open (filename, "r") as algRst:
+ fileFound = True
+ algText = algRst.read()
+ if (usagePattern.search(algText) == None) and (excusesPattern.search(algText) == None):
+ #check if already in a ticket
+ usageTicket = ticketExists(alg,ticketHash)
+ outputError(alg, algVersion, "No usage section", usageTicket)
+ if fileFound==False:
+ outputError(alg, algVersion, "File not found")
+