
Installation
============

* Dependencies

 -  numpy, scipy  ->  Mandatory, automatically installed by pip
 -  Pillow        ->  Mandatory, for reading of SAXS images, automatic install by pip
 -  matplotlib    ->  Mandatory, for 3D plots and on Windows
 -  Ipython       ->  Optional, for convenience as a powerfull python shell
 -  gfortran      ->  Optional, without some functions dont work or use a slower python version
 -  xmgrace       ->  Optional, prefered plotting on Unix like (use matplotlib on Windows)

Installation may need root privileges. Use "sudo" on Linux and MacOS if needed.

* Pip installation options (use pip2 or pip3 dependent if you use python2.7 or python3) ::

   sudo pip install jscatter

  As user in home directory (pip default is in ~/.local/).
  No sudo needed, only user privileges::

   pip install jscatter --user

  from a local repository (development versions)::

   pip install jscatter --user --upgrade --pre --find-links /where/the/file/is/saved

   options
   --user       : Install in user directory (folder defined by PYTHONUSERBASE or the default ~/.local)
   --find-links : look in the given path for package links e.g development releases
   --upgrade    : to install upgrades
   --pre        : to install also development versions

* Ubuntu, all Debian related Linux ::

   sudo apt-get install gfortran grace python-matplotlib  # or python3-matplotlib
   sudo pip install ipython
   sudo pip install jscatter

* CentOs, Suse, Fedora ... do same as above but with yum/zypper...

* MacOs, install Homebrew first as given on their web page (see `Homebrew <https://brew.sh/>`_) ::

   # install XQuartz from homebrew or from the AppStore
   sudo brew cask install xquartz
   # install xmgrace and gfortran
   sudo brew install grace gfortran matplotlib
   # then use pip
   sudo pip install ipython
   sudo pip install jscatter


* Windows: `Anaconda <https://www.anaconda.com/distribution>`_ is a python distribution as alternative
  with numpy, scipy, matplotlib, Ipython preinstalled.
  Need of sudo depends on how Anaconda was installed (root or user).
  Maybee the matplotlib backend needs to be configured on Windows to work properly.

  And there was more to adjust, when i stopped waisting my time.
  In my testcase it was a pain, but test and examples work (no Xmgrace, no fortran).

  I strongly advise to **use Linux in a VirtualMachine** as it is easier to install and use.
  ::

   # install jscatter on working anaconda environment
   pip install jscatter

* Manjaro Linux (yaourt asks for permission as root or prepend sudo as above)  ::

   # install gfortran
   yaourt gcc-fortran
   # install xmgrace (only found in AUR), fonts are needed for the interface, fonts are loaded after restart
   yaourt xorg-fonts-75 xorg-fonts-100 grace-openmotif python-matplotlib
   pip install ipython
   pip install jscatter

* CONTIN in DLS module (Only if needed).

  See DLS module documentation for details how to get and compile the original fortran code.

* Testing

  You can test basic functionality of jscatter after installation::

   import jscatter as js
   js.test.doTest()
   #basic graphics and fitting
   js.examples.runExample(7)

  Example 7 shows :
   - 3 sine fit plots with one sine
   - a fit plot with 5 sine curves fitted simultanous
   - a simple plot with 5 points ( phase against Amplitude of the 5 sines)
   - a 3D Sinusoidal fit in matplotlib.

  During development::

   python setup.py test


* Troubleshooting and tips

  If xmgrace is not found by jscatter the path to the executable may be not on your PATH variable.
  Check this by calling xmgrace in a shell.
  Change your PATH in your .bashrc by adding::

   export PATH=/path/to/xmgrace:$(PATH) )

  To open .agr files by klicking add a new file association e.g. to KDE.
   In SystemSettings/FileAssociations add a new type xmgrace.
   Inside this add FilenamePatterns '*.agr' and similar.

   In 'ApplicationPreferenceOrder' add xmgrace and edit this new application :
    In General :  edit name to "xmgrace" (keep it).
    In Application : edit name to "xmgracefree" and command to "xmgrace -free".
    This will open files in free floating size format.
   In 'ApplicationPreferenceOrder' add again application xmgrace (no changes)
   The second opens files in fixed size format (no '-free').



