Development

[YuuuXie]

Summary

The major changes of this pull request includes

1. Rearrange modules
2. Clean up unused code
3. Merge flare++ into flare
4. Use yaml file for training (same command, different config files for on-the-fly training, offline training, restarting, combine multiple dataset/models)

flare-otf config.yaml

(see flare/examples for the format and parameters for yaml)

Code rearrangement

Following the arrangement in the figure below (also in the README), the modules are rearranged

In the flare folder, we now have

• bffs: gp, mgp, sgp (new, flare_pp python modules), rbcm
• descriptors: env (2+3b)
• io: output, otf_parser
• kernels: our python kernels
• learners: otf, gpfa
• md: nosehoover, npt, lammps (new, modified ASE calculator and MD engine), fake (new, using otf for AIMD trajectory)
• scripts: otf_train (new, training script for yaml config)
• utils: env_getarray, parameter_helper, parameters
• atoms.py: the FLARE_Atoms module, to replace struc.py
• _version.py: place to save the version number

In the root directory, we now have files and folders from flare++ including

• src: c++ source code
• dev: developer's utils for c++ code
• ctests: c++ google tests for c++ code
• cmake files: for compilation of c++ code

Code removal

Modules that are kept in version < 1.0.0, but not in version >= 1.0.0

• flare_io is replaced by ASE's io
• utils/element_coder.py converts chemical symbols to atomic numbers, and can be replaced by functions in ASE
• flare/lammps can be replaced by ASE lammps calculator
• learning_protocal.py not used or tested
• The earliest version of OTF using in-house Verlet MD is degraded, and this brings up the following changes
  • removed md.py, dft_interface folder, utils/md_helper.py
  • merged ase/otf.py into otf.py
  • removed ase/dft.py

Remove corresponding unit tests and test_files

• Unit test scripts: test_OTF_vasp.py, test_ase_otf.py, test_cp2k_util.py, test_flare_io.py, test_struc.py, test_vasp.util.py, test_qe_util.py
• Input, output and log files in test_files folder:
  • Outdated/Unused OTF log files: AgI_snippet.out, gp_test_al.out, otf_output_*.out, sample_al_otf.out
  • Input/Output for dft_interface: cp2k_input_.in, cp2k_output_.out, dummy_vasp.py, qe_input_.in, qe_output_.out, test_POSCAR*, test_vasprun.xml, test_vasprun_h2.xml
  • Others: stress.lammps, BR, GR
  • Added NPT_1.out and VelocityVerlet_1.out log files from the previous ASE_OTF output to test_files, and match the current new OTF output with them in unit test.

Code addition

• LAMMPS calculator: A modified ASE LAMMPS calculator LAMMPS_MOD in flare/ase/lammps.py, such that the same syntax can be used as this example on ASE web, and additionally supports compute, region, dump and other fix such as nvt in the parameter dict.
• LAMMPS MD engine: The module LAMMPS_MD in flare/ase/lammps.py is a child class of ASE MolecularDynamics which can be used in OTF with md_engine = "PyLAMMPS", such that the MD in OTF is done by LAMMPS. Both non-mapped and mapped variances are supported. This serves as a simple version (flightning) of LAMMPS OTF while the lammps is called from python, and the lammps commands are only limited to those supported by LAMMPS_MOD. For more complete version, wait until Anders merges the lmp_otf branch.
• Fake MD engine (offline training): The module FakeMD and FakeDFT in flare/md/fake.py are used for offline training with OTF code by setting md_engine="Fake", which provides a less advanced version of GPFA. Basically we provide an AIMD trajectory to it, and during OTF, it will run a fake md by giving the next frame from the provided trajectory instead of a real MD step. And FakeDFT will give forces of the current frame directly from the provided trajectory instead of a real DFT code.
• Yaml run script: On-the-fly training script in flare/scripts is used for training yaml configuration. After pip installation, the users do flare-otf config.yaml to launch OTF training.
• Unit tests:
  • test_sparse_gp.py, test_parse.py and test_lammps.py are merged from flare++
  • test_sgp_otf.py is for sparse GP with OTF training. It also tests that the OTF with ASE VelocityVerlet has trajectory matching exactly with LAMMPS MD using fix/nve
  • test_fake_otf.py tests OTF training for fake MD
• Yaml config file in examples for unit tests

Staled issues to close

close #24, close #124: in-house MD code has been replaced by ASE MD close #41, close #116, close #129: in-house DFT interfaces have been replaced by ASE calculators close #58: the DFT frames from OTF are saved into an .xyz file, in the PyLAMMPS MD mode, the MD trajectory is saved into an .xyz file. While other information like hyper parameters are still saved in the .out file without need for formatting.

Dependencies

• add pyyaml for yaml support
• add docutils==0.17.1, alabaster==0.7.12, babel, pygments==2.11.2, to remove error from pip installation
• removed pymatgen, which was used in struc.py and vasp_utils.py that have been replaced

TODO (if any)

• [ ] add flare tutorials to unit test
• [ ] update tutorial for yaml configuration

Checklist

Work-in-progress pull requests are encouraged, but please put [WIP] in the pull request title.

Before a pull request can be merged, the following items must be checked:

• [x] Code is in the standard Python style. Run Black on your local machine.
• [x] Docstrings have been added in the Sphinx docstring format.
• [x] Type annotations are highly encouraged.
• [x] Tests have been added for any new functionality or bug fixes.
• [x] All existing tests pass.
• [x] The version number in setup.py is updated. We are using a version number format a.b.c
  • If this PR fixes bugs, update version number to a.b.c+1
  • If this PR adds new features, update version number to a.b+1.0
  • If this PR includes significant changes in framework or interface, update version number to a+1.0.0

Note that the CI system will run all the above checks. But it will be much more efficient if you already fix most errors prior to submitting the PR.