Better Fe example and output reference

docs/Iron.rst

@@ -1,15 +1,74 @@
-Iron
--------
-
-This is an example to calculate the muon local field at the tetrahedral site(s) in bcc-Fe [Schmolz1986]_.
+BCC Iron
+---------
 
+This example shows how to calculate the local field at the tetrahedral 
+site(s) in bcc-Fe as descibed in Ref. [Schmolz1986]_.
 
+Let's first load some useful tools.
 
 .. literalinclude:: ../examples/Fe_bcc/run_example.py
-   :lines: 6-36
+   :lines: 6-14
    :lineno-start: 6
    :language: python
 
+the lattice structure and one of the twelve tetrahedral muon sites are
+added to our sample objectc:
+
+.. literalinclude:: ../examples/Fe_bcc/run_example.py
+   :lines: 20-24
+   :lineno-start: 20
+   :language: python
+
+Since the lattice structure was parsed from a CIF file, symmetry information
+are already present in our Sample object. This allows to obtain all the
+twelve tetrahedral sites with the command
+
+.. literalinclude:: ../examples/Fe_bcc/run_example.py
+   :lines: 29
+   :lineno-start: 29
+   :language: python
+
+Finally, we define the ferromagnetci structure with local moments parallel
+to z in Cartesian coordinates.
+
+.. literalinclude:: ../examples/Fe_bcc/run_example.py
+   :lines: 32-37
+   :lineno-start: 32
+   :language: python
+
+The local fields at the muon sites are obtained with the following commands
+
+.. literalinclude:: ../examples/Fe_bcc/run_example.py
+   :lines: 77-78
+   :lineno-start: 77
+   :language: python
+
+By default, for each muon site the contact coupling is set to 0. To obtain
+the total contribution at the muon sites the parameter ACont must be set 
+for all the twelse muon sites (can be different in general).
+
+.. literalinclude:: ../examples/Fe_bcc/run_example.py
+   :lines: 92-102
+   :lineno-start: 92
+   :emphasize-lines: 9
+   :language: python
+
+In the aboce lines we collected the results in numpy arrays to simplify the
+output statements.
+
+
+As discussed in [Schmolz1986]_, "The field contribution at each equivalent site
+is either parallel or antiparallel to the magnetization of the domains" such that
+B_dip(parallel)=-2B_dip(antiparallel) "the average of the dipolar field at these three sites vanishes "
+
+The final print statements shows that this result is actually verified 
+by our calculations.
+
+.. literalinclude:: ../examples/Fe_bcc/run_example.py
+   :lines: 115-123
+   :lineno-start: 115
+   :language: python
+
 
 
 .. [Schmolz1986] M. Schmolz et.al, Hyperfine Interactions 31 199 (1986)

docs/Tutorial.rst

@@ -13,20 +13,20 @@ Definig the sample
 +++++++++++++++++++++++++++++++++
 
 The fundamental component of muesr is the :py:class:`muesr.core.sample.Sample` object.
-You can import and instantiate it like this:
+You can import and initialize it like this:
 
 .. code-block:: python
     
     >>> from muesr.core import Sample
     >>>
     >>> mysample = Sample()
 
-Specifying the atomic structure
+Specifying the lattice structure
 ++++++++++++++++++++++++++++++++++++
 
-The first thing that must be defined is the atomic structure. Muesr uses 
-the ASE :class:`~Atoms` class. You can declare your own, fore example
-like this (Copper in simple cubic lattice)
+The first thing that must be defined is the lattice structure together with
+the atomic positions. Muesr uses the ASE :class:`~Atoms` class. You can 
+declare your own, fore example like this (Copper in simple cubic lattice)
 
 .. code-block:: python
     
@@ -40,7 +40,7 @@ like this (Copper in simple cubic lattice)
 However this is quite tedious and error prone so it is much better to use some
 builtin functions to parse crystallographic files.
 
-At the moment musr can parse XCrysDen files (xsf), CIF (cif) and mCIF (mcif)
+At the moment muesr can parse XCrysDen files (xsf), CIF (cif) and mCIF (mcif)
 files. Here's a few examples:
 
 .. code-block:: python
@@ -74,7 +74,7 @@ Setting muon positions
 When the lattice structure is defined it is possible to specify the
 muon position and the magnetic orders.
 
-To specify the muon position, simply do:
+To specify the muon position, just do:
 
 .. code-block:: python
     

examples/Fe_bcc/reference/run_example.out

@@ -0,0 +1,17 @@
+Using internal LFC library
+Dipolar Field for all the 12 tetrahedral equivalent sites
+[[ 0.       0.       0.26498]
+ [-0.      -0.       0.26498]
+ [-0.       0.      -0.52995]
+ [ 0.       0.      -0.52995]
+ [ 0.       0.       0.26498]
+ [-0.      -0.       0.26498]
+ [ 0.      -0.       0.26498]
+ [-0.      -0.       0.26498]
+ [ 0.       0.      -0.52995]
+ [ 0.       0.      -0.52995]
+ [-0.      -0.       0.26498]
+ [-0.      -0.       0.26498]]
+The Lorentz field is 0.000 0.000 0.731
+The contact field is 1.111 T
+Dipolar average of 1 parallel site and 2 antiparallel sites is 0.00000 T

examples/Fe_bcc/run_example.py

@@ -13,6 +13,8 @@
 from muesr.engines.clfc import find_largest_sphere     # Aids in the calculation of the sphere's radius for the lattice sum.
 from muesr.utilities.muon import muon_find_equiv       # For finding and including the symmetry equivalent muon positions in the calculation 
 
+#
+np.set_printoptions(suppress=True,precision=5)
 
 #    Declare  and load sample 
 fe= Sample()                          
@@ -23,11 +25,12 @@
 
 
 #   Finds and includes the symmetry equivalent positions of the above defined muon.
-#   For this example there are 12 sites "print fe.muons" will show their positions.
+#   For this example there are 12 sites "print (fe.muons)" will show their positions.
 muon_find_equiv(fe)  
 
 
-#   Description of the propagation vector k and fourier components fc with a new magnetic structure declared with fe.new_mm()
+#   Description of the propagation vector k and fourier components fc 
+#   with a new magnetic structure declared with fe.new_mm()
 fe.new_mm()     
 fe.mm.k=np.array([0.0,0.0,0.0])
 fe.mm.fc= np.array([[0.0+0.j, 0.0+0.j, 2.22+0.j],
@@ -75,7 +78,7 @@
 r=locfield(fe, 's', [100, 100, 100] ,radius) 
 
 """
-- The find_largest_sphere func. is an experimental function.This func. must not be used, see documentation. 
+- The find_largest_sphere func. is an experimental function. This func. has not been thoroughly tested, see documentation. 
 -  s is for the summation method used. For help type 'help(locfield)' on the interactive python session after the locfield  must have been imported
 -  [100, 100, 100] defines the supercell for the calculation
 -  radius is the sphere radius
@@ -90,6 +93,7 @@
 B_Lor=np.zeros([len(fe.muons),3])
 B_Cont=np.zeros([len(fe.muons),3])
 B_Tot=np.zeros([len(fe.muons),3])
+
 for i in range(len(fe.muons)):
 	B_dip[i]=r[i].D
 	B_Lor[i]=r[i].L
@@ -98,16 +102,6 @@
 	B_Tot[i]=r[i].T
 
 
-print("Dipolar Field for all the 12 tetrahedral equivalent sites")
-print(B_dip) 
-
-# This is and should be same for all the equivalent sites
-print("The Lorentz field is {}".format(B_Lor[0]))   
-
-print("The contact field is {} T".format(np.linalg.norm(B_Cont[0]))) 
-
-
-
 """
 Quick look on the description of the muon jumps between the tetrahedral sites as 
 discussed in the reference below. "The field contribution at each equivalent site
@@ -118,31 +112,14 @@
 
 """
 
-print("Dipolar average of 1 parallel site and 2 antiparallel sites is {} T".format(np.linalg.norm(B_dip[3]+B_dip[10]+B_dip[11])))
-
-
+print("Dipolar Field for all the 12 tetrahedral equivalent sites")
+print(B_dip) 
 
+# This is and should be same for all the equivalent sites
+print("The Lorentz field is {:4.3f} {:4.3f} {:4.3f}".format(*tuple(B_Lor[0])))
 
+print("The contact field is {:4.3f} T".format(np.linalg.norm(B_Cont[0])))
 
-"""
-- Result on standard output should appear like this:
-Using internal LFC library
-Dipolar Field for all the 12 tetrahedral equivalent sites
-[[  5.92276907e-18   3.82211885e-17   2.64976810e-01]
- [ -2.69848666e-17  -7.10720260e-18   2.64976810e-01]
- [ -1.86130196e-17   4.90398830e-16  -5.29953619e-01]
- [  7.49570991e-16   4.25793961e-16  -5.29953619e-01]
- [  2.85341954e-17   1.46870359e-17   2.64976810e-01]
- [ -9.54449012e-17  -3.56696222e-17   2.64976810e-01]
- [  2.32510025e-17  -9.21149791e-18   2.64976810e-01]
- [ -2.55973467e-17  -3.03263233e-17   2.64976810e-01]
- [  4.74017137e-16   4.22061112e-16  -5.29953619e-01]
- [  4.95076670e-16   4.00493505e-16  -5.29953619e-01]
- [ -2.89631243e-17   4.75531976e-19   2.64976810e-01]
- [ -1.58672778e-17  -1.93742009e-17   2.64976810e-01]]
-The Lorentz field is [ 0.          0.          0.73108635]
-The contact field is 1.11077214797 T
-Dipolar average of 1 parallel site and 2 antiparallel sites is 9.30957573598e-14 T 
+print("Dipolar average of 1 parallel site and 2 antiparallel sites is {:4.5f} T".format(np.linalg.norm(B_dip[3]+B_dip[10]+B_dip[11])))
 
-"""