Merge pull request #6 from RDeRenzi/master

Checked up to LiFePo

docs/Install.rst

@@ -38,16 +38,28 @@ XCrysDen  >= 1.0    :mod:`muesr.i_o.xsf.xsf.show_cell` ,            http://www.x
    The muesr distribution ships with a internal version of appdirs which,
    however, may not be up to date.
 
-To compile the python extension you also need the build tools appropriate
+
+Compilation and installation
+----------------------------
+
+This is the hard way. Make your git project muesr directory, move into it and use ::
+
+  git clone https://github.com/bonfus/muesr.git
+
+In order to compile the python extension you also need the build tools appropriate
 for your system (gcc on Linux, XCode on OS X, Visual Studio or gcc on Windows).
 
-If you do not want to compile you can use these wheels:
+If you have all the prerequisites and you are in the muesr directory, type:: 
 
-Installation
-------------
-Use the python way of installing the package.
+   make clean
+   make all
+   make install
 
-Simply type ::
+If you do not want to compile, you can use instead the following `wheels: <https://packaging.python.org/wheel_egg/>`_
+
+Direct installation
+-------------------
+Use the python way of installing the package. First, `download it <https://github.com/bonfus/muesr/archive/master.zip>`_ and unzip. Move to the muesr directory and simply type ::
    
    python setup.py test
    python setup.py install
@@ -89,6 +101,11 @@ Muesr functions you also need `spglib` and `PyYAML` ::
 
    pip install pyyaml spglib
    
-Now you are ready to go! Why not start with Muesr examples?
+
+Now you are ready to go! Why not start with a look at the first paragraph of the Tutorial_ and then move directly to the Muesr Examples_?
+
+.. _Tutorial: ../html/Tutorial.html
+.. _Examples: ../html/Examples.html
+
 
 

docs/LiFePO4.rst

@@ -15,8 +15,8 @@ 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
+   :lines: 11-17
+   :lineno-start: 11
    :language: python
 
 
@@ -44,14 +44,14 @@ We can import these data from a CIF file using the function
    :language: python
 
 
-The next step is setting the the definition of the magnetic order. This 
+The next step is the definition of the magnetic order. This 
 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.
-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.
+will let you specify the Fourier components and the propagation vector.
+
+We want to describe LiFePo anti-ferromagnetic order in which the
+iron moments, 4.19 :math:`\mu_{\mathrm{B}}` in magnitude, lie along the :math:`y` axis. We do this by defining a `ferromagnetic order` (propagation vector **k** = 0), with a basis of four moments. If you run the code the full output below allows you to recognize the input that you have to provide fromthe function prompts.  
 
 .. literalinclude:: ../examples/LiFePO4/run_example.py
    :lines: 43-61
@@ -95,8 +95,8 @@ 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**.
+site, contain the total, dipolar, Lorentz and Contact contributions in
+Tesla (in the present case, an antiferromagnet in zero external field, with no Fermi contact term, only the dipolar field is obtained).
 
 The next four lines of code print the results of the simulation in T/:math:`\mu_{\mathrm{B}}` 
 
@@ -105,12 +105,23 @@ The next four lines of code print the results of the simulation in T/:math:`\mu_
    :lineno-start: 84
    :language: python
 
+You should now see the following self explaining result 
+
+::
+
+   (array([-0.15540174, -0.12234256, -0.02399385]), 'Norm  0.1992')
+   (array([ -1.32075572e-17,  -1.24059244e-01,  -1.10237957e-19]), 'Norm  0.1241')  
+   (array([ -5.22880379e-18,  -1.80946551e-01,   3.16831013e-18]), 'Norm  0.1809')
+   (array([-0.1333684 , -0.11733706, -0.03497624]), 'Norm  0.1810')"
+
+These are the Cartesian components and modulus of the local field at the four Sugiyama sites, in Tesla.
 
 .. note::   **The results are always** reported in the **Cartesian** 
             coordinate system defined by the lattice vectors of the
             crystal.
 
 
+
 Programmatic magnetic order definition
 ---------------------------------------
 

docs/Tutorial.rst

@@ -9,11 +9,26 @@ To proficiently use :py:mod:`~muesr` a basic knowledge of python is
 strongly suggested. There are plenty of tutorial out there in the web, pick
 one and get familiar with the basic python syntax before going forward.
 
+To use :py:mod:`~muesr` you must be familiar with python. An interactive shell like ipython or jupyter can help a lot but it is not needed.
+
+To be pedantic, you can
+
+1. Run the commands listed below in an ipython console
+2. Write these commands in a example.py file and run by the command ::
+  python example.py
+3. Use the muesr gui (which implies having what?)
+4. Use `Mantid <https://www.mantidproject.org/Main_Page>`_, that contains a muesr library
+
+
+
 
 First steps with muesr
 ---------------------------
+Find below a tutorial description of the main functions. An alternative way to familiarise with muer is to run directly the examples_ first and then come back here for a more systematic introduction.
+
+.. _examples: ../html/Examples.html
 
-Definig the sample
+Defining the sample
 +++++++++++++++++++++++++++++++++
 
 The fundamental component of Muesr is the :py:class:`~muesr.core.sample.Sample` object.
@@ -251,11 +266,11 @@ the muon is automatically placed in the center of the supercell.
    sampling outside the supercell size you can use the python
    function `find_largest_sphere` in the LFC python package.
 
+
 .. warning::
    If the Lorentz sphere does not fit into the supercell, the results 
    obtained with this function are not accurate!
 
-
 The `results` variable now contains a list of 
 :py:class:`~muesr.core.magmodel.LocalField` objects.
 However, if you print the `results` variable you'll see something that looks like

docs/index.rst

@@ -6,7 +6,7 @@
 Welcome to MuESR's documentation!
 =================================
 
-MuESR (Magneti strtucture and mUon Embedding Site Refinement) is a tool 
+MuESR (Magnetic structure and mUon Embedding Site Refinement) is a tool 
 to identify muon sites and analize local fields for a given magnetic 
 structure quickly and effectively.
 

examples/LiFePO4/run_example.py

@@ -96,18 +96,19 @@
 smpl.new_mm()
 
 # The new magnetic order is automatically selected.
-#  one can get the current magnetic model with the
-#  property "mm". 
+# One can obtain the current magnetic model with the
+#  property "mm". E.g. smpl.mm.k prints the k-vector, etc. 
 
-# Set a description for the magnetic order
+# Set a description for the magnetic order 
 smpl.mm.desc = "Ferromagnetic"
+# Remember: anti-ferro = ferro with a bassis
 
-# the k property can provides and set the propagation vector,
-#  always defined in reciprocal lattice units (r.l.u.).
+# The smpl.mm.k property can also set the propagation vector,
+#  in reciprocal lattice units (r.l.u.).
 smpl.mm.k=np.array([0.,0.,0.])
 
-# Define Fourier components, in CARTESIAN coordinates and bhor magnetons!
-#  if this is done in the script, the components for all the atoms must be set.
+# Now define Fourier components (in CARTESIAN coordinates and Bohr magnetons);
+#  the components must be set for all the atoms in a cell (28 in the present case).
 FCs = np.array([[ 0.00+0.j,  4.19+0.j,  0.00+0.j],
        [ 0.00+0.j, -4.19+0.j,  0.00+0.j],
        [ 0.00+0.j, -4.19+0.j,  0.00+0.j],
@@ -137,7 +138,7 @@
        [ 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 Fourier components, by default in Cartesian coordinates.
+# Set the Fourier components, by default in Cartesian coordinates.
 smpl.mm.fc_set(FCs)