Re #19575 Added SampleDetails reference page

docs/source/api/python/techniques/ISISPowder-GEM-v1.rst

@@ -147,7 +147,7 @@ object which contains the sample properties used when
 whilst focusing.
 
 For more details on the SampleDetails object and how to set
-it see: TODO
+it see: :ref:`isis-powder-diffraction-sampleDetails-ref`
 
 The following parameter is required when calling *set_sample*
 

docs/source/api/python/techniques/ISISPowder-Polaris-v1.rst

@@ -7,7 +7,7 @@ ISIS Powder Diffraction Scripts - POLARIS Reference
 .. contents:: Table of Contents
     :local:
 
-.. _creating_polaris_object-isis-powder-diffraction-ref:
+.. _creating_polaris_object_isis-powder-diffraction-ref:
 
 Creating POLARIS Object
 --------------------
@@ -57,7 +57,7 @@ The following methods can be executed on a POLARIS object:
 - :ref:`set_sample_polaris_isis-powder-diffraction-ref`
 
 For information on creating a POLARIS object see: 
-:ref:`creating_polaris_object-isis-powder-diffraction-ref`
+:ref:`creating_polaris_object_isis-powder-diffraction-ref`
 
 .. _create_vanadium_polaris_isis-powder-diffraction-ref:
 
@@ -147,7 +147,7 @@ object which contains the sample properties used when
 whilst focusing.
 
 For more details on the SampleDetails object and how to set
-it see: TODO
+it see: :ref:`isis-powder-diffraction-sampleDetails-ref`
 
 The following parameter is required when calling *set_sample*
 

docs/source/api/python/techniques/ISISPowder-SampleDetails-v1.rst

+.. _isis-powder-diffraction-sampleDetails-ref:
+
+=========================================================
+ISIS Powder Diffraction Scripts - SampleDetails Reference
+=========================================================
+
+.. contents:: Table of Contents
+    :local:
+
+
+Introduction
+------------
+The sample details object holds the user defined properties of
+the current sample if absorption corrections are required whilst
+focusing. Only specific instruments support sample absorption
+corrections. This can be determined from visiting the 
+instrument reference:
+:ref:`instrument_doc_links_isis-powder-diffraction-ref`. 
+If the instrument has a *set_sample_details* method it supports sample 
+absorption corrections.
+
+Before you can use absorption corrections you will need to:
+- :ref:`create_sampleDetails_object_isis-powder-diffraction-ref`
+- :ref:`set_material_sample_details_isis-powder-diffraction-ref`
+
+Optionally you may also:
+
+- :ref:`set_material_properties_sampleDetails_isis-powder-diffraction-ref`
+
+.. _create_sampleDetails_object_isis-powder-diffraction-ref:
+
+Create SampleDetails Object
+------------------------------
+This method assumes you are familiar with the concept of objects in Python.
+If not more details can be read here: :ref:`intro_to_objects-isis-powder-diffraction-ref`
+
+For more details on any of the parameters set here see:
+:ref:`Set Sample<algm-SetSample>`.
+
+**Note: this assumes a cylinder geometry**
+
+To create a SampleDetails object the following parameters of the 
+sample geometry are required:
+
+- :ref:`height_sampleDetails_isis-powder-diffraction-ref` - Cylinder height
+- :ref:`radius_sampleDetails_isis-powder-diffraction-ref` - Cylinder radius
+- :ref:`center_sampleDetails_isis-powder-diffraction-ref` - List of x, y, z 
+  positions of the cylinder
+
+Example
+^^^^^^^
+
+.. code-block:: Python
+
+    from isis_powder import SampleDetails
+
+    cylinder_height = 3.0
+    cylinder_radius = 2.0
+    cylinder_position = [0.0, 0.0, 0.2]
+    sample_obj = SampleDetails(height=cylinder_height, radius=cylinder_radius,
+                               center=cylinder_position)
+
+.. _height_sampleDetails_isis-powder-diffraction-ref:
+
+height
+^^^^^^^
+The height of the sample cylinder in cm. This must be a number
+which is greater than 0.
+
+Example Input:
+
+.. code-block:: Python
+
+    sample_obj = SampleDetails(height=5.0, ...)
+
+.. _radius_sampleDetails_isis-powder-diffraction-ref:
+
+radius
+^^^^^^
+The radius of the sample cylinder in cm. This must be a number
+which is greater than 0.
+
+Example Input:
+
+.. code-block:: Python
+
+    sample_obj = SampleDetails(radius=5.0, ...)
+
+.. _center_sampleDetails_isis-powder-diffraction-ref:
+
+center
+^^^^^^
+The center of the sample cylinder as defined by X, Y and Z
+co-ordinates. This co-ordinates must be numeric.
+
+Example Input:
+
+.. code-block:: Python
+
+    sample_obj = SampleDetails(center=[-1.0, 0.0, 1.0], ...)
+
+.. _set_material_sample_details_isis-powder-diffraction-ref:
+
+Setting the material
+--------------------
+Having successfully defined the geometry 
+(see: :ref:`create_sampleDetails_object_isis-powder-diffraction-ref`)
+we now must set the material of the sample. 
+
+This can only be set once per object without explicitly calling 
+the reset method or constructing a new object (which is preferred)
+see: :ref:`changing_sample_properties_sampleDetails_isis-powder-diffraction-ref`
+
+The following properties are required to set the sample material:
+
+- :ref:`chemical_formula_sampleDetails_isis-powder-diffraction-ref`
+- :ref:`number_density_sampleDetails_isis-powder-diffraction-ref`
+  (Optional if *chemical_formula* is an element, otherwise mandatory).
+
+Example
+^^^^^^^
+
+.. code-block:: Python
+
+    sample_obj.set_material(chemical_formula="V")
+    # OR
+    sample_obj.set_material(chemical_formula="VNb", number_density=123)
+
+.. _chemical_formula_sampleDetails_isis-powder-diffraction-ref:
+
+chemical_formula
+^^^^^^^^^^^^^^^^
+The chemical formula of this material. Isotopes can be defined
+by the ratios as well. For example V 95.1% Nb 4.9% can be 
+expressed as *V0.951 Nb0.049*.
+
+See: :ref:`SetSampleMaterial <algm-SetSampleMaterial>` for 
+more details.
+
+Example Input:
+
+.. code-block:: Python
+
+    sample_obj.set_material(chemical_formula="V")
+    # Or
+    sample_obj.set_material(chemical_formula="V0.951 Nb0.049", ...)
+
+.. _number_density_sampleDetails_isis-powder-diffraction-ref:
+
+number_density
+^^^^^^^^^^^^^^
+This parameter defines the number density of the property.
+When :ref:`chemical_formula_sampleDetails_isis-powder-diffraction-ref`
+defines an element this can automatically be calculated by Mantid.
+
+If :ref:`chemical_formula_sampleDetails_isis-powder-diffraction-ref`
+is not an element the user must enter this value.
+
+Example Input:
+
+.. code-block:: Python
+
+    sample_obj.set_material(number_density=0.123, ...)
+
+.. _set_material_properties_sampleDetails_isis-powder-diffraction-ref:
+
+Setting material properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Advanced material properties can be optionally set instead of letting 
+Mantid calculate them. For more details see:
+:ref:`SetSampleMaterial<algm-SetSampleMaterial>`
+This can only be set once per object without 
+explicitly calling the reset method or constructing a new object (which is preferred)
+see: :ref:`changing_sample_properties_sampleDetails_isis-powder-diffraction-ref`
+
+These properties are:
+
+- :ref:`absorption_cross_section_sampleDetails_isis-powder-diffraction-ref`
+- :ref:`scattering_cross_section_sampleDetails_isis-powder-diffraction-ref`
+
+Example
+^^^^^^^
+
+.. code-block:: Python
+
+        sample_obj.set_material_properties(absorption_cross_section=123, 
+                                           scattering_cross_section=456)
+
+.. _absorption_cross_section_sampleDetails_isis-powder-diffraction-ref:
+
+absorption_cross_section
+^^^^^^^^^^^^^^^^^^^^^^^^
+The absorption cross section for the sample in barns to use
+whilst calculating absorption corrections.
+
+.. _scattering_cross_section_sampleDetails_isis-powder-diffraction-ref:
+
+scattering_cross_section
+^^^^^^^^^^^^^^^^^^^^^^^^
+The scattering cross section for the sample in barns to use
+whilst calculating absorption corrections.
+
+.. _changing_sample_properties_sampleDetails_isis-powder-diffraction-ref:
+
+Changing sample properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. warning:: This method is not recommended for changing multiple samples. 
+             Instead it is recommended you create a new sample details object
+             if you need to change properties mid way through a script. 
+             See :ref:`create_sampleDetails_object_isis-powder-diffraction-ref`
+             and :ref:`intro_to_objects-isis-powder-diffraction-ref`.
+
+*Note: The geometry of a sample cannot be changed without creating a new 
+sample details object*
+
+Once you have set a material by calling *set_material* or set 
+the properties by calling *set_material_properties* you will 
+not be able to change (or set) these details without first
+resetting the object. This is to enforce the sample properties 
+being set only once so that users are guaranteed of the state. 
+
+To change the chemical material or its advanced properties all 
+*reset_sample_material*. This will reset **all** details (i.e
+advanced properties and chemical properties).
+
+.. code-block:: Python
+
+    sample_obj.reset_sample_material()
\ No newline at end of file

docs/source/api/python/techniques/ISISPowder-Tutorials.rst

@@ -689,7 +689,7 @@ First we need to import the sample details object from ISIS Powder.
 The properties required when creating a SampleDetails 
 object is the geometry of the sample.
 
-**Note this assumes a cylinder currently**
+**Note: this assumes a cylinder geometry**
 
 - *height* - Cylinder height
 - *radius* - Cylinder radius
@@ -741,7 +741,7 @@ Setting material properties
 Advanced material properties can be optionally set instead of letting 
 Mantid calculate them. These properties are:
 
-- *absorption_cross_section* - Attenuation Cross Section
+- *absorption_cross_section* - Absorption Cross Section
 - *scattering_cross_section* - Scattering Cross Section
 
 *Note: This is purely optional and Mantid will calculate these