TBTK
Overview

Model, Solvers, and PropertyExtractors

It is useful to think of a typical scientific numerical study as involving three relatively separate questions:

  • What is the model?
  • What method to use?
  • What properties to calculate?

When writing code, the answer to these three questions essentially determines the input, algorithm, and output, respectively. To successfully carry out studies of complex problems, it is important that it is easy to set up the model and to extract the properties, and that the underlying algorithm that performs the work is efficient. However, the simultaneous requirement on the algorithm to be efficient and that the calculation is easy to set up easily run contrary to each other. Efficiency often require low level optimization in the algorithm, which e.g. can put strict requirement on how the input and output is represented in memory. If this means the user is required to setup the input and extract the output on a format that requires deep knowledge about the internal workings of the algorithm, two important problems arise. First, if details about the algorithm is required to be kept in mind at all levels of the code it hinders the user from thinking about the problem on a higher level where numeric nuisance has been abstracted away. Second, if the specific requirements of an algorithm determines the structure of the whole program, the whole code has to be rewritten if the choice is made to try another algorithm.

To get around these problems TBTK is designed to encourage a workflow where the three stages of specifying input, choosing algorithm, and extracting properties are largely independent from each other. To achieve this TBTK has a class called a Model that allows for general models to be setup. Further, algorithms are implemented in a set of different Solvers, which takes a Model and internally converts it to the format most suitable for the algorithm. Finally, the Solver is wrapped in a PropertyExtractor, where the different PropertyExtractors have a uniform interface. By using the PropertyExtractors to extract properties from the Model, rather than by calling the Solvers directly, most code do not need to be changed if the Solver is changed.

Auxiliary tasks

While the three questions above captures the essence of a typical scientific problem, auxiliary tasks such as reading/writing data from/to file, plotting, etc. are required to solve a problem. TBTK therefore also have a large set of tools for simplifying such tasks, allowing the developer to put more mental effort into the main scientific questions. Further, a fundamental key feature of TBTK is that it also comes with a powerful method for handling units. While physical quantities often are expressed in terms of some specific combinations of units such as K, eV, C, etc. it is often useful to work in some for the problem at hands natural set of units. In high-energy physics this may mean \( \hbar = c = 1\), while in condensed matter physics it can be useful to express energies in terms of Rydbergs or some arbitrary unit set by a hopping parameter. For this TBTK provides a UnitHandler that enables the developer to specify the natural units for the given problem. All function calls to TBTK functions should be understood to be in terms of the specified natural units.

Implementing applications

For developers interested in implementing calculations that are meant to answer specific physical questions, which is also referred to as implementing applications, TBTK comes ready with a set of native Solvers. This manual is mainly intended to describe this use case and therefore covers the most important classes needed to achieve this. In particular, this manual outlines how to properly setup a Model, select a Solver, and to extract properties using PropertyExtractors.

Implementing new Solvers

TBTK is also intended to enable the development of new Solvers and provides many classes ment to simplify this task. This manual does not cover all these classes and the interested developer is instead referred to the API for a more detailed description. However, developers are still encouraged to study this manual to understand the design philosophy behind TBTK, and to also use the already existing Solvers as inspiration when writing new Solvers. Doing so can significantly reduce the amount of overhead required to create a new Solver and makes it easier for other developers to use the new Solver in their own project. The development of new Solvers is greatly encouraged and if you are interested in doing so but do not know where to start, please contact Kristofer Björnson at krist.nosp@m.ofer.nosp@m..bjor.nosp@m.nson.nosp@m.@phys.nosp@m.ics..nosp@m.uu.se. New Solvers can either be released as stand alone packages or be pulled into the TBTK library. In the later case the Solver will have to adhere to the main development philosophy of TBTK, but we are happy with providing help with polishing the Solver to the point that it does.