Reference¶
Command Line Interface (CLI)¶
- Entry point module for the command-line
interface. The kmos executable should be on the program path, import this modules main function and run it.
To call kmos command as you would from the shell, use
kmos.cli.main('...')
Every command can be shortened as long as it is non-ambiguous, e.g.
kmos ex <xml-file>
instead of
kmos export <xml-file>
etc.
List of commands¶
kmos benchmark
- Run 1 mio. kMC steps on model in current directory and report runtime.
kmos build
Build kmc_model.so from *f90 files in the current directory.
- Additional Parameters ::
- -d/–debug
- Turn on assertion statements in F90 code
- -n/–no-compiler-optimization
- Do not send optimizing flags to compiler.
kmos edit <xml-file>
- Open the kmos xml-file in a GUI to edit the model.
kmos export <xml-file> [<export-path>]
Take a kmos xml-file and export all generated source code to the export-path. There try to build the kmc_model.so.
Additional Parameters
-s/--source-only Export source only and don't build binary -b/--backend (local_smart|lat_int) Choose backend. Default is "local_smart". lat_int is EXPERIMENTAL and not made for production, yet. -d/--debug Turn on assertion statements in F90 code. (Only active in compile step) -n/--no-compiler-optimization Do not send optimizing flags to compiler.
kmos help <command>
- Print usage information for the given command.
kmos help all
- Display documentation for all commands.
kmos import <xml-file>
- Take a kmos xml-file and open an ipython shell with the project_tree imported as pt.
kmos rebuild
Export code and rebuild binary module from XML information included in kmc_settings.py in current directory.
- Additional Parameters ::
- -d/–debug
- Turn on assertion statements in F90 code
kmos run
- Open an interactive shell and create a KMC_Model in it
- run == shell
kmos settings-export <xml-file> [<export-path>]
- Take a kmos xml-file and export kmc_settings.py to the export-path.
kmos shell
- Open an interactive shell and create a KMC_Model in it
- run == shell
kmos version
- Print version number and exit.
kmos view
Take a kmc_model.so and kmc_settings.py in the same directory and start to simulate the model visually.
- Additional Parameters ::
- -v/–steps-per-frame <number>
- Number of steps per frame
kmos xml
- Print xml representation of model to stdout
Data Types¶
kmos.types¶
Holds all the data models used in kmos.
-
class
kmos.types.
Project
¶ A Project is where (almost) everything comes together. A Project holds all other elements needed to describe one kMC Project ready to be manipulated, exported, or imported.
The overall structure is the following as is also displayed in the editor GUI.
Project:
- Meta - Parameters - Lattice(s) - Species - Processes
-
add_layer
(*layers, **kwargs)¶ Add a layer to the project. A Layer, or keywords that are passed to the Layer constructor are accepted.
Parameters: - layers (list) – List of layers.
- cell (np.array (3x3)) – Size of unit-cell.
- default_layer (str.) – name of default layer.
-
add_parameter
(*parameters, **kwargs)¶ Add a parameter to the project. A Parameter, or keywords that are passed to the Parameter constructor are accepted.
Parameters: - name (str) – The name of the parameter.
- value (float) – Default value of parameter.
- adjustable (bool) – Create controller in GUI.
- min (float) – Minimum value for controller.
- max (float) – Maximum value for controller.
- scale (str) – Controller scale: ‘log’ or ‘lin’
-
add_process
(*processes, **kwargs)¶ Add a process to the project. A Process, or keywords that are passed to the Process constructor are accepted.
Parameters: - name (str) – Name of process.
- rate_constant (str) – Expression for rate constant.
- condition_list (list.) – List of conditions (class Condition).
- action_list (list.) – List of conditions (class Action).
- enabled (bool.) – Switch this process on or of.
- chemical_expression (str.) – Chemical expression (i.e: A@site1 + B@site2 -> empty@site1 + AB@site2) to generate process from.
- tof_count (dict.) – Stoichiometric factor for observable products {‘NH3’: 1, ‘H2O(gas)’: 2}. Hint: avoid space in keys.
-
add_site
(**kwargs)¶ Add a site to the project. The arguments are
add_site(layer_name, site)
Parameters: - name (str) – Name of layer to add the site to.
- site (Site) – Site instance to add.
-
add_species
(*speciess, **kwargs)¶ Add a species to the project. A Species, or keywords that are passed to the Species constructor are accepted.
Parameters: - name (str) – Name of species.
- color (str) – Color of species in editor GUI (#ffffff hex-type specification).
- representation (str) – ase.atoms.Atoms constructor describing species geometry.
- tags (str) – Tags of species (space separated string).
-
get_parameters
(pattern=None)¶ Return list of parameters in Project.
Parameters: pattern (str) – Pattern to fnmatch name of parameter against.
-
get_processes
(pattern=None)¶ Return list of processes.
Parameters: pattern (str) – Pattern to fnmatch name of process against.
-
get_speciess
(pattern=None)¶ Return list of species in Project.
Parameters: pattern (str) – Pattern to fnmatch name of process against.
-
import_xml_file
(filename)¶ Takes a filename, validates the content against kmc_project.dtd and import all fields into the current project tree
-
parse_and_add_process
(string)¶ Generate and add processes using a shorthand notation like, e.g. :: process_name; species1A@coord1 + species2A@coord2 + ... -> species1B@coord1 + species2A@coord2 + ...; rate_constant_expression
.
Parameters: string (str) – shorthand notation for process
-
parse_process
(string)¶ Generate processes using a shorthand notation like, e.g. :: process_name; species1A@coord1 + species2A@coord2 + ... -> species1B@coord1 + species2A@coord2 + ...; rate_constant_expression
.
Parameters: string (str) – shorthand notation for process
-
validate_model
()¶ Run various consistency and completeness test of the model to make sure we have a minimally complete model.
-
-
class
kmos.types.
Meta
(*args, **kwargs)¶ Class holding the meta-information about the kMC project
-
class
kmos.types.
Parameter
(**kwargs)¶ A parameter that can be used in a rate constant expression and defined via some init file.
Parameters: - name (str) – The name of the parameter.
- adjustable (bool) – Create controller in GUI.
- min (float) – Minimum value for controller.
- max (float) – Maximum value for controller.
- scale (str) – Controller scale: ‘log’ or ‘lin’
-
class
kmos.types.
LayerList
(**kwargs)¶ A list of layers
Parameters: - cell (np.array (3x3)) – Size of unit-cell.
- default_layer (str.) – name of default layer.
-
generate_coord
(terms)¶ Expecting something of the form site_name.offset.layer and return a Coord object
-
generate_coord_set
(size=[1, 1, 1], layer_name='default')¶ Generates a set of coordinates around unit cell of any desired size. By default it includes exactly all sites in the unit cell. By setting size=[2,1,1] one gets an additional set in the positive and negative x-direction.
-
class
kmos.types.
Layer
(**kwargs)¶ Represents one layer in a possibly multi-layer geometry.
Parameters: - name (str) – Name of layer.
- sites (list) – Sites associated with this layer (Default: [])
-
class
kmos.types.
Site
(**kwargs)¶ Represents one lattice site.
Parameters: - name (str) – Name of site.
- pos (np.array or str) – Position within unit cell.
- tags (str) – Tags for this site (space separated).
- default_species (str) – Initial population for this site.
-
class
kmos.types.
Species
(**kwargs)¶ Class that represent a species such as oxygen, empty, ... . Note: empty is treated just like a species.
Parameters: - name (str) – Name of species.
- color (str) – Color of species in editor GUI (#ffffff hex-type specification).
- representation (str) – ase.atoms.Atoms constructor describing species geometry.
- tags (str) – Tags of species (space separated string).
-
class
kmos.types.
Process
(**kwargs)¶ One process in a kMC process list
Parameters: - name (str) – Name of process.
- rate_constant (str) – Expression for rate constant.
- condition_list (list.) – List of conditions (class Condition).
- action_list (list.) – List of conditions (class Action).
- enabled (bool.) – Switch this process on or of.
- chemical_expression (str.) – Chemical expression (i.e: A@site1 + B@site2 -> empty@site1 + AB@site2) to generate process from.
- tof_count (dict.) – Stoichiometric factor for observable products {‘NH3’: 1, ‘H2O(gas)’: 2}. Hint: avoid space in keys.
-
class
kmos.types.
ConditionAction
(**kwargs)¶ Represents either a condition or an action. Since both have the same attributes we use the same class here, and just store them in different lists, depending on its role. For better readability one can also use Condition or Action which are just aliases.
Parameters: - coord (Coord) – Relative Coord (generated by
LayerList.generate_coord()
orLattice.generate_coord_set()
). - species (str) – Name of species.
- coord (Coord) – Relative Coord (generated by
-
class
kmos.types.
Coord
(**kwargs)¶ Class that holds exactly one coordinate as used in the description of a process. The distinction between a Coord and a Site may seem superfluous but it is made to avoid data duplication.
Parameters: - name (str) – Name of coordinate.
- offset (np.array or list) – Offset in term of unit-cells.
- layer (str) – Name of layer.
- tags (str) – List of tags (space separated string).
-
pos
¶ pos is np.array((3, 1)) and is calculated from offset and position. Not to be set manually.
kmos.io¶
Features front-end import/export functions for kMC Projects. Currently import and export is supported to XML and export is supported to Fortran 90 source code.
-
kmos.io.
export_source
(project_tree, export_dir=None, code_generator='local_smart')¶ Export a kmos project into Fortran 90 code that can be readily compiled using f2py. The model contained in project_tree will be stored under the directory export_dir. export_dir will be created if it does not exist. The XML representation of the model will be included in the kmc_settings.py module.
export_source is the central feature of the kmos approach. In order to generate different backend solvers, additional candidates of this methods could be implemented.
-
kmos.io.
export_xml
(project_tree, filename=None)¶ Writes a project to an XML file.
-
class
kmos.io.
ProcListWriter
(data, dir)¶ Write the different parts of Fortran 90 code needed to run a kMC model.
-
write_lattice
()¶ Write the lattice.f90 module, i.e. the geometric information that belongs to a kMC model.
-
write_proclist
(smart=True, code_generator='local_smart')¶ Write the proclist.f90 module, i.e. the rules which make up the kMC process list.
-
write_settings
()¶ Write the kmc_settings.py. This contains all parameters, which can be changed on the fly and without recompilation of the Fortran 90 modules.
-
Editor frontend¶
kmos.gui¶
A GUI frontend to create and edit kMC models.
-
class
kmos.gui.
Editor
¶ The editor GUI frontend.
-
class
kmos.gui.
GTKProject
(parent, menubar)¶ A facade of kmos.types.Project so that pygtk can display in a TreeView.
kmos.forms¶
Runtime frontend¶
kmos.run¶
kmos.view¶
kmos.cli¶
Entry point module for the command-line interface. The kmos executable should be on the program path, import this modules main function and run it.
To call kmos command as you would from the shell, use
kmos.cli.main('...')
Every command can be shortened as long as it is non-ambiguous, e.g.
kmos ex <xml-file>
instead of
kmos export <xml-file>
etc.
-
kmos.cli.
main
(args=None)¶ The CLI main entry point function.
The optional argument args, can be used to directly supply command line argument like
$ kmos <args>
otherwise args will be taken from STDIN.
-
kmos.cli.
match_keys
(arg, usage, parser)¶ Try to match part of a command against the set of commands from usage. Throws an error if not successful.
-
kmos.cli.
sh
(banner)¶ Wrapper around interactive ipython shell that factors out ipython version depencies.
Utils¶
kmos.utils¶
Several utility functions that do not seem to fit somewhere else.
-
class
kmos.utils.
CorrectlyNamed
¶ Syntactic Sugar class for use with kiwi, that makes sure that the name field of the class has a name field, that always complys with the rules for variables.
-
__init__
()¶
-
__module__
= 'kmos.utils'¶
-
on_name__validate
(_, name)¶ Called by kiwi upon chaning a string
-
-
kmos.utils.
T_grid
(T_min, T_max, n)¶
-
kmos.utils.
build
(options)¶ Build binary with f2py binding from complete set of source file in the current directory.
-
kmos.utils.
col_str2tuple
(hex_string)¶ Convenience function that turns a HTML type color into a tuple of three float between 0 and 1
-
kmos.utils.
col_tuple2str
(tup)¶ Convenience function that turns a HTML type color into a tuple of three float between 0 and 1
-
kmos.utils.
download
(project)¶
-
kmos.utils.
evaluate_kind_values
(infile, outfile)¶ Go through a given file and dynamically replace all selected_int/real_kind calls with the dynamically evaluated fortran code using only code that the function itself contains.
-
kmos.utils.
evaluate_param_expression
(param, parameters={})¶
-
kmos.utils.
evaluate_rate_expression
(rate_expr, parameters={})¶ Evaluates an expression for a typical kMC rate constant. This expression can be any python expression returning a number (most likely you will want a float). Standard functions like sin(x), cos(x), pi, pow(x,y ), log(x, [base]) are evaluated using the builtin math module.
beta is an shorthand for 1/(kboltzmann*T) and requires the present of a temperature parameter T.
Short-hands for common conversion factor (bar, c, hbar, h, hbar, e, eV, angstrom, umass) are evaluated as defined in kmos.units.
The short-hand m_CO is substituted by the atomic weight in atomic mass units u.
The short-hand p_<species> is interpreted as the gas-phase pressure of the corresponding species which can be used in other functions.
The short-hand mu_<species> is interpreted as the gas-phase chemical potential in eV which kmos attempts to evaluate using a linear interpolation of the corresponding JANAF gas phase chemical table (if installed).
Additional external parameters can be passed in as dictionary, like the following:
- parameters = {‘p_CO’:{‘value’:1},
- ‘T’:{‘value’:1}}
or as a list of parameters:
parameters = [Parameter(), ... ]
-
kmos.utils.
get_ase_constructor
(atoms)¶ Return the ASE constructor string for atoms.
-
kmos.utils.
jmolcolor_in_hex
(i)¶ Return a given jmol color in hexadecimal representation.
-
kmos.utils.
p_grid
(p_min, p_max, n)¶
-
kmos.utils.
product
(*args, **kwds)¶ Take two lists and return iterator producing all combinations of tuples between elements of the two lists.
-
kmos.utils.
split_sequence
(seq, size)¶ Take a list and a number n and return list divided into n sublists of roughly equal size.
-
kmos.utils.
timeit
(func)¶ Generic timing decorator
To stop time for function call f just
from kmos.utils import timeit @timeit def f(): ...
-
kmos.utils.
write_py
(fileobj, images, **kwargs)¶ Write a ASE atoms construction string for images into fileobj.
kmos kMC project DTD¶
The central storage and exchange format is XML. XML was chosen over JSON, pickle or alike because it still seems as the most flexible and universal format with good methods to define the overall structure of the data.
One way to define an XML format is by using a document type description (DTD) and in fact at every import a kmos file is validated against the DTD below.
<!ELEMENT kmc (meta?,species_list?,parameter_list?, lattice, process_list?,output_list?)>
<!ATTLIST kmc
version CDATA #REQUIRED
>
<!ELEMENT meta EMPTY>
<!ATTLIST meta
author CDATA #IMPLIED
debug CDATA #IMPLIED
email CDATA #IMPLIED
model_dimension CDATA #IMPLIED
model_name CDATA #IMPLIED
>
<!ELEMENT species_list (species)*>
<!ATTLIST species_list
default_species CDATA #IMPLIED
>
<!ELEMENT species EMPTY>
<!ATTLIST species
name CDATA #REQUIRED
color CDATA #IMPLIED
representation CDATA #IMPLIED
tags CDATA #IMPLIED
>
<!ELEMENT parameter_list (parameter)*>
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #IMPLIED
adjustable CDATA #IMPLIED
min CDATA #IMPLIED
max CDATA #IMPLIED
scale CDATA #IMPLIED
>
<!ELEMENT lattice (layer)*>
<!ATTLIST lattice
cell_size CDATA #REQUIRED
default_layer CDATA #REQUIRED
substrate_layer CDATA #IMPLIED
representation CDATA #IMPLIED
>
<!ELEMENT layer (site)*>
<!ATTLIST layer
name CDATA #REQUIRED
grid CDATA #IMPLIED
grid_offset CDATA #IMPLIED
color CDATA #IMPLIED
>
<!ELEMENT site EMPTY>
<!ATTLIST site
pos CDATA #REQUIRED
type CDATA #REQUIRED
tags CDATA #IMPLIED
default_species CDATA #IMPLIED
>
<!ELEMENT process_list (process)*>
<!ELEMENT process (condition|action)*>
<!ATTLIST process
name CDATA #REQUIRED
rate_constant CDATA #REQUIRED
enabled CDATA #IMPLIED
tof_count CDATA #IMPLIED
>
<!ELEMENT condition EMPTY>
<!ATTLIST condition
coord_name CDATA #REQUIRED
coord_layer CDATA #REQUIRED
coord_offset CDATA #REQUIRED
species CDATA #REQUIRED
implicit CDATA #IMPLIED
>
<!ELEMENT action EMPTY>
<!ATTLIST action
coord_name CDATA #REQUIRED
coord_layer CDATA #REQUIRED
coord_offset CDATA #REQUIRED
species CDATA #REQUIRED
>
<!ELEMENT output_list (output)*>
<!ELEMENT output EMPTY>
<!ATTLIST output
item CDATA #REQUIRED
>
Backend¶
In general the backend includes all functions that are implemented in Fortran90, which therefore should not have to be changed by hand often. The backend is divided into three modules, which import each other in the following way
base <- lattice <- proclist
The key for this division is reusability of the code. The base module implement all aspects of the kMC code, which do not depend on the described model. Thus it “never” has to change. The latttice module basically repeats all methods of the base model in terms of lattice coordinates. Thus the lattice module only changes, when the geometry of the model changes, e.g. when you add or delete sites. The proclist module implements the process list, that is the species or states each site can have and the elementary steps. Typically that changes most often while developing a model.
The rate constants and physical parameters of the system are not implemented in the backend at all, since in the physical sense they are too high-level to justify encoding and compilation at the Fortran level and so they are typical read and parsed from a python script.
The kmos.run.KMC_Model class implements a convenient interface for most of these functions, however all public methods (in Fortran called subroutines) and variables can also be accessed directly like so
from kmos.run import KMC_Model
model = KMC_Model(print_rates=False, banner=False)
model.base.<TAB>
model.lattice.<TAB>
model.proclist.<TAB>
which works best in conjunction with ipython.
kmos/base¶
The base kMC module, which implements the kMC method on a lattice. Virtually any lattice kMC model can be build on top of this. The methods offered are:
- de/allocation of memory
- book-keeping of the lattice configuration and all available processes
- updating and tracking kMC time, kMC step and wall time
- saving and reloading the current state
- determine the process and site to be executed
base/accum_rates¶
Stores the accumulated rate constant multiplied with the number of sites available for that process to be used by determine_procsite. Let be the rate constants the number of available sites, and the accumulated rates, then is calculated according to .
base/add_proc¶
The main idea of this subroutine is described in del_proc. Adding one process to one capability is programmatically simpler since we can just add it to the end of the respective array in avail_sites.
proc
positive integer number that represents the process to be added.site
positive integer number that represents the site to be manipulated
base/allocate_system¶
Allocates all book-keeping structures and stores local copies of system name and size(s):
systen_name
identifier of this simulation, used as name of punch filevolume
the total number of sitesnr_of_proc
the total number of processes
base/assertion_fail¶
Function that shall be used by all parts of the program to print a proper message in case some assertion fails.
a
condition that is supposed to hold truer
message that is printed to the poor user in case it fails
base/avail_sites¶
Main book-keeping array that stores for each process the sites that are available and for each site the address in this very array. The meaning of the fields are:
avail_sites(proc, field, switch)where:
- proc – refers to a process in the process list
- the field within the process, but the meaning differs as explained under ‘switch’
- switch – can be either 1 or 2 and switches between (1) the actual numbers of the sites, which are available and filled in from the left but in whatever order they come or (2) the location where the site is stored in (1).
base/can_do¶
Returns true if ‘site’ can do ‘proc’ right now
proc
integer representing the requested process.site
integer representing the requested site.can
writeable boolean, where the result will be stored.
base/deallocate_system¶
Deallocate all allocatable arrays: avail_sites, lattice, rates, accum_rates, integ_rates, procstat.
none
base/del_proc¶
del_proc delete one process from the main book-keeping array avail_sites. These book-keeping operations happen in O(1) time with the help of some more book-keeping overhead. avail_sites stores for each process all sites that are available. The array for each process is filled from the left, but sites generally not ordered. With this determine_procsite can effectively pick the next site and process. On the other hand a second array (avail_sites(:,:,2) ) holds for each process and each site, the location where it is stored in avail_site(:,:,1). If a site needs to be removed this subroutine first looks up the location via avail_sites(:,:,1) and replaces it with the site that is stored as the last element for this process.
proc
positive integer that states the processsite
positive integer that encodes the site to be manipulated
base/determine_procsite¶
Expects two random numbers between 0 and 1 and determines the corresponding process and site from accum_rates and avail_sites. Technically one random number would be sufficient but to circumvent issues with wrong interval_search_real implementation or rounding errors I decided to take two random numbers:
ran_proc
Random real number from that selects the next processran_site
Random real number from that selects the next siteproc
Return integersite
Return integer
base/get_accum_rate¶
Return accumulated rate at a given process.
proc_nr
integer representing the requested process.return_accum_rate
writeable real, where the requested accumulated rate will be stored.
base/get_avail_site¶
Return field from the avail_sites database
proc_nr
integer representing the requested process.field
integer for the site at questionswitch
1 or 2 for site or storage location
base/get_integ_rate¶
Return integrated rate at a given process.
proc_nr
integer representing the requested process.return_integ_rate
writeable real, where the requested integrated rate will be stored.
base/get_kmc_step¶
Return the current kmc_step
kmc_step
Writeable integer
base/get_kmc_time¶
Returns current kmc_time as rdouble real as defined in kind_values.f90.
return_kmc_time
writeable real, where the kmc_time will be stored.
base/get_kmc_time_step¶
Returns current kmc_time_step (the time increment).
return_kmc_step
writeable real, where the kmc_time_step will be stored.
base/get_kmc_volume¶
Return the total number of sites.
volume
Writeable integer.
base/get_nrofsites¶
Return how many sites are available for a certain process. Usually used for debugging
proc
integer representing the requested processreturn_nrofsites
writeable integer, where nr of sites gets stored
base/get_procstat¶
Return process counter for process proc as integer.
proc
integer representing the requested process.return_procstat
writeable integer, where the process counter will be stored.
base/get_rate¶
Return rate of given process.
proc_nr
integer representing the requested process.return_rate
writeable real, where the requested rate will be stored.
base/get_species¶
Return the species that occupies site.
site
integer representing the site
base/get_system_name¶
Return the systems name, that was specified with base/allocate_system
system_name
Writeable string of type character(len=200).
base/get_walltime¶
Return the current walltime.
return_walltime
writeable real where the walltime will be stored.
base/increment_procstat¶
Increment the process counter for process proc by one.
proc
integer representing the process to be increment.
base/integ_rates¶
Stores the time-integrated rates (non-normalized to surface area) Used to determine reaction rates, i.e. average number of reactions per unit surface and time. Let the integrated rates, be the rate constants, the number of available sites during kMC-time interval i, the corresponding timesteps then at the time is calculated according to .
base/interval_search_real¶
This is basically a standard binary search algorithm that expects an array of ascending real numbers and a scalar real and return the key of the corresponding field, with the following modification :
- the value of the returned field is equal of larger of the given value. This is important because the given value is between 0 and the largest value in the array and otherwise the last field is never selected.
- if two or more values in the array are identical, the function return the index of the leftmost of those field. This is important because having field with identical values means that all field except the leftmost one do not contain any sites. Refer to update_accum_rate to understand why.
- the value of the returned field may no be zero. Therefore the index the to be equal or larger than the first non-zero field.
However: as everyone knows the binary search is trickier than it appears at first site especially real numbers. So intensive testing is suggested here!
arr
real array of type rsingle (kind_values.f90) in monotonically (not strictly) increasing ordervalue
real positive number from [0, max_arr_value]
base/kmc_step¶
Number of kMC steps executed.
base/kmc_time¶
Simulated kMC time in this run in seconds.
base/kmc_time_step¶
The time increment of the current kMC step.
base/lattice¶
Stores the actual physical lattice in a 1d array, where the value on each slot represents the species on that site.
Species constants can be conveniently defined in lattice_... and later used directly in the process list.
base/nr_of_proc¶
Total number of available processes.
base/nr_of_sites¶
Stores the number of sites available for each process.
base/procstat¶
Stores the total number of times each process has been executed during one simulation.
base/rates¶
Stores the rate constants for each process in s^-1.
base/reload_system¶
Restore state of simulation from *.reload file as saved by save_system(). This function also allocates the system’s memory so calling allocate_system again, will cause a runtime failure.
system_name
string of 200 characters which will make the reload_system look for a file called ./<system_name>.reloadreloaded
logical return variable, that is .true. reload of system could be completed successfully, and .false. otherwise.
base/replace_species¶
Replaces the species at a given site with new_species, given that old_species is correct, i.e. identical to the site that is already there.
site
integer representing the siteold_species
integer representing the species to be removednew_species
integer representing the species to be placed
base/reset_site¶
This function is a higher-level function to reset a site as if it never existed. To achieve this the species is set to null_species and all available processes are stripped from the site via del_proc.
site
integer representing the requested site.species
integer representing the species that ought to be at the site, for consistency checks
base/save_system¶
save_system stores the entire system information in a simple ASCII filed names <system_name>.reload. All fields except avail_sites are stored in the simple scheme:
variable valueIn the case of array variables, multiple values are seperated by one or more spaces, and the record is terminated with a newline. The variable avail_sites is treated slightly differently, since printed on a single line it is almost impossible to interpret from the ASCII files. Instead each process starts a new line, and the first number on the line stands for the process number and the remaining fields, hold the values.
none
base/set_kmc_time¶
Sets current kmc_time as rdouble real as defined in kind_values.f90.
new
readable real, that the kmc time will be set to
base/set_rate_const¶
Allows to set the rate constant of the process with the number proc_nr.
proc_n
The process number as defined in the corresponding proclist_ module.rate
the rate in
base/set_system_name¶
Set the systems name. Useful in conjunction with base.save_system to save *.reload files under a different name than the default one.
system_name
Readable string of type character(len=200).
base/start_time¶
CPU time spent in simulation at least reload.
base/system_name¶
Unique indentifier of this simulation to be used for restart files. This name should not contain any characters that you don’t want to have in a filename either, i.e. only [A-Za-z0-9_-].
base/update_accum_rate¶
Updates the vector of accum_rates.
none
base/update_clocks¶
Updates walltime, kmc_step and kmc_time.
ran_time
Random real number
base/update_integ_rate¶
Updates the vector of integ_rates.
none
base/volume¶
Total number of sites.
base/walltime¶
Total CPU time spent on this simulation.
kmos/lattice¶
Implements the mappings between the real space lattice and the 1-D lattice, which kmos/base operates on. Furthermore replicates all geometry specific functions of kmos/base in terms of lattice coordinates. Using this module each site can be addressed with 4-tuple(i, j, k, n)
wherei, j, k
define the unit cell andn
the site within the unit cell.
lattice/allocate_system¶
Allocates system, fills mapping cache, and checks whether mapping is consistent
none
lattice/calculate_lattice2nr¶
Maps all lattice coordinates onto a continuous set of integer
site
integer array of size (4) a lattice coordinate
lattice/calculate_nr2lattice¶
Maps a continuous set of of integers to a 4-tuple representing a lattice coordinate
nr
integer representing the site index
lattice/deallocate_system¶
Deallocates system including mapping cache.
none
kmos/proclist¶
Implements the kMC process list.
proclist/do_kmc_step¶
Performs exactly one kMC step. * first update clock * then configuration sampling step * last execute process
none
proclist/do_kmc_steps¶
Performs
n
kMC step. If one has to run many steps without evaluation do_kmc_steps might perform a little better. * first update clock * then configuration sampling step * last execute process
n
: Number of steps to run
proclist/get_kmc_step¶
Determines next step without executing it.
none
proclist/get_occupation¶
Evaluate current lattice configuration and returns the normalized occupation as matrix. Different species run along the first axis and different sites run along the second.
none
proclist/init¶
Allocates the system and initializes all sites in the given layer.
input_system_size
number of unit cell per axis.system_name
identifier for reload file.layer
initial layer.no_banner
[optional] if True no copyright is issued.
proclist/initialize_state¶
Initialize all sites and book-keeping array for the given layer.
layer
integer representing layer
proclist/run_proc_nr¶
Runs process
proc
on sitenr_site
.
proc
integer representing the process numbernr_site
integer representing the site