Previous Section - SPPARKS Website - SPPARKS Documentation - SPPARKS Commands - Next Section

8. Modifying & extending SPPARKS

SPPARKS is designed in a modular fashion so as to be easy to modify and extend with new functionality.

In this section, changes and additions users can make are listed along with minimal instructions. If you add a new feature to SPPARKS and think it will be of interest to general users, we encourage you to submit it to the developers for inclusion in the released version of SPPARKS.

The best way to add a new feature is to find a similar feature in SPPARKS and look at the corresponding source and header files to figure out what it does. You will need some knowledge of C++ to be able to understand the hi-level structure of SPPARKS and its class organization, but functions (class methods) that do actual computations are written in vanilla C-style code and operate on simple C-style data structures (vectors and arrays).

Most of the new features described in this section require you to write a new C++ derived class. Creating a new class requires 2 files, a source code file (*.cpp) and a header file (*.h). The derived class must provide certain methods to work as a new option. Depending on how different your new feature is compared to existing features, you can either derive from the base class itself, or from a derived class that already exists. Enabling SPPARKS to invoke the new class is as simple as adding two lines to the style_user.h file, in the same syntax as other SPPARKS classes are specified in the style.h file.

The advantage of C++ and its object-orientation is that all the code and variables needed to define the new feature are in the 2 files you write, and thus shouldn't make the rest of SPPARKS more complex or cause side-effect bugs.

Here is a concrete example. Suppose you write 2 files app_foo.cpp and app_foo.h that define a new class AppFoo that implements a Monte Carlo model described in the classic 1997 paper by Foo, et al. If you wish to invoke that application in a SPPARKS input script with a command like

app_style foo 0.1 3.5 

you put your 2 files in the SPPARKS src directory and re-make the code. The app_foo.h file should have these lines at the top

#ifdef APP_CLASS

where "foo" is the style keyword to be used in the app_style command, and AppFoo is the class name in your C++ files.

When you re-make SPPARKS, your new application becomes part of the executable and can be invoked with a app_style command like the example above. Arguments like 0.1 and 3.5 can be defined and processed by your new class.

Here is a list of the new features that can be added in this way.

As illustrated by the application example, these options are referred to in the SPPARKS documentation as the "style" of a particular command.

The instructions below give the header file for the base class that these styles are derived from. Public variables in that file are ones used and set by the derived classes which are also used by the base class. Sometimes they are also used by the rest of SPPARKS. Virtual functions in the base class header file which are set = 0 are ones you must define in your new derived class to give it the functionality SPPARKS expects. Virtual functions that are not set to 0 are functions you can optionally define.

Application styles

In SPPARKS, applications are what define the simulation model that is evolved via Monte Carlo algorithms. A new model typically requires adding a new application to the code. Read the doc page for the app_style command to understand the distinction between on-lattice and off-lattice applications. A new off-lattice application can be anything you wish. On-lattice applications are derive from the AppLattice class.

For on-lattice and off-lattice applications, here is a brief description of methods you define in your new derived class. Some of them are required; some are optional. See app.h for details.

input_app additional commands the application defines
grow_app set pointers to per-site arrays used by the application
init_app initialize the application before a run
site_energy compute energy of a site
site_event_rejection peform an event with null-bin rejection (for rKMC)
site_propensity compute propensity of all events on a site (for KMC)
site_event perform an event (for KMC)

Note that two of the methods are required if you want your application to perform kinetic Monte Carlo (KMC) with a solver. One of the methods is required if you want your application to perform rejection KMC (rKMC) with a sweep method.

The constructor for your application class also needs to define, to insure proper operation with the "KMC solvers'_solve.html and rejection KMC sweep methods. These are the flags, all of which have default values set in app_lattice.cpp:

ninteger how many integer values are defined per site
ndouble how many floating point values are defined per site
delpropensity how many neighbors away values are needed to compute propensity
delevent how many neighbors away may the value can be changed by an event
allow_kmc 1 if methods are provided for KMC
allow_rejection 1 if methods are provided for rejection KMC
allow_masking 1 if rKMC method supports masking
numrandom # of random numbers used by the site_event_rejection method

Diagnostic styles

Diagnostic classes compute some form of analysis periodically during a simulation. See the diag_style command for details.

To add a new diagnostic, here is a brief description of methods you define in your new derived class. Some of them are required; some are optional. See diag.h for details.

init setup the computation
compute perform the analysis computation
stats_header what to add to statistics header for this diagnostic
stats fields added to statistics by this diagnostic

Input script commands

New commands can be added to SPPARKS input scripts by adding new classes that have a "command" method and are listed in the Command sections of style_user.h (or style.h). For example, the shell commands (cd, mkdir, rm, etc) are implemented in this fashion. When such a command is encountered in the SPPARKS input script, SPPARKS simply creates a class with the corresponding name, invokes the "command" method of the class, and passes it the arguments from the input script. The command method can perform whatever operations it wishes on SPPARKS data structures.

The single method your new class must define is as follows:

command operations performed by the new command

Of course, the new class can define other methods and variables as needed.

Solve styles

In SPPARKS, a solver performs the kinetic Monte Carlo (KMC) operation of selecting an event from a list of events and associated probabilities. See the solve_style command for details.

To add a new KMC solver, here is a brief description of methods you define in your new derived class. Some of them are required; some are optional. See diag.h for details.

Here is a brief description of methods you define in your new derived class. All of them are required. See solve.h for details.

clone make a copy of the solver for use within a sector of the domain
init initialize the solver
update update one or more event probabilities
resize change the number of events in the list
event select an event and associated timestep

(Foo) Foo, Morefoo, and Maxfoo, J of Classic Monte Carlo Applications, 75, 345 (1997).