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,
*  apparent crystalline sizes,
*  phase fractions

are hardcoded next to the graph of "Yobs", "Ycal" and "Yobs-Ycal".
Two images are saved:
* Truncated graph enhanced with refined parameters.
* Full graph without distractions.
* Both graphs are displayed in reciprocal space.

.. image:: https://github.com/pgarbus/magnetmatter/blob/master/magnetmatter/plot_prf_examples/8nm.png?raw=true

.. image:: https://github.com/pgarbus/magnetmatter/blob/master/magnetmatter/plot_prf_examples/8nm_plain.png?raw=true

see section `HOW SHOULD FILES BE ORGANIZED`_ to understand how your files should be organized. The example folders shown are possible to download.

TOC:

* `INSTALLATION`_
* `HOW TO USE`_
* `HOW SHOULD FILES BE ORGANIZED`_
* `NEW FORMAT OF PCR FILE`_
* `LaTeX FORMAT OF PHASENAMES`_
* `REPOSITORY`_
* `TODO`_


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

This installation assumes that you have access to python3 (version > 3.6).
If on Ubuntu/MacTos, python 2.7 will be preinstalled. Then use "python3" and "pip3" for all purposes. Otherwise "python" and "pip" will be enough. Check version of python installation by typing "python --version" into command prompt or terminal.

Before installing, try

::

   $ pip search magnetmatter

and you should see

* "magnetmatter (?.?.?)  - Visualization of FullProf-refined neutron and X-ray powder diffraction 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
==========

Initiate python in a terminal or use your favorite editor. Then type

::

    >>> import magnetmatter as mm

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
   >>> mm.plot_prf(path)

By default printsize = "two_in_docx" and xlim = (2.8,3.6).
The xlim parameter (values in reciprocal space) truncates the enhanced graph.
The default printed size is approximately 8 cm (two plots fit into a docx document).
Other options include:

::

	>>> mm.plot_prf(path, xlim = (2.8,3.6)) # default!
	>>> mm.plot_prf(path, xlim = (1.0,2.0)) # show 1 to 2 invers Å in enhanced graph
	>>> mm.plot_prf(path, xlim = None) # Enhanced graph is not truncated
	>>> mm.plot_prf(path, printsize = "one_in_docx") # 15 cm wide
	>>> mm.plot_prf(path, printsize = "two_in_ppt")  # 17 cm wide
	>>> mm.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 `here <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 and examples can be found at `GitHub <https://github.com/pgarbus/magnetmatter/>`_.

====
TODO
====

* make plot of .dat/.xye file if plot_prf fails to finish.