Skip to content
Snippets Groups Projects
Commit 2b836a83 authored by Martin Deimel's avatar Martin Deimel
Browse files

MAINT Update reference content

parent 1c54a205
No related branches found
No related tags found
1 merge request!288Rework and update documentation
Hide whitespace changes
Inline Side-by-side
doc/source/reference/cli.rst
+ 0
− 15
View file @ 2b836a83
Entry point module for the command-line
interface. The kmos3 executable should be
on the program path, import this modules
main function and run it.
To call kmos3 commands as you would from the shell,
use ::
kmos3.cli.main('...')
You may also use the syntax kmos3.export("...") for any cli command.
List of commands
^^^^^^^^^^^^^^^^
.. argparse::
:filename: ../kmos3/cli.py
:func: _parser
......
doc/source/reference/index.rst
+ 154
− 178
View file @ 2b836a83
......@@ -2,111 +2,10 @@
Reference
*********
Model running commands
======================
Typical usage: model.[command]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Source code in: https://github.com/kmos3/kmos3/blob/master/kmos3/run/__init__.py
.. autoclass:: kmos3.run.KMC_Model
:members: _adjust_database,
_get_configuration,
_put,
_set_configuration,
create_configuration_plot,
deallocate,
do_steps,
do_steps_time,
do_acc_steps,
double,
dump_config,
export_movie,
export_picture,
get_atoms,
get_avail,
get_backend,
get_global_configuration,
get_local_configurations,
get_next_kmc_step,
get_occupation_header,
get_param_header,
get_species_coordinates,
get_std_sampled_data,
get_tof_header,
halve,
load_config,
get_std_sampled_data,
nr2site,
peek,
play_ascii_movie,
post_mortem,
plot_configuration,
print_accum_rate_summation,
print_adjustable_parameters,
print_coverages,
print_kmc_state,
procstat_normalized,
procstat_pprint,
put,
reset,
run,
show,
show_ascii_picture,
start,
view,
xml
.. base,
.. cell_size,
.. lattice,
.. null_species,
.. parameters,
.. print_rates,
.. procstat,
.. rate_constants,
.. settings,
.. site2nr,
.. steps_per_frame,
.. autoclass:: kmos3.run.Model_Rate_Constants
:members: __call__,
by_name,
inverse
.. autoclass:: kmos3.run.Model_Parameters
:members: __call__
Connected Variables
===================
The connected_variables dictionary allows a person to pass string-writable objects
created during the model building into the runtime environment. This can be useful if
a person needs access to some data structures (like lists of surrounding sites) during runtime.
Dictionaries, strings, and lists can be passed. For more complex variables,
one could pass the name of a pickle file.
This feature is used for the surroundingSitesDict.
The basic syntax in a build_file would be as follows::
kmc_model = kmos3.create_kmc_model(model_name)
kmc_model.connected_variables['frog_list'] = [1,2,3,4]
Then, during runtime, one could do the following::
print(model.connected_variables['frog_list'])
Additional Information for developers. Currently (Dec 2022), the way kmos3 processes things from the build file to the Runtime environment is as follows:
A person's build file makes a Project class object (typically "kmc_model"), for example in https://github.com/kmos3/kmos3/blob/master/examples/MyFirstDiffusion__build.py
That build file makes an xml file (or ini file), which occurs in types.py _get_etree_xml or _get_etree_ini where a string is made that then gets written to file.
That xml/ini is then read back in and validated , which occurs against a DTD. A new Project class object is made from what is read back in.
It is important to recognize that the new Project class object has many attributes that are the same as the one in the build file, but it is not the same object. It has fewer of the original attributes due to hardcoded mapping during xml writing and xml reading.
When the source code compilation occurs, kmc_settings. is made. What is in kmc_settings roughly mirrors the original Project class object, but it is actually from the new Project class object that has been created from the xml.
Command Line Interface (CLI)
============================
.. include:: cli.rst
Data Types
==========
......@@ -115,140 +14,221 @@ kmos3.types
^^^^^^^^^^^
.. automodule:: kmos3.types
.. autoclass:: kmos3.types.Project
:members: add_layer, add_parameter, add_process, add_species, add_site,
get_parameters, get_processes, get_speciess,
import_xml_file, parse_and_add_process, parse_process,
print_statistics, save, set_meta, validate_model
:members:
:undoc-members:
:private-members:
.. get_layers, lattice,
.. autoclass:: kmos3.types.Project
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.Meta
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.Parameter
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.LayerList
:members: generate_coord_set, generate_coord
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.Layer
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.Site
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.Species
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.Process
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.ConditionAction
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.types.Coord
:members:
:undoc-members:
:private-members:
kmos3.io
^^^^^^^^
.. automodule:: kmos3.io
:members: export_source, import_xml, export_xml
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.io.ProcListWriter
:members: write_proclist, write_settings
:members:
:undoc-members:
:private-members:
.. write_lattice
.. Editor frontend
.. ===============
.. kmos3.gui
.. ^^^^^^^^^
.. .. automodule:: kmos3.gui
.. .. autoclass:: kmos3.gui.Editor
.. .. autoclass:: kmos3.gui.GTKProject
.. kmos3.forms
.. ^^^^^^^^^^^
.. .. automodule:: kmos3.forms
.. :members: MetaForm, SpeciesListForm, SpeciesForm, ParameterForm,
.. LatticeForm, LayerEditor, SiteForm, ProcessForm,
.. parse_chemical_expression, BatchProcessForm
Runtime frontend
Runtime Frontend
================
kmos3.run
^^^^^^^^^
.. automodule:: kmos3.run
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.run.Model_Rate_Constants
:members:
:undoc-members:
:private-members:
:special-members: __call__
.. autoclass:: kmos3.run.Model_Parameters
:members:
:undoc-members:
:private-members:
:special-members: __call__
.. autoclass:: kmos3.run.ModelRunner
:members: run
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.run.ModelParameter
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.run.PressureParameter
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.run.TemperatureParameter
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.run.LinearParameter
:members:
:undoc-members:
:private-members:
.. autoclass:: kmos3.run.LogParameter
:members:
:undoc-members:
:private-members:
kmos3.view
^^^^^^^^^^
.. automodule:: kmos3.view
:members: KMC_Viewer
:members:
:undoc-members:
:private-members:
kmos3.cli
^^^^^^^^^
.. automodule:: kmos3.cli
:members: main
:members:
:undoc-members:
:private-members:
kmos3.utils
^^^^^^^^^^^
.. automodule:: kmos3.utils
:members: T_grid, build, evaluate_kind_values, get_ase_constructor, p_grid,
product, split_sequence, write_py
:members:
:undoc-members:
:private-members:
kmos3 kMC project DTD
=====================
Connected Variables
===================
A standardized kmc model format has been made in XML.
XML was chosen over JSON, pickle or alike because near 2010 it was the most flexible
and universal format with good methods to define the overall
structure of the data.
The connected_variables dictionary allows to pass string-writable objects created during the model
building into the runtime environment. This can be useful if a person needs access to some data
structures (like lists of surrounding sites) during runtime. Dictionaries, strings, and lists can
be passed. For more complex variables, one could pass the name of a pickle file. This feature is
used for the ``surroundingSitesDict``.
New infrastrcture for JSON formats now exists, and it is on the to-do list to
switch to using JSON to make a standard kmc model format.
The basic syntax in a ``build_file`` would be as follows::
One way to define an XML format is by using a document type description
(DTD) and in fact at every import a kmos3 file is validated against
the DTD below.
kmc_model = kmos3.create_kmc_model(model_name)
kmc_model.connected_variables['frog_list'] = [1,2,3,4]
.. literalinclude:: kmc_project_v0.5.dtd
Then, during runtime, one could do the following::
print(model.connected_variables['frog_list'])
.. Currently, the way kmos3 processes things from the build file to the runtime environment is as
.. follows:
.. A person's build file makes a Project class object (typically "kmc_model"), for example in
.. https://gitlab.mpcdf.mpg.de/fhi-theory/kmos3/-/blob/main/examples/MyFirstDiffusion__build.py
.. That build file makes an xml file (or ini file), which occurs in types.py
.. ``_get_etree_xml`` or ``_get_etree_ini`` where a string is made that then gets written to
.. file.
.. That xml/ini is then read back in and validated , which occurs against a DTD. A new Project
.. class object is made from what is read back in.
.. It is important to recognize that the new Project class object has many attributes that are
.. the same as the one in the build file, but it is not the same object. It has fewer of the
.. original attributes due to hardcoded mapping during xml writing and xml reading.
.. When the source code compilation occurs, kmc_settings. is made. What is in kmc_settings
.. roughly mirrors the original Project class object, but it is actually from the new Project
.. class object that has been created from the xml.
kmos3 KMC Project DTD
=====================
The central storage and exchange format is XML. XML was chosen over JSON, pickle, or alike because
it seems to be one of 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 kmos3 file is validated against the DTD below.
.. literalinclude:: kmc_project_v0.5.dtd
Backends
========
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 ::
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 `kmos3.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 ::
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 `kmos3.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 kmos3.run import KMC_Model
model = KMC_Model(print_rates=False, banner=False)
......@@ -260,6 +240,7 @@ which works best in conjunction with `ipython <ipython.org>`_.
local_smart
^^^^^^^^^^^
.. include:: robodoc/local_smart_base.rst
.. include:: robodoc/local_smart_lattice.rst
.. include:: robodoc/local_smart_proclist.rst
......@@ -283,9 +264,4 @@ otf
.. include:: robodoc/otf_proclist.rst
.. include:: robodoc/otf_kind_values.rst
Command Line Interface (CLI)
============================
.. include:: cli.rst
.. TODO:: Fix some functions' docstrings.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment