Better description of LiFePO4 example, initial draft for Iron

docs/Examples.rst

@@ -6,3 +6,4 @@ The following examples provide a broad introduction to MuESR.
 .. toctree::
 
    LiFePO4
+   Iron

docs/Iron.rst

@@ -0,0 +1,15 @@
+Iron
+-------
+
+This is an example to calculate the muon local field at the tetrahedral site(s) in bcc-Fe [Schmolz1986]_.
+
+
+
+.. literalinclude:: ../examples/Fe_bcc/run_example.py
+   :lines: 6-36
+   :lineno-start: 6
+   :language: python
+
+
+
+.. [Schmolz1986] M. Schmolz et.al, Hyperfine Interactions 31 199 (1986)

docs/LiFePO4.rst

@@ -1,34 +1,41 @@
 LiFePO4
--------
+=======
 
 In this example we will go through the relevant lines of the script
 `run_example.py` in the `LiFePO4` directory of the examples.
-This example shows how to calculate the local fields at the muon site in
-ferromagnetic LiFePO4.
+This example shows how to calculate the local fields at the muon sites in
+LiFePO4 and loosely follows the description of Ref. [Sugiyama2011]_.
 
-To prepare the environment, first load the necessary python objects and
-functions of `mod`:muesr.
+Interactive magnetic order definition
+-------------------------------------
+
+In this section we will prepare a script that asks the user to specify
+the magnetic order at runtime and prints the output on screen.
+
+Let's first import the necessary python objects and functions of :py:mod:`muesr`.
 
 .. literalinclude:: ../examples/LiFePO4/run_example.py
    :lines: 14-17
    :lineno-start: 14
    :language: python
 
 
-The sample object holds the following information:
-  * Lattice structure
-  * Magnetic Orders
-  * Muon positions
-  * Symmetry (optional)
-
 To create a new sample definition and initialize it, just do:
 
 .. literalinclude:: ../examples/LiFePO4/run_example.py
    :lines: 28
    :lineno-start: 28
    :language: python
 
-the lattice structure can be imported from a CIF file using the function
+The sample object holds the following information:
+  * Lattice structure
+  * Magnetic Orders
+  * Muon positions
+  * Symmetry (optional)
+
+The lattice structure is orthorhombic, with *Pnma* symmetry and
+lattice parameters :math:`a=10.3244(2), b=6.0064(3), c=4.6901(5)`.
+We can import these data from a CIF file using the function
 :py:func:`~muesr.io.cif.cif.load_cif`:
 
 .. literalinclude:: ../examples/LiFePO4/run_example.py
@@ -42,8 +49,9 @@ can be done interactively during the script execution or programmatically.
 Let's discuss the former case first. The function :py:func:`~muesr.utilities.ms.mago_add`
 will prompt the input and let you specify the Fourier components and the
 propagation vector.
-In this case the iron moments lie along the y axis and are 4.19 Bohr
-magnetons in magnitude.
+Here we want to describe an anti-ferromagnetic order in which the
+iron moments lie along the :math:`y` axis and are
+4.19 :math:`\mu_{\mathrm{B}}` in magnitude.
 
 .. literalinclude:: ../examples/LiFePO4/run_example.py
    :lines: 43-61
@@ -62,6 +70,10 @@ Jun Sugiyama `et al.` [Sugiyama2011]_.
    :language: python
 
 
+.. note:: The muon sites will be automatically placed in the central 
+          unit cell of the supercell that will be used for the subsequent
+          calculations.
+
 The local fields are finally calculated with the :py:func:`~muesr.engines.clfc.locfield`
 command.
 
@@ -70,13 +82,60 @@ command.
    :emphasize-lines: 2
    :lineno-start: 80
    :language: python
+
+.. warning:: * Always check convergence against the supercell size.
+             * Always use a Lorentz sphere that can be inscribed in the 
+               selected supercell.
 
 
+Please see the documentation of the function :py:func:`~muesr.engines.clfc.locfield`
+to see a description of the input parameters. As it is immediately evident,
+the supercell size and the Lorentz radius are not the ideal choices.
+Improving this parameters is left as an exercise to the reader.
+
 The results are stored in a list of 
 :py:class:`~muesr.core.magmodel.LocalField` objects which, for each muon
 site, contain the Total, Dipolar, Lorentz and Contact contributions in
-*Tesla*.
+**Tesla**.
+
+The next four lines of code print the results of the simulation in T/:math:`\mu_{\mathrm{B}}` 
+
+.. literalinclude:: ../examples/LiFePO4/run_example.py
+   :lines: 84-87
+   :lineno-start: 84
+   :language: python
+
+
+.. note::   **The results are always** reported in the **Cartesian** 
+            coordinate system defined by the lattice vectors of the
+            crystal.
+
+
+Programmatic magnetic order definition
+---------------------------------------
+
+As already mentioned above, it's also possible to scepcify a magnetic 
+order programmatically. This can be done with the help of the methods
+:py:attr:`~muesr.core.sample.Sample.new_mm`, 
+:py:attr:`~muesr.core.magmodel.MM.k` and :py:attr:`~muesr.core.magmodel.MM.fc`.
+
+.. literalinclude:: ../examples/LiFePO4/run_example.py
+   :lines: 95-141
+   :emphasize-lines: 2,9,13,47
+   :lineno-start: 95
+   :language: python
+
+Please remember to specify the FC in a 2D array with 3 columns and :math:`N_{\mathrm{Atoms}}`
+rows of complex values.
 
+.. note::  The **propagation vector** is **always** specified in **recirocal lattice units**. 
+           On the other hand, the **Fourier components** can be specified with **three
+           different coordinate system and units**: 
+
+              1. Bohr Magnetons in Cartesian coordinates (Cartesian vector notation)
+              2. Bohr Magnetons/Angstrom along the lattice vectors (Lattice vector notation)
+              3. Modulus (in Bohr Magnetons) along the lattice vectors.
 
+The results can be retrived as described above.
 
 .. [Sugiyama2011] Jun Sugiyama `et al.`, Phys. Rev. B 84, 054430 (2011)

examples/LiFePO4/run_example.py

@@ -78,7 +78,7 @@
 #  
 #  The parameters of the following function are:
 #            sample   type of calculation     supercell    Lorentz radius
-r = locfield( smpl,          's',           [100,100,100],       200)
+r = locfield( smpl,          's',           [100,100,100],       40)
 
 # we report the results in T/mu_B (same as the paper cited above)
 print(r[0].T/4.19, "Norm {: 0.4f}".format(np.linalg.norm(r[0].T/4.19)))
@@ -102,8 +102,8 @@
 # Set a description for the magnetic order
 smpl.mm.desc = "Ferromagnetic"
 
-
-# propagation vector, defined with respoect to the cel lattice vectors
+# the k property can provides and set the propagation vector,
+#  always defined in reciprocal lattice units (r.l.u.).
 smpl.mm.k=np.array([0.,0.,0.])
 
 # Define Fourier components, in CARTESIAN coordinates and bhor magnetons!
@@ -137,12 +137,12 @@
        [ 0.00+0.j,  0.00+0.j,  0.00+0.j],
        [ 0.00+0.j,  0.00+0.j,  0.00+0.j]])
 
-# set the f
+# set the Fourier components, by default in Cartesian coordinates.
 smpl.mm.fc_set(FCs)
 
 
 print('Local fields at the muon sites (Tesla/Bohr Magneton):')
-r = locfield(smpl, 's', [100,100,100],200)
+r = locfield(smpl, 's', [100,100,100],40)
 
 print(r[0].T/4.19, "Norm {: 0.4f}".format(np.linalg.norm(r[0].T/4.19)))
 print(r[1].T/4.19, "Norm {: 0.4f}".format(np.linalg.norm(r[1].T/4.19)))