INTRODUCTION
============

Materials science research visualization of FullProf-refined neutron (DMC::SINQ::PSI) and X-ray powder diffraction data.
FullProf .prf, .out and .pcr files are read and informations on:

 *  refined parameters,
 *  phases,
 *  appearent crystalline sizes,
 *  phase fractions

are hardcoded next to the graph of "Yobs", "Ycal" and "Yobs-Ycal".


see section `HOW SHOULD FILES BE ORGANIZED`_ to understand how your files should be organized.

============
INSTALLATION
============

This installation assumes that you have a plain python (version > 3.0) installed that can be accessed through the command prompt.
If on Ubuntu/MacTos, python 2.7 will be preinstalled. Then use "python3" and "pip3" for all purposes.

Before installing, try::

   pip search magnetmatter

and you should see

* "magnetmatter (0.1.0)  - Visualization of neutron and X-ray powder diffraction FullProf-refined data"

now go ahead with the installation::

   pip install magnetmatter

now be patient while "magnetmatter" is installed.
Installation may be longer because dependencies such as:

* "numpy", "pandas", "matplotlib"

are installed if missing.


==========
HOW TO USE
==========

type python/python3 in command prompt. then type::

    import magnetmatter as mogens

Type now::

   path = r"C:\give\a\valid\path\to\folder\with\datasubfolders\"  # Windows
   path = r"C:/give/a/valid/path/to/folder/with/datasubfolders/"  # Linux
   mogens.plot_prf(path)

The default printed size is 8 cm (two plots fit into a docx document). other options include::

	mogens.plot_prf(path, printsize = "two_in_docx") # 8  cm wide - default!
	mogens.plot_prf(path, printsize = "one_in_docx") # 15 cm wide
	mogens.plot_prf(path, printsize = "two_in_ppt")  # 17 cm wide
	mogens.plot_prf(path, printsize = "one_in_ppt")  # 32 cm wide

The files are saved as .png in the "path" folder.

=============================
HOW SHOULD FILES BE ORGANIZED
=============================

The script goes into each subfolder and looks for an .out, a .pcr and a .prf file.
If no such files are found (or if indeed multiple files are found), the script will skip the respective folder.
Note the "backup" folder is not mandatory. I like to keep a copy of an uncorrupted .pcr at hand.

The below examples can be downloaded `from <https://github.com/pgarbus/magnetmatter/tree/master/magnetmatter/plot_prf_examples>`_.

::

 │./
 │   CoKa_BB_ISx.irf
 │   CoKa_PB_ISxmm.irf
 │   17nm.png
 │   8nm.png
 │
 ├───17nm
 │   │   size_bigger_10nm.dat
 │   │   size_bigger_10nm.ras
 │   │   size_bigger_10nm_Theta_2-Theta.asc
 │   │   size_bigger_10nm_Theta_2-Theta.raw
 │   │   _gFe2O3_Fe3O4_.out
 │   │   _gFe2O3_Fe3O4_.pcr
 │   │   _gFe2O3_Fe3O4_.prf
 │   │   _gFe2O3_Fe3O4_.sum
 │   │   _gFe2O3_Fe3O4_1.fst
 │   │   _gFe2O3_Fe3O4_1.mic
 │   │   _gFe2O3_Fe3O4_2.fst
 │   │   _gFe2O3_Fe3O4_2.mic
 │   │
 │   └───backup
 │           _gFe2O3_Fe3O4_.pcr
 │
 └───8nm
     │   size_smaller_10nm.dat
     │   size_smaller_10nm.ras
     │   size_smaller_10nm_Theta_2-Theta.asc
     │   size_smaller_10nm_Theta_2-Theta.raw
     │   _gFe2O3_Fe3O4_.out
     │   _gFe2O3_Fe3O4_.pcr
     │   _gFe2O3_Fe3O4_.prf
     │   _gFe2O3_Fe3O4_.sum
     │   _gFe2O3_Fe3O4_1.fst
     │   _gFe2O3_Fe3O4_1.mic
     │   _gFe2O3_Fe3O4_2.fst
     │   _gFe2O3_Fe3O4_2.mic
     │
     └───backup
             _gFe2O3_Fe3O4_.pcr

======================
NEW FORMAT OF PCR FILE
======================

The new FullProf .pcr format is expected.
Make sure that you have this format by using the FullProf toolbar:

* click "EdPCR"
* click "output"
* unclick "Classical Output Format for a Single Pattern in PCR".

==========================
LaTeX FORMAT OF PHASENAMES
==========================

Below is a phase-example from a .pcr file. Note that the phasename is given by "$\gamma$-Fe$_2$O$_3$".
The dollarsigns indicate that LaTeX format should be used for the from dollarsigns-inclosed characters.

::

 !-------------------------------------------------------------------------------
 !  Data for PHASE number:   1  ==> Current R_Bragg for Pattern#  1:     3.75
 !-------------------------------------------------------------------------------
 $\gamma$-Fe$_2$O$_3$
 !
 !Nat Dis Ang Jbt Isy Str Furth        ATZ     Nvk More
   8   0   0   0   0   0   0       1703.3091   0   0
 !Contributions (0/1) of this phase to the  1 patterns
 1
 !Irf Npr Jtyp  Nsp_Ref Ph_Shift for Pattern#  1
   0   7    0      0      0
 ! Pr1    Pr2    Pr3   Brind.   Rmua   Rmub   Rmuc     for Pattern#  1
  0.000  0.000  1.000  1.000  0.000  0.000  0.000
 !
 !
 P 43 21 2                <--Space group symbol
 !Atom   Typ       X        Y        Z     Biso       Occ     In Fin N_t Spc /Codes
 Fe1    Fe      0.74400  0.99600  0.12000  0.10000   1.00000   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 Fe2    Fe      0.62000  0.62000  0.00000  0.10000   0.50000   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 Fe3    Fe      0.36400  0.86700 -0.01600  0.10000   1.00000   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 Fe4    Fe      0.14000  0.14000  0.00000  0.10000   0.16650   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 O1     O       0.61500  0.86900 -0.01400  0.10000   1.00000   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 O2     O       0.11900  0.37700 -0.00500  0.10000   1.00000   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 O3     O       0.13700  0.86100  0.00700  0.10000   1.00000   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 O4     O       0.38300  0.63100 -0.00300  0.10000   1.00000   0   0   0    0
       0.00       0.00     0.00     0.00     0.00
 !-------> Profile Parameters for Pattern #  1
 !  Scale        Shape1      Bov      Str1      Str2      Str3   Strain-Model
   0.90441E-03   0.00000   2.25111   0.00000   0.00000   0.00000       0
   111.00000     0.000   151.000     0.000     0.000     0.000
 !       U         V          W           X          Y        GauSiz   LorSiz Size-Model
   0.000000   0.000000   0.000000   0.00000     0.380097    0.00000   0.0000     0
   0.000000   0.000000   0.000000   0.00000   131.000       0.00000   0.0000
 !     a          b         c        alpha      beta       gamma      #Cell Info
   8.362284   8.362284   8.319425  90.000000  90.000000  90.000000
   11.00000   11.00000   61.00000    0.00000    0.00000    0.00000
 !  Pref1    Pref2      Asy1     Asy2     Asy3     Asy4      S_L      D_L
   0.00000  0.00000  0.00000  0.00000  0.00000  0.00000  0.02957  0.02957
   0.00     0.00     0.00     0.00     0.00     0.00     0.00     0.00

==========
REPOSITORY
==========

The source code can be found at

`Github <https://github.com/pgarbus/magnetmatter/>`_.
