# pyfplo

## Introduction

### General

The python extension pyfplo exposes some of the functionality of the FPLO package to python. Among the main features are input management (write and read of `=.in`), the easy creation of FPLO band/bandweight type files, the python version of faddwei and the slabify module, which allows to map Wannier function models onto larger unit cells, finite slabs and semi infinite slabs. Band structure and spectral densities can be calculated for these super structures. The Berry curvature for Weyl points can be calculated.

There are examples under `..../FPLO22.00-62/DOC/pyfplo/`.

Attention

Many data objects which are returned by the `pyfplo` classes are copies of the underlying c++ objects, which means that:

    bp=sla.BandPlot()
    bp.points.append(...)

will modify the temporary object returned by `pyfplo.common.BandPlot.points` and then discard it. In general, the only supported operation is assignement:

    l=[]
    l.append(['$~G',[0,0,0]])
    l.append(...)
    l.append(...)

    bp=sla.BandPlot()

    bp.points=l

### Installation

Prerequisites:
  `numpy` must be installed on your system. You need to know how to link to lapack, if you want to use it or you use our own copy (which might not as effective).
Prepare Make:
  As with the other fplo make files we need some preliminary setup. This is done by `install/MMakefile` together with the default setup procedure.
Make:
  Go to `PYTHON` under your fplo source tree and run `make` for a python2 package and `make python3` for a python3 package. Note that the example scripts need to be run via `python3 script.py` in the latter case. Answer all questions. As a first trial just hit enter, unless a number is required and see if the installation works. Later try to refine the installation, if needed. The result should be a new directory called `pyfplo`. If you want you can copy the whole `pyfplo` directory somewhere else.

Setup:

  The standard installation procedure of python often requires admin rights, which is inconvenient. We decided to let `pyfplo` reside inside the FPLO source tree. To use it we need to set environment variables. If one copies `pyfplo` somewhere else, one need to adapt `pyfplopath` in the code below. This way different versions can be managed. Use export statements in your batch scripts or local shell environment. (The actual syntax for exporting environment variables depends on the shell you use. There are most certainly already examples in your local shell configuration file.) Add

      # Define the pyfplo path here. The last directory in this path
      # must be the one under which pyfplo resides.

      pyfplopath=.../FPLO/FPLO22.00-62/PYTHON

      # Now export the environment variables.
      export PYTHONPATH=$pyfplopath:$PYTHONPATH

      # uncomment this if you get dynamic link issues
      #export LD_LIBRARY_PATH=$pyfplopath/pyfplo:$LD_LIBRARY_PATH

  to your script or `.bashrc` (or similar config files) where `../FPLO/FPLO22.00-62/PYTHON` is replaced by the actual directory your `pyfplo` sits in. It is important that these variables are set before the python script is executed.

  If more than one `pyfplo` versions exist (which is often the case) it is absolutely necessary to either set the environment via `.bashrc` (and the like) or in job-queue scripts or to wrap `pyfplo` into a shell script which sets `PYTHONPATH` (and perhaps `LD_LIBRARY_PATH`) first and then executes the python script. If `LD_LIBRARY_PATH` is need both variables need to be set correctly otherwise python will import modules from one version and the library from another, which obviously is not good.

  There is yet another possibility, which might work. You could explicitely specify the `pyfplo` version path in the beginning of the script before you import any `pyfplo` modules:

      import sys
      sys.path.insert(0,"PATH_UNDER_WHICH_TO_FIND_pyfplo");

  where `PATH_UNDER_WHICH_TO_FIND_pyfplo` is a path under which your desired pyfplo version sits. This method requires to modify your python scripts, but has its own charm.

  You might want to find out, which version was used. Do this:

      import pyfplo.fedit as fedit
      print '\npyfplo version=: {0}\nfrom: {1}\n'.format(fedit.version,fedit.__file__)