Index: doc/ref/index.rst
===================================================================
--- doc/ref/index.rst	(revision 7bb290c023a5380c0dbdd211a4aec8925839e3da)
+++ doc/ref/index.rst	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -8,3 +8,4 @@
 
    intro.rst
+   magnetism.rst
    refs.rst
Index: doc/ref/intro.rst
===================================================================
--- doc/ref/intro.rst	(revision 61ba6233ec36e842d625c589deec77f689b2a9b6)
+++ doc/ref/intro.rst	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -44,6 +44,4 @@
 ($x$) axis of the plane of the detector.
 
-For information about polarised and magnetic scattering, see here_.
+For information about polarised and magnetic scattering, see :ref:`magnetism`.
 
-
-.. _here: polar_mag_help.html
Index: doc/ref/magnetism.rst
===================================================================
--- doc/ref/magnetism.rst	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
+++ doc/ref/magnetism.rst	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -0,0 +1,96 @@
+.. _magnetism:
+
+Polarisation/Magnetic Scattering
+=======================================================
+
+Magnetic scattering is implemented in seven (2D) models
+
+*  :ref:`sphere`
+*  :ref:`core-shell-sphere`
+*  :ref:`core-multi-shell`
+*  :ref:`cylinder`
+*  :ref:`parallelepiped`
+
+In general, the scattering length density (SLD = $\beta$) in each region where the
+SLD is uniform, is a combination of the nuclear and magnetic SLDs and, for polarised
+neutrons, also depends on the spin states of the neutrons.
+
+For magnetic scattering, only the magnetization component $\mathbf{M_\perp}$
+perpendicular to the scattering vector $\mathbf{Q}$ contributes to the the magnetic
+scattering length.
+
+
+.. figure::
+    img/mag_vector.bmp
+
+The magnetic scattering length density is then
+
+.. math::
+    \beta_M = \dfrac{\gamma r_0}{2\mu_B}\sigma \cdot
+    \mathbf{M_\perp} = D_M\sigma \cdot \mathbf{M_\perp}
+
+where $\gamma = -1.913$ is the gyromagnetic ratio, $\mu_B$ is the
+Bohr magneton, $r_0$ is the classical radius of electron, and $\sigma$
+is the Pauli spin.
+
+Assuming that incident neutrons are polarized parallel (+) and anti-parallel (-)
+to the $x'$ axis, the possible spin states after the sample are then
+
+No spin-flips (+ +) and (- -)
+
+Spin-flips    (+ -) and (- +)
+
+.. figure::
+    img/M_angles_pic.bmp
+
+If the angles of the $Q$ vector and the spin-axis $x'$ to the $x$ - axis are
+$\phi$ and $\theta_{up}$, respectively, then, depending on the spin state of the
+neutrons, the scattering length densities, including the nuclear scattering
+length density ($\beta_N$) are
+
+.. math::
+    \beta_{\pm\pm} =  \beta_N \mp D_M M_{\perp x'}
+    \text{ when there are no spin-flips}
+
+and
+
+.. math::
+    \beta_{\pm\mp} =  -D_M (M_{\perp y'} \pm iM_{\perp z'})
+    \text{ when there are}
+
+where
+
+.. math::
+    M_{\perp x'} = M_{0q_x}\cos(\theta_{up})+M_{0q_y}\sin(\theta_{up}) \\
+    M_{\perp y'} = M_{0q_y}\cos(\theta_{up})-M_{0q_x}\sin(\theta_{up}) \\
+    M_{\perp z'} = M_{0z} \\
+    M_{0q_x} = (M_{0x}\cos\phi - M_{0y}\sin\phi)\cos\phi \\
+    M_{0q_y} = (M_{0y}\sin\phi - M_{0x}\cos\phi)\sin\phi
+
+Here, $M_{0x}$, $M_{0x}$, $M_{0z}$ are the x, y and z components
+of the magnetization vector given in the laboratory xyz frame given by
+
+.. math::
+    M_{0x} = M_0\cos\theta_M\cos\phi_M \\
+    M_{0y} = M_0\sin\theta_M \\
+    M_{0z} = -M_0\cos\theta_M\sin\phi_M
+
+and the magnetization angles $\theta_M$ and $\phi_M$ are defined in
+the figure above.
+
+The user input parameters are:
+
+===========   ================================================================
+ M0_sld        = $D_M M_0$
+ Up_theta      = $\theta_up$
+ M_theta       = $\theta_M$
+ M_phi         = $\phi_M$
+ Up_frac_i     = (spin up)/(spin up + spin down) neutrons *before* the sample
+ Up_frac_f     = (spin up)/(spin up + spin down) neutrons *after* the sample
+===========   ================================================================
+
+.. note::
+    The values of the 'Up_frac_i' and 'Up_frac_f' must be in the range 0 to 1.
+
+.. note::
+    This help document was last changed by Steve King, 02May2015
Index: sasmodels/models/core_multi_shell.py
===================================================================
--- sasmodels/models/core_multi_shell.py	(revision 40a87fa5096610e24c3ead10299f609e99f093f2)
+++ sasmodels/models/core_multi_shell.py	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -26,5 +26,5 @@
 
 For information about polarised and magnetic scattering, see
-the :doc:`magnetic help <../sasgui/perspectives/fitting/mag_help>` documentation.
+the :ref:`magnetism` documentation.
 
 Our model uses the form factor calculations implemented in a c-library provided
Index: sasmodels/models/core_shell_sphere.py
===================================================================
--- sasmodels/models/core_shell_sphere.py	(revision 40a87fa5096610e24c3ead10299f609e99f093f2)
+++ sasmodels/models/core_shell_sphere.py	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -4,4 +4,7 @@
 This model provides the form factor, $P(q)$, for a spherical particle with
 a core-shell structure. The form factor is normalized by the particle volume.
+
+For information about polarised and magnetic scattering, see
+the :ref:`magnetism` documentation.
 
 Definition
Index: sasmodels/models/cylinder.py
===================================================================
--- sasmodels/models/cylinder.py	(revision 40a87fa5096610e24c3ead10299f609e99f093f2)
+++ sasmodels/models/cylinder.py	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -3,4 +3,6 @@
 r"""
 The form factor is normalized by the particle volume V = \piR^2L.
+For information about polarised and magnetic scattering, see
+the :ref:`magnetism` documentation.
 
 Definition
Index: sasmodels/models/fuzzy_sphere.py
===================================================================
--- sasmodels/models/fuzzy_sphere.py	(revision 40a87fa5096610e24c3ead10299f609e99f093f2)
+++ sasmodels/models/fuzzy_sphere.py	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -1,5 +1,5 @@
 r"""
 For information about polarised and magnetic scattering, see
-the :doc:`magnetic help <../sasgui/perspectives/fitting/mag_help>`
+the :ref:`magnetism`
 documentation.
 
Index: sasmodels/models/multilayer_vesicle.py
===================================================================
--- sasmodels/models/multilayer_vesicle.py	(revision 40a87fa5096610e24c3ead10299f609e99f093f2)
+++ sasmodels/models/multilayer_vesicle.py	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -13,5 +13,5 @@
     Geometry of the multilayer_vesicle model.
 
-See the :ref:`core-shell` model for more documentation.
+See the :ref:`core-shell-sphere` model for more documentation.
 
 The 2D scattering intensity is the same as 1D, regardless of the orientation
@@ -28,5 +28,5 @@
 
 For information about polarised and magnetic scattering, see
-the :doc:`magnetic help <../sasgui/perspectives/fitting/mag_help>` documentation.
+the :ref:`magnetism` documentation.
 
 This code is based on the form factor calculations implemented in the NIST
Index: sasmodels/models/parallelepiped.py
===================================================================
--- sasmodels/models/parallelepiped.py	(revision 40a87fa5096610e24c3ead10299f609e99f093f2)
+++ sasmodels/models/parallelepiped.py	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -3,4 +3,6 @@
 r"""
 The form factor is normalized by the particle volume.
+For information about polarised and magnetic scattering, see
+the :ref:`magnetism` documentation.
 
 Definition
Index: sasmodels/models/sphere.py
===================================================================
--- sasmodels/models/sphere.py	(revision 40a87fa5096610e24c3ead10299f609e99f093f2)
+++ sasmodels/models/sphere.py	(revision 9f60c06d85ba919d831dd8784f26618e41931862)
@@ -1,5 +1,5 @@
 r"""
 For information about polarised and magnetic scattering, see
-the :doc:`magnetic help <../sasgui/perspectives/fitting/mag_help>`
+the :ref:`magnetism` documentation.
 documentation.
 
