Commit 41f17308 authored by Nick Draper's avatar Nick Draper
Browse files

re #9923 updated links and qc, still needs links from algs

parent 990a0194
......@@ -8,10 +8,10 @@ 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,
Algorithms operate primarily on data in :ref:`workspaces <Workspace>`. They
will normally take one or more :ref:`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
:ref:`workspace <Workspace>` (although it is possible to have multiple
outputs).
Categories, Name and Versions
......@@ -27,8 +27,7 @@ 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.
subcategories of Algorithms category.
Name
~~~~
......@@ -52,7 +51,7 @@ Parameters
----------
Each algorithm will have one or more parameters, known within Mantid as
`properties <properties>`__, that will control how it performs its
:ref:`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.
......@@ -66,10 +65,6 @@ 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
......@@ -89,9 +84,6 @@ From MantidScript(Python)
print alg["Property2"]
# prints 'p2', etc
.. raw:: html
</div>
Using the C++ API
^^^^^^^^^^^^^^^^^
......@@ -99,10 +91,6 @@ 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
......@@ -117,35 +105,29 @@ prop)
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>`__
- :ref:`Plus <algm-Plus>`
- An algorithm for adding data in two :ref:`workspaces <Workspace>`
together
- `Rebin <http://docs.mantidproject.org/nightly/algorithms/Rebin.html>`__
- :ref:`Rebin <algm-Rebin>`
- An algorithm for altering the binning of the data in a
`workspace <Workspace>`__.
- `LoadRaw <http://docs.mantidproject.org/nightly/algorithms/LoadRaw.html>`__
:ref:`workspace <Workspace>`.
- :ref:`LoadRaw <algm-LoadRaw>`
- An algorithm for loading the data from a RAW file into a
`workspace <Workspace>`__.
- `GroupDetectors <http://docs.mantidproject.org/nightly/algorithms/GroupDetectors.html>`__
:ref:`workspace <Workspace>`.
- :ref:`GroupDetectors <algm-GroupDetectors>`
- 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
A primer for this is `here <http://www.mantidproject.org/Writing_an_Algorithm>`__. Also look at the
examples in the :ref:`UserAlgorithms <UserAlgorithms>` directory of your
Mantid installation.
......
.. _Analysis Data Service:
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
The Analysis Data Service is a :ref:`Data Service <Data Service>` that is
specialized to hold all of the :ref:`workspaces <Workspace>` that are
created by user run :ref:`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.
......@@ -16,18 +16,18 @@ 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>`__.
The most usual way in user code would be to use the :ref:`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>`__)
Or you could get it directly from the AnalysisDataService (as a :ref:`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.
Workspace :ref:`Property <Properties>` to access or store your workspaces.
......
.. _Create_an_IDF:
Create an IDF
=============
This page will help you get started with making an instrument definition file. For documentation on individual elements of an IDF refer to the :ref:`IDF documentation <InstrumentDefinitionFile>`
Basic Steps
-----------
The best way to get started is to:
- `Set up an editor for XML that uses schema validation <http://www.mantidproject.org/Using_XML_Schema>`__
- Read the :ref:`introduction to IDFs <InstrumentDefinitionFile>`
- Read the annotated existing IDFs
- Look for similar existing IDFs
- Use the IDF page for more detailed documentation
Using the Schema
----------------
To set up your editor with the schema, `Follow These Instructions <http://www.mantidproject.org/Using_XML_Schema>`__.
The Schema can help with writing the IDF. For example:
- In Visual Studio the schema can be used to auto-insert elements and attributes permitted by the schema.
- In eclipse the IDF can be created in a design view by selected available elements and attributes without having to type the code yourself.
The IDF schema (IDFSchema.xsd) is located in your mantid install directory at MantidInstall\instrument\Schema. Note this folder also includes the schema, ParameterFileSchema.xsd, which may be used to assist in writting a :ref:`parameter file <InstrumentParameterFile>`
Find a Similar existing IDF
---------------------------
It may be that an instrument already exists that is similar to the one you wish to add. To see the existing instruments follow the procedure below.
- Install Mantid
- Open MantidPlot
- Execute the algorithm LoadEmptyInstrument
- This open the algorithm window for this algorithm. Click the Browse button and browse to the instrument folder of your Mantid install directory
- The instrument folder contains all the instruments that Mantid currently support. Select for example SANS2D_Definition.xml. Fill in the output workspace name, and and click 'Run'
- The created workspace will appear in the Workspaces window. Right click on the workspace and chose 'Show Instrument'
- A new window appears, which is called the `Instrument view <http://www.mantidproject.org/MantidPlot:_Instrument_View>`__.
In addition below is a list (for now just containing one item) of existing IDFs which have been annotated with the purpose of (hopefully) quickly learn the basis of creating an IDF:
- :ref:`SANS2D: ISIS small angle scattering instrument <SANS2D_Sample_IDF>`
- :ref:`LET: ISIS direct inelastic instrument<LET_Sample_IDF>`
.. categories:: Concepts
.. _Data Service:
Data_Service
Data Service
============
What are they?
......@@ -17,10 +17,10 @@ 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
- :ref:`Analysis Data Service <Analysis Data Service>` - A data service
holding all of the :ref:`workspaces <Workspace>` used in this session.
- :ref:`Instrument Data Service <Instrument Data Service>` - A data
service holding all of the :ref:`instruments <Instrument>` used in this
session.
......
.. _Dynamic Factory:
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.
implementing the :ref:`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
responsible for creating instances of :ref:`Algorithms <Algorithm>` when
you need them.
As the factory is dynamic it does not have a set list of objects that it
......
.. _Error Propagation:
Error_Propagation
Error Propagation
=================
The purpose of this document is to explain how Mantid deals with Error
......
......@@ -6,29 +6,29 @@ EventWorkspace
Quick Summary For Users
-----------------------
The EventWorkspace is a type of `MatrixWorkspace <MatrixWorkspace>`__,
The EventWorkspace is a type of :ref:`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
- You can :ref:`rebin <algm-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
- You can convert an EventWorkspace to a :ref:`Workspace2D <Workspace2D>`
by using the :ref:`Rebin <algm-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.
:ref:`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>`__
it can be another EventWorkspace. For example, the :ref:`Plus <algm-Plus>`
algorithm will append the event lists if given two input
EventWorkspaces.
- Since it retains the most information, it is advantageous to keep
......@@ -61,7 +61,7 @@ Lists of Events (EventList)
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
tracks which detector(s) were hit by the events in
the list.
- The histogram bins (X axis) are also stored in EventList. The Y and E
......@@ -70,7 +70,7 @@ Lists of Events (EventList)
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
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.
......@@ -79,7 +79,7 @@ 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
histograms, a MRUList. This MRU caches the last histogram
data generated for fastest display.
A note about workspace index / spectrum number / detector ID
......@@ -95,9 +95,9 @@ Workspace2D compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~
EventWorkspace is designed to be able to be read (but not written to)
like a `Workspace2D <Workspace2D>`__. By default, if an algorithm
like a :ref:`Workspace2D <Workspace2D>`. By default, if an algorithm
performs an operation and outputs a new workspace, the
`WorkspaceFactory <WorkspaceFactory>`__ will create a Workspace2D *copy*
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.
......
.. _Facilities File:
Facilities_File
Facilities File
===============
Summary
......@@ -8,7 +8,7 @@ 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
to function correctly for your facility then the facilities file should
contain the appropriate definitions as defined below.
File syntax
......@@ -17,10 +17,6 @@ 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"?>
......@@ -34,10 +30,6 @@ component of a facility. A simple facility definition would be
</facilities>
.. raw:: html
</div>
which would define a facility called *BrandNew* with an instrument
called *ABCDEF*. The facilities attributes have the following meanings:
......@@ -51,10 +43,6 @@ called *ABCDEF*. The facilities attributes have the following meanings:
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"?>
......@@ -73,10 +61,6 @@ that instrument rather than the facility as a whole, e.g.
</facilities>
.. raw:: html
</div>
where the attributes are defined as:
- ``shortName`` gives a shortened version of the instrument name
......@@ -99,7 +83,7 @@ Location
The file should be located in the directory pointed to by the
**instrumentDefinition.directory** key in the
`.properties <Properties_File>`__ file.
:ref:`.properties <Properties File>` file.
......
.. _FitConstraint:
FitConstraint
=============
Fit Constraint
==============
.. role:: math(raw)
:format: html latex
..
How constraints on parameters work
----------------------------------
......
.. _Framework Manager:
Framework_Manager
Framework Manager
=================
What is it?
......
......@@ -7,15 +7,15 @@ What is it?
-----------
Geometry is the description of the physical shape (volume) of an object
within a Mantid `instrument <Instrument>`__ and the distances and
within a Mantid :ref:`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
In Mantid we seperate the :ref:`Geometry of the shape <Geometry of Shape>`
of an object from the :ref:`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
......
......@@ -7,7 +7,7 @@ What is it?
-----------
In Mantid we need to be able to define the position and orientation of
every component within an `instrument <instrument>`__.
every component within an :ref:`instrument <instrument>`.
What is a component?
--------------------
......@@ -37,7 +37,7 @@ Object Component
^^^^^^^^^^^^^^^^
An object component is a component that has a
`shape <Geometry_of_Shape>`__. Shapes can contain a lot more information
:ref:`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
......@@ -59,10 +59,10 @@ 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>`__.
an instrument can be found :ref:`here <InstrumentDefinitionFile>`.
.. |SimpleInstrumentTree.png| image:: SimpleInstrumentTree.png
.. |SimpleInstrumentTree.png| image:: ../images/SimpleInstrumentTree.png
.. categories:: Concepts
\ No newline at end of file
.. _Geometry of Shape:
Geometry_of_Shape
Geometry of Shape
=================
What is it?
......@@ -50,7 +50,7 @@ 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>`__.
:ref:`HowToDefineGeometricShape <HowToDefineGeometricShape>`.
......
.. _HowToDefineGeometricShape:
HowToDefineGeometricShape
=========================
How To Define Geometric Shape
=============================
Overview
--------
......@@ -10,7 +10,7 @@ Primitive Shapes
~~~~~~~~~~~~~~~~
There is direct support for defining any of the following geometric
shapes to add `Instrument Definition File <IDF>`__.
shapes to add :ref:`Instrument Definition File <InstrumentDefinitionFile>`.
- Sphere
- Infinite Cylinder
......@@ -35,8 +35,7 @@ algebra that follows the following notation:
+------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
| " " | "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 |
| #. | 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 |
+------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
......@@ -78,10 +77,6 @@ Examples
Defining a sphere
~~~~~~~~~~~~~~~~~
.. raw:: html
<div style="border:1pt dashed black; background:#f9f9f9;padding: 1em 0;">
.. code:: xml
<sphere id="some-sphere">
......@@ -91,10 +86,6 @@ Defining a 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
......@@ -104,10 +95,6 @@ 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">
......@@ -124,9 +111,6 @@ Defining a ball with a hole through it along the x-axis
<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
......@@ -141,10 +125,6 @@ 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">
......@@ -152,17 +132,9 @@ Sphere
<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">
......@@ -172,21 +144,15 @@ Cylinder
<height val="10.2" />
</cylinder>
.. raw:: html
</div>
.. figure:: XMLcylinderDescription.png
.. figure:: ../images/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" >
......@@ -195,17 +161,9 @@ Infinite cylinder
<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">
......@@ -215,27 +173,20 @@ Slice of cylinder ring
<arc val="45.0"/>
</slice-of-cylinder-ring>
.. raw:: html
</div>
This XML element defines a slice of a cylinder ring. Most importantly