Purpose and learning outcome

In this tutorial we learn how to create, build and execute an application. We also describe the default folder structure and learn how to create template projects. At the end of this tutorial you should be comfortable with setting up a new project and be ready to learn how to implement an applications.

Creating, building, and executing a first application

Create an application

We begin by creating a folder within which applications will be created. To create this folder and enter it, we type the following on the command line.

mkdir TBTKApplications

cd TBTKApplications

Once inside the folder we type

TBTKCreateApplication ApplicationName

where ApplicationName can be any valid folder name (without spaces). This creates 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

cd ApplicationName
cmake .
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 that is separate from the source code. This can be achieved by instead typing

mkdir ApplicationNameBuild
cd ApplicationNameBuild
cmake ../ApplicationName
make

Execute the application

The application can now be executed by typing

./build/Application

That's it, you have now created, built, and executed your first application.

Default application folder structure

When running TBTKCreateApplication, a number of files and folders are created inside the new application folder. 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.
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

So far we have shown how to create an application from scratch using TBTKCreateApplication. It is also possible to create one of several template projects by instead typing

TBTKCreateApplication ApplicationName TemplateName

where TemplateName can be any of the following

TemplateName	Description
BasicArnoldi	Demonstrates how to use the Solver::ArnoldiIterator.
BasicChebyshev	Demonstrates how to use the Solver::ChebyshevExapnder.
BasicDiagonalization	Demonstrates how to use the Solver::Diagonalizer.
BasicFourierTransform	Demonstrates how to use the FourierTransform.
BasicLinearEquation	Demonstrates how to use the Solver::BasicLinearEquation.
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, let's build and execute BasicDiagonalization. We note that this template uses the Plotter and, therefore, requires that Python with matplotlib and numpy is installed and detected by TBTK. Therefore, make sure that the Python box is checked in the output from the cmake command below before proceeding to line four and five.

Starting from the folder TBTKApplication, we type

TBTKCreateApplication MyDiagonalizationApplication BasicDiagonalization
cd MyDiagonalizationApplication
cmake .
make
./build/Application

The application should run and save six figures in the figures folder.