Development Guide

The important dependencies between the Python modules is illustrated in the following graph:

digraph { node [shape=box,style=solid]; kmc_dirichlet_boundary; kmc_fmm -> kmc_local; kmc_fmm -> kmc_full_long_range; kmc_fmm -> kmc_octal; kmc_fmm -> kmc_fmm_self_interaction; kmc_fmm -> kmc_mpi_decomp; kmc_fmm -> kmc_inject_extract; kmc_fmm -> kmc_fmm_common; kmc_local -> kmc_fmm_common; kmc_full_long_range -> kmc_fmm_common; kmc_octal -> kmc_fmm_common; kmc_mpi_decomp -> kmc_fmm_common; kmc_inject_extract -> kmc_direct; kmc_fmm -> kmc_expansion_tools; kmc_direct -> kmc_expansion_tools; kmc_octal -> kmc_expansion_tools; kmc_inject_extract -> kmc_expansion_tools; }

We now give a brief description of the functionality provided in each module.

kmc_fmm

Provides the main KMCFMM class which, by default, defines the initialise, propose, propose_with_dats and accept interfaces. When initialise is called a FMM solver from PPMD is created and called to compute the initial system energy and construct the initial local expansions. A instance of FMMMPIDecomp is created to handle the MPI decomposition of the domain. As part of the initialisation process the data structures for direct interactions are initialised using kmc_local along with data structures for indirect interactions using kmc_octal. Long range interactions are initialised using kmc_full_long_range and the self interactions are initialised using the kmc_self_interaction module.

Periodic boundary conditions are enacted by splitting the domain into two sets of periodic images. The first is the inner set which is formed from the primary image and its nearest neighbours. In the inner set energy differences from proposed moves are computed by considering the change in potential field of a move. i.e. the difference is calculated in both the indirect and direct parts, as opposed to computing the new energy of the new configuration and subtracting the old energy. In the second “far-field” set of periodic images, the new energy is computed in full for each proposed move. This splitting approach is why the FMM solver from PPMD is used in “27” mode even for the fully periodic case.

kmc_dirichlet_boundary

This is a helper module contains the class MirrorChargeSystem that aids the construction of systems where each input charge is mirrored in the z-direction such that the potential field is zeroed on the z boundaries.

kmc_mpi_decomp

The FMMMPIDecomp class performs a domain decomposition of the domain over the MPI ranks. This decomposition step determines which local expansions are required by each rank by taking into account the maximum move size. This class also provides the setup_propose method which translates passed proposed moves, in either the propose or propose_with_dats format, into an internal format that can be passed to the modules that handle the indirect, direct, long-range and self interaction components.

kmc_octal

The class LocalCellExpansions handles the interactions through local expansions for the primary image and its nearest 26 neighbours. At initialisation the required expansions are copied from the owning rank in the FMM solver using MPI RMA operations. Proposed moves are passed using the format specified in kmc_mpi_decomp.

kmc_local

The class LocalParticleData computes direct interactions between charges. At initialisation particle positions and charges are copied into local data structures. Proposed moves are passed in the standard format specified in kmc_mpi_decomp.

kmc_fmm_self_interaction

When moves are proposed the new energy contains a self interaction contribution that should be subtracted. This module computes the self interactions between the new position and the old images in the primary image and its nearest neighbours. There are no spurious contributions from further away periodic images as these images are handled “in full” by the kmc_full_long_range module.

kmc_full_long_range

Computes the far-field contribution for proposed moves (and initialisation). The main class FullLongRangeEnergy maintains the level zero multipole expansion for the original charge locations in the domain. When a move is proposed the current contribution for the moving charge is subtracted and the new contribution is added. The long range multipole to local operator is applied to give the local expansion for the far-field contribution.

The class also maintains the vector of coefficients that when used in a dot product with the far-field local expansion give the far-field energy contribution. As with the multipole expansion, the current contribution of the moving charge is subtracted from this vector and the new contribution added. The new set of coefficients is then used to compute the proposed far-field contribution.

kmc_inject_extract

Contains a parent class that when inherited adds the propose_inject, inject, propose_extract and extract methods to the KMCFMM class. When extractions/injections are proposed this class uses functionality in kmc_direct to compute the self energy of the involved group of charges. In general, this self energy is non-zero when the group of charges involved contains more than one charge. As we only allow injections and extractions in mirror mode there is always a self energy term.

This module also contains the DiscoverInjectExtract class which, at each iteration, finds empty inject sites and charges that exist on extract sites. Critically, these methods assume that the number of inject and extract sites is small in comparison to the number of charges in the simulation.

kmc_direct

Contains electrostatic solvers for systems containing small numbers of charges. i.e. small enough that direct methods are the most efficient to compute the electrostatic energy of the system. Along with testing, these methods are used to compute the self energy of groups of charges in inject and extract scenarios.

kmc_expansion_tools

Contains methods to generate code that computes and evaluates local and multipole expansions. This functionality should (and is) be merged into PPMD.