instructions for adding models

doc/adding_models.md

@@ -0,0 +1,43 @@
+The models (Hamiltonians) are added to nrgljubljana_interface by creating "template directories"
+in templates/. The templates are organised as templates/[model_name]/[symmetry_type], where the
+model name is e.g. "SIAM", while the symmetry type is one of the NRG Ljubljana codes for symmetry
+types, e.g. QS (conserved charge and spin) or QSZ (conserved charge and z-component of spin). The
+list of all symmetry types can be found in nrgljubljana/nrginit/initial.m.
+
+Each "template directory" contains a parameter file "param", Hamiltonian description in a .m file,
+matrix representations of operators in files "data.in", "ham*", "op*", scripts for problem
+initialization ("prepare" and "instantiate", which makes calls to "discretize" and "wilson"), and
+postprocessing ("process"). Finally, there are some descriptor files, "info", "gf_struct" and
+"cf_struct". Info file lists operators and spectral functions, parameters, and some optional
+parameters, while structure files describe the structure of the Green's function and dynamic
+susceptibility matrix.
+
+To introduce a new Hamiltonian, one should add appropriate new directories under the "templates/"
+hierarchy and modify the files according to user's requirements. The new set of "data.in", "ham*"
+and "op*" matrix element files is generated by running "nrginit" tool,
+nrgljubljana/nrginit/nrginit. Note that this tool requires Mathematica. 
+
+When making changes to a template is recommended to make small changes and check if everything
+works correctly after each step. Remember to call "cmake install" after each modification and to
+adapt CmakeLists.txt. Alternatively, new models can be added directly to the installed templates/
+directory.
+
+To define new models, the user should be somewhat familiar with the NRG Ljubljana package. There
+is some documentation available online and training sessions are organised periodically. One can
+also get in touch with the authors.
+
+Adding new quantities to be computed to existing model templates is quite simple. One needs to
+modify the "params" file, line "ops", where one adds the required operators. A set of operators is
+defined in nrgljubljana/nrginit/operators.m, and that file can be further extended. In addition,
+one should add the operators to line "ops" in the file "info". If additional dynamical quantities
+need to be computed, they should be added to appropriate "spec*" lines in the file "info". Here
+'s' stands for singlet, 'd' for doublet, 't' for triplet and 'q' for quadriplet operators, with
+respect to spin symmetry. For example, charge susceptibility <<n_d;n_d>> corresponds to "n_d-n_d"
+in line "specs", because the charge operator "n_d" is a spin singlet. Green's function
+<<d;d^\dag>> corresponds to "A_d-A_d" in line "specd", because creation/annihilation operators are
+doublets with respect to spin. Spin susceptibility in the presence of SU(2) symmetry correspond to
+"sigma_d-sigma_d" in line "spect", because the spin operators for a triplet; in the presence of
+U(1) it corresponds to "SZd-SZd" in line "specs", because the operator for the z-component of
+spin, SZd, in this case behaves as a "singlet".
+
+

doc/index.rst

@@ -33,4 +33,5 @@ Learn how to use nrgljubljana_interface in the :ref:`documentation`.
    documentation
    issues
    ChangeLog.md
+   adding_models.md
    about