Need a break? Support the development by playing Polarity Puzzles
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, 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 .

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

Execute the application

The application can now be executed by typing


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 .

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