Package: pylfl
pylflA tool for loss function landscape (LFL) exploration in Python. This package provides a Python interface for the software developed by theWales groupincluding,GMIN,OPTIM,PATHSAMPLEand visualisation usingdisconnectivity graphs.The standard workflow of landscape exploration using the Wales software is the following.Find minima of the LFL using GMINWrite found minima to a pathsample database - this is needed to find transition statesExtend pathsample db and find transition statesVisualise LFL using disconnectivity graph (and calculate AUC of minima)Below, each step is explained in detail. Please note that currently, only cross-entropy and approximated-AUC loss functions are supported. The below also considers a single hidden layer only, but more layers can be added with minimal effort.To install the package, simplypip install pylflYou can load it into your session byimport pylfl as pl1) GMIN: Finding minima of the LFLGMIN requires three files to be present. Adatafile containing GMIN parameters,acoordsfile containing the starting coordinates and a fileMLPdatacontaining the training data. The currently accepted data format requires the true output in the first column, followed by the data, all tab separated. All three files must be present inside the directory from which GMIN is run (and have the exact names specified above).
We provide templates fordataandcoordsfiles, which can be simply generated by:import pylfl as pl
import numpy as np

nin=2 #no. of input nodes
nhidden=3 #no. of hidden nodes
nout=2 #no. of output nodes
dof=17 #degree of freedom = no. of weights
ndata=sum(1 for line in open('MLPdata')) #count no. of data items
f_outname='data'

pl.make_gmin_data(nin,nhidden,nout,ndata=ndata,f_outname=f_outname)
pl.random_starting_coords(dof)Note that information about the individual keywords of thedatafile can be foundhere.
If all the files are present, you can simply executepl.gmin()which will run GMIN and upon completion return a file calledlowestthat contains the energy (loss value) and coordinates of all found minima.2) Initiate PATHSAMPLE databaseTo find transition states, we need to convert the lowest file into a memory-efficient format that can be read by PATHSAMPLE. To do this, we require two more files to be present in the current directory,odata.dumpdataandpathdata.addmin. Again, we provide templates for these and they can be easily generated usingpl.make_odata_dumpdata(nin,nhidden,nout)
pl.make_pathdata_addmin(nin,nhidden,nout)Information about the keywords in both files can be found in the respectiveOPTIM keywordsandPATHSAMPLE keywordsdocumentations.
To run this step, simply executepl.initpdb(dof)This will return four different files: min.data (containing one line per minimum inlowest), ts.data (which will be empty as no transition state search has happened yet), and min.point/ts.points which will contain the coordinates of minima and ts (with ts again being empty for now).3) Extend PATHSAMPLE databaseTo fill ts.data (and ts.points), we need to grow our PATHSAMPLE database using methods described in detail in the PATHSAMPLE documentation. In this step we now need three different files, templates of which can as before simply be obtained bypl.make_pathdata_newconnections(nin,nhidden,nout)
pl.make_odata_connect(nin,nhidden,nout)
pl.make_odata_tspath(nin,nhidden,nout)With the keywords again explained in the respective documentations. The 4 keywordsNEWCONNECTIONS, UNTRAP, CONNECTUNC, CONNECTREGIONare of special importance as they describe the four most commonly used ways to connect minima. Only one can be used at a time, and for a first run,NEWCONNECTIONSshould be used. thepathdata.NEWCONNECTIONSfile requires a path to the OPTIM binary and due to Fortran memory pre-allocation, any line of this pathname can be at most 80 characters in length, with multiple lines separater by+++.This step can then be executed bypl.extendpdb()which will search connections between minima as specified in thepathdata.NEWCONNECTIONSfile. his step can be repeated multiple time with different to continuously grow the PATHSAMPLE database. It is not unusual to se a warning ofNote: The following floating-point exceptions are signalling: IEEE_UNDERFLOW_FLAG IEEE_DENORMALhere.In general, note that thedata,odata,pathdatafiles provided by us are merely first templates to get a system working. As can be seen from the respective documentations, many more options exist to fine-tune the different programs.4) Compute AUC of all minimaTo evaluate the minima for their AUC, the test dataset must now be written to theMLPdatafile (and hence replace the training data). The two files needed for AUC computation areodata.AUCandpathdata.EXTRACTMIN. The templates for both can be obtained viapl.make_odata_auc(nin,nhidden,nout)
pl.make_pathdata_extractmin(nin,nhidden,nout)and the AUC is then computed bypl.auc()This returns the maximum AUC as well as two files, AUCs_unsorted (which is a in-place bijection to the minima in min.data - i.e. the AUC of the minimum in line 25 of min.data is in line 25 of AUCs_unsorted), and AUCs_sorted, which is self-explanatory.5) Disconnectivity graphsTo visualise the landscapes, disconnectivity graphs can be computed usingpl.maketree()with adinfofile. A templatedinfofile can be created bypl.make_dinfo()The disconnectivity graph is written to a file namedtree.ps.