Creating a new application (Unix like operating systems such as Linux and Mac OS)

Purpose and learning outcome

In this tutorial we learn how to create a new project and how to build and execute an application. We also go through the file and folder structure of a basic project and learn to create more complex template projects. At the end of this tutorial the reader should be comfortable with the support structure inside which an application is built and be ready to learn how to write actual applications.

Creating, building, and executing a first application

Project creation using TBTKCreateApplication

One of the main issues when writing code in a language such as C++ is the need to manage both source files and dependencies in terms of other libraries. In addition to the main source code, a full project therefore requires one or several supporting files and folders. TBTK therefore comes with an executable called TBTKCreateApplication that helps setup the relevant support structure, and which in combination with CMake allows the developer to focus on developing the actual application. Before creating a project, it is recommended to have a folder called for example TBTKApplications inside which applications are created. This can be created on the command line using

1 mkdir TBTKApplications

Then, to enter this folder and create a new application, type

1 cd TBTKApplications
2 TBTKCreateApplication ApplicationName

where ApplicationName can be any valid folder name (no spaces). This will create a new folder named ApplicationName that contains all the relevant files for building and running a TBTK application.

Build executable

To enter the project folder and build the application, type

1 cd ApplicationName
2 cmake .
3 make

Here the second line creates the relevant files required to build the application, while the third line builds the actual executable.

It can also be useful to build the application in a separate folder from source code. This can be achieved by instead typing

1 mkdir ApplicationNameBuild
2 cd ApplicationNameBuild
3 cmake ../ApplicationName
4 make

Execute the application

The application can now be executed by typing

1 ./build/Application

Default application folder structure

When creating an application using TBTKCreateApplication, a number of files and folders are created. The purpose of the folders are

Folder name Description
build Contains the final executable application.
figures Intended for generated figures.
include Contains header files (.h).
src Contains source files (.cpp).

At creation the project also contains a number of files. The files and their purpose are listed below. Application developers can largely ignore files in gray text since these are meant to be unedited. However, descriptions are provided to aid developers interested in customizing the build procedure.

File name Description
CMakeLists.txt File used by CMake to setup the build system. The file used by the cmake call.
plot.sh File intended for python plot commands to be listed in (see TBTK/Templates for examples).
src/main.cpp The file in which the code for the actual application is written.

Once cmake is executed, a number of additional files are created

File name Description
CMakeCache.txt See the CMake documentation.
CMakeFiles (folder) See the CMake documentation.
cmake_install.cmake See the CMake documentation.
Makefile The file used by the make call.

Template applications

More complex templates

While the usage of TBTKCreateApplication as presented above is useful for starting projects from scratch, it is also possible to start from more complex projects by typing

1 TBTKCreateApplication ApplicationName TemplateName

where TemplateName can be any of

TemplateName Description
BasicArnoldi Demonstrates how to use the ArnoldiIterator.
BasicChebyshev Demonstrates how to use the ChebyshevExapnder.
BasicDiagonalization Demonstrates how to use the Diagonalizer.
BasicFourierTransform Demonstrates how to use the FourierTransform.
CarbonNanotube Demonstrates how to set up a carbon nanotube.
HexagonalLattice Demonstrates how to set up a hexagonal lattice.
PartialBilayer Demonstrates how to set up a partial bilayer.
SelfConsistentSuperconductivity Demonstrates how to set up a self-consistent calculation for the superconducting order parameter using the Diagonalizer.
WireOnSuperconductor Demonstrates how to set up a magnetic wire on top of a two-dimensional superconducting layer.

Example: BasicDiagonalization

To demonstrate the use of template projects, lets build and execute BasicDiagonalization. Before beginning we note that this template uses the FileWriter and therefore requires that HDF5 is installed and detected by TBTK. Therefore make sure the HDF5 box is checked in the output from cmake below. Starting from the folder TBTKApplication, we type

1 TBTKCreateApplication MyDiagonalizationApplication BasicDiagonalization
2 cd MyDiagonalizationApplication
3 cmake .
4 make
5 ./build/Application

The application should run and output

1 Constructing system
2  Basis size: 800
3 Initializing Diagonalizer
4  Basis size: 800
5 Running Diagonalizer
7 .

Taking a look at the code in src/main.cpp, we see several lines for example reading


These lines writes the results to a file called TBTKResults.h5 (set by FileWriter::setFileName("TBTKResults.h5")) which will contain the results of the calculation. Next, taking a look in the file plot.sh, we see several corresponding lines for example reading

1 TBTKPlotDensity.py TBTKResults.h5

These reads the results from TBTKResults.h5 and plots the result in files stored in the folder figures. Therefore type

1 bash plot.sh

and view the results in the figures folder.