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 AppStyle(foo,AppFoo) #else
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.
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 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 |
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.
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).