diff --git a/doc/source/reference/cli.rst b/doc/source/reference/cli.rst
index 9c0798f1e572779ae93a3236e1f6b3c2294ba433..82031356524d3c2e78ca2c97461882e349796035 100644
--- a/doc/source/reference/cli.rst
+++ b/doc/source/reference/cli.rst
@@ -1,18 +1,3 @@
-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
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 977e5e7e05e8c78a9d9933e54620940733741afa..668af4bb8335269b7740d32aa6c31e6362badd9a 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -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.