PyBigDFT Documentation Release 0.1 Luigi Genovese Nov 19, 2018 Contents 1 How to write documentation in this package3 2 Module Members 5 3 Index of the Package 55 4 Indices and tables 59 Python Module Index 61 i ii PyBigDFT Documentation, Release 0.1 This package is a collection of Python Modules that are conceived for pre- and post- processing of BigDFT input and output files. Such modules are supposed to enhance the BigDFT experience by high-level approach. Also, calculators and workflows are supposed to be created and inspected with modules of the PyBigDFT package. The documentation of this package is described in Contents 1 PyBigDFT Documentation, Release 0.1 2 Contents CHAPTER 1 How to write documentation in this package The syntax in the text pages is ReStructured Text format. see this page for examples of the syntax, and this one for a more comprehensive explanation of the syntax. The syntax chosen for the auto-documentation of the Python module is Google Docstring syntax. see the google Docstring example in the Sphinx-napoleon package. 1.1 How to generate documentation • Install sphinx package and the requirements written in the file source/requirements.txt of provided with the sources of PyBigDFT. • Copy the quick build file Makefile-sphinxbuild of the PyBigDFT source directory into Makefile • Run the command make html • The documentation of the package can be explored starting from the file build/html/index.html. 1.2 Automodule generation The directive to be used is mainly the automodule one, see this page: 3 PyBigDFT Documentation, Release 0.1 4 Chapter 1. How to write documentation in this package CHAPTER 2 Module Members Input file representation and usage from Python 2.1 BigDFT.Inputfiles module Handling of the input options This module contain the useful quantities to deal with the preparation and the usage of inputfiles for BigDFT code. The main object is the Inputfile class, which inherits from a python dictionary. Such inheritance is made possible by the internal representation of the BigDFT inputfile, which employs the YAML syntax. This means that there is a one-to-one correspondence between a python dictionary and a BigDFT inputfile. class BigDFT.Inputfiles.Inputfile(*args, **kwargs) Bases: dict The BigDFT inputfile. Principal object needed to run a BigDFT calculation. Might be initialized either from a dictionary, a Logfile instance or a (yaml-compliant) filename path Note: Each of the actions of the module InputActions, which is defined on a generic dictionary, also corresponds to a method of of the Inputfile class, and it is applied to the class instance. Therefore also the first argument of the corresponding action is implicitly the class instance. For the remove() method, the action has to be invoked should come from the InputActions module. Example >>> import InputActions asA , Inputfiles asI >>> inp=I.Inputfile() >>> inp.set_hgrids(0.3) # equivalent to A.set_hgrids(inp,0.3) (continues on next page) 5 PyBigDFT Documentation, Release 0.1 (continued from previous page) >>> inp {'dft': {'hgrids': 0.3}} >>> inp.optimize_geometry() # equivalent to A.optimize_geometry(inp) >>> inp {'dft': {'hgrids': 0.3},'geopt': {'method': 'FIRE','ncount_cluster_x': 50} } >>> inp.remove(A.optimize_geometry) # equivalent to A.remove(inp,A.optimize_ ,!geometry) >>> inp {'dft': {'hgrids': 0.3}} Todo: Consider the possiblity of initializing an Inputfile instance from a yaml file. And also from a Logfile class Input Actions on the BigDFT input file 2.2 BigDFT.InputActions module Actions to define on the Input parameters. This module defines some of the most common actions that a BigDFT user might like to perform on the input file. Such module therefore set some of the keys of the input dictionary to the values needed to perform the operations. Users might also inspire to the actions performed in order to customize the runs in a different way. All the functions of this module have as first argument inp, the dictionary of the input parameters. Many other actions are available in BigDFT code. This module only regroups the most common. Any of these functionalities might be removed from the input file by the remove() function. Note: Any of the action of this module, including the remove() function, can be also applied to an instance of the BigDFT.Inputfiles.Inputfile class, by removing the first argument (inp). This adds extra flexibility as the same method may be used to a dictionary instance or to a BigDFT input files. See the example Example. Note: Each of the actions here must have default value for the arguments (except the input dictionary inp). This is needed for a good behaviour of the function remove. remove(inp, action) Remove action from the input dictionary. set_xc(inp[, xc]) Set the exchange and correlation approximation set_hgrid(inp[, hgrids]) Set the wavelet grid spacing. set_rmult(inp[, rmult, coarse, fine]) Set the wavelet grid extension by modifying the multi- plicative radii. set_atomic_positions(inp[, posinp]) Insert the atomic positions as a part of the input dictio- nary set_mesh_sizes(inp[, ngrids]) Constrain the number of grid points in each direction. optimize_geometry(inp[, method, nsteps]) Optimize the geometry of the system spin_polarize(inp[, mpol]) Add a collinear spin polarization to the system. charge(inp[, charge]) Charge the system charge_and_polarize(inp) Charge the system by removing one electron. Continued on next page 6 Chapter 2. Module Members PyBigDFT Documentation, Release 0.1 Table 1 – continued from previous page set_symmetry(inp[, yes]) Set the symmetry detection for the charge density and the ionic forces and stressdef set_symmetry(inp,yes=True): apply_electric_field(inp[, elecfield]) Apply an external electric field on the system set_random_inputguess(inp) Input orbitals are initialized as random coefficients write_orbitals_on_disk(inp[, format]) Set the code to write the orbitals on disk in the provided format read_orbitals_from_disk(inp) Read the orbitals from data directory, if available write_density_on_disk(inp) Write the charge density on the disk after the last SCF convergence calculate_dipole(inp) Extract the dipole momenet from the total charge den- sity. use_gpu_acceleration(inp) Employ gpu acceleration when available, for convolu- tions and Fock operator change_data_directory(inp[, name]) Modify the name of the data- directory. connect_run_data(inp[, log]) Associate the data of the run of a given logfile to the input by retrieving the data directory name of the logfile. add_empty_SCF_orbitals(inp[, norbs]) Insert norbs empty orbitals in the SCF procedure extract_virtual_states(inp, nvirt[, davidson]) Extract a given number of empty states after the scf cy- cle. set_electronic_temperature(inp[, kT, T]) Define the electronic temperature, in AU (kT) or K (T) calculate_tddft_coupling_matrix(inp[, Perform a casida TDDFT coupling matrix extraction. tda, . ]) BigDFT.InputActions.add_empty_SCF_orbitals(inp, norbs=10) Insert norbs empty orbitals in the SCF procedure Parameters norbs (int) – Number of empty orbitals Warning: In linear scaling case, this is only meaningful for the direct minimization approach. BigDFT.InputActions.apply_electric_field(inp, elecfield=[0, 0, 0.001]) Apply an external electric field on the system Parameters electric (list, float) – Values of the Electric Field in the three directions. Might also be a scalar. BigDFT.InputActions.calculate_dipole(inp) Extract the dipole momenet from the total charge density. Note: This function is useful for the linear scaling setup as the cubic scaling approach always calculates the charge density multipoles. BigDFT.InputActions.calculate_tddft_coupling_matrix(inp, tda=False, rpa=True, fxc=True) Perform a casida TDDFT coupling matrix extraction. Parameters • tda (bool) – when True, Tamm-Dancoff approximation is used for the extraction of the coupling matrix 2.2. BigDFT.InputActions module 7 PyBigDFT Documentation, Release 0.1 • rpa (bool) – when False, the calculation of the RPA term (the linear response of the hartree potential) is switched off • fxc (bool) – when False, the calculation of the fxc term (the linear response of the XC operator) is switched off. Note: The arguments fxc and rpa should not be simultaneously False. Warning: Presently the LR-TDDFT casida fxc is only available for LDA functionals in ABINIT flavour. BigDFT.InputActions.change_data_directory(inp, name=”) Modify the name of the data- directory. Useful to grab the orbitals from another directory than the run name BigDFT.InputActions.charge(inp, charge=-1) Charge the system Parameters charge (int,float) – value of the charge in units of e (the electron has charge -1). Also accept floating point numbers. BigDFT.InputActions.charge_and_polarize(inp) Charge the system by removing one electron. Assume that the original system is closed shell, thus polarize. BigDFT.InputActions.connect_run_data(inp, log=None) Associate the data of the run of a given logfile to the input by retrieving the data directory name of the logfile. Parameters log (Logfile) – instance of a Logfile class BigDFT.InputActions.extract_virtual_states(inp, nvirt, davidson=False) Extract a given number of empty states after the scf cycle. Parameters davidson (bool) – If set to True activates davidson calculation, otherwise Trace Minimization of the Hamiltonian is employed. BigDFT.InputActions.optimize_geometry(inp, method=’FIRE’, nsteps=50) Optimize the geometry of the system Parameters • nsteps (int) – maximum number of atomic steps. • method (str) – Geometry optimizer. Available keys: * SDCG: A combination of Steepest