2. Executable

Here we explain how to modify FitSNAP when running as an Executable. First we begin with an explanation of what goes on under the good when running FitSNAP as an executable with

python -m fitsnap3 input.in

There is a certain sequence of functions that is explained here, and coded in fitsnap3/__main__.py. Specifically, the main() function uses the FitSNAP library to execute the following sequence of functions that perform a fit:

from fitsnap3lib.fitsnap import FitSnap

def main():
    snap = FitSnap()
    snap.scrape_configs(delete_scraper=True)
    snap.process_configs(delete_data=True)
    # Good practice after a large parallel operation is to impose a barrier.
    snap.pt.all_barrier()
    snap.perform_fit()
    snap.write_output()

From the above code, it is seen that we first run the fitsnap3lib.initialize.initialize_fitsnap_run() function. This simply prepares necessary imports and outputs settings. The rest of the main program execution relies on functions in the FitSNAP library. These are accessed by declaring a FitSNAP object with

snap = FitSNAP()

This can be achieved in any external python script, provided the necessary imports shown above are used, and instatiating the pt and config objects as we did above. This snap object has functions located in fitsnap3lib.fitsnap, and the code that these functions depends on can be seen by observing fitsnap3lib/fitsnap.py. These functions can be executed in any order desired by the user. The library also provides a deeper level of control, that we will explain in Library. Examples of using the library to perform a variety of tasks outside the usual FitSNAP main program execution are located in https://github.com/FitSNAP/FitSNAP/tree/master/examples/library.

Further explanations on how to modify FitSNAP as an executable are explained below.

2.1. Data & configuration extraction

After creating the FitSNAP object in __main__.py, the first step is scraping the configs. Then we process the configs (calculate the descriptors) with snap.process_configs(). The Calculator class in calculators/calculator.py has a create_a method which allocates the size of the a and b matrices, containing data such as descriptors and target energies/forces. calculators/calculator.py also has a process_configs method which is overwritten by user-defined derived class, e.g. LammpsSnap in lammps_snap.py. The calculator.process_configs method therefore gets directed to the method in the derived class, which depends on the particular calculator being used.

2.2. Modifying the output dataframe

The Pandas dataframe is used for linear solvers to store information about the fit.

The error_analysis function in solvers/solver.py builds a dataframe containing arrays from pt.shared_arrays and pt.fitsnap_dict. If you want to add your own column to the dataframe, it must first be declared/allocated as a pt.fitsnap_dict in calculators/calculator.py, with the pt.add_2_fitsnap function. When extracting LAMMPS data in a particular calculator subclass, there are loops over energy bik rows, force rows, and stress rows. These are located in lammps_snap.py and lammps_pace.py, in the _collect_lammps() function. There it is seen that data is added to the pt.fitsnap_dict['Column_Name'][indices] array, where 'Column_Name' is the name of the new column declared earlier, and 'indices' are the rows of the array.

When adding a new pt.fitsnap_dict, realize that it’s a DistributedList; this means that a list of whatever declared size exists on each proc. There is a method collect_distributed_lists in calculators/calculator.py that gathers all these distributed lists on the root proc.

2.3. Adding new input file keywords

First you need to choose what section the keyword you’re adding is in. For example in the input file you will see a CALCULATOR section. If you want to add a keyword to this section, go to fitsnap3lib/io/sections/calculator_sections/calculator.py, and use the existing keyword examples to add a new keyword. Likewise for other sections such as SOLVER, we edit fitsnap3lib/io/sections/solver_sections/solver.py. If you want to access this keyword later in the FitSNAP code somewhere, it is done with config.sections['SOLVER'].new_keyword for example.

If you want to add new descriptor settings for LAMMPS, e.g. in the BISPECTRUM section, follow the format in io/sections/calculator_sections/bispectrum.py. Then make sure that the new compute setting is used in calculators/lammps_snap.py in the _set_computes function.

2.4. Adding your own Calculator

  • Add a new file like my_calculator.py in fitsnap3lib/io/sections/calculator_sections. Take inspiration from the given basic_calculator.py file.

  • Now add the import for this new calculator in fitsnap3lib/io/sections/section_factory. Your new sub class should show up in the Sections.__subclasses__() method.

  • Your new calculator needs a types attribute so that io.sections.eshift can assign eshifts to types. Add the necessary if statement to io.sections.eshift.

  • Add your calculator keyword name (this looks like calculator=LAMMPSMYCALCULATOR) in calculators.calculator_factory, in the import section at the top.

  • Obviously, now we also need a LammpsMycalculator subclass of the calculator class. Add this in calculators.lammps_mycalculator

  • Edit the create_a function in calculator.py to allocate data necessary for your calculator. Currently the a array is for per-atom quantities in all configs, the b array is for per-config quantities like energy, the c matrix is for per-atom 3-vectors like position and velocity. Other arrays like dgrad can be natoms*neighbors.

2.5. Adding your own Model/Solver

  • Add a new file like mysolver.py in fitsnap3lib/io/sections/solver_sections.

  • Add from fitsnap3lib.io.sections.solver_sections.mysolver import MYSOLVER to header of section_factory.

  • Import your new solver at the header of fitsnap3lib.solvers.solver_factory

  • You will need to declare solver = MYSOLVER in the [SOLVER] section of the input script, similar to adding a new Calculator.