doc doc doc

docs/FAQ.rst

@@ -1,14 +1,16 @@
-FAQ
-===
+Frequently Asked Questions
+==========================
 
 Symmetry is not correctly recognized by spglib!
-
-   Try lowering the numerical precision threshold by running, 
-   for example, ``sym_search(precision=1e-3)``. If that does not work 
-   I'm keen to think that there is an error in you input structure since
-   spglib is a well tested piece of code. If your input is correct file
-   a bug at spglib.sf.net .
-   
-How do I convert the hyperfine filed to reasonable units?
+  Try lowering the numerical precision threshold by running, 
+  for example, ::
+
+      >>> symsearch(yoursample, precision=1e-3)
+
+  If that does not work I'm keen to think that there is an error in 
+  your input structure since spglib is a well tested piece of code.
+  If your input is correct file a bug at `spglib.sf.net <http://spglib.sf.net>`_.
 
-   See ContactTerm
+
+How do I convert the hyperfine filed to reasonable units?
+  See ContactTerm

docs/Install.rst

@@ -27,7 +27,7 @@ installed to use *all* features of Muesr:
 Package   Version   Required for                                    Package URL
 ========= ========= =============================================== =========================================
 YAML      >= 2.0.0  :mod:`muesr.io.sampleIO`                        http://pyyaml.org/
-Spglib    >= 1.6    :mod:`muesr.utilities.symsearch.sym_search`     http://atztogo.github.io/spglib/
+Spglib    >= 1.6    :mod:`muesr.utilities.symsearch`                http://atztogo.github.io/spglib/
 Sympy     >= 1.0    :mod:`muesr.core.magmodel.SMM`                  http://sympy.org
 appdirs   >= 1.1    :mod:`muesr.settings`               
 XCrysDen  >= 1.0    :mod:`muesr.io.xsf.xsf.show_cell` ,             http://www.xcrysden.org

docs/Intro.rst

@@ -9,6 +9,8 @@ We briefly describe here the interactions involved between the muon and the elec
 
 [TODO]
 
+.. _intro_description_of_magnetic_structures:
+
 Description of Magnetic Structures
 -----------------------------------
 
@@ -53,27 +55,9 @@ Implementation details
 
 :mod:`muesr` is a tool to analyze muon sites and local field contributions
 generated by a known magnetic structure. It is intended to be used in an 
-interactive python environment such ipython or Jupyter notebooks.
+interactive python environment such as `IPython <http://ipython.org>`_ or `Jupyter <http://jupyter.org>`_ notebooks.
 
 Internally, muesr uses Tesla units and Angstrom for lengths if not 
 specified. Magnetic moments are specified in units of Bohr magnetons.
 
-There are many conventions to specify the magnetic structures:
-
-http://magcryst.org/resources/magnetic-coordinates/
-
-At the current stage :py:mod:`muesr` supports:
-
-1. Bohr Magneton/Angstrom units, with x||a, y||b and z||c
-    This is the reduced lattice coordinate system, where the magnetic metric tensor (M) is the same metric used for interatomic distances (G).
-
-2. Bohr Magneton units, with x||a, y||b and z||c
-    This is the crystal-axis coordinate system, where components of the moment are defined by their projections along the lattice basis vectors.
-    If we define L = {{a,0,0},{0,b,0},{0,0,c}}, then the magnetic metric tensor is M = L.G.L^(-1), which is unitless.
-
-In addition, fourier coefficients can also be specified in Cartesian coordinates (the same used to define
-the lattice parameters).
 
-Useful readings
----------------
-http://www.neutron-sciences.org/articles/sfn/pdf/2014/01/sfn201402001.pdf

docs/Source.rst

@@ -26,6 +26,16 @@ Source documentation
    :undoc-members:
    :show-inheritance:
 
+
+:mod:`muesr.core.atoms` -- Defined the unit cell
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: muesr.core.atoms
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
 :mod:`muesr.core.cells` -- Functions for lattice
 +++++++++++++++++++++++++++++++++++++++++++++++++
 

docs/Symmetry.rst

@@ -8,6 +8,6 @@ The symmetry equivalent sites depend indeed only on the symmetry of the
 parent cell. If one consider the symmetry of the magnetic structure and 
 searches for the equivalent muon sites, many of them will be missing.
 The symmetry of every cell can always be identified with the help of 
-the `sym_search` command.
+the `symsearch` command.
 Note however that, when dealing with supercells, some of the symmetry 
 equivalent muon positions must be specified by hand.

docs/Usage.rst

@@ -1,6 +1,89 @@
 Usage
 =====
 
+Defining a sample
+-----------------
+
+This is very easy! You just do: ::
+
+
+    >>> from muesr.core.sample import Sample
+    >>> smp = Sample()
+    >>> smp.name = "My very interesting experiment on ..."
+
+the :py:attr:`~muesr.core.sample.Sample.name` property is optional.
+
+Defining a lattice structure
+----------------------------
+
+This can be done at code level by using the
+:py:attr:`~muesr.core.sample.Sample.cell` property.
+For example ::
+
+    >>> from muesr.core.sample import Sample
+    >>> from muesr.core.atoms import Atoms
+    >>> smp = Sample()
+    >>> smp.cell = Atoms(...)
+
+where the dots replace the :py:class:`~muesr.core.atoms.Atoms` 
+class initialization arguments.
+
+However this can be tedious and error prone. Therefore you are strongly
+suggested to load the lattice informations from a file using use one of
+these functions:
+
+ - :py:func:`~muesr.io.cif.cif.load_cif` for Crystallographic Information Files
+ - :py:func:`~muesr.io.cif.cif.load_mcif` for Magnetic Crystallographic Information Files
+ - :py:func:`~muesr.io.xsf.xsf.load_xsf` for XCrysDen files.
+
+.. note ::
+   For CIF files the symmetry is automatically parsed and set from the file.
+   For MCIF and XSF files it is not set and must be defined by hand or 
+   with the :py:func:`~muesr.utilities.symsearch.symsearch` function 
+   (only available is `spglib` is installed).
+
+
+Defining a magnetic structure
+-----------------------------
+
+In :mod:`muesr` the magnetic structure is defined by the propagation 
+vector `k`, the Fouerier components and the phases 
+(see :ref:`intro_description_of_magnetic_structures`)
+
+The propagation vector 
+
+There are `many <http://magcryst.org/resources/magnetic-coordinates/>`_
+conventions to specify the Fourier components of a magnetic structures:
+
+
+
+At the current stage :mod:`muesr` supports the following coordinate 
+systems:
+
+0. Cartesian system
+    the same used to define the lattice parameters which is implicitly 
+    defined by the lattice vectors.
+
+1. Bohr Magneton/Angstrom units, with x||a, y||b and z||c
+    This is the reduced lattice coordinate system, where the magnetic 
+    metric tensor (M) is the same metric used for interatomic distances 
+    (G).
+
+2. Bohr Magneton units, with x||a, y||b and z||c
+    This is the crystal-axis coordinate system, where components of the
+    moment are defined by their projections along the lattice basis
+    vectors.
+    If we define L = {{a,0,0},{0,b,0},{0,0,c}}, then the magnetic metric
+    tensor is M = L.G.L^(-1), which is unitless.
+
+
+
+
+Useful readings
++++++++++++++++
+ - http://www.neutron-sciences.org/articles/sfn/pdf/2014/01/sfn201402001.pdf
+
+
 Calculate local fields 
 ------------------------
 

muesr/core/atoms.py

@@ -212,9 +212,11 @@ def set_cell(self, cell):
         Set lattice vectors parameters.
         
         :param cell: numpy array of the form
-                     [[v1(1), v1(2), v1(3)],
-                       v2(1), v2(2), v2(3)],
-                       v3(1), v3(2), v3(3)]]
+                     
+                     | [[v1(1), v1(2), v1(3)],
+                     | v2(1), v2(2), v2(3)],
+                     | v3(1), v3(2), v3(3) ]]
+                     
                      where v1, v2, v3 are the lattice vectors.  
         """
 

muesr/utilities/symsearch.py

@@ -19,7 +19,7 @@
 
 
 
-def sym_search(sample, precision=1e-4):
+def symsearch(sample, precision=1e-4):
     """
     Identifies symmetry operations of the unit cell using spglib and 
     update the sample definition.